keri-ts 2.1.0 → 2.2.1

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

@@ -0,0 +1,120 @@
+/**
+ * IPEX Admit preparation over borrowed protocol owners.
+ *
+ * Reads accepted Grants and their graph truth from the Habery, Exchanger and
+ * registry store only; it records no admission. Embedders that keep admitted
+ * records (the wallet) call it before and after their own inventory writes.
+ */
+import { SerderACDC, Vrsn_2_0 } from "cesr-ts";
+import { call } from "effection";
+import { evaluateChain } from "../../acdc/chaining.js";
+import { ValidationError } from "../../core/errors.js";
+import { loadNests } from "../../db/exchange/exchange-nests.js";
+import { isLocalGroupHab } from "../multisig/group-members.js";
+import { envelopeFromFrame } from "../protocol/parsering.js";
+import { ipexExnBody } from "./ipex-building.js";
+import { anchorExchange, exchangeWire, IpexDiscloser } from "./ipex-discloser.js";
+import { walkIpexGraph } from "./ipex-graph.js";
+import { authenticateIpexNode, issuedNodeVerdict } from "./ipex-node-authentication.js";
+import { ipexGrantWalk } from "./ipex-v2.js";
+/** Borrow concrete owners only; no constructor opens a store or starts a worker. */
+export class IpexAdmitter {
+    constructor(hby, registry, exc) {
+        Object.defineProperty(this, "hby", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: hby
+        });
+        Object.defineProperty(this, "registry", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: registry
+        });
+        Object.defineProperty(this, "exc", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: exc
+        });
+    }
+    /** Authenticate accepted outer evidence through existing replay, without current node policy. */
+    async accepted(said, route) {
+        const body = this.hby.db.exns.get([said]);
+        if (!body || body.said !== said || body.route !== route || body.pvrsn.major !== 2 || !this.exc.complete(said)) {
+            throw new ValidationError("Accepted ACDC v2 exchange at the exact route is required.");
+        }
+        for await (const _chunk of this.exc.replay(said)) { /* replay authenticates retained outer factors */ }
+        return body;
+    }
+    /** New use requires current node evidence and a valid root under shared issued-state policy. */
+    graphAccepted(grant, origin) {
+        if (!this.exc.verifyAccepted(grant, "/ipex/grant"))
+            return false;
+        const graph = walkIpexGraph(origin, loadNests(this.hby.db, grant), ipexGrantWalk(this.exc));
+        if (!graph)
+            return false;
+        const verdicts = new Map();
+        for (const [said, node] of graph.nodes) {
+            const auth = authenticateIpexNode(node.body, envelopeFromFrame(node), this.hby.db, this.registry);
+            verdicts.set(said, issuedNodeVerdict(auth));
+        }
+        return evaluateChain(graph, verdicts, this.hby.db)?.kind === "valid";
+    }
+    /** Resolve only the origin actually carried by this accepted Grant. */
+    origin(grant) {
+        const origins = grant.sad.a && grant.sad.a.o;
+        if (!Array.isArray(origins) || origins.length !== 1 || typeof origins[0] !== "string") {
+            throw new ValidationError("Wallet admission requires one disclosed origin.");
+        }
+        if (!loadNests(this.hby.db, grant.said).some((node) => node.body instanceof SerderACDC && node.body.said === origins[0])) {
+            throw new ValidationError("Accepted Grant origin is missing.");
+        }
+        return origins[0];
+    }
+    /** Freeze an unsigned response only after explicit consent, exact prior authentication and current root truth. */
+    *prepareAdmitBody(grant, holder, { consent = false, message = "", gvrsn = Vrsn_2_0 } = {}) {
+        if (consent !== true)
+            throw new ValidationError("Explicit consent is required.");
+        if (gvrsn.major < 2)
+            throw new ValidationError("ACDC v2 Admit requires attachment genus 2 or later.");
+        const g = yield* call(() => this.accepted(grant, "/ipex/grant")), hab = this.hby.habs.get(holder);
+        if (!hab || g.sad.ri !== holder)
+            throw new ValidationError("Grant must address the intended local holder.");
+        const response = this.hby.db.erpy.get([grant]);
+        if (response && this.exc.complete(response.qb64)) {
+            throw new ValidationError("Grant already has an accepted response.");
+        }
+        if (!this.graphAccepted(grant, this.origin(g))) {
+            throw new ValidationError("Current authenticated graph acceptance is required before signing.");
+        }
+        return ipexExnBody(holder, "/ipex/admit", [], { message, prior: g, gvrsn });
+    }
+    /** Sign an individual response; group approval consumes the same unsigned body through its own exact-stream owner. */
+    *prepareAdmit(grant, holder, { consent = false, message = "", gvrsn = Vrsn_2_0, receiptor, auths } = {}) {
+        if (consent !== true)
+            throw new ValidationError("Explicit consent is required.");
+        if (gvrsn.major < 2)
+            throw new ValidationError("ACDC v2 Admit requires attachment genus 2 or later.");
+        const hab = this.hby.habs.get(holder);
+        if (!hab)
+            throw new ValidationError("Grant must address the intended local holder.");
+        if (isLocalGroupHab(this.hby, hab)) {
+            throw new ValidationError("ACDC v2 wallet admission requires a single-signature holder.");
+        }
+        const admit = yield* this.prepareAdmitBody(grant, holder, { consent, message, gvrsn });
+        const anchored = admit.sad.a.ax?.[0] === true;
+        if (anchored && !receiptor)
+            throw new ValidationError("Anchored Admit requires its actual receipt owner.");
+        const source = anchored ? yield* anchorExchange(this.hby, receiptor, hab, admit, auths) : undefined;
+        if (!this.graphAccepted(grant, this.origin(this.hby.db.exns.get([grant])))) {
+            throw new ValidationError("Current authenticated graph acceptance is required after source receipts.");
+        }
+        return {
+            admit,
+            wire: exchangeWire(hab, admit, undefined, source, gvrsn),
+            support: source ? new IpexDiscloser(this.hby, this.registry, this.exc, receiptor).kel(hab) : new Uint8Array(),
+        };
+    }
+}

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

@@ -0,0 +1,197 @@
+/**
+ * Legacy (v1) IPEX conversation for a single-signature controller: send an
+ * apply, offer, agree or spurn, read where a conversation stands and observe it
+ * until the peer replies. Owned by the library so that every host (CLI, wallet,
+ * service) runs one implementation.
+ *
+ * Operations follow the workflow contract. `sendIpexApply`, `sendIpexOffer`,
+ * `sendIpexAgree` and `sendIpexSpurn` are explicit: each validates the accepted
+ * prior message, signs exactly one exchange, accepts it locally, hands it to the
+ * Poster and returns once that delivery attempt has an outcome. They never wait
+ * for the peer. `ipexExchangeStatus` is a pure synchronous read of durable
+ * state. `waitForIpexExchange` only observes: it starts no worker and returns a
+ * timed-out value instead of throwing.
+ *
+ * Boundaries:
+ * - Dependencies are narrow collaborators, not an AgentRuntime (ADR-0013). The
+ *   host owns their lifetimes and must be running the Poster worker so the
+ *   delivery attempt can complete (`withRuntimeWorkers` for a one-shot host).
+ * - Recipients arrive as resolved AIDs; contact lookup is a host concern.
+ * - Group controllers do not use these operations: their propose/approve split
+ *   needs the multisig coordinator, which the group proposal API will own.
+ * - Durable state records acceptance, not delivery, so there is no "sent but
+ *   unanswered" read distinct from `awaiting-reply`; a send's return value is
+ *   the evidence that it was sent.
+ */
+import { concatBytes, Counter } from "cesr-ts";
+import { sleep } from "effection";
+import { ValidationError } from "../../core/errors.js";
+import { exchange } from "../../core/exchange/protocol-exchanging.js";
+import { CREDENTIAL_MAILBOX_TOPIC } from "../../core/mailbox/mailbox-topics.js";
+import { isLocalGroupHab } from "../multisig/group-members.js";
+import { systemClock } from "../runtime/runtime-clock.js";
+import { credentialSaidFromGrant } from "./ipex-credentialing.js";
+import { sendCredentialStream } from "./ipex-grouping.js";
+import { IPEX_AGREE_ROUTE, IPEX_APPLY_ROUTE, IPEX_GRANT_ROUTE, IPEX_OFFER_ROUTE, IPEX_SPURN_ROUTE, validateIpexReply, } from "./ipexing.js";
+/**
+ * Require a local single-signature sender.
+ *
+ * @throws ValidationError when `sender` is not a local AID of `hby` or is a group AID.
+ */
+export function requireIpexSender(hby, sender) {
+    if (!sender.pre || hby.habs.get(sender.pre) !== sender) {
+        throw new ValidationError(`No local AID found for sender ${sender.pre || "<missing>"}.`);
+    }
+    if (isLocalGroupHab(hby, sender)) {
+        throw new ValidationError(`Sender ${sender.pre} is a group AID; single-signature IPEX operations do not apply.`);
+    }
+}
+/**
+ * Validate an accepted predecessor and its known parties before any local signing.
+ *
+ * @throws ValidationError when the prior is not accepted, has the wrong route or
+ * parties, or already has an accepted response.
+ */
+export function requireIpexPrior(hby, sender, recipient, said, verb) {
+    const prior = hby.db.exns.get([said]);
+    if (!prior)
+        throw new ValidationError("Prior IPEX exchange is not accepted.");
+    validateIpexReply(prior, verb, sender, recipient);
+    if (hby.db.erpy.get([said])) {
+        throw new ValidationError("Prior IPEX exchange already has an accepted response; resume the existing exchange.");
+    }
+}
+/**
+ * Accept one signed exchange locally and confirm it was accepted.
+ *
+ * @param wire Signed exchange followed by its attachments.
+ * @param refusal Message for the infrastructure failure of a local exchange that was not accepted.
+ * @param prior Said of the message this one answers; its status changes too.
+ */
+export function* acceptIpexExchange(deps, exn, wire, genus, refusal, prior) {
+    yield* deps.reactor.processBytes(concatBytes(Counter.makeGVC(genus), wire), { local: true });
+    yield* deps.protocol.processEscrowsOnce();
+    if (!deps.protocol.exc.complete(exn.said))
+        throw new ValidationError(refusal);
+    if (prior)
+        deps.changes?.push({ kind: "ipex", id: prior });
+    deps.changes?.push({ kind: "ipex", id: exn.said });
+}
+/**
+ * Sign one prepared exchange, accept it locally and deliver it. A spurn goes out
+ * as a one-message stream; every other verb as a queued message with a
+ * completion notice. A failed delivery outcome throws its original error; the
+ * accepted exchange stays stored.
+ */
+function* signAcceptAndSend(deps, sender, recipient, [exn, attachments], prior) {
+    const genus = exn.gvrsn ?? exn.pvrsn;
+    const wire = concatBytes(sender.endorse(exn, { pipelined: false, gvrsn: genus }), attachments);
+    yield* acceptIpexExchange(deps, exn, wire, genus, "Local IPEX exchange was not accepted.", prior);
+    if (exn.route === IPEX_SPURN_ROUTE) {
+        return { exn, deliveries: yield* sendCredentialStream(deps.postman, sender, recipient, [wire]) };
+    }
+    const evt = deps.postman.send({ src: sender.pre, dest: recipient, topic: CREDENTIAL_MAILBOX_TOPIC, msg: wire }, { notify: true });
+    const outcome = yield* deps.postman.wait(evt);
+    if (outcome.kin === "failed")
+        throw outcome.error;
+    return { exn, deliveries: outcome.deliveries };
+}
+/**
+ * Send an `/ipex/apply` asking `recipient` for a credential of `schema`.
+ * An apply starts a conversation, so there is no prior to validate and sending
+ * it twice sends two distinct applies.
+ *
+ * @throws ValidationError for a sender that is not a local single-signature AID or a refused local exchange.
+ */
+export function* sendIpexApply(deps, sender, { recipient, schema, attrs = {}, message = "" }) {
+    requireIpexSender(deps.hby, sender);
+    const prepared = exchange(IPEX_APPLY_ROUTE, { m: message, s: schema, a: attrs, i: recipient }, {
+        sender: sender.pre,
+        recipient,
+    });
+    return yield* signAcceptAndSend(deps, sender, recipient, prepared);
+}
+/**
+ * Send an `/ipex/offer` carrying one embedded ACDC, optionally answering an apply.
+ *
+ * @throws ValidationError as for {@link requireIpexPrior} when `apply` is given.
+ */
+export function* sendIpexOffer(deps, sender, { recipient, acdc, apply, message = "" }) {
+    requireIpexSender(deps.hby, sender);
+    if (apply)
+        requireIpexPrior(deps.hby, sender.pre, recipient, apply, "offer");
+    const prepared = exchange(IPEX_OFFER_ROUTE, { m: message }, {
+        sender: sender.pre,
+        recipient,
+        dig: apply,
+        embeds: { acdc },
+    });
+    return yield* signAcceptAndSend(deps, sender, recipient, prepared, apply || undefined);
+}
+/**
+ * Send an `/ipex/agree` answering an accepted offer.
+ *
+ * @throws ValidationError as for {@link requireIpexPrior}.
+ */
+export function* sendIpexAgree(deps, sender, { recipient, offer, message = "" }) {
+    requireIpexSender(deps.hby, sender);
+    requireIpexPrior(deps.hby, sender.pre, recipient, offer, "agree");
+    const prepared = exchange(IPEX_AGREE_ROUTE, { m: message }, { sender: sender.pre, recipient, dig: offer });
+    return yield* signAcceptAndSend(deps, sender, recipient, prepared, offer);
+}
+/**
+ * Send an `/ipex/spurn` rejecting an accepted apply, offer, agree or grant.
+ *
+ * @throws ValidationError as for {@link requireIpexPrior}.
+ */
+export function* sendIpexSpurn(deps, sender, { recipient, prior, message = "" }) {
+    requireIpexSender(deps.hby, sender);
+    requireIpexPrior(deps.hby, sender.pre, recipient, prior, "spurn");
+    const prepared = exchange(IPEX_SPURN_ROUTE, { m: message }, { sender: sender.pre, recipient, dig: prior });
+    return yield* signAcceptAndSend(deps, sender, recipient, prepared, prior);
+}
+/**
+ * Pure synchronous status of the accepted exchange `said`, derived from the
+ * exchange store, the reply index and (for grants) the saved-credential index.
+ * Mutates nothing.
+ */
+export function ipexExchangeStatus(deps, said) {
+    const exn = deps.hby.db.exns.get([said]);
+    if (!exn)
+        return { state: "unknown" };
+    const route = exn.route ?? "";
+    const credentialSaid = route === IPEX_GRANT_ROUTE ? credentialSaidFromGrant(exn) : null;
+    const credential = credentialSaid
+        ? { credential: { said: credentialSaid, saved: !!deps.reger.saved.get([credentialSaid]) } }
+        : {};
+    const response = deps.hby.db.erpy.get([said]);
+    if (!response)
+        return { state: "awaiting-reply", route, ...credential };
+    const replySaid = response.qb64;
+    const reply = { said: replySaid, route: deps.hby.db.exns.get([replySaid])?.route ?? null };
+    return { state: "replied", route, reply, ...credential };
+}
+function reached(status, until) {
+    if (until === "credential-saved")
+        return status.state !== "unknown" && !!status.credential?.saved;
+    return status.state === "replied";
+}
+/**
+ * Observe `said` until the wanted state holds or the budget expires. A wait
+ * that is already satisfied returns at once. Starts no worker: the host's own
+ * poller and escrow loop make the peer's reply or the credential arrive.
+ *
+ * @returns `settled`, or `timed-out`; both carry the status read at return.
+ */
+export function* waitForIpexExchange(deps, said, { timeoutMs, until = "replied", pollMs = 250, clock = systemClock }) {
+    const deadline = clock.now() + timeoutMs;
+    while (true) {
+        const status = ipexExchangeStatus(deps, said);
+        if (reached(status, until))
+            return { outcome: "settled", status };
+        const remaining = deadline - clock.now();
+        if (remaining <= 0)
+            return { outcome: "timed-out", status, timeoutMs };
+        yield* sleep(Math.min(pollMs, remaining));
+    }
+}