feat(client): generic shared-wallet shim surface (docs/storeRegistry/isolation/accounts)
Port the shared-wallet shim mechanics from the Festipod app into the
generic @ng-eventually/client library — zero app-specific knowledge, the
consumer injects the domain (entity->scope mapping, connections, storage).
New namespaces exposed from src/index.ts:
- docs docCreate/sparqlUpdate/sparqlQuery via the REAL injected `ng`
(getConfig().ng), never the public makeNg proxy — the JS-over-
iframe double proxy breaks doc_create postMessage marshaling
(DataCloneError). Validated hard constraint.
- storeRegistry generic (account,scope)->NURI resolver, createEntityDoc/
listEntityDocs + per-scope index, sharedWalletShim in the
private_store, cache. Consumer wiring injected via
configureStoreRegistry({ getSession, normalizeUser }).
- isolation pure applyIsolation (public=all / protected=owner+connections
/ private=owner); accessors + connection graph injected.
- accounts AccountStore (localStorage-backed faux login, storage injected)
+ normalizeUsername. React wrapper intentionally NOT ported.
polyfill.ts gains configureStoreRegistry/getStoreRegistryDeps + resetConfig.
36/36 bun test, tsc --noEmit rc=0.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This commit is contained in:
Sylvain Duchesne
@@ -0,0 +1,84 @@
|
||||
import { test, expect } from "bun:test";
|
||||
import {
|
||||
AccountStore,
|
||||
browserAccountStore,
|
||||
normalizeUsername,
|
||||
ACCOUNT_STORAGE_KEY,
|
||||
type AccountStorage,
|
||||
} from "../src/accounts";
|
||||
|
||||
// In-memory fake of the Storage subset — keeps this framework/DOM-agnostic.
|
||||
function fakeStorage(): AccountStorage & { map: Map<string, string> } {
|
||||
const map = new Map<string, string>();
|
||||
return {
|
||||
map,
|
||||
getItem: (k) => (map.has(k) ? (map.get(k) as string) : null),
|
||||
setItem: (k, v) => void map.set(k, v),
|
||||
removeItem: (k) => void map.delete(k),
|
||||
};
|
||||
}
|
||||
|
||||
test("normalizeUsername: strips leading @, trims, lowercases", () => {
|
||||
expect(normalizeUsername("marie")).toBe("marie");
|
||||
expect(normalizeUsername("@Marie")).toBe("marie");
|
||||
expect(normalizeUsername(" @@MARIE ")).toBe("marie");
|
||||
expect(normalizeUsername(null)).toBe("");
|
||||
expect(normalizeUsername(undefined)).toBe("");
|
||||
});
|
||||
|
||||
test("AccountStore: login persists a trimmed username, get reads it back", () => {
|
||||
const s = fakeStorage();
|
||||
const store = new AccountStore(s);
|
||||
expect(store.get()).toBeNull();
|
||||
|
||||
expect(store.login(" Marie ")).toBe("Marie"); // trimmed, NOT normalized (display form)
|
||||
expect(store.get()).toBe("Marie");
|
||||
expect(s.map.get(ACCOUNT_STORAGE_KEY)).toBe("Marie");
|
||||
});
|
||||
|
||||
test("AccountStore: blank login is ignored, keeps the previous value", () => {
|
||||
const store = new AccountStore(fakeStorage());
|
||||
store.login("bob");
|
||||
expect(store.login(" ")).toBe("bob");
|
||||
expect(store.get()).toBe("bob");
|
||||
});
|
||||
|
||||
test("AccountStore: logout clears the username (no throw)", () => {
|
||||
const store = new AccountStore(fakeStorage());
|
||||
store.login("bob");
|
||||
store.logout();
|
||||
expect(store.get()).toBeNull();
|
||||
});
|
||||
|
||||
test("AccountStore: null storage degrades to non-persisting (SSR-safe)", () => {
|
||||
const store = new AccountStore(null);
|
||||
expect(store.get()).toBeNull();
|
||||
expect(store.login("bob")).toBe("bob"); // returns the value, just doesn't persist
|
||||
expect(store.get()).toBeNull();
|
||||
store.logout(); // no throw
|
||||
});
|
||||
|
||||
test("AccountStore: swallows storage errors on read and write", () => {
|
||||
const throwing: AccountStorage = {
|
||||
getItem: () => {
|
||||
throw new Error("boom");
|
||||
},
|
||||
setItem: () => {
|
||||
throw new Error("boom");
|
||||
},
|
||||
removeItem: () => {
|
||||
throw new Error("boom");
|
||||
},
|
||||
};
|
||||
const store = new AccountStore(throwing);
|
||||
expect(store.get()).toBeNull(); // read error swallowed → null
|
||||
expect(() => store.login("bob")).not.toThrow();
|
||||
expect(() => store.logout()).not.toThrow();
|
||||
});
|
||||
|
||||
test("browserAccountStore returns a working store (uses global localStorage if present)", () => {
|
||||
const store = browserAccountStore("ng-eventually.test.account");
|
||||
expect(store).toBeInstanceOf(AccountStore);
|
||||
// Behaves regardless of environment: login returns the value.
|
||||
expect(store.login("zoe")).toBe("zoe");
|
||||
});
|
||||
@@ -0,0 +1,91 @@
|
||||
import { test, expect, mock } from "bun:test";
|
||||
import { docCreate, sparqlUpdate, sparqlQuery } from "../src/docs";
|
||||
import * as ngProxy from "../src/ng-proxy";
|
||||
|
||||
// NOTE ORDER: the "not configured → throw" case MUST run before any configure()
|
||||
// call, because configure() sets a module-level singleton with no public reset.
|
||||
|
||||
test("throws a clear error when configure() was not called", async () => {
|
||||
await expect(docCreate("sid", "Graph", "data:graph", "store")).rejects.toThrow(
|
||||
/configure\(\) must be called before use/,
|
||||
);
|
||||
await expect(sparqlUpdate("sid", "INSERT DATA {}")).rejects.toThrow(
|
||||
/configure\(\) must be called before use/,
|
||||
);
|
||||
await expect(sparqlQuery("sid", "SELECT * {}")).rejects.toThrow(
|
||||
/configure\(\) must be called before use/,
|
||||
);
|
||||
});
|
||||
|
||||
// From here on, a fake real `ng` is injected via configure().
|
||||
import { configure } from "../src/polyfill";
|
||||
|
||||
function fakeNg() {
|
||||
return {
|
||||
doc_create: mock(async (..._a: unknown[]) => "did:ng:o:new-doc"),
|
||||
sparql_update: mock(async (..._a: unknown[]) => undefined),
|
||||
sparql_query: mock(async (..._a: unknown[]) => ({ results: { bindings: [] } })),
|
||||
// A sentinel: makeNg(), if ever used, would `.bind` and call THIS through
|
||||
// the JS Proxy. We assert the primitives call the raw fns above directly.
|
||||
};
|
||||
}
|
||||
|
||||
function inject() {
|
||||
const ng = fakeNg();
|
||||
configure({ ng: ng as any, useShape: (() => {}) as any });
|
||||
return ng;
|
||||
}
|
||||
|
||||
test("docCreate calls the real injected ng.doc_create with the exact args", async () => {
|
||||
const ng = inject();
|
||||
const nuri = await docCreate("sid-1", "Graph", "data:graph", "store", undefined);
|
||||
expect(nuri).toBe("did:ng:o:new-doc");
|
||||
expect(ng.doc_create).toHaveBeenCalledTimes(1);
|
||||
expect(ng.doc_create.mock.calls[0]).toEqual(["sid-1", "Graph", "data:graph", "store", undefined]);
|
||||
});
|
||||
|
||||
test("sparqlUpdate forwards (sessionId, query, anchor) to the real ng.sparql_update", async () => {
|
||||
const ng = inject();
|
||||
await sparqlUpdate("sid-2", "INSERT DATA { GRAPH <did:ng:o:a> { <s> <p> <o> } }", "did:ng:o:a");
|
||||
expect(ng.sparql_update).toHaveBeenCalledTimes(1);
|
||||
expect(ng.sparql_update.mock.calls[0]).toEqual([
|
||||
"sid-2",
|
||||
"INSERT DATA { GRAPH <did:ng:o:a> { <s> <p> <o> } }",
|
||||
"did:ng:o:a",
|
||||
]);
|
||||
});
|
||||
|
||||
test("sparqlUpdate passes anchor=undefined when omitted", async () => {
|
||||
const ng = inject();
|
||||
await sparqlUpdate("sid-3", "INSERT DATA {}");
|
||||
expect(ng.sparql_update.mock.calls[0]).toEqual(["sid-3", "INSERT DATA {}", undefined]);
|
||||
});
|
||||
|
||||
test("sparqlQuery forwards (sessionId, query, base, anchor) and returns the raw result", async () => {
|
||||
const ng = inject();
|
||||
const res = await sparqlQuery("sid-4", "SELECT ?e { GRAPH <g> { ?s ?p ?e } }", undefined, "did:ng:o:g");
|
||||
expect(res).toEqual({ results: { bindings: [] } });
|
||||
expect(ng.sparql_query).toHaveBeenCalledTimes(1);
|
||||
expect(ng.sparql_query.mock.calls[0]).toEqual([
|
||||
"sid-4",
|
||||
"SELECT ?e { GRAPH <g> { ?s ?p ?e } }",
|
||||
undefined,
|
||||
"did:ng:o:g",
|
||||
]);
|
||||
});
|
||||
|
||||
test("the primitives do NOT route through the public ng proxy (makeNg)", async () => {
|
||||
// makeNg builds a JS Proxy over the injected ng. If a primitive went through
|
||||
// it, calls would land on the proxy's `get` trap, not on our raw mock fns.
|
||||
// Spy on makeNg: it must never be invoked by the docs primitives.
|
||||
const spy = mock(ngProxy.makeNg);
|
||||
const ng = inject();
|
||||
await docCreate("sid", "Graph", "data:graph", "store");
|
||||
await sparqlUpdate("sid", "INSERT DATA {}");
|
||||
await sparqlQuery("sid", "SELECT * {}");
|
||||
expect(spy).toHaveBeenCalledTimes(0);
|
||||
// And the raw injected fns were reached directly:
|
||||
expect(ng.doc_create).toHaveBeenCalledTimes(1);
|
||||
expect(ng.sparql_update).toHaveBeenCalledTimes(1);
|
||||
expect(ng.sparql_query).toHaveBeenCalledTimes(1);
|
||||
});
|
||||
@@ -0,0 +1,68 @@
|
||||
import { test, expect } from "bun:test";
|
||||
import {
|
||||
applyIsolation,
|
||||
connectionsFromLinks,
|
||||
visibleSet,
|
||||
isVisible,
|
||||
type IsolationAccessors,
|
||||
} from "../src/isolation";
|
||||
import type { Scope } from "../src/types";
|
||||
|
||||
// Generic item: owner + scope. ZERO domain — the accessors read these fields.
|
||||
interface Item {
|
||||
id: string;
|
||||
owner: string;
|
||||
scope: Scope;
|
||||
}
|
||||
const acc: IsolationAccessors<Item> = { ownerOf: (i) => i.owner, scopeOf: (i) => i.scope };
|
||||
|
||||
// alice —— bob (carol is unconnected)
|
||||
const links = [{ a: "alice", b: "bob" }];
|
||||
const conns = connectionsFromLinks(links);
|
||||
|
||||
test("connectionsFromLinks / visibleSet: self + direct connections, both directions", () => {
|
||||
expect([...conns.neighbors("alice")].sort()).toEqual(["bob"]);
|
||||
expect([...conns.neighbors("bob")].sort()).toEqual(["alice"]);
|
||||
expect([...conns.neighbors("carol")]).toEqual([]);
|
||||
|
||||
expect([...visibleSet("alice", conns)].sort()).toEqual(["alice", "bob"]);
|
||||
expect([...visibleSet("carol", conns)].sort()).toEqual(["carol"]);
|
||||
});
|
||||
|
||||
test("isVisible matrix: public=all, protected=owner+connections, private=owner", () => {
|
||||
const vis = visibleSet("alice", conns); // { alice, bob }
|
||||
// public → everyone, regardless of owner
|
||||
expect(isVisible("public", "carol", "alice", vis)).toBe(true);
|
||||
// protected → owner must be in the visible set
|
||||
expect(isVisible("protected", "bob", "alice", vis)).toBe(true);
|
||||
expect(isVisible("protected", "carol", "alice", vis)).toBe(false);
|
||||
// private → owner must be the current principal
|
||||
expect(isVisible("private", "alice", "alice", vis)).toBe(true);
|
||||
expect(isVisible("private", "bob", "alice", vis)).toBe(false);
|
||||
});
|
||||
|
||||
test("applyIsolation narrows a mixed collection for the current principal", () => {
|
||||
const items: Item[] = [
|
||||
{ id: "e", owner: "carol", scope: "public" }, // public → kept for all
|
||||
{ id: "p1", owner: "alice", scope: "protected" }, // own protected → kept
|
||||
{ id: "p2", owner: "bob", scope: "protected" }, // connection's protected → kept
|
||||
{ id: "p3", owner: "carol", scope: "protected" }, // stranger's protected → dropped
|
||||
{ id: "s1", owner: "alice", scope: "private" }, // own private → kept
|
||||
{ id: "s2", owner: "bob", scope: "private" }, // connection's private → dropped
|
||||
];
|
||||
|
||||
const forAlice = applyIsolation(items, "alice", conns, acc).map((i) => i.id);
|
||||
expect(forAlice).toEqual(["e", "p1", "p2", "s1"]);
|
||||
|
||||
const forCarol = applyIsolation(items, "carol", conns, acc).map((i) => i.id);
|
||||
// carol sees: public + her own protected + her own private
|
||||
expect(forCarol).toEqual(["e", "p3"]);
|
||||
});
|
||||
|
||||
test("applyIsolation with empty principal passes everything through (hydration guard)", () => {
|
||||
const items: Item[] = [
|
||||
{ id: "s1", owner: "alice", scope: "private" },
|
||||
{ id: "p1", owner: "bob", scope: "protected" },
|
||||
];
|
||||
expect(applyIsolation(items, "", conns, acc).map((i) => i.id)).toEqual(["s1", "p1"]);
|
||||
});
|
||||
@@ -0,0 +1,202 @@
|
||||
import { test, expect, mock, beforeEach, afterAll } from "bun:test";
|
||||
import {
|
||||
ensureAccount,
|
||||
allAccounts,
|
||||
loadShim,
|
||||
resolveWriteGraph,
|
||||
resolveReadGraphs,
|
||||
createEntityDoc,
|
||||
listEntityDocs,
|
||||
resetRegistryCache,
|
||||
} from "../src/store-registry";
|
||||
import type { RegistrySession } from "../src/store-registry";
|
||||
import {
|
||||
configure,
|
||||
configureStoreRegistry,
|
||||
resetStoreRegistry,
|
||||
resetConfig,
|
||||
} from "../src/polyfill";
|
||||
|
||||
// This suite injects a fake `ng` via configure(); bun runs test files in a
|
||||
// shared process with a single module singleton, and may run this file BEFORE
|
||||
// docs.test.ts's order-dependent "not configured" guard. Restore the un-
|
||||
// configured state when we're done so that guard still sees a null config.
|
||||
afterAll(() => {
|
||||
resetConfig();
|
||||
resetStoreRegistry();
|
||||
});
|
||||
|
||||
// NOTE ORDER: the "not configured → throw" case MUST run first — configure*()
|
||||
// sets module-level singletons and this suite never fully un-injects the real
|
||||
// `ng` (docs' getConfig has no reset), so we exercise the registry-deps guard.
|
||||
|
||||
test("throws a clear error when configureStoreRegistry() was not called", async () => {
|
||||
resetStoreRegistry();
|
||||
resetRegistryCache();
|
||||
await expect(ensureAccount("alice")).rejects.toThrow(
|
||||
/configureStoreRegistry\(\) must be called before use/,
|
||||
);
|
||||
});
|
||||
|
||||
// --- A stateful fake `ng` that emulates just enough SPARQL over an in-memory
|
||||
// quad store: INSERT DATA parsing + the two SELECT shapes the registry issues.
|
||||
|
||||
interface Quad { g: string; s: string; p: string; o: string }
|
||||
|
||||
function makeFakeNg() {
|
||||
const quads: Quad[] = [];
|
||||
let docCounter = 0;
|
||||
|
||||
const doc_create = mock(async (..._a: unknown[]) => `did:ng:o:doc${++docCounter}`);
|
||||
|
||||
// Parses `INSERT DATA { GRAPH <g> { <s> <p> "o"/<o>/;-lists } }`.
|
||||
const sparql_update = mock(async (...a: unknown[]) => {
|
||||
const query = a[1] as string;
|
||||
const gm = query.match(/GRAPH <([^>]+)>\s*\{([\s\S]*)\}/);
|
||||
if (!gm) return undefined;
|
||||
const g = gm[1]!;
|
||||
const body = gm[2]!;
|
||||
// Subject is the first <...> token in the body.
|
||||
const sm = body.match(/<([^>]+)>/);
|
||||
if (!sm) return undefined;
|
||||
const s = sm[1]!;
|
||||
// Predicate/object pairs: `<p> "o"` or `<p> <o>` (a == rdf:type ignored form
|
||||
// handled as literal-free; here the registry only uses <p> "literal" and
|
||||
// <p> <iri> and `a <type>`).
|
||||
const pairRe = /(?:a|<([^>]+)>)\s+(?:"([^"]*)"|<([^>]+)>)/g;
|
||||
let m: RegExpExecArray | null;
|
||||
// Skip the subject token so we don't treat it as a predicate.
|
||||
const after = body.slice(body.indexOf(sm[0]) + sm[0].length);
|
||||
while ((m = pairRe.exec(after)) !== null) {
|
||||
const p = m[1] ?? "urn:ng-eventually:shim:Account"; // `a` → rdf:type-ish
|
||||
const o = m[2] ?? m[3] ?? "";
|
||||
quads.push({ g, s, p, o });
|
||||
}
|
||||
return undefined;
|
||||
});
|
||||
|
||||
const sparql_query = mock(async (...a: unknown[]) => {
|
||||
const query = a[1] as string;
|
||||
const anchor = a[3] as string | undefined;
|
||||
if (query.includes("<urn:ng-eventually:shim:username>")) {
|
||||
// Account SELECT, scoped to the anchor graph.
|
||||
const bySubject = new Map<string, Record<string, string>>();
|
||||
for (const q of quads) {
|
||||
if (q.g !== anchor) continue;
|
||||
const rec = bySubject.get(q.s) ?? {};
|
||||
if (q.p === "urn:ng-eventually:shim:username") rec.username = q.o;
|
||||
if (q.p === "urn:ng-eventually:shim:docPublic") rec.docPublic = q.o;
|
||||
if (q.p === "urn:ng-eventually:shim:docProtected") rec.docProtected = q.o;
|
||||
if (q.p === "urn:ng-eventually:shim:docPrivate") rec.docPrivate = q.o;
|
||||
bySubject.set(q.s, rec);
|
||||
}
|
||||
const bindings = [...bySubject.values()]
|
||||
.filter((r) => r.username)
|
||||
.map((r) => ({
|
||||
username: { value: r.username! },
|
||||
docPublic: { value: r.docPublic ?? "" },
|
||||
docProtected: { value: r.docProtected ?? "" },
|
||||
docPrivate: { value: r.docPrivate ?? "" },
|
||||
}));
|
||||
return { results: { bindings } };
|
||||
}
|
||||
// Entity-index SELECT: `<index> <contains> ?e` in the anchor graph.
|
||||
const bindings = quads
|
||||
.filter((q) => q.g === anchor && q.p === "urn:ng-eventually:shim:contains")
|
||||
.map((q) => ({ e: { value: q.o } }));
|
||||
return { results: { bindings } };
|
||||
});
|
||||
|
||||
return { doc_create, sparql_update, sparql_query, _quads: quads };
|
||||
}
|
||||
|
||||
const SESSION: RegistrySession = { sessionId: "sid-1", privateStoreId: "PRIV" };
|
||||
|
||||
function inject() {
|
||||
const ng = makeFakeNg();
|
||||
configure({ ng: ng as any, useShape: (() => {}) as any });
|
||||
configureStoreRegistry({
|
||||
getSession: async () => SESSION,
|
||||
normalizeUser: (u) => u.trim().replace(/^@+/, "").toLowerCase(),
|
||||
});
|
||||
resetRegistryCache();
|
||||
return ng;
|
||||
}
|
||||
|
||||
let fake: ReturnType<typeof makeFakeNg>;
|
||||
beforeEach(() => {
|
||||
fake = inject();
|
||||
});
|
||||
|
||||
test("ensureAccount creates 3 scope docs and persists them to the shim", async () => {
|
||||
const rec = await ensureAccount("Alice");
|
||||
expect(rec.username).toBe("Alice");
|
||||
expect(fake.doc_create).toHaveBeenCalledTimes(3);
|
||||
expect(rec.docPublic).toMatch(/^did:ng:o:doc/);
|
||||
expect(rec.docProtected).not.toBe(rec.docPublic);
|
||||
expect(rec.docPrivate).not.toBe(rec.docProtected);
|
||||
// Persisted into the shim anchor graph (did:ng:PRIV).
|
||||
expect(fake.sparql_update.mock.calls[0]![2]).toBe("did:ng:PRIV");
|
||||
});
|
||||
|
||||
test("ensureAccount is idempotent (case/@-insensitive key), no extra docs", async () => {
|
||||
const a = await ensureAccount("Alice");
|
||||
const b = await ensureAccount("@alice");
|
||||
expect(b).toEqual(a);
|
||||
expect(fake.doc_create).toHaveBeenCalledTimes(3); // not 6
|
||||
});
|
||||
|
||||
test("loadShim round-trips a persisted account across a cache reset", async () => {
|
||||
await ensureAccount("Bob");
|
||||
resetRegistryCache(); // force a re-read from the fake store
|
||||
const map = await loadShim();
|
||||
const rec = map.get("bob");
|
||||
expect(rec?.username).toBe("Bob");
|
||||
expect(rec?.docPublic).toMatch(/^did:ng:o:doc/);
|
||||
});
|
||||
|
||||
test("resolveWriteGraph returns the per-scope index doc; resolveReadGraphs fans out", async () => {
|
||||
const rec = await ensureAccount("Carol");
|
||||
expect(await resolveWriteGraph("carol", "protected")).toBe(rec.docProtected);
|
||||
expect(await resolveReadGraphs("public")).toEqual([rec.docPublic]);
|
||||
});
|
||||
|
||||
test("createEntityDoc + listEntityDocs round-trip via the per-scope index", async () => {
|
||||
const rec = await ensureAccount("Dave");
|
||||
const e1 = await createEntityDoc("dave", "public");
|
||||
const e2 = await createEntityDoc("dave", "public");
|
||||
const other = await createEntityDoc("dave", "protected");
|
||||
// Public listing unions dave's public entities only.
|
||||
const pub = await listEntityDocs("public");
|
||||
expect(pub.sort()).toEqual([e1, e2].sort());
|
||||
const prot = await listEntityDocs("protected");
|
||||
expect(prot).toEqual([other]);
|
||||
// The index append targets the account's public index doc.
|
||||
expect(rec.docPublic).toMatch(/^did:ng:o:doc/);
|
||||
});
|
||||
|
||||
test("listEntityDocs fans out across multiple accounts", async () => {
|
||||
await ensureAccount("Eve");
|
||||
await ensureAccount("Frank");
|
||||
const e = await createEntityDoc("eve", "public");
|
||||
const f = await createEntityDoc("frank", "public");
|
||||
expect((await listEntityDocs("public")).sort()).toEqual([e, f].sort());
|
||||
});
|
||||
|
||||
test("allAccounts reflects every ensured account", async () => {
|
||||
await ensureAccount("Gina");
|
||||
await ensureAccount("Hank");
|
||||
const names = (await allAccounts()).map((a) => a.username).sort();
|
||||
expect(names).toEqual(["Gina", "Hank"]);
|
||||
});
|
||||
|
||||
test("normalizeUser defaults to trim when not provided", async () => {
|
||||
const ng = makeFakeNg();
|
||||
configure({ ng: ng as any, useShape: (() => {}) as any });
|
||||
configureStoreRegistry({ getSession: async () => SESSION });
|
||||
resetRegistryCache();
|
||||
const a = await ensureAccount(" Ivy ");
|
||||
const b = await ensureAccount("Ivy"); // trimmed key matches
|
||||
expect(b).toEqual(a);
|
||||
expect(ng.doc_create).toHaveBeenCalledTimes(3);
|
||||
});
|
||||
Reference in New Issue
Block a user