keri-ts 2.1.0 → 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-grouping.js

@@ -136,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.");
     }
@@ -166,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
@@ -665,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));
+}