@fora-protocol/sdk 1.0.3

package/sdk/ts/resolvers/http.js

@@ -0,0 +1,274 @@
+// The one HTTP transport seam the fetching resolvers share. Transport-neutral
+// per the SDK dependency policy (the resolvers accept an injected fetch-compatible
+// callable) but the DEFAULT transport now runs on a maintained HTTP client
+// (undici) instead of a hand-rolled node:http request. undici owns the response
+// state machine — status, redirects, 1xx, decompression — so this module owns
+// only the SSRF guard (an injectable connection-level connector) and the
+// fail-closed status→body taxonomy. Integration tests / on-prem deployments that
+// must reach a private origin inject their own FetchLike (the escape hatch).
+import { lookup as dnsLookup } from "node:dns/promises";
+import { Agent, buildConnector, interceptors, request as undiciRequest, } from "undici";
+import { DirectoryUnavailable } from "./errors.js";
+import { allowedScheme, blockedAddress, MAX_REDIRECTS } from "./ssrf.js";
+/** Bounds the guarded default transport's GET so a slow origin cannot pin a
+ * Resolve call or the poller (Go: defaultWBAHTTPTimeout). */
+const DEFAULT_HTTP_TIMEOUT_MS = 10_000;
+/** Well-known documents are small; bound the body read (Go: maxDocBytes). */
+const MAX_DOC_BYTES = 1 << 20; // 1 MiB
+/** An SSRF error surfaced when the guarded transport refuses to dial a target.
+ * fetchStrict/fetchSoft see it as an ordinary transport failure (fail-closed
+ * DirectoryUnavailable / best-effort undefined), so the guard never resolves a
+ * blocked host as a valid — merely empty — directory. */
+export class SsrfBlockedError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "SsrfBlockedError";
+    }
+}
+/** The GENERIC dial-refusal the guard raises for EVERY refuse reason — an
+ * unresolvable host, an empty resolution, or a resolved-reserved address all yield
+ * the SAME message. It names only the caller-supplied host (already known to the
+ * caller), never the resolved IP, and does not distinguish an NXDOMAIN from a
+ * resolved-private answer, so it cannot serve as a pre-auth DNS oracle against
+ * internal networks. Identical wording across the three SDKs. */
+function ssrfRefusal(host) {
+    return new SsrfBlockedError(`SSRF guard: refusing to dial ${host}`);
+}
+/** An SSRF-guarded undici connector, injectable into any undici Dispatcher.
+ *
+ * DX: `new Agent({ connect: ssrfGuard() })`. The guard runs at the CONNECTION
+ * (dial) seam — the only place the DNS-REBINDING window is actually closed: it
+ * resolves the host, checks EVERY resolved address against blockedAddress, and
+ * pins the dial to a checked IP literal (undici does not re-resolve it), while
+ * the TLS `servername` keeps the original hostname so cert/SNI validation is
+ * unaffected. Because undici re-dials every followed redirect through the same
+ * connector, each redirect hop is re-vetted too (consistent with the Go and
+ * Python guards); a redirect into a non-http(s) scheme is a WHATWG-fetch network
+ * error, so the scheme allowlist is deny-by-default without a redirect handler. */
+export function ssrfGuard() {
+    const base = buildConnector({});
+    return (opts, cb) => {
+        const originalHostname = opts.hostname;
+        dnsLookup(originalHostname, { all: true })
+            .then((records) => {
+            // Fail closed on an empty resolution OR any reserved address in the set (the
+            // multi-address any-reserved rule: a MIXED public/reserved answer is refused
+            // outright, so a rebinding/round-robin trick cannot land a later connect on
+            // the reserved member). Every refuse path raises the SAME generic error.
+            if (records.length === 0 ||
+                records.some(({ address }) => blockedAddress(address))) {
+                cb(ssrfRefusal(originalHostname), null);
+                return;
+            }
+            // Every address passed; pin to the first (all public) checked IP literal
+            // — no re-resolution at connect — and keep servername = original host.
+            base({
+                ...opts,
+                hostname: records[0]?.address ?? originalHostname,
+                servername: opts.servername || originalHostname,
+            }, cb);
+        })
+            .catch(() => {
+            cb(ssrfRefusal(originalHostname), null);
+        });
+    };
+}
+/** The single guarded Dispatcher backing the default guarded transport. The SSRF
+ * connector vets + pins every dial (initial and each followed redirect hop); the
+ * composed redirect interceptor bounds the chain to the shared MAX_REDIRECTS cap so
+ * undici does not inherit its ~20-hop default. Beyond the cap the interceptor stops
+ * following and surfaces the 3xx as an ordinary non-2xx (fail-closed at fetchStrict). */
+const guardedAgent = new Agent({ connect: ssrfGuard() }).compose(interceptors.redirect({ maxRedirections: MAX_REDIRECTS }));
+/** Reads an undici response body as text, bounded to MAX_DOC_BYTES. Iterates the
+ * body stream (async-iterable in Node) so a hostile origin cannot force an
+ * unbounded read; breaking the loop cancels the stream once the cap is hit. */
+async function readBounded(body) {
+    if (body === null)
+        return "";
+    const chunks = [];
+    let total = 0;
+    for await (const chunk of body) {
+        chunks.push(chunk);
+        total += chunk.length;
+        if (total >= MAX_DOC_BYTES)
+            break;
+    }
+    const buf = Buffer.concat(chunks.map((c) => Buffer.from(c)));
+    return buf.subarray(0, MAX_DOC_BYTES).toString("utf8");
+}
+/** GET `url` through `dispatcher` (an undici Agent carrying the SSRF connector
+ * and the redirect-cap interceptor), gating the initial scheme with `allowScheme`
+ * and bounding the body to MAX_DOC_BYTES. undici owns status/redirect/1xx/decompress
+ * and the interceptor bounds the redirect chain, so this owns only the scheme gate
+ * and the body cap. A blocked target surfaces as the precise SsrfBlockedError (the
+ * connector rejects directly or via `err.cause`); non-guard errors propagate. The
+ * one request path both guarded faces share, so their wiring cannot drift. */
+async function requestBounded(url, dispatcher, allowScheme) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch (err) {
+        throw new SsrfBlockedError(`SSRF guard: unparseable url ${url}: ${String(err)}`);
+    }
+    // Gate the scheme BEFORE any dial. URL.protocol carries a trailing colon ("https:").
+    const scheme = parsed.protocol.replace(/:$/, "");
+    if (!allowScheme(scheme)) {
+        throw new SsrfBlockedError(`SSRF guard: refusing disallowed scheme ${parsed.protocol}`);
+    }
+    let resp;
+    try {
+        resp = await undiciRequest(url, {
+            dispatcher,
+            signal: AbortSignal.timeout(DEFAULT_HTTP_TIMEOUT_MS),
+        });
+    }
+    catch (err) {
+        if (err instanceof SsrfBlockedError)
+            throw err;
+        const cause = err.cause;
+        if (cause instanceof SsrfBlockedError)
+            throw cause;
+        throw err;
+    }
+    const body = await readBounded(resp.body);
+    return { status: resp.statusCode, text: () => Promise.resolve(body) };
+}
+/** The SSRF-guarded default transport. The directory host is derived from a
+ * caller-supplied Signature-Agent and the fetch runs BEFORE the ed25519 check,
+ * so an unguarded default would be a pre-auth SSRF lever. Runs on undici through
+ * the guarded connector (see ssrfGuard): the initial URL's scheme is vetted
+ * deny-by-default, every dial (initial + each redirect hop) is address-checked and
+ * pinned, the redirect chain is bounded to MAX_REDIRECTS, and undici owns
+ * status/redirect/1xx so a non-2xx is an ordinary response, never a crash. */
+export const guardedFetch = (url) => requestBounded(url, guardedAgent, allowedScheme);
+// ---------------------------------------------------------------------------
+// The ONE env-driven, best-effort guarded fetch factory.
+// ---------------------------------------------------------------------------
+/** Read a boolean env flag: true iff the value is "true" (any case) or "1". Every
+ * other value (including unset and "0") is false. */
+function envFlag(name) {
+    return ["true", "1"].includes((process.env[name] ?? "").toLowerCase());
+}
+/** Whether the dial-time address guard is disabled (SKIP_SSRF). Default: off.
+ *
+ * Exported because the client tier builds its own dispatchers and has to honour the same
+ * deployment flag this tier does — Go reads it in NewGuardedTransport and Python in
+ * guarded_client, so a TypeScript client that ignored it would be the one place the
+ * documented opt-out did nothing. */
+export function skipSSRF() {
+    return envFlag("SKIP_SSRF");
+}
+/** Whether plaintext http is permitted (ALLOW_INSECURE); else https-only. Default: off. */
+function allowInsecure() {
+    return envFlag("ALLOW_INSECURE");
+}
+/** The two-flag scheme decision: https always, http only under ALLOW_INSECURE,
+ * everything else denied (a scheme denylist is unwinnable — ftp, telnet, gopher,
+ * file, data, …). Case-insensitive. */
+export function schemeGuardAllows(scheme) {
+    const s = scheme.toLowerCase();
+    if (s === "https")
+        return true;
+    return s === "http" && allowInsecure();
+}
+/**
+ * requireScheme refuses a URL this SDK will not dial, BEFORE any dial happens.
+ *
+ * The connector returned by ssrfGuard is an ADDRESS pin — it decides what a hostname is
+ * allowed to resolve to, and it never sees the scheme, because by then the URL has already
+ * been reduced to a host and a port. So a dispatcher built from it alone will happily carry
+ * an RFC 9421 signature, or a proof of possession, over plaintext http. The scheme is a
+ * separate decision and needs a separate gate: Go states it in schemeGuardRoundTripper and
+ * Python in _SchemeGuardTransport, both wrapping the transport so it applies to whatever
+ * base a caller injected. This is the same gate for the callers that dial undici directly.
+ *
+ * Raising SsrfBlockedError rather than a typed client failure is deliberate: the client
+ * tier already classifies an unrecognised dial failure the way Go classifies this one,
+ * which reaches it through the RoundTripper for the same reason.
+ */
+export function requireScheme(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch (err) {
+        throw new SsrfBlockedError(`SSRF guard: unparseable url: ${String(err)}`);
+    }
+    // URL.protocol carries a trailing colon ("https:").
+    if (!schemeGuardAllows(parsed.protocol.replace(/:$/, ""))) {
+        throw new SsrfBlockedError(`SSRF guard: refusing disallowed scheme ${parsed.protocol}`);
+    }
+}
+/** The ONE public env-driven best-effort guarded fetch factory — every consumer's
+ * fetch for any third-party-influenceable request. Two orthogonal env flags drive
+ * it: SKIP_SSRF toggles the dial-time address guard (default: on), ALLOW_INSECURE
+ * toggles the scheme guard (default: https-only). There is no deployment-stack
+ * allow-list and no config error. Both paths use a per-factory undici Agent that
+ * ignores HTTP(S)_PROXY env, so a proxied CONNECT cannot tunnel a private target
+ * past the (guarded) dial guard, and both carry the same request timeout. Returns
+ * a FetchLike closing over one dispatcher. */
+export function guardedFetchFromEnv() {
+    // One dispatcher per factory: the SSRF connector (unless SKIP_SSRF) plus the
+    // redirect-cap interceptor, so a proxied CONNECT cannot tunnel past the (guarded)
+    // dial guard and the redirect chain is bounded to the shared MAX_REDIRECTS cap.
+    const base = skipSSRF() ? new Agent() : new Agent({ connect: ssrfGuard() });
+    const dispatcher = base.compose(interceptors.redirect({ maxRedirections: MAX_REDIRECTS }));
+    return (url) => requestBounded(url, dispatcher, schemeGuardAllows);
+}
+/** Default transport for a resolver whose URL is a FIXED, operator-chosen address
+ * (the well-known JWKS): a plain fetch, NOT SSRF-guarded. An on-prem JWKS may
+ * legitimately be private, and the operator rather than an attacker chose it.
+ *
+ * Which default a resolver takes follows its URL's PROVENANCE, and that is the
+ * whole rule — the Go oracle states it in the options struct these ports mirror.
+ * A fixed operator-chosen URL takes this transport. A REQUEST-DERIVED host — the
+ * WBA directory named by a Signature-Agent header, an Exchange domain read off an
+ * offer or a registration — takes `guardedFetchFromEnv`, because the party
+ * choosing the address is not the party running the process.
+ *
+ * The endpoint resolver in this package is request-derived and still defaults
+ * here, which is a known gap being closed separately; it is not the rule. Do not
+ * reach for this transport for a new resolver without first asking where its URL
+ * comes from. */
+export const defaultFetch = async (url) => {
+    const r = await fetch(url);
+    // Bound the body read even on the unguarded path: a misconfigured / hostile
+    // well-known origin cannot force an unbounded read into the JSON decoder. The
+    // WHATWG Response body is async-iterable in Node, so it reuses readBounded (the
+    // same 1 MiB cap as the guarded transport and the Go/Python well-known paths).
+    const body = await readBounded(r.body);
+    return { status: r.status, text: () => Promise.resolve(body) };
+};
+/** GET `url` and return the body text. A transport failure or a non-200 status
+ * throws DirectoryUnavailable (fail-closed halt) — the taxonomy a composite
+ * relies on to distinguish an outage from an unknown key. A blocked SSRF target
+ * is a transport failure and surfaces the same way (never a valid empty doc). */
+export async function fetchStrict(fetchFn, url) {
+    let resp;
+    try {
+        resp = await fetchFn(url);
+    }
+    catch (err) {
+        throw new DirectoryUnavailable(`fetch ${url}`, { cause: err });
+    }
+    if (resp.status !== 200) {
+        throw new DirectoryUnavailable(`status ${resp.status} for ${url}`);
+    }
+    return resp.text();
+}
+/** Best-effort GET: returns the body text on 200, or `undefined` on any
+ * transport/status failure. The revocation refresh uses this so a fetch blip
+ * leaves the prior snapshot in place (Go: best-effort refresh) rather than
+ * propagating — a stale-but-present snapshot is safer than dropping revocations. */
+export async function fetchSoft(fetchFn, url) {
+    try {
+        const resp = await fetchFn(url);
+        if (resp.status !== 200)
+            return undefined;
+        return await resp.text();
+    }
+    catch {
+        return undefined;
+    }
+}

package/sdk/ts/resolvers/index.d.ts

@@ -0,0 +1,9 @@
+export { DirectoryUnavailable, EndpointRefused, ExchangeNotPermitted, KeyExpired, KeyRevoked, ManifestNotExchange, ManifestUnusable, ManifestVersionRefused, NoEndpoint, ResolverError, RevocationUnevaluated, UnknownKey, } from "./errors.ts";
+export type { FetchLike, FetchResponse } from "./http.ts";
+export { guardedFetchFromEnv, SsrfBlockedError, ssrfGuard } from "./http.ts";
+export { type CachedOfferKeyResolver, type CachedOfferKeyResolverOptions, clampOfferKeyExpiry, createCachedOfferKeyResolver, createWBAOfferDirectoryFetch, type OfferDirectoryFetch, } from "./offer-key-cache.ts";
+export { createWellKnownRequirementsReader, type RegistrationRequirements, type WellKnownRequirementsOptions, type WellKnownRequirementsReader, } from "./registration-requirements.ts";
+export { allowedScheme, blockedAddress } from "./ssrf.ts";
+export { createStaticKeyResolver, type StaticKeyResolver } from "./static.ts";
+export { activeEd25519Key, activeEd25519KeyScreened, activeEd25519KeyWithExpiry, activeEd25519KeyWithExpiryScreened, createWBAKeyResolver, WBA_DIRECTORY_PATH, type WBAKeyResolver, type WBAKeyResolverOptions, wbaDirectoryURL, } from "./wba.ts";
+export { type EndpointOptions, createWellKnownEndpointResolver, createWellKnownKeyResolver, type WellKnownEndpointResolver, type WellKnownKeyResolver, type WellKnownOptions, } from "./wellknown.ts";

package/sdk/ts/resolvers/index.js

@@ -0,0 +1,15 @@
+// Public surface of the FORA SDK resolver faces (ADR-020 §4). These are the FIRST
+// IO in the TS SDK, so they live OUTSIDE the IO-free core/src tree (exported via
+// package.json `exports`) to keep the transport-neutrality invariant on core
+// green. Four faces port the Go oracle: a static named map, a well-known JWKS
+// key resolver, a host-keyed well-known endpoint resolver, and the WBA
+// identity-directory resolver + revocation poller. The typed error classes
+// preserve the oracle's errors.Is-DISTINCT fail-closed taxonomy.
+export { DirectoryUnavailable, EndpointRefused, ExchangeNotPermitted, KeyExpired, KeyRevoked, ManifestNotExchange, ManifestUnusable, ManifestVersionRefused, NoEndpoint, ResolverError, RevocationUnevaluated, UnknownKey, } from "./errors.js";
+export { guardedFetchFromEnv, SsrfBlockedError, ssrfGuard } from "./http.js";
+export { clampOfferKeyExpiry, createCachedOfferKeyResolver, createWBAOfferDirectoryFetch, } from "./offer-key-cache.js";
+export { createWellKnownRequirementsReader, } from "./registration-requirements.js";
+export { allowedScheme, blockedAddress } from "./ssrf.js";
+export { createStaticKeyResolver } from "./static.js";
+export { activeEd25519Key, activeEd25519KeyScreened, activeEd25519KeyWithExpiry, activeEd25519KeyWithExpiryScreened, createWBAKeyResolver, WBA_DIRECTORY_PATH, wbaDirectoryURL, } from "./wba.js";
+export { createWellKnownEndpointResolver, createWellKnownKeyResolver, } from "./wellknown.js";

package/sdk/ts/resolvers/jwks.d.ts

@@ -0,0 +1,2 @@
+/** Extract the Ed25519 public keys (keyed by kid) from a parsed JWKS doc. */
+export declare function ed25519KeysFromJwks(doc: unknown): Map<string, Uint8Array>;

package/sdk/ts/resolvers/jwks.js

@@ -0,0 +1,43 @@
+// Ad-hoc JWKS decode for the well-known KEY document. The publisher's
+// fora.json key set is the kid-carrying RFC 7517 subset
+// `{"keys":[{"kid","kty":"OKP","crv":"Ed25519","x":"<base64url>"}]}` — NOT the
+// gen JsonWebKey/WellKnownManifest schemas, which carry no `kid` and no JWK-set
+// (decoding through them would resolve ZERO keys). The gen schemas are reserved
+// for the WBA path (thumbprint-keyed, needs no kid). base64url `x` decode reuses
+// the byte-parity-pinned primitive.
+//
+// Extraction is SKIP-NOT-FAIL (mirroring go-jose ed25519KeysFromJWKS): a key
+// with an empty/missing kid, a non-OKP/Ed25519 type, or a wrong-length `x` is
+// skipped, survivors are keyed by kid, and one bad key never fails the whole set.
+import { decodeBase64UrlStrict } from "../src/base64url.js";
+const ED25519_PUBLIC_KEY_BYTES = 32;
+/** Extract the Ed25519 public keys (keyed by kid) from a parsed JWKS doc. */
+export function ed25519KeysFromJwks(doc) {
+    const out = new Map();
+    const keys = doc.keys;
+    if (!Array.isArray(keys))
+        return out;
+    for (const entry of keys) {
+        const extracted = extractEd25519(entry);
+        if (extracted)
+            out.set(extracted.kid, extracted.pub);
+    }
+    return out;
+}
+function extractEd25519(entry) {
+    if (typeof entry !== "object" || entry === null)
+        return undefined;
+    const e = entry;
+    if (typeof e.kid !== "string" || e.kid === "")
+        return undefined;
+    if (e.kty !== "OKP" || e.crv !== "Ed25519")
+        return undefined;
+    if (typeof e.x !== "string")
+        return undefined;
+    // JWK OKP `x` is UNPADDED base64url (RFC 8037); reject padding / the standard
+    // alphabet to match Go's go-jose JWKS parse (RawURLEncoding).
+    const raw = decodeBase64UrlStrict(e.x);
+    if (!raw || raw.length !== ED25519_PUBLIC_KEY_BYTES)
+        return undefined;
+    return { kid: e.kid, pub: raw };
+}

package/sdk/ts/resolvers/offer-key-cache.d.ts

@@ -0,0 +1,68 @@
+import { WBAFileSchema } from "../../../gen/ts/wire/schemas.ts";
+import type { OfferKeyResolver } from "../core/verifier.ts";
+import { type FetchLike } from "./http.ts";
+/** A parsed WBA identity directory — the shape the injected fetch seam returns. */
+type WBAFile = ReturnType<typeof WBAFileSchema.parse>;
+/**
+ * OfferDirectoryFetch resolves one exchange domain to its WBA directory, or
+ * `undefined` when the directory is unresolvable (unreachable, malformed, blocked).
+ * The injected IO seam of the cache: a test injects a directory table with no
+ * network, an app wraps its shared well-known fetch. The seam SHOULD contain its
+ * own failures as `undefined` rather than throw — but resolve() defends against a
+ * throwing seam anyway (Core Invariant), so a hand-rolled fetcher that raises still
+ * fails closed. Mirrors Python's `DirectoryFetch` None-absence contract.
+ */
+export type OfferDirectoryFetch = (domain: string) => Promise<WBAFile | undefined>;
+/** Wires a {@link createCachedOfferKeyResolver}. `fetch` is REQUIRED. */
+export interface CachedOfferKeyResolverOptions {
+    /** Resolves a domain to its WBA directory. REQUIRED — the factory throws a
+     * TypeError at construction when it is missing (a resolver with no directory
+     * source can never resolve anything). */
+    fetch: OfferDirectoryFetch;
+    /** Per-domain cache TTL in ms; ≤0/undefined → {@link DEFAULT_TTL_MS}. The stored
+     * entry's expiry is clamped to min(now+ttlMs, not_after). */
+    ttlMs?: number;
+    /** The cache-freshness + selection clock; undefined → Date.now. Tests inject. */
+    now?: () => number;
+    /** Screens a candidate key by its RFC 7638 thumbprint — a revoked key is skipped
+     * during selection so a window-active-but-revoked key is never served. undefined
+     * screens nothing; inject a revoked-set predicate on any verification path. A
+     * throwing predicate fails closed (resolve → undefined), never propagates. */
+    revoked?: (thumbprint: string) => boolean;
+}
+/** The public face: the OfferKeyResolver core.Verifier resolves offer keys through. */
+export type CachedOfferKeyResolver = OfferKeyResolver;
+/**
+ * clampOfferKeyExpiry bounds a cache entry's expiry to the key's validity window:
+ * the entry expires at min(nowMs+ttlMs, notAfterMs), so a key is never served past
+ * its not_after even within the TTL. A pure helper (all epoch-ms) so the
+ * tri-language clamp corpus replays the SAME arithmetic the resolver runs, not a
+ * re-inlined copy that could silently drift.
+ */
+export declare function clampOfferKeyExpiry(nowMs: number, ttlMs: number, notAfterMs: number): number;
+/**
+ * createCachedOfferKeyResolver builds a domain-keyed offer-key cache implementing
+ * OfferKeyResolver. `newX` for family consistency with the sibling resolver
+ * factories (createWBAKeyResolver, createWellKnownKeyResolver, …). Throws TypeError when
+ * opts.fetch is missing; every other failure fails closed at resolve() time.
+ */
+export declare function createCachedOfferKeyResolver(opts: CachedOfferKeyResolverOptions): CachedOfferKeyResolver;
+/**
+ * createWBAOfferDirectoryFetch returns the default {@link OfferDirectoryFetch}: it
+ * GETs {scheme}://{domain}[:{port}]{WBA_DIRECTORY_PATH} (built by the shared
+ * wbaDirectoryURL) and parses the body as a WBAFile, returning `undefined` on ANY
+ * transport/status/decode failure so
+ * the default fetcher itself upholds the undefined-not-throw seam contract.
+ *
+ * The default transport is SSRF-guarded (guardedFetchFromEnv): the exchange domain
+ * is signature-covered but attacker-influenceable and the fetch runs before the
+ * offer signature is checked, so an unguarded default would be a pre-auth SSRF
+ * lever (mirrors Go NewWBADirectoryFetcher). Tests inject a loopback fetch; apps
+ * may inject a fetch wrapping their shared well-known client.
+ */
+export declare function createWBAOfferDirectoryFetch(opts?: {
+    fetch?: FetchLike;
+    scheme?: string;
+    port?: string;
+}): OfferDirectoryFetch;
+export {};

package/sdk/ts/resolvers/offer-key-cache.js

@@ -0,0 +1,152 @@
+// CachedOfferKeyResolver — the domain-keyed offer-signing-key cache that
+// consolidates the Broker's offerkeys.Resolver and the MCP shim's
+// ExchangeOfferKeyCache into the SDK. It resolves an exchange DOMAIN
+// (Offer.exchange) to that exchange's active Ed25519 offer-signing key, caching
+// per domain with a TTL whose expiry is CLAMPED to the key's not_after, folding
+// revocation screening into selection, and coalescing concurrent resolves for a
+// domain into a single directory fetch. It IMPLEMENTS core/verifier.ts
+// OfferKeyResolver (resolve(exchange) → Promise<key | undefined>), so
+// createVerifier({ resolve }) injects it directly.
+//
+// It ASSEMBLES existing SDK primitives rather than reinventing them:
+//   - activeEd25519KeyWithExpiryScreened (wba.ts) — the revocation-aware
+//     document-order active-key selector with the not_after to clamp against.
+//   - the host-keyed TTL-cache + per-host single-flight shape mirrored from
+//     EndpointResolverImpl (wellknown.ts).
+//   - the SSRF-guarded fetch seam (http.ts) for the default directory fetcher.
+//
+// CORE INVARIANT (fail-closed): core.Verifier awaits resolve() with NO try/catch
+// (verifier.ts check()), so a throw would fail-CRASH the whole verification batch
+// instead of fail-closed-REJECTING the one offer. resolve() therefore NEVER
+// throws: every fallible step — the injected fetch, the async selector (its
+// thumbprint screening), and the caller-supplied revoked() callback — is wrapped
+// so any throw or absence becomes `undefined`. Only a successful selection caches
+// and returns a key. TS is fail-closed by ABSENCE (undefined), matching Python's
+// absence-from-map — NOT Go's error return. The one exception is a MISSING fetch
+// seam, which is a programmer error surfaced at CONSTRUCTION (TypeError), never a
+// per-resolve absence — mirroring Go's PanicsWithoutFetch.
+import { WBAFileSchema } from "../../../gen/ts/wire/schemas.js";
+import { fetchStrict, guardedFetchFromEnv } from "./http.js";
+import { activeEd25519KeyWithExpiryScreened, wbaDirectoryURL } from "./wba.js";
+/** Default per-domain cache TTL (5 min), matching the Go/Python resolver. */
+const DEFAULT_TTL_MS = 300_000;
+/**
+ * clampOfferKeyExpiry bounds a cache entry's expiry to the key's validity window:
+ * the entry expires at min(nowMs+ttlMs, notAfterMs), so a key is never served past
+ * its not_after even within the TTL. A pure helper (all epoch-ms) so the
+ * tri-language clamp corpus replays the SAME arithmetic the resolver runs, not a
+ * re-inlined copy that could silently drift.
+ */
+export function clampOfferKeyExpiry(nowMs, ttlMs, notAfterMs) {
+    return Math.min(nowMs + ttlMs, notAfterMs);
+}
+class CachedOfferKeyResolverImpl {
+    fetchFn;
+    ttlMs;
+    now;
+    revoked;
+    cache = new Map();
+    flight = new Map();
+    constructor(opts) {
+        // A missing fetch seam is a programmer error, surfaced at CONSTRUCTION — never
+        // a per-resolve fail-closed absence (mirrors Go PanicsWithoutFetch).
+        if (typeof opts.fetch !== "function") {
+            throw new TypeError("CachedOfferKeyResolver requires a fetch directory seam");
+        }
+        this.fetchFn = opts.fetch;
+        this.ttlMs = opts.ttlMs && opts.ttlMs > 0 ? opts.ttlMs : DEFAULT_TTL_MS;
+        this.now = opts.now ?? Date.now;
+        this.revoked = opts.revoked ?? (() => false);
+    }
+    async resolve(exchange) {
+        const hit = this.cached(exchange);
+        if (hit !== undefined)
+            return hit;
+        let flight = this.flight.get(exchange);
+        if (!flight) {
+            flight = this.fetchAndSelect(exchange);
+            this.flight.set(exchange, flight);
+        }
+        try {
+            // fetchAndSelect is total (all failures → undefined), so awaiting the flight
+            // cannot throw — resolve() upholds the never-throw Core Invariant.
+            return await flight;
+        }
+        finally {
+            this.flight.delete(exchange);
+        }
+    }
+    cached(exchange) {
+        const entry = this.cache.get(exchange);
+        // Miss at or past the (clamped) expiry — hit strictly before it, so a key whose
+        // clamped entry expires exactly at not_after is refetched at not_after (and then
+        // fails closed, since it is no longer window-active). Matches the Go read check.
+        if (!entry || this.now() >= entry.exp)
+            return undefined;
+        return entry.key;
+    }
+    async fetchAndSelect(exchange) {
+        try {
+            const hit = this.cached(exchange);
+            if (hit !== undefined)
+                return hit; // filled while we queued behind the flight
+            const dir = await this.fetchFn(exchange);
+            if (dir === undefined)
+                return undefined; // unresolvable directory → fail closed
+            const nowMs = this.now();
+            const selected = await activeEd25519KeyWithExpiryScreened(dir, nowMs, this.revoked);
+            if (selected === null)
+                return undefined; // no active, non-revoked key
+            // The decoded key bytes are ArrayBuffer-backed at runtime; the selector widens
+            // them to ArrayBufferLike, so pin the generic (base64url.ts convention) to
+            // satisfy OfferKeyResolver's Uint8Array<ArrayBuffer> contract under tsc --strict.
+            const key = selected.key;
+            const exp = clampOfferKeyExpiry(nowMs, this.ttlMs, selected.notAfter);
+            this.cache.set(exchange, { key, exp });
+            return key;
+        }
+        catch {
+            // Core Invariant: ANY throw (fetch seam, async thumbprint screening, or the
+            // caller-supplied revoked() callback) fails closed to undefined — never
+            // propagates, since core.Verifier awaits resolve() with no try/catch.
+            return undefined;
+        }
+    }
+}
+/**
+ * createCachedOfferKeyResolver builds a domain-keyed offer-key cache implementing
+ * OfferKeyResolver. `newX` for family consistency with the sibling resolver
+ * factories (createWBAKeyResolver, createWellKnownKeyResolver, …). Throws TypeError when
+ * opts.fetch is missing; every other failure fails closed at resolve() time.
+ */
+export function createCachedOfferKeyResolver(opts) {
+    return new CachedOfferKeyResolverImpl(opts);
+}
+/**
+ * createWBAOfferDirectoryFetch returns the default {@link OfferDirectoryFetch}: it
+ * GETs {scheme}://{domain}[:{port}]{WBA_DIRECTORY_PATH} (built by the shared
+ * wbaDirectoryURL) and parses the body as a WBAFile, returning `undefined` on ANY
+ * transport/status/decode failure so
+ * the default fetcher itself upholds the undefined-not-throw seam contract.
+ *
+ * The default transport is SSRF-guarded (guardedFetchFromEnv): the exchange domain
+ * is signature-covered but attacker-influenceable and the fetch runs before the
+ * offer signature is checked, so an unguarded default would be a pre-auth SSRF
+ * lever (mirrors Go NewWBADirectoryFetcher). Tests inject a loopback fetch; apps
+ * may inject a fetch wrapping their shared well-known client.
+ */
+export function createWBAOfferDirectoryFetch(opts = {}) {
+    const fetchFn = opts.fetch ?? guardedFetchFromEnv();
+    const scheme = opts.scheme && opts.scheme !== "" ? opts.scheme : "https";
+    const port = opts.port ?? "";
+    return async (domain) => {
+        try {
+            const host = port !== "" ? `${domain}:${port}` : domain;
+            const body = await fetchStrict(fetchFn, wbaDirectoryURL(scheme, host));
+            return WBAFileSchema.parse(JSON.parse(body));
+        }
+        catch {
+            return undefined;
+        }
+    };
+}

package/sdk/ts/resolvers/registration-requirements.d.ts

@@ -0,0 +1,47 @@
+import { type RegistrationSchema, type SchemaVerdict } from "../src/regschema.ts";
+import { type FetchLike } from "./http.ts";
+/** What one Exchange asks of a registration. Both members are optional in the
+ * contract, and their absence is a normal answer rather than a failure. */
+export interface RegistrationRequirements {
+    /** The manifest's `terms_digest`, `undefined` when the Exchange publishes none.
+     * Copy it onto `RegisterRequest.terms_digest` unchanged: the request signature
+     * covers the echo, and that echo is the durable record of which terms revision
+     * the operator accepted. */
+    termsDigest: string | undefined;
+    /** Validates `registration_data` before anything is signed. `null` in TWO cases
+     * — the Exchange publishes none, and it publishes one this SDK refuses — and
+     * `verdict` is what tells them apart. Both are deliberately the same VALUE,
+     * because the contract requires a client that cannot check locally to send
+     * anyway: a local check that cannot run must not become a local veto. */
+    schema: RegistrationSchema | null;
+    /** The SDK's answer for the published schema. `not_published` is the ordinary
+     * absent case; `accepted` means `schema` is usable; anything else names why a
+     * published schema was refused, which is worth logging and is never worth
+     * refusing the registration over. */
+    verdict: SchemaVerdict;
+}
+/** The well-known registration-requirements face, named for the concrete reader
+ * the oracle exposes (`resolvers.WellKnownRequirementsReader`). */
+export interface WellKnownRequirementsReader {
+    resolveRegistrationRequirements(exchange: string): Promise<RegistrationRequirements>;
+}
+/** Options for the reader. `ttlMs` and `now` are deliberately absent: it caches
+ * nothing, so it has no freshness to compute. */
+export interface WellKnownRequirementsOptions {
+    /** The transport. Omitted, it is the SSRF-GUARDED one: the domain is
+     * caller-named — an agent registers at whichever Exchange it means to transact
+     * with, and that domain routinely arrives at runtime rather than from
+     * configuration — so this is request-derived provenance, which takes the guarded
+     * default. A deployment that must reach a private or loopback Exchange injects
+     * its own transport here, or opts out through the SKIP_SSRF / ALLOW_INSECURE
+     * environment flags. */
+    fetch?: FetchLike;
+    /** Trust allowlist consulted BEFORE the fetch. A domain it rejects never
+     * reaches the network. */
+    allow?: (domain: string) => boolean;
+    /** The URL scheme used to build `{scheme}://{domain}/.well-known/fora.json`
+     * (tests inject "http"). */
+    scheme?: string;
+}
+/** Read registration requirements from an Exchange's own well-known manifest. */
+export declare function createWellKnownRequirementsReader(opts?: WellKnownRequirementsOptions): WellKnownRequirementsReader;