ng-eventually/docs/briefs/2026-07-20-caps-emulation-alignment.md

# Brief — aligner l'émulation des caps sur le vrai modèle NextGraph

**Brief (incubation) — 2026-07-20.** Voir la référence `docs/readcap-and-nuri-model.md`.

## Problème

`caps.ts` émule les droits de lecture comme une **ACL** (`Map<Nuri, Set<PrincipalId>>`,
`grantRead(doc, grantee)`) — **l'inversion** du vrai modèle NextGraph (possession
de clé). Conséquences : pas de notion de **référence cap-less**, grant/révocation
**instantanés et totaux** (au lieu de scellage durable + re-key), et une API
(`declareConnections`) que les consommateurs doivent **re-déclarer à chaque
session**. Cet écart empêche de bâtir correctement des modèles qui reposent sur la
vraie sémantique — notamment la **présence anonyme** (nommer/compter sans lire).

## Objectif : shape-fidelity, PAS sécurité

Le polyfill **n'égale PAS** la sécurité de NextGraph fini, et n'essaie pas. Le
wallet partagé + l'absence de crypto rendent l'émulation **volontairement
non-sécurisée** (tout est en clair, tout marqueur est forgeable) — véhicule de
dev/staging, pas un but. **Seul objectif** : exposer la **BONNE FORME** des
primitives futures pour que les consommateurs (Festipod) soient codés contre le
**modèle mental correct** et **n'aient pas à être réécrits** quand NextGraph sera fini.

Corollaire : **« pas de crypto » n'est pas un problème** ; ce qui compte est d'être
**dans la même logique, avec RIGUEUR**. Une critique « un attaquant lit le clair /
forge un marqueur » est **exacte mais hors-scope**. Ce qui est **inacceptable** =
exposer la **mauvaise forme** (ex. une ACL là où le réel est possession de clé) →
le consommateur code contre un modèle qui n'existera pas. **L'inversion ACL des
ReadCaps EST ce manque de rigueur** — le défaut central à corriger.

## Mécanisme d'enforcement : simulation crypto LÉGÈRE (anti-ACL, anti-raccourci)

Pour que la forme soit **réellement** possession-de-clé (et pas une ACL déguisée),
la donnée d'un doc est **stockée chiffrée** (chiffrement symétrique par-doc, même
léger) et le **ReadCap = la clé**. Invariant (cf. `docs/vision.md`) :

> un **`did` nu (sans ReadCap)** ne permet **PAS** de lire ; un **NURI avec
> ReadCap** est **suffisant et requis**.

Ça **empêche les raccourcis** que l'adversaire a relevés (#4/#6 : lire le clair,
`sparqlQuery`/`inbox.read` qui bypass le filtre) et **interdit** de retomber sur
une ACL — c'est le cœur de « même logique, avec rigueur ».

**Cible — PAS l'état actuel** : toutes les surfaces de lecture (`read-model`,
`read-filter`, `sparqlQuery`, `inbox.read`) devront passer par le
déchiffrement-avec-clé. **Aujourd'hui c'est FAUX** : `inbox.read` (`inbox.ts:198`)
et `sparqlQuery` brut (`docs.ts:82`) **bypass** le filtre, et le seul garde
(`caps.canRead`, `caps.ts:95`) est une **ACL set-membership** — l'inversion même
que la vision interdit. **Fermer ces voies = le cœur de P1.**

1. **Deux formes de référence distinctes** : cap-less (nomme/localise sans lire —
   aligné sur le NURI sans `:k:`) vs cap-porteur (id + clé/token). Aujourd'hui
   absent.
2. **Grant = livrer un cap-token à un destinataire** (émuler le scellage :
   le destinataire *reçoit* le token dans son inbox ; c'est la **possession** du
   token qui autorise la lecture — pas une ligne d'ACL vérifiée par principal).
3. **Enforcement par possession** : les lecteurs (`read-filter`, `use-shape`) ne
   voient que ce dont ils **détiennent le token**, pas « ce dont ils sont dans le
   set de readers ».
4. **Résoudre un cap-less** = nommer / prouver l'existence / compter, **sans**
   exposer le contenu (support de la présence anonyme).
5. **Révocation = re-key** émulé : invalider l'ancien token, re-livrer un nouveau
   aux autorisés restants ; **non-rétroactif**.

## Questions ouvertes

- **TRANCHÉ (directive PO, 2026-07-21)** : on **simule la crypto** (donnée chiffrée
  par-doc, cap = clé). La « sémantique seule » (registre de tokens) est **écartée** —
  elle redevient une ACL et laisse lire le clair. Reste à trancher le **niveau** de
  simulation (chiffrement réel léger vs projection read-model masquée), **avant P1**.
- Représentation NURI cap-less vs cap-porteur dans l'émulation (calquer `:k:`).
- Faut-il permettre le **fetch keyless** (résoudre un cap-less en existence/compte
  sans le contenu) — dépend de ce que le vrai broker autorise (INFÉRÉ, non tracé).
- Migration d'API : `declareConnections`/`grantRead` → `seal(cap, recipient)` +
  `inbox → caps reçus`. Casse les consommateurs (`declareConnections` app disparaît).

## P0 — Spike « keyless-resolve » (le verrou, AVANT tout P1)

**Question porteuse** : un détenteur d'une **référence cap-less** (`did:ng:o:{id}:v:{overlay}`, sans `:k:`) peut-il, **sans jamais lire le contenu** :
- **Q1 — Existence / fetch** : prouver/récupérer la présence des blocs (chiffrés) auprès du broker ? Ou le broker exige-t-il un ReadCap/membership pour servir les blocs ?
- **Q2 — Suppression** : distinguer « existe » de « supprimé » ? *(Le point FRAGILE : NextGraph est append-only CRDT — une désinscription = un **commit tombstone** qu'il faudrait **lire** pour connaître → potentiellement **la clé est requise**. Or le **décrément au leave** en dépend.)*
- **Q3 — Confidentialité** : la clé (`:k:`) reste-t-elle **requise** pour déchiffrer (le keyless ne donne jamais le contenu) ?

**Pourquoi c'est le verrou** : tout le **compteur anonyme** (compter/valider des réfs cap-less sans lire) ET le **décrément au leave** en dépendent. **Si NON** → « compteur anonyme par réf cap-less » est **inconstruisible en cible** → Festipod ne doit **pas** coder cette forme (réécriture garantie). **Si OUI** → P1 expose `resolveCapLess(nuri) → {exists|deleted}` (jamais de contenu), et l'émulation la simule fidèlement.

**Méthode** (bon marché, décisif) :
1. **Tracer** dans `nextgraph-rs` le chemin d'**autorisation de fetch** du broker/verifier : qui sert les blocs (`BlocksGet`/`TopicSync`/`OverlaySync`) ? un cap/membership est-il vérifié, ou `id+overlay` suffit ? l'overlay *outer* est-il public ? une suppression est-elle observable sans clé ?
2. *(Optionnel)* **test e2e décisif** (façon `e2e/reactivity-doc-subscribe.ts`) : B détient la réf cap-less, tente fetch/existence **sans** la clé, vérifie qu'il **n'accède pas** au contenu. Preuve empirique > source.
3. *(Ou)* confirmer avec le dev NextGraph — le plus rapide.

**Livrable** : YES/NO/PARTIAL par Q1/Q2/Q3 + le primitif exact (file:line) + la forme d'API à exposer (si OUI), ou le constat que le compteur change (si NON).
**Décision gatée** : OUI → P1 ; NON → le brief inscriptions revoit le compteur (pas anonyme, ou autre primitif).

## Esquisse de phases

- **P1** — distinction cap-less / cap-porteur dans les NURI + le read-model
  (résoudre un cap-less = nommer/compter, pas lire).
- **P2** — remplacer l'ACL par un modèle de **possession de token** (grant = livrer
  à un destinataire ; enforcement = possession).
- **P3** — révocation par re-key (invalidation + re-livraison, non-rétroactive).
- **P4** — adapter l'API consommateur + `migration-guide.md`.

## Revue adverse (2026-07-20) — à intégrer

Un adversaire a réfuté le brief (6 constats). **À lire au filtre de l'Objectif ci-dessus** (forme, pas sécurité). Les critiques purement **sécurité** — contenu en clair lisible (#4), marqueurs forgeables — sont **ACCEPTÉES / hors-scope** : le polyfill ne cherche pas à les empêcher. Restent les vrais défauts de **FORME / rigueur** (à corriger), et une question de **modèle futur** (#5) :

1. **WriteCap oublié, et « possession » y est FAUX.** L'écriture est **membership/permissions** (`AddMember`) — une **liste d'autorisation**, pas de la possession de clé (réf §1) ; `ng-proxy.ts:28-48` garde chaque `sparql_update`. → garder une **piste WriteCap = membership** ; la **possession ne concerne QUE la lecture**.
2. **P2 « possession sans crypto » = l'ACL renommée.** Sans crypto, « qui détient quel token » = `Map<doc, Set<holder>>` = le `readers` actuel : **aucun delta observable**. Les vrais deltas sont **durabilité + cap-less + re-partage par le détenteur** — c'est ÇA le contenu de P2, pas « inverser l'ACL ».
3. **Révocation non-rétroactive INÉMULABLE** sans versioning : `read-model.ts:112-118` ne lit que l'état courant → « invalider l'ancien token » = retrait total = l'inverse du réel (l'ex-détenteur déchiffre les versions **antérieures**). → n'émuler que « plus de nouvelles lectures après re-key » + **documenter la non-rétroactivité comme non-émulable**.
4. **cap-less « sans exposer le contenu » ILLUSOIRE dans l'émulation** : contenu en **clair** dans le wallet partagé ; `sparqlQuery`/`inbox.read` **bypass** le filtre ; `read-filter.ts:30-35` est tout-ou-rien. → l'anonymat cap-less exige soit du **vrai crypto**, soit une **projection read-model masquée** (compter sans lire). « Remplacement pas refonte » est **surévalué**.
5. **Keyless-fetch = INFÉRÉ et load-bearing** : ajouter un **spike P0** qui le vérifie **avant** P1 (sinon le modèle — polyfill ET Festipod — est inconstruisible).
6. **Migration ≠ swap d'API.** `declareConnections` se re-joue chaque session parce que la map est éphémère ; des scellages durables déplacent le grant à l'**acceptation de connexion** + persistent « déjà scellé » — pas d'analogue de `protectedDocsOf` + la boucle de re-dérivation. **Re-architecture consommateur.**
7. *(Plausible)* livrer un cap par inbox async **ne re-déclenche pas** `watchShape` (souscrit aux docs de données, pas aux caps) → vues illisibles **périmées** jusqu'à un autre changement. → prévoir un signal de mutation de caps.

**Conséquence** : ajouter en tête **P0 (spike keyless-fetch)** et une **piste WriteCap distincte** ; requalifier P2 (le vrai contenu = durabilité + cap-less + re-partage, pas « inverser l'ACL ») ; acter que **sans crypto, la privacy de lecture n'est pas applicable** (choisir : vrai crypto vs projection masquée).

Liens : `readcap-and-nuri-model.md`, `packages/client/src/caps.ts`. Côté consommateur,
le brief Festipod « réaligner les inscriptions » dépend de ce chantier.