Files

T

Sylvain Duchesne 9d3e2d2bfe Fix documentation defects found by an adversarial review

Fifteen findings, all verified before acting. The ones that mattered:

- Corrections added without updating what they corrected. §5's table still
  said a cap-less NURI is one "without :k:", two hundred lines after §4
  established the discriminant is `r:`. Same shape of defect in the P1a
  report, which kept the sentence "it is the owner's keyring, upstream the
  keyring is the wallet" — the exact sentence §4quater declares wrong, and the
  one that produced a global in-memory keyring.

- A wrong source citation: RootCapRefresh/BranchCapRefresh live in
  verifier/src/commits/mod.rs, not repo/src/commit.rs, and are no-op stubs.

- Documentation describing deleted code: isolation.ts, discovery.readIndex,
  the global index, and an acceptance test that was dropped with discovery.

- The P1a implementation report had aged into being wrong in four places
  (caps not persisted, inbox processing not started, plain string types, the
  :k: segment). It is dated, so it now carries a header saying what later lots
  overtook, rather than being rewritten.

- vision.md stated "a document's data is stored encrypted" in the present
  tense. That is the target; here the cap value is the constant OK and nothing
  is encrypted. Said plainly now.

- Prose left mangled by an earlier mechanical find-and-replace, in four places
  I had claimed were repaired.

Also: reach.ts and connect.ts had no home in the permanent docs — the boundary
and the connection sequence are now described in simulation.md, not only in a
brief.

2026-08-03 11:34:24 +02:00

3.4 KiB

Raw Blame History

Vision & principles of the `@ng-eventually/client` polyfill

Purpose

A stand-in faithful in SHAPE to NextGraph's future primitives. Single objective: that consumers (Festipod) be coded against the CORRECT mental model — the one of finished NextGraph — and have NOTHING to rewrite when NextGraph provides the real primitives.

What the polyfill is NOT

A security layer. The shared wallet (everyone shares the same keys) plus the absence of real crypto make the emulation infinitely less secure than a wallet-per-user — it is a dev/staging vehicle, not a goal. Insecurity is ACCEPTED. An attacker who bypasses the emulation is not our problem.

The only criterion: shape-fidelity, with RIGOR

The exposed surfaces must match the exact SHAPE of the future primitives, even where enforcement is simulated. The failure mode to avoid: exposing the wrong shape → the consumer codes against a model that will not exist → rewrite. The ACL inversion of ReadCaps was exactly that defect (an ACL where the real thing is key possession) — a lack of rigor.

Simulating crypto to PREVENT shortcuts

Without a minimum of crypto simulation, damaging shortcuts get taken (reading the plaintext, falling back on ACLs). The polyfill therefore simulates the final mechanism, enough to hold this invariant:

A did (bare id, WITHOUT a ReadCap) and a NURI (WITH a ReadCap) are treated GENUINELY differently: the former does NOT allow reading the data; the latter is SUFFICIENT and REQUIRED.

Concretely, in the target: a document's data is stored encrypted (per-doc symmetric encryption, however lightweight); the ReadCap = the key; without it, decrypting/reading is impossible. No ACL, no plaintext accessible "on the side". Obtaining read access = holding the key, exactly as in the target model.

Not yet true here, and saying so matters. The shape is in place — possession decides, every access is confined to the connected virtual user, caps are stored and read back — but the cap value is the constant OK and nothing is encrypted. Per-document encryption is P1b, and it is one function (nuri.ts mintCap). Until it lands, nothing this library does may be described as anonymous or private.

Shape consequences (to respect everywhere)

Everything is keys and URLs. There is no notion of membership, role, or authorization list in the model: only symmetric and asymmetric cryptography, URIs, and who holds which key. Any exposed shape that looks like an ACL, a member, a role, or a permission is a wrong shape, whatever scaffolding one may otherwise read in the current state of NextGraph.
Reading = possession of the read key (ReadCap = {id, key}). A bare id (a did without a ReadCap) does not read.
Writing = possession of the write key — a key distinct from the read key, hence a distinct axis, but possession too.
Sharing a cap = sealing it to a recipient (durable delivery, at share time — NOT an ACL re-declared every session).
Revocation = re-key (new key; former holders keep the old state). Non-retroactive.
Cap-less reference (naming/pointing without reading) distinct from the cap-bearing reference.

See readcap-and-nuri-model.md (the real model, verified in nextgraph-rs) and briefs/2026-07-20-caps-emulation-alignment.md (the alignment effort).

3.4 KiB Raw Blame History

Vision & principles of the @ng-eventually/client polyfill