keri-ts 0.11.0 → 2.0.0

package/esm/keri/npm/src/app/{ipexing.js → ipex/ipexing.js}

@@ -1,4 +1,5 @@
-import { exchange } from "../core/protocol-exchanging.js";
+import { ValidationError } from "../../core/errors.js";
+import { exchange, isIpexVerb } from "../../core/exchange/protocol-exchanging.js";
 import { IpexV2Handler } from "./ipex-v2.js";
 /** KERIpy IPEX route constants. */
 export const IPEX_APPLY_ROUTE = "/ipex/apply";
@@ -110,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, options.maxRegistryEvents));
+        exchanger.addHandler(new IpexV2Handler(route, hby, options.notifier ?? null, options.registry ?? null));
     }
 }
 /** Apply for an ACDC. */
@@ -191,6 +192,62 @@ function requiredSaid(serder, label) {
 function rawMessage(message) {
     return message instanceof Uint8Array ? message : message.raw;
 }
+/** Validate known signed response parties and the existing legacy predecessor graph. */
+export function validateIpexReply(prior, verb, sender, recipient) {
+    if (!(PREVIOUS_IPEX_ROUTES.get(verb) ?? []).some(route => prior.route === `/ipex/${route}`)) {
+        throw new ValidationError("Prior IPEX exchange is missing or has the wrong route.");
+    }
+    const intended = ipexRecipient(prior);
+    if (prior.pre !== recipient || (intended && intended !== sender)) {
+        throw new ValidationError("IPEX response parties do not match the accepted prior exchange.");
+    }
+}
+/**
+ * Preflight a proposed legacy conversation before a member adds a signature.
+ * Missing accepted predecessors stay pending; malformed routes, changed parties
+ * and replacement responses fail. This does not admit an EXN or change its indexes.
+ */
+export function ipexConversationReady(db, exn) {
+    const verb = ipexVerbForRoute(exn.route ?? "");
+    if (!verb || !exn.pre || exn.pvrsn.major !== 1)
+        throw new ValidationError("Unsupported IPEX conversation profile.");
+    const said = priorSaid(exn);
+    if (!said) {
+        if (!STARTABLE_WITHOUT_PRIOR.has(verb))
+            throw new ValidationError("IPEX response requires its predecessor.");
+        if (!ipexRecipient(exn))
+            throw new ValidationError("IPEX proposal is missing its recipient.");
+        return true;
+    }
+    const prior = db.exns.get([said]);
+    if (!prior)
+        return false;
+    const recipient = ipexRecipient(exn, prior);
+    if (!recipient)
+        throw new ValidationError("IPEX proposal is missing its recipient.");
+    validateIpexReply(prior, verb, exn.pre, recipient);
+    const response = db.erpy.get([said]);
+    if (response && response.qb64 !== exn.said) {
+        throw new ValidationError("Prior IPEX exchange already has another accepted response.");
+    }
+    return true;
+}
+/**
+ * Resolve signed recipient data, or the sender of an accepted linked predecessor.
+ * Legacy admit/agree/spurn builders omit an explicit recipient. Callers loading
+ * a predecessor must supply it from accepted storage; this helper does not admit it.
+ */
+export function ipexRecipient(exn, prior) {
+    const rp = exn.ked?.rp;
+    if (typeof rp === "string" && rp.length > 0)
+        return rp;
+    const attrs = exn.ked?.a;
+    if (isRecord(attrs) && typeof attrs.i === "string" && attrs.i.length > 0)
+        return attrs.i;
+    if (prior?.said && priorSaid(exn) === prior.said)
+        return prior.pre || null;
+    return null;
+}
 function priorSaid(serder) {
     const prior = serder.ked?.p;
     return typeof prior === "string" ? prior : "";
@@ -203,14 +260,6 @@ function ipexVerbForRoute(route) {
     const verb = parts[2];
     return isIpexVerb(verb) ? verb : null;
 }
-function isIpexVerb(value) {
-    return value === "apply"
-        || value === "offer"
-        || value === "agree"
-        || value === "grant"
-        || value === "admit"
-        || value === "spurn";
-}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/esm/keri/npm/src/app/mailbox/forward-handler.js

@@ -0,0 +1,228 @@
+/** Authenticated /fwd intake: validate provider authority before storing reconstructed child bytes. */
+import { collectPayload, concatBytes, Counter, Diger, nestedPayload, parsePather, SerderACDC, SerderKERI, Vrsn_2_0, } from "cesr-ts";
+import { Roles } from "../../core/roles.js";
+import { abortable } from "../runtime/abortable.js";
+/**
+ * Accepted `/fwd` route handler that stores embedded payloads in mailbox topics.
+ *
+ * This is the `keri-ts` mailbox-storage analogue to KERIpy's `ForwardHandler`.
+ *
+ * Authorization rule:
+ * - the request-scoped mailbox AID passed with this message must currently be
+ *   authorized for the addressed recipient
+ */
+export class ForwardHandler {
+    /**
+     * Bind mailbox publication without acquiring a store.
+     *
+     * @param mailboxDirector Borrowed provider owner that publishes accepted forwarded payloads.
+     */
+    constructor(mailboxDirector) {
+        /** Instance route identity used by exchange dispatch. */
+        Object.defineProperty(this, "resource", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: ForwardHandler.resource
+        });
+        /** This route binds a single v2 child body; recipient processors authenticate its evidence. */
+        Object.defineProperty(this, "acceptsNests", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: true
+        });
+        /** Borrowed provider publication/correlation owner. */
+        Object.defineProperty(this, "mailboxDirector", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.mailboxDirector = mailboxDirector;
+    }
+    /**
+     * Verify that the embedded exchange has the mailbox modifiers and one
+     * extractable forwarded payload.
+     *
+     * @param args Signed forwarding exchange, attachment evidence and optional nested frames; children retain their own authentication requirements.
+     * @returns Whether required modifiers and one bound forwarded payload are structurally valid.
+     */
+    verify(args) {
+        const modifiers = args.serder.ked?.q;
+        if (typeof modifiers?.pre !== "string" || typeof modifiers?.topic !== "string")
+            return false;
+        if (args.serder.pvrsn.major < 2) {
+            return !args.nests?.length && extractForwardedMessage(args.serder, args.attachments) !== null;
+        }
+        if (args.nests?.length !== 1)
+            return false;
+        const signed = args.serder.a?.evt;
+        const child = args.nests[0].body;
+        if (typeof signed !== "string" || !(child instanceof SerderKERI || child instanceof SerderACDC))
+            return false;
+        try {
+            return child.verify() && new Diger({ qb64: signed }).verify(child.raw);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Store one forwarded payload when the receiving host is allowed to act as
+     * the recipient's async correspondence store.
+     *
+     * Accepted host shapes:
+     * - explicit mailbox provider authorized in `ends.`
+     * - recipient witness host from the accepted KEL witness set
+     * - recipient agent host authorized in `ends.`
+     *
+     * Controller endpoints stay excluded here because they are direct
+     * correspondence destinations, not store-and-forward hosts.
+     *
+     * @param args Accepted exchange with borrowed attachments/children and receiving mailboxAid provenance.
+     * @returns An operation for v2 child serialization, or synchronous completion/no-op for legacy or unauthorized input.
+     */
+    handle(args) {
+        const modifiers = args.serder.ked?.q;
+        const recipient = typeof modifiers?.pre === "string" ? modifiers.pre : null;
+        const topic = typeof modifiers?.topic === "string" ? modifiers.topic : null;
+        const child = args.serder.pvrsn.major >= 2 ? args.nests?.[0] : undefined;
+        const forwarded = child ? null : extractForwardedMessage(args.serder, args.attachments);
+        const mailboxAid = args.mailboxAid;
+        if (!recipient || !topic || (!child && !forwarded)) {
+            return;
+        }
+        if (!this.canStoreRecipient(recipient, mailboxAid))
+            return;
+        if (child) {
+            // Mailbox LMDB accepts a finite row; collect one child, never the whole exchange stream.
+            return abortable(async (signal) => {
+                const wire = await collectPayload(nestedPayload(child, Vrsn_2_0), signal);
+                signal.throwIfAborted();
+                if (this.canStoreRecipient(recipient, mailboxAid))
+                    this.mailboxDirector.publish(recipient, topic, wire);
+            });
+        }
+        this.mailboxDirector.publish(recipient, topic, forwarded);
+    }
+    /** Re-read accepted authority in the same synchronous turn as provider publication. */
+    canStoreRecipient(recipient, mailboxAid) {
+        const hby = this.mailboxDirector.hby;
+        const kever = hby.db.getKever(recipient);
+        if (!kever)
+            return false;
+        if (mailboxAid)
+            return hostCanStoreForwardRecipient(hby, recipient, kever, mailboxAid);
+        return hasLocalStoreForwardHost(hby, recipient, kever);
+    }
+}
+/** Registered exchange route for store-forward messages. */
+Object.defineProperty(ForwardHandler, "resource", {
+    enumerable: true,
+    configurable: true,
+    writable: true,
+    value: "/fwd"
+});
+/**
+ * Check recipient-specific store-forward authority without treating a controller endpoint as a mailbox.
+ *
+ * @param hby Borrowed local habitat collection and accepted-state database.
+ * @param recipient Final recipient AID.
+ * @param recipientKever Accepted recipient state supplying its current witness cohort.
+ * @param hostAid Receiving endpoint AID whose witness/mailbox/agent authority is checked.
+ * @returns True when current accepted witness or endpoint-role state authorizes a local store-forward host.
+ */
+function hostCanStoreForwardRecipient(hby, recipient, recipientKever, hostAid) {
+    // A local host may store forwarded traffic only when it is an authorized
+    // witness/mailbox/agent for the recipient. This keeps mailbox storage from
+    // becoming a generic unauthenticated relay.
+    if (recipientKever.wits.includes(hostAid)) {
+        return true;
+    }
+    for (const role of [Roles.mailbox, Roles.agent]) {
+        const end = hby.db.ends.get([recipient, role, hostAid]);
+        if (end?.allowed || end?.enabled) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Check recipient-specific store-forward authority without treating a controller endpoint as a mailbox.
+ *
+ * @param hby Borrowed local habitat collection and accepted-state database.
+ * @param recipient Final recipient AID.
+ * @param recipientKever Accepted recipient state supplying its current witness cohort.
+ * @returns True when current accepted witness or endpoint-role state authorizes a local store-forward host.
+ */
+function hasLocalStoreForwardHost(hby, recipient, recipientKever) {
+    // Check all local prefixes because a multi-role runtime can host a mailbox
+    // AID that is distinct from the controller currently processing the EXN.
+    for (const hostAid of hby.db.prefixes) {
+        if (hostCanStoreForwardRecipient(hby, recipient, recipientKever, hostAid)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Reconstruct legacy forwarded wire without assigning outer attachments to the child.
+ *
+ * @param serder Legacy forwarding exchange containing an e.evt body.
+ * @param attachments Pathed attachments; only /e/evt material belongs to the embedded message.
+ * @returns Reconstructed child wire, or null without an embedded event.
+ */
+function extractForwardedMessage(serder, attachments) {
+    const embeds = serder.ked?.e;
+    const evt = embeds?.evt;
+    if (!evt || typeof evt !== "object" || Array.isArray(evt)) {
+        return null;
+    }
+    // Rebuild the embedded event from SAD plus only the attachment material
+    // pathed to `/e/evt`; other pathed groups belong to the outer `/fwd` message.
+    const embedded = embeddedSerderRaw(evt);
+    const messageParts = [embedded];
+    for (const attachment of attachments) {
+        const atc = forwardedAttachmentForPath(attachment.raw, "/e/evt");
+        if (atc) {
+            messageParts.push(atc);
+        }
+    }
+    return concatBytes(...messageParts);
+}
+/**
+ * Serialize one legacy embedded body according to its declared protocol.
+ *
+ * @param sad Embedded self-addressing data; version prefix selects ACDC versus KERI serialization.
+ * @returns Serialized embedded body bytes; caller owns attachment reconstruction.
+ */
+function embeddedSerderRaw(sad) {
+    const version = typeof sad.v === "string" ? sad.v : "";
+    if (version.startsWith("ACDC")) {
+        return new SerderACDC({ sad, verify: false }).raw;
+    }
+    return new SerderKERI({ sad }).raw;
+}
+/**
+ * Extract the forwarded attachment bytes for the embedded `/e/evt` path.
+ *
+ * Forwarded attachment groups can carry multiple pathed attachments, so the
+ * path filter keeps mailbox reconstruction focused on the embedded event.
+ *
+ * @param raw One qualified pathed attachment group in text-domain bytes.
+ * @param path Exact embedded SAD path to match.
+ * @returns Attachment bytes after the matching pather, or null for a different/empty group.
+ */
+function forwardedAttachmentForPath(raw, path) {
+    if (raw.length === 0) {
+        return null;
+    }
+    const counter = new Counter({ qb64b: raw });
+    const offset = counter.fullSize;
+    const pather = parsePather(raw.slice(offset), "txt");
+    if (pather.path !== path) {
+        return null;
+    }
+    return raw.slice(offset + pather.fullSize);
+}