@fora-protocol/sdk 1.0.3

package/sdk/ts/src/pop.js

@@ -0,0 +1,166 @@
+import { thumbprint } from "./thumbprint.js";
+import { AgentKeyHeader } from "./wire.js";
+import { decodeBase64Url, utf8Bytes } from "./base64url.js";
+import { opaqueUrl } from "./opaque-url.js";
+// Proof-of-possession verification for delivery-URL identity binding (ADR-013),
+// relocated from the app edge (src/edge/src/pop.ts) as a pure L1 helper.
+//
+// When a signed URL carries an `agent_id` (the agent's RFC 7638 thumbprint), a
+// code-capable edge requires the fetcher to prove possession of the bound key —
+// fully offline:
+//
+//   1. present its raw Ed25519 public key in `X-FORA-Agent-Key`, and
+//   2. sign the GET with RFC 9421 over `@method` + `@target-uri`,
+//
+// and the edge enforces the 3-way identity:
+//
+//   agent_id (URL) == keyid (Signature-Input) == thumbprint(presented key)
+//
+// The Ed25519 verify primitive is INJECTABLE (input.verifyEd25519) so a runtime
+// without WebCrypto Ed25519 (Fastly Compute) can supply its own — the byte
+// contract is the signature base, not the primitive. The default primitive is
+// WebCrypto crypto.subtle, which observes byte-identical output on the default
+// path. Byte-parity guard: the pop vectors are produced by the sdk/go signer
+// over the same @method/@target-uri base (sigbase.go buildSignatureBase).
+export const AGENT_KEY_HEADER = AgentKeyHeader.toLowerCase();
+const ED25519_PUBLIC_KEY_BYTES = 32;
+const okResult = { ok: true };
+const fail = (reason) => ({ ok: false, reason });
+/**
+ * Verify the agent's proof of possession of the key bound to `agentId`.
+ * Returns `{ ok: true }` only when the presented key, the RFC 9421 signature,
+ * and the 3-way identity all check out.
+ */
+export async function verifyAgentBinding(input) {
+    const presented = readPresentedKey(input.headers);
+    if (!presented.ok)
+        return presented.result;
+    const parsed = parseSignatureInput(input.headers.get("signature-input"));
+    if (!parsed)
+        return fail("malformed_sig_input");
+    // alg is an early reject only; the verify primitive is hard-pinned to Ed25519,
+    // so alg is never a key/algorithm SELECTION input (no downgrade possible).
+    if (parsed.alg.toLowerCase() !== "ed25519")
+        return fail("unsupported_alg");
+    if (!coversExactly(parsed.covered))
+        return fail("bad_covered_components");
+    const sigBytes = parseSignature(input.headers.get("signature"));
+    if (!sigBytes)
+        return fail("missing_sig");
+    // 3-way identity. keyid and the presented-key thumbprint must both equal the
+    // URL-bound agent_id before any signature work is trusted.
+    if (parsed.keyid !== input.agentId)
+        return fail("keyid_mismatch");
+    const presentedThumb = await thumbprint(presented.key);
+    if (presentedThumb !== input.agentId)
+        return fail("thumbprint_mismatch");
+    const stale = freshnessFailure(parsed, input.now);
+    if (stale)
+        return fail(stale);
+    // Coerce a URL-like input (Fastly hands a URL object, not a string) to its
+    // opaque string form once at the boundary. The @target-uri line must carry the
+    // verbatim bytes the agent signed, never a WHATWG-normalized toString(). This
+    // is behavior-neutral for the template literal on a string caller
+    // (String(s) === s); it makes the opaque-string contract explicit and matches
+    // the signed-URL verify boundary.
+    const url = opaqueUrl(input.url);
+    const base = signatureBase(input.method, url, parsed.rawParams);
+    const verify = input.verifyEd25519 ?? defaultVerifyEd25519;
+    const valid = await verify(presented.key, sigBytes, utf8Bytes(base));
+    return valid ? okResult : fail("pop_sig_invalid");
+}
+function readPresentedKey(headers) {
+    const raw = headers.get(AGENT_KEY_HEADER);
+    if (!raw)
+        return { ok: false, result: fail("missing_agent_key") };
+    const bytes = decodeBase64Url(raw);
+    if (!bytes || bytes.length !== ED25519_PUBLIC_KEY_BYTES) {
+        return { ok: false, result: fail("bad_agent_key") };
+    }
+    return { ok: true, key: bytes };
+}
+function coversExactly(covered) {
+    return covered.length === 2 && covered.includes("@method") && covered.includes("@target-uri");
+}
+// MAX_FUTURE_SKEW_SEC: a proof's created timestamp may not lead the verifier
+// clock by more than this (mirrors the Go service-to-service verifier).
+const MAX_FUTURE_SKEW_SEC = 300;
+function freshnessFailure(parsed, now) {
+    const nowSec = Math.floor((now?.() ?? Date.now()) / 1000);
+    if (parsed.created === undefined)
+        return "pop_missing_created";
+    if (parsed.created > nowSec + MAX_FUTURE_SKEW_SEC)
+        return "pop_future_created";
+    if (parsed.expires === undefined)
+        return "pop_missing_exp";
+    if (nowSec >= parsed.expires)
+        return "pop_expired";
+    return undefined;
+}
+/**
+ * Rebuild the RFC 9421 signature base for the covered GET components. Order
+ * mirrors the inner list (`@method`, `@target-uri`), then `@signature-params`.
+ * MUST stay byte-identical to the sdk/go signer (sigbase.go buildSignatureBase).
+ */
+export function signatureBase(method, url, rawParams) {
+    return [
+        `"@method": ${method.toUpperCase()}`,
+        `"@target-uri": ${url}`,
+        `"@signature-params": ${rawParams}`,
+    ].join("\n");
+}
+/** Parse `label=("@method" "@target-uri");keyid="..";alg="..";created=..;expires=..`. */
+export function parseSignatureInput(raw) {
+    if (!raw)
+        return undefined;
+    const eq = raw.indexOf("=");
+    if (eq < 0)
+        return undefined;
+    const rawParams = raw.slice(eq + 1).trim();
+    const listMatch = rawParams.match(/^\(([^)]*)\)(.*)$/);
+    if (!listMatch)
+        return undefined;
+    const covered = [...(listMatch[1] ?? "").matchAll(/"([^"]+)"/g)].map((m) => m[1]);
+    const tail = listMatch[2] ?? "";
+    const keyid = matchParam(tail, /;keyid="([^"]*)"/);
+    const alg = matchParam(tail, /;alg="([^"]*)"/);
+    if (keyid === undefined || alg === undefined)
+        return undefined;
+    const created = matchInt(tail, /;created=(\d+)/);
+    const expires = matchInt(tail, /;expires=(\d+)/);
+    return {
+        covered,
+        rawParams,
+        keyid,
+        alg,
+        ...(created !== undefined ? { created } : {}),
+        ...(expires !== undefined ? { expires } : {}),
+    };
+}
+function matchParam(s, re) {
+    return s.match(re)?.[1];
+}
+function matchInt(s, re) {
+    const m = s.match(re);
+    return m ? Number(m[1]) : undefined;
+}
+/** Parse the RFC 9421 `Signature` header value `label=:<base64>:`. */
+export function parseSignature(raw) {
+    if (!raw)
+        return undefined;
+    const m = raw.match(/:([^:]+):/);
+    if (!m || !m[1])
+        return undefined;
+    // The Signature byte string is standard base64; decodeBase64Url's url->std
+    // alphabet remap is a no-op on it, so the shared decoder handles it.
+    return decodeBase64Url(m[1]);
+}
+const defaultVerifyEd25519 = async (pubkey, sig, message) => {
+    try {
+        const key = await crypto.subtle.importKey("raw", pubkey, { name: "Ed25519" }, false, ["verify"]);
+        return await crypto.subtle.verify("Ed25519", key, sig, message);
+    }
+    catch {
+        return false;
+    }
+};

package/sdk/ts/src/regschema.d.ts

@@ -0,0 +1,229 @@
+import { type ValidateFunction } from "ajv/dist/2020.js";
+import type { RegistrationFieldError as RegistrationFieldErrorShape } from "./errordetail.ts";
+/**
+ * maxRegistrationSchemaBytes is the published schema's size cap, measured as the
+ * UTF-8 bytes of the data_schema member AS SERVED in fora.json — which is why the
+ * compile face takes raw bytes rather than a decoded document. A re-encoding is a
+ * different length than what the origin sent, and the cap is defined over what the
+ * origin sent.
+ */
+export declare const maxRegistrationSchemaBytes = 16384;
+/**
+ * maxRegistrationSchemaDepth bounds how deeply the schema document may nest. It
+ * counts JSON containers, so a bare `{}` is depth 1. Deep allOf/$ref chains are
+ * the cheapest way to make a compile expensive, and a real registration schema is
+ * three to five levels deep.
+ */
+export declare const maxRegistrationSchemaDepth = 32;
+/**
+ * maxRegistrationFieldErrors is the number of member failures a refusal may carry
+ * — the wire's own bound (RegistrationFailure.field_errors declares
+ * repeated.max_items = 64), restated so the validator never builds a list the
+ * contract would reject.
+ */
+export declare const maxRegistrationFieldErrors = 64;
+/** The wire bounds on RegistrationFieldError.path and .error. */
+export declare const maxRegistrationFieldErrorPathLen = 255;
+export declare const maxRegistrationFieldErrorTextLen = 255;
+/**
+ * registrationSchemaDialect is the only $schema value a published data_schema may
+ * name. A document that names none is read as this dialect; one that names another
+ * is refused rather than validated under semantics its author did not intend.
+ */
+export declare const registrationSchemaDialect = "https://json-schema.org/draft/2020-12/schema";
+/**
+ * maxRegistrationSchemaEvaluations bounds the WORK of checking a payload, which the
+ * size and depth caps do not: `anyOf` branches multiply along a reference chain, so a
+ * schema can be small and shallow and still cost an unbounded amount to evaluate.
+ * Cost is linear in this count, so the bound is really a time bound expressed as a
+ * number a static walk can compute and a shared corpus can pin, which a stopwatch
+ * cannot.
+ */
+export declare const maxRegistrationSchemaEvaluations = 10000;
+/**
+ * maxRegistrationSchemaRefHops bounds how long a `$ref` chain may be, measured as the
+ * longest path of reference hops rather than as the number of references a document
+ * contains.
+ *
+ * A SEPARATE axis from maxRegistrationSchemaDepth, and the shape that forced it shows
+ * why: a chain of five hundred definitions, each referring to the next, is three JSON
+ * containers deep however long it is, so the depth cap never sees it. The evaluation cap
+ * does not see it either — a flat chain costs one evaluation per link.
+ *
+ * What it bounds is the RECURSION a validator does while resolving that chain. The cost
+ * walk here does not care, but the libraries the three SDKs hand an accepted schema to
+ * do, and one of them exhausted its interpreter stack at 495 links — raising out of a
+ * face documented as returning a verdict, on a document every SDK had just called valid.
+ */
+export declare const maxRegistrationSchemaRefHops = 100;
+/**
+ * SchemaVerdict is the outcome of compiling a published data_schema. The tokens
+ * are the Go `SchemaVerdict.String()` vocabulary verbatim, which is what the
+ * shared vectors record — a union of string literals rather than a numeric enum,
+ * matching the sibling AudienceVerdict.
+ *
+ * "no_verdict" is Go's zero value and is never returned here; it is in the
+ * vocabulary because the corpus carries the whole vocabulary.
+ */
+export declare const schemaVerdicts: readonly ["no_verdict", "accepted", "malformed", "wrong_dialect", "remote_ref", "too_large", "too_deep", "unsafe_pattern", "too_complex", "ref_cycle", "ref_chain_too_long", "compile_timeout", "uncompilable", "not_published"];
+export type SchemaVerdict = (typeof schemaVerdicts)[number];
+export type { RegistrationFieldError } from "./errordetail.ts";
+/** One failure before it is narrowed to the wire's two-field shape. */
+export interface SchemaViolation extends RegistrationFieldErrorShape {
+    /**
+     * The failed keyword. The shared corpus pins THIS rather than the prose:
+     * `error` wording is validator-defined by contract, while the keyword is the
+     * same word in every JSON Schema library.
+     */
+    keyword: string;
+}
+/**
+ * The largest {n,m} bound admitted. RE2 refuses a repeat count over 1000 outright
+ * while the other two engines expand it, so a larger bound is a pattern one SDK
+ * compiles and another does not.
+ */
+/**
+ * The largest {n,m} bound admitted. RE2 refuses a repeat count over 1000 outright while
+ * the other two engines expand it, so a larger bound is a pattern one SDK compiles and
+ * another does not. Exported so the parity suite can hold it against the corpus header:
+ * it and the escape alphabet are the two values that decide which patterns this port
+ * admits, and they were the two the suite did not check.
+ */
+export declare const maxPortableRepeat = 1000;
+/**
+ * isSafeSchemaPattern reports whether a `pattern` uses only constructs all three SDK
+ * languages express identically, and none that make a backtracking engine explode.
+ *
+ * Draft 2020-12 patterns are ECMA-262, and the three SDKs run three different engines
+ * over them. Two distinct failures follow, and this function answers only the first.
+ *
+ * Some constructs one engine cannot express at all — RE2 has no lookaround, this
+ * runtime has no inline flags — so no care at the call site reconciles them and they
+ * are refused here. Others every engine compiles and then reads DIFFERENTLY: `\d` is
+ * Unicode-aware in Python and ASCII here and in RE2, and Python's `$` also matches
+ * before a trailing newline. Those are not refused — they appear in almost every real
+ * pattern — they are corrected in the port that diverges, which is Python.
+ *
+ * The escape rule is an ALLOWLIST rather than a list of the divergent escapes, because
+ * the divergent set is open-ended: two successive reviews found new counterexamples by
+ * trying, which is the signature of a rule stated from the wrong side. The portable set
+ * is small, closed and checkable, and the corpus carries it as data.
+ *
+ * The last rule is about availability rather than agreement: a quantified group whose
+ * body can repeat or branch is refused, because that is what makes backtracking
+ * catastrophic and no timer here could stop one.
+ */
+export declare function isSafeSchemaPattern(pattern: string): boolean;
+/**
+ * A compiled, accepted data_schema. Immutable and safe to share, so a server
+ * compiles the operator's schema once at start-up and a client caches one per
+ * Exchange.
+ */
+export declare class RegistrationSchema {
+    #private;
+    constructor(validate: ValidateFunction);
+    /**
+     * Check a registration_data payload and name what failed. An empty array means
+     * the payload conforms.
+     *
+     * The result is ready for the refusal builder: `path` an RFC 6901 pointer
+     * relative to registration_data ("" addresses the whole object), `error` the
+     * violated CONSTRAINT and never the submitted value.
+     *
+     * The order is deterministic — entries are deduplicated by pointer and keyword,
+     * then sorted by both, before the list is capped. Three validators walk a
+     * failing document in three different orders, so an unsorted list is one no
+     * shared corpus could pin.
+     */
+    validate(data: unknown): RegistrationFieldErrorShape[];
+    /**
+     * The whole answer, keyword included. `validate` narrows it to the wire's
+     * two-field shape; the parity suite reads it whole, because the corpus pins the
+     * keyword while `error` wording is validator-defined by contract.
+     */
+    violations(data: unknown): SchemaViolation[];
+}
+/**
+ * compileRegistrationSchema checks a published data_schema against every rule and
+ * compiles it.
+ *
+ * `raw` is the schema AS SERVED — the exact UTF-8 bytes of the data_schema member
+ * in fora.json — because maxRegistrationSchemaBytes is defined over those bytes.
+ *
+ * The schema is null unless the verdict is "accepted". Nothing throws: every way
+ * this can fail is a property of the schema, and both callers need to know WHICH.
+ * They read the same refusal differently, and that difference is the contract. A
+ * CLIENT pre-checking a payload treats any non-accepted verdict as "do not
+ * pre-check" and sends anyway — the Exchange's enforcement is the deciding one, and
+ * a client that refused here would block a payload the Exchange would have taken.
+ * An EXCHANGE compiling its OWN configured schema treats the same verdict as an
+ * operator misconfiguration, and must not advertise a schema it cannot enforce.
+ */
+export declare function compileRegistrationSchema(raw: Uint8Array | string): {
+    schema: RegistrationSchema | null;
+    verdict: SchemaVerdict;
+};
+/**
+ * maxRegistrationDataBytes bounds a submitted registration_data payload, measured as
+ * its RFC 8785 canonical JSON encoding.
+ *
+ * The UNIT has to be named, and that is the whole point of this constant. Every other
+ * cap in this module is over bytes a party actually served; registration_data is not
+ * served as bytes at all — it arrives as a decoded google.protobuf.Struct — so "16KB"
+ * means nothing until an encoding is chosen, and two implementations choosing privately
+ * is the disagreement this module exists to remove. JCS is the choice because all three
+ * SDKs already compute it for the signing primitive, and because it pins number
+ * formatting: a payload carrying 1e300 is seven bytes to one renderer and three hundred
+ * to another.
+ *
+ * It bounds WORK, not storage. The schema's own caps bound the schema; nothing bounded
+ * the payload the schema is applied to, and validation cost is roughly the schema's cost
+ * multiplied by the elements in the payload — a subschema under `items` is counted once
+ * by maxRegistrationSchemaEvaluations and evaluated once per element.
+ */
+export declare const maxRegistrationDataBytes = 16384;
+/**
+ * maxRegistrationDataMembers bounds the number of members at the TOP LEVEL of a
+ * payload. Top level rather than recursive, deliberately: nested bulk is already bounded
+ * by the byte cap, and a recursive count would refuse a small document that merely
+ * nests, which a business entity legitimately does (an address is an object).
+ */
+export declare const maxRegistrationDataMembers = 64;
+/**
+ * maxRegistrationDataDepth bounds how deeply a submitted registration_data payload may
+ * nest, counting JSON containers so a bare `{}` is depth 1. Same number and same counting
+ * rule as maxRegistrationSchemaDepth, because it is the same question asked of the other
+ * document.
+ *
+ * It exists because without it the ANSWER depended on the reader's runtime rather than on
+ * the payload. Canonicalising walks the payload recursively, and where that walk runs out
+ * of stack differs by language and even by interpreter version — one port refused a
+ * payload past about five hundred containers on one Python and accepted nine hundred on
+ * the next, while this one and Go accepted every depth tried. A static bound checked
+ * first turns that into one verdict every implementation reaches.
+ */
+export declare const maxRegistrationDataDepth = 32;
+/**
+ * RegistrationDataVerdict is the outcome of checking a submitted registration_data
+ * payload. The tokens are the Go oracle's vocabulary verbatim.
+ *
+ * "no_verdict" is Go's zero value and is never returned here; it is in the vocabulary
+ * because the corpus carries the whole vocabulary.
+ */
+export declare const registrationDataVerdicts: readonly ["no_verdict", "accepted", "too_large", "too_many_members", "too_deep", "uncanonicalizable"];
+export type RegistrationDataVerdict = (typeof registrationDataVerdicts)[number];
+/**
+ * checkRegistrationData bounds a submitted registration_data payload.
+ *
+ * `data` is the decoded object. A null/undefined or empty payload is accepted: sending
+ * no business data is a matter for the published schema's `required` list, not for a
+ * size bound.
+ *
+ * This runs BEFORE RegistrationSchema.validate, for the same reason the schema's own
+ * size cap runs before the schema is parsed: the bound exists to stop work, so it has to
+ * precede the work. An Exchange refuses an over-bound payload outright — a malformed
+ * request rather than a schema failure, so NOT
+ * REGISTRATION_FAILURE_REASON_INVALID_REGISTRATION_DATA, which names non-conformance to
+ * a published schema and applies only when one is published.
+ */
+export declare function checkRegistrationData(data: Record<string, unknown> | null | undefined): RegistrationDataVerdict;