keri-ts 2.0.1 → 2.2.0

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

@@ -0,0 +1,93 @@
+import { ValidationError } from "../../core/errors.js";
+import { acceptIpexExchange, ipexExchangeStatus, requireIpexPrior, requireIpexSender, } from "./ipex-conversation.js";
+import { ipexCredentialAdmit, ipexCredentialGrant, processCredentialPresentationArtifacts, storedGrantArtifacts, validateAdmitGrant, } from "./ipex-credentialing.js";
+import { requireStoredExchange, sendCredentialStream } from "./ipex-grouping.js";
+/**
+ * Grant a stored single-signature credential: validate the optional agree,
+ * assemble the embedded artifacts and support messages, sign, accept locally
+ * and deliver support then grant as one stream. Granting a credential again
+ * without an agree authors another grant; an agree answers once.
+ *
+ * @throws ValidationError for a non-local sender, a refused prior, missing local
+ * credential evidence or a grant local state does not accept.
+ */
+export function* sendIpexGrant(deps, sender, { recipient, credential, message = "", agree, gvrsn, deliver = true }) {
+    requireIpexSender(deps.hby, sender);
+    if (agree)
+        requireIpexPrior(deps.hby, sender.pre, recipient, agree, "grant");
+    const built = ipexCredentialGrant({
+        hby: deps.hby,
+        hab: sender,
+        reger: deps.reger,
+        recipient,
+        credentialSaid: credential,
+        message,
+        options: { agree: agree ? deps.hby.db.exns.get([agree]) : null, gvrsn },
+    });
+    const genus = built.grant.gvrsn ?? gvrsn ?? built.grant.pvrsn;
+    yield* acceptIpexExchange(deps, built.grant, built.wire, genus, "Local IPEX grant was not accepted.", agree);
+    const deliveries = deliver
+        ? yield* sendCredentialStream(deps.postman, sender, recipient, [...built.support, built.wire])
+        : [];
+    return { grant: built.grant, credential, support: built.support, wire: built.wire, deliveries };
+}
+/**
+ * Validate a stored grant for admission by `holder` without signing: it is
+ * accepted, addressed to the holder, carries a credential and has no accepted
+ * response yet. Saving is not required here.
+ *
+ * @throws ValidationError when the grant is not stored, was already answered or is not addressed to `holder`.
+ */
+export function requireAdmittableGrant(deps, holder, grantSaid) {
+    const grant = requireStoredExchange(deps.hby, grantSaid);
+    const sender = grant.ked?.i;
+    if (typeof sender !== "string" || sender.length === 0) {
+        throw new ValidationError("Grant is missing sender AID.");
+    }
+    requireIpexPrior(deps.hby, holder.pre, sender, grant.said, "admit");
+    const credential = validateAdmitGrant(grant, holder.pre, deps.reger, false);
+    return { grant, recipient: sender, credential };
+}
+/**
+ * The holder's consent to a grant: validate the stored grant, sign an admit,
+ * accept it locally and deliver it to the grant's sender. A grant that already
+ * has an accepted response is refused, so a second admit never re-signs.
+ *
+ * @throws ValidationError as for {@link requireAdmittableGrant}, for a credential
+ * that is not saved when `requireSaved` holds, or for an admit local state does not accept.
+ */
+export function* sendIpexAdmit(deps, holder, grantSaid, { message = "", gvrsn, requireSaved = true, deliver = true } = {}) {
+    requireIpexSender(deps.hby, holder);
+    const { grant, recipient, credential } = requireAdmittableGrant(deps, holder, grantSaid);
+    const saved = !!deps.reger.saved.get([credential]);
+    const prepared = ipexCredentialAdmit({
+        hab: holder,
+        reger: deps.reger,
+        grant,
+        message,
+        options: { requireSaved, gvrsn },
+    });
+    const genus = prepared.admit.gvrsn ?? gvrsn ?? prepared.admit.pvrsn;
+    yield* acceptIpexExchange(deps, prepared.admit, prepared.wire, genus, "Local IPEX admit was not accepted.", grant.said);
+    const deliveries = deliver ? yield* sendCredentialStream(deps.postman, holder, recipient, [prepared.wire]) : [];
+    return { admit: prepared.admit, grant, credential, saved, wire: prepared.wire, deliveries };
+}
+/**
+ * Import a stored grant's authenticated artifacts once, so the wallet can save
+ * its credential as evidence resolves. Idempotent: a credential that is already
+ * saved is not replayed. Signs nothing and does not wait; observe the outcome
+ * with `waitForIpexExchange(..., { until: "credential-saved" })` while the
+ * host's workers run.
+ *
+ * @param holder AID the grant must be addressed to.
+ * @returns The grant's status after the import.
+ * @throws ValidationError when the grant is not stored or not addressed to `holder`.
+ */
+export function* settleGrantCredential(deps, holder, grantSaid, { gvrsn } = {}) {
+    const grant = requireStoredExchange(deps.hby, grantSaid);
+    const credential = validateAdmitGrant(grant, holder, deps.reger, false);
+    if (!deps.reger.saved.get([credential])) {
+        yield* processCredentialPresentationArtifacts(deps.protocol, storedGrantArtifacts(deps.hby, grant, gvrsn));
+    }
+    return ipexExchangeStatus(deps, grantSaid);
+}

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

@@ -1,6 +1,6 @@
 /** Borrowed IPEX frame DAGs, negotiated disclosure paths and traversal policy. */
 import { Compactor, makePather, SerderACDC } from "cesr-ts";
-import { acdcEdgeBlocks as blocks, acdcEdgeTarget, acdcGroupLabels } from "../../acdc/chaining.js";
+import { walkAcdcGraph } from "../../acdc/chaining.js";
 const nodeIlks = new Set([null, "acm", "ace", "act", "acg"]);
 /** Empty UUID marks field-map metadata; fixed-field public credentials keep that slot empty too. */
 export function isIpexMetadata(node) {
@@ -58,15 +58,15 @@ export function singleDagDisclosurePlan(value) {
     return Array.isArray(value) && value.length === 1 && validDisclosurePlan(value[0]) ? value[0] : null;
 }
 /**
- * Index unique disclosed credential nodes and walk their reachable graph in BFS order.
- * Offers may omit far nodes; grants require every referenced node. Nested ownership
+ * Index unique disclosed credential frames, then delegate the graph walk to `walkAcdcGraph`.
+ * Offers always walk open; Grants use the caller's walk policy. Nested ownership
  * does not make these nodes independently accepted runtime messages.
  */
-export function walkIpexGraph(origin, nests, closed) {
+export function walkIpexGraph(origin, nests, walk) {
     const nodes = new Map();
     for (const [index, frame] of nests.entries()) {
         const body = frame.body;
-        if (!(body instanceof SerderACDC) || !body.verify() || !nodeIlks.has(body.ilk)
+        if (!(body instanceof SerderACDC) || !nodeIlks.has(body.ilk)
             || !body.said || (index === 0 && body.said !== origin) || nodes.has(body.said))
             return null;
         // Descendants are not additional implicit evidence for this disclosed node.
@@ -74,71 +74,8 @@ export function walkIpexGraph(origin, nests, closed) {
             return null;
         nodes.set(body.said, frame);
     }
-    if (!nodes.has(origin))
-        return null;
-    const seen = new Set();
-    const order = [];
-    const dependencies = new Map();
-    const queue = [origin];
-    for (let index = 0; index < queue.length; index++) {
-        const said = queue[index];
-        if (seen.has(said))
-            continue;
-        seen.add(said);
-        order.push(said);
-        const farNodes = new Set();
-        dependencies.set(said, farNodes);
-        const edges = blocks(nodes.get(said).body.sad.e);
-        if (!edges)
-            return null;
-        const groups = [...edges];
-        for (let g = 0; g < groups.length; g++) {
-            const edge = groups[g];
-            const target = acdcEdgeTarget(edge);
-            if (target === false)
-                return null;
-            if (typeof target === "string") {
-                if (!nodes.has(target)) {
-                    if (closed)
-                        return null;
-                }
-                else {
-                    farNodes.add(target);
-                    if (!seen.has(target))
-                        queue.push(target);
-                }
-            }
-            else {
-                if (!record(edge))
-                    return null;
-                for (const [key, value] of Object.entries(edge)) {
-                    if (acdcGroupLabels.has(key) || typeof value === "string")
-                        continue;
-                    groups.push(value);
-                }
-            }
-        }
-    }
-    if (seen.size !== nodes.size)
-        return null;
-    const parents = new Map();
-    for (const [near, children] of dependencies) {
-        for (const far of children) {
-            if (!parents.has(far))
-                parents.set(far, new Set());
-            parents.get(far).add(near);
-        }
-    }
-    const dependencyOrder = order.filter((said) => dependencies.get(said).size === 0);
-    for (let i = 0; i < dependencyOrder.length; i++) {
-        for (const near of parents.get(dependencyOrder[i]) ?? []) {
-            const children = dependencies.get(near);
-            children.delete(dependencyOrder[i]);
-            if (!children.size)
-                dependencyOrder.push(near);
-        }
-    }
-    return dependencyOrder.length === nodes.size ? { nodes, order } : null;
+    const order = walkAcdcGraph(origin, nodes, walk);
+    return order ? { nodes, order, walk } : null;
 }
 /** Compare SAD values structurally while retaining list order; map insertion order is not semantic here. */
 function equal(a, b) {

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

@@ -29,10 +29,11 @@ import { collectBytes } from "../transport/byte-source.js";
 import { credentialGrantReady, credentialPresentationSupportMessages, credentialSaidFromGrant, validateAdmitGrant, } from "./ipex-credentialing.js";
 import { walkIpexGraph } from "./ipex-graph.js";
 import { authenticateIpexNode, issuedNodeVerdict } from "./ipex-node-authentication.js";
+import { ipexGrantWalk } from "./ipex-v2.js";
 import { IPEX_ADMIT_ROUTE, IPEX_GRANT_ROUTE, ipexConversationReady, ipexRecipient } from "./ipexing.js";
 /** Authenticate the exact disclosed graph; only the existing evaluator's explicit true authorizes new use. */
-function acdcV2GraphUse(hby, registry, origin, nests) {
-    const graph = walkIpexGraph(origin, nests, true);
+function acdcV2GraphUse(hby, registry, origin, nests, walk) {
+    const graph = walkIpexGraph(origin, nests, walk);
     if (!graph)
         throw new ValidationError("ACDC v2 group graph is malformed or incomplete.");
     const verdicts = new Map();
@@ -55,7 +56,7 @@ function acdcV2GrantUse(hby, exchanger, registry, said) {
     if (!Array.isArray(origins) || origins.length !== 1 || typeof origins[0] !== "string") {
         throw new ValidationError("ACDC v2 group Grant requires one origin.");
     }
-    return acdcV2GraphUse(hby, registry, origins[0], loadNests(hby.db, said));
+    return acdcV2GraphUse(hby, registry, origins[0], loadNests(hby.db, said), ipexGrantWalk(exchanger));
 }
 /** Recheck current graph authorization at an accepted group's new delivery, output or consent action. */
 export function requireAcdcV2GroupUse(hby, protocol, embedded) {
@@ -110,8 +111,10 @@ export function* prepareAcdcV2GroupIpex(hby, protocol, group, raw) {
             if (!Array.isArray(origins) || origins.length !== 1 || typeof origins[0] !== "string") {
                 throw new ValidationError("ACDC v2 group Grant requires one origin.");
             }
-            if (acdcV2GraphUse(hby, protocol.registry?.store ?? null, origins[0], frame.nests ?? []) !== true)
+            const walk = ipexGrantWalk(protocol.exc);
+            if (acdcV2GraphUse(hby, protocol.registry?.store ?? null, origins[0], frame.nests ?? [], walk) !== true) {
                 return null;
+            }
         }
         else if (embedded.route === IPEX_ADMIT_ROUTE) {
             if (typeof embedded.sad.p !== "string"
@@ -133,20 +136,13 @@ export function* prepareAcdcV2GroupIpex(hby, protocol, group, raw) {
     return wire;
 }
 /**
- * Approve one pending multisig wrapper around an embedded IPEX message.
- *
- * @param hby Borrowed local identities and accepted-state stores.
- * @param protocol Borrowed semantic owner; this approval creates its own byte-input context.
- * @param postman Borrowed delivery owner; the caller runs and joins its worker.
- * @param reger Explicit legacy store, required for grant approval/delivery and fresh admit approval.
- * @param wrapper Accepted multisig exchange carrying the proposed IPEX child.
- * @param options Approval/genus policy used for the existing group workflow.
- * @returns Approval and current group/protocol completion information.
+ * Approve one stored multisig wrapper around an IPEX message locally: validate it, reuse or sign this member's
+ * contribution and accept it, without publishing or sending anything. The explicit consent of the library's group
+ * IPEX operations; {@link approveMultisigIpex} adds publication and the lead's delivery.
  */
-export function* approveMultisigIpex(hby, protocol, postman, reger, wrapper, options = {}) {
+export function* approveMultisigIpexLocally(hby, protocol, reger, wrapper) {
     const { child, groupHab } = yield* loadIpexProposal(hby, wrapper);
     const { event: embedded, genus } = child;
-    const embeddedSaid = embedded.said;
     if (embedded.pvrsn.major === 1 && embedded.route === IPEX_GRANT_ROUTE && !reger) {
         throw new ValidationError("VDR runtime did not open Reger.");
     }
@@ -163,6 +159,23 @@ export function* approveMultisigIpex(hby, protocol, postman, reger, wrapper, opt
         }
     }
     const approved = yield* approveIpexChild(hby, protocol, groupHab, child, wrapper, reger);
+    return { embedded, groupHab, genus, approved };
+}
+/**
+ * Approve one pending multisig wrapper around an embedded IPEX message.
+ *
+ * @param hby Borrowed local identities and accepted-state stores.
+ * @param protocol Borrowed semantic owner; this approval creates its own byte-input context.
+ * @param postman Borrowed delivery owner; the caller runs and joins its worker.
+ * @param reger Explicit legacy store, required for grant approval/delivery and fresh admit approval.
+ * @param wrapper Accepted multisig exchange carrying the proposed IPEX child.
+ * @param options Approval/genus policy used for the existing group workflow.
+ * @returns Approval and current group/protocol completion information.
+ */
+export function* approveMultisigIpex(hby, protocol, postman, reger, wrapper, options = {}) {
+    const local = yield* approveMultisigIpexLocally(hby, protocol, reger, wrapper);
+    const { embedded, groupHab, genus, approved } = local;
+    const embeddedSaid = embedded.said;
     if (!approved)
         return { approved: null, accepted: protocol.exc.complete(embeddedSaid), messages: [], deliveries: [] };
     const publication = options.publish
@@ -353,7 +366,7 @@ function* prepareGroupIpexMessages(hby, protocol, groupHab, embedded, childGvrsn
         if (child.route === IPEX_GRANT_ROUTE) {
             const origins = child.sad.a.o;
             if (!Array.isArray(origins) || origins.length !== 1 || typeof origins[0] !== "string"
-                || acdcV2GraphUse(hby, protocol.registry?.store ?? null, origins[0], childFrame.nests ?? []) !== true) {
+                || acdcV2GraphUse(hby, protocol.registry?.store ?? null, origins[0], childFrame.nests ?? [], ipexGrantWalk(protocol.exc)) !== true) {
                 throw new ValidationError("ACDC v2 group graph is unavailable before proposal publication.");
             }
         }
@@ -662,3 +675,16 @@ function hexToFixedBytes(hex, size) {
     }
     return raw;
 }
+/** The stored `/multisig/exn` wrapper that carries the IPEX message `embeddedSaid`, if one is held. */
+export function findStoredMultisigIpex(db, embeddedSaid) {
+    for (const [, wrapper] of db.exns.getTopItemIter()) {
+        if (wrapper.route === MULTISIG_EXN_ROUTE && storedMultisigIpexBody(db, wrapper)?.said === embeddedSaid) {
+            return wrapper;
+        }
+    }
+    return null;
+}
+/** Whether the local member of `group` already holds a verified contribution to `embedded` (a recorded approval). */
+export function groupIpexApproved(hby, group, embedded) {
+    return !!localIpexContribution(hby.db, localGroupMember(hby, group).pre, embedded, rebuildStoredExchangeGroups(hby.db, embedded.said));
+}

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

@@ -1,7 +1,7 @@
 import { IPEX_V2_PREDECESSORS, isIpexVerb, nestedIpexRoute, } from "../../core/exchange/protocol-exchanging.js";
 /** V2 IPEX route policy; v1 routing remains independently registered. */
 import { Diger, ParserError, Prefixer, } from "cesr-ts";
-import { evaluateChain } from "../../acdc/chaining.js";
+import { DEFAULT_GRANT_WALK, evaluateChain } from "../../acdc/chaining.js";
 import { validateUpdate, verifyRegistryAnchor, vet, vetBinds, vetBlind, vetBound, } from "../../acdc/regeventing.js";
 import { validateSchema } from "../../acdc/scheming.js";
 import { DatabaseOperationError } from "../../core/errors.js";
@@ -31,9 +31,11 @@ function missing(reason) {
  * Authenticate each disclosed node independently before Exchanger persists an EXN.
  * Registry evidence is caller-owned; notifier delivery follows durable acceptance.
  * Presentation registries require the retained receiver receipt and node-local proofs.
+ * `grantWalk` selects how a Grant treats an undisclosed far node (`AcdcWalkPolicy`);
+ * a far node the disclosure plan selects but the Grant does not nest always refuses.
  */
 export class IpexV2Handler {
-    constructor(resource, hby, notifier = null, registry = null) {
+    constructor(resource, hby, notifier = null, registry = null, grantWalk = DEFAULT_GRANT_WALK) {
         Object.defineProperty(this, "resource", {
             enumerable: true,
             configurable: true,
@@ -58,6 +60,12 @@ export class IpexV2Handler {
             writable: true,
             value: registry
         });
+        Object.defineProperty(this, "grantWalk", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: grantWalk
+        });
         Object.defineProperty(this, "protocolMajor", {
             enumerable: true,
             configurable: true,
@@ -266,7 +274,7 @@ export class IpexV2Handler {
         if (verb === "offer" && nests.length) {
             if (nests.some(hasIpexNodeAttachments))
                 return false;
-            const graph = walkIpexGraph(attrs.o[0], nests, false);
+            const graph = walkIpexGraph(attrs.o[0], nests, "open");
             return graph ? this.nodeSchemas(graph) : false;
         }
         if (verb !== "grant")
@@ -287,7 +295,7 @@ export class IpexV2Handler {
         if (!single(attrs.o, "string") || !this.validOrigin(attrs.o[0]) || !nests.length)
             return false;
         const origin = attrs.o[0];
-        const graph = walkIpexGraph(origin, nests, true);
+        const graph = walkIpexGraph(origin, nests, this.grantWalk);
         if (!graph || [...graph.nodes.values()].some((node) => isIpexMetadata(node.body)))
             return false;
         if (!verifyIpexDisclosure(plan, origin, graph))
@@ -492,7 +500,7 @@ export class IpexV2Handler {
         const nests = loadNests(this.hby.db, offerSaid);
         if (!nests.length)
             return missing(`Missing metadata ACDC for accepted Offer ${offerSaid}.`);
-        const offered = walkIpexGraph(offeredOrigin, nests, false);
+        const offered = walkIpexGraph(offeredOrigin, nests, "open");
         if (!offered)
             return false;
         const metadata = offered.nodes.get(offeredOrigin).body;
@@ -690,3 +698,11 @@ export class IpexV2Handler {
         return [[issuee, regid]];
     }
 }
+/**
+ * The Grant walk policy of the exchanger's v2 Grant owner. Later use of an
+ * accepted Grant re-walks it under this policy so reuse agrees with admission.
+ */
+export function ipexGrantWalk(exchanger) {
+    const handler = exchanger.routeHandler("/ipex/grant", 2);
+    return handler instanceof IpexV2Handler ? handler.grantWalk : DEFAULT_GRANT_WALK;
+}

package/esm/keri/npm/src/app/ipex/ipexing.js

@@ -111,7 +111,7 @@ export class IpexHandler {
 export function loadIpexHandlers(hby, exchanger, options = {}) {
     for (const route of IPEX_ROUTES) {
         exchanger.addHandler(new IpexHandler(route, hby, options.notifier ?? null));
-        exchanger.addHandler(new IpexV2Handler(route, hby, options.notifier ?? null, options.registry ?? null));
+        exchanger.addHandler(new IpexV2Handler(route, hby, options.notifier ?? null, options.registry ?? null, options.grantWalk));
     }
 }
 /** Apply for an ACDC. */