keri-ts 2.2.4 → 2.2.5

package/esm/keri/npm/src/app/ipex/unblinding-workflow.js

@@ -186,14 +186,16 @@ export class UnblindingOperations {
     }
     /**
      * Whether a pass has work: a live operation, or an owner holds an authenticated peer query whose reply is
-     * owed (an in-memory walk of the owners, no store read).
+     * owed (an in-memory walk of the owners, no store read). Finding what is owed reprocesses held queries, which
+     * answers them (signs), so an owner whose habitat cannot sign yet is skipped here as it is in `adopt`.
      */
     active() {
         if (this.live.size > 0)
             return true;
-        for (const owner of this.deps.unblinds.unblindOwners())
-            if (owner.awaitingReply().length)
+        for (const owner of this.deps.unblinds.unblindOwners()) {
+            if (owner.hab.canSign() && owner.awaitingReply().length)
                 return true;
+        }
         return false;
     }
     /** Advance every live operation by one pass, each bounded by its Grant deadline. */
@@ -208,6 +210,9 @@ export class UnblindingOperations {
                 const left = op.expires - BigInt(deps.clock.now()) * 1000n;
                 if (left <= 0n)
                     this.end(op, "expired", this.expiry(op));
+                // A habitat that cannot sign yet waits for its signer; only its Grant deadline ends the operation meanwhile.
+                else if (!op.hab.canSign())
+                    continue;
                 else if ((yield* race([this.advance(op), this.timer(Number(left) / 1000)])) === "expired") {
                     this.end(op, "expired", this.expiry(op));
                 }
@@ -233,6 +238,10 @@ export class UnblindingOperations {
     adopt() {
         const { deps } = this;
         for (const owner of deps.unblinds.unblindOwners()) {
+            // Finding what is owed reprocesses held queries, which answers them (signs); an owner whose habitat cannot
+            // sign yet is asked on a later pass.
+            if (!owner.hab.canSign())
+                continue;
             for (const { xid, grant } of owner.awaitingReply()) {
                 if (this.live.has(unblindingKey(grant, "responder")))
                     continue;
@@ -297,6 +306,10 @@ export class UnblindingOperations {
             this.end(op, "abandoned", reason);
         return bound.map(op => op.grant);
     }
+    /** Grants of the live Unblind operations whose habitat is `pre`. */
+    grantsOf(pre) {
+        return [...new Set([...this.live.values()].filter(op => op.hab.pre === pre).map(op => op.grant))];
+    }
     /** Drop the live entry and the owner's approval and frozen messages; delivered bytes stay the peer's. */
     release(op) {
         this.live.delete(unblindingKey(op.grant, op.role));

package/esm/keri/npm/src/app/mailbox/agent-inbox.js

@@ -0,0 +1,292 @@
+/**
+ * The host's inbox rules: what a host keeps for pickup by an identifier that runs elsewhere, under the storing roles
+ * it honours (`mailbox` and `agent`), and which raw arrivals it keeps for an identifier that authorized it as `agent`.
+ *
+ * A KERIpy or KERIA sender reaches an agent with `sendDirect`: one bare signed message per request, no `/fwd`, no
+ * topic and often no recipient (keripy forwarding.py `Poster.deliverDo`; keria indirecting.py `HttpEnd.on_post`).
+ * The agent processes that message as its own input (dispatch is the single ingest). For an identifier that runs
+ * elsewhere (an edge) and authorized this host as its agent, the host also keeps one copy in the edge's mailbox
+ * topic, where the edge polls it. This module decides that copy and writes it; it owns no store and no registry and
+ * reads only accepted `ends.` rows, local habitats and accepted key state.
+ *
+ * A `/fwd` names its recipient and topic; the forward handler stores it under {@link keepsForPickup} and
+ * {@link ownTraffic}. A raw arrival is kept only under the `agent` role: a sender reaches a `mailbox` with `/fwd`.
+ *
+ * Raw-arrival rules:
+ * - Principal: an identifier with an allowed or enabled `ends.[cid, agent, host]` row.
+ * - With a named recipient R, the one principal is R when it authorized the host as agent and
+ *   {@link keepsForPickup}; otherwise nothing is kept.
+ * - With no named recipient, every principal that is not a local habitat (a local group is processed by its hosted
+ *   co-member through dispatch, so the edge receives one copy under its member AID).
+ * - Never kept: {@link ownTraffic}, a message whose originator is a local habitat, a principal of the host, or a
+ *   member of the recipient group (an edge's own traffic, or a local group's own events); and a message whose topic,
+ *   derived from its remote route, the mailbox store cannot key.
+ * - Kept only when the body verifies its SAID, carries attached authentication, and the agent's own processor
+ *   decided it ({@link keptDecision}). The edge is the verifier of signatures and state and re-verifies everything,
+ *   so a decision that waits on state is kept: `accept`, `escrow`, KRAM `pending`/`missing` and an `unverified`
+ *   reply. The agent never keeps what it could not decode: dispatch refuses malformed field values as a typed
+ *   `reject` or `drop` before any escrow decision (`core/wire-fields.ts`), and those are not kept; nor is a message
+ *   no processor decided, except a receipt, whose processor decodes it and reports none.
+ */
+import { collectPayload, framePayload, Ilks, SerderACDC, SerderKERI, } from "cesr-ts";
+import { CREDENTIAL_MAILBOX_TOPIC, DELEGATE_MAILBOX_TOPIC, RECEIPT_MAILBOX_TOPIC, REPLAY_MAILBOX_TOPIC, REPLY_MAILBOX_TOPIC, } from "../../core/mailbox/mailbox-topics.js";
+import { Roles } from "../../core/roles.js";
+import { storableTopic } from "../../db/mailbox/mailboxing.js";
+import { isAcceptedGroupMember } from "../multisig/group-members.js";
+import { envelopeFromFrame } from "../protocol/parsering.js";
+import { abortable } from "../runtime/abortable.js";
+import { mailboxTopicKey } from "./mailboxing.js";
+import { mailboxTopicForRoute } from "./topic-routing.js";
+/**
+ * Whether `cid` authorized `hostAid` under a storing role: row `ends.[cid, mailbox, hostAid]` or
+ * `ends.[cid, agent, hostAid]`, allowed or enabled. Witness membership is not a storing role here.
+ *
+ * @param hby Borrowed local habitat collection and accepted-state database.
+ * @param cid Identifier whose end-role authorization is read.
+ * @param hostAid Endpoint AID the role must name.
+ * @returns True when either row authorizes the host.
+ */
+export function authorizedStoringHost(hby, cid, hostAid) {
+    return [Roles.mailbox, Roles.agent].some((role) => {
+        const end = hby.db.ends.get([cid, role, hostAid]);
+        return !!(end?.allowed || end?.enabled);
+    });
+}
+/**
+ * Whether `cid` authorized `hostAid` as its agent: row `ends.[cid, agent, hostAid]`, allowed or enabled.
+ *
+ * @param hby Borrowed local habitat collection and accepted-state database.
+ * @param cid Identifier whose end-role authorization is read.
+ * @param hostAid Local endpoint AID the role must name.
+ * @returns True when the accepted row authorizes the host.
+ */
+export function authorizedAgent(hby, cid, hostAid) {
+    const end = hby.db.ends.get([cid, Roles.agent, hostAid]);
+    return !!(end?.allowed || end?.enabled);
+}
+/**
+ * Whether this host keeps mail for pickup for `recipient`: the recipient authorized it under a storing role
+ * ({@link authorizedStoringHost}) and is either remote (an edge) or a local group (whose remote members poll the
+ * group's mailbox). A local single-sig habitat processes its own mail here and has nobody to pick it up.
+ *
+ * @param hby Borrowed local habitat collection and accepted-state database.
+ * @param recipient Identifier the message is addressed to.
+ * @param hostAid Local endpoint AID that received the message.
+ * @returns True when the host keeps a copy in the recipient's mailbox.
+ */
+export function keepsForPickup(hby, recipient, hostAid) {
+    return authorizedStoringHost(hby, recipient, hostAid) && (!hby.habs.has(recipient) || hby.db.groups.has(recipient));
+}
+/**
+ * Whether a message is traffic of the very identifiers that would pick it up, which is never kept: its originator
+ * is a local habitat, authorized `hostAid` as agent, or is an accepted member of the recipient group (the edge
+ * member that polls the group's mailbox). An edge does not pick up what it sent, and a local group's own events
+ * reach its remote members through their own exchanges.
+ *
+ * @param hby Borrowed local habitat collection and accepted-state database.
+ * @param originator The message's own `i` (an ACDC's issuer), or null when it names none.
+ * @param recipient Named recipient, or null when the message names none.
+ * @param hostAid Local endpoint AID that received the message.
+ * @returns True when the message must not be kept.
+ */
+export function ownTraffic(hby, originator, recipient, hostAid) {
+    if (!originator)
+        return false;
+    if (hby.habs.has(originator) || authorizedAgent(hby, originator, hostAid))
+        return true;
+    return recipient !== null && hby.db.groups.has(recipient) && isAcceptedGroupMember(hby.db, recipient, originator);
+}
+/**
+ * The recipient a raw message names, or null when it names none.
+ *
+ * An exn or xip names it in `rp` (v1) or `ri` (v2) when non-empty. A delegated event is addressed to its delegator:
+ * a `dip` carries it in `di`; a `drt` carries no `di`, so its delegator is read from the delegate's accepted key
+ * state (dispatch has already run, so a `drt` the agent accepted or escrowed has its `dip` behind it).
+ *
+ * @param hby Borrowed accepted-state database, read only for a `drt`'s delegator.
+ * @param serder Raw message body.
+ * @returns Named recipient AID, or null.
+ */
+export function rawRecipient(hby, serder) {
+    switch (serder.ilk) {
+        case Ilks.exn:
+        case Ilks.xip: {
+            const named = serder.ked?.rp ?? serder.ked?.ri;
+            return typeof named === "string" && named.length > 0 ? named : null;
+        }
+        case Ilks.dip:
+            return serder.delpre;
+        case Ilks.drt:
+            return serder.pre ? hby.db.getKever(serder.pre)?.delpre ?? null : null;
+        default:
+            return null;
+    }
+}
+/**
+ * Mailbox topic for a raw message; null means it is never kept.
+ *
+ * | body | topic |
+ * | --- | --- |
+ * | exn/xip | `mailboxTopicForRoute(route)` |
+ * | exn `/fwd`, qry, other ilks | null (host-addressed transport or nothing to pick up) |
+ * | dip/drt addressed to its delegator | `/delegate` |
+ * | other KEL events | `/replay` |
+ * | rct | `/receipt` |
+ * | rpy | `/reply` |
+ * | TEL events and ACDC bodies | `/credential` |
+ *
+ * @param body Raw message body.
+ * @param recipient Recipient from {@link rawRecipient}; for a dip/drt, its delegator.
+ * @returns Mailbox topic, or null.
+ */
+export function rawMailboxTopic(body, recipient) {
+    if (body instanceof SerderACDC)
+        return CREDENTIAL_MAILBOX_TOPIC;
+    switch (body.ilk) {
+        case Ilks.exn:
+        case Ilks.xip: {
+            if (body.route === "/fwd")
+                return null;
+            const topic = mailboxTopicForRoute(body.route ?? "");
+            return topic.length > 0 ? topic : null;
+        }
+        case Ilks.dip:
+        case Ilks.drt:
+            return recipient !== null ? DELEGATE_MAILBOX_TOPIC : REPLAY_MAILBOX_TOPIC;
+        case Ilks.icp:
+        case Ilks.rot:
+        case Ilks.ixn:
+            return REPLAY_MAILBOX_TOPIC;
+        case Ilks.rct:
+            return RECEIPT_MAILBOX_TOPIC;
+        case Ilks.rpy:
+            return REPLY_MAILBOX_TOPIC;
+        case Ilks.vcp:
+        case Ilks.vrt:
+        case Ilks.iss:
+        case Ilks.rev:
+        case Ilks.bis:
+        case Ilks.brv:
+            return CREDENTIAL_MAILBOX_TOPIC;
+        default:
+            return null;
+    }
+}
+/**
+ * Store one dispatched raw arrival once for each of its principals (see the module rules).
+ *
+ * @param director Borrowed mailbox owner; a host without a mailbox store keeps nothing.
+ * @param arrival The dispatched frame, its host and the agent's decision.
+ * @returns Number of mailbox entries written.
+ */
+export function* keepRawArrival(director, arrival) {
+    const hby = director.hby;
+    const body = arrival.frame.body;
+    if (!director.mailboxer || !(body instanceof SerderKERI || body instanceof SerderACDC))
+        return 0;
+    if (!keptDecision(body, arrival.decision) || !saidVerifies(body))
+        return 0;
+    const recipient = body instanceof SerderKERI ? rawRecipient(hby, body) : null;
+    const topic = rawMailboxTopic(body, recipient);
+    if (topic === null || !authenticated(arrival.frame))
+        return 0;
+    const originator = body instanceof SerderKERI ? body.pre : body.issuer;
+    if (!rawPrincipals(hby, originator, recipient, arrival.hostAid).length)
+        return 0;
+    const wire = yield* abortable((signal) => collectPayload(framePayload(arrival.frame), signal));
+    // Re-read accepted authority in the same synchronous turn as publication. The topic comes from a remote route; one
+    // the mailbox store cannot key is not kept, never a store fault.
+    const principals = rawPrincipals(hby, originator, recipient, arrival.hostAid)
+        .filter((principal) => storableTopic(mailboxTopicKey(principal, topic)));
+    for (const principal of principals)
+        director.publish(principal, topic, wire);
+    return principals.length;
+}
+/**
+ * The principals one raw arrival is kept for, from current accepted state; empty when it is never kept.
+ *
+ * @param hby Borrowed local habitat collection and accepted-state database.
+ * @param originator The message's own `i` (an ACDC's issuer), or null.
+ * @param recipient Named recipient from {@link rawRecipient}, or null.
+ * @param hostAid Local endpoint AID that received the message.
+ * @returns Principals to publish under, in a stable order.
+ */
+function rawPrincipals(hby, originator, recipient, hostAid) {
+    if (ownTraffic(hby, originator, recipient, hostAid))
+        return [];
+    if (recipient !== null) {
+        return authorizedAgent(hby, recipient, hostAid) && keepsForPickup(hby, recipient, hostAid) ? [recipient] : [];
+    }
+    return agentPrincipals(hby, hostAid);
+}
+/**
+ * Every remote identifier that authorized `hostAid` as its agent.
+ *
+ * `ends.` is keyed cid-first with no reverse index, so this scans every row; it runs only for a message that names
+ * no recipient. One Habery serves one account downstream, so the table is that account's contacts' roles.
+ *
+ * @param hby Borrowed local habitat collection and accepted-state database.
+ * @param hostAid Local endpoint AID.
+ * @returns Principals in stored key order.
+ */
+function agentPrincipals(hby, hostAid) {
+    const cids = [];
+    for (const [[cid, role, eid], end] of hby.db.ends.getTopItemIter()) {
+        if (role === Roles.agent && eid === hostAid && (end.allowed || end.enabled) && !hby.habs.has(cid))
+            cids.push(cid);
+    }
+    return cids;
+}
+/**
+ * Whether the agent's decision shows it decoded the message and leaves it worth delivering: decided by a processor,
+ * not refused, and not a repeat of what it holds. See the module rules.
+ *
+ * Malformed fields are the dispatch processors' typed `reject` or `drop`; this reads only the decision they return.
+ *
+ * @param body Dispatched message body.
+ * @param decision Dispatch decision; undefined when no processor reported one.
+ * @returns True for `accept`, `escrow`, `pending`, `missing` and `unverified`, and for a receipt with no decision;
+ *   false otherwise.
+ */
+function keptDecision(body, decision) {
+    if (!decision)
+        return body instanceof SerderKERI && body.ilk === Ilks.rct;
+    switch (decision.kind) {
+        case "accept":
+        case "escrow":
+        case "pending":
+        case "missing":
+        case "unverified":
+            return true;
+        default:
+            return false;
+    }
+}
+/** Whether the body's SAID matches its content. */
+function saidVerifies(body) {
+    try {
+        return body.verify();
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Whether the frame carries any attached signature, receipt or seal-source authentication.
+ *
+ * @param frame Dispatched frame.
+ * @returns True when the normalized attachments include authentication material.
+ */
+function authenticated(frame) {
+    const envelope = envelopeFromFrame(frame);
+    return [
+        envelope.sigers,
+        envelope.wigers,
+        envelope.cigars,
+        envelope.trqs,
+        envelope.tsgs,
+        envelope.ssgs,
+        envelope.sscs,
+        envelope.ssts,
+    ].some((material) => material.length > 0);
+}