keri-ts 2.1.0 → 2.2.1

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-grouping.js

@@ -36,15 +36,20 @@ 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();
+    const verdicts = new Map(), why = [];
     for (const [said, node] of graph.nodes) {
-        verdicts.set(said, issuedNodeVerdict(authenticateIpexNode(node.body, envelopeFromFrame(node), hby.db, registry)));
+        const authentication = authenticateIpexNode(node.body, envelopeFromFrame(node), hby.db, registry);
+        verdicts.set(said, issuedNodeVerdict(authentication));
+        if (authentication.kind !== "authenticated")
+            why.push(`${said} ${authentication.kind}: ${authentication.reason}`);
     }
     const verdict = evaluateChain(graph, verdicts, hby.db);
     if (verdict?.kind === "unknown" && verdict.retryable)
         return null;
-    if (verdict?.kind !== "valid")
-        throw new ValidationError("ACDC v2 group graph is false or unresolved.");
+    if (verdict?.kind !== "valid") {
+        const found = !verdict ? "no verdict" : verdict.kind === "unknown" ? `unknown: ${verdict.reason}` : verdict.kind;
+        throw new ValidationError(`ACDC v2 group graph is false or unresolved (${found}${why.length ? `; ${why.join("; ")}` : ""}).`);
+    }
     return true;
 }
 /** Current retained Grant authentication and graph truth are separate from protocol completion/history. */
@@ -136,20 +141,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.");
     }
@@ -166,12 +164,30 @@ export function* approveMultisigIpex(hby, protocol, postman, reger, wrapper, opt
         }
     }
     const approved = yield* approveIpexChild(hby, protocol, groupHab, child, wrapper, reger);
-    if (!approved)
-        return { approved: null, accepted: protocol.exc.complete(embeddedSaid), messages: [], deliveries: [] };
+    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: [], members: [] };
+    }
     const publication = options.publish
         ? yield* publishGroupIpexProposal(hby, protocol, postman, groupHab, approved, genus)
-        : { messages: [], deliveries: [] };
-    const deliveries = publication.deliveries;
+        : { messages: [], deliveries: [], members: [] };
+    const deliveries = [...publication.deliveries];
     if ((options.sendLead ?? true)
         && hby.db.exns.get([embeddedSaid])?.said === embeddedSaid
         && protocol.exc.lead(groupHab, embeddedSaid)) {
@@ -181,6 +197,7 @@ export function* approveMultisigIpex(hby, protocol, postman, reger, wrapper, opt
         accepted: hby.db.exns.get([embeddedSaid])?.said === embeddedSaid,
         messages: publication.messages,
         deliveries,
+        members: publication.members,
         approved,
     };
 }
@@ -420,6 +437,7 @@ export function* publishInitialGroupIpex(hby, protocol, postman, groupHab, embed
             recipient: message.recipient,
             exnSaid: message.exnSaid,
             payloadSaid: message.payloadSaid,
+            outcome: "delivered",
             deliveries: outcome.deliveries,
         });
     }
@@ -665,3 +683,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-node-authentication.js

@@ -1,9 +1,10 @@
 /** Node issuer authentication over public KEL/TEL evidence; no conversation or validity policy. */
-import { Diger, NumberPrimitive, Prefixer } from "cesr-ts";
+import { Diger, NumberPrimitive, Prefixer, SerderACDC } from "cesr-ts";
 import { validateRip, validateUpdate, vetBinds, vetBlind, vetBound, } from "../../acdc/regeventing.js";
 import { TransIdxSigGroup } from "../../core/dispatch.js";
 import { DatabaseOperationError } from "../../core/errors.js";
 import { verifyExchangeProofs } from "../../core/exchange/exchange-proofing.js";
+import { envelopeFromFrame } from "../protocol/parsering.js";
 /** Protocol admission authenticates registry observations without imposing an application state vocabulary. */
 export function authenticatedNodeVerdict(authentication) {
     switch (authentication.kind) {
@@ -65,35 +66,57 @@ export function acceptedRegistryEvidence(store, regid) {
     }
     return { rip, updates };
 }
+/**
+ * Whether a Grant's origin node is a fresh issuance: a credential its own sender issues, disclosed with no registry
+ * proof because no registry update has issued it yet. A presentation of an issued credential carries the proof
+ * that opens its registry update, so it never matches. Both are Grants on the wire; only a fresh one is consented to
+ * as an issuance. The answer is the same before and after the registry update is approved.
+ */
+export function isIssuanceOrigin(sender, origin) {
+    const body = origin?.body;
+    if (!(body instanceof SerderACDC) || body.issuer !== sender || !body.regid)
+        return false;
+    const { bsqs, bsss } = envelopeFromFrame(origin);
+    return !bsqs.length && !bsss.length;
+}
 /** A declared registry, then supplied anchors, take precedence over current signatures. */
 export function authenticateIpexNode(serder, envelope, db, registry, historical = false) {
     if (serder.regid) {
         const proofs = [...envelope.bsqs, ...envelope.bsss];
-        if (!proofs.length || !registry)
-            return { kind: "reject" };
+        if (!proofs.length || !registry) {
+            return {
+                kind: "reject",
+                reason: "The node declares a registry but carries no issuer proof or no registry store is open.",
+            };
+        }
         const chain = acceptedRegistryEvidence(registry, serder.regid);
         if (!chain)
             return { kind: "missing", reason: `Missing local TEL evidence for ${serder.regid}.` };
         // A RIP alone authenticates ownership, never a disclosed credential state.
-        if (!chain.updates.length)
-            return { kind: "reject" };
+        if (!chain.updates.length) {
+            return {
+                kind: "reject",
+                reason: "The registry has only its inception; a RIP alone authenticates ownership, never a disclosed credential state.",
+            };
+        }
         let at;
         if (historical) {
             if (!serder.verify() || serder.issuer !== chain.rip.issuer || serder.regid !== chain.rip.said) {
-                return { kind: "reject" };
+                return { kind: "reject", reason: "The node differs from the registry inception it declares." };
             }
             // Authenticate all supplied bodies/duplicates and known bound contradictions
             // before missing evidence wins, independently of attachment order.
             if (proofs.some((proof) => !vetBlind(proof, proof.d.nonce))
                 || new Set(proofs.map((proof) => proof.d.nonce)).size !== proofs.length)
-                return { kind: "reject" };
+                return { kind: "reject", reason: "The disclosed issuer proofs are malformed or repeat a nonce." };
             let unresolved = false;
             for (const proof of proofs) {
                 if (proof.td.nonce && proof.td.nonce !== serder.said)
                     continue;
                 const bound = vetBound(proof, serder, db);
-                if (bound?.kind === "reject")
-                    return { kind: "reject" };
+                if (bound?.kind === "reject") {
+                    return { kind: "reject", reason: "A disclosed issuer proof contradicts the node." };
+                }
                 if (bound)
                     unresolved = true;
             }
@@ -103,7 +126,7 @@ export function authenticateIpexNode(serder, envelope, db, registry, historical
                     continue;
                 const matches = chain.updates.filter((event) => event.sad.b === proof.d.nonce);
                 if (matches.length > 1)
-                    return { kind: "reject" };
+                    return { kind: "reject", reason: "Several registry updates match one issuer proof." };
                 if (matches.length)
                     selected.push(matches[0]);
                 else
@@ -111,8 +134,9 @@ export function authenticateIpexNode(serder, envelope, db, registry, historical
             }
             if (unresolved)
                 return { kind: "missing", reason: `Missing retained issuer proof evidence for ${serder.said}.` };
-            if (!selected.length)
-                return { kind: "reject" };
+            if (!selected.length) {
+                return { kind: "reject", reason: "No registry update matches the disclosed issuer proofs." };
+            }
             const candidates = new Set(selected.map((event) => event.said));
             // Accepted history is ascending. Vacuous and other-target openings cannot
             // advance this issuer prefix; generic source locators never select it.
@@ -131,7 +155,7 @@ export function authenticateIpexNode(serder, envelope, db, registry, historical
         }
         return result.kind === "verified" && result.state.regid === serder.regid
             ? { kind: "authenticated", registration: result.state }
-            : { kind: "reject" };
+            : { kind: "reject", reason: "The registry update does not bind the node." };
     }
     // Disclosed inner rd without top-level rd is an unsupported hidden issuer registry.
     // Compact aggregate entries expose no declaration and remain opaque here.
@@ -139,15 +163,15 @@ export function authenticateIpexNode(serder, envelope, db, registry, historical
     const sections = [serder.sad.a, ...(Array.isArray(aggregate) ? aggregate.slice(1) : [aggregate])];
     if (sections.some(section => section && typeof section === "object" && !Array.isArray(section)
         && section.rd))
-        return { kind: "reject" };
+        return { kind: "reject", reason: "A disclosed inner registry has no top-level declaration." };
     if (!serder.issuer)
-        return { kind: "reject" };
+        return { kind: "reject", reason: "The node names no issuer." };
     let issuer;
     try {
         issuer = new Prefixer({ qb64: serder.issuer });
     }
     catch {
-        return { kind: "reject" };
+        return { kind: "reject", reason: "The node names a malformed issuer." };
     }
     const sourceSeals = [
         ...envelope.sscs.map((seal) => ({ i: issuer, ...seal })),
@@ -159,7 +183,7 @@ export function authenticateIpexNode(serder, envelope, db, registry, historical
             ? { kind: "missing", reason: `Missing issuer KEL anchor for ${serder.said}.` }
             : result.sourceSeals.length > 0
                 ? { kind: "authenticated", registration: null }
-                : { kind: "reject" };
+                : { kind: "reject", reason: "No issuer KEL anchor seals the node." };
     }
     const explicit = envelope.tsgs.filter((group) => group.pre === issuer.qb64);
     const last = envelope.ssgs.filter((group) => group.pre === issuer.qb64);
@@ -181,5 +205,5 @@ export function authenticateIpexNode(serder, envelope, db, registry, historical
         ? { kind: "missing", reason: `Missing current issuer KEL evidence for ${serder.said}.` }
         : result.tsgs.length + result.cigars.length > 0
             ? { kind: "authenticated", registration: null }
-            : { kind: "reject" };
+            : { kind: "reject", reason: "No current issuer signature authenticates the node." };
 }