keri-ts 2.2.4 → 2.2.6

package/esm/keri/npm/src/app/bootstrap/oobiery.js

@@ -1,4 +1,4 @@
-import { Ilks, Prefixer, SerderKERI } from "cesr-ts";
+import { Ilks, ParserError, Prefixer, SerderKERI, WireParseError } from "cesr-ts";
 import { call, resource, scoped } from "effection";
 import { ValidationError } from "../../core/errors.js";
 import { exchange } from "../../core/exchange/protocol-exchanging.js";
@@ -6,13 +6,31 @@ import { OOBI_MAILBOX_TOPIC } from "../../core/mailbox/mailbox-topics.js";
 import { Roles } from "../../core/roles.js";
 import { acceptReplyDecision, unverifiedReplyDecision } from "../../core/routing.js";
 import { Schemer } from "../../core/scheming.js";
+import { isRelayOrigin, relayAuthorized, relayEndpoint, RelayOnlyError, relayRefusal, } from "../delivery/relaying.js";
 import { persistResolvedContact } from "../identity/organizing.js";
+import { servingHost } from "../mailbox/forward-handler.js";
 import { abortable } from "../runtime/abortable.js";
 import { doEveryOnWrite, PROTOCOL_PACING } from "../runtime/doing.js";
 import { systemClock } from "../runtime/runtime-clock.js";
 import { collectBytes } from "../transport/byte-source.js";
+import { isRequestableHttpUrl } from "../transport/http-client.js";
 import { processMessages } from "../transport/message-source.js";
+import { TransportError } from "../transport/transport-error.js";
 export const OOBI_REQUEST_ROUTE = "/oobis";
+/**
+ * How long an edge's OOBI job waits for its relay to hold the answer before it fails: 30 seconds, measured from the
+ * job's first relay attempt on the composed clock. It matches KERIpy's `Oobiery.RetryDelay` and the default
+ * `bootstrapOobis` timeout; the keri-ts Oobiery has no other retry, and a direct fetch fails on its first non-OK
+ * answer.
+ */
+export const RELAY_OOBI_TIMEOUT_MS = 30_000;
+/** Job states of an OOBI an edge resolves through its relay; any other state starts a new relay wait. */
+const RelayOobiStates = Object.freeze({
+    /** Waiting; the relay has not been asked yet (its location or a serving authorization is missing). */
+    pending: "relay-pending",
+    /** Waiting; the relay was asked with `/oobis` and has not answered with the result yet. */
+    requested: "relay-requested",
+});
 /**
  * Return the current terminal state projection for one requested OOBI URL.
  *
@@ -49,6 +67,29 @@ export function oobiTerminalState(db, url, kind = queueKindFor(url)) {
     }
     return { status: "pending", via: "none", record: null };
 }
+/**
+ * Classify an error that ended one OOBI or authentication job: the {@link OobiJobFailure} a remote party can cause,
+ * or null for a fault that must propagate and end the runtime (a store error such as `DatabaseError`, corrupt
+ * durable state, a programmer error such as `TypeError`, a plain `Error`).
+ *
+ * Limits: a cesr `ParserError`, `SyntaxError` or `RangeError` raised while decoding local stored state during the
+ * same dispatch is indistinguishable by class from one raised by a remote field, so it also ends only that job.
+ *
+ * @param error What escaped the job's request or response ingestion.
+ * @returns The failure to record, or null to rethrow.
+ */
+export function oobiJobFailure(error) {
+    if (error instanceof RelayOnlyError)
+        return "egress-refused";
+    if (error instanceof TransportError)
+        return "transport-failed";
+    if (error instanceof WireParseError)
+        return "unparseable-response";
+    if (error instanceof ParserError || error instanceof SyntaxError || error instanceof RangeError) {
+        return "invalid-response-frame";
+    }
+    return null;
+}
 /**
  * Durable OOBI processing component for one `Habery`.
  *
@@ -71,10 +112,11 @@ export class Oobiery {
      * @param rvy Actual shared reply verifier used for OOBI reply proof persistence.
      * @param http Borrowed HTTP implementation selected by composition.
      * @param cues Required application result Deck supplied by composition.
+     * @param relaying Relay collaborators of an edge runtime; null (a forwarder) resolves every OOBI directly.
      */
     constructor(hby, protocol, 
     /** Borrowed reply verifier; route installation and proof writes share this owner. */
-    rvy, http, cues) {
+    rvy, http, cues, relaying = null) {
         Object.defineProperty(this, "protocol", {
             enumerable: true,
             configurable: true,
@@ -115,6 +157,13 @@ export class Oobiery {
             writable: true,
             value: void 0
         });
+        /** Relay collaborators of an edge; null resolves every OOBI directly. */
+        Object.defineProperty(this, "relaying", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         /** Prevent overlapping passes over this owner's durable job queue. */
         Object.defineProperty(this, "active", {
             enumerable: true,
@@ -122,6 +171,16 @@ export class Oobiery {
             writable: true,
             value: false
         });
+        /**
+         * URL of the last job handled with a relay, so a job left waiting does not starve the jobs after it: the next
+         * pass takes the first queued URL after this one. Always null without a relay.
+         */
+        Object.defineProperty(this, "relayCursor", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: null
+        });
         this.hby = hby;
         this.kvy = protocol.makeKevery();
         if (this.kvy.db !== hby.db || this.kvy.rvy !== rvy) {
@@ -129,6 +188,7 @@ export class Oobiery {
         }
         this.cues = cues;
         this.http = http;
+        this.relaying = relaying;
     }
     /**
      * Register `/introduce` on the shared reply router.
@@ -209,16 +269,24 @@ export class Oobiery {
     *oobiDo(clock = systemClock, pacing = PROTOCOL_PACING) {
         return yield* doEveryOnWrite(clock, pacing, this.hby.db, () => this.processOnce());
     }
-    /** Select queued work, including a surviving in-flight row whose former process is gone. */
+    /**
+     * Select queued work, including a surviving in-flight row whose former process is gone. After a relay job, the
+     * first queued URL after it is taken, wrapping around, so jobs waiting on the relay take turns.
+     */
     nextQueued() {
+        const after = this.relayCursor;
+        let first = null;
         for (const store of [this.hby.db.oobis, this.hby.db.coobi]) {
             for (const [keys, record] of store.getTopItemIter()) {
                 const url = keys[0];
-                if (url)
+                if (!url)
+                    continue;
+                if (after === null || url > after)
                     return ["oobis", url, record];
+                first ??= ["oobis", url, record];
             }
         }
-        return null;
+        return first;
     }
     /** Select a parent only after its current child attempts, including authentication, settle. */
     nextReadyMoobi() {
@@ -238,7 +306,7 @@ export class Oobiery {
      * Stores touched:
      * - `oobis.` / `woobi.` as the durable queued worklists
      * - `coobi.` while a fetched response is being processed
-     * - `eoobi.` on HTTP failure
+     * - `eoobi.` on HTTP failure or an {@link OobiJobFailure}; the queued row is removed so it is not re-read
      * - `roobi.` after parser/routing success
      *
      * @param kind Durable OOBI queue family identifying the job path.
@@ -246,6 +314,17 @@ export class Oobiery {
      * @param record Pending durable job; retained through failure and joined cleanup.
      */
     *processJob(kind, url, record) {
+        if (!isRequestableHttpUrl(url)) {
+            // Neither this host nor a relay can fetch it; fail it before any request instead of on every pass.
+            this.remQueueStore(kind, url);
+            this.failFetchedOobi(url, record, "url-refused");
+            return;
+        }
+        if (this.relaying && !isRelayOrigin(this.hby, this.relaying.relay, url)) {
+            this.relayCursor = url;
+            yield* this.processRelayJob(this.relaying, kind, url, record);
+            return;
+        }
         const http = this.http;
         const meta = {
             ...parseOobiUrl(url, record.oobialias ?? undefined),
@@ -288,6 +367,14 @@ export class Oobiery {
                 this.cues.push({ kin: "oobiFailed", url, reason: `HTTP ${refused}` });
             }
         }
+        catch (error) {
+            // What the remote party caused ends this job only; the response scope has closed.
+            const failure = oobiJobFailure(error);
+            if (failure === null)
+                throw error;
+            this.remQueueStore(kind, url);
+            this.failFetchedOobi(url, queuedRecord, failure);
+        }
         finally {
             this.hby.db.coobi.rem(url);
         }
@@ -349,13 +436,186 @@ export class Oobiery {
             role: meta.role ?? undefined,
             eid: meta.eid ?? undefined,
         };
+        yield* this.ingestCesrOobiResponse(kind, url, queuedRecord, response);
+        this.hby.db.roobi.pin(url, { ...queuedRecord, date: new Date().toISOString(), state: "resolved" });
+        persistResolvedContact(this.hby, meta.cid, { alias: queuedRecord.oobialias, oobi: url });
+        this.cues.push(cue);
+    }
+    /**
+     * Dispatch one complete CESR OOBI response through this owner's Kevery and the shared semantic handlers, keeping
+     * the queued row and an in-flight `coobi.` row until the stream is consumed. Writes no terminal state.
+     *
+     * @param kind Durable OOBI queue family identifying the job path.
+     * @param url Exact OOBI URL used as the durable job key.
+     * @param queuedRecord Original durable job metadata retained until terminal publication.
+     * @param response Borrowed scoped HTTP response.
+     */
+    *ingestCesrOobiResponse(kind, url, queuedRecord, response) {
         this.pinQueueStore(kind, url, queuedRecord);
         this.hby.db.coobi.pin(url, { ...queuedRecord, state: "streaming" });
         yield* processMessages((signal) => response.body(signal), this.protocol, this.kvy);
         this.hby.db.coobi.rem(url);
-        this.hby.db.roobi.pin(url, { ...queuedRecord, date: new Date().toISOString(), state: "resolved" });
-        persistResolvedContact(this.hby, meta.cid, { alias: queuedRecord.oobialias, oobi: url });
-        this.cues.push(cue);
+    }
+    /**
+     * Resolve one job through the relay: ask it once, then fetch the result from the relay's own OOBI endpoint.
+     *
+     * The job stays in `oobis.` while it waits, dated from its first relay attempt; a pass that changes nothing
+     * writes nothing. It waits while the relay answers 404, is unreachable, or answers a controller OOBI without the
+     * controller's KEL. It fails at {@link RELAY_OOBI_TIMEOUT_MS}: `relay-unresolved` when the relay was asked,
+     * `relay-unserved` when it never could be (no accepted relay location, or no local identifier authorized the
+     * relay as its mailbox). Another non-OK answer fails at once as `http-<status>`, as a direct fetch does, an answer
+     * that is not CESR or whose frames do not decode fails at once with its {@link OobiJobFailure}, and a URL that names
+     * neither an identifier nor a SAID fails at once as `relay-unmappable-oobi`.
+     *
+     * @param relaying Relay collaborators of this edge.
+     * @param kind Durable OOBI queue family identifying the job path.
+     * @param url Exact third-party OOBI URL used as the durable job key; it is never fetched.
+     * @param record Pending durable job.
+     */
+    *processRelayJob(relaying, kind, url, record) {
+        const { relay, postman, clock } = relaying;
+        const meta = { ...parseOobiUrl(url, record.oobialias ?? undefined), ...record, url };
+        const path = relayOobiPath(meta);
+        if (path === null) {
+            this.remQueueStore(kind, url);
+            this.failFetchedOobi(url, record, "relay-unmappable-oobi");
+            return;
+        }
+        let waiting = record;
+        if (record.state !== RelayOobiStates.pending && record.state !== RelayOobiStates.requested) {
+            waiting = {
+                ...record,
+                date: new Date(clock.now()).toISOString(),
+                state: RelayOobiStates.pending,
+                cid: meta.cid ?? null,
+                eid: meta.eid ?? null,
+                role: meta.role ?? null,
+                oobialias: meta.alias ?? meta.oobialias ?? null,
+                said: meta.said ?? null,
+            };
+            this.hby.db.transaction(() => {
+                this.pinQueueStore(kind, url, waiting);
+                this.hby.db.eoobi.rem(url);
+                this.hby.db.roobi.rem(url);
+            });
+        }
+        if (waiting.state === RelayOobiStates.pending) {
+            const asker = this.relayAsker(relay);
+            if (asker) {
+                const exn = oobiRequestExn(asker, relay.aid, url);
+                postman.send({
+                    src: asker.pre,
+                    dest: relay.aid,
+                    topic: OOBI_MAILBOX_TOPIC,
+                    msg: asker.endorse(exn, { pipelined: false }),
+                });
+                waiting = { ...waiting, state: RelayOobiStates.requested };
+                this.pinQueueStore(kind, url, waiting);
+            }
+        }
+        const endpoint = relayEndpoint(this.hby, relay);
+        const base = endpoint?.urls.https ?? endpoint?.urls.http;
+        if (base) {
+            const refused = yield* this.fetchFromRelay(kind, url, waiting, meta, new URL(path, withSlash(base)).href);
+            if (refused === "resolved")
+                return;
+            if (typeof refused === "number") {
+                this.remQueueStore(kind, url);
+                this.hby.db.eoobi.pin(url, { ...waiting, date: new Date().toISOString(), state: `http-${refused}` });
+                this.cues.push({ kin: "oobiFailed", url, reason: `HTTP ${refused}` });
+                return;
+            }
+            if (refused !== "waiting") {
+                this.remQueueStore(kind, url);
+                this.failFetchedOobi(url, waiting, refused);
+                return;
+            }
+        }
+        if (clock.now() - Date.parse(waiting.date ?? "") < RELAY_OOBI_TIMEOUT_MS)
+            return;
+        const state = waiting.state === RelayOobiStates.requested ? "relay-unresolved" : "relay-unserved";
+        this.remQueueStore(kind, url);
+        this.failFetchedOobi(url, waiting, state);
+    }
+    /**
+     * Fetch what the relay holds for one job and ingest it under the ordinary verification.
+     *
+     * @param kind Durable OOBI queue family identifying the job path.
+     * @param url Exact third-party OOBI URL used as the durable job key.
+     * @param record Waiting durable job metadata.
+     * @param meta Parsed OOBI URL metadata selecting the response interpretation.
+     * @param relayUrl URL on the relay's origin that serves the job's answer.
+     * @returns `resolved` after a terminal write, `waiting` when the relay does not hold the answer yet or cannot be
+     * reached, the refusing HTTP status, or the {@link OobiJobFailure} of an answer that cannot be ingested.
+     */
+    *fetchFromRelay(kind, url, record, meta, relayUrl) {
+        const http = this.http;
+        // deno-lint-ignore no-this-alias -- The scoped body borrows this OOBI worker's durable queue.
+        const self = this;
+        try {
+            return yield* scoped(function* () {
+                const response = yield* http.open(relayUrl);
+                if (response.status === 404)
+                    return "waiting";
+                if (!response.ok)
+                    return response.status;
+                const type = mediaType(response.headers.get("content-type") ?? "");
+                if (!isCesrMediaType(type) && type.includes("json")) {
+                    // Schema and JSON OOBI bodies reach a terminal state under the direct-fetch rules.
+                    yield* self.processResponse(kind, url, record, meta, response);
+                    self.remQueueStore(kind, url);
+                    return "resolved";
+                }
+                yield* self.ingestCesrOobiResponse(kind, url, record, response);
+                // An answer without the controller's KEL is not the result yet; the relay may still be resolving it.
+                if (meta.cid && !self.hby.db.getKever(meta.cid))
+                    return "waiting";
+                self.remQueueStore(kind, url);
+                self.hby.db.roobi.pin(url, { ...record, date: new Date().toISOString(), state: "resolved" });
+                persistResolvedContact(self.hby, meta.cid, { alias: record.oobialias, oobi: url });
+                self.cues.push({
+                    kin: "oobiResolved",
+                    url,
+                    cid: meta.cid ?? undefined,
+                    role: meta.role ?? undefined,
+                    eid: meta.eid ?? undefined,
+                });
+                return "resolved";
+            });
+        }
+        catch (error) {
+            // An unreachable relay is the same wait as a relay that has not resolved the job yet.
+            if (error instanceof TransportError && !(error instanceof RelayOnlyError))
+                return "waiting";
+            // A relay answering what cannot be ingested fails the job, as a direct fetch does.
+            const failure = oobiJobFailure(error);
+            if (failure === null)
+                throw error;
+            return failure;
+        }
+        finally {
+            // Remove only a row this fetch left; a pass that changed nothing writes nothing.
+            if (this.hby.db.coobi.get(url))
+                this.hby.db.coobi.rem(url);
+        }
+    }
+    /**
+     * The local identifier that asks the relay to resolve an OOBI: one the relay serves, which has authorized the
+     * relay as its mailbox ({@link relayAuthorized}). A group cannot sign the request alone, so groups never ask.
+     *
+     * @param relay The configured relay agent.
+     * @returns The asking habitat, or null while the relay has no accepted location or no local identifier it serves.
+     */
+    relayAsker(relay) {
+        if (relayRefusal(this.hby, relay, null))
+            return null;
+        for (const hab of this.hby.habs.values()) {
+            const pre = hab.pre;
+            if (pre && pre !== relay.aid && !this.hby.db.groups.has(pre) && relayAuthorized(this.hby, pre, relay)) {
+                return hab;
+            }
+        }
+        return null;
     }
     /** Handle schema data-OOBIs before generic JSON reply handling. */
     processSchemaOobiResponse(url, record, bytes) {
@@ -401,18 +661,19 @@ export class Oobiery {
     /** Fan one multi-OOBI reply out into child `oobis.` jobs and a parent `moobi.` record. */
     processMultiOobiReply(url, record, serder) {
         const data = serder.ked?.a;
-        const cid = typeof data?.aid === "string" ? new Prefixer({ qb64: data.aid }).qb64 : null;
+        const cid = remotePrefix(data?.aid);
         const urls = Array.isArray(data?.urls)
             ? [
                 ...new Set(data.urls.filter((entry) => typeof entry === "string")),
             ]
             : [];
+        // A child the HTTP client would refuse fails the whole reply, before the first queue write: no partial fanout.
         if (!cid || cid !== (record.cid ?? parseOobiUrl(url).cid ?? null)
-            || urls.length === 0) {
+            || urls.length === 0 || !urls.every(isRequestableHttpUrl)) {
             this.failFetchedOobi(url, record, "invalid-multi-oobi");
             return;
         }
-        // Normalize every child before the first queue write; malformed later URLs cannot leave partial fanout.
+        // Normalize every child before the first queue write.
         const children = urls.map((childUrl) => {
             const meta = parseOobiUrl(childUrl, record.oobialias ?? undefined);
             return { url: childUrl, kind: queueKindFor(childUrl), meta, record: this.queuedRecord(meta) };
@@ -496,15 +757,15 @@ export class Oobiery {
             throw new ValidationError(`Unsupported route=${args.route} in ${Ilks.rpy} reply.`);
         }
         const data = args.serder.ked?.a;
-        const cid = typeof data?.cid === "string" ? new Prefixer({ qb64: data.cid }).qb64 : null;
+        const cid = remotePrefix(data?.cid);
         const oobi = typeof data?.oobi === "string" ? data.oobi : null;
         const dt = typeof args.serder.ked?.dt === "string" ? args.serder.ked.dt : new Date().toISOString();
         if (!cid || !oobi) {
-            throw new ValidationError("Missing cid/oobi in /introduce reply.");
+            throw new ValidationError("Missing or invalid cid/oobi in /introduce reply.");
         }
-        const parsed = new URL(oobi);
-        if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
-            throw new ValidationError(`Invalid introduced OOBI scheme ${parsed.protocol}.`);
+        // Refused at intake: a URL the HTTP client refuses by construction can never resolve.
+        if (!isRequestableHttpUrl(oobi)) {
+            throw new ValidationError(`Introduced OOBI ${oobi} is not an HTTP(S) URL without credentials.`);
         }
         const proof = this.rvy.decideReply({
             serder: args.serder,
@@ -541,8 +802,17 @@ export class Oobiery {
         return acceptReplyDecision();
     }
 }
-export function loadOobiHandlers(hby, exchanger, notifier = null) {
-    exchanger.addHandler(new OobiRequestHandler(hby, notifier));
+/**
+ * Register the `/oobis` exchange handler.
+ *
+ * @param hby Borrowed local identities and the durable OOBI queue.
+ * @param exchanger Exchanger receiving the route.
+ * @param notifier Optional operator notice producer.
+ * @param relaying Whether this host relays (the agent side of relay mode): requests are then accepted only from a
+ * served sender.
+ */
+export function loadOobiHandlers(hby, exchanger, notifier = null, relaying = false) {
+    exchanger.addHandler(new OobiRequestHandler(hby, notifier, relaying));
 }
 /**
  * Peer-to-peer OOBI request handler for `/oobis` exchange messages.
@@ -557,15 +827,27 @@ export function loadOobiHandlers(hby, exchanger, notifier = null) {
  *
  * Local `keri-ts` adaptation:
  * - verification stays lightweight and route-local: we only require a string
- *   `oobi` payload with an `http:` or `https:` scheme
+ *   `oobi` payload that is an `http:` or `https:` URL without embedded
+ *   credentials, which is what the HTTP client can request
  * - durable follow-on work still belongs to `Oobiery` itself; this handler is
  *   just the exchange ingress seam that translates an EXN into queued resolver
  *   state
  * - unlike KERIpy's DoDoer-centric runtime, the queued record is later
  *   advanced by the shared `AgentRuntime` turn that owns OOBI processing
+ * - on a relaying host (the agent side of relay mode) a request is accepted
+ *   only from a served sender, by the same rule `/fwd` intake relays for
+ *   ({@link servingHost}): the sender authorized a local habitat as its
+ *   `mailbox` or `agent`. An edge resolves third-party OOBIs this way; nobody
+ *   else can make the agent fetch a URL. Without relaying, any authenticated
+ *   sender is accepted, as in KERIpy.
  */
 export class OobiRequestHandler {
-    constructor(hby, notifier = null) {
+    /**
+     * @param hby Borrowed local identities and the durable OOBI queue.
+     * @param notifier Optional operator notice producer.
+     * @param relaying Restrict requests to served senders (a relaying host); false accepts any sender.
+     */
+    constructor(hby, notifier = null, relaying = false) {
         Object.defineProperty(this, "resource", {
             enumerable: true,
             configurable: true,
@@ -584,21 +866,30 @@ export class OobiRequestHandler {
             writable: true,
             value: void 0
         });
+        /** Whether requests are restricted to served senders. */
+        Object.defineProperty(this, "relaying", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         this.hby = hby;
         this.notifier = notifier;
+        this.relaying = relaying;
     }
+    /**
+     * Accept a request carrying an `oobi` the HTTP client can request ({@link isRequestableHttpUrl}: HTTP(S), no
+     * embedded credentials); on a relaying host, only from a served sender. Anything else could never resolve.
+     *
+     * @param args Authenticated exchange and the receiving hosted endpoint, if the request named one.
+     * @returns False to reject the exchange.
+     */
     verify(args) {
-        const payload = args.serder.ked?.a;
-        if (typeof payload?.["oobi"] !== "string") {
-            return false;
-        }
-        try {
-            const parsed = new URL(payload.oobi);
-            return parsed.protocol === "http:" || parsed.protocol === "https:";
-        }
-        catch {
+        if (this.relaying && !servingHost(this.hby, { sender: args.serder.pre, origin: null }, args.mailboxAid)) {
             return false;
         }
+        const payload = args.serder.ked?.a;
+        return typeof payload?.["oobi"] === "string" && isRequestableHttpUrl(payload.oobi);
     }
     handle(args) {
         const src = args.serder.pre;
@@ -698,6 +989,48 @@ function findPathSequence(parts, sequence) {
     }
     return -1;
 }
+/**
+ * Path, relative to the relay's location, at which the relay serves what an OOBI job names. The relay's OOBI
+ * endpoint answers for what it holds, so the third party's host and base path are dropped:
+ * - a controller, witness, agent or mailbox OOBI `.../oobi/{cid}/{role}[/{eid}]` maps to
+ *   `oobi/{cid}/{role}[/{eid}]`; the relay answers with the controller's KEL (receipts included) and the replies
+ *   it holds for that role;
+ * - a data OOBI `.../oobi/{said}` (a schema) maps to `oobi/{said}`.
+ * Well-known OOBIs are authentication jobs, not Oobiery jobs. A URL naming neither maps to nothing.
+ *
+ * @param job Parsed job metadata.
+ * @returns The relative path, or null when the job names no identifier or SAID.
+ */
+function relayOobiPath(job) {
+    if (job.cid && job.role) {
+        return ["oobi", job.cid, job.role, ...(job.eid ? [job.eid] : [])].map(encodeURIComponent).join("/");
+    }
+    if (job.said)
+        return `oobi/${encodeURIComponent(job.said)}`;
+    return null;
+}
+/** A base URL that resolves relative paths beneath it rather than beside its last segment. */
+function withSlash(url) {
+    return url.endsWith("/") ? url : `${url}/`;
+}
+/**
+ * The qualified prefix a remote reply names, or null when the value is not a string or does not decode as one.
+ *
+ * @param value Remote field value.
+ * @returns The prefix's qb64, or null.
+ */
+function remotePrefix(value) {
+    if (typeof value !== "string")
+        return null;
+    try {
+        return new Prefixer({ qb64: value }).qb64;
+    }
+    catch (error) {
+        if (error instanceof ParserError)
+            return null;
+        throw error;
+    }
+}
 function queueKindFor(url) {
     return isWellKnownOobiUrl(url) ? "woobi" : "oobis";
 }

package/esm/keri/npm/src/app/credentials/credential-importing.js

@@ -1,6 +1,7 @@
 /** Finite credential-bundle intake; protocol owners retain and recover their own pending evidence. */
 import { Ilks, parse, SerderACDC, SerderKERI } from "cesr-ts";
 import { action, call, ensure, race } from "effection";
+import { validateRip, validateUpdate } from "../../acdc/regeventing.js";
 import { consoleLogger } from "../../core/logger.js";
 import { rethrowCleanupFailure } from "../runtime/abortable.js";
 import { chunkBytes } from "../transport/byte-source.js";
@@ -10,6 +11,14 @@ import { chunkBytes } from "../transport/byte-source.js";
  * Later input failures preserve earlier accepted state. Receipts, replies and other messages still
  * use normal dispatch; absence of an importer acceptance lookup is not an additional refusal policy.
  *
+ * The input is retained history the caller already holds (for example an exported disclosure stream: KELs, the v2
+ * registry TEL, a Grant and its Admit), so every frame is dispatched with `DispatchOptions.retained`. Its v2
+ * exchanges skip KRAM, whose window their original stamps passed long ago; signatures, route verification and
+ * escrows are unchanged, and the accepted exchanges raise no notice and get no exchange lifetime. Targets: raw
+ * credentials, KEL and v1 TEL events, v2 `rip`/`bup` (accepted at their exact ordinal in the v2 registry store),
+ * and exchanges (accepted by the Exchanger; a v2 Admit also needs its Grant's reply row to name it). Importing the
+ * same input again changes nothing and reports the same acceptance.
+ *
  * @param protocol Borrowed protocol dispatcher, sharing reger with its TEL/credential handlers.
  * @param reger Borrowed credential/TEL store whose accepted records establish the result.
  * @param bytes Borrowed finite CESR bundle; parser chunks are copied during intake.
@@ -120,7 +129,8 @@ function readImportTargets(protocol, reger, bytes, kvy) {
                     if (target)
                         targets.set(target.said, target);
                 }
-                const { decision } = yield* protocol.dispatch(next.value, {}, kvy);
+                // The one dispatch that marks its input as retained history; see the operation docs.
+                const { decision } = yield* protocol.dispatch(next.value, { retained: true }, kvy);
                 if (decision && (decision.kind === "reject" || decision.kind === "drop")) {
                     consoleLogger.warn("Credential import message refused", {
                         said: serder.said,
@@ -148,7 +158,16 @@ function readImportTargets(protocol, reger, bytes, kvy) {
 function importTarget(serder, reger) {
     const said = serder.said, ilk = serder.ilk;
     if (serder instanceof SerderACDC) {
-        return ilk === null ? { ilk, said, savedBefore: reger.saved.get([said]) !== null } : null;
+        if (ilk === null)
+            return { ilk, said, savedBefore: reger.saved.get([said]) !== null };
+        if (ilk !== Ilks.rip && ilk !== Ilks.bup)
+            return null;
+        // An event that fails field validation, or whose ordinal no store can hold, keeps no coordinates, so it is
+        // always reported unaccepted.
+        const result = ilk === Ilks.rip ? validateRip(serder) : validateUpdate(serder, serder.regid ?? "");
+        return result.kind === "valid" && result.event.sn <= BigInt(Number.MAX_SAFE_INTEGER)
+            ? { ilk, said, regid: result.event.regid, sn: Number(result.event.sn) }
+            : { ilk, said, regid: null, sn: null };
     }
     switch (ilk) {
         case Ilks.icp:
@@ -164,7 +183,11 @@ function importTarget(serder, reger) {
         case Ilks.brv:
             return { ilk, said, pre: serder.pre, sn: serder.sn };
         case Ilks.exn:
-            return { ilk, said };
+        case Ilks.xip: {
+            const prior = serder.sad?.p;
+            const admit = serder.pvrsn.major >= 2 && serder.route === "/ipex/admit" && typeof prior === "string";
+            return { ilk, said, answers: admit ? prior : null };
+        }
         default:
             return null;
     }
@@ -195,7 +218,13 @@ function importTargetAccepted(target, protocol, reger) {
         case Ilks.bis:
         case Ilks.brv:
             return target.pre !== null && target.sn !== null && reger.tels.getOn(target.pre, target.sn)?.qb64 === target.said;
+        case Ilks.rip:
+        case Ilks.bup:
+            return target.regid !== null && target.sn !== null
+                && protocol.registry?.store.seqSaider(target.regid, target.sn)?.qb64 === target.said;
         case Ilks.exn:
-            return protocol.kvy.db.exns.get([target.said]) !== null;
+        case Ilks.xip:
+            return protocol.exc.complete(target.said)
+                && (target.answers === null || protocol.kvy.db.erpy.get([target.answers])?.qb64 === target.said);
     }
 }