@fora-protocol/sdk 1.0.3

package/sdk/ts/client/index.js

@@ -0,0 +1,740 @@
+// The FORA client: the six verbs an agent needs, over the Connect-unary JSON transport.
+//
+// TS port of sdk/go/connect (Client + BrokerClient). The transports differ — Go keeps
+// full connect-go, this speaks the unary JSON form — but that is an implementation
+// difference, not an API difference: the verbs carry the same names and the same
+// contracts, and the fail-closed offer verification is the SAME Verifier the core ships,
+// never a second verification path.
+//
+// It owns NO state. The signer, the keys, the dialing seam, the endpoint resolver and the
+// verification policy are all injected.
+import { createVerifier, } from "../core/verifier.js";
+import { clockWindow } from "../core/window.js";
+import { fromWireOffer } from "../core/wire-canon.js";
+import { signOfferAcceptance, signRequestAcceptance, ACCEPTANCE_SIGNATURE_ALGORITHM, } from "../src/acceptance.js";
+import { registrationFailureDetail } from "../src/errordetail.js";
+import { redactUserinfo } from "../src/host-ref.js";
+import { isBareDomain } from "../src/hosts.js";
+import { generateIdempotencyKey } from "../src/idempotency.js";
+import { ProtocolVersion } from "../src/wire.js";
+import { DiscoveryRequestSchema, DiscoveryResponseSchema, DisputeRequestSchema, DisputeResponseSchema, GetAccountStatusRequestSchema, GetAccountStatusResponseSchema, PushResourcesRequestSchema, PushResourcesResponseSchema, RefreshCatalogRequestSchema, RefreshCatalogResponseSchema, RegisterRequestSchema, RegisterResponseSchema, RemoveResourcesRequestSchema, RemoveResourcesResponseSchema, ResourceQuerySchema, ResourceResponseSchema, TransactionRequestSchema, TransactionResponseSchema, UsageReportSchema, UsageReportResponseSchema, } from "../../../gen/ts/wire/schemas.js";
+import { fetchContent } from "./content.js";
+import { malformed, notSent, ForaCallError } from "./errors.js";
+import { checkRegistrationData } from "../src/regschema.js";
+import { createWellKnownRequirementsReader, ExchangeNotPermitted, ManifestNotExchange, ManifestUnusable, } from "../resolvers/index.js";
+import { isInvalidHostRefusal, vetExchangeEndpoint } from "./route.js";
+import { createUnarySend } from "./send.js";
+import { DEFAULT_CALL_TIMEOUT_MS, DEFAULT_MAX_RPC_READ_BYTES, parseMessage, unaryCall, validateRequest, } from "./transport.js";
+const EXCHANGE_SERVICE = "fora.v1.ExchangeService";
+const BROKER_SERVICE = "fora.v1.BrokerService";
+const CATALOG_SERVICE = "fora.v1.CatalogService";
+/** How long a delivery-fetch proof stays valid, in seconds.
+ *
+ * Short on purpose, and deliberately NOT the signed URL's own expiry, which can be hours:
+ * the proof covers only the method and the URL, so for as long as the window is open
+ * anyone who observes the request can repeat it. */
+export const DEFAULT_PROOF_WINDOW_SEC = 30;
+function resolve(opts) {
+    const now = opts.now ?? (() => Date.now());
+    const verifier = createVerifier(opts.verification ?? "strict", {
+        // Fail-closed by default: with no resolver injected nothing resolves, so every
+        // offer lands in `rejected` with a reason rather than being surfaced unchecked.
+        resolve: opts.resolveOfferKey ?? (async () => undefined),
+        now,
+    });
+    const signer = opts.signer === undefined
+        ? undefined
+        : {
+            privKey: opts.signer.privKey,
+            keyid: opts.signer.keyid,
+            ...(opts.signatureAgent !== undefined
+                ? { signatureAgent: opts.signatureAgent }
+                : {}),
+            ...(opts.signWindow !== undefined ? { window: opts.signWindow } : {}),
+        };
+    return {
+        opts,
+        verifier,
+        send: opts.send ?? createUnarySend({ guarded: false }),
+        guardedSend: opts.guardedSend ?? createUnarySend({ guarded: true }),
+        requirements: opts.registrationRequirements ?? createWellKnownRequirementsReader(),
+        signer,
+    };
+}
+// call is the one place a verb reaches the wire, so every leg carries the same header
+// set, the same bound and the same deadline.
+async function call(r, op, baseURL, service, method, message, guarded) {
+    return unaryCall({
+        target: { baseURL, service, method },
+        op,
+        message,
+        // The leg decides the dial AND the gate together, so the two cannot drift apart.
+        send: guarded ? r.guardedSend : r.send,
+        guarded,
+        ...(r.signer !== undefined ? { signer: r.signer } : {}),
+        ...(r.opts.requestId !== undefined ? { requestId: r.opts.requestId } : {}),
+        maxBytes: r.opts.maxRPCReadBytes ?? DEFAULT_MAX_RPC_READ_BYTES,
+        timeoutMs: r.opts.callTimeoutMs ?? DEFAULT_CALL_TIMEOUT_MS,
+    });
+}
+/**
+ * createClient builds a client against baseURL — the agent's HOME Exchange, the one its
+ * account lives on.
+ *
+ * Discovery and purchase go to baseURL. A usage report or a dispute does NOT: those reach
+ * the Exchange that ISSUED the offer, resolved per call from that Exchange's own
+ * manifest, over a separately guarded transport.
+ */
+export function createClient(baseURL, options = {}) {
+    const r = resolve(options);
+    return {
+        discover: (query) => discover(r, baseURL, query),
+        execute: (offer, opts) => execute(r, baseURL, offer, opts ?? {}),
+        reportUsage: (report, opts) => reportUsage(r, report, opts ?? {}),
+        dispute: (request, opts) => dispute(r, request, opts ?? {}),
+        register: (request) => register(r, request),
+        getAccountStatus: (request) => getAccountStatus(r, request),
+        fetch: (signedURL) => fetchVerb(r, signedURL),
+    };
+}
+/**
+ * createBrokerClient builds a client against a Broker's base URL.
+ *
+ * A SEPARATE constructor rather than a second surface on the exchange client because the
+ * two speak to different parties. A Broker is not an Exchange: it fans a query out across
+ * Exchanges it knows and relays back what they offered, so its address is the Broker's,
+ * not any Exchange's. Hanging both off one base URL would mean one of the two was always
+ * pointed at the wrong party.
+ *
+ * It takes the same options, but only the ones a discovery call has any use for do
+ * anything, and two need care. A single pinned offer key is the wrong shape here: Broker
+ * fan-out returns offers minted by different Exchanges, so inject a resolver that
+ * resolves each issuing Exchange's own key. And `requester` is REQUIRED, not optional: a
+ * Broker resolves the calling agent from it and declines a request naming none, so
+ * resolve refuses locally rather than spending a round trip to be told.
+ */
+export function createBrokerClient(baseURL, options = {}) {
+    const r = resolve(options);
+    return { resolve: (request) => brokerResolve(r, baseURL, request) };
+}
+// ---------------------------------------------------------------------------
+// The verbs
+// ---------------------------------------------------------------------------
+/**
+ * discover issues DiscoverResources and returns one group per requested URI, each
+ * carrying the fail-closed {verified, rejected} split.
+ *
+ * EVERY returned offer is verified against the exchange offer-signing key before it is
+ * handed back. Neither an unverifiable nor a doctored offer is silently dropped — it
+ * lands in `rejected` with a reason. A URI the responder GROUPED and left empty keeps its
+ * group, carrying the typed reason, so a refusal is an answer rather than an absence.
+ *
+ * The query is CLONED before `ver` and the requester are filled in, so the message the
+ * caller built stays untouched — it crossed a module boundary as an argument, not as a
+ * buffer. Both are filled only when EMPTY: a value the caller set is theirs.
+ *
+ * `exchange` is NOT among them: the caller MUST set it to the bare host of the Exchange
+ * being queried, because the contract requires every addressed request to name its
+ * recipient. It is left to the caller rather than derived from the base URL on purpose —
+ * the point of the field is to state whom the SENDER meant, and a value the transport
+ * filled in from the address it was already dialling would restate the dial target
+ * instead of checking it.
+ */
+async function discover(r, baseURL, query) {
+    const op = "discover";
+    const sent = stampDiscovery(op, query, r.opts.requester);
+    validateRequest(op, sent, ResourceQuerySchema, r.opts.validation ?? "strict");
+    const raw = await call(r, op, baseURL, EXCHANGE_SERVICE, "DiscoverResources", sent, false);
+    const msg = parseMessage(op, raw, ResourceResponseSchema);
+    return {
+        // The offers are read from the RAW answer, not the parsed one. A schema parse is
+        // the GATE — it proves the answer is well formed and that its field names are
+        // canonical — but it also NORMALIZES: Zod fills every declared default, which adds
+        // keys the signer never covered and would make a genuine offer fail verification.
+        // A signature covers what the responder sent.
+        groups: await discoveredGroups(r.verifier, sent, isRecord(raw) ? raw : {}),
+        exchange: typeof msg["exchange"] === "string" ? msg["exchange"] : "",
+        ...(isRecord(msg["rate_limit"]) ? { rateLimit: msg["rate_limit"] } : {}),
+    };
+}
+/**
+ * discoveredGroups folds a ResourceResponse's two offer representations into the per-URI
+ * form.
+ *
+ * The message carries a grouped list AND a flat one, and the contract says a responder
+ * populating groups SHOULD leave the flat list empty "to avoid ambiguity" — but a real
+ * Exchange populates both, the flat list mirroring the grouped offers as a single-URI
+ * convenience. So the two are read as ALTERNATIVES, never concatenated: concatenating
+ * would double every offer against such a server, and deduplicating would silently accept
+ * a responder whose two lists disagree, which is precisely the ambiguity the contract
+ * forbids.
+ *
+ * Groups win when present. The flat fallback becomes a single group; it carries no URI of
+ * its own, so it takes the query's only URI when the query named exactly one, and none
+ * otherwise — the SDK does not invent an attribution the wire did not make.
+ */
+async function discoveredGroups(verifier, query, msg) {
+    const groups = msg["offer_groups"];
+    if (Array.isArray(groups) && groups.length > 0) {
+        return verifier.sortGroups(groups.map(canonicalizeGroupOffers));
+    }
+    const flat = msg["offers"];
+    if (!Array.isArray(flat) || flat.length === 0)
+        return [];
+    const uris = query["uris"];
+    const uri = Array.isArray(uris) && uris.length === 1 && typeof uris[0] === "string"
+        ? uris[0]
+        : "";
+    return [
+        { uri, result: await verifier.sort(canonicalize(flat)), restrictionFilters: [] },
+    ];
+}
+/**
+ * canonicalize inverts the wire emission of each offer before it is verified.
+ *
+ * A FORA Exchange serves proto-JSON with EmitUnpopulated, so a wire offer carries
+ * zero-valued scalars, empty repeateds, null messages and *_UNSPECIFIED enums that the
+ * SIGNED form does not — the signature covers the omit-unpopulated rendering. Verifying
+ * the wire object as-is would fail every genuine offer, which is a fail-closed direction
+ * but the wrong answer. fromWireOffer is the schema-aware inversion, byte-parity-pinned
+ * against the Go oracle; a field newer than its pinned schema is kept verbatim, so an
+ * offer this SDK cannot reconstruct still verifies FALSE rather than being waved through.
+ *
+ * The verified value is therefore the CANONICAL offer, which is what execute reflects
+ * back: the Exchange verifies the presented bytes and re-renders them canonically either
+ * way, so reflecting the canonical form is the same statement with none of the wire
+ * emission's noise.
+ */
+function canonicalize(offers) {
+    return offers.map((offer) => isRecord(offer) ? fromWireOffer(offer) : offer);
+}
+/** canonicalizeGroupOffers applies the inversion to one group's offers, leaving the
+ * group's own URI and typed reasons untouched. */
+function canonicalizeGroupOffers(group) {
+    if (!isRecord(group))
+        return group;
+    const offers = group["offers"];
+    if (!Array.isArray(offers))
+        return group;
+    return { ...group, offers: canonicalize(offers) };
+}
+/**
+ * resolve runs discovery through the Broker, which fans out to the Exchanges it knows and
+ * returns one group per requested URI.
+ *
+ * Every returned offer is verified through the SAME fail-closed Verifier discover uses —
+ * not a second verification path. Broker-relayed offers are precisely the case that rule
+ * exists for: the Broker forwards offers it did not mint, and an unverified relay can
+ * steer an agent's selection with doctored terms that only fail later, at the purchase.
+ *
+ * A resolve that finds nothing is a SUCCESSFUL answer carrying a typed reason, not a
+ * failure: the whole-call reason lands on the result and the per-URI ones on each group.
+ *
+ * It carries no idempotency key. Pure discovery buys nothing and changes nothing, so
+ * there is nothing for a server to deduplicate — the request message has no such field.
+ */
+async function brokerResolve(r, baseURL, request) {
+    const op = "resolve";
+    const sent = stampDiscovery(op, request, r.opts.requester);
+    // Refused locally rather than sent: a Broker resolves the calling agent from the
+    // requester and declines a request that names none, so this is a verdict the client
+    // already knows, and naming the remedy beats relaying "requester required" from a
+    // round trip away. execute refuses the same way.
+    if (sent["requester"] === undefined) {
+        throw malformed(op, new Error("no requester configured; a Broker resolves who is asking"));
+    }
+    validateRequest(op, sent, DiscoveryRequestSchema, r.opts.validation ?? "strict");
+    const raw = await call(r, op, baseURL, BROKER_SERVICE, "Resolve", sent, false);
+    const msg = parseMessage(op, raw, DiscoveryResponseSchema);
+    // Read from the RAW answer for the same reason discover does: a parse normalizes, and
+    // a signature covers what the responder sent.
+    const groups = isRecord(raw) ? raw["offer_groups"] : undefined;
+    const absence = msg["absence_reason"];
+    return {
+        groups: await r.verifier.sortGroups(Array.isArray(groups) ? groups.map(canonicalizeGroupOffers) : []),
+        ...(typeof absence === "string" ? { absenceReason: absence } : {}),
+        // A DiscoveryResponse names no single Exchange and carries no rate-limit signal —
+        // each offer carries its own issuing domain instead.
+        exchange: "",
+    };
+}
+/**
+ * execute commits to a VERIFIED offer and returns the transaction response.
+ *
+ * It accepts ONLY a VerifiedOffer — the brand is module-private to the core, so passing a
+ * rejected offer or a raw parsed one is a COMPILE error. A per-call idempotency key is
+ * minted fresh unless one is pinned. execute builds the whole TransactionRequest, so it
+ * also stamps `ver` from ProtocolVersion — the caller neither supplies nor overrides it.
+ */
+async function execute(r, baseURL, offer, opts) {
+    const op = "execute";
+    if (r.opts.requester === undefined) {
+        throw malformed(op, new Error("no requester configured; an Exchange resolves who is buying from it"));
+    }
+    if (r.opts.signer === undefined) {
+        // not_signable, matching what fetch answers for the same missing holder: a caller
+        // branching on the kind sees one condition under one class, whichever verb met it
+        // first.
+        throw new ForaCallError({
+            kind: "not_signable",
+            op,
+            cause: new Error("no signer configured; a purchase carries a detached acceptance signed with the agent's own key"),
+        });
+    }
+    const wire = offer.offer;
+    const offerSig = typeof wire["signature"] === "string" ? wire["signature"] : "";
+    // An acceptance floating free of a concrete offer is meaningless, and an unsigned
+    // offer is reachable here: verification "off" and RejectedOffer.unsafe() both mint a
+    // VerifiedOffer without a signature check.
+    if (offerSig === "") {
+        throw malformed(op, new Error("cannot accept an unsigned offer"));
+    }
+    // `??` would take an EMPTY pinned key as a value and send it, which fails the
+    // message's own min(1). An empty string is the absence of a key, as Go and Python
+    // both read it.
+    const key = opts.idempotencyKey !== undefined && opts.idempotencyKey !== ""
+        ? opts.idempotencyKey
+        : generateIdempotencyKey();
+    const requester = r.opts.requester;
+    const requesterId = stringField(requester, "id");
+    const requesterDomain = stringField(requester, "domain");
+    const requestItems = [{ offerSig, exchange: stringField(wire, "exchange") }];
+    // The acceptance covers the offer, the requester and the idempotency key, so a retry
+    // that pins the same key reproduces byte-identical acceptance bytes. That is the
+    // deliberate-replay semantic, not an accident.
+    let signature;
+    try {
+        signature = await signOfferAcceptance({
+            offerSig,
+            requesterId,
+            requesterDomain,
+            idempotencyKey: key,
+        }, r.opts.signer.privKey);
+    }
+    catch (cause) {
+        throw new ForaCallError({ kind: "not_signable", op, cause });
+    }
+    let requestSignature;
+    if (requestItems[0].exchange !== "") {
+        try {
+            requestSignature = await signRequestAcceptance({ items: requestItems, requesterId, requesterDomain, idempotencyKey: key }, r.opts.signer.privKey);
+        }
+        catch (cause) {
+            throw new ForaCallError({ kind: "not_signable", op, cause });
+        }
+    }
+    // Items-only wire shape: a single offer is the degenerate 1-element items list, each
+    // item reflecting its signed Offer back exactly as received at discovery. The
+    // authoritative identity is the reflected offer; the optional top-level offer_id
+    // correlation scalar is left unset.
+    const request = {
+        ver: ProtocolVersion,
+        idempotency_key: key,
+        requester,
+        items: [
+            {
+                offer: wire,
+                agent_acceptance: {
+                    signature,
+                    signature_algorithm: ACCEPTANCE_SIGNATURE_ALGORITHM,
+                },
+            },
+        ],
+        ...(requestSignature === undefined
+            ? {} : { agent_request_acceptance: {
+                payload: {
+                    items: requestItems.map((item) => ({
+                        offer_sig: item.offerSig,
+                        exchange: item.exchange,
+                    })),
+                    requester_id: requesterId,
+                    requester_domain: requesterDomain,
+                    idempotency_key: key,
+                },
+                signature: requestSignature,
+                signature_algorithm: ACCEPTANCE_SIGNATURE_ALGORITHM,
+            } }),
+    };
+    validateRequest(op, request, TransactionRequestSchema, r.opts.validation ?? "strict");
+    const raw = await call(r, op, baseURL, EXCHANGE_SERVICE, "ExecuteTransaction", request, false);
+    return parseMessage(op, raw, TransactionResponseSchema);
+}
+/**
+ * reportUsage files a usage report with the Exchange that ISSUED the offer — never
+ * through a Broker, and never to an address from configuration.
+ *
+ * The destination comes off the report itself: `exchange` carries the offer's signed
+ * exchange domain, and the endpoint is then resolved from that Exchange's own well-known
+ * manifest. Reading it off the message rather than taking it as an argument is what makes
+ * the rule structural — there is no parameter a configured origin could be passed as, so
+ * it cannot become the default by anyone's convenience.
+ *
+ * The report is CLONED before `ver` and the idempotency key are stamped, so the message
+ * the caller built stays untouched. The key identifies the REPORT, not the attempt: a
+ * fresh one is minted only when the caller supplied none, because an application that
+ * mints its own key for its own dedup would otherwise have it silently discarded and see
+ * every retry counted as a second report.
+ */
+async function reportUsage(r, report, opts) {
+    const op = "report usage";
+    const sent = stampEnvelope(op, report, opts);
+    // The address is vetted BEFORE the schema: an unroutable recipient is a refusal to
+    // send, which is a different verdict from a message the server would reject, and the
+    // caller acts on them differently.
+    const endpoint = await vetExchangeEndpoint(r.opts.endpointResolver, stringField(sent, "exchange"), op);
+    validateRequest(op, sent, UsageReportSchema, r.opts.validation ?? "strict");
+    const raw = await call(r, op, endpoint, EXCHANGE_SERVICE, "ReportUsage", sent, true);
+    return parseMessage(op, raw, UsageReportResponseSchema);
+}
+/**
+ * dispute files a dispute with the Exchange that issued the offer, over the same vetted
+ * routing a usage report takes.
+ *
+ * The destination comes off the request, exactly as it does for a usage report. A
+ * parameter is something a configured origin can be passed as; reading the destination
+ * off the signed message leaves no such seam.
+ *
+ * The dispute chain is a structural invariant: an agent must have filed a usage report
+ * and received a report_id before it can dispute, so `report_id` and `transaction_id`
+ * both name links the Exchange already holds.
+ */
+async function dispute(r, request, opts) {
+    const op = "dispute";
+    const sent = stampEnvelope(op, request, opts);
+    const endpoint = await vetExchangeEndpoint(r.opts.endpointResolver, stringField(sent, "exchange"), op);
+    validateRequest(op, sent, DisputeRequestSchema, r.opts.validation ?? "strict");
+    const raw = await call(r, op, endpoint, EXCHANGE_SERVICE, "DisputeTransaction", sent, true);
+    return parseMessage(op, raw, DisputeResponseSchema);
+}
+// ---------------------------------------------------------------------------
+// The account-setup verbs
+//
+// They route like a usage report, not like discovery. An account is per-Exchange,
+// and which Exchange is the agent's choice PER CALL: a target routinely arrives at
+// runtime — a denial names where to register — rather than from configuration. So
+// the destination is read off the request's own `exchange` field and resolved
+// through that Exchange's own manifest, over the guarded leg.
+//
+// Neither message carries an idempotency key, so neither verb takes CallOptions.
+// ---------------------------------------------------------------------------
+/** The ErrorDetail domain for a refusal THIS CLIENT computed, before anything was
+ * sent. It names the failing surface, which here is the client's own tier: the
+ * Exchange never saw the request, so naming it would attribute a local verdict to a
+ * party that reached none. The naming rule the value follows — a Service suffix for
+ * an RPC service that exists in the contract, a bare noun for a tier that does not —
+ * is recorded on the Go oracle's edgeErrorDomain, beside EDGE_ERROR_DOMAIN's twin. */
+const CLIENT_ERROR_DOMAIN = "fora.v1.Client";
+/**
+ * register creates the calling agent's account at the Exchange the request names.
+ *
+ * The caller's identity is the request SIGNATURE. Nothing in the message says who is
+ * registering, and the business payload is not an identity claim.
+ *
+ * Four bounds on `registration_data` are checked before anything is signed, in the order
+ * the contract fixes, because a limit that exists to stop work belongs before the work it
+ * would stop — including before the manifest read.
+ *
+ * `terms_digest` is filled only when the caller left it ABSENT, from a freshly fetched
+ * manifest, and the payload is pre-checked against the schema that manifest publishes. A
+ * caller that sets the field is managing its own requirements and gets neither.
+ *
+ * A schema this SDK refuses never becomes a local veto: refusing locally and declining to
+ * send would turn a rule about reading a third party's document into a denial of service
+ * against the caller's own user, so an unusable schema is skipped and the Exchange
+ * decides. A usable schema the payload fails is the pre-check working, and that request is
+ * refused here with the offending members named.
+ */
+async function register(r, request) {
+    const op = "register";
+    const sent = stampVer(op, request);
+    requireRecipient(op, stringField(sent, "exchange"));
+    // Narrowed rather than asserted. The bounds below are defined over an OBJECT, and
+    // Object.keys on a string answers its character indices — so a cast let a string
+    // payload be refused as "too many members", a verdict about a bound it never
+    // reached and a member count it does not have. Go cannot express the state at all
+    // (the field is a Struct) and Python narrows the same way, so this is the port
+    // that had to say so.
+    const verdict = checkRegistrationData(isRecord(sent.registration_data) ? sent.registration_data : null);
+    if (verdict !== "accepted") {
+        throw malformed(op, new Error(`registration_data: ${verdict}`));
+    }
+    if (sent.terms_digest === undefined || sent.terms_digest === null) {
+        await applyRegistrationRequirements(r, op, sent);
+    }
+    const endpoint = await vetExchangeEndpoint(r.opts.endpointResolver, stringField(sent, "exchange"), op);
+    validateRequest(op, sent, RegisterRequestSchema, r.opts.validation ?? "strict");
+    const raw = await call(r, op, endpoint, EXCHANGE_SERVICE, "Register", sent, true);
+    return parseMessage(op, raw, RegisterResponseSchema);
+}
+/**
+ * getAccountStatus reports whether the calling agent's account at the named Exchange is
+ * active.
+ *
+ * The request carries no field identifying the caller — the Exchange resolves the account
+ * from the verified signature — so `exchange` is the only thing that says which account is
+ * being asked about. An empty `billing_ref` in the answer is a NORMAL answer: no account
+ * there yet.
+ *
+ * A caveat worth knowing before calling this in a loop. The request has no varying field,
+ * so two calls to the same Exchange inside one wall-clock second sign IDENTICAL bytes, and
+ * a peer screening replays on (key id, signature) refuses the second. This verb does not
+ * choose the freshness window for you, because a window is one instance per client rather
+ * than per call: pass `monotonicWindow` as `signWindow` when repeat calls are expected.
+ */
+async function getAccountStatus(r, request) {
+    const op = "get account status";
+    const sent = stampVer(op, request);
+    requireRecipient(op, stringField(sent, "exchange"));
+    const endpoint = await vetExchangeEndpoint(r.opts.endpointResolver, stringField(sent, "exchange"), op);
+    validateRequest(op, sent, GetAccountStatusRequestSchema, r.opts.validation ?? "strict");
+    const raw = await call(r, op, endpoint, EXCHANGE_SERVICE, "GetAccountStatus", sent, true);
+    return parseMessage(op, raw, GetAccountStatusResponseSchema);
+}
+/**
+ * applyRegistrationRequirements reads what the Exchange asks of a registration and applies
+ * it to the request being built.
+ *
+ * A failed READ refuses the registration rather than sending without a digest. Guessing
+ * here is not the cautious option: an Exchange that publishes a digest refuses a
+ * registration that omits one, so sending anyway trades a local failure the caller can act
+ * on for a remote one it cannot.
+ */
+async function applyRegistrationRequirements(r, op, sent) {
+    let reqs;
+    try {
+        reqs = await r.requirements.resolveRegistrationRequirements(stringField(sent, "exchange"));
+    }
+    catch (err) {
+        // A value this deployment or the Exchange refused is FINAL; anything else is a
+        // transport failure worth retrying. The same split the routing tier makes, and
+        // the same causes: a value that is not a host will not become one on a later
+        // attempt either, and a document that arrived unusable arrives unusable again.
+        // The SDK's own reader throws all three itself — the middle two for the document
+        // it was handed, and ManifestUnusable for a version it cannot classify — and an
+        // INJECTED reader stricter than it reaches the same three. Only the invalid-host
+        // refusal is normally out of reach here, because the verb's own recipient check
+        // runs that rule first. Classifying any of them as retryable would have a caller
+        // retry a verdict.
+        if (err instanceof ExchangeNotPermitted ||
+            err instanceof ManifestNotExchange ||
+            err instanceof ManifestUnusable ||
+            isInvalidHostRefusal(err)) {
+            throw notSent(op, err);
+        }
+        throw new ForaCallError({ kind: "unreachable", op, cause: err });
+    }
+    if (reqs.termsDigest !== undefined) {
+        sent.terms_digest = reqs.termsDigest;
+    }
+    // A null validator means "nothing to enforce", which is the behaviour the contract
+    // requires both when the Exchange publishes no schema and when it publishes one this
+    // SDK refused. One branch, deliberately.
+    const fails = reqs.schema?.validate(sent.registration_data ?? {}) ?? [];
+    if (fails.length > 0) {
+        // An empty path addresses the whole object, which is how a missing required
+        // member and every other whole-object failure is reported. Rendering a bare
+        // ": ..." there would read as a member with no name.
+        const named = fails.map((f) => (f.path ? `${f.path}: ${f.error}` : f.error)).join("; ");
+        // The failures travel as a typed detail, not only as prose. An Exchange attaches
+        // this same list when it refuses the same payload, so a consumer that renders one
+        // refusal renders both, and nothing has to parse the members back out of a
+        // sentence.
+        throw new ForaCallError({
+            kind: "malformed",
+            op,
+            cause: new Error(`registration_data does not match the schema ${stringField(sent, "exchange")} publishes: ${named}`),
+            detail: registrationFailureDetail(CLIENT_ERROR_DOMAIN, "registration_data does not match the published data_schema", "REGISTRATION_FAILURE_REASON_INVALID_REGISTRATION_DATA", fails),
+        });
+    }
+}
+/**
+ * fetch retrieves the content a signed delivery URL names, presenting proof of possession
+ * of the agent key that URL is bound to.
+ *
+ * This is the LOW-TIER fetch: follow one signed URL, present the key, return the bytes. It
+ * does not discover, select, buy or report — that orchestration is a separate, higher
+ * tier.
+ *
+ * It takes no CallOptions: a fetch is a GET against an already-issued URL, so there is no
+ * idempotency key to pin — nothing on this path mutates state.
+ */
+async function fetchVerb(r, signedURL) {
+    const op = "fetch content";
+    if (r.opts.signer === undefined) {
+        throw new ForaCallError({
+            kind: "not_signable",
+            op,
+            cause: new Error("no signer configured; a bound fetch proves possession of the agent key — " +
+                "the same key the request is signed with"),
+        });
+    }
+    if (r.opts.agentPublicKey === undefined) {
+        throw new ForaCallError({
+            kind: "not_signable",
+            op,
+            cause: new Error("no agent public key configured; a bound fetch presents it alongside the " +
+                "proof, and a non-extractable signing key cannot yield it"),
+        });
+    }
+    return fetchContent(signedURL, {
+        // One private key, held by the signer. The public half rides alongside because
+        // custody keeps the private one and a CryptoKey cannot be asked for its pair.
+        keyPair: { privateKey: r.opts.signer.privKey, publicKey: r.opts.agentPublicKey },
+        // The proof window is the client's, not the signer's. core/sign.ts defaults to the
+        // 10-minute TTL a server-side proof uses; a delivery proof is minted for one GET
+        // and wants the short window instead, so the default is set here rather than
+        // inherited.
+        window: r.opts.proofWindow ?? clockWindow(() => Date.now() / 1000, DEFAULT_PROOF_WINDOW_SEC),
+        ...(r.opts.contentTimeoutMs !== undefined
+            ? { timeoutMs: r.opts.contentTimeoutMs }
+            : {}),
+        ...(r.opts.maxContentBytes !== undefined
+            ? { maxBytes: r.opts.maxContentBytes }
+            : {}),
+        ...(r.opts.requestId !== undefined ? { requestId: r.opts.requestId } : {}),
+    });
+}
+// ---------------------------------------------------------------------------
+// Envelope stamping
+// ---------------------------------------------------------------------------
+/**
+ * stampDiscovery fills the envelope a DISCOVERY call carries, which is the mutating
+ * envelope minus the idempotency key: pure discovery buys nothing and changes nothing, so
+ * there is no action for a key to identify.
+ *
+ * Both fills are only-when-empty. The caller's own value always wins — the message
+ * crossed a module boundary as an argument, not as a buffer to fill in — and the
+ * requester is filled because both reference services resolve the calling agent from it
+ * and refuse a request that names none, while the client already holds that identity.
+ */
+function stampDiscovery(op, message, requester) {
+    const sent = clone(op, message);
+    if (sent["ver"] === undefined || sent["ver"] === "")
+        sent["ver"] = ProtocolVersion;
+    if (sent["requester"] === undefined && requester !== undefined) {
+        sent["requester"] = requester;
+    }
+    return sent;
+}
+/**
+ * stampEnvelope fills the two envelope fields the protocol requires on a state-mutating
+ * call, WITHOUT overwriting what the caller already set.
+ *
+ * Fill-when-empty is the whole rule. `ver` has a single owner, so the SDK supplies it
+ * rather than making every caller reach for the constant. The idempotency key is REQUIRED
+ * and identifies the action rather than the attempt, so a value the caller put there is
+ * theirs — discarding it would turn each of their retries into a fresh action, which is
+ * the double-counting the field exists to prevent. A pinned key overrides both.
+ */
+function stampEnvelope(op, message, opts) {
+    const sent = clone(op, message);
+    if (sent["ver"] === undefined || sent["ver"] === "")
+        sent["ver"] = ProtocolVersion;
+    const onMessage = sent["idempotency_key"];
+    // Each fallback is taken when the one before it is EMPTY, not merely absent: an empty
+    // pinned key is no key, which is how Go and Python both read it.
+    sent["idempotency_key"] =
+        opts.idempotencyKey !== undefined && opts.idempotencyKey !== ""
+            ? opts.idempotencyKey
+            : typeof onMessage === "string" && onMessage !== ""
+                ? onMessage
+                : generateIdempotencyKey();
+    return sent;
+}
+// clone copies a caller's message so the SDK can stamp its envelope without touching what
+// the caller still holds. structuredClone is the runtime's own deep copy; a message that
+// cannot survive it is one that cannot be serialized to the wire either.
+function clone(op, message) {
+    try {
+        return structuredClone(message);
+    }
+    catch (cause) {
+        throw malformed(op, cause);
+    }
+}
+function stringField(record, key) {
+    const value = record[key];
+    return typeof value === "string" ? value : "";
+}
+function isRecord(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+/**
+ * createCatalogClient builds a client against an Exchange's CATALOG endpoint — the
+ * publisher role's face: push, remove and refresh the catalog entries a publisher, or a
+ * contributor it authorised, supplies.
+ *
+ * A SEPARATE constructor, as the Broker's is, and for a related reason: the address is a
+ * different one. An Exchange advertises CatalogService at its manifest's
+ * `catalog_endpoint`, distinct from the ExchangeService endpoint the agent client dials,
+ * and the caller is a different party holding a different key — a contributor's, named
+ * by `caller_id`, never an agent's. Hanging the catalog verbs on the agent client would
+ * carry every agent-only holder into a client that uses none of them, and point one of
+ * the two roles at the wrong address.
+ *
+ * The publisher chose the Exchange, so the origin is configuration and the leg runs on
+ * the plain send — the posture of the agent client's home Exchange, not of its
+ * offer-derived leg. It takes the same options; `signer` is what a real push needs (an
+ * Exchange refuses an unsigned catalog call), and the agent-only ones — the requester,
+ * the agent key, the offer-key resolver, the endpoint resolver, the guarded send — are
+ * inert here rather than errors, so one option set can build every face.
+ */
+export function createCatalogClient(baseURL, options = {}) {
+    const r = resolve(options);
+    return {
+        pushResources: (request) => catalogCall(r, baseURL, "push resources", "PushResources", PushResourcesRequestSchema, PushResourcesResponseSchema, request),
+        removeResources: (request) => catalogCall(r, baseURL, "remove resources", "RemoveResources", RemoveResourcesRequestSchema, RemoveResourcesResponseSchema, request),
+        refreshCatalog: (request) => catalogCall(r, baseURL, "refresh catalog", "RefreshCatalog", RefreshCatalogRequestSchema, RefreshCatalogResponseSchema, request),
+    };
+}
+/**
+ * catalogCall is the one shape all three catalog verbs share. The request is CLONED
+ * before `ver` is stamped (fill-when-empty; the caller's value is theirs); no
+ * idempotency key is stamped, because the messages carry none — a catalog push is an
+ * upsert and naturally idempotent, so a key there would be ceremony. `exchange` is the
+ * caller's to set, the bare domain of the Exchange the call is meant for; a request
+ * that names none, or names something that is not a bare domain, is refused before
+ * anything is signed or sent — a refusal to send, the verdict a report with no
+ * routable recipient gets, not a malformed message.
+ */
+async function catalogCall(r, baseURL, op, method, requestSchema, responseSchema, request) {
+    const sent = stampVer(op, request);
+    requireRecipient(op, stringField(sent, "exchange"));
+    validateRequest(op, sent, requestSchema, r.opts.validation ?? "strict");
+    const raw = await call(r, op, baseURL, CATALOG_SERVICE, method, sent, false);
+    return parseMessage(op, raw, responseSchema);
+}
+function stampVer(op, message) {
+    const sent = clone(op, message);
+    if (sent["ver"] === undefined || sent["ver"] === "")
+        sent["ver"] = ProtocolVersion;
+    return sent;
+}
+// Serves the catalog verbs and the two account verbs, and asks only the SHAPE question.
+//
+// The predicate is isBareDomain, the SHAPE rule, not the routing rule isBareHost. The
+// only question it answers is whether the value is the form the contract admits, which
+// is the protovalidate pattern `exchange` carries and the same rule the Exchange's own
+// audience check applies on arrival. Whether the value can be DIALLED is a separate
+// question with a separate answer: a catalog client is built against an address the
+// publisher configured and never asks it, while the account verbs resolve this domain
+// through its own manifest and ask it there, under the routing predicate. The routing
+// predicate is deliberately wider: an underscore, a trailing root dot and a bracketed
+// IPv6 literal are all usable hosts and none of them is a value this field may hold,
+// so vetting with it would sign and send a request the recipient can only refuse.
+//
+// The refused value is redacted before it is named. A reference carrying userinfo is a
+// verdict rather than a parse failure, so it reaches the message below verbatim; the
+// routing check next door redacts for the same reason, and a tier that echoes is the
+// drift redactUserinfo exists to prevent.
+function requireRecipient(op, exchange) {
+    if (exchange === "") {
+        throw notSent(op, new Error("request names no recipient; set exchange to the Exchange's bare domain"));
+    }
+    if (!isBareDomain(exchange)) {
+        throw notSent(op, new Error(`exchange ${JSON.stringify(redactUserinfo(exchange))} is not a bare domain`));
+    }
+}
+export { ForaCallError } from "./errors.js";
+export { DEFAULT_CALL_TIMEOUT_MS, DEFAULT_MAX_RPC_READ_BYTES, NOT_CANONICAL_WIRE_NAMING, } from "./transport.js";
+export { DEFAULT_CONTENT_TIMEOUT_MS, DEFAULT_MAX_CONTENT_BYTES, } from "./content.js";