feat(client): real per-document isolation + bilateral connections + deposit guards

The ReadCap filter now enforces on per-entity documents (consumers create one doc
per entity, so each has a declared policy — private→owner, protected→owner+
connections, public→all). Isolation is genuinely active, not dormant.

- connections.ts (new): a BILATERAL connection registry — a link grants protected
  read only when BOTH sides have asserted it (each assertion bound to its author).
  A unilateral/self-declared connection grants nothing (closes the confused-deputy
  hole). declareConnections is authenticated to the current identity.
- inbox.post: `from` is bound to the current identity — a spoofed `from` throws.
- discovery.submitToIndex: PUBLIC-ONLY — a governed non-public doc is refused
  (no protected/private leak into the world-readable index).
- docs/simulation.md: documents this as application-level emulated isolation on a
  shared wallet (not crypto); at NextGraph maturity → real caps, consumer unchanged.

89 tests pass (+10 covering: active protected isolation via bilateral connect,
unilateral grants nothing, from-spoof rejected, non-public submit refused). tsc rc=0.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

packages/client/test/connections.test.ts

@@ -0,0 +1,60 @@
+/**
+ * ConnectionRegistry — BILATERAL connection materialization (T03.h).
+ *
+ * A connection is live only when BOTH sides have asserted the other. A unilateral
+ * (self-declared) assertion yields no neighbour — the defence against a reader who
+ * fakes a connection to an owner to read that owner's protected documents.
+ */
+import { test, expect } from "bun:test";
+import { ConnectionRegistry, bilateralConnections } from "../src/connections";
+
+test("a UNILATERAL assertion yields NO neighbour", () => {
+  const reg = new ConnectionRegistry();
+  reg.assert("mallory", "alice"); // mallory self-declares; alice never asserts back
+  expect([...reg.neighbors("mallory")]).toEqual([]);
+  expect([...reg.neighbors("alice")]).toEqual([]);
+});
+
+test("a BILATERAL assertion (both sides) materializes the link", () => {
+  const reg = new ConnectionRegistry();
+  reg.assert("alice", "bob");
+  reg.assert("bob", "alice");
+  expect([...reg.neighbors("alice")]).toEqual(["bob"]);
+  expect([...reg.neighbors("bob")]).toEqual(["alice"]);
+});
+
+test("mixed: only the reciprocated peers surface", () => {
+  const reg = new ConnectionRegistry();
+  reg.assert("alice", "bob"); // reciprocated below
+  reg.assert("bob", "alice");
+  reg.assert("alice", "carol"); // NOT reciprocated by carol
+  reg.assert("dave", "alice"); // dave asserts alice, alice never asserts dave
+  expect([...reg.neighbors("alice")].sort()).toEqual(["bob"]);
+});
+
+test("self-assertion and empty are ignored", () => {
+  const reg = new ConnectionRegistry();
+  reg.assert("alice", "alice");
+  reg.assert("", "bob");
+  reg.assert("alice", "");
+  expect([...reg.neighbors("alice")]).toEqual([]);
+});
+
+test("bilateralConnections adapts to the Connections interface", () => {
+  const reg = new ConnectionRegistry();
+  reg.assertAll([
+    { from: "alice", to: "bob" },
+    { from: "bob", to: "alice" },
+  ]);
+  const conns = bilateralConnections(reg);
+  expect([...conns.neighbors("alice")]).toEqual(["bob"]);
+  expect([...conns.neighbors("carol")]).toEqual([]);
+});
+
+test("clear() removes all assertions", () => {
+  const reg = new ConnectionRegistry();
+  reg.assert("alice", "bob");
+  reg.assert("bob", "alice");
+  reg.clear();
+  expect([...reg.neighbors("alice")]).toEqual([]);
+});

packages/client/test/discovery.test.ts

@@ -7,6 +7,8 @@ import {
   resetStoreRegistry,
   resetConfig,
   setCurrentUser,
+  getCaps,
+  resetCaps,
 } from "../src/polyfill";
 import { resetRegistryCache, ensureAccount } from "../src/store-registry";
 import type { RegistrySession } from "../src/store-registry";
@@ -20,6 +22,7 @@ afterAll(() => {
   resetConfig();
   resetStoreRegistry();
   setCurrentUser(null);
+  resetCaps();
 });
 
 test("throws a clear error when configureStoreRegistry() was not called", async () => {
@@ -171,6 +174,7 @@ test("submitToIndex creates the @index special account on first sight (3 docs)",
 });
 
 test("submit → read round-trips the reference as an index entry", async () => {
+  setCurrentUser("alice"); // `from` is bound to the current identity
   const ref = { nuri: "did:ng:o:event1", title: "Concert au parc" };
   await submitToIndex(ref, { from: "alice", ts: 100 });
   const entries = await readIndex();
@@ -197,8 +201,9 @@ test("a reference submitted by A is discovered by a NON-connected reader via the
 
 test("readIndex deduplicates identical references (materialization moderation point)", async () => {
   const ref = { nuri: "did:ng:o:dup", title: "Twice" };
-  await submitToIndex(ref, { from: "alice", ts: 100 });
-  await submitToIndex(ref, { from: "bob", ts: 200 }); // duplicate reference
+  // Anonymous submissions (dedup keys on the ref, not the submitter).
+  await submitToIndex(ref, { from: null, ts: 100 });
+  await submitToIndex(ref, { from: null, ts: 200 }); // duplicate reference
   const entries = await readIndex();
   expect(entries).toHaveLength(1); // surfaced once
 });
@@ -209,6 +214,30 @@ test("from: null makes an anonymous submission", async () => {
   expect(entries[0]!.from).toBeNull();
 });
 
+// (d) PUBLIC-ONLY: a protected/private document must NOT be submittable to the
+// world-readable discovery index; a public (or ungoverned) document is fine.
+test("(d) submitToIndex refuses a PROTECTED/PRIVATE document (public-only)", async () => {
+  resetCaps();
+  // A PROTECTED and a PRIVATE governed document, and a PUBLIC one.
+  getCaps().open("did:ng:o:prot", "protected", "alice");
+  getCaps().open("did:ng:o:priv", "private", "alice");
+  getCaps().open("did:ng:o:pub", "public", "alice");
+
+  // Submitting the protected doc's NURI is REJECTED.
+  await expect(
+    submitToIndex({ nuri: "did:ng:o:prot" }, { from: null, doc: "did:ng:o:prot" }),
+  ).rejects.toThrow(/PUBLIC|public-only|protected\/private/i);
+  // Private too.
+  await expect(
+    submitToIndex({ nuri: "did:ng:o:priv" }, { from: null, doc: "did:ng:o:priv" }),
+  ).rejects.toThrow(/PUBLIC|public-only|protected\/private/i);
+  // The PUBLIC document passes.
+  await submitToIndex({ nuri: "did:ng:o:pub" }, { from: null, doc: "did:ng:o:pub", ts: 1 });
+  const entries = await readIndex();
+  expect(entries.map((e) => (e.ref as { nuri: string }).nuri)).toEqual(["did:ng:o:pub"]);
+  resetCaps();
+});
+
 test("INDEX_ACCOUNT lives in the reserved namespace (no typed username can equal it)", () => {
   // The index account occupies a key no user input can produce: it is prefixed
   // with a NUL control char, which a user cannot type into a username field and

packages/client/test/inbox.test.ts

@@ -134,6 +134,7 @@ beforeEach(() => {
 });
 
 test("post writes via the real injected ng.sparql_update (not makeNg), scoped to the inbox", async () => {
+  setCurrentUser("alice"); // `from` is bound to the current identity
   await post(TARGET, { from: "alice", payload: { kind: "join" }, ts: 100 });
   expect(fake.sparql_update).toHaveBeenCalledTimes(1);
   const call = fake.sparql_update.mock.calls[0]!;
@@ -143,12 +144,29 @@ test("post writes via the real injected ng.sparql_update (not makeNg), scoped to
 });
 
 test("post → read round-trips payload, from and ts", async () => {
+  setCurrentUser("alice"); // `from` is bound to the current identity
   await post(TARGET, { from: "alice", payload: { kind: "join", n: 3 }, ts: 100 });
   const deposits = await read(TARGET);
   expect(deposits).toHaveLength(1);
   expect(deposits[0]).toEqual({ from: "alice", payload: { kind: "join", n: 3 }, ts: 100 });
 });
 
+// (c) `from` is BOUND to the current identity — a spoof (naming another
+// principal) is REJECTED; identifying as self or anonymous (null) is allowed.
+test("(c) post rejects a spoofed `from` (naming another principal); self/null allowed", async () => {
+  setCurrentUser("alice");
+  // SPOOF: alice tries to deposit AS bob → rejected.
+  await expect(post(TARGET, { from: "bob", payload: { x: 1 }, ts: 1 })).rejects.toThrow(
+    /spoof|current identity/i,
+  );
+  // Identifying as self → allowed.
+  await post(TARGET, { from: "alice", payload: { x: 2 }, ts: 2 });
+  // Explicit anonymous → allowed.
+  await post(TARGET, { from: null, payload: { x: 3 }, ts: 3 });
+  const froms = (await read(TARGET)).map((d) => d.from);
+  expect(froms).toEqual(["alice", null]);
+});
+
 test("from is optional — omitting it defaults to the current user", async () => {
   setCurrentUser("bob");
   await post(TARGET, { payload: { hi: 1 }, ts: 200 });

packages/client/test/isolation-active.test.ts

@@ -1,12 +1,15 @@
 /**
- * ReadCap ACTIVE — end-to-end proof that isolation is enforced by the emulated
- * cap registry (not merely by the app's social isolation filter).
+ * ReadCap ACTIVE (T03.h) — end-to-end proof that the emulated SDK enforces
+ * per-DOCUMENT isolation, driven by per-entity documents + BILATERAL connections.
  *
- * This mirrors exactly what the app's storeRegistry wrapper does: create an
- * entity document through the REAL registry (`createEntityDoc`), then declare
- * its cap policy via `getCaps().open(doc, scope, owner)`. The read filter then
- * hides one owner's private document from another principal — the faithful
- * per-DOCUMENT NextGraph behavior.
+ * Mirrors exactly what the app does: create an entity document through the REAL
+ * registry (`createEntityDoc`), declare its cap policy via
+ * `getCaps().open(doc, scope, owner)`, set the current identity, and declare
+ * connections as the CURRENT identity's own peers (authenticated, bilateral). The
+ * read filter then discriminates:
+ *   (a) unconnected principal denied a PROTECTED doc; granted after a BILATERAL
+ *       connection; PUBLIC readable throughout — via the ACTIVE ReadCap.
+ *   (b) a UNILATERAL / self-declared connection grants NOTHING.
  */
 import { test, expect, mock, afterAll } from "bun:test";
 import { createEntityDoc, resetRegistryCache } from "../src/store-registry";
@@ -18,15 +21,16 @@ import {
   resetConfig,
   getCaps,
   resetCaps,
+  setCurrentUser,
   declareConnections,
 } from "../src/polyfill";
 import { filterReadable } from "../src/read-filter";
-import { connectionsFromLinks } from "../src/isolation";
 
 afterAll(() => {
   resetConfig();
   resetStoreRegistry();
   resetCaps();
+  setCurrentUser(null);
 });
 
 const SESSION: RegistrySession = { sessionId: "sid", privateStoreId: "PRIV" };
@@ -42,75 +46,78 @@ function inject() {
   configureStoreRegistry({ getSession: async () => SESSION, normalizeUser: (u) => u.trim() });
   resetRegistryCache();
   resetCaps();
+  setCurrentUser(null);
   return ng;
 }
 
 test("ReadCap active: a private entity doc created via the real registry is hidden from another principal", async () => {
   inject();
 
-  // Alice creates a PRIVATE entity document via the REAL store-registry, then
-  // (as the app wrapper does) declares its cap policy: owner-only read.
   const aliceDoc = await createEntityDoc("alice", "private");
   getCaps().open(aliceDoc, "private", "alice");
 
-  // Bob creates a PUBLIC entity document (world-readable).
   const bobDoc = await createEntityDoc("bob", "public");
   getCaps().open(bobDoc, "public", "bob");
 
-  // The reactive set as the broker would deliver it (mono-store: items carry
-  // their @graph = the document they live in).
   const items = [
     { "@graph": aliceDoc, "@id": "a1", label: "alice-private" },
     { "@graph": bobDoc, "@id": "b1", label: "bob-public" },
   ];
 
-  // Bob cannot read alice's private doc; he CAN read the public one and, since
-  // the read filter is now under a policy, alice's private item is filtered out.
-  const bobView = filterReadable(items, getCaps(), "bob").map((i) => i["@id"]);
-  expect(bobView).toEqual(["b1"]);
-
-  // Alice reads her own private doc AND the public one.
-  const aliceView = filterReadable(items, getCaps(), "alice").map((i) => i["@id"]);
-  expect(aliceView.sort()).toEqual(["a1", "b1"]);
-
-  // Anonymous sees only the public doc.
-  const anonView = filterReadable(items, getCaps(), null).map((i) => i["@id"]);
-  expect(anonView).toEqual(["b1"]);
-
-  // Sanity: this is the REGISTRY talking, not app-level isolation — the caps
-  // registry has an active read policy.
+  expect(filterReadable(items, getCaps(), "bob").map((i) => i["@id"])).toEqual(["b1"]);
+  expect(filterReadable(items, getCaps(), "alice").map((i) => i["@id"]).sort()).toEqual(["a1", "b1"]);
+  expect(filterReadable(items, getCaps(), null).map((i) => i["@id"])).toEqual(["b1"]);
   expect(getCaps().hasReadPolicy()).toBe(true);
 });
 
-test("ReadCap active: a PROTECTED entity doc is hidden from an unconnected principal, revealed after they connect, PUBLIC readable regardless", async () => {
+// (a) protected hidden while unconnected → revealed after a BILATERAL connection;
+//     public readable regardless — all through the ACTIVE ReadCap.
+test("(a) PROTECTED doc: hidden unconnected, revealed after BILATERAL connection, PUBLIC always readable", async () => {
   inject();
 
-  // Alice creates a PROTECTED entity document + a PUBLIC one, declaring the caps
-  // exactly as the app wrapper does (createEntityDoc → getCaps().open).
   const aliceProtected = await createEntityDoc("alice", "protected");
   getCaps().open(aliceProtected, "protected", "alice");
   const alicePublic = await createEntityDoc("alice", "public");
   getCaps().open(alicePublic, "public", "alice");
 
   const items = [
-    { "@graph": aliceProtected, "@id": "p1", label: "alice-protected" },
-    { "@graph": alicePublic, "@id": "u1", label: "alice-public" },
+    { "@graph": aliceProtected, "@id": "p1" },
+    { "@graph": alicePublic, "@id": "u1" },
   ];
+  const view = (u: string) => filterReadable(items, getCaps(), u).map((i) => i["@id"]).sort();
 
-  const view = (user: string) => filterReadable(items, getCaps(), user).map((i) => i["@id"]).sort();
-
-  // BEFORE any connection: bob (unconnected) sees ONLY alice's public item, NOT
-  // her protected one. Alice sees both.
+  // BEFORE any connection: bob sees only the public item.
   expect(view("bob")).toEqual(["u1"]);
   expect(view("alice")).toEqual(["p1", "u1"]);
 
-  // The app declares the CONNECTIONS graph to the SDK (domain sharing act): now
-  // alice and bob are connected. The SDK issues the protected doc's read cap to
-  // bob (owner's connection). Public is unaffected.
-  declareConnections(connectionsFromLinks([{ a: "alice", b: "bob" }]));
+  // BILATERAL: alice asserts bob AND bob asserts alice → the link materializes and
+  // the SDK issues the protected doc's read cap to bob.
+  declareConnections(["bob"], "alice");
+  declareConnections(["alice"], "bob");
 
-  // AFTER connecting: bob reads alice's PROTECTED item too; PUBLIC still readable.
   expect(view("bob")).toEqual(["p1", "u1"]);
-  // A THIRD, still-unconnected principal (carol) sees only the public one.
+  // A third, unconnected principal still sees only the public one.
   expect(view("carol")).toEqual(["u1"]);
 });
+
+// (b) A UNILATERAL / self-declared connection must NOT grant protected read.
+test("(b) a UNILATERAL / self-declared connection grants NO protected read", async () => {
+  inject();
+
+  const aliceProtected = await createEntityDoc("alice", "protected");
+  getCaps().open(aliceProtected, "protected", "alice");
+  const items = [{ "@graph": aliceProtected, "@id": "p1" }];
+  const view = (u: string) => filterReadable(items, getCaps(), u).map((i) => i["@id"]);
+
+  // The ATTACKER (mallory) self-declares a connection to alice — a UNILATERAL
+  // assertion authored by mallory. Alice NEVER asserts mallory back.
+  declareConnections(["alice"], "mallory");
+  expect(view("mallory")).toEqual([]); // still denied — no bilateral link
+
+  // Even if alice connects to bob (a different, legitimate bilateral link),
+  // mallory's one-sided assertion still grants nothing.
+  declareConnections(["bob"], "alice");
+  declareConnections(["alice"], "bob");
+  expect(view("mallory")).toEqual([]);
+  expect(view("bob")).toEqual(["p1"]);
+});