@fora-protocol/sdk 1.0.3

package/sdk/ts/src/scopes.d.ts

@@ -0,0 +1,20 @@
+/**
+ * normalizeScopes returns scopes with empty entries dropped, duplicates removed
+ * (first-seen), and a stable (lexicographic) order — so two callers supplying
+ * the same set produce identical bytes on the wire. No casing change, no
+ * trimming. The sdk/go oracle returns nil for empty/all-empty input (JSON
+ * null); the TS face returns `[]` (the parity comparator treats null == []).
+ */
+export declare function normalizeScopes(scopes: string[]): string[];
+/**
+ * scopesSubset reports whether every scope in `sub` is present in `sup`. It is
+ * the delegation-attenuation rule (Delegation.scopes MUST be a subset of the
+ * principal's granted scopes). An empty `sub` is always a subset.
+ */
+export declare function scopesSubset(sub: string[], sup: string[]): boolean;
+/**
+ * applyScopes is the functional analogue of the Go ApplyScopes (which mutates a
+ * proto Requester). The TS port has no generated Requester mutation face, so it
+ * returns the normalized scopes array the caller stamps onto its own request.
+ */
+export declare function applyScopes(scopes: string[]): string[];

package/sdk/ts/src/scopes.js

@@ -0,0 +1,45 @@
+// Scopes / entitlements (ADR-020 §5) — TS port of the sdk/go oracle
+// (helpers/scopes.go). The subscriptions/entitlements a requester holds are a
+// SUPPLIED credential: the application hands the SDK what it holds and the SDK
+// plumbs it into the request. NormalizeScopes/ScopesSubset are pure, byte-
+// deterministic string ops pinned to the shared scopes-vectors.json.
+/**
+ * normalizeScopes returns scopes with empty entries dropped, duplicates removed
+ * (first-seen), and a stable (lexicographic) order — so two callers supplying
+ * the same set produce identical bytes on the wire. No casing change, no
+ * trimming. The sdk/go oracle returns nil for empty/all-empty input (JSON
+ * null); the TS face returns `[]` (the parity comparator treats null == []).
+ */
+export function normalizeScopes(scopes) {
+    const seen = new Set();
+    const out = [];
+    for (const s of scopes) {
+        if (s === "" || seen.has(s))
+            continue;
+        seen.add(s);
+        out.push(s);
+    }
+    out.sort();
+    return out;
+}
+/**
+ * scopesSubset reports whether every scope in `sub` is present in `sup`. It is
+ * the delegation-attenuation rule (Delegation.scopes MUST be a subset of the
+ * principal's granted scopes). An empty `sub` is always a subset.
+ */
+export function scopesSubset(sub, sup) {
+    const set = new Set(sup);
+    for (const s of sub) {
+        if (!set.has(s))
+            return false;
+    }
+    return true;
+}
+/**
+ * applyScopes is the functional analogue of the Go ApplyScopes (which mutates a
+ * proto Requester). The TS port has no generated Requester mutation face, so it
+ * returns the normalized scopes array the caller stamps onto its own request.
+ */
+export function applyScopes(scopes) {
+    return normalizeScopes(scopes);
+}

package/sdk/ts/src/signurl.d.ts

@@ -0,0 +1,23 @@
+/** Signed-URL sign inputs. An empty agentId yields a bearer (unbound) URL; an
+ * empty kid omits the kid param — mirror the Go signer's conditional sets. */
+export interface SignUrlParams {
+    kid: string;
+    agentId: string;
+    expUnix: number;
+}
+/**
+ * signEd25519SignedUrl signs `source` with `privateKey`, embedding exp (and kid
+ * when set, agent_id when set) plus the base64url-no-pad signature over
+ * "GET\n<url>". The URL is signed as OPAQUE BYTES — scheme/host/path are
+ * preserved verbatim; only the query is deterministically re-encoded. The emitted
+ * string is byte-identical to the Go oracle (helpers.SignURLEd25519).
+ */
+export declare function signEd25519SignedUrl(source: string, params: SignUrlParams, privateKey: CryptoKey): Promise<string>;
+/**
+ * canonicalUrl builds the URL whose bytes the signature covers: the raw prefix
+ * (scheme+host+path, VERBATIM) plus the deterministically re-encoded query. It
+ * drops sig, applies `mutate`, sorts, and re-encodes. Shared by the sign face
+ * (here) and the verify face (verify.ts::canonicalMessage) so both agree on the
+ * byte contract by construction. Exported for that reuse only.
+ */
+export declare function canonicalUrl(rawUrl: string, mutate?: (pairs: Array<[string, string]>) => void): string;

package/sdk/ts/src/signurl.js

@@ -0,0 +1,107 @@
+// sdk/ts Ed25519 signed delivery-URL SIGN face (ADR-013) — the Exchange-minting
+// sibling of src/verify.ts. Mirror of the Go oracle helpers.SignURLEd25519.
+//
+// THE CONTRACT: the signature covers "GET\n<url>" as
+// OPAQUE URL BYTES. Neither signer nor verifier re-normalizes scheme/host/path —
+// a mixed-case host, an explicit default port, and a raw space or percent in the
+// path are all preserved verbatim. The ONLY transform is deterministic query
+// handling (add exp/kid/agent_id, remove sig, sort the query). This is why the
+// canonical string is built by splitting the raw URL at its first "?" and keeping
+// the prefix byte-for-byte, rather than round-tripping through `new URL()` (which
+// WHATWG-lowercases the host, strips :443, and re-escapes the path).
+//
+// The query is re-encoded to match Go's url.Values.Encode() byte-for-byte
+// (sort by key, space -> "+", unreserved A-Za-z0-9-._~ kept, everything else
+// %XX uppercase) so the three SDKs produce identical bytes — see canonicalUrl.
+import { encodeBase64Url, utf8Bytes } from "./base64url.js";
+import { opaqueUrl } from "./opaque-url.js";
+const SIG_PARAM = "sig";
+const EXP_PARAM = "exp";
+const KID_PARAM = "kid";
+const AGENT_ID_PARAM = "agent_id";
+/**
+ * signEd25519SignedUrl signs `source` with `privateKey`, embedding exp (and kid
+ * when set, agent_id when set) plus the base64url-no-pad signature over
+ * "GET\n<url>". The URL is signed as OPAQUE BYTES — scheme/host/path are
+ * preserved verbatim; only the query is deterministically re-encoded. The emitted
+ * string is byte-identical to the Go oracle (helpers.SignURLEd25519).
+ */
+export async function signEd25519SignedUrl(source, params, privateKey) {
+    // Coerce a URL-like source (a Fastly Compute request URL object) to its opaque
+    // string form ONCE at the boundary; canonicalUrl needs string ops. No-op for
+    // string callers (verbatim bytes preserved).
+    const src = opaqueUrl(source);
+    const unsigned = canonicalUrl(src, (pairs) => {
+        setParam(pairs, EXP_PARAM, String(params.expUnix));
+        if (params.kid !== "")
+            setParam(pairs, KID_PARAM, params.kid);
+        if (params.agentId !== "")
+            setParam(pairs, AGENT_ID_PARAM, params.agentId);
+    });
+    const sig = new Uint8Array(await crypto.subtle.sign("Ed25519", privateKey, utf8Bytes(`GET\n${unsigned}`)));
+    const sigParam = encodeBase64Url(sig);
+    return canonicalUrl(unsigned, (pairs) => setParam(pairs, SIG_PARAM, sigParam));
+}
+/**
+ * canonicalUrl builds the URL whose bytes the signature covers: the raw prefix
+ * (scheme+host+path, VERBATIM) plus the deterministically re-encoded query. It
+ * drops sig, applies `mutate`, sorts, and re-encodes. Shared by the sign face
+ * (here) and the verify face (verify.ts::canonicalMessage) so both agree on the
+ * byte contract by construction. Exported for that reuse only.
+ */
+export function canonicalUrl(rawUrl, mutate) {
+    const q = rawUrl.indexOf("?");
+    const prefix = q >= 0 ? rawUrl.slice(0, q) : rawUrl;
+    const rawQuery = q >= 0 ? rawUrl.slice(q + 1) : "";
+    const pairs = parseQueryPairs(rawQuery).filter(([k]) => k !== SIG_PARAM);
+    mutate?.(pairs);
+    const encoded = encodeQuery(pairs);
+    return encoded === "" ? prefix : `${prefix}?${encoded}`;
+}
+/** setParam overwrites an existing key in place (preserving order) or appends. */
+function setParam(pairs, key, value) {
+    const existing = pairs.find(([k]) => k === key);
+    if (existing)
+        existing[1] = value;
+    else
+        pairs.push([key, value]);
+}
+/** parseQueryPairs splits a raw query into ordered [key, value] pairs, decoding
+ * each side exactly as Go's url.ParseQuery (a "+" decodes to a space). */
+function parseQueryPairs(rawQuery) {
+    if (rawQuery === "")
+        return [];
+    const out = [];
+    for (const part of rawQuery.split("&")) {
+        if (part === "")
+            continue;
+        const eq = part.indexOf("=");
+        const key = eq >= 0 ? part.slice(0, eq) : part;
+        const value = eq >= 0 ? part.slice(eq + 1) : "";
+        out.push([queryUnescape(key), queryUnescape(value)]);
+    }
+    return out;
+}
+/** encodeQuery serializes pairs byte-identically to Go's url.Values.Encode():
+ * sort by key (stable per-key value order), escape each side, join "k=v&k=v". */
+function encodeQuery(pairs) {
+    const sorted = [...pairs].sort((a, b) => (a[0] < b[0] ? -1 : a[0] > b[0] ? 1 : 0));
+    return sorted.map(([k, v]) => `${queryEscape(k)}=${queryEscape(v)}`).join("&");
+}
+/** Go url.QueryUnescape: "+" -> space, "%XX" -> byte, then UTF-8 decode. */
+function queryUnescape(s) {
+    return decodeURIComponent(s.replaceAll("+", " "));
+}
+/** Go url.QueryEscape: unreserved A-Za-z0-9-._~ kept, space -> "+", everything
+ * else percent-encoded uppercase (UTF-8). decodeURIComponent/encodeURIComponent
+ * keep a slightly wider unreserved set (!'()*), so post-process those to match. */
+function queryEscape(s) {
+    const encoded = encodeURIComponent(s)
+        .replaceAll("%20", "+")
+        .replaceAll("!", "%21")
+        .replaceAll("'", "%27")
+        .replaceAll("(", "%28")
+        .replaceAll(")", "%29")
+        .replaceAll("*", "%2A");
+    return encoded;
+}

package/sdk/ts/src/thumbprint.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Compute the RFC 7638 JWK Thumbprint of a raw 32-byte Ed25519 public key,
+ * base64url-no-pad encoded (ADR-013 D4).
+ *
+ * The canonical JWK is fixed by RFC 7638 §3.2 for OKP keys —
+ * `{"crv":"Ed25519","kty":"OKP","x":"<base64url-nopad(pubkey)>"}`, members in
+ * lexicographic order, no whitespace — and the thumbprint is
+ * `base64url-nopad(SHA-256(canonical JWK))`.
+ *
+ * This MUST stay byte-identical to the sdk/go oracle (helpers.Thumbprint, which
+ * builds the same canonical JWK via go-jose). Both are pinned to the shared
+ * testdata/thumbprint-vectors.json.
+ */
+export declare function thumbprint(pubkey: Uint8Array): Promise<string>;

package/sdk/ts/src/thumbprint.js

@@ -0,0 +1,24 @@
+import { encodeBase64Url } from "./base64url.js";
+const ED25519_PUBLIC_KEY_BYTES = 32;
+/**
+ * Compute the RFC 7638 JWK Thumbprint of a raw 32-byte Ed25519 public key,
+ * base64url-no-pad encoded (ADR-013 D4).
+ *
+ * The canonical JWK is fixed by RFC 7638 §3.2 for OKP keys —
+ * `{"crv":"Ed25519","kty":"OKP","x":"<base64url-nopad(pubkey)>"}`, members in
+ * lexicographic order, no whitespace — and the thumbprint is
+ * `base64url-nopad(SHA-256(canonical JWK))`.
+ *
+ * This MUST stay byte-identical to the sdk/go oracle (helpers.Thumbprint, which
+ * builds the same canonical JWK via go-jose). Both are pinned to the shared
+ * testdata/thumbprint-vectors.json.
+ */
+export async function thumbprint(pubkey) {
+    if (pubkey.length !== ED25519_PUBLIC_KEY_BYTES) {
+        throw new Error(`thumbprint: public key must be ${ED25519_PUBLIC_KEY_BYTES} bytes`);
+    }
+    const x = encodeBase64Url(pubkey);
+    const canonical = `{"crv":"Ed25519","kty":"OKP","x":"${x}"}`;
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(canonical));
+    return encodeBase64Url(new Uint8Array(digest));
+}

package/sdk/ts/src/verify.d.ts

@@ -0,0 +1,49 @@
+export interface VerifyResult {
+    valid: boolean;
+    expired: boolean;
+    kid?: string;
+    /** RFC 7638 thumbprint the URL is bound to (base64url string, the agent_id
+     * param verbatim) — the same name/representation as Go VerifiedURL.AgentID
+     * and Python SignedUrlResult.agent_id. Absent on a bearer (unbound) URL. */
+    agentId?: string;
+    reason?: VerifyFailure;
+}
+export type VerifyFailure = "missing_sig" | "missing_exp" | "bad_sig_encoding" | "bad_exp_encoding" | "expired" | "bad_agent_encoding" | "signature_mismatch";
+/**
+ * The Ed25519 primitive the verify envelope calls once a key is resolved. It
+ * receives the resolved key (whatever type `resolveKey` yields — a WebCrypto
+ * `CryptoKey` by default, but a raw 32-byte public key on a runtime whose
+ * SubtleCrypto lacks Ed25519), the canonical message bytes, and the signature
+ * bytes, and returns whether the signature verifies. INJECTABLE so a consumer
+ * on a runtime without native Ed25519 (Fastly Compute) swaps in @noble/ed25519
+ * and reuses this whole envelope (param parse, expiry, reason mapping) instead
+ * of re-hand-rolling it — mirroring how the sign/verify faces already inject
+ * key resolution. `K` is inferred from `resolveKey`.
+ */
+export type Ed25519Verifier<K = CryptoKey> = (key: K, message: Uint8Array<ArrayBuffer>, sig: Uint8Array<ArrayBuffer>) => Promise<boolean> | boolean;
+export interface VerifyDeps<K = CryptoKey> {
+    now?: () => number;
+    resolveKey: (kid: string | undefined) => Promise<K | undefined>;
+    /** Ed25519 primitive; defaults to WebCrypto native (`crypto.subtle.verify`).
+     * A runtime lacking native Ed25519 injects its own (e.g. @noble/ed25519) and
+     * MUST when `resolveKey` yields a non-`CryptoKey` (e.g. raw public-key bytes). */
+    verify?: Ed25519Verifier<K>;
+}
+export declare function verifyEd25519SignedUrl<K = CryptoKey>(rawUrl: string, deps: VerifyDeps<K>): Promise<VerifyResult>;
+/**
+ * The canonical signed message: "GET\n<url>" over the URL as OPAQUE BYTES. Only
+ * the `sig` param is stripped and the query is deterministically re-encoded;
+ * scheme/host/path are preserved verbatim (no `new URL()` host-lowercasing,
+ * default-port stripping, or path-escaping). Reuses the SAME builder the sign
+ * face uses (signurl.ts::canonicalUrl) so signer and verifier agree by
+ * construction — see the verbatim-canonicalization contract there.
+ *
+ * rawUrl is coerced via opaqueUrl defensively: some edge runtimes (Fastly Compute)
+ * hand the request URL as a URL-like object rather than a primitive string, and
+ * canonicalUrl needs string operations. For a primitive string this is a no-op,
+ * so the verbatim bytes are preserved for the server-to-server callers that own
+ * the raw URL string. This coercion is retained even though verifyEd25519SignedUrl
+ * now coerces at its boundary: canonicalMessage is a public export with its own
+ * external callers, so it owns its input contract independently.
+ */
+export declare function canonicalMessage(rawUrl: string): Uint8Array<ArrayBuffer>;

package/sdk/ts/src/verify.js

@@ -0,0 +1,109 @@
+import { z } from "zod";
+import { decodeBase64Url, utf8Bytes } from "./base64url.js";
+import { opaqueUrl } from "./opaque-url.js";
+import { canonicalUrl } from "./signurl.js";
+const ParamsSchema = z.object({
+    sig: z.string().min(1),
+    exp: z.string().regex(/^\d+$/),
+    kid: z.string().min(1).optional(),
+    agentId: z.string().min(1).optional(),
+});
+// The default primitive: WebCrypto native Ed25519. Byte-identical to the prior
+// inline crypto.subtle.verify — the argument order is adapted (WebCrypto takes
+// (algo, key, sig, data); the injectable contract is (key, message, sig)).
+const defaultVerify = (key, message, sig) => crypto.subtle.verify("Ed25519", key, sig, message);
+export async function verifyEd25519SignedUrl(rawUrl, deps) {
+    // Coerce a URL-like input (a Fastly Compute request URL object) to its opaque
+    // string form ONCE at the boundary, so param parsing and the canonical message
+    // both operate on the same verbatim bytes. No-op for string callers.
+    const raw = opaqueUrl(rawUrl);
+    const url = new URL(raw);
+    const params = parseParams(url);
+    if (!params.ok) {
+        return { valid: false, expired: false, reason: params.reason };
+    }
+    const { sig, exp, kid, agentId } = params.value;
+    const nowSec = Math.floor((deps.now?.() ?? Date.now()) / 1000);
+    if (nowSec >= Number(exp)) {
+        return { valid: false, expired: true, reason: "expired" };
+    }
+    const sigBytes = decodeBase64Url(sig);
+    if (!sigBytes) {
+        return { valid: false, expired: false, reason: "bad_sig_encoding" };
+    }
+    if (agentId !== undefined) {
+        // Decode purely as VALIDATION: a malformed agent_id is rejected before any
+        // signature work; the public surface carries the base64url STRING verbatim.
+        if (!decodeBase64Url(agentId)) {
+            return { valid: false, expired: false, reason: "bad_agent_encoding" };
+        }
+    }
+    const key = await deps.resolveKey(kid);
+    if (!key) {
+        return buildResult({ valid: false, expired: false, kid, reason: "signature_mismatch" });
+    }
+    const message = canonicalMessage(raw);
+    // The default cast is dead when K !== CryptoKey: such a consumer always
+    // supplies its own verifier (the `??` short-circuits), so defaultVerify — which
+    // only type-checks for CryptoKey — is never reached with a foreign key type.
+    const verify = deps.verify ?? defaultVerify;
+    const okSig = await verify(key, message, sigBytes);
+    if (!okSig) {
+        return buildResult({ valid: false, expired: false, kid, reason: "signature_mismatch" });
+    }
+    return buildResult({ valid: true, expired: false, kid, ...(agentId !== undefined && { agentId }) });
+}
+function buildResult(r) {
+    const out = { valid: r.valid, expired: r.expired };
+    if (r.kid !== undefined)
+        out.kid = r.kid;
+    if (r.agentId !== undefined)
+        out.agentId = r.agentId;
+    if (r.reason !== undefined)
+        out.reason = r.reason;
+    return out;
+}
+function parseParams(url) {
+    const sig = url.searchParams.get("sig");
+    if (!sig)
+        return { ok: false, reason: "missing_sig" };
+    const exp = url.searchParams.get("exp");
+    if (!exp)
+        return { ok: false, reason: "missing_exp" };
+    const kidRaw = url.searchParams.get("kid");
+    const agentRaw = url.searchParams.get("agent_id");
+    const candidate = { sig, exp };
+    if (kidRaw !== null)
+        candidate.kid = kidRaw;
+    if (agentRaw !== null)
+        candidate.agentId = agentRaw;
+    const parsed = ParamsSchema.safeParse(candidate);
+    if (!parsed.success) {
+        return { ok: false, reason: "bad_exp_encoding" };
+    }
+    const value = { sig: parsed.data.sig, exp: parsed.data.exp };
+    if (parsed.data.kid !== undefined)
+        value.kid = parsed.data.kid;
+    if (parsed.data.agentId !== undefined)
+        value.agentId = parsed.data.agentId;
+    return { ok: true, value };
+}
+/**
+ * The canonical signed message: "GET\n<url>" over the URL as OPAQUE BYTES. Only
+ * the `sig` param is stripped and the query is deterministically re-encoded;
+ * scheme/host/path are preserved verbatim (no `new URL()` host-lowercasing,
+ * default-port stripping, or path-escaping). Reuses the SAME builder the sign
+ * face uses (signurl.ts::canonicalUrl) so signer and verifier agree by
+ * construction — see the verbatim-canonicalization contract there.
+ *
+ * rawUrl is coerced via opaqueUrl defensively: some edge runtimes (Fastly Compute)
+ * hand the request URL as a URL-like object rather than a primitive string, and
+ * canonicalUrl needs string operations. For a primitive string this is a no-op,
+ * so the verbatim bytes are preserved for the server-to-server callers that own
+ * the raw URL string. This coercion is retained even though verifyEd25519SignedUrl
+ * now coerces at its boundary: canonicalMessage is a public export with its own
+ * external callers, so it owns its input contract independently.
+ */
+export function canonicalMessage(rawUrl) {
+    return utf8Bytes(`GET\n${canonicalUrl(opaqueUrl(rawUrl))}`);
+}

package/sdk/ts/src/wire-names.d.ts

@@ -0,0 +1 @@
+export { snakeFromJsonName } from "../../../gen/ts/wire/names.ts";

package/sdk/ts/src/wire-names.js

@@ -0,0 +1,16 @@
+// Recovering a proto field name from protojson's lowerCamelCase spelling of it.
+//
+// Re-export, not a second copy. The rule lives in gen/ts/wire/names.ts, beside the
+// generated schemas, because the schema seam itself depends on it — wire/base.ts refuses
+// an answer spelled in the json_name alias, and a rule the seam needs cannot live in a
+// tier above the seam. It is re-exported here so the SDK's own reader of the alias — the
+// Connect error-detail `debug` projection, which IS lowerCamelCase and cannot be made
+// otherwise — reaches the same implementation rather than transcribing it.
+//
+// One rule, two callers, opposite verdicts, which is the reason it is worth sharing:
+// errordetail NORMALIZES the alias (Connect emits it there and no server codec replaces
+// it), while the schema seam REFUSES it (a whole response body in the alias means the peer
+// is not speaking the contract).
+//
+// See gen/ts/wire/names.ts for the rule itself and why the boundary test is ASCII-only.
+export { snakeFromJsonName } from "../../../gen/ts/wire/names.js";

package/sdk/ts/src/wire.d.ts

@@ -0,0 +1,68 @@
+/** ContentTypeProto is the Content-Type for binary protobuf bodies. */
+export declare const ContentTypeProto = "application/proto";
+/** ContentTypeJSON is the Content-Type for canonical proto-JSON bodies. */
+export declare const ContentTypeJSON = "application/json";
+/** ConnectProtocolVersionHeader carries the Connect unary protocol version. */
+export declare const ConnectProtocolVersionHeader = "Connect-Protocol-Version";
+/** ConnectProtocolVersion is the only Connect protocol version FORA speaks. */
+export declare const ConnectProtocolVersion = "1";
+/**
+ * ProtocolVersion is the FORA protocol version stamped on the `ver` field of
+ * every FORA message — NOT the Connect transport version above. Senders stamp
+ * it from here so a protocol bump is a single edit; receivers treat `ver` as
+ * advisory. The /.well-known/fora.json document carries its own version in a
+ * separate namespace, which this constant does NOT supply — that is
+ * WellKnownManifestVersion.
+ */
+export declare const ProtocolVersion = "1.0";
+/**
+ * WellKnownManifestVersion is the version of the /.well-known/fora.json DOCUMENT
+ * layout, stamped on WellKnownManifest.ver by every party that serves one. A
+ * namespace separate from ProtocolVersion and never derived from it: a change
+ * to the manifest layout bumps both numbers, a protocol change that leaves the
+ * manifest untouched bumps only ProtocolVersion. Both read "1.0" today because
+ * neither has moved yet; neither is derived from the other. The receive-side
+ * check a manifest reader applies is manifestVersionRefusal.
+ */
+export declare const WellKnownManifestVersion = "1.0";
+/** RequestIDHeader correlates a request across services and the edge. */
+export declare const RequestIDHeader = "X-Request-ID";
+/** SignatureAgentHeader carries the signer's Web Bot Auth key-directory URL. */
+export declare const SignatureAgentHeader = "Signature-Agent";
+/**
+ * Header carrying the fetcher's raw Ed25519 public key on a PoP GET. Canonical
+ * (Go) casing; HTTP field names are case-insensitive, so lookups lowercase it —
+ * see `AGENT_KEY_HEADER` in `pop.ts`, which derives from this rather than
+ * restating the string.
+ */
+export declare const AgentKeyHeader = "X-FORA-Agent-Key";
+/**
+ * Path of the discovery document on every Exchange host. The one bootstrap
+ * coordinate: a client holding only a hostname fetches
+ * `{scheme}://{host}${WellKnownPath}` to learn the endpoint and the keys, so the
+ * three SDKs agreeing on it is the precondition for interop, not a tidiness
+ * concern.
+ * `WellKnownManifestVersion` versions the document's content; `WellKnownPath`
+ * specifies where it is served.
+ */
+export declare const WellKnownPath = "/.well-known/fora.json";
+/**
+ * The receive-side rule for WellKnownManifest.ver, as a pure verdict.
+ *
+ * Returns undefined when the document is accepted — its MAJOR equals the major
+ * of WellKnownManifestVersion, whatever the MINOR. Otherwise returns the reason:
+ * an unrecognised major, a value that is not MAJOR.MINOR, or an absent member
+ * (undefined, null, or any non-string is how a missing `ver` arrives from
+ * JSON.parse). Absent is refused because a document with no version is one whose
+ * layout the reader cannot classify. Why a minor is accepted, and why the gate
+ * runs before any other member is read and fails closed, is stated once on
+ * WellKnownManifest.ver in the proto.
+ *
+ * The message names the value found so an operator can tell a version mismatch
+ * from a network failure, clipped to MAX_ECHOED_VER characters: the body is read
+ * up to 1 MiB and a refusal is never cached, so an unclipped echo would let a
+ * hostile origin size every error. The three SDK languages pin this verdict to a
+ * shared corpus. The error a resolver throws for a refusal is
+ * ManifestVersionRefused.
+ */
+export declare function manifestVersionRefusal(ver: unknown): string | undefined;

package/sdk/ts/src/wire.js

@@ -0,0 +1,114 @@
+// Wire constants shared across the SDK — TS port of the sdk/go oracle
+// (helpers/constants.go + core/requestid.go). Encoding is negotiated per hop via
+// Content-Type (ADR-020): application/proto for binary, application/json for
+// canonical proto-JSON. The Go layer splits RequestIDHeader across
+// helpers/constants.go and core/requestid.go; the single TS module exposes all
+// ten values once. Pinned to wire-constants-vectors.json.
+//
+// Also home to the pure receive-side rule for WellKnownManifest.ver, so the
+// constant and the check that reads it sit together.
+/** ContentTypeProto is the Content-Type for binary protobuf bodies. */
+export const ContentTypeProto = "application/proto";
+/** ContentTypeJSON is the Content-Type for canonical proto-JSON bodies. */
+export const ContentTypeJSON = "application/json";
+/** ConnectProtocolVersionHeader carries the Connect unary protocol version. */
+export const ConnectProtocolVersionHeader = "Connect-Protocol-Version";
+/** ConnectProtocolVersion is the only Connect protocol version FORA speaks. */
+export const ConnectProtocolVersion = "1";
+/**
+ * ProtocolVersion is the FORA protocol version stamped on the `ver` field of
+ * every FORA message — NOT the Connect transport version above. Senders stamp
+ * it from here so a protocol bump is a single edit; receivers treat `ver` as
+ * advisory. The /.well-known/fora.json document carries its own version in a
+ * separate namespace, which this constant does NOT supply — that is
+ * WellKnownManifestVersion.
+ */
+export const ProtocolVersion = "1.0";
+/**
+ * WellKnownManifestVersion is the version of the /.well-known/fora.json DOCUMENT
+ * layout, stamped on WellKnownManifest.ver by every party that serves one. A
+ * namespace separate from ProtocolVersion and never derived from it: a change
+ * to the manifest layout bumps both numbers, a protocol change that leaves the
+ * manifest untouched bumps only ProtocolVersion. Both read "1.0" today because
+ * neither has moved yet; neither is derived from the other. The receive-side
+ * check a manifest reader applies is manifestVersionRefusal.
+ */
+export const WellKnownManifestVersion = "1.0";
+/** RequestIDHeader correlates a request across services and the edge. */
+export const RequestIDHeader = "X-Request-ID";
+/** SignatureAgentHeader carries the signer's Web Bot Auth key-directory URL. */
+export const SignatureAgentHeader = "Signature-Agent";
+/**
+ * Header carrying the fetcher's raw Ed25519 public key on a PoP GET. Canonical
+ * (Go) casing; HTTP field names are case-insensitive, so lookups lowercase it —
+ * see `AGENT_KEY_HEADER` in `pop.ts`, which derives from this rather than
+ * restating the string.
+ */
+export const AgentKeyHeader = "X-FORA-Agent-Key";
+/**
+ * Path of the discovery document on every Exchange host. The one bootstrap
+ * coordinate: a client holding only a hostname fetches
+ * `{scheme}://{host}${WellKnownPath}` to learn the endpoint and the keys, so the
+ * three SDKs agreeing on it is the precondition for interop, not a tidiness
+ * concern.
+ * `WellKnownManifestVersion` versions the document's content; `WellKnownPath`
+ * specifies where it is served.
+ */
+export const WellKnownPath = "/.well-known/fora.json";
+const ASCII_DIGITS = /^[0-9]+$/;
+/** The MAJOR run of a MAJOR.MINOR string, or undefined when `ver` is not one.
+ * Both runs must be non-empty ASCII digits joined by exactly one dot; a missing
+ * minor, a patch component, a leading "v", surrounding whitespace or a non-digit
+ * is not a version this rule recognises. */
+function parseMajor(ver) {
+    const dot = ver.indexOf(".");
+    if (dot < 0)
+        return undefined;
+    const major = ver.slice(0, dot);
+    const minor = ver.slice(dot + 1);
+    if (!ASCII_DIGITS.test(major) || !ASCII_DIGITS.test(minor))
+        return undefined;
+    return major;
+}
+/**
+ * The receive-side rule for WellKnownManifest.ver, as a pure verdict.
+ *
+ * Returns undefined when the document is accepted — its MAJOR equals the major
+ * of WellKnownManifestVersion, whatever the MINOR. Otherwise returns the reason:
+ * an unrecognised major, a value that is not MAJOR.MINOR, or an absent member
+ * (undefined, null, or any non-string is how a missing `ver` arrives from
+ * JSON.parse). Absent is refused because a document with no version is one whose
+ * layout the reader cannot classify. Why a minor is accepted, and why the gate
+ * runs before any other member is read and fails closed, is stated once on
+ * WellKnownManifest.ver in the proto.
+ *
+ * The message names the value found so an operator can tell a version mismatch
+ * from a network failure, clipped to MAX_ECHOED_VER characters: the body is read
+ * up to 1 MiB and a refusal is never cached, so an unclipped echo would let a
+ * hostile origin size every error. The three SDK languages pin this verdict to a
+ * shared corpus. The error a resolver throws for a refusal is
+ * ManifestVersionRefused.
+ */
+export function manifestVersionRefusal(ver) {
+    const acceptMajor = parseMajor(WellKnownManifestVersion);
+    if (acceptMajor === undefined) {
+        throw new Error(`WellKnownManifestVersion is not MAJOR.MINOR: ${WellKnownManifestVersion}`);
+    }
+    if (typeof ver !== "string" || ver === "") {
+        return `ver is absent, accept major ${acceptMajor}`;
+    }
+    const major = parseMajor(ver);
+    if (major === undefined) {
+        return `ver ${JSON.stringify(echoVer(ver))} is not MAJOR.MINOR, accept major ${acceptMajor}`;
+    }
+    if (major !== acceptMajor) {
+        return `ver ${JSON.stringify(echoVer(ver))} has major ${major}, accept major ${acceptMajor}`;
+    }
+    return undefined;
+}
+/** How much of a refused `ver` an error message repeats. Go and Python clip at
+ * the same length, so an operator reading three SDKs' logs sees the same prefix. */
+const MAX_ECHOED_VER = 64;
+function echoVer(ver) {
+    return ver.length <= MAX_ECHOED_VER ? ver : `${ver.slice(0, MAX_ECHOED_VER)}...`;
+}