@fora-protocol/sdk 1.0.3

package/sdk/ts/resolvers/wellknown.js

@@ -0,0 +1,169 @@
+// The two well-known fetching faces: WellKnownKeyResolver (one fixed JWKS URL,
+// kid-keyed) and WellKnownEndpointResolver (host-keyed fora.json → endpoint).
+// Both port the Go oracle's lazy-fetch + TTL-cache + single-flight coalescing and
+// its fail-closed taxonomy: a fetch/decode failure throws DirectoryUnavailable;
+// an unknown kid is `undefined`; a manifest whose `ver` is not a recognised major
+// (or is absent) throws ManifestVersionRefused before anything else is read — on
+// the endpoint face only, the key face reads a JWKS document that carries no
+// manifest version; a manifest with no endpoint throws NoEndpoint.
+import { endpointRefusal } from "../src/endpoint-rule.js";
+import { invalidHost } from "../src/host-ref.js";
+import { isBareHost } from "../src/hosts.js";
+import { manifestVersionRefusal, WellKnownPath } from "../src/wire.js";
+import { DirectoryUnavailable, EndpointRefused, ManifestVersionRefused, NoEndpoint } from "./errors.js";
+import { defaultFetch, fetchStrict } from "./http.js";
+import { ed25519KeysFromJwks } from "./jwks.js";
+const DEFAULT_TTL_MS = 300_000; // 5 minutes
+/** Lazily fetch the JWKS at `url`, cache resolved keys with a TTL. */
+export function createWellKnownKeyResolver(url, opts = {}) {
+    return new KeyResolverImpl(url, opts);
+}
+/** Host-keyed resolver of an Exchange domain → its self-advertised endpoint. */
+export function createWellKnownEndpointResolver(opts = {}) {
+    return new EndpointResolverImpl(opts);
+}
+class KeyResolverImpl {
+    url;
+    fetchFn;
+    ttlMs;
+    now;
+    allow;
+    cache = new Map();
+    cacheExp = 0;
+    inflight;
+    constructor(url, opts) {
+        this.url = url;
+        this.fetchFn = opts.fetch ?? defaultFetch;
+        this.ttlMs = opts.ttlMs && opts.ttlMs > 0 ? opts.ttlMs : DEFAULT_TTL_MS;
+        this.now = opts.now ?? Date.now;
+        this.allow = opts.allow;
+    }
+    async resolve(keyid) {
+        if (this.allow && !this.allow(keyid))
+            return undefined;
+        const hit = this.cachedKey(keyid);
+        if (hit)
+            return hit;
+        await this.refresh();
+        return this.cachedKey(keyid);
+    }
+    cachedKey(keyid) {
+        if (this.now() > this.cacheExp)
+            return undefined;
+        return this.cache.get(keyid);
+    }
+    async refresh() {
+        if (this.now() <= this.cacheExp)
+            return; // another refresh won the race
+        if (this.inflight)
+            return this.inflight;
+        this.inflight = this.doRefresh();
+        try {
+            await this.inflight;
+        }
+        finally {
+            this.inflight = undefined;
+        }
+    }
+    async doRefresh() {
+        const body = await fetchStrict(this.fetchFn, this.url);
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch (err) {
+            throw new DirectoryUnavailable(`jwks decode ${this.url}`, { cause: err });
+        }
+        this.cache = ed25519KeysFromJwks(parsed);
+        this.cacheExp = this.now() + this.ttlMs;
+    }
+}
+class EndpointResolverImpl {
+    fetchFn;
+    ttlMs;
+    now;
+    scheme;
+    allow;
+    cache = new Map();
+    flight = new Map();
+    constructor(opts) {
+        this.fetchFn = opts.fetch ?? defaultFetch;
+        this.ttlMs = opts.ttlMs && opts.ttlMs > 0 ? opts.ttlMs : DEFAULT_TTL_MS;
+        this.now = opts.now ?? Date.now;
+        this.scheme = opts.scheme && opts.scheme !== "" ? opts.scheme : "https";
+        this.allow = opts.allow;
+    }
+    async resolveEndpoint(host) {
+        // Checked BEFORE the allow overlay and before the cache. The fetch URL is
+        // built by concatenation, so a value carrying a path or a query would choose
+        // WHAT gets fetched rather than merely where from — and the raw string is the
+        // cache key, so admitting one would also put it in a shared map.
+        // A fault in the CALLER's value, not a verdict on the Exchange's answer, so
+        // it is the same invalid-host error isBareHost itself throws for a reference
+        // it cannot read at all — the oracle uses one sentinel across both branches
+        // here for the same reason. EndpointRefused stays what it says: the manifest
+        // was read and its answer is unusable.
+        //
+        // Built by the shared constructor rather than by hand. A value that PARSES and
+        // carries a credential — user:pass@exchange.example — reaches this branch
+        // rather than the throwing one, so a message written out here is the one path
+        // into these refusals that would name the credential.
+        if (!isBareHost(host)) {
+            throw invalidHost(host, "not a bare host");
+        }
+        if (this.allow && !this.allow(host))
+            throw new NoEndpoint(`host ${host} not allowed`);
+        const hit = this.cached(host);
+        if (hit !== undefined)
+            return hit;
+        let flight = this.flight.get(host);
+        if (!flight) {
+            flight = this.fetchEndpoint(host);
+            this.flight.set(host, flight);
+        }
+        try {
+            return await flight;
+        }
+        finally {
+            this.flight.delete(host);
+        }
+    }
+    cached(host) {
+        const entry = this.cache.get(host);
+        if (!entry || this.now() > entry.exp)
+            return undefined;
+        return entry.endpoint;
+    }
+    async fetchEndpoint(host) {
+        const hit = this.cached(host);
+        if (hit !== undefined)
+            return hit; // filled while we queued behind the flight lock
+        const url = `${this.scheme}://${host}${WellKnownPath}`;
+        const body = await fetchStrict(this.fetchFn, url);
+        let doc;
+        try {
+            doc = JSON.parse(body);
+        }
+        catch (err) {
+            throw new DirectoryUnavailable(`manifest decode ${url}`, { cause: err });
+        }
+        // The document version gate runs before the endpoint is so much as looked
+        // at, and never caches: the next resolve fetches again.
+        const versionRefusal = manifestVersionRefusal(doc?.ver);
+        if (versionRefusal !== undefined) {
+            throw new ManifestVersionRefused(versionRefusal);
+        }
+        const endpoint = doc.endpoint;
+        if (typeof endpoint !== "string" || endpoint === "") {
+            throw new NoEndpoint(`host=${host}`);
+        }
+        // Vetted BEFORE it is cached, so a refused endpoint is not held for the TTL
+        // and then served to every later caller out of memory.
+        const refusal = endpointRefusal(host, endpoint);
+        if (refusal !== undefined) {
+            throw new EndpointRefused(refusal);
+        }
+        this.cache.set(host, { endpoint, exp: this.now() + this.ttlMs });
+        return endpoint;
+    }
+}

package/sdk/ts/src/acceptance.d.ts

@@ -0,0 +1,46 @@
+/** The JOSE/JWA algorithm identifier advertised on AgentAcceptance.signature. Always EdDSA for Ed25519
+ * (mirror helpers.AcceptanceSignatureAlgorithm). */
+export declare const ACCEPTANCE_SIGNATURE_ALGORITHM = "EdDSA";
+/** The acceptance binding fields. EVERY empty field is omitted from the canonical
+ * payload, not only requesterDomain (proto omit-unpopulated) — so an empty value and
+ * an absent one sign the same bytes, and neither signs the bytes of a populated one.
+ * An empty offerSig is rejected fail-closed — an empty anchor would let the
+ * acceptance float free of any concrete offer. */
+export interface AcceptanceInput {
+    offerSig: string;
+    requesterId: string;
+    requesterDomain: string;
+    idempotencyKey: string;
+}
+/**
+ * acceptancePayload reproduces the canonical signed bytes:
+ * JCS(protojson(AgentAcceptancePayload)) with EVERY empty string field omitted.
+ * Throws on an empty offer signature (fail-closed, mirror Go
+ * CanonicalAcceptanceBytes / Python jcs_acceptance_payload).
+ */
+export declare function acceptancePayload(input: AcceptanceInput): Uint8Array<ArrayBuffer>;
+/**
+ * signOfferAcceptance signs the canonical acceptance payload with the agent's
+ * Ed25519 private key and returns the hex signature for AgentAcceptance.signature.
+ */
+export declare function signOfferAcceptance(input: AcceptanceInput, privateKey: CryptoKey): Promise<string>;
+/**
+ * verifyOfferAcceptance verifies a hex acceptance signature over the canonical
+ * payload with the agent's Ed25519 public key. Returns false (never throws) on a
+ * bad binding, a bad key, or an unsigned offer.
+ */
+export declare function verifyOfferAcceptance(input: AcceptanceInput, signatureHex: string, publicKey: CryptoKey): Promise<boolean>;
+export interface RequestAcceptanceItemInput {
+    offerSig: string;
+    exchange: string;
+}
+export interface RequestAcceptanceInput {
+    items: RequestAcceptanceItemInput[];
+    requesterId: string;
+    requesterDomain: string;
+    idempotencyKey: string;
+}
+/** Canonical JCS(protojson(...)) bytes for the complete ordered execute set. */
+export declare function requestAcceptancePayload(input: RequestAcceptanceInput): Uint8Array<ArrayBuffer>;
+export declare function signRequestAcceptance(input: RequestAcceptanceInput, privateKey: CryptoKey): Promise<string>;
+export declare function verifyRequestAcceptance(input: RequestAcceptanceInput, signatureHex: string, publicKey: CryptoKey): Promise<boolean>;

package/sdk/ts/src/acceptance.js

@@ -0,0 +1,162 @@
+// sdk/ts offer-acceptance sign/verify face — the AGENT-role acceptance surface,
+// mirror of Go helpers.SignOfferAcceptance / VerifyOfferAcceptance and Python
+// core.sign_offer_acceptance_jcs / verify_offer_acceptance_jcs.
+//
+// An agent signs a DETACHED, content-bound acceptance over an accepted Offer;
+// the Exchange verifies it to bind the agent to the transaction. Unlike the
+// transport RFC 9421 request signature, the acceptance is topology-independent:
+// it stays valid no matter how many brokers relay the request, because it covers
+// the offer signature + requester + idempotency, not the HTTP envelope.
+//
+// The signed bytes are JCS(protojson(AgentAcceptancePayload)) — snake_case,
+// omit-unpopulated — the SAME primitive the offer signature uses, so every
+// language reproduces the exact bytes. Ed25519 is deterministic (RFC 8032), so a
+// given (payload, key) always yields the same signature; the parity suite pins
+// the TS output byte-identical to the Go oracle.
+//
+// WebCrypto is the crypto primitive (the same one the L1 pop/verify faces use);
+// the caller supplies the imported CryptoKey, exactly as core/sign.ts does.
+import canonicalize from "canonicalize";
+import { utf8Bytes } from "./base64url.js";
+/** The JOSE/JWA algorithm identifier advertised on AgentAcceptance.signature. Always EdDSA for Ed25519
+ * (mirror helpers.AcceptanceSignatureAlgorithm). */
+export const ACCEPTANCE_SIGNATURE_ALGORITHM = "EdDSA";
+// Strict about what a hex digit is, and about the length. Number.parseInt accepts a sign,
+// leading whitespace and a trailing tail — "-1", "+f" and " a" all produce a number — so a
+// signature carrying any of them would decode to bytes rather than being refused, where
+// Go's hex.DecodeString and Python's bytes.fromhex refuse it. An odd length used to
+// truncate silently. The value comes from a peer, so the three languages have to agree on
+// what is a signature and what is garbage.
+const HEX_PAIR = /^[0-9a-fA-F]{2}$/;
+function hexToBytes(hex) {
+    if (hex.length % 2 !== 0)
+        return undefined;
+    const out = new Uint8Array(hex.length / 2);
+    for (let i = 0; i < out.length; i += 1) {
+        const pair = hex.slice(i * 2, i * 2 + 2);
+        if (!HEX_PAIR.test(pair))
+            return undefined;
+        out[i] = Number.parseInt(pair, 16);
+    }
+    return out;
+}
+function bytesToHex(bytes) {
+    let hex = "";
+    for (const b of bytes)
+        hex += b.toString(16).padStart(2, "0");
+    return hex;
+}
+/**
+ * acceptancePayload reproduces the canonical signed bytes:
+ * JCS(protojson(AgentAcceptancePayload)) with EVERY empty string field omitted.
+ * Throws on an empty offer signature (fail-closed, mirror Go
+ * CanonicalAcceptanceBytes / Python jcs_acceptance_payload).
+ */
+export function acceptancePayload(input) {
+    if (input.offerSig === "") {
+        throw new Error("fora/acceptance: cannot accept an unsigned offer (empty offer signature)");
+    }
+    // proto omit-unpopulated: every empty string field is absent before JCS. The Go
+    // oracle gets that structurally from EmitUnpopulated=false; this record is
+    // hand-built, so the omission is applied once over the whole record rather than
+    // per key. A per-key guard is how the rule went missing for requester_id --
+    // wire-valid, since Requester.id carries no min_len -- which signed bytes Go never
+    // produces. The filter tests for the empty STRING, which covers every member
+    // AgentAcceptancePayload has (the field-set guard in the Go suite pins that list),
+    // so a string field added to the message cannot arrive without its omission. A
+    // non-string field would need its own zero-value test.
+    const payload = {
+        offer_sig: input.offerSig,
+        requester_id: input.requesterId,
+        requester_domain: input.requesterDomain,
+        idempotency_key: input.idempotencyKey,
+    };
+    const obj = Object.fromEntries(Object.entries(payload).filter(([, v]) => v !== ""));
+    const jcs = canonicalize(obj);
+    if (jcs === undefined) {
+        throw new Error("fora/acceptance: payload is not JSON-serializable");
+    }
+    return utf8Bytes(jcs);
+}
+/**
+ * signOfferAcceptance signs the canonical acceptance payload with the agent's
+ * Ed25519 private key and returns the hex signature for AgentAcceptance.signature.
+ */
+export async function signOfferAcceptance(input, privateKey) {
+    const payload = acceptancePayload(input);
+    const sig = new Uint8Array(await crypto.subtle.sign("Ed25519", privateKey, payload));
+    return bytesToHex(sig);
+}
+/**
+ * verifyOfferAcceptance verifies a hex acceptance signature over the canonical
+ * payload with the agent's Ed25519 public key. Returns false (never throws) on a
+ * bad binding, a bad key, or an unsigned offer.
+ */
+export async function verifyOfferAcceptance(input, signatureHex, publicKey) {
+    let payload;
+    try {
+        payload = acceptancePayload(input);
+    }
+    catch {
+        return false;
+    }
+    const signature = hexToBytes(signatureHex);
+    if (signature === undefined)
+        return false;
+    try {
+        return await crypto.subtle.verify("Ed25519", publicKey, signature, payload);
+    }
+    catch {
+        return false;
+    }
+}
+/** Canonical JCS(protojson(...)) bytes for the complete ordered execute set. */
+export function requestAcceptancePayload(input) {
+    if (input.items.length === 0) {
+        throw new Error("fora/acceptance: request acceptance requires at least one item");
+    }
+    const items = input.items.map((item, index) => {
+        if (item.offerSig === "") {
+            throw new Error(`fora/acceptance: request item ${index} has an empty offer signature`);
+        }
+        if (item.exchange === "") {
+            throw new Error(`fora/acceptance: request item ${index} has an empty exchange`);
+        }
+        return { offer_sig: item.offerSig, exchange: item.exchange };
+    });
+    const payload = {
+        items,
+        requester_id: input.requesterId,
+        requester_domain: input.requesterDomain,
+        idempotency_key: input.idempotencyKey,
+    };
+    const obj = Object.fromEntries(Object.entries(payload).filter(([, value]) => value !== ""));
+    const jcs = canonicalize(obj);
+    if (jcs === undefined) {
+        throw new Error("fora/acceptance: request payload is not JSON-serializable");
+    }
+    return utf8Bytes(jcs);
+}
+export async function signRequestAcceptance(input, privateKey) {
+    const payload = requestAcceptancePayload(input);
+    const sig = new Uint8Array(await crypto.subtle.sign("Ed25519", privateKey, payload));
+    return bytesToHex(sig);
+}
+export async function verifyRequestAcceptance(input, signatureHex, publicKey) {
+    let payload;
+    try {
+        payload = requestAcceptancePayload(input);
+    }
+    catch {
+        return false;
+    }
+    const signature = hexToBytes(signatureHex);
+    if (signature === undefined)
+        return false;
+    try {
+        return await crypto.subtle.verify("Ed25519", publicKey, signature, payload);
+    }
+    catch {
+        return false;
+    }
+}

package/sdk/ts/src/base64url.d.ts

@@ -0,0 +1,19 @@
+/** Decode a base64url (or std-base64) string to bytes, or `undefined` on error.
+ * Typed `Uint8Array<ArrayBuffer>` (never SharedArrayBuffer-backed) so decoded
+ * bytes satisfy WebCrypto's BufferSource without casts. */
+export declare function decodeBase64Url(input: string): Uint8Array<ArrayBuffer> | undefined;
+/** Strict base64url decode for JWK OKP `x` key material (RFC 8037: key material
+ * MUST be unpadded base64url). Rejects `=` padding and the standard (`+`/`/`)
+ * alphabet that {@link decodeBase64Url} silently tolerates, mirroring Go's
+ * `base64.RawURLEncoding` byte-for-byte so the tri-language WBA active-key
+ * selector / thumbprint resolver picks the SAME key on a directory holding a
+ * standard-alphabet or padded `x`. Returns `undefined` on any non-urlsafe
+ * character, `=` padding, or an invalid unpadded length (`len % 4 === 1`). */
+export declare function decodeBase64UrlStrict(input: string): Uint8Array<ArrayBuffer> | undefined;
+/** UTF-8 encode, pinned ArrayBuffer-backed. TextEncoder.encode always allocates
+ * a fresh ArrayBuffer, but some lib typings widen the return to ArrayBufferLike;
+ * pin it once here so consumers on any TS/lib version feed WebCrypto without
+ * casts of their own. */
+export declare function utf8Bytes(s: string): Uint8Array<ArrayBuffer>;
+/** Encode bytes as base64url with no padding. */
+export declare function encodeBase64Url(bytes: Uint8Array): string;

package/sdk/ts/src/base64url.js

@@ -0,0 +1,55 @@
+// base64url codec — the shared byte primitive under the thumbprint, signed-URL,
+// and PoP helpers. Relocated verbatim from the app edge (src/edge/src/verify.ts)
+// so the SDK's canonical encodings stay byte-identical to the wire contract the
+// sdk/go oracle emits.
+//
+// The decoder accepts both url- and std-alphabet input (it remaps `-_` -> `+/`
+// and pads), so an RFC 9421 Signature header — which carries STANDARD base64 —
+// decodes correctly through the same path (the remap is a no-op on std input).
+/** Decode a base64url (or std-base64) string to bytes, or `undefined` on error.
+ * Typed `Uint8Array<ArrayBuffer>` (never SharedArrayBuffer-backed) so decoded
+ * bytes satisfy WebCrypto's BufferSource without casts. */
+export function decodeBase64Url(input) {
+    const pad = input.length % 4 === 0 ? "" : "=".repeat(4 - (input.length % 4));
+    const b64 = input.replaceAll("-", "+").replaceAll("_", "/") + pad;
+    try {
+        const bin = atob(b64);
+        const out = new Uint8Array(bin.length);
+        for (let i = 0; i < bin.length; i += 1)
+            out[i] = bin.charCodeAt(i);
+        return out;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Strict base64url decode for JWK OKP `x` key material (RFC 8037: key material
+ * MUST be unpadded base64url). Rejects `=` padding and the standard (`+`/`/`)
+ * alphabet that {@link decodeBase64Url} silently tolerates, mirroring Go's
+ * `base64.RawURLEncoding` byte-for-byte so the tri-language WBA active-key
+ * selector / thumbprint resolver picks the SAME key on a directory holding a
+ * standard-alphabet or padded `x`. Returns `undefined` on any non-urlsafe
+ * character, `=` padding, or an invalid unpadded length (`len % 4 === 1`). */
+export function decodeBase64UrlStrict(input) {
+    if (!/^[A-Za-z0-9_-]*$/.test(input))
+        return undefined;
+    if (input.length % 4 === 1)
+        return undefined;
+    // Input is now guaranteed unpadded url-alphabet, so the lenient path decodes it
+    // exactly (its `-_`->`+/` remap + re-pad is the identity transform here).
+    return decodeBase64Url(input);
+}
+/** UTF-8 encode, pinned ArrayBuffer-backed. TextEncoder.encode always allocates
+ * a fresh ArrayBuffer, but some lib typings widen the return to ArrayBufferLike;
+ * pin it once here so consumers on any TS/lib version feed WebCrypto without
+ * casts of their own. */
+export function utf8Bytes(s) {
+    return new TextEncoder().encode(s);
+}
+/** Encode bytes as base64url with no padding. */
+export function encodeBase64Url(bytes) {
+    let bin = "";
+    for (let i = 0; i < bytes.length; i += 1)
+        bin += String.fromCharCode(bytes[i]);
+    return btoa(bin).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/, "");
+}

package/sdk/ts/src/crossfield.d.ts

@@ -0,0 +1,28 @@
+import { z } from "zod";
+import { GetAccountStatusResponseSchema, LicenseSchema, LicenseTermSchema, ObligationSchema, PricingSchema, RegistrationFailureSchema, RestrictionSchema, WellKnownManifestSchema } from "../../../gen/ts/wire/schemas.ts";
+/** Stable rule-id carried on each cross-field Zod issue via params.ruleId. */
+export interface CrossFieldIssueParams {
+    ruleId: string;
+}
+/**
+ * crossFieldRuleIds returns the cross-field (message-CEL) rule-ids the instance
+ * violates, empty when it passes cross-field validation. Direct analogue of the
+ * Go oracle's ValidationRuleIDs(err) over the crossfield corpus.
+ */
+export declare function crossFieldRuleIds(message: string, json: unknown): string[];
+/**
+ * The cross-field composition of a generated schema: exactly what `superRefine`
+ * returns on it. Spelled as the method's own return type, not as a Zod class,
+ * so the published declaration holds under both supported majors — Zod 3 returns
+ * a ZodEffects wrapper, Zod 4 returns the schema's own class — while keeping the
+ * schema's output and input inference.
+ */
+export type CrossField<T extends z.ZodTypeAny> = ReturnType<T["superRefine"]>;
+export declare const GetAccountStatusResponseCrossFieldSchema: CrossField<typeof GetAccountStatusResponseSchema>;
+export declare const LicenseCrossFieldSchema: CrossField<typeof LicenseSchema>;
+export declare const LicenseTermCrossFieldSchema: CrossField<typeof LicenseTermSchema>;
+export declare const ObligationCrossFieldSchema: CrossField<typeof ObligationSchema>;
+export declare const PricingCrossFieldSchema: CrossField<typeof PricingSchema>;
+export declare const RestrictionCrossFieldSchema: CrossField<typeof RestrictionSchema>;
+export declare const RegistrationFailureCrossFieldSchema: CrossField<typeof RegistrationFailureSchema>;
+export declare const WellKnownManifestCrossFieldSchema: CrossField<typeof WellKnownManifestSchema>;