From 88d96857fb9d41c30fc5b0c7e735e2e0c77243ce Mon Sep 17 00:00:00 2001 From: Sylvain Duchesne Date: Mon, 29 Jun 2026 11:19:57 +0200 Subject: [PATCH] Refactor read filter from per-item grant to per-document ReadCap MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Model the read filter on NextGraph's real ReadCap mechanism instead of an invented per-item grant. Verified in nextgraph-rs: there is no Document type (document = repo); a store is a container repo referencing other repos by RDF overlay; holding a store's cap does NOT grant the repos it contains (each repo needs its own cap; no read-cap inheritance). So the access unit is the DOCUMENT = an item's `@graph`, never the item. - caps.ts: CapRegistry (read/write caps per document NURI + public docs; open/grantRead/grantWrite/makePublic/canRead/canWrite/governsRead/ hasReadPolicy). Replaces access.ts (Grant). - read-filter.ts: filter keeps an item iff its `@graph` document is readable (held cap or public); items with no `@graph` or in an ungoverned document are kept. No injected grantOf — the filter reads `@graph` and consults the registry (automatic, domain-agnostic). - polyfill.ts: getCaps()/resetCaps() replace setGrantOf/getGrantOf; useShape filters only when caps.hasReadPolicy() (else passthrough, no regression). - tests: caps.test.ts (6) + read-filter.test.ts (4), incl. no-inheritance between documents. 10 pass; tsc rc=0. Co-Authored-By: Claude Opus 4.8 (1M context) --- packages/client/src/access.ts | 42 ---------- packages/client/src/caps.ts | 97 ++++++++++++++++++++++++ packages/client/src/polyfill.ts | 28 +++---- packages/client/src/read-filter.ts | 52 ++++++++----- packages/client/src/types.ts | 13 ---- packages/client/src/use-shape.ts | 17 +++-- packages/client/test/access.test.ts | 30 -------- packages/client/test/caps.test.ts | 50 ++++++++++++ packages/client/test/read-filter.test.ts | 51 ++++++++----- 9 files changed, 231 insertions(+), 149 deletions(-) delete mode 100644 packages/client/src/access.ts create mode 100644 packages/client/src/caps.ts delete mode 100644 packages/client/test/access.test.ts create mode 100644 packages/client/test/caps.test.ts diff --git a/packages/client/src/access.ts b/packages/client/src/access.ts deleted file mode 100644 index bb00229..0000000 --- a/packages/client/src/access.ts +++ /dev/null @@ -1,42 +0,0 @@ -/** - * Capability emulation — pure, generic, no domain rules. Mirrors what the broker - * will enforce via real caps; at migration these checks disappear (the broker - * only ever syncs/serves what the wallet is authorized for). - */ - -import type { Grant, PrincipalId, Scope } from "./types"; - -/** May `principal` read a document carrying `grant`? */ -export function canRead(grant: Grant, principal: PrincipalId | null): boolean { - if (grant.read.includes("public")) return true; - if (principal === null) return false; - return grant.read.includes(principal); -} - -/** May `principal` write a document carrying `grant`? */ -export function canWrite(grant: Grant, principal: PrincipalId | null): boolean { - if (principal === null) return false; - return grant.write.includes(principal); -} - -/** - * The grant a freshly created document gets, by scope, for its `owner`. These - * are the *defaults* a creator attaches; further sharing (e.g. granting a - * connection read on a protected doc) is a separate explicit act. - */ -export function defaultGrant(scope: Scope, owner: PrincipalId): Grant { - switch (scope) { - case "public": - return { read: ["public"], write: [owner] }; - case "protected": - return { read: [owner], write: [owner] }; - case "private": - return { read: [owner], write: [owner] }; - } -} - -/** Add a read grant to a principal (e.g. when a connection is accepted). */ -export function grantRead(grant: Grant, principal: PrincipalId): Grant { - if (grant.read.includes(principal)) return grant; - return { ...grant, read: [...grant.read, principal] }; -} diff --git a/packages/client/src/caps.ts b/packages/client/src/caps.ts new file mode 100644 index 0000000..cf2ddf2 --- /dev/null +++ b/packages/client/src/caps.ts @@ -0,0 +1,97 @@ +/** + * Capability emulation — generic, no domain rules. Models NextGraph **ReadCaps** + * (and write caps) as faithfully as a data layer can. + * + * In NextGraph a ReadCap is possession of a *document's* (repo's) read key: the + * broker only ever delivers documents the wallet holds a cap for. The access + * UNIT is therefore the **document = repo**, identified here by its NURI — the + * `@graph` an item lives in — **never the item**. (Verified in nextgraph-rs: + * a store is just a container repo; holding a store's cap does NOT grant the + * repos it references — each document needs its own cap. So this registry is + * purely per-document, with NO store-level inheritance.) + * + * At migration this whole layer disappears: the broker/verifier enforces the + * real caps and `useShape` already returns only authorized documents. + */ + +import type { Nuri, PrincipalId, Scope } from "./types"; + +/** + * Who holds the read/write cap of each document. The consumer populates it via + * cap operations (create-public, grant-to-a-connection…) exactly as it will in + * the target; this layer enforces possession generically — it knows no policy. + */ +export class CapRegistry { + /** doc NURI → principals holding its READ cap. */ + private readers = new Map>(); + /** doc NURI → principals holding its WRITE cap. */ + private writers = new Map>(); + /** doc NURIs readable by everyone (public_store repos — no cap needed). */ + private publicDocs = new Set(); + + /** Grant `principal` the READ cap of document `doc`. */ + grantRead(doc: Nuri, principal: PrincipalId): void { + add(this.readers, doc, principal); + } + + /** Grant `principal` the WRITE cap of document `doc`. */ + grantWrite(doc: Nuri, principal: PrincipalId): void { + add(this.writers, doc, principal); + } + + /** Mark `doc` public (readable without a cap — a public_store repo). */ + makePublic(doc: Nuri): void { + this.publicDocs.add(doc); + } + + /** + * Apply the caps a creator attaches to a fresh document, by scope. Public → + * world-readable; protected/private → only the owner reads. The owner always + * holds the write cap. Further sharing is a separate explicit grant. + */ + open(doc: Nuri, scope: Scope, owner: PrincipalId): void { + if (scope === "public") this.makePublic(doc); + else this.grantRead(doc, owner); + this.grantWrite(doc, owner); + } + + /** Is `doc` under any READ-cap policy? (Undeclared docs are not enforced.) */ + governsRead(doc: Nuri): boolean { + return this.publicDocs.has(doc) || this.readers.has(doc); + } + + /** Does `principal` hold a READ cap for `doc` (or is `doc` public)? */ + canRead(doc: Nuri, principal: PrincipalId | null): boolean { + if (this.publicDocs.has(doc)) return true; + if (principal === null) return false; + return this.readers.get(doc)?.has(principal) ?? false; + } + + /** Is `doc` under any WRITE-cap policy? */ + governsWrite(doc: Nuri): boolean { + return this.writers.has(doc); + } + + /** Does `principal` hold a WRITE cap for `doc`? */ + canWrite(doc: Nuri, principal: PrincipalId | null): boolean { + if (principal === null) return false; + return this.writers.get(doc)?.has(principal) ?? false; + } + + /** No READ policy declared → the read filter stays inert (passthrough). */ + hasReadPolicy(): boolean { + return this.readers.size > 0 || this.publicDocs.size > 0; + } + + clear(): void { + this.readers.clear(); + this.writers.clear(); + this.publicDocs.clear(); + } +} + +function add(m: Map>, doc: Nuri, principal: PrincipalId): void { + let s = m.get(doc); + if (!s) m.set(doc, (s = new Set())); + s.add(principal); +} diff --git a/packages/client/src/polyfill.ts b/packages/client/src/polyfill.ts index f40f917..b8e86dd 100644 --- a/packages/client/src/polyfill.ts +++ b/packages/client/src/polyfill.ts @@ -9,7 +9,7 @@ */ import type { NgLike, UseShapeLike, PrincipalId } from "./types"; -import type { GrantResolver } from "./read-filter"; +import { CapRegistry } from "./caps"; export interface EventuallyConfig { /** The REAL `@ng-org/web` `ng` (injected to avoid a hard import / alias loop). */ @@ -24,18 +24,17 @@ export interface EventuallyConfig { init?: (...args: any[]) => any; /** REAL `@ng-org/orm` `initNg` (ORM signals) — forwarded by the lib's `initNg()`. */ initNg?: (...args: any[]) => any; - /** How to read a document's emulated grant. When set, reads are filtered. */ - grantOf?: GrantResolver; } let cfg: EventuallyConfig | null = null; let currentUser: PrincipalId | null = null; -let grantOf: GrantResolver | null = null; +/** The emulated ReadCap/WriteCap registry. Empty until the app declares caps; + * while it has no read policy the read filter passes through (no regression). */ +let caps = new CapRegistry(); export function configure(c: EventuallyConfig): void { cfg = c; currentUser = c.currentUser ?? null; - grantOf = c.grantOf ?? null; } /** @internal — used by the SDK-shaped wrappers to reach the injected real SDK. */ @@ -53,16 +52,17 @@ export function getCurrentUser(): PrincipalId | null { return currentUser; } -/** Set/clear how reads resolve a document's grant. null → reads pass through. */ -export function setGrantOf(fn: GrantResolver | null): void { - grantOf = fn; +/** The emulated cap registry — the app grants/opens caps on it (as it will via + * real cap operations in the target). The read filter consults it. */ +export function getCaps(): CapRegistry { + return caps; } -export function getGrantOf(): GrantResolver | null { - return grantOf; +/** Reset all emulated caps (mainly for tests / fresh sessions). */ +export function resetCaps(): void { + caps = new CapRegistry(); } -// Capability helpers — polyfill-era surface (caps are emulated now; native at -// migration). Re-exported here so the whole polyfill API lives under /polyfill. -export { canRead, canWrite, defaultGrant, grantRead } from "./access"; -export type { GrantResolver } from "./read-filter"; +// Cap surface — polyfill-era (caps are emulated now; native at migration). +// Re-exported here so the whole polyfill API lives under /polyfill. +export { CapRegistry } from "./caps"; diff --git a/packages/client/src/read-filter.ts b/packages/client/src/read-filter.ts index 3ff5536..67e7ee0 100644 --- a/packages/client/src/read-filter.ts +++ b/packages/client/src/read-filter.ts @@ -1,34 +1,47 @@ /** * Read filter — the polyfill of capability-based read access. * - * In the target, the broker only delivers documents the user holds a read cap + * In the target, the broker only delivers documents the user holds a **ReadCap** * for, so `useShape` already returns an authorized subset. Here (single shared - * wallet, everything readable) we reproduce that: a read-filtered VIEW over the - * reactive set that yields only items whose emulated grant satisfies the current - * user. Removed at migration (the broker does it natively). + * wallet, everything readable) we reproduce that with a read-filtered VIEW over + * the reactive set: it keeps only items whose **document** (its `@graph` = the + * repo it lives in) the current user may read, per the {@link CapRegistry}. + * + * Faithful to NextGraph: the access unit is the DOCUMENT, not the item. In a + * mono-store layout (every item in one repo) the filter is therefore all-or- + * nothing on that document — which is exactly the native behavior, and why + * fine-grained isolation requires one document per entity. Removed at migration. */ -import { canRead } from "./access"; -import type { Grant, PrincipalId } from "./types"; +import type { CapRegistry } from "./caps"; +import type { PrincipalId } from "./types"; + +/** The document (repo NURI) an item lives in — its `@graph`. */ +function docOf(item: unknown): string | null { + const g = (item as Record | null)?.["@graph"]; + return typeof g === "string" ? g : null; +} /** - * Reads a document's emulated grant. Return `undefined` when the item carries no - * grant — such items are kept (the filter only restricts items that DECLARE a - * grant). The consumer injects this (the lib stays domain-agnostic). + * May `user` read this item? An item with no `@graph`, or in a document under no + * cap policy, is KEPT (the filter only restricts documents that DECLARE a cap — + * mirrors the prior behavior and keeps ungoverned data flowing). */ -export type GrantResolver = (item: unknown) => Grant | undefined; +function readable(item: unknown, caps: CapRegistry, user: PrincipalId | null): boolean { + const doc = docOf(item); + if (doc === null) return true; + if (!caps.governsRead(doc)) return true; + return caps.canRead(doc, user); +} -/** Pure: keep only the items the user may read. Ungranted items are kept. */ +/** Pure: keep only the items the user may read. */ export function filterReadable( items: Iterable, - grantOf: GrantResolver, + caps: CapRegistry, user: PrincipalId | null, ): T[] { const out: T[] = []; - for (const item of items) { - const g = grantOf(item); - if (g === undefined || canRead(g, user)) out.push(item); - } + for (const item of items) if (readable(item, caps, user)) out.push(item); return out; } @@ -41,13 +54,10 @@ export function filterReadable( */ export function makeReadFilteredView( set: S, - grantOf: GrantResolver, + caps: CapRegistry, getUser: () => PrincipalId | null, ): S { - const keep = (item: unknown): boolean => { - const g = grantOf(item); - return g === undefined || canRead(g, getUser()); - }; + const keep = (item: unknown): boolean => readable(item, caps, getUser()); return new Proxy(set, { get(target, prop, receiver) { if (prop === Symbol.iterator) { diff --git a/packages/client/src/types.ts b/packages/client/src/types.ts index e528a86..f27af1a 100644 --- a/packages/client/src/types.ts +++ b/packages/client/src/types.ts @@ -13,19 +13,6 @@ export type Scope = "public" | "protected" | "private"; * Polyfill: a chosen id (e.g. a username), because everyone shares one wallet. */ export type PrincipalId = string; -/** - * Emulated capability attached to a document — mirrors real NextGraph caps, - * which the broker/verifier will enforce natively at migration. The app attaches - * these via cap operations exactly as it will in the target; this layer enforces - * them generically (it does NOT know any authorization policy). - */ -export interface Grant { - /** Read grant: `"public"` = everyone, otherwise explicit principals. */ - read: Array; - /** Write grant: principals allowed to write the document. */ - write: PrincipalId[]; -} - /** * Loose shape of the real `@ng-org/web` `ng` object that we wrap. Injected by * the consumer at {@link configure} — we never hard-import the SDK, which keeps diff --git a/packages/client/src/use-shape.ts b/packages/client/src/use-shape.ts index 78047c6..60b7c05 100644 --- a/packages/client/src/use-shape.ts +++ b/packages/client/src/use-shape.ts @@ -1,16 +1,17 @@ /** - * Wrapped `useShape`: same signature as `@ng-org/orm`. When a grant resolver is - * configured, the returned set is a read-filtered VIEW (only items the current - * user may read); otherwise it passes the real set through unchanged. At - * migration the filtering disappears — the broker only delivers authorized docs. + * Wrapped `useShape`: same signature as `@ng-org/orm`. When a read-cap policy is + * declared, the returned set is a read-filtered VIEW (only items in documents the + * current user holds a ReadCap for); otherwise it passes the real set through + * unchanged. At migration the filtering disappears — the broker only delivers + * authorized documents. */ -import { getConfig, getCurrentUser, getGrantOf } from "./polyfill"; +import { getConfig, getCurrentUser, getCaps } from "./polyfill"; import { makeReadFilteredView } from "./read-filter"; export function useShape(shapeType: unknown, scope: unknown): unknown { const set = getConfig().useShape(shapeType, scope) as object; - const grantOf = getGrantOf(); - if (!grantOf) return set; // no policy configured → passthrough (filter inert) - return makeReadFilteredView(set, grantOf, getCurrentUser); + const caps = getCaps(); + if (!caps.hasReadPolicy()) return set; // no policy configured → passthrough + return makeReadFilteredView(set, caps, getCurrentUser); } diff --git a/packages/client/test/access.test.ts b/packages/client/test/access.test.ts deleted file mode 100644 index 6bf63b8..0000000 --- a/packages/client/test/access.test.ts +++ /dev/null @@ -1,30 +0,0 @@ -import { test, expect } from "bun:test"; -import { canRead, canWrite, defaultGrant, grantRead } from "../src/access"; - -test("public docs are readable by anyone, even anonymous", () => { - const g = defaultGrant("public", "alice"); - expect(canRead(g, null)).toBe(true); - expect(canRead(g, "bob")).toBe(true); -}); - -test("protected docs: owner + explicitly granted principals only", () => { - let g = defaultGrant("protected", "alice"); - expect(canRead(g, "alice")).toBe(true); - expect(canRead(g, "bob")).toBe(false); - g = grantRead(g, "bob"); // e.g. bob becomes a connection of alice - expect(canRead(g, "bob")).toBe(true); -}); - -test("private docs: owner only", () => { - const g = defaultGrant("private", "alice"); - expect(canRead(g, "alice")).toBe(true); - expect(canRead(g, "bob")).toBe(false); - expect(canRead(g, null)).toBe(false); -}); - -test("write is restricted to the write grant", () => { - const g = defaultGrant("public", "alice"); - expect(canWrite(g, "alice")).toBe(true); - expect(canWrite(g, "bob")).toBe(false); - expect(canWrite(g, null)).toBe(false); -}); diff --git a/packages/client/test/caps.test.ts b/packages/client/test/caps.test.ts new file mode 100644 index 0000000..5a6b727 --- /dev/null +++ b/packages/client/test/caps.test.ts @@ -0,0 +1,50 @@ +import { test, expect } from "bun:test"; +import { CapRegistry } from "../src/caps"; + +test("public documents are readable by anyone, even anonymous", () => { + const caps = new CapRegistry(); + caps.open("did:ng:o:pub", "public", "alice"); + expect(caps.canRead("did:ng:o:pub", null)).toBe(true); + expect(caps.canRead("did:ng:o:pub", "bob")).toBe(true); +}); + +test("protected documents: owner + explicitly granted principals only", () => { + const caps = new CapRegistry(); + caps.open("did:ng:o:prot", "protected", "alice"); + expect(caps.canRead("did:ng:o:prot", "alice")).toBe(true); + expect(caps.canRead("did:ng:o:prot", "bob")).toBe(false); + caps.grantRead("did:ng:o:prot", "bob"); // bob becomes a connection of alice + expect(caps.canRead("did:ng:o:prot", "bob")).toBe(true); +}); + +test("private documents: owner only", () => { + const caps = new CapRegistry(); + caps.open("did:ng:o:priv", "private", "alice"); + expect(caps.canRead("did:ng:o:priv", "alice")).toBe(true); + expect(caps.canRead("did:ng:o:priv", "bob")).toBe(false); + expect(caps.canRead("did:ng:o:priv", null)).toBe(false); +}); + +test("write is restricted to write-cap holders; the creator always holds it", () => { + const caps = new CapRegistry(); + caps.open("did:ng:o:pub", "public", "alice"); + expect(caps.canWrite("did:ng:o:pub", "alice")).toBe(true); + expect(caps.canWrite("did:ng:o:pub", "bob")).toBe(false); + expect(caps.canWrite("did:ng:o:pub", null)).toBe(false); +}); + +test("holding a document's cap does NOT grant another document (no inheritance)", () => { + const caps = new CapRegistry(); + caps.grantRead("did:ng:o:doc1", "alice"); + expect(caps.canRead("did:ng:o:doc1", "alice")).toBe(true); + expect(caps.canRead("did:ng:o:doc2", "alice")).toBe(false); // separate repo, separate cap +}); + +test("governsRead / hasReadPolicy distinguish governed from ungoverned documents", () => { + const caps = new CapRegistry(); + expect(caps.hasReadPolicy()).toBe(false); + caps.grantRead("did:ng:o:doc1", "alice"); + expect(caps.hasReadPolicy()).toBe(true); + expect(caps.governsRead("did:ng:o:doc1")).toBe(true); + expect(caps.governsRead("did:ng:o:unknown")).toBe(false); // not declared → not enforced +}); diff --git a/packages/client/test/read-filter.test.ts b/packages/client/test/read-filter.test.ts index 334f084..f3bd045 100644 --- a/packages/client/test/read-filter.test.ts +++ b/packages/client/test/read-filter.test.ts @@ -1,38 +1,47 @@ import { test, expect } from "bun:test"; import { filterReadable, makeReadFilteredView } from "../src/read-filter"; -import type { Grant } from "../src/types"; +import { CapRegistry } from "../src/caps"; -interface Item { id: string; grant?: Grant } -const grantOf = (i: unknown): Grant | undefined => (i as Item).grant; +// The access unit is the DOCUMENT (an item's `@graph` = the repo it lives in), +// not the item. Items here carry `@graph`; caps are granted per document. +interface Item { id: string; "@graph"?: string } -const A: Item = { id: "a", grant: { read: ["alice"], write: ["alice"] } }; -const PUB: Item = { id: "p", grant: { read: ["public"], write: ["bob"] } }; -const NOGRANT: Item = { id: "n" }; // no grant → always kept +const PRIV: Item = { id: "a", "@graph": "did:ng:o:alice" }; // alice's doc +const PUB: Item = { id: "p", "@graph": "did:ng:o:public" }; // public doc +const UNGOV: Item = { id: "n", "@graph": "did:ng:o:other" }; // doc under no policy +const NOGRAPH: Item = { id: "x" }; // no document → kept -test("filterReadable keeps public, owner-readable, and ungranted items", () => { - const items = [A, PUB, NOGRANT]; - expect(filterReadable(items, grantOf, "alice").map(i => (i as Item).id)).toEqual(["a", "p", "n"]); - expect(filterReadable(items, grantOf, "bob").map(i => (i as Item).id)).toEqual(["p", "n"]); - expect(filterReadable(items, grantOf, null).map(i => (i as Item).id)).toEqual(["p", "n"]); +function caps(): CapRegistry { + const c = new CapRegistry(); + c.grantRead("did:ng:o:alice", "alice"); + c.makePublic("did:ng:o:public"); + return c; +} + +test("filterReadable keeps public, cap-held, ungoverned and graphless items", () => { + const items = [PRIV, PUB, UNGOV, NOGRAPH]; + expect(filterReadable(items, caps(), "alice").map(i => (i as Item).id)).toEqual(["a", "p", "n", "x"]); + expect(filterReadable(items, caps(), "bob").map(i => (i as Item).id)).toEqual(["p", "n", "x"]); + expect(filterReadable(items, caps(), null).map(i => (i as Item).id)).toEqual(["p", "n", "x"]); }); test("makeReadFilteredView filters iteration/size, reflects the current user", () => { - const set = new Set([A, PUB, NOGRANT]); + const set = new Set([PRIV, PUB, UNGOV, NOGRAPH]); let user: string | null = "bob"; - const view = makeReadFilteredView(set, grantOf, () => user); + const view = makeReadFilteredView(set, caps(), () => user); - expect([...view].map(i => i.id)).toEqual(["p", "n"]); - expect(view.size).toBe(2); + expect([...view].map(i => i.id)).toEqual(["p", "n", "x"]); + expect(view.size).toBe(3); user = "alice"; // read lazily → view updates without rewrapping - expect([...view].map(i => i.id)).toEqual(["a", "p", "n"]); - expect(view.size).toBe(3); + expect([...view].map(i => i.id)).toEqual(["a", "p", "n", "x"]); + expect(view.size).toBe(4); }); test("makeReadFilteredView forwards mutations and membership to the target", () => { const set = new Set([PUB]); - const view = makeReadFilteredView(set, grantOf, () => "bob"); - const C: Item = { id: "c", grant: { read: ["bob"], write: ["bob"] } }; + const view = makeReadFilteredView(set, caps(), () => "bob"); + const C: Item = { id: "c", "@graph": "did:ng:o:public" }; view.add(C); expect(set.has(C)).toBe(true); // mutation reached the real set @@ -43,8 +52,8 @@ test("makeReadFilteredView forwards mutations and membership to the target", () }); test("forEach is filtered too", () => { - const set = new Set([A, PUB]); + const set = new Set([PRIV, PUB]); const seen: string[] = []; - makeReadFilteredView(set, grantOf, () => "bob").forEach((i) => seen.push((i as Item).id)); + makeReadFilteredView(set, caps(), () => "bob").forEach((i) => seen.push((i as Item).id)); expect(seen).toEqual(["p"]); });