@fora-protocol/sdk 1.0.3

package/sdk/ts/client/route.d.ts

@@ -0,0 +1,41 @@
+/**
+ * EndpointResolver turns a signed exchange domain into the origin that Exchange
+ * advertises for itself. It is an interface so a test can drive reporting without
+ * standing up a manifest server — and, more to the point, so this module has no way to
+ * accept a report endpoint from configuration.
+ *
+ * An implementation's FAILURE decides how a caller is told to react, so it is part of the
+ * contract rather than an implementation detail. A failure that is a VERDICT — the host
+ * is unusable, the host is not allowed, the manifest carries a version this reader does
+ * not accept, advertises no endpoint, or advertises one that must not be used — MUST
+ * throw the resolver tier's ManifestVersionRefused, NoEndpoint or EndpointRefused, or
+ * the invalid-host error isBareHost raises; those surface as `not_sent`, which tells
+ * the caller not to retry. Anything else is read as a transport
+ * failure and reported as `unreachable`, i.e. worth retrying. An implementation that
+ * throws a bare error for a refusal therefore has its final answer retried indefinitely.
+ */
+export interface EndpointResolver {
+    resolveEndpoint(host: string): Promise<string>;
+}
+/**
+ * vetExchangeEndpoint resolves an exchange domain to an origin a signed call may be sent
+ * to, or refuses — naming the check that declined, and classifying it by CAUSE. "The
+ * Exchange said no", "we could not reach it" and "we refused to dial it" are three
+ * different outcomes calling for three different responses, and only the class tells them
+ * apart: a verdict is final, a transport failure is worth retrying.
+ *
+ * It is one function so the vetting reads in one place: the checks are the part that
+ * grows, and seeing them together is what makes it evident that no branch falls through
+ * to the send.
+ */
+export declare function vetExchangeEndpoint(resolver: EndpointResolver | undefined, exchangeDomain: string, op: string): Promise<string>;
+/** Whether a cause is the invalid-host refusal.
+ *
+ * Matched on its wording rather than its type. The host helpers are L1 and deliberately
+ * raise a bare error for it — a typed InvalidHost would cross the helpers-versus-resolvers
+ * sentinel split the SDK documents — so the shared prefix is what there is to match.
+ *
+ * Exported because TWO injectable readers can raise it, the endpoint resolver and the
+ * registration-requirements reader, and both have to call it final for the same reason. A
+ * second copy of the prefix is exactly how the two would come to disagree. */
+export declare function isInvalidHostRefusal(cause: unknown): boolean;

package/sdk/ts/client/route.js

@@ -0,0 +1,107 @@
+// Routing a call to the Exchange that ISSUED an offer. TS port of sdk/go/connect/route.go.
+//
+// There are three kinds of destination, and the difference decides how much checking a
+// call needs. The Broker and the home Exchange come from the client's own configuration
+// and are trusted as far as that configuration is. The Exchange a usage report goes to is
+// named inside an OFFER, which arrived over the network — so an actor who can influence
+// an offer can influence that address.
+//
+// A signature covers the DOMAIN; it says nothing about where that domain's endpoint
+// lives, or where its DNS points. That is why the address is resolved from the Exchange's
+// own manifest and then checked, rather than taken on trust or, worse, read from
+// configuration.
+import { EndpointRefused, ManifestVersionRefused, NoEndpoint } from "./../resolvers/errors.js";
+import { endpointRefusal } from "../src/endpoint-rule.js";
+import { isBareHost } from "../src/hosts.js";
+import { redactUserinfo } from "../src/host-ref.js";
+import { ForaCallError, notSent } from "./errors.js";
+/**
+ * vetExchangeEndpoint resolves an exchange domain to an origin a signed call may be sent
+ * to, or refuses — naming the check that declined, and classifying it by CAUSE. "The
+ * Exchange said no", "we could not reach it" and "we refused to dial it" are three
+ * different outcomes calling for three different responses, and only the class tells them
+ * apart: a verdict is final, a transport failure is worth retrying.
+ *
+ * It is one function so the vetting reads in one place: the checks are the part that
+ * grows, and seeing them together is what makes it evident that no branch falls through
+ * to the send.
+ */
+export async function vetExchangeEndpoint(resolver, exchangeDomain, op) {
+    if (resolver === undefined) {
+        throw notSent(op, new Error("no endpoint resolver configured"));
+    }
+    if (exchangeDomain === "") {
+        throw notSent(op, new Error("no exchange domain to route to; it comes from the signed offer"));
+    }
+    // A plain hostname, checked here even if the caller checked it. The resolver builds
+    // its URL by concatenating this value, so a path or query smuggled through would
+    // choose what gets fetched; this module owns the call and cannot rely on every present
+    // and future caller having vetted it.
+    let bare;
+    try {
+        bare = isBareHost(exchangeDomain);
+    }
+    catch (cause) {
+        throw notSent(op, new Error(`exchange ${redactUserinfo(exchangeDomain)} is not a usable domain: ${cause instanceof Error ? cause.message : String(cause)}`));
+    }
+    if (!bare) {
+        throw notSent(op, new Error(`exchange ${redactUserinfo(exchangeDomain)} is not a bare domain, refusing to resolve it`));
+    }
+    let endpoint;
+    try {
+        endpoint = await resolver.resolveEndpoint(exchangeDomain);
+    }
+    catch (cause) {
+        // Classified by CAUSE, not by position. Reaching the manifest is a network
+        // operation, and a DNS blip or a 500 from an otherwise healthy Exchange is
+        // TRANSIENT — reporting it as a refusal would tell a caller "we declined to send
+        // this, do not retry" and permanently drop a usage report over a momentary outage.
+        // Only a verdict is a refusal: the value was not a usable host, the host was not
+        // allowed, the manifest was read and advertises no endpoint at all, or it
+        // advertises one the resolver will not hand back.
+        throw new ForaCallError({
+            kind: isVerdict(cause) ? "not_sent" : "unreachable",
+            op,
+            cause: new Error(`resolve exchange ${exchangeDomain}: ${cause instanceof Error ? cause.message : String(cause)}`),
+        });
+    }
+    // Re-checked here even though the SDK's own resolver already refuses such an endpoint.
+    // The resolver is an injectable seam — its own docs offer it so a caller can drive
+    // reporting without a manifest server — and this module cannot make a SIGNED call
+    // conditional on a stranger's implementation having remembered the rule. The cost is
+    // string work on a path that just did a network fetch.
+    //
+    // The SAME predicate both times, deliberately. Stated twice it drifts, and a
+    // half-mirrored version of this rule is how a signed call ends up carrying credentials
+    // the SDK never chose.
+    const refusal = endpointRefusal(exchangeDomain, endpoint);
+    if (refusal !== undefined) {
+        throw notSent(op, new Error(`refusing to send a signed call to the endpoint exchange ${redactUserinfo(exchangeDomain)} advertises: ${refusal}`));
+    }
+    return endpoint;
+}
+/** Whether a cause is the invalid-host refusal.
+ *
+ * Matched on its wording rather than its type. The host helpers are L1 and deliberately
+ * raise a bare error for it — a typed InvalidHost would cross the helpers-versus-resolvers
+ * sentinel split the SDK documents — so the shared prefix is what there is to match.
+ *
+ * Exported because TWO injectable readers can raise it, the endpoint resolver and the
+ * registration-requirements reader, and both have to call it final for the same reason. A
+ * second copy of the prefix is exactly how the two would come to disagree. */
+export function isInvalidHostRefusal(cause) {
+    return (cause instanceof Error &&
+        cause.message.startsWith("hosts: reference is not a usable host"));
+}
+// isVerdict tells the resolver's final answers from its transient ones. The invalid-host
+// error is in the set because the resolver checks the host itself too, and a value that
+// is not a host will not become one on a later attempt. This module checks it before
+// resolving, so the SDK's own resolver never reaches here that way — an injected one can.
+function isVerdict(cause) {
+    if (cause instanceof ManifestVersionRefused ||
+        cause instanceof NoEndpoint ||
+        cause instanceof EndpointRefused) {
+        return true;
+    }
+    return isInvalidHostRefusal(cause);
+}

package/sdk/ts/client/send.d.ts

@@ -0,0 +1,64 @@
+import { type UnarySend } from "./transport.ts";
+/** How the default send decides whether to dial through the SSRF guard. */
+export interface SendOptions {
+    /**
+     * Whether the dial-time address guard is applied. It exists for the legs whose host
+     * is chosen by a party on the network — the offer-derived Exchange and the delivery
+     * edge. The home Exchange and the Broker are operator-configured, so their address is
+     * trusted as far as that configuration is.
+     */
+    guarded: boolean;
+}
+/**
+ * createUnarySend returns the SDK's own dialing seam.
+ *
+ * One dispatcher per send, holding the guard connector and no redirect interceptor, so a
+ * proxied CONNECT cannot tunnel a private target past the dial guard and a 3xx arrives as
+ * an ordinary response this tier can classify.
+ */
+export declare function createUnarySend(opts: SendOptions): UnarySend;
+/**
+ * readBounded consumes a body under the caller's cap.
+ *
+ * It reads one byte past the cap so an oversized body is DETECTED rather than silently
+ * truncated. Truncated content that looks whole is worse than a refusal: a caller has no
+ * way to tell it is incomplete, and on the delivery leg it has already paid for it.
+ */
+export declare function readBounded(body: AsyncIterable<Uint8Array>, maxBytes: number, op?: string): Promise<string>;
+/**
+ * reclaim releases the socket behind a response body that was not read to the end.
+ *
+ * Every refusal above a read is one of these: the check that rejects a coding, the class
+ * that rejects a redirect. Each throws while the body is still mid-stream, and undici
+ * cannot return a connection whose response nobody consumed — so the socket stays open
+ * until the PEER hangs up, and a peer that never does is exactly the party these guards
+ * exist to contain. Measured before this: six refusals left six live sockets, still six
+ * after fifteen seconds idle, on a dispatcher the delivery leg shares process-wide. With a
+ * bounded pool one refusal wedged it outright and the client's own deadline did not break
+ * it.
+ *
+ * Both siblings get this from an idiom TypeScript has no equivalent of — Go from
+ * `defer resp.Body.Close()`, Python from `with … stream()` — so here it is spelled out, in
+ * a `finally` rather than at each throw. That placement is the point: the last regression
+ * added a throw ABOVE the branch that happened to be doing the reclaiming, and a fix
+ * attached to the throws we can currently name would go the same way.
+ *
+ * DESTROY rather than drain. Reading the body to free the socket would be an unbounded read
+ * from a peer whose answer is already refused, and draining under a cap is what undici's
+ * `dump` does — but `dump` settles only when the stream closes, so awaiting it hands a peer
+ * that trickles control of how long the refusal takes. Nothing is owed to a body that is
+ * being discarded.
+ *
+ * Idempotent, so the paths that already consumed can run through it unharmed: a read that
+ * finished has ended, and one that threw mid-iteration was destroyed by the loop's own
+ * exit. `destroy` alone would be safe on an ended stream — undici raises the abort only
+ * while `endEmitted` is false — but the guard says so where a reader will see it.
+ */
+export declare function reclaim(body: {
+    readonly destroyed: boolean;
+    readonly readableEnded: boolean;
+    on: (event: "error", listener: () => void) => unknown;
+    destroy: () => void;
+}): void;
+/** concat joins the read chunks into one buffer. */
+export declare function concat(chunks: Uint8Array[], total: number): Uint8Array;

package/sdk/ts/client/send.js

@@ -0,0 +1,142 @@
+// The default dialing seam for the client tier.
+//
+// It runs on undici, like the resolver tier's transport, with one deliberate difference:
+// REDIRECTS ARE REFUSED rather than followed under a cap. The resolvers fetch public
+// well-known documents, where following a hop is harmless; every leg here carries a
+// credential — an RFC 9421 signature, or a proof of possession bound to one URL — and
+// following a 3xx would either replay that credential at a host the peer chose or mint a
+// fresh one for it. A 3xx is an answer to report, never a hop to take.
+//
+// The address pin is composed here rather than accepted already built: this factory takes
+// what sits UNDER it, never what replaces it. It matters most on the offer-derived leg,
+// where the caller names a domain, the manifest it serves names an endpoint, and a signed
+// call then goes there — without the pin one hop down, that is a signed request aimed at
+// an arbitrary internal address.
+//
+// A caller CAN replace this whole factory, by passing their own UnarySend to the client.
+// That takes the address pin with it, which is the same latitude the Python client gives
+// an injected httpx client and more than Go gives at all. What it does NOT take is the
+// scheme gate: that lives in unaryCall, above the send, so no injected dial reaches a
+// plaintext endpoint carrying a signature.
+//
+// An edge runtime with no undici injects its own send. That is the same escape hatch the
+// resolver tier offers, and the same obligations come with it: no redirects, no reading
+// past the caller's byte bound, and the lifetime of a body it does NOT read — a refusal
+// that walks away from an unread stream holds the socket open until the peer hangs up,
+// and a peer that never does is the case the guard exists for. See reclaim.
+import { Agent, request as undiciRequest } from "undici";
+import { skipSSRF, ssrfGuard } from "../resolvers/http.js";
+import { ForaCallError } from "./errors.js";
+import { refuseUnrequestedEncoding, } from "./transport.js";
+/**
+ * createUnarySend returns the SDK's own dialing seam.
+ *
+ * One dispatcher per send, holding the guard connector and no redirect interceptor, so a
+ * proxied CONNECT cannot tunnel a private target past the dial guard and a 3xx arrives as
+ * an ordinary response this tier can classify.
+ */
+export function createUnarySend(opts) {
+    // The address guard, unless the deployment turned it off — the same SKIP_SSRF switch
+    // Go reads in NewGuardedTransport and Python in guarded_client. The scheme gate below
+    // is separate and is NOT covered by that flag; ALLOW_INSECURE is its own decision.
+    const dispatcher = opts.guarded && !skipSSRF() ? new Agent({ connect: ssrfGuard() }) : new Agent();
+    return async (req) => {
+        const response = await undiciRequest(req.url, {
+            method: "POST",
+            headers: req.headers,
+            body: req.body,
+            signal: req.signal,
+            dispatcher,
+            // undici follows nothing unless the redirect interceptor is composed in, so
+            // the refusal is the absence of that interceptor rather than a setting.
+            maxRedirections: 0,
+        });
+        try {
+            // Before a byte is read: a coding the client did not negotiate cannot be
+            // bounded, because a decoder expands a whole raw read at once. The headers are
+            // only visible here, which is why the check lives in the send rather than
+            // beside the decode.
+            refuseUnrequestedEncoding(req.op, response.statusCode, response.headers);
+            return {
+                status: response.statusCode,
+                body: await readBounded(response.body, req.maxBytes, req.op),
+            };
+        }
+        finally {
+            reclaim(response.body);
+        }
+    };
+}
+/**
+ * readBounded consumes a body under the caller's cap.
+ *
+ * It reads one byte past the cap so an oversized body is DETECTED rather than silently
+ * truncated. Truncated content that looks whole is worse than a refusal: a caller has no
+ * way to tell it is incomplete, and on the delivery leg it has already paid for it.
+ */
+export async function readBounded(body, maxBytes, op = "read response") {
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of body) {
+        total += chunk.length;
+        if (total > maxBytes) {
+            throw new ForaCallError({
+                kind: "too_large",
+                op,
+                cause: new Error(`body exceeds the ${maxBytes} byte cap`),
+            });
+        }
+        chunks.push(chunk);
+    }
+    return new TextDecoder().decode(concat(chunks, total));
+}
+/**
+ * reclaim releases the socket behind a response body that was not read to the end.
+ *
+ * Every refusal above a read is one of these: the check that rejects a coding, the class
+ * that rejects a redirect. Each throws while the body is still mid-stream, and undici
+ * cannot return a connection whose response nobody consumed — so the socket stays open
+ * until the PEER hangs up, and a peer that never does is exactly the party these guards
+ * exist to contain. Measured before this: six refusals left six live sockets, still six
+ * after fifteen seconds idle, on a dispatcher the delivery leg shares process-wide. With a
+ * bounded pool one refusal wedged it outright and the client's own deadline did not break
+ * it.
+ *
+ * Both siblings get this from an idiom TypeScript has no equivalent of — Go from
+ * `defer resp.Body.Close()`, Python from `with … stream()` — so here it is spelled out, in
+ * a `finally` rather than at each throw. That placement is the point: the last regression
+ * added a throw ABOVE the branch that happened to be doing the reclaiming, and a fix
+ * attached to the throws we can currently name would go the same way.
+ *
+ * DESTROY rather than drain. Reading the body to free the socket would be an unbounded read
+ * from a peer whose answer is already refused, and draining under a cap is what undici's
+ * `dump` does — but `dump` settles only when the stream closes, so awaiting it hands a peer
+ * that trickles control of how long the refusal takes. Nothing is owed to a body that is
+ * being discarded.
+ *
+ * Idempotent, so the paths that already consumed can run through it unharmed: a read that
+ * finished has ended, and one that threw mid-iteration was destroyed by the loop's own
+ * exit. `destroy` alone would be safe on an ended stream — undici raises the abort only
+ * while `endEmitted` is false — but the guard says so where a reader will see it.
+ */
+export function reclaim(body) {
+    if (body.destroyed || body.readableEnded)
+        return;
+    // Tearing down a stream that has not ended raises an abort ON that stream, and an
+    // "error" nothing is listening for is an uncaught exception in Node — so releasing the
+    // socket would take the caller's process down on every refusal, which is worse than the
+    // leak. The listener is what makes the teardown survivable, and undici's own discard
+    // helper carries the same one for the same reason.
+    body.on("error", () => { });
+    body.destroy();
+}
+/** concat joins the read chunks into one buffer. */
+export function concat(chunks, total) {
+    const out = new Uint8Array(total);
+    let at = 0;
+    for (const chunk of chunks) {
+        out.set(chunk, at);
+        at += chunk.length;
+    }
+    return out;
+}

package/sdk/ts/client/transport.d.ts

@@ -0,0 +1,187 @@
+import type { Window } from "../core/window.ts";
+/**
+ * DEFAULT_MAX_RPC_READ_BYTES caps the response body a single FORA call will read.
+ *
+ * A FORA response for a realistic batch is small; the bound is what stops a peer —
+ * including one an offer named — spending the caller's memory on its behalf. Mirrors the
+ * Go client's DefaultMaxRPCReadBytes.
+ */
+export declare const DEFAULT_MAX_RPC_READ_BYTES: number;
+/**
+ * DEFAULT_CALL_TIMEOUT_MS bounds one call. A FORA RPC is interactive — something is
+ * waiting on the other end — so a request that has not answered by now is more useful as
+ * an error than as a hang. Mirrors the Go client's DefaultCallTimeout.
+ */
+export declare const DEFAULT_CALL_TIMEOUT_MS = 30000;
+/** One outbound unary request, after the SDK has assembled and signed it. */
+export interface UnaryRequest {
+    url: string;
+    headers: Record<string, string>;
+    body: Uint8Array<ArrayBuffer>;
+    /** Aborts the send when the call's deadline elapses. */
+    signal: AbortSignal;
+    /** The body bound the send must not read past. */
+    maxBytes: number;
+    /** The verb, so a failure raised inside the send names the call rather than the
+     * mechanism — Go and Python both report it. */
+    op: string;
+}
+/** What a send returns. The body is already read, bounded, as text. */
+export interface UnaryResponse {
+    status: number;
+    body: string;
+}
+/**
+ * The seam the transport dials through. Injected, so an edge runtime supplies its own and
+ * a test drives the whole client without a socket.
+ *
+ * An implementation MUST honour `signal`: the tier above sets the call deadline on it and
+ * has no other way to stop a send that never returns. The shipped send passes it to undici.
+ *
+ * What an implementation is NOT responsible for is the scheme: `unaryCall` refuses a URL it
+ * will not dial before this is ever called, so a send cannot admit one by omission. What it
+ * DOES take on by replacing the shipped send is the dial-time address pin — the check that
+ * a hostname resolves somewhere public — which the default composes and an injected send
+ * must compose for itself if it needs one.
+ *
+ * An implementation MUST NOT follow redirects. Following one would re-sign the caller's
+ * request for a target the peer chose, after the endpoint check had already passed — a
+ * 3xx is an answer to be reported, never a hop to take. It MUST also refuse to read past
+ * `maxBytes`, and signal that by throwing a ForaCallError of kind `too_large`.
+ */
+export type UnarySend = (req: UnaryRequest) => Promise<UnaryResponse>;
+/** Where a call is addressed: the origin, the fully-qualified service, and the method. */
+export interface UnaryTarget {
+    baseURL: string;
+    service: string;
+    method: string;
+}
+/** The identity a signed call carries. Absent means the call goes out unsigned. */
+export interface CallSigner {
+    privKey: CryptoKey;
+    keyid: string;
+    /** The WBA directory origin this client signs as. Covered by the signature even when
+     * empty, so it is passed through verbatim rather than defaulted here. */
+    signatureAgent?: string;
+    /** The RFC 9421 freshness window. Defaults to the signing transport's own. */
+    window?: Window;
+}
+/** Everything one unary call needs beyond its message. */
+export interface UnaryCallOptions {
+    target: UnaryTarget;
+    op: string;
+    /** The request message, already validated by its generated schema. */
+    message: unknown;
+    send: UnarySend;
+    /** Whether this leg dials a host another party named — an offer-derived Exchange. The
+     * scheme is gated here rather than inside the send, so replacing the send cannot
+     * remove it. */
+    guarded?: boolean;
+    signer?: CallSigner;
+    requestId?: () => string;
+    maxBytes?: number;
+    timeoutMs?: number;
+}
+/**
+ * rpcURL joins an origin to the Connect unary path. The trailing slash is trimmed so a
+ * base URL written either way addresses the same method — a doubled slash is a different
+ * path to some servers and a 404 from them.
+ */
+export declare function rpcURL(target: UnaryTarget): string;
+/**
+ * unaryCall sends one FORA RPC and returns the peer's answer as parsed JSON.
+ *
+ * The body is serialized ONCE and the same bytes are signed and sent: RFC 9530
+ * Content-Digest covers the exact octets, so re-serializing between signing and sending
+ * would produce a digest for a body the peer never received.
+ */
+export declare function unaryCall(opts: UnaryCallOptions): Promise<unknown>;
+/**
+ * IDENTITY_ENCODING asks the peer for no content coding.
+ *
+ * Sending nothing is not the same thing: per RFC 9110 §12.5.3 an absent Accept-Encoding
+ * means ANY coding is acceptable, and undici does not decode one — so a gzipped answer
+ * would arrive as raw octets, fail to parse, and be reported as the peer's fault for
+ * something the peer was entitled to do.
+ */
+export declare const IDENTITY_ENCODING: {
+    readonly "accept-encoding": "identity";
+};
+/**
+ * refuseUnrequestedEncoding refuses a response carrying a content coding we did not ask for.
+ *
+ * Every leg negotiates identity, so a coding here is the peer answering that negotiation
+ * and then ignoring it. It is refused BEFORE the body is read, which is the only bound
+ * that holds at any chunk size — a decoder expands a whole raw read at once, so a running
+ * total over decoded chunks can be overshot by however much one chunk inflates to. The
+ * same check, for the same reason, is what bounds the Python client.
+ *
+ * `identity` itself is not a coding, and neither is an absent header.
+ */
+export declare function refuseUnrequestedEncoding(op: string, status: number, headers: Record<string, string | string[] | undefined>): void;
+/**
+ * decodeResponse turns one answer into a parsed message, or throws the typed failure.
+ *
+ * A non-2xx is the Connect error envelope: `{code, message, details}`. The typed reason
+ * rides in `details`, which errorDetailFrom reads — including the lowerCamelCase `debug`
+ * projection connect-go emits there and no server codec replaces.
+ */
+export declare function decodeResponse(op: string, response: UnaryResponse): unknown;
+/**
+ * NOT_CANONICAL_WIRE_NAMING is the reason a peer's answer is refused for spelling its
+ * field names the wrong way.
+ *
+ * It is the SDK's own verdict rather than a token the peer sent, which is the one place
+ * that happens: the peer's failure IS that it did not speak the contract, so there is no
+ * refusal of its own to carry. Go never produces it — it speaks binary proto, and
+ * protojson accepts both spellings on the way in — so this is a value only the JSON
+ * clients can observe, not a divergence in the shared failure taxonomy.
+ */
+export declare const NOT_CANONICAL_WIRE_NAMING = "not_canonical_wire_naming";
+/**
+ * Whether a request is checked against its generated schema before it is signed and sent.
+ * "strict" is the default; a caller that means to probe a server with a deliberately
+ * invalid message turns it off.
+ *
+ * DELIBERATELY STRICTER THAN GO, which defaults to ValidationOff. These two SDKs are the
+ * ones handed to external partners, so catching a missing recipient or idempotency key
+ * before anything is signed is worth more here than matching the oracle's default. It
+ * costs nothing in safety: the Exchange enforces the same rules whatever this says, and
+ * the answer coming back is validated either way.
+ *
+ * And it is a SMALLER check than the Go client's, not an equal one: the generated schema
+ * carries field-level rules, while the cross-field CEL rules stay server-authoritative.
+ * "Strict" does not mean the same thing in the two places.
+ */
+export type Validation = "strict" | "off";
+/**
+ * validateRequest refuses a request the protocol would reject anyway, before it costs a
+ * signature and a round trip.
+ *
+ * The check is FIELD-level, which is what the generated schema carries: the cross-field
+ * CEL rules stay server-authoritative, so this is a smaller check than the Go client's
+ * protovalidate interceptor, not an equal one. What it does catch is the common case — a
+ * required recipient or idempotency key left unset — where the server's only possible
+ * answer is a refusal.
+ *
+ * The validated value is DISCARDED and the caller's own object is what gets sent: a parse
+ * fills declared defaults, and sending those would put fields on the wire the caller never
+ * set.
+ */
+export declare function validateRequest(op: string, message: unknown, schema: {
+    safeParse: (v: unknown) => {
+        success: boolean;
+        data?: unknown;
+    };
+}, validation: Validation): void;
+/**
+ * parseMessage validates one answer against its generated schema, after refusing a
+ * non-canonical spelling. The schema owns the field names, the enum NAME strings and the
+ * proto3 omit-unpopulated shape; nothing about the message is decided here.
+ */
+export declare function parseMessage<T>(op: string, raw: unknown, schema: {
+    safeParse: (v: unknown) => {
+        success: boolean;
+        data?: unknown;
+    };
+}): T;