@fora-protocol/sdk 1.0.3

package/sdk/ts/core/wire-canon.js

@@ -0,0 +1,174 @@
+// sdk/ts/core — the wire→canonical offer inversion (the from-wire canonicalizer).
+// Companion to the Verifier's canonicalOfferPayload: that face clears the two
+// signature fields and JCS-es an ALREADY-canonical offer; THIS face reconstructs
+// the canonical form from the FORA Connect WIRE offer (proto3-JSON with
+// EmitUnpopulated — zero-valued scalars, empty repeateds, null messages, and
+// *_UNSPECIFIED enums all present). Every TS client verifying a wire offer must
+// invert the wire emission BEFORE canonicalOfferPayload, never call it on raw wire.
+//
+// Mirror of sdk/python fora_sdk.wire_canon.from_wire_offer. Its presence rules are
+// SCHEMA-AWARE, driven by the generated gen/ts OfferSchema exactly as the Python
+// side reads them from the gen/python model field defaults:
+//
+//   .optional()  → proto3 presence-tracked → a set-but-zero scalar is KEPT
+//                  (an optional string deliberately "" survives, e.g. pricing.unit).
+//   .default("")/.default(0)/bare-required → non-optional → the zero value is DROPPED.
+//   z.object     → message: recurse (a set-but-empty {} stays, a null message drops).
+//   z.array      → repeated: drop when empty, else canonicalize each element.
+//   z.record     → map/Struct: keep VERBATIM (keys are data, never pruned or cased),
+//                  drop only when empty.
+//   *_UNSPECIFIED enum values are zero values and drop.
+//
+// Byte-parity with the Go oracle is pinned by tests/wire-canonical.parity.test.ts
+// over the shared sdk/go/helpers/testdata/wire-canonical-vectors.json corpus.
+//
+// FAIL-CLOSED: a wire field newer than the pinned OfferSchema is kept verbatim, so a
+// signature covering bytes this pin cannot reconstruct verifies FALSE (rejected),
+// never silently accepted.
+import { OfferSchema } from "../../../gen/ts/wire/schemas.js";
+// Sentinel: this field is omitted entirely by the canonical marshal.
+const OMIT = Symbol("fora.core.wire-canon.omit");
+const CAMEL_BOUNDARY = /([a-z0-9])([A-Z])/g;
+const UNSPECIFIED_ENUM = /^[A-Z][A-Z0-9_]*_UNSPECIFIED$/;
+// Wrapper node types that decorate a field without changing its wire identity.
+const WRAPPERS = new Set(["ZodOptional", "ZodDefault", "ZodNullable", "ZodBranded", "ZodEffects", "ZodPipe"]);
+function zdef(schema) {
+    return schema._def;
+}
+// kindOf reads the node kind in Zod 3 spelling for both majors: Zod 4's "optional"
+// becomes "ZodOptional", so one vocabulary drives the walk. A node with neither
+// spelling is a Zod this module does not read; it throws rather than returning a
+// kind nothing matches, which would silently drop presence-tracked zero values
+// from the canonical form and fail signature verification without a cause.
+export function kindOf(schema) {
+    const d = zdef(schema);
+    if (d.typeName !== undefined)
+        return d.typeName;
+    if (typeof d.type !== "string") {
+        throw new Error("fora/core: zod node has neither typeName (Zod 3) nor a string type (Zod 4)");
+    }
+    return `Zod${d.type.charAt(0).toUpperCase()}${d.type.slice(1)}`;
+}
+// innerOf peels one wrapper: ZodOptional/ZodDefault/ZodNullable expose `innerType`,
+// Zod 3 ZodArray/ZodBranded expose `type`, Zod 3 ZodEffects exposes `schema`, Zod 4
+// arrays expose `element` and Zod 4 pipes `in` — mutually exclusive.
+function innerOf(schema) {
+    const d = zdef(schema);
+    const inner = d.innerType ?? d.schema ?? d.element ?? d.in ?? (typeof d.type === "object" ? d.type : undefined);
+    if (inner === undefined)
+        throw new Error("fora/core: zod wrapper has no inner type");
+    return inner;
+}
+function shapeOf(schema) {
+    return schema.shape;
+}
+// coreType strips presence/decoration wrappers to the underlying kind (ZodObject,
+// ZodArray, ZodRecord, or a scalar). It STOPS at ZodArray so a repeated field is
+// still detectable as repeated (the element is unwrapped separately).
+function coreType(schema) {
+    let s = schema;
+    while (WRAPPERS.has(kindOf(s)))
+        s = innerOf(s);
+    return s;
+}
+// isPresenceTracked mirrors Python's `field.default is None`: a `.optional()` field
+// is proto3 presence-tracked (keep its zero value); `.default(...)` or a bare
+// required field is non-optional (drop its zero value).
+function isPresenceTracked(schema) {
+    const t = kindOf(schema);
+    if (t === "ZodOptional")
+        return true;
+    if (t === "ZodDefault")
+        return false;
+    if (t === "ZodNullable" || t === "ZodBranded" || t === "ZodEffects" || t === "ZodPipe") {
+        return isPresenceTracked(innerOf(schema));
+    }
+    return false;
+}
+function isPlainObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+// snake inverts protojson's lowerCamel json_name back to the proto name. It is
+// idempotent on already-snake keys (the shared corpus is snake_case wire).
+function snake(key) {
+    return key.replace(CAMEL_BOUNDARY, "$1_$2").toLowerCase();
+}
+function canonScalar(value, presence) {
+    if (presence)
+        return value; // set (on the wire) → part of the signed bytes
+    const zeroish = value === "" || value === false || (typeof value === "number" && value === 0);
+    if (zeroish)
+        return OMIT;
+    if (typeof value === "string" && UNSPECIFIED_ENUM.test(value))
+        return OMIT;
+    return value;
+}
+function canonField(field, value) {
+    if (value === null)
+        return OMIT; // unset message/Struct (EmitUnpopulated renders null)
+    const core = coreType(field);
+    const kind = kindOf(core);
+    if (Array.isArray(value)) {
+        const elem = kind === "ZodArray" ? coreType(innerOf(core)) : undefined;
+        const elemIsMessage = elem !== undefined && kindOf(elem) === "ZodObject";
+        const items = value.map((v) => elemIsMessage && elem !== undefined && isPlainObject(v) ? canonMessage(elem, v) : v);
+        return items.length > 0 ? items : OMIT; // canonical omits empty repeated
+    }
+    if (isPlainObject(value)) {
+        if (kind === "ZodObject")
+            return canonMessage(core, value); // set-but-empty {} stays
+        if (kind === "ZodRecord")
+            return Object.keys(value).length > 0 ? value : OMIT; // map keys verbatim
+        return value;
+    }
+    return canonScalar(value, isPresenceTracked(field));
+}
+// keep writes a member the canonical form must carry, including one whose name is an
+// inherited property of every object. A plain assignment to "__proto__" replaces the
+// object's prototype and creates no member; defineProperty creates the member, which is
+// what JSON.stringify — and therefore JCS, and therefore the signature — reads.
+function keep(out, name, value) {
+    Object.defineProperty(out, name, {
+        value,
+        enumerable: true,
+        writable: true,
+        configurable: true,
+    });
+}
+function canonMessage(objectSchema, wire) {
+    const shape = shapeOf(objectSchema);
+    const out = {};
+    for (const [key, value] of Object.entries(wire)) {
+        const name = snake(key);
+        // hasOwn on the READ, and defineProperty on the WRITE. Both are the same key: a
+        // wire name like "__proto__" or "constructor" resolves to an inherited member of
+        // Object.prototype, so a truthiness test hands the walk an object with no _def,
+        // and a plain assignment invokes the prototype SETTER instead of creating a
+        // member. An offer comes from a peer, so the key is attacker-chosen, and the
+        // second half was the dangerous one: the member vanished from the canonical form
+        // while the object silently inherited whatever the attacker put there. The signed
+        // bytes were unaffected, so an offer carrying an appended __proto__ still VERIFIED
+        // — the one member name that could be added to a signed offer for free — and the
+        // caller then read attacker-chosen values off a VerifiedOffer.
+        const field = Object.hasOwn(shape, name) ? shape[name] : undefined;
+        if (field === undefined) {
+            // Newer-than-pin field: keep it so verification fails CLOSED (the signature
+            // covered bytes this pin cannot reconstruct).
+            keep(out, name, value);
+            continue;
+        }
+        const canon = canonField(field, value);
+        if (canon !== OMIT)
+            keep(out, name, canon);
+    }
+    return out;
+}
+/**
+ * fromWireOffer reconstructs the canonical (signed) offer object from the WIRE
+ * offer object, mirroring sdk/python from_wire_offer. Feed its result to
+ * canonicalOfferPayload (or RFC 8785 JCS directly) to reproduce the exact bytes the
+ * offer signature covers.
+ */
+export function fromWireOffer(offerWire) {
+    return canonMessage(OfferSchema, offerWire);
+}

package/sdk/ts/hono/middleware.d.ts

@@ -0,0 +1,38 @@
+import type { Ed25519Verify } from "../core/verifier.ts";
+/**
+ * A minimal structural view of the Hono context the middleware touches: the raw
+ * inbound Fetch Request and a Response slot the binding sets on deny. Declared
+ * structurally (not imported from Hono) so the core-adjacent binding stays free of
+ * a hard Hono runtime import while remaining drop-in for a real Hono `Context`.
+ */
+export interface ForaVerifyContext {
+    req: {
+        raw: Request;
+    };
+    res: Response | undefined;
+}
+export type ForaVerifyNext = () => Promise<void> | void;
+/** Options for the server-verify binding. The clock + verify primitive are
+ * injected exactly as the core Verifier's are; the binding owns no state. The
+ * GET-PoP path is self-verifying via the presented key, so no key resolver is
+ * accepted — a resolver here would be dead weight the middleware never reads. */
+export interface ForaVerifyOptions {
+    now?: () => number;
+    verifyEd25519?: Ed25519Verify;
+}
+/**
+ * foraVerify builds the opt-in Hono server-verify middleware. On an inbound
+ * request it verifies the RFC 9421 GET PoP through the L1 verifyAgentBinding; on
+ * success it calls next() (the guarded handler runs); on failure it sets a 403 deny
+ * response and does NOT call next() (fail-closed).
+ *
+ * SCOPE LIMIT — presenter self-consistency only: the binding derives agentId
+ * from the PRESENTED key (thumbprint), so the 3-way check collapses to "the
+ * presenter signed with the key it presented". It does NOT anchor a URL-bound
+ * agent_id. A consumer enforcing URL-bound delivery (e.g. an edge serving
+ * signed URLs whose agent_id query param binds the fetcher) MUST call the L1
+ * verifyAgentBinding directly with the URL's agent_id as the anchor — building
+ * URL-bound verification on this middleware would silently accept any
+ * self-consistent presenter.
+ */
+export declare function foraVerify(opts: ForaVerifyOptions): (ctx: ForaVerifyContext, next: ForaVerifyNext) => Promise<void>;

package/sdk/ts/hono/middleware.js

@@ -0,0 +1,64 @@
+// sdk/ts/hono — the OPT-IN server/verify binding over sdk/ts/core, the natural
+// adapter for Edge (src/edge/src/app.ts, a SERVER/VERIFIER). It is a thin Hono
+// middleware that verifies an inbound RFC 9421 GET proof-of-possession at the HTTP
+// seam (where the exact request exists) via the L1 verifyAgentBinding, and
+// fail-closes: an unsigned/forged request never reaches the guarded handler and
+// the binding sets a 403 deny response.
+//
+// This binding depends one-directionally on core + L1; core NEVER imports Hono.
+// Hono is a PEER dependency of this binding, not of the core. The middleware is
+// framework-shaped (a (ctx, next) pair) but does not import Hono's runtime — it
+// operates over the standard Fetch Request the Hono context exposes as ctx.req.raw
+// and the standard Response it assigns to ctx.res, so it is testable without a
+// running Hono app and stays byte-neutral to the web standard.
+import { decodeBase64Url } from "../src/base64url.js";
+import { AGENT_KEY_HEADER, verifyAgentBinding } from "../src/pop.js";
+import { thumbprint } from "../src/thumbprint.js";
+const ED25519_PUBLIC_KEY_BYTES = 32;
+/**
+ * foraVerify builds the opt-in Hono server-verify middleware. On an inbound
+ * request it verifies the RFC 9421 GET PoP through the L1 verifyAgentBinding; on
+ * success it calls next() (the guarded handler runs); on failure it sets a 403 deny
+ * response and does NOT call next() (fail-closed).
+ *
+ * SCOPE LIMIT — presenter self-consistency only: the binding derives agentId
+ * from the PRESENTED key (thumbprint), so the 3-way check collapses to "the
+ * presenter signed with the key it presented". It does NOT anchor a URL-bound
+ * agent_id. A consumer enforcing URL-bound delivery (e.g. an edge serving
+ * signed URLs whose agent_id query param binds the fetcher) MUST call the L1
+ * verifyAgentBinding directly with the URL's agent_id as the anchor — building
+ * URL-bound verification on this middleware would silently accept any
+ * self-consistent presenter.
+ */
+export function foraVerify(opts) {
+    return async (ctx, next) => {
+        const req = ctx.req.raw;
+        // The presented key is the PoP authority; its thumbprint is the identity the
+        // 3-way check anchors on (keyid == thumbprint(presented) == agent_id). Derive
+        // agent_id from the presented key so a request that omits the URL param still
+        // verifies self-consistently.
+        const presentedRaw = req.headers.get(AGENT_KEY_HEADER);
+        const presented = presentedRaw ? decodeBase64Url(presentedRaw) : undefined;
+        if (!presented || presented.length !== ED25519_PUBLIC_KEY_BYTES) {
+            ctx.res = deny();
+            return;
+        }
+        const agentId = await thumbprint(presented);
+        const result = await verifyAgentBinding({
+            url: req.url,
+            method: req.method,
+            headers: req.headers,
+            agentId,
+            ...(opts.now ? { now: opts.now } : {}),
+            ...(opts.verifyEd25519 ? { verifyEd25519: opts.verifyEd25519 } : {}),
+        });
+        if (!result.ok) {
+            ctx.res = deny();
+            return;
+        }
+        await next();
+    };
+}
+function deny() {
+    return new Response("forbidden", { status: 403 });
+}

package/sdk/ts/resolvers/errors.d.ts

@@ -0,0 +1,130 @@
+/** Base of every resolver verdict. */
+export declare class ResolverError extends Error {
+}
+/** No key is known for the requested keyid/thumbprint (fall-through miss) —
+ * the class face of Go `ErrUnknownKey` / Python `UnknownKeyError`. The SDK's
+ * own resolver faces signal this verdict with an `undefined` return; the class
+ * exists for consumers and fail-closed composite stacks that surface the miss
+ * as a catchable error, keeping the taxonomy identical across all three SDKs. */
+export declare class UnknownKey extends ResolverError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The WBA identity directory (or a well-known JWKS/manifest) could not be
+ * fetched, returned non-200, or failed to decode. DISTINCT from unknown-key so a
+ * fail-closed composite halts on an outage instead of falling through. */
+export declare class DirectoryUnavailable extends ResolverError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The thumbprint is present in the directory host's current revocation snapshot. */
+export declare class KeyRevoked extends ResolverError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The key exists but `now` falls outside its [not_before, not_after) window. */
+export declare class KeyExpired extends ResolverError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The key resolved, but its directory declares a revocation_url whose snapshot
+ * has never been fetched (unreachable or not host-anchored) — so revocation was
+ * NEVER EVALUATED, DISTINCT from KeyRevoked ("evaluated and revoked"). Only
+ * thrown when the resolver's `requireRevocation` option is set; the default
+ * keeps the prior best-effort behavior (a declared-but-unreachable revocation
+ * channel does not block resolution). It lets a caller that treats revocation as
+ * mandatory fail closed instead of trusting an unevaluated key. */
+export declare class RevocationUnevaluated extends ResolverError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** A well-known manifest was fetched and decoded, but advertises no endpoint.
+ * DISTINCT from DirectoryUnavailable: the manifest is reachable, simply inert. */
+export declare class NoEndpoint extends ResolverError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** A well-known manifest was read and advertises an endpoint this resolver will
+ * not hand back: one on a host or port unrelated to the domain that served the
+ * manifest, or one carrying userinfo.
+ *
+ * DISTINCT from NoEndpoint and from DirectoryUnavailable because it is a VERDICT
+ * — the Exchange answered, and the answer is not usable. A caller that classifies
+ * retryability reads this as final rather than as something to try again in a
+ * moment. */
+export declare class EndpointRefused extends ResolverError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The deployment's allow overlay excluded this Exchange domain, before anything
+ * was dialled — the class face of Go `ErrExchangeNotPermitted` / Python
+ * `ExchangeNotPermittedError`. It says nothing about whether the Exchange exists
+ * or answers, only that this deployment declined to ask, so the remedy is a
+ * configuration change rather than a retry. */
+export declare class ExchangeNotPermitted extends ResolverError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The document served at the domain's well-known path describes some other role
+ * — the class face of Go `ErrManifestNotExchange` / Python
+ * `ManifestNotExchangeError`. Registration requirements are an Exchange's to
+ * publish, so a manifest claiming to be an agent, a broker or a publisher is
+ * refused rather than read for members it has no business carrying. A manifest
+ * naming no role at all is refused the same way: the field is required by the
+ * contract, and reading silence as assent would make the check advisory. */
+export declare class ManifestNotExchange extends ResolverError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The document arrived and this reader cannot use it — the class face of Go
+ * `ErrManifestUnusable` / Python `ManifestUnusableError`. A VERDICT and not a
+ * failed read: the bytes were served, and the next attempt gets the same ones, so
+ * a caller told to retry retries forever.
+ *
+ * The SDK's own requirements reader throws it for exactly ONE thing: a document
+ * whose version it cannot classify. That is the contract's own first question about
+ * this document, asked before any other member is read, and a layout no reader can
+ * classify is not a disappointment about one member — it is the whole document being
+ * unreadable for what a registration owes.
+ *
+ * The other two ways a manifest can disappoint that reader stay deliberate
+ * non-errors: a member carrying a type the contract does not admit reads as ABSENT,
+ * because the projection is shared with the endpoint and key faces, and a document
+ * that does not parse at all is a transport failure.
+ *
+ * It is ALSO the word for a reader stricter than the SDK's own, which is why the
+ * seam admits it at all: that seam is injectable, and a reader validating the whole
+ * document — or applying a version rule narrower than this one — has to be able to
+ * say its refusal is final.
+ *
+ * Deliberately NOT `ManifestVersionRefused`, which belongs to the endpoint seam. The
+ * two vocabularies are disjoint: that one answers whether an endpoint may be dialled,
+ * this one whether a document can be read for what a registration owes. */
+export declare class ManifestUnusable extends ResolverError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** A /.well-known/fora.json was fetched and parsed but carries a
+ * WellKnownManifest.ver this resolver does not accept: an unrecognised major
+ * version, a value that is not MAJOR.MINOR, or no version at all. The rule is
+ * manifestVersionRefusal in src/wire.ts.
+ *
+ * Like EndpointRefused it is a VERDICT — final, not a transport failure to
+ * retry — and it is never cached. The gate runs before any other member of the
+ * document is read, for the reason stated once on WellKnownManifest.ver in the
+ * proto. */
+export declare class ManifestVersionRefused extends ResolverError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}

package/sdk/ts/resolvers/errors.js

@@ -0,0 +1,150 @@
+// Typed error surface for the fetching resolver faces. The Go oracle uses
+// errors.Is-DISTINCT sentinels (ErrKeyRevoked / ErrKeyExpired /
+// ErrDirectoryUnavailable / ErrNoEndpoint / ErrUnknownKey) so a composite
+// resolver can HALT on a fail-closed verdict rather than fall through as if the
+// key were merely unknown. The TS port preserves that distinctness as distinct
+// thrown classes. The SDK's own RequestKeyResolver faces still signal a plain
+// miss with the `undefined` return (never a throw); UnknownKey below is the
+// catchable class of that same verdict for consumers and composite stacks that
+// need the error-shaped face Go and Python expose.
+/** Base of every resolver verdict. */
+export class ResolverError extends Error {
+}
+/** No key is known for the requested keyid/thumbprint (fall-through miss) —
+ * the class face of Go `ErrUnknownKey` / Python `UnknownKeyError`. The SDK's
+ * own resolver faces signal this verdict with an `undefined` return; the class
+ * exists for consumers and fail-closed composite stacks that surface the miss
+ * as a catchable error, keeping the taxonomy identical across all three SDKs. */
+export class UnknownKey extends ResolverError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "UnknownKey";
+    }
+}
+/** The WBA identity directory (or a well-known JWKS/manifest) could not be
+ * fetched, returned non-200, or failed to decode. DISTINCT from unknown-key so a
+ * fail-closed composite halts on an outage instead of falling through. */
+export class DirectoryUnavailable extends ResolverError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "DirectoryUnavailable";
+    }
+}
+/** The thumbprint is present in the directory host's current revocation snapshot. */
+export class KeyRevoked extends ResolverError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "KeyRevoked";
+    }
+}
+/** The key exists but `now` falls outside its [not_before, not_after) window. */
+export class KeyExpired extends ResolverError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "KeyExpired";
+    }
+}
+/** The key resolved, but its directory declares a revocation_url whose snapshot
+ * has never been fetched (unreachable or not host-anchored) — so revocation was
+ * NEVER EVALUATED, DISTINCT from KeyRevoked ("evaluated and revoked"). Only
+ * thrown when the resolver's `requireRevocation` option is set; the default
+ * keeps the prior best-effort behavior (a declared-but-unreachable revocation
+ * channel does not block resolution). It lets a caller that treats revocation as
+ * mandatory fail closed instead of trusting an unevaluated key. */
+export class RevocationUnevaluated extends ResolverError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "RevocationUnevaluated";
+    }
+}
+/** A well-known manifest was fetched and decoded, but advertises no endpoint.
+ * DISTINCT from DirectoryUnavailable: the manifest is reachable, simply inert. */
+export class NoEndpoint extends ResolverError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "NoEndpoint";
+    }
+}
+/** A well-known manifest was read and advertises an endpoint this resolver will
+ * not hand back: one on a host or port unrelated to the domain that served the
+ * manifest, or one carrying userinfo.
+ *
+ * DISTINCT from NoEndpoint and from DirectoryUnavailable because it is a VERDICT
+ * — the Exchange answered, and the answer is not usable. A caller that classifies
+ * retryability reads this as final rather than as something to try again in a
+ * moment. */
+export class EndpointRefused extends ResolverError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "EndpointRefused";
+    }
+}
+/** The deployment's allow overlay excluded this Exchange domain, before anything
+ * was dialled — the class face of Go `ErrExchangeNotPermitted` / Python
+ * `ExchangeNotPermittedError`. It says nothing about whether the Exchange exists
+ * or answers, only that this deployment declined to ask, so the remedy is a
+ * configuration change rather than a retry. */
+export class ExchangeNotPermitted extends ResolverError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ExchangeNotPermitted";
+    }
+}
+/** The document served at the domain's well-known path describes some other role
+ * — the class face of Go `ErrManifestNotExchange` / Python
+ * `ManifestNotExchangeError`. Registration requirements are an Exchange's to
+ * publish, so a manifest claiming to be an agent, a broker or a publisher is
+ * refused rather than read for members it has no business carrying. A manifest
+ * naming no role at all is refused the same way: the field is required by the
+ * contract, and reading silence as assent would make the check advisory. */
+export class ManifestNotExchange extends ResolverError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ManifestNotExchange";
+    }
+}
+/** The document arrived and this reader cannot use it — the class face of Go
+ * `ErrManifestUnusable` / Python `ManifestUnusableError`. A VERDICT and not a
+ * failed read: the bytes were served, and the next attempt gets the same ones, so
+ * a caller told to retry retries forever.
+ *
+ * The SDK's own requirements reader throws it for exactly ONE thing: a document
+ * whose version it cannot classify. That is the contract's own first question about
+ * this document, asked before any other member is read, and a layout no reader can
+ * classify is not a disappointment about one member — it is the whole document being
+ * unreadable for what a registration owes.
+ *
+ * The other two ways a manifest can disappoint that reader stay deliberate
+ * non-errors: a member carrying a type the contract does not admit reads as ABSENT,
+ * because the projection is shared with the endpoint and key faces, and a document
+ * that does not parse at all is a transport failure.
+ *
+ * It is ALSO the word for a reader stricter than the SDK's own, which is why the
+ * seam admits it at all: that seam is injectable, and a reader validating the whole
+ * document — or applying a version rule narrower than this one — has to be able to
+ * say its refusal is final.
+ *
+ * Deliberately NOT `ManifestVersionRefused`, which belongs to the endpoint seam. The
+ * two vocabularies are disjoint: that one answers whether an endpoint may be dialled,
+ * this one whether a document can be read for what a registration owes. */
+export class ManifestUnusable extends ResolverError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ManifestUnusable";
+    }
+}
+/** A /.well-known/fora.json was fetched and parsed but carries a
+ * WellKnownManifest.ver this resolver does not accept: an unrecognised major
+ * version, a value that is not MAJOR.MINOR, or no version at all. The rule is
+ * manifestVersionRefusal in src/wire.ts.
+ *
+ * Like EndpointRefused it is a VERDICT — final, not a transport failure to
+ * retry — and it is never cached. The gate runs before any other member of the
+ * document is read, for the reason stated once on WellKnownManifest.ver in the
+ * proto. */
+export class ManifestVersionRefused extends ResolverError {
+    constructor(message, options) {
+        super(message, options);
+        this.name = "ManifestVersionRefused";
+    }
+}

package/sdk/ts/resolvers/http.d.ts

@@ -0,0 +1,98 @@
+import { buildConnector } from "undici";
+/** The minimal response shape the resolvers read — a structural subset of the
+ * WHATWG `Response`, so the global `fetch` (and undici's) satisfies it. */
+export interface FetchResponse {
+    status: number;
+    text(): Promise<string>;
+}
+/** An injected HTTP GET. Defaults to the SSRF-guarded transport (guardedFetch). */
+export type FetchLike = (url: string) => Promise<FetchResponse>;
+/** 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 declare class SsrfBlockedError extends Error {
+    constructor(message: string);
+}
+/** 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 declare function ssrfGuard(): buildConnector.connector;
+/** 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 declare const guardedFetch: FetchLike;
+/** 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 declare function skipSSRF(): boolean;
+/** 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 declare function schemeGuardAllows(scheme: string): boolean;
+/**
+ * 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 declare function requireScheme(url: string): void;
+/** 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 declare function guardedFetchFromEnv(): FetchLike;
+/** 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 declare const defaultFetch: FetchLike;
+/** 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 declare function fetchStrict(fetchFn: FetchLike, url: string): Promise<string>;
+/** 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 declare function fetchSoft(fetchFn: FetchLike, url: string): Promise<string | undefined>;