keri-ts 1.0.0 → 2.0.1

package/esm/keri/npm/src/app/{keeping.js → identity/keeping.js}

@@ -1,6 +1,7 @@
-import { decodeB64, Decrypter, Diger, Encrypter, hydrateMatter, intToB64, MtrDex, NumberPrimitive, NumDex, parseMatter, Saider, Salter, Signer, Tiers, Verfer, } from "cesr-ts";
+import { decodeB64, Decrypter, Diger, Encrypter, hydrateMatter, intToB64, MtrDex, NumberPrimitive, NumDex, parseMatter, Prefixer, Saider, Salter, Signer, Tiers, Verfer, } from "cesr-ts";
 import { b } from "cesr-ts";
-import { PubLot } from "../db/keeping.js";
+import { ValidationError } from "../../core/errors.js";
+import { PubLot } from "../../db/keeping.js";
 /**
  * Root key-creation strategy selectors stored in keeper globals.
  *
@@ -207,7 +208,7 @@ function emptyLot(dt = "") {
  * - `randy` and `salty` creator algorithms are live; `group` and `extern`
  *   remain explicit unsupported-algorithm seams
  * - AEID handling now includes real sealed-box encryption for keeper-global
- *   salt, per-prefix salts, and signer seeds, while keeping the encrypted
+ *   salt, per-prefix salts, signer seeds and registry roots, while keeping the encrypted
  *   runtime dependency local to the KERI package instead of CESR
  * - readonly opens intentionally avoid keeper mutation so visibility commands
  *   can inspect stores without side effects
@@ -361,76 +362,79 @@ export class Manager {
      * Re-encryption scope:
      * - keeper-global root salt in `gbls.salt`
      * - per-prefix salts in `prms.salt`
-     * - signer seeds in `pris.`
+     * - signer seeds in `pris.` and Salt128 registry roots in `rroots.`
      *
      * Behavior matrix:
      * - `current AEID -> same AEID`: validate and keep stable
      * - `current AEID -> new AEID`: decrypt with old seed, re-encrypt with new
      *   public box key
-     * - `current AEID -> empty`: decrypt and persist plaintext secrets
-     * - `empty -> new AEID`: encrypt newly managed secrets going forward
+     * - `current AEID -> empty`: refuse retained registry roots; otherwise persist plaintext secrets
+     * - `empty -> new AEID`: encrypt existing and subsequently managed secrets
      *
      * Failure model:
      * - current seed must authenticate the currently stored AEID before any
      *   secret migration is attempted
      * - new seed must authenticate the new AEID before any re-encryption is
      *   attempted
+     * - Keeper owns one synchronous native transaction for all affected rows;
+     *   refusal or failure leaves durable and live crypto state unchanged
+     * - publish encrypter/decrypter/seed only after that transaction commits;
+     *   readonly and borrowed-writer changes are refused
      */
     updateAeid(aeid, seed) {
         const currentAeid = this.aeid;
-        if (currentAeid) {
-            if (!this.seed || !this.encrypter
-                || !this.encrypter.verifySeed(this.seed)) {
-                throw new Error(`Last seed missing or provided last seed not associated with last aeid=${currentAeid}.`);
-            }
-        }
-        if (aeid) {
-            const nextEncrypter = new Encrypter({ verkey: aeid });
-            if (!seed || !nextEncrypter.verifySeed(seed)) {
-                throw new Error(`Seed missing or provided seed not associated with aeid=${aeid}.`);
-            }
-            this.encrypter = nextEncrypter;
-        }
-        else {
-            this.encrypter = null;
-        }
-        const salt = this.salt;
-        if (salt !== null) {
-            this.salt = salt;
+        if (currentAeid && (!this.seed || !new Encrypter({ verkey: currentAeid }).verifySeed(this.seed))) {
+            throw new Error(`Last seed missing or provided last seed not associated with last aeid=${currentAeid}.`);
+        }
+        const encrypter = aeid ? new Encrypter({ verkey: aeid }) : null;
+        if (encrypter && (!seed || !encrypter.verifySeed(seed))) {
+            throw new Error(`Seed missing or provided seed not associated with aeid=${aeid}.`);
+        }
+        const decrypter = seed ? new Decrypter({ seed }) : null;
+        this.ks.changeEncryption({ currentAeid, aeid, encrypter, decrypter: this.decrypter });
+        // All fallible preparation and durable work precedes publication of live state.
+        this.encrypter = encrypter;
+        this.decrypter = decrypter;
+        this._seed = seed;
+    }
+    /** Require full canonical keys; local ownership is the calling operation's responsibility. */
+    registryRootKeys(aid, regid) {
+        if (new Prefixer({ qb64: aid }).qb64 !== aid || new Diger({ qb64: regid }).qb64 !== regid) {
+            throw new Error("Registry root keys must be canonical AID and registry SAID strings");
         }
-        if (this.decrypter) {
-            // `prms.salt` stores derivation salt per managed prefix, so AEID changes
-            // must migrate that state in lockstep with keeper-global salt.
-            for (const [keys, data] of this.ks.prms.getTopItemIter()) {
-                if (!data.salt) {
-                    continue;
-                }
-                data.salt = this.encrypter
-                    ? this.encrypter.encrypt({
-                        prim: this.decrypter.decrypt({
-                            qb64: data.salt,
-                            ctor: Salter,
-                        }),
-                    }).qb64
-                    : this.decrypter.decrypt({
-                        qb64: data.salt,
-                        ctor: Salter,
-                    }).qb64;
-                this.ks.prms.pin(keys, data);
-            }
-            // `pris.` stores signer seeds keyed by their public verifier. Reads here
-            // are intentionally plaintext through the decrypter so the subdb can
-            // immediately re-pin under the new encryption policy.
-            for (const [keys, signer] of this.ks.pris.getTopItemIter("", this.decrypter)) {
-                this.ks.pris.pin(keys, signer, this.encrypter ?? undefined);
-            }
+        return [aid, regid];
+    }
+    /** Authenticate live policy as well as process-local crypto, refusing stale managers. */
+    registryRootCrypto() {
+        const aeid = this.aeid;
+        if (!aeid || !this.encrypter || !this.decrypter || !new Encrypter({ verkey: aeid }).verifySeed(this.seed)) {
+            throw new ValidationError("Registry roots require an authenticated encrypted unlocked Keeper");
         }
-        this._seed = seed;
-        this.decrypter = seed ? new Decrypter({ seed }) : null;
-        if (this.ks.readonly) {
-            return;
+        return { aeid, encrypter: this.encrypter, decrypter: this.decrypter };
+    }
+    /** Assert encrypted, unlocked current policy before authorizing an operation with no root yet. */
+    requireRegistryRootAccess() {
+        this.registryRootCrypto();
+    }
+    /** Return the retained Salt128 root; absent reads require no encryption. */
+    getRegistryRoot(aid, regid) {
+        const cipher = this.ks.rroots.get(this.registryRootKeys(aid, regid));
+        if (!cipher)
+            return null;
+        const { decrypter } = this.registryRootCrypto();
+        const root = decrypter.decrypt({ cipher, ctor: Salter });
+        if (!(root instanceof Salter) || root.code !== MtrDex.Salt_128) {
+            throw new Error("Retained registry root is not Salt128");
         }
-        this.ks.pinGbls("aeid", aeid);
+        return root;
+    }
+    /** Retain once, returning false for the identical root without replacing ciphertext. */
+    putRegistryRoot(aid, regid, root) {
+        const keys = this.registryRootKeys(aid, regid);
+        if (!(root instanceof Salter) || root.code !== MtrDex.Salt_128)
+            throw new Error("Registry root must be Salt128");
+        const { aeid, encrypter, decrypter } = this.registryRootCrypto();
+        return this.ks.retainRegistryRoot(keys, root, aeid, encrypter, decrypter);
     }
     signerDecrypter() {
         if (this.aeid && !this.decrypter) {

package/esm/keri/npm/src/app/{organizing.js → identity/organizing.js}

@@ -1,4 +1,4 @@
-import { ValidationError } from "../core/errors.js";
+import { ValidationError } from "../../core/errors.js";
 const textDecoder = new TextDecoder();
 const textEncoder = new TextEncoder();
 /**
@@ -10,23 +10,53 @@ const textEncoder = new TextEncoder();
  * - no broader contact-management CLI surface yet
  */
 export class Organizer {
-    constructor(hby) {
-        Object.defineProperty(this, "hby", {
+    /** Borrow contact storage and its optional signing authority without owning their lifetime. */
+    constructor(db, signator) {
+        Object.defineProperty(this, "db", {
             enumerable: true,
             configurable: true,
             writable: true,
-            value: void 0
+            value: db
+        });
+        Object.defineProperty(this, "signator", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: signator
         });
-        this.hby = hby;
+    }
+    /**
+     * Resolve one application recipient input into the actual destination prefix.
+     *
+     * Resolution order matches the mailbox CLI mental model:
+     * - exact known prefix wins
+     * - otherwise exact organizer alias lookup is required
+     *
+     * @param recipient Known AID prefix or exact organizer alias.
+     * @returns Resolved destination AID.
+     * @throws ValidationError for absent or ambiguous aliases.
+     */
+    resolveRecipient(recipient) {
+        if (this.db.getKever(recipient)) {
+            return recipient;
+        }
+        const matches = this.findExact("alias", recipient);
+        if (matches.length === 0) {
+            throw new ValidationError(`no contact found with alias '${recipient}'`);
+        }
+        if (matches.length > 1) {
+            throw new ValidationError(`multiple contacts match alias '${recipient}', use prefix instead`);
+        }
+        return matches[0].id;
     }
     /** Load one signed contact record by identifier prefix. */
     get(pre) {
-        const raw = this.hby.db.cons.get([pre]);
+        const raw = this.db.cons.get([pre]);
         if (raw === null) {
             return null;
         }
-        const cigar = this.hby.db.ccigs.get([pre]);
-        if (cigar && this.hby.signator && !verifySignedContact(this.hby, raw, cigar)) {
+        const cigar = this.db.ccigs.get([pre]);
+        if (cigar && this.signator && !verifySignedContact(this.signator, raw, cigar)) {
             throw new ValidationError(`failed signature on ${pre} contact data`);
         }
         const parsed = JSON.parse(raw);
@@ -43,7 +73,7 @@ export class Organizer {
      * and OOBI URL recall, not arbitrary structured contact search.
      */
     update(pre, data) {
-        const signator = this.hby.signator;
+        const signator = this.signator;
         if (!signator) {
             throw new ValidationError("Contact updates require an available habery signator.");
         }
@@ -51,19 +81,19 @@ export class Organizer {
         const next = { ...(current ?? {}), ...data };
         delete next.id;
         const raw = JSON.stringify(next);
-        this.hby.db.cons.pin([pre], raw);
-        this.hby.db.ccigs.pin([pre], signator.sign(textEncoder.encode(raw)));
+        this.db.cons.pin([pre], raw);
+        this.db.ccigs.pin([pre], signator.sign(textEncoder.encode(raw)));
         for (const [field, value] of Object.entries(data)) {
             if (value === undefined || value === null) {
                 continue;
             }
-            this.hby.db.cfld.pin([pre, field], String(value));
+            this.db.cfld.pin([pre, field], String(value));
         }
     }
     /** Find contacts whose indexed field exactly equals the provided value. */
     findExact(field, value) {
         const matches = [];
-        for (const [keys, current] of this.hby.db.cfld.getTopItemIter()) {
+        for (const [keys, current] of this.db.cfld.getTopItemIter()) {
             const pre = keys[0];
             const currentField = keys[1];
             if (!pre || currentField !== field || current !== value) {
@@ -77,11 +107,7 @@ export class Organizer {
         return matches;
     }
 }
-function verifySignedContact(hby, raw, cigar) {
-    const signator = hby.signator;
-    if (!signator) {
-        return true;
-    }
+function verifySignedContact(signator, raw, cigar) {
     return signator.verify(textEncoder.encode(raw), cigar);
 }
 /** Persist minimal alias/OOBI contact state once one remote AID resolves. */
@@ -99,10 +125,10 @@ export function persistResolvedContact(hby, pre, data) {
     if (Object.keys(next).length === 0) {
         return;
     }
-    new Organizer(hby).update(pre, next);
+    new Organizer(hby.db, hby.signator).update(pre, next);
 }
 /** Debug helper kept local so organizer serialization stays reviewable. */
-export function signedContactJson(hby, pre) {
-    const raw = hby.db.cons.get([pre]);
+export function signedContactJson(db, pre) {
+    const raw = db.cons.get([pre]);
     return raw === null ? null : textDecoder.decode(textEncoder.encode(raw));
 }

package/esm/keri/npm/src/app/ipex/ipex-building.js

@@ -0,0 +1,162 @@
+/** Pure v2 IPEX body construction and finite, cancellable byte-input preparation. */
+import { collectPayload, nestedPayload, parseBytes, SerderACDC, Vrsn_2_0 } from "cesr-ts";
+import { exchange, exincept, IPEX_V2_PREDECESSORS, isIpexVerb } from "../../core/exchange/protocol-exchanging.js";
+import { abortable } from "../runtime/abortable.js";
+import { hasIpexNodeAttachments, isIpexMetadata, singleDagDisclosurePlan, validDisclosurePlan, } from "./ipex-graph.js";
+const nodeIlks = new Set([null, "acm", "ace", "act", "acg"]);
+/**
+ * Construct an XIP opener or EXN continuation from parsed credential bodies, without reading or owning wire.
+ * The first node is the origin SAID commitment; offer callers may send just that
+ * commitment or borrow the frames' nestedPayloads. A commitment authenticates no
+ * child signature. Conversation storage, signing and anchoring belong to callers.
+ */
+export function ipexExnBody(sender, route, nodes, options) {
+    const verb = route.slice("/ipex/".length);
+    if (route !== `/ipex/${verb}` || !isIpexVerb(verb)) {
+        throw new Error("Unsupported IPEX route.");
+    }
+    if (nodes.length && verb !== "offer" && verb !== "grant") {
+        throw new Error("Only offer and grant disclose credential nodes.");
+    }
+    if (nodes.some((node) => !(node instanceof SerderACDC) || !node.said || !nodeIlks.has(node.ilk))) {
+        throw new Error("IPEX requires parsed disclosed ACDC nodes.");
+    }
+    if (new Set(nodes.map((node) => node.said)).size !== nodes.length)
+        throw new Error("Duplicate IPEX credential node.");
+    if (verb === "grant" && nodes.some(isIpexMetadata))
+        throw new Error("IPEX Grant requires credentials, not metadata.");
+    const prior = options.prior;
+    let recipient = options.recipient;
+    let xid;
+    if (prior) {
+        if (prior.pvrsn.major !== 2 || verb === "apply"
+            || (prior.ilk === "xip"
+                ? !["/ipex/apply", "/ipex/offer", "/ipex/grant"].includes(prior.route ?? "")
+                : prior.ilk !== "exn" || !prior.sad.p)
+            || !IPEX_V2_PREDECESSORS[verb].some((v) => prior.route === `/ipex/${v}`)) {
+            throw new Error("Unsupported IPEX prior route.");
+        }
+        if (!prior.sad.ri || prior.sad.ri !== sender || (recipient !== undefined && recipient !== prior.pre)) {
+            throw new Error("IPEX reply parties do not match the prior.");
+        }
+        if (verb === "spurn" && prior.route === "/ipex/grant" && prior.sad.p) {
+            throw new Error("Only an opening grant may be spurned.");
+        }
+        recipient = prior.pre;
+        xid = prior.ilk === "xip" ? prior.said : prior.sad.x;
+    }
+    else if (!["apply", "offer", "grant"].includes(verb) || !recipient) {
+        throw new Error("An IPEX opener requires a recipient; replies require a prior.");
+    }
+    const attrs = { ...options.attrs };
+    if (["m", "o", "ax"].some((key) => Object.hasOwn(attrs, key))) {
+        throw new Error("Use named IPEX inputs for m, o and ax.");
+    }
+    attrs.m = options.message;
+    const priorAnchor = prior?.sad?.a?.ax?.[0] === true;
+    const anchor = options.anchor ?? (["agree", "admit"].includes(verb) && priorAnchor ? true : undefined);
+    if (anchor !== undefined) {
+        if (typeof anchor !== "boolean")
+            throw new TypeError("IPEX anchor must be boolean.");
+        attrs.ax = [anchor];
+    }
+    if (prior && ((["agree", "grant", "admit"].includes(verb) && (anchor === true) !== priorAnchor)
+        || (verb === "offer" && priorAnchor && anchor !== true)))
+        throw new Error("IPEX reply must preserve the anchoring requirement.");
+    let plan = options.plan;
+    if (verb === "offer" && prior && (plan === undefined || !plan.length)) {
+        const inherited = singleDagDisclosurePlan(prior.sad?.q?.dp);
+        if (inherited === null) {
+            throw new Error("IPEX offer cannot inherit an invalid Apply plan.");
+        }
+        plan ??= [];
+    }
+    if (verb === "agree") {
+        if (plan?.length)
+            throw new Error("IPEX agree must use an empty ditto plan.");
+        plan = [];
+    }
+    if (verb === "grant" && plan === undefined) {
+        if (prior || !nodes.length)
+            plan = [];
+        else if (nodes.length === 1) {
+            const schema = nodes[0].schema;
+            plan = [[
+                    typeof schema === "object" && schema !== null
+                        ? schema.$id
+                        : schema,
+                    "/",
+                    [],
+                ]];
+        }
+        else
+            throw new Error("A grant with multiple nodes requires an explicit disclosure plan.");
+    }
+    const modifiers = {};
+    if (["apply", "offer", "agree", "grant"].includes(verb)) {
+        if (!validDisclosurePlan(plan))
+            throw new Error("IPEX requires a valid disclosure plan.");
+        modifiers.dp = [structuredClone(plan)];
+    }
+    else if (plan !== undefined)
+        throw new Error("This IPEX route does not negotiate disclosure.");
+    if (verb === "grant") {
+        if (!prior && Boolean(plan.length) !== Boolean(nodes.length)) {
+            throw new Error("Opening grant nodes must match its disclosure obligation.");
+        }
+        attrs.o = nodes.length ? [nodes[0].said] : [];
+    }
+    else if (verb === "offer" && nodes.length)
+        attrs.o = [nodes[0].said];
+    if (!prior) {
+        return exincept(route, {
+            sender,
+            receiver: recipient,
+            attributes: attrs,
+            modifiers,
+            stamp: options.date ?? options.stamp,
+            kind: options.kind,
+            gvrsn: options.gvrsn ?? Vrsn_2_0,
+        });
+    }
+    return exchange(route, attrs, {
+        sender,
+        recipient,
+        xid,
+        dig: prior?.said ?? "",
+        modifiers,
+        stamp: options.stamp,
+        date: options.date,
+        kind: options.kind,
+        pvrsn: Vrsn_2_0,
+        gvrsn: options.gvrsn ?? Vrsn_2_0,
+    })[0];
+}
+/**
+ * Parse a finite stream of direct child messages once, then consume their nested
+ * wire for the enclosing exchange. Parsed frames and Texters are ordinary values;
+ * serialization observes the operation signal.
+ * Returned nested bytes must share the enclosure with the parent's own proofs.
+ */
+export function* prepareIpexExn(sender, route, wire, options) {
+    return yield* abortable(async (signal) => {
+        const frames = parseBytes(wire);
+        if (frames.some((frame) => !(frame.body instanceof SerderACDC) || frame.nests?.length)) {
+            throw new Error("IPEX requires direct credential node frames.");
+        }
+        if (route === "/ipex/offer" && frames.some(hasIpexNodeAttachments)) {
+            throw new Error("IPEX Offer nodes must not carry attachments.");
+        }
+        const body = ipexExnBody(sender, route, frames.map((frame) => frame.body), options);
+        const payloads = frames.map((frame) => nestedPayload(frame, Vrsn_2_0));
+        const payload = {
+            size: payloads.reduce((sum, child) => sum + child.size, 0),
+            /** Borrow each frame only until collection completes or aborts. */
+            async *open(signal) {
+                for (const child of payloads)
+                    yield* child.open(signal);
+            },
+        };
+        return [body, await collectPayload(payload, signal)];
+    });
+}