keri-ts 2.2.3 → 2.2.5

package/esm/keri/npm/src/app/queries/relay-refresh.js

@@ -0,0 +1,81 @@
+/**
+ * Agent side of relay mode: refresh the agent's own view of a subject when a served edge asks about it.
+ *
+ * An edge's only view of third-party key state is its agent's: every edge query is addressed to the agent, which
+ * answers from its own store. That store may be stale for an identifier the agent has no reason of its own to
+ * follow. So when a relaying agent receives a `logs` or `ksn` query from a sender it serves about a subject that is
+ * not one of its own, it also issues its own ordinary `logs` query for that subject, as an ordinary `query` cue its
+ * own querier consumes. The agent is a forwarder, so that query goes directly to the subject's controller, agent or
+ * witness endpoint. This is on demand only, as KERIA queries for its Signify clients: no watching, no subscription
+ * list, no new store.
+ *
+ * What the edge sees: the answer to the query that caused the refresh comes from what the agent held then, unless
+ * the query names a sequence number or anchor the agent lacks, in which case the agent escrows it (query-not-found)
+ * and answers once the refresh lands. A later edge query returns the refreshed state.
+ */
+import { Ilks } from "cesr-ts";
+import { Kever } from "../../core/kel/kever.js";
+import { servingHost } from "../mailbox/forward-handler.js";
+import { queryEnvelopeFromDispatch } from "../protocol/parsering.js";
+import { addressableAttesters } from "./witness-inquisitor.js";
+/**
+ * The requester of a query whose attached signatures satisfy its current signing threshold, or null.
+ *
+ * `logs` and `ksn` answers are public, so the KEL query path does not authenticate the requester (nor does KERIpy).
+ * A refresh spends the agent's own traffic on the requester's behalf, so it needs the requester proven: a
+ * transferable source whose KEL the agent holds and whose current keys signed this query to threshold.
+ *
+ * @param hby Borrowed accepted-state store holding the requester's KEL.
+ * @param query Normalized query envelope with its requester source and indexed signatures.
+ * @returns The authenticated requester AID, or null.
+ */
+function authenticatedRequester(hby, query) {
+    const source = query.source?.qb64;
+    if (!source)
+        return null;
+    const kever = hby.db.getKever(source);
+    if (!kever?.tholder)
+        return null;
+    const verified = Kever.verifyIndexedSignatures(query.serder.raw, query.sigers ?? [], kever.verfers);
+    return kever.tholder.satisfy(verified.indices) ? source : null;
+}
+/**
+ * Decide whether one processed query makes a relaying host refresh its view of the subject, and return the query cue
+ * that does it.
+ *
+ * Every condition must hold:
+ * - the message is a remote (not local) `logs` or `ksn` query the KEL owner accepted or escrowed;
+ * - its subject `q.i` is not a prefix of this Habery;
+ * - its requester is authenticated (see {@link authenticatedRequester}) and served by a local host under the shared
+ *   `servingHost` rule (an accepted mailbox or agent end role naming the host);
+ * - the host can address an attester for the subject now ({@link addressableAttesters}: one with an accepted
+ *   location), so the request is sent on the querier's next pass instead of waiting in its queue.
+ *
+ * The cue is `{ route: "logs", q: {} }` for the subject, signed by the serving host: one full replay from the
+ * attester covers both routes, since `ksn` is answered from the same key state. A `tels` query is not refreshed:
+ * its wire body names the registry and credential but not the issuer the querier selects attesters by.
+ *
+ * @param hby Borrowed habitats and accepted-state store of the relaying host.
+ * @param result Processed envelope and the decision its owner made.
+ * @param mailboxAid Receiving hosted endpoint AID, or null when the request named none.
+ * @returns The refresh query cue, or null when this query refreshes nothing.
+ */
+export function relayRefreshCue(hby, result, mailboxAid) {
+    const { envelope, decision } = result;
+    const serder = envelope.serder;
+    if (envelope.local || serder.ilk !== Ilks.qry || (serder.route !== "logs" && serder.route !== "ksn"))
+        return null;
+    if (!decision || (decision.kind !== "accept" && decision.kind !== "escrow"))
+        return null;
+    const subject = serder.ked?.q?.i;
+    if (typeof subject !== "string" || hby.db.prefixes.has(subject))
+        return null;
+    const requester = authenticatedRequester(hby, queryEnvelopeFromDispatch(envelope));
+    if (!requester)
+        return null;
+    const host = servingHost(hby, { sender: requester, origin: null }, mailboxAid);
+    const hab = host ? hby.habs.get(host) : undefined;
+    if (!hab || addressableAttesters(hab, subject).length === 0)
+        return null;
+    return { kin: "query", pre: subject, route: "logs", q: {}, signer: hab.pre };
+}

package/esm/keri/npm/src/app/queries/witness-inquisitor.js

@@ -7,22 +7,36 @@
  * is an explicitly selected remote attester. Resolve/sign just before sending,
  * using accepted endpoint evidence. One worker owns the unsigned request Deck
  * and current network attempt; there is no retained signed retry backlog.
+ *
+ * With a relay (an edge runtime) every query is addressed and sent to the relay,
+ * which is the attester: it answers from its own store through its Respondant
+ * and Poster into the edge's mailbox, which it hosts. No query goes to a witness
+ * or controller, whatever `src` or `wits` the request names.
  */
 import { concatBytes } from "cesr-ts";
 import { call, resource } from "effection";
 import { Deck } from "../../core/deck.js";
-import { ValidationError } from "../../core/errors.js";
 import { consoleLogger } from "../../core/logger.js";
 import { Roles } from "../../core/roles.js";
 import { Schemes } from "../../core/schemes.js";
 import { introduce } from "../delivery/introducing.js";
-import { runtimeTurn } from "../runtime/runtime-turn.js";
+import { relayEndpoint, relayRefusal } from "../delivery/relaying.js";
+import { PROTOCOL_TOCK_MS } from "../runtime/doing.js";
+import { waitOnClock } from "../runtime/workflow-contract.js";
 import { CesrHttpRefusal } from "../transport/cesr-egress.js";
+import { isRequestableHttpUrl } from "../transport/http-client.js";
 import { HTTPMessenger } from "../transport/http-messenger.js";
+import { messengerUrl } from "../transport/messengering.js";
 import { requireTcpDialer } from "../transport/tcp-dialer.js";
 import { TransportError } from "../transport/transport-error.js";
 /** First eligible role used by KERIpy WitnessInquisitor before random endpoint selection. */
 const QUERY_ROLE_PRIORITY = [Roles.controller, Roles.agent, Roles.witness];
+/**
+ * Delivery passes an ordinary request may rotate with a ready signer but no reachable attester before it is dropped:
+ * about five minutes at the protocol tock. Any remote party can cause such requests (every unverified reply signed by
+ * an unknown prefix yields a `query` cue), so without a bound they would rotate in the queue forever.
+ */
+export const UNADDRESSED_QUERY_PASS_LIMIT = 9_600;
 /**
  * Copy only the owned query-body level without erasing its route/payload relationship.
  *
@@ -40,6 +54,22 @@ function copyQuery(instruction) {
             return { route: instruction.route, q: { ...instruction.q } };
     }
 }
+/**
+ * Identity of one unsigned request for duplicate detection: every field that changes what is signed or where it goes.
+ *
+ * @param request Queued or candidate request; query filters are strings and string-valued seal SADs.
+ * @returns A canonical string equal for two requests exactly when they would produce the same query.
+ */
+function requestKey(request) {
+    return JSON.stringify([
+        request.route,
+        request.pre,
+        request.signer ?? null,
+        request.src ?? null,
+        request.wits ?? null,
+        request.q,
+    ]);
+}
 /**
  * Return the sole local habitat when exactly one exists.
  *
@@ -55,12 +85,47 @@ function soleHab(hby) {
     const first = habitats.next();
     return first.done || !habitats.next().done ? null : first.value;
 }
+/**
+ * The attesters an ordinary (non-relay) query for `pre` may go to: the AIDs of the first role among controller,
+ * agent and witness that has any accepted endpoint for the subject. Mailbox providers are not query attesters.
+ *
+ * @param hab Local habitat whose accepted-state store is read.
+ * @param pre Subject AID whose accepted endpoint roles are consulted.
+ * @returns Eligible attester AIDs, or an empty array for an unknown subject or a subject with no such endpoint.
+ */
+function queryAttesters(hab, pre) {
+    if (!hab.db.getKever(pre))
+        return [];
+    const ends = hab.endsFor(pre);
+    for (const role of QUERY_ROLE_PRIORITY) {
+        const eids = Object.keys(ends[role] ?? {});
+        if (eids.length > 0)
+            return eids;
+    }
+    return [];
+}
+/**
+ * The location a query can be sent to, preferring HTTPS, then HTTP, then TCP. An accepted location comes from a remote
+ * `/loc/scheme` reply, so one the HTTP client refuses by construction (embedded credentials) is no location: sending
+ * to it would throw a refusal that is not a send outcome.
+ *
+ * @param urls Accepted locations of one endpoint, by scheme.
+ * @returns The preferred usable location, or null when none is usable.
+ */
+function preferredLocation(urls) {
+    for (const url of [urls[Schemes.https], urls[Schemes.http]])
+        if (url && isRequestableHttpUrl(url))
+            return url;
+    // A TCP location without a valid port is refused by the TCP messenger; it is no location here.
+    const tcp = urls[Schemes.tcp];
+    return tcp && messengerUrl({ tcp }) ? tcp : null;
+}
 /**
  * Resolve the actual transport URL for one query destination AID.
  *
  * An explicit witness uses its own location records. Ordinary queries use only
  * the selected controller, agent or witness endpoint; mailbox providers are not
- * query attesters. Missing/unsupported locations do not promote another endpoint.
+ * query attesters. Missing, unsupported or unusable locations do not promote another endpoint.
  *
  * @param hab Local habitat used to construct/sign this output; stores remain borrowed.
  * @param queriedPre Subject AID whose state is requested.
@@ -69,18 +134,27 @@ function soleHab(hby) {
  * @returns Preferred endpoint URL, or null if no permitted route exists.
  */
 function resolveQueryDestinationUrl(hab, queriedPre, destination, { explicitWitness = false, } = {}) {
-    if (explicitWitness) {
-        const urls = hab.fetchUrls(destination);
-        return urls[Schemes.https] ?? urls[Schemes.http] ?? urls[Schemes.tcp] ?? null;
-    }
+    if (explicitWitness)
+        return preferredLocation(hab.fetchUrls(destination));
     const ends = hab.endsFor(queriedPre);
     for (const role of [Roles.controller, Roles.agent, Roles.witness]) {
         const urls = ends[role]?.[destination];
         if (urls)
-            return urls[Schemes.https] ?? urls[Schemes.http] ?? urls[Schemes.tcp] ?? null;
+            return preferredLocation(urls);
     }
     return null;
 }
+/**
+ * The attesters of an ordinary query for `pre` that can be sent to now: those {@link queryAttesters} selects that also
+ * have an accepted location.
+ *
+ * @param hab Local habitat whose accepted-state store is read.
+ * @param pre Subject AID whose accepted endpoint roles and locations are consulted.
+ * @returns Addressable attester AIDs of the first eligible role; empty when none can be reached now.
+ */
+export function addressableAttesters(hab, pre) {
+    return queryAttesters(hab, pre).filter((aid) => resolveQueryDestinationUrl(hab, pre, aid) !== null);
+}
 /**
  * KERIpy-shaped query sender, independent from semantic query completion.
  *
@@ -108,9 +182,10 @@ export class WitnessInquisitor {
      * @param protocol Borrowed same-database processor for incoming query replies.
      * @param http Borrowed HTTP implementation selected by composition.
      * @param clock Borrowed clock for transport deadlines; times are milliseconds.
+     * @param relay The agent every query goes to; null selects attesters from accepted endpoint roles.
      * @param hab Optional default local signer; null requires an unambiguous sole habitat.
      */
-    constructor(hby, protocol, http, clock, hab = null) {
+    constructor(hby, protocol, http, clock, relay, hab = null) {
         /** Borrowed local signers and accepted-state stores. */
         Object.defineProperty(this, "hby", {
             enumerable: true,
@@ -181,12 +256,20 @@ export class WitnessInquisitor {
             writable: true,
             value: void 0
         });
+        /** The agent every query is addressed and sent to (an edge); null selects ordinary attesters. */
+        Object.defineProperty(this, "relay", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         if (protocol.kvy.db !== hby.db)
             throw new RangeError("Query protocol must use the same database");
         this.hby = hby;
         this.protocol = protocol;
         this.http = http;
         this.clock = clock;
+        this.relay = relay;
         this.hab = hab;
     }
     /**
@@ -197,6 +280,17 @@ export class WitnessInquisitor {
     configure({ hab = null } = {}) {
         this.hab = hab;
     }
+    /** The explicitly configured default signer, or null when the sole local habitat is used. */
+    get defaultSigner() {
+        return this.hab?.pre ?? null;
+    }
+    /** Whether a queued request names `signer` as its explicit signer. */
+    hasRequestsSignedBy(signer) {
+        for (const request of this.requests)
+            if (request.signer === signer)
+                return true;
+        return false;
+    }
     /** Deferred instructions and active sends are this sender's only pending work. */
     hasPendingWork() {
         return !this.requests.empty || this.hasPendingDelivery;
@@ -214,6 +308,7 @@ export class WitnessInquisitor {
             ...request,
             ...copyQuery(request),
             wits: request.wits ? [...request.wits] : undefined,
+            unaddressedPasses: 0,
         });
     }
     /**
@@ -231,6 +326,27 @@ export class WitnessInquisitor {
         const selected = { ...request, signer: request.signer ?? hab?.pre };
         this.enqueue(selected);
     }
+    /**
+     * Admit a routed query cue unless an identical request is already queued: same subject, route, filters, signer,
+     * attester and witness overrides, with the signer resolved as {@link enqueueCue} resolves it. A relaying host's cue
+     * router uses this, so the queries of the many edges it serves about one subject leave one request queued; a request
+     * already taken for delivery is no longer queued, so a later cue queues the next one.
+     *
+     * @param cue Typed query cue; missing route/subject produces no request.
+     * @param hab Optional local signer hint when the cue has no explicit signer.
+     */
+    enqueueCueOnce(cue, hab) {
+        if (this.closed)
+            throw new Error("Query sender is closed");
+        if (!cue.route || !cue.pre)
+            return;
+        const { kin: _, ...request } = cue;
+        const key = requestKey({ ...request, signer: request.signer ?? hab?.pre });
+        for (const queued of this.requests)
+            if (requestKey(queued) === key)
+                return;
+        this.enqueueCue(cue, hab);
+    }
     /** Include actual query I/O in convergence; pending instructions have their own queue. */
     get hasPendingDelivery() {
         return this.delivering;
@@ -281,7 +397,16 @@ export class WitnessInquisitor {
                 const packet = self.prepareRequest(request);
                 self.requests.pull();
                 if (!packet) {
-                    self.requests.append(request);
+                    // A signer that cannot sign yet, or a relay not yet usable, is local state that waits; a ready signer with no
+                    // reachable attester counts toward the bound.
+                    if (!self.relay && self.configuredHab(request.signer)?.canSign())
+                        request.unaddressedPasses++;
+                    if (request.unaddressedPasses >= UNADDRESSED_QUERY_PASS_LIMIT) {
+                        consoleLogger.warn(`Dropping ${request.route} query for ${request.pre}: no reachable attester after ${request.unaddressedPasses} passes.`);
+                    }
+                    else {
+                        self.requests.append(request);
+                    }
                     continue;
                 }
                 active.signal.throwIfAborted();
@@ -339,12 +464,15 @@ export class WitnessInquisitor {
      * preparation/cleanup faults terminate the worker. Caller cancellation joins
      * the current attempt; it does not close the borrowed state or HTTP service.
      */
-    *deliverDo() {
+    *deliverDo(tockMs = PROTOCOL_TOCK_MS) {
         while (true) {
-            const failure = yield* this.deliveryPass();
-            if (failure)
-                consoleLogger.warn("Query delivery failed", failure);
-            yield* runtimeTurn();
+            // Fixed tock: a pass only when a request is queued; a request waits at most `tockMs` to start.
+            if (!this.requests.empty) {
+                const failure = yield* this.deliveryPass();
+                if (failure)
+                    consoleLogger.warn("Query delivery failed", failure);
+            }
+            yield* waitOnClock(this.clock, tockMs);
         }
     }
     /**
@@ -365,51 +493,73 @@ export class WitnessInquisitor {
      * Resolve/sign one selected query and introduction immediately before its attempt.
      *
      * @param request Deferred unsigned request; nested query values must remain immutable.
-     * @returns Prepared packet, or null when signer/attester evidence is unresolved.
-     * @throws A selected attester with no endpoint URL throws; source removal remains with the caller.
+     * The attester is chosen at random among the eligible ones (the explicit `src`, the `wits` overrides, or the first
+     * eligible endpoint role) that have an accepted location. An attester without one is never promoted to another
+     * role; when none of the eligible attesters can be reached the request is unresolved, like a signer that cannot sign
+     * yet, so no endpoint condition ends the delivery loop or fails a caller's pass.
+     *
+     * @param request Deferred unsigned request; nested query values must remain immutable.
+     * @returns Prepared packet, or null when signer/attester evidence is unresolved, no eligible attester has an
+     *   accepted location, or the signer cannot sign yet.
      */
     prepareRequest(request) {
         const hab = this.configuredHab(request.signer);
-        if (!hab)
+        // A signer that cannot sign yet leaves the request unresolved: it goes to the tail, and the next pass tries again.
+        if (!hab || !hab.canSign())
             return null;
-        const attesters = request.src ? [] : this.attestersFor(request.pre, { signer: hab.pre, wits: request.wits });
-        const destination = request.src ?? attesters[Math.floor(Math.random() * attesters.length)];
-        if (!destination)
-            return null;
-        const url = resolveQueryDestinationUrl(hab, request.pre, destination, {
-            explicitWitness: request.wits?.includes(destination) ?? false,
+        if (this.relay)
+            return this.prepareRelayRequest(hab, request, this.relay);
+        const eligible = request.src
+            ? [request.src]
+            : this.attestersFor(request.pre, { signer: hab.pre, wits: request.wits });
+        const reachable = eligible.flatMap((destination) => {
+            const url = resolveQueryDestinationUrl(hab, request.pre, destination, {
+                explicitWitness: request.wits?.includes(destination) ?? false,
+            });
+            // A TCP location on a host without a TCP dialer cannot be sent to: it is unreachable, not a fault.
+            return url && (this.http.tcp || !url.startsWith("tcp:")) ? [{ destination, url }] : [];
         });
-        if (!url)
-            throw new ValidationError(`No endpoint URL found for query destination ${destination}.`);
+        const selected = reachable[Math.floor(Math.random() * reachable.length)];
+        if (!selected)
+            return null;
+        const { destination, url } = selected;
         const message = hab.query(request.pre, destination, copyQuery(request));
         const intro = introduce(hab, destination);
         return { url, body: concatBytes(intro, message), destination };
     }
     /**
-     * Return the first eligible role’s attester IDs; preparation chooses one randomly.
+     * Address one query to the relay and sign it for the relay's location. The relay must have an accepted location
+     * and the signer must have authorized it as mailbox (where the answer is stored); until then the request stays
+     * unresolved and is tried again on a later pass, as for a signer that cannot sign yet.
+     *
+     * @param hab Local signing habitat.
+     * @param request Deferred unsigned request; its `src` and `wits` are not consulted.
+     * @param relay The configured relay agent, which is the attester.
+     * @returns Prepared packet for the relay, or null while {@link relayRefusal} refuses the relay for this signer.
+     */
+    prepareRelayRequest(hab, request, relay) {
+        if (relayRefusal(this.hby, relay, hab.pre))
+            return null;
+        const endpoint = relayEndpoint(this.hby, relay);
+        const message = hab.query(request.pre, relay.aid, copyQuery(request));
+        return { url: endpoint.url, body: concatBytes(introduce(hab, relay.aid), message), destination: relay.aid };
+    }
+    /**
+     * Return the first eligible role’s attester IDs; preparation chooses one randomly. With a relay, the relay is the
+     * only attester.
      *
      * @param pre Subject AID whose accepted endpoint roles are consulted.
      * @param options Optional local signer AID and remote witness/attester overrides; neither selects a transport implementation.
      * @returns Eligible attester AIDs, or an empty array for an unknown subject or unresolved signer/role.
      */
     attestersFor(pre, { signer, wits } = {}) {
+        if (this.relay)
+            return [this.relay.aid];
         if (wits && wits.length > 0) {
             // Explicit watcher/witness overrides outrank endpoint-role lookup.
             return [...wits];
         }
         const hab = this.configuredHab(signer);
-        if (!hab || !this.hby.db.getKever(pre))
-            return [];
-        const ends = hab.endsFor(pre);
-        for (const role of QUERY_ROLE_PRIORITY) {
-            const roleEnds = ends[role];
-            if (!roleEnds) {
-                continue;
-            }
-            const eids = Object.keys(roleEnds);
-            if (eids.length > 0)
-                return eids;
-        }
-        return [];
+        return hab ? queryAttesters(hab, pre) : [];
     }
 }