keri-ts 2.1.0 → 2.2.0

package/README.md

@@ -13,9 +13,20 @@ npm install keri-ts
 
 - default import: browser-safe core/types surface
 - `keri-ts/runtime`: explicit non-browser-safe runtime surface
-- `keri-ts/db`: explicit LMDB-backed storage surface
+- `keri-ts/db`: backend-neutral storage surface
+- `keri-ts/db/lmdb`: native LMDB storage backend
+- `keri-ts/db/indexeddb`: browser IndexedDB storage backend (`indexedDbOpener`).
+  The opener is single-writer by default: its first store takes a Web Locks lock per
+  store identity (`base`, `name`, `temp`), shared by every family it creates and
+  released when the last closes. A second opener or tab gets `StoreLockHeldError`,
+  and an engine without `navigator.locks` gets `StoreLockUnsupportedError`. Pass
+  `unsafeSkipStoreLock: true` only when another mechanism serializes writers (for
+  example a SharedWorker owner); `locks` injects a lock manager for tests
+- `keri-ts/runtime/web`: browser host concerns (`barrierHttpClient` output barrier,
+  `acquireStoreLock` and `storeLockKey` for hosts that compose stores themselves,
+  `requestPersistentStorage`)
 
-Those three entrypoints are the general library surfaces. `keri-ts/cli` is the
+These entrypoints are the general library surfaces. `keri-ts/cli` is the
 separate command-helper boundary used by Tufa. Runnable CLI/server ownership
 lives in `@keri-ts/tufa`.
 
@@ -25,6 +36,23 @@ implementation-module exports do not automatically become package API. npm deep
 imports such as `keri-ts/app/...` and `keri-ts/core/...` are not supported. Import
 runtime operations from `keri-ts/runtime` and storage from `keri-ts/db`.
 
+## Browser bundles
+
+`keri-ts`, `keri-ts/runtime`, `keri-ts/runtime/web`, `keri-ts/db` and
+`keri-ts/db/indexeddb` carry a
+`browser` export condition that resolves to a build of the same entrypoint
+without the Node polyfill import, so bundlers targeting the browser reach no
+`node:` module. `keri-ts/cli`, `keri-ts/db/lmdb` and `keri-ts/runtime/node` are
+Node-only and have no `browser` condition. The `import` and `types` targets are
+unchanged.
+
+The graph includes `cesr-ts`, which uses a top-level `await` to instantiate its
+Argon2 WebAssembly, so bundle as ESM targeting ES2022 or later. See the
+`cesr-ts` README for the Content Security Policy note.
+
+esbuild also fails on `effection`'s `main()` runner, which lazily imports
+`node:process`; mark `node:process` external. Vite and webpack need nothing.
+
 ## Maintainer Docs
 
 - `docs/ARCHITECTURE_MAP.md`: package and module ownership map

package/esm/keri/npm/src/acdc/authoring.js

@@ -0,0 +1,195 @@
+/**
+ * Finite ACDC v2 registry authoring: stage, anchor and update protocol cores.
+ *
+ * Existing engines own acceptance and receipt authentication; this class only
+ * sequences them for one local individual issuer. It reads and writes no
+ * credential inventory: embedders that keep issued or held records wrap it
+ * (the wallet's `WalletAuthor` adds `issue` and `revoke`). Private derivation
+ * requires a `RegistryCustody`, whose coordinate store the embedder supplies.
+ */
+import { bytesEqual, makeBlindState } from "cesr-ts";
+import { isLocalGroupHab } from "../app/multisig/group-members.js";
+import { ValidationError } from "../core/errors.js";
+import { acdcmap, blindate } from "./messaging.js";
+import { matchesRegistrySeal } from "./regeventing.js";
+import { validateSchema as validateAcdcSchema } from "./scheming.js";
+/** Borrow the actual registry environment and receipt collector; acquire no handles or workers. */
+export class RegistryAuthor {
+    constructor(rgy, receiptor, custody) {
+        Object.defineProperty(this, "rgy", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: rgy
+        });
+        Object.defineProperty(this, "receiptor", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: receiptor
+        });
+        Object.defineProperty(this, "custody", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: custody
+        });
+        if (receiptor.hby !== rgy.hby) {
+            throw new ValidationError("Authoring requires the registry environment's actual receipt owner.");
+        }
+        if (custody && (custody.options.hby !== rgy.hby || custody.options.registry.baser !== rgy.baser)) {
+            throw new ValidationError("Authoring custody must use this registry environment's actual owners.");
+        }
+    }
+    /** Resolve the actual local registry; staging supports groups while signing methods enforce their owner. */
+    registry(name, controller) {
+        const registry = this.rgy.registryByName(name);
+        if (!registry || registry.hab.pre !== controller) {
+            throw new ValidationError("Unknown registry or different controller.");
+        }
+        return registry;
+    }
+    /** Signing belongs either to this individual owner or to explicit group approval, never a staging flag. */
+    individual(reg) {
+        if (isLocalGroupHab(this.rgy.hby, reg.hab)) {
+            throw new ValidationError("ACDC v2 group authoring requires member approval.");
+        }
+    }
+    /** Idempotently stage an alias, then return only its exact accepted inception. */
+    *incept(name, controller, auths) {
+        const hab = this.rgy.hby.habs.get(controller);
+        if (!hab || isLocalGroupHab(this.rgy.hby, hab)) {
+            throw new ValidationError("ACDC v2 inception requires a local individual controller.");
+        }
+        const reg = this.rgy.registryByName(name) ?? this.rgy.makeRegistry(name, controller);
+        this.registry(name, controller);
+        const event = reg.store.event(reg.regk);
+        yield* this.anchor(reg, event, auths);
+        return event;
+    }
+    /** Construct the issuer's credential using the existing ACDC v2 finite builder. */
+    create(reg, options) {
+        this.registry(reg.name, reg.hab.pre);
+        return acdcmap(reg.hab.pre, { ...options, regid: reg.regk });
+    }
+    /** Stage one BUP state advance, preserving an exact pending retry and its opening. Never author historical upd. */
+    stage(reg, acdc, state, options = {}) {
+        return this.stageState(reg, acdc, state, options);
+    }
+    /** Share validation and exact pending-next reuse; only the concrete revocation ensure operation can reuse an accepted head. */
+    stageState(reg, acdc, state, options, ensureRevoked = false) {
+        this.registry(reg.name, acdc.issuer);
+        if (!acdc.verify() || acdc.regid !== reg.regk) {
+            throw new ValidationError("Credential does not match this registry.");
+        }
+        const schema = validateAcdcSchema(acdc, this.rgy.hby.db);
+        if (schema.kind !== "valid") {
+            throw new ValidationError(schema.kind === "missing" ? `Missing ACDC schema: ${schema.said}` : schema.reason);
+        }
+        const head = reg.store.headEvent(reg.regk);
+        if (!head || head.ilk === "upd")
+            throw new ValidationError("An accepted ACDC v2 registry head is required.");
+        if (options.public && options.boundEvent) {
+            throw new ValidationError("Public opening cannot use private bound coordinates.");
+        }
+        if (!options.public && !this.custody) {
+            throw new ValidationError("Derived authoring requires provisioned registry custody.");
+        }
+        if (!options.public && this.custody.options.hab !== reg.hab) {
+            throw new ValidationError("Derived authoring requires the registry habitat's custody.");
+        }
+        const sn = Number(BigInt(`0x${head.sad.n}`));
+        if (!Number.isSafeInteger(sn + 1))
+            throw new ValidationError("Registry ordinal is not representable.");
+        let bound;
+        if (options.boundEvent) {
+            const issuee = acdc.issuee, db = this.rgy.hby.db;
+            const event = issuee ? db.getEvtSerder(issuee, options.boundEvent) : null;
+            if (!event || event.sn === null || !Number.isSafeInteger(event.sn)
+                || db.kels.getLast(issuee, event.sn) !== event.said || !db.fullyWitnessed(event)) {
+                throw new ValidationError("Bound update requires an exact accepted witnessed Issuee event.");
+            }
+            bound = { bsn: event.sn, bd: event.said };
+        }
+        const derive = (ordinal) => options.public
+            ? makeBlindState({ sn: ordinal, acdc: acdc.said, state })
+            : this.custody.derive(reg.regk, ordinal, acdc.said, state, bound ? { bound: true, ...bound } : {});
+        const matches = (event, opening) => event.ilk === "bup" && event.sad.b === opening.d.nonce && opening.td.nonce === acdc.said
+            && opening.ts.label === state;
+        const pending = [...reg.store.baser.evts.getTopItemIter()].map(([, event]) => event).filter((event) => event.regid === reg.regk && event.sad.n === (sn + 1).toString(16));
+        if (pending.length) {
+            const event = pending[0], opening = options.public ? reg.store.publicOpening(event.said) : derive(sn + 1);
+            if (pending.length !== 1 || !opening || !matches(event, opening) || event.sad.p !== head.said) {
+                throw new ValidationError("Registry has a different pending update.");
+            }
+            if (!options.public)
+                this.custody.retainDerivedUpdate(event, opening);
+            return { event, opening };
+        }
+        if (ensureRevoked && sn && head.ilk === "bup") {
+            const published = reg.store.publicOpening(head.said);
+            const opening = options.public ? published : derive(sn);
+            if (opening && matches(head, opening) && (!options.public || published)) {
+                if (!options.public)
+                    this.custody.retainDerivedUpdate(head, opening);
+                return { event: head, opening };
+            }
+        }
+        if (bound && this.rgy.hby.db.getKever(acdc.issuee)?.serder.said !== bound.bd) {
+            throw new ValidationError("New bound update must reference the known current Issuee event.");
+        }
+        const opening = derive(sn + 1), event = blindate(reg.regk, head.said, opening.d.nonce, { sn: sn + 1, stamp: options.stamp });
+        if (!options.public)
+            this.custody.retainDerivedUpdate(event, opening);
+        reg.store.baser.transaction(() => {
+            reg.store.putEvent(event);
+            if (options.public)
+                reg.store.retainOpening(event, opening);
+            const decision = reg.processEvent(event);
+            if (decision.kind === "reject")
+                throw new ValidationError(`Registry update rejected: ${decision.reason}`);
+        });
+        return { event, opening };
+    }
+    /** Advance one explicit state through real anchoring; staging is never reported as accepted. */
+    *update(reg, acdc, state, options = {}) {
+        this.individual(reg);
+        const { event } = this.stage(reg, acdc, state, options);
+        yield* this.anchor(reg, event, options.auths);
+        return event;
+    }
+    /** Reuse the current branch's already signed seal even before receipts; no extra anchor merely to poll. */
+    *anchor(reg, event, auths) {
+        this.registry(reg.name, reg.hab.pre);
+        this.individual(reg);
+        const ordinal = Number(BigInt(`0x${event.sad.n}`));
+        const accepted = reg.store.seqEvent(reg.regk, ordinal);
+        if (accepted && bytesEqual(accepted.raw, event.raw))
+            return;
+        const hab = reg.hab;
+        let current = hab.kever.serder, anchor = null;
+        while (current) {
+            if (current.seals.some((seal) => matchesRegistrySeal(seal, event)))
+                anchor = current;
+            const prior = current.prior ? hab.db.getEvtSerder(hab.pre, current.prior) : null;
+            if (!prior || prior.sn !== current.sn - 1)
+                break;
+            current = prior;
+        }
+        if (!anchor) {
+            const data = [{ i: reg.regk, s: event.sad.n, d: event.said }];
+            if (hab.kever.estOnly)
+                hab.rotate({ data });
+            else
+                hab.interact({ data });
+            anchor = hab.kever.serder;
+        }
+        yield* this.receiptor.receipt(hab.pre, { sn: anchor.sn, allowTcp: true, auths });
+        this.rgy.hby.kevery.processEscrows();
+        reg.processEscrows();
+        const exact = reg.store.seqEvent(reg.regk, ordinal);
+        if (!exact || !bytesEqual(exact.raw, event.raw)) {
+            throw new ValidationError("ACDC v2 registry event remains pending authenticated anchor receipts.");
+        }
+    }
+}

package/esm/keri/npm/src/acdc/custody.js

@@ -0,0 +1,164 @@
+/**
+ * Registry blind derivation over the Keeper's registry root.
+ *
+ * Issuing a blinded (BUP) registry update needs a deterministic opening. The
+ * root salt stays in the Keeper; this core derives openings from it and keeps
+ * only the public, event-specific coordinates in a `DerivedUpdateStore`. A
+ * runtime defaults to {@link BaserDerivedUpdateStore}; a wallet backs the port
+ * with its own table. The core opens no database of its own.
+ */
+import { bytesEqual, makeBlindState, makeBoundState, MtrDex, Salter } from "cesr-ts";
+import { ValidationError } from "../core/errors.js";
+import { DerivedUpdateRecord } from "../core/records.js";
+import { vetBlind } from "./regeventing.js";
+/** Process-local store for a CLI or tests; a wallet backs the port with its own durable table. */
+export class MemoryDerivedUpdateStore {
+    constructor() {
+        Object.defineProperty(this, "rows", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: new Map()
+        });
+    }
+    get(event) {
+        return this.rows.get(event) ?? null;
+    }
+    pin(event, value) {
+        this.rows.set(event, structuredClone(value));
+    }
+}
+/**
+ * Derivation coordinates kept in a registry environment's own database (`RegBaser.dvus`). The default of a
+ * runtime that supplies no store, so a server agent keeps them durably beside the registry events they
+ * describe. A wallet with its own table still passes that instead.
+ */
+export class BaserDerivedUpdateStore {
+    constructor(baser) {
+        Object.defineProperty(this, "baser", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: baser
+        });
+    }
+    get(event) {
+        const row = this.baser.dvus.get([event]);
+        return row ? { credential: row.credential, state: row.state, bound: row.bound } : null;
+    }
+    pin(event, value) {
+        this.baser.dvus.pin([event], new DerivedUpdateRecord(structuredClone(value)));
+    }
+}
+/** Explicit capability over a local habitat's Keeper root and accepted public registry evidence. */
+export class RegistryCustody {
+    /** Borrow owners only; construction loads no encrypted row. */
+    constructor(options) {
+        Object.defineProperty(this, "options", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: options
+        });
+        this.owner();
+    }
+    /** Bind the actual local habitat and its key owners, never an AID label alone. */
+    owner() {
+        const { hby, hab } = this.options;
+        if (hby.habs.get(hab.pre) !== hab || hab.ks !== hby.ks || hab.mgr !== hby.mgr || hab.db !== hby.db) {
+            throw new ValidationError("Custody requires the actual local habitat and Keeper owners");
+        }
+    }
+    /** Load only this habitat's Keeper root; possession confers no protocol authority. */
+    load(registry) {
+        this.owner();
+        const root = this.options.hby.mgr.getRegistryRoot(this.options.hab.pre, registry);
+        if (!root)
+            throw new ValidationError("Registry custody is not provisioned");
+        return root;
+    }
+    /** Provision an issuer-selected root once, refusing replacement behind opaque accepted history. */
+    createCustody(registry) {
+        this.owner();
+        const { hby, hab } = this.options;
+        if (!hby.mgr.aeid || !hby.mgr.seed) {
+            throw new ValidationError("Private credential custody requires an authenticated encrypted Keeper");
+        }
+        if (hby.mgr.getRegistryRoot(hab.pre, registry))
+            return { registry };
+        const rip = this.options.registry.seqEvent(registry, 0);
+        if (!rip || rip.issuer !== hab.pre) {
+            throw new ValidationError("New custody requires the accepted registry issuer's actual local habitat");
+        }
+        // Existing clone validation authenticates public openings without another parser or proof algorithm.
+        for (const _ of this.options.registry.cloneTelIter(registry)) { /* consume the accepted public prefix */ }
+        const head = this.options.registry.headEvent(registry);
+        const last = head ? Number(BigInt(`0x${head.sad.n}`)) : 0;
+        if (!Number.isSafeInteger(last))
+            throw new ValidationError("Accepted registry ordinal is not representable");
+        for (let ordinal = 1; ordinal <= last; ordinal++) {
+            const event = this.options.registry.seqEvent(registry, ordinal);
+            if (!event)
+                throw new ValidationError("Accepted registry history is incomplete");
+            if (event.ilk === "bup" && !this.options.registry.opening(event.said)) {
+                throw new ValidationError("Local custody is missing for blinded registry history; salt cannot be recreated");
+            }
+        }
+        hby.mgr.putRegistryRoot(hab.pre, registry, new Salter({ code: MtrDex.Salt_128, raw: crypto.getRandomValues(new Uint8Array(16)) }));
+        return { registry };
+    }
+    /** Derive a candidate only; consumers still authenticate its exact accepted event and bound KEL reference. */
+    derive(registry, ordinal, credential, state, options = {}) {
+        if ((typeof ordinal !== "bigint" && (typeof ordinal !== "number" || !Number.isSafeInteger(ordinal))) || ordinal < 1) {
+            throw new ValidationError("Update ordinal must be a positive integer");
+        }
+        const root = this.load(registry);
+        const values = { salt: root.qb64, sn: ordinal, tier: "low", acdc: credential, state };
+        return options.bound
+            ? makeBoundState({ ...values, bsn: options.bsn ?? 0, bd: options.bd ?? "" })
+            : makeBlindState(values);
+    }
+    /** Persist exact nonsecret coordinates before processing/anchoring a newly derived BUP. */
+    retainDerivedUpdate(event, opening) {
+        if (event.ilk !== "bup" || !event.verify() || !vetBlind(opening, event.sad.b)) {
+            throw new ValidationError("Derived update requires its exact authenticated BUP opening");
+        }
+        const value = {
+            credential: opening.td.nonce,
+            state: opening.ts.label,
+            bound: "bn" in opening ? { bn: opening.bn.num.toString(16), bd: opening.bd.nonce } : null,
+        };
+        const old = this.options.store.get(event.said);
+        if (old && JSON.stringify(canonical(old)) !== JSON.stringify(value)) {
+            throw new ValidationError("Different derivation coordinates are already retained for this event");
+        }
+        this.options.store.pin(event.said, value);
+        return value;
+    }
+    /** Reproduce only the exact accepted event, never today's head or a later credential's coordinates. */
+    derivedOpening(event) {
+        if (event.ilk !== "bup" || !event.verify())
+            throw new ValidationError("Exact accepted blinded update is required");
+        const ordinal = BigInt(`0x${event.sad.n}`);
+        if (!Number.isSafeInteger(Number(ordinal))) {
+            throw new ValidationError("Accepted registry ordinal is not representable");
+        }
+        const stored = event.regid ? this.options.registry.seqEvent(event.regid, Number(ordinal)) : null;
+        if (!stored || !bytesEqual(stored.raw, event.raw)) {
+            throw new ValidationError("Exact accepted registry event is required");
+        }
+        const value = this.options.store.get(event.said);
+        if (!value)
+            throw new ValidationError("Exact derived update coordinates are unavailable");
+        const opening = this.derive(event.regid, ordinal, value.credential, value.state, value.bound ? { bound: true, bsn: BigInt(`0x${value.bound.bn}`), bd: value.bound.bd } : {});
+        if (!vetBlind(opening, event.sad.b)) {
+            throw new ValidationError("Derived opening does not match the exact accepted event");
+        }
+        return opening;
+    }
+}
+/** Fix field order so equality does not depend on how a store hydrated the record. */
+function canonical(value) {
+    const { credential, state, bound } = value;
+    return { credential, state, bound: bound ? { bn: bound.bn, bd: bound.bd } : null };
+}