ng-eventually/docs/readcap-and-nuri-model.md

# Modèle ReadCap & NURI de NextGraph — et l'émulation caps du polyfill

**Établi 2026-07-20**, VÉRIFIÉ par lecture directe du cœur Rust `nextgraph-rs`
(sauf points marqués INFÉRÉ). Les `file:line` sont datés — les numéros de ligne
sont volatils, se repérer par symbole/regex.

But : donner la vérité-terrain du modèle de droits d'accès NextGraph, pour
aligner l'émulation `caps.ts` du polyfill (aujourd'hui une ACL — l'inverse du
modèle réel). C'est la base de l'item « aligner ReadCap/WriteCap avec NextGraph ».

---

## 1. Un ReadCap = possession d'une clé, PAS une ACL par-identité

Un **ReadCap est fondamentalement une clé cryptographique que l'on détient**, pas
une entrée d'ACL liée à un wallet. « Qui détient la clé peut lire. »

- Structure : `ReadCap = ObjectRef = BlockRef { id: BlockId, key: SymKey }`
  (`engine/repo/src/types.rs:461, 463-471, 557, 565`).
  - `id: BlockId` = digest **BLAKE3** (adresse de l'objet chiffré).
  - `key: SymKey = ChaCha20Key([u8;32])` = la **clé de déchiffrement**.
  Détenir le couple → le broker sert les blocs chiffrés par `id`, on déchiffre
  **localement** avec `key`.
- Granularité : par commit/objet l'`ObjectRef` **est** le cap ; pour une branche
  → commit de définition ; pour un repo → RootBranch ; pour un store → cap du
  repo racine (`types.rs:559-565`). `ReadCapSecret` = la moitié clé (`:567-570`).
- **Il n'y a PAS de read-ACL.** L'appartenance/permissions d'un repo
  (`RootBranch`, `AddMember`, `AddPermission`) gouvernent l'**écriture/admin**,
  pas la lecture. La lecture n'est gardée que par la possession de la clé.

## 2. Accorder la lecture = sceller la clé au destinataire

« Grant » = livrer le cap **scellé** (`crypto_box seal`, chiffrement à clé
publique anonyme) à la **pubkey d'inbox** du destinataire — seul lui l'ouvre avec
sa clé privée.

- Message d'inbox scellé : `InboxMsgBody.msg` = `crypto_box::seal(... to_inbox ...)`,
  ouvert avec la clé secrète d'inbox (`engine/net/src/types.rs:4272, 4299, 4319`).
- Le payload peut porter un cap : `ContactDetails.read_cap: Option<ReadCap>`
  (« if user wants to share the content of profile ») (`net/types.rs:4232-4233`)
  → **grant dirigé** (scellé à un destinataire).
- Variante **non-dirigée** : `RepoLinkV0.read_cap` = un lien partageable que
  **quiconque le reçoit** peut ouvrir (`net/types.rs:5061-5078`).

Le « ciblage wallet » vit donc dans **l'enveloppe de scellage**, pas dans le cap :
le cap reste `{id, clé}`, possession-based.

## 3. Révocation = re-key (grossier, non-rétroactif)

On ne « reprend » pas une clé livrée. Révoquer = **re-chiffrer** avec une nouvelle
clé et ne la re-sceller qu'aux autorisés restants.

- « Capabilities are not durable: they can be refreshed by members and previously
  shared Caps become obsolete/revoked… if [a member] doesn't subscribe, they lose
  access after the refresh » (`net/types.rs:5055-5058`).
- Mécanisme : `RootCapRefresh` / `BranchCapRefresh` (`repo/src/commit.rs:616,630`;
  perms `types.rs:1748-1749`).
- Conséquences : **grossier** (échelle repo/branche), **non-rétroactif** (ce qui a
  été lu avant reste connu de l'ex-détenteur ; il ne déchiffre que les versions
  **antérieures** au refresh).
- Livraison **durable** d'un cap = `PermaCap` — encore **TODO** (`repo/types.rs:578`).

## 4. Grammaire NURI : cap-less vs cap-porteur (le segment `:k:`)

Le discriminant est le segment **`:k:{clé}`** : présent = cap-porteur ; **absent =
cap-less** (nomme/localise **sans** donner le droit de lire). C'est de **première
classe** dans le type : `NuriV0.target` (des ids) et `access`/`objects` (le cap)
sont des **champs séparés** — un NURI d'id parse avec `access: vec![]`
(`engine/net/src/app_protocol.rs:53-62, 99-118, 181-195, 659-677`).

**Cap-less** (id + overlay éventuel, pas de clé) — formatters `app_protocol.rs`,
regexes `net/types.rs` :
- `did:ng:o:{repo_id}` (`:315`, `RE_REPO_O` types.rs:52)
- `did:ng:o:{repo_id}:v:{overlay_id}` (`:263`, `RE_REPO` types.rs:55)
- `did:ng:o:{repo_id}:v:{overlay_id}:b:{branch_id}` (`RE_BRANCH` types.rs:58)
- `did:ng:o:{repo_id}:c:{commit_id}` (`:355`)
- `did:ng:b:{branch}` / `h:{topic}` / `v:{overlay}` / `d:{inbox}` (`:327,323,319,359`)

**Cap-porteur** (embarque la clé) :
- `did:ng:j:{id}:k:{clé}` — read cap d'objet/fichier (`repo/types.rs:511`,
  `RE_FILE_READ_CAP` types.rs:49)
- `did:ng:o:{repo}:c:{commit}:k:{clé}` (`RE_COMMIT` types.rs:73)
- liste `RE_OBJECTS` `…:[cj]:{id}:k:{clé}…:l:{locator}` (types.rs:64)

Le segment `:v:` est l'**overlay**, qui a sa propre section ci-dessous — c'est le
point le plus lourd de conséquences pour les modèles de présence anonyme.

## 4bis. L'overlay est l'espace réseau d'un STORE — jamais d'un document

**L'overlay est l'unité d'adressage réseau d'un store.** Chez le broker, les blocs
sont rangés sous une clé `(overlay, block_id)`, et les pairs se synchronisent
*dans* un overlay. Deux formes par store :

| | Dérivation | Qui peut le calculer |
|---|---|---|
| **outer** | `OverlayId::outer(store_id)` = BLAKE3 **public** | tout le monde (le store_id suffit) |
| **inner** | `OverlayId::inner(store_id, readcap_secret)` = BLAKE3 **keyed** | seulement qui détient la clé de lecture du store |

Cohérent avec le reste du modèle : pas de rôle ni de liste, seulement « détiens-tu
la clé qui permet de dériver cet identifiant ». `outer` = le nom public du store,
`inner` = son nom privé.

**Le `:v:` d'un NURI de DOCUMENT porte l'overlay de son STORE** (VÉRIFIÉ, chaîne
lue de bout en bout) : `NuriV0::repo_graph_name(repo_id, overlay_id)` formate
`o:{repo_id}:v:{overlay_id}` ; dans `doc_create` la valeur injectée est
`store.outer_overlay()` — le store **contenant**, jamais le `repo_id`. Un `Repo` ne
porte **aucun** champ overlay (seulement `store: Arc<Store>`) ; c'est `Store` qui
porte `overlay_id`. **Contre-preuve mécanique** : dans `Store`, `get`/`put`/`del`/`has`
passent tous `&self.overlay_id` au block storage — tous les documents d'un store
partagent le namespace de blocs, donc un overlay par-document est structurellement
impossible.

### La conséquence à connaître : le `:v:` est un pseudonyme stable

**Tous les documents d'une même personne dans son store protected portent le MÊME
`:v:`** = `outer(protected_store_id)`. Donc une référence cap-less — précisément
celle qu'on utilise pour « nommer sans donner à lire » — **expose l'appartenance
au store**, c'est-à-dire un **identifiant pseudonyme stable et permanent de la
personne**. Le store_id lui-même ne fuit pas (BLAKE3 non inversible), donc ça ne
dit pas *qui* ; mais c'est un **handle constant**, le même partout et pour
toujours, corrélable par quiconque collecte des références cap-less.

**Le couplage qui en résulte, et qui contraint tout modèle de présence anonyme** :
ce même `:v:` est *simultanément* (a) ce qui permet de **dédupliquer** des
références sans les lire — deux références de même `:v:` viennent de la même
personne — et (b) ce qui permet de **tracer** cette personne d'un contexte à
l'autre. **C'est le même bit d'information.** On ne peut pas obtenir la dédup sans
concéder le traçage, ni supprimer le traçage sans perdre la dédup — sauf à changer
le découpage en stores, ce qui déplace le curseur mais ne supprime pas l'arbitrage.

*Nuances.* Le `:v:` du NURI est l'overlay **outer**, alors que le trafic
client↔broker et le stockage local utilisent l'**inner** — valeur différente, mais
tirée du store elle aussi, donc la propriété tient dans les deux cas. Un store
`Dialog` renvoie un `Inner`, toujours store-scopé.

INFÉRÉ : un détenteur **sans clé** peut vraisemblablement **récupérer les blocs
chiffrés** (avec l'overlay, toujours cap-less) → vérifier l'**existence** d'un doc
sans lire son **contenu**. Le chemin d'autorisation de fetch broker pour un
détenteur sans clé n'a **pas** été tracé — à confirmer avant de s'en servir.

## 5. Ce que le polyfill émule (caps.ts) — et où ça diverge

`packages/client/src/caps.ts` modélise `readers: Map<Nuri, Set<PrincipalId>>` +
`grantRead(doc, grantee)` (`:29-30, 41-42`) — **une ACL de principals par
document, soit l'INVERSION exacte du modèle réel** (clé). Divergences :

| | Réel NextGraph | Émulation caps.ts |
|---|---|---|
| Nature | possession de **clé** | **ACL** (set de principals) |
| Grant | sceller la clé (crypto_box) à l'inbox | ajouter un principal au set |
| Durabilité | **durable** (clé livrée une fois) | **éphémère** (Map vide à chaque session → re-déclarée) |
| Révocation | **re-key** grossier, non-rétroactif | retrait du set : **instantané et total** |
| Granularité | repo / branche / commit / objet | **un cap par doc-NURI** |
| Réf. sans droit | **NURI cap-less** (sans `:k:`) | pas de notion (l'ACL dit qui peut) |

**Face app** : `declareConnections` (côté consommateur) qui re-déclare « mes
connexions lisent mes entités protected » **à chaque session** est un **artefact
de cette ACL éphémère** — sans objet dans le modèle réel (les scellages y sont
durables ; on scelle par-doc au partage, pas par-session).

## 6. Implications pour les consommateurs (ex. Festipod)

- « **scope protected = mon réseau peut lire** » n'est **pas** une ACL vérifiée
  par le broker : c'est « j'ai **scellé ma read key** à chacune de mes
  connexions ». Le modèle mental « scope = ACL » est faux au niveau NextGraph.
- **Références anonymes possibles** : mettre un **NURI cap-less** dans une
  collection tierce laisse le tiers **nommer/compter** sans **lire l'identité** ;
  sceller le cap-porteur séparément aux seuls autorisés. (Base d'un modèle de
  présence « participation auto-possédée + Set curé cap-less + cap scellé aux
  connexions ».)
- **Alignement à faire** : quand les vraies opérations de cap seront disponibles,
  remplacer l'ACL émulée par du scellage de clé durable par-doc, et
  `declareConnections`-comme-ACL-ré-déclarée disparaît.

## Réserves / lacunes

- `file:line` datés (2026-07) — re-vérifier par symbole ; le core bouge.
- INFÉRÉ : fetch broker keyless (existence sans clé) — non tracé au runtime.
- Non tracé : exécution complète de `RootCapRefresh` côté verifier
  (`verifier/src/commits/mod.rs:616`), stockage wallet de `private_store_read_cap`
  (`repo/types.rs:945,976`).