@fora-protocol/sdk 1.0.3

package/sdk/ts/src/licenseterm.js

@@ -0,0 +1,433 @@
+// License-term canonicalisation and the ingest-tier checks — TS port of the
+// sdk/go oracle (helpers/licenseterm.go), pinned to the shared
+// licenseterm-vectors.json.
+//
+// A pushed entry passes two tiers at the Exchange. The wire tier is the
+// generated field-level schema plus the cross-field (message-CEL) rules,
+// applied to the entry as received. The ingest tier runs over the CANONICALISED
+// terms: restriction tokens are folded and alias-resolved to their registered
+// form, then a bare Pricing.unit or Quota.metric that is not a registered token
+// is rejected, as is a restriction whose permitted and prohibited lists name one
+// token once folded, while an unregistered restriction token and an
+// OBLIGATION_KIND_OTHER obligation without detail are accepted with a warning
+// that reaches PushResourcesResponse.warnings. The Exchange's own run is the
+// deciding one; a client-side verdict is advice about what that run will say.
+//
+// Folding is ASCII-only and only RFC 8259 whitespace is trimmed — a platform
+// Unicode fold turns U+212A KELVIN SIGN into "k" and a homograph into a
+// registered token. Messages are the exact strings the Go oracle emits, which
+// are the strings an Exchange puts on the wire.
+import { JSON_NAME_ALIAS_ERROR, WireNamingError, underWirePolicy, } from "../../../gen/ts/wire/base.js";
+import { ResourceEntrySchema } from "../../../gen/ts/wire/schemas.js";
+import * as functiontokens from "../../../gen/ts/vocab/functiontokens.js";
+import * as geographytokens from "../../../gen/ts/vocab/geographytokens.js";
+import * as pricingunits from "../../../gen/ts/vocab/pricingunits.js";
+import * as quotametrics from "../../../gen/ts/vocab/quotametrics.js";
+import * as usertypes from "../../../gen/ts/vocab/usertypes.js";
+import { crossFieldRuleIds } from "./crossfield.js";
+/** Rejects a bare (non-namespaced) Pricing.unit that is not a registered metering token. */
+export const RULE_PRICING_UNIT_REGISTERED = "pricing.unit.registered";
+/** Rejects a bare Quota.metric that is not a registered quota token. */
+export const RULE_QUOTA_METRIC_REGISTERED = "quota.metric.registered";
+/**
+ * Rejects a restriction whose permitted and prohibited lists name the same token
+ * once both are canonicalised. The wire tier's rule compares the tokens AS
+ * WRITTEN, so two accepted spellings of one token — an alias beside its
+ * registered form, or two spellings differing only in ASCII case — pass it and
+ * collide only after the fold.
+ */
+export const RULE_RESTRICTION_CANONICAL_DISJOINT = "restriction.canonical_disjoint";
+/** Warns about a bare restriction token not registered on its axis; the term is accepted. */
+export const RULE_RESTRICTION_TOKEN_REGISTERED = "restriction.token.registered";
+/** Warns about an OBLIGATION_KIND_OTHER obligation carrying no detail. */
+export const RULE_OBLIGATION_OTHER_REQUIRES_DETAIL = "obligation.other.requires_detail";
+const KIND_FUNCTION = "RESTRICTION_KIND_FUNCTION";
+const KIND_GEOGRAPHY = "RESTRICTION_KIND_GEOGRAPHY";
+const KIND_USER_TYPE = "RESTRICTION_KIND_USER_TYPE";
+// The enum's zero, as the oracle spells it when a restriction carries no kind.
+const KIND_UNSPECIFIED = "RESTRICTION_KIND_UNSPECIFIED";
+const OBLIGATION_KIND_OTHER = "OBLIGATION_KIND_OTHER";
+function asObj(v) {
+    return typeof v === "object" && v !== null && !Array.isArray(v) ? v : undefined;
+}
+function asArr(v) {
+    return Array.isArray(v) ? v : [];
+}
+function str(v) {
+    return typeof v === "string" ? v : "";
+}
+function isJSONWhitespace(c) {
+    return c === " " || c === "\t" || c === "\n" || c === "\r";
+}
+// The four RFC 8259 whitespace characters and nothing else, so a token padded
+// with a non-breaking space stays padded, in every language.
+function trimJSONWhitespace(s) {
+    let start = 0;
+    let end = s.length;
+    while (start < end && isJSONWhitespace(s.charAt(start)))
+        start++;
+    while (end > start && isJSONWhitespace(s.charAt(end - 1)))
+        end--;
+    return s.slice(start, end);
+}
+// ASCII letters only — no flag on the class, so no Unicode case folding.
+function asciiLower(s) {
+    return s.replace(/[A-Z]/g, (c) => String.fromCharCode(c.charCodeAt(0) + 32));
+}
+function asciiUpper(s) {
+    return s.replace(/[a-z]/g, (c) => String.fromCharCode(c.charCodeAt(0) - 32));
+}
+function hasCanonicalRule(kind) {
+    return kind === KIND_FUNCTION || kind === KIND_USER_TYPE || kind === KIND_GEOGRAPHY;
+}
+function isNamespacedToken(token) {
+    return token.includes(":");
+}
+// Two uppercase ASCII letters — the structural shape of an ISO 3166-1 alpha-2
+// code, which the geography registry deliberately does not enumerate.
+function isISOAlpha2(token) {
+    if (token.length !== 2)
+        return false;
+    const a = token.charCodeAt(0);
+    const b = token.charCodeAt(1);
+    return a >= 65 && a <= 90 && b >= 65 && b <= 90;
+}
+/**
+ * canonicalRestrictionToken returns the canonical form of a restriction token
+ * on an axis (`kind` is the RestrictionKind enum NAME): RFC 8259 whitespace
+ * trimmed, ASCII case folded (lower for FUNCTION and USER_TYPE, upper for
+ * GEOGRAPHY) and, where the axis authors aliases, the alias resolved to its
+ * registered token. OTHER and any unknown axis are returned unchanged.
+ * Applying it twice is a fixed point.
+ */
+export function canonicalRestrictionToken(kind, token) {
+    switch (kind) {
+        case KIND_FUNCTION:
+            return functiontokens.canonical(asciiLower(trimJSONWhitespace(token)));
+        case KIND_USER_TYPE:
+            return usertypes.canonical(asciiLower(trimJSONWhitespace(token)));
+        case KIND_GEOGRAPHY:
+            return geographytokens.canonical(asciiUpper(trimJSONWhitespace(token)));
+        default:
+            return token;
+    }
+}
+/**
+ * knownRestrictionToken reports whether an already-canonical token is
+ * registered on its axis. GEOGRAPHY admits the registered specials and any
+ * two-uppercase-letter ISO 3166-1 alpha-2 code; OTHER and unknown axes never.
+ */
+export function knownRestrictionToken(kind, token) {
+    switch (kind) {
+        case KIND_FUNCTION:
+            return functiontokens.isRegistered(token);
+        case KIND_USER_TYPE:
+            return usertypes.isRegistered(token);
+        case KIND_GEOGRAPHY:
+            return geographytokens.isRegistered(token) || isISOAlpha2(token);
+        default:
+            return false;
+    }
+}
+function canonicalizeTokens(kind, tokens) {
+    if (!Array.isArray(tokens))
+        return tokens;
+    return tokens.map((t) => (typeof t === "string" ? canonicalRestrictionToken(kind, t) : t));
+}
+/**
+ * normalizeLicenseTerm returns a deep copy of the term (proto-JSON, snake_case)
+ * with its restriction tokens rewritten to canonical form on every axis that
+ * carries a canonicalisation rule. Nothing else moves. The input is untouched;
+ * the Go oracle rewrites in place, and the corpus pins the output either way.
+ */
+export function normalizeLicenseTerm(term) {
+    const out = structuredClone(term);
+    for (const r of asArr(out["restrictions"])) {
+        const restriction = asObj(r);
+        if (!restriction)
+            continue;
+        const kind = str(restriction["kind"]);
+        if (!hasCanonicalRule(kind))
+            continue;
+        if (restriction["permitted"] !== undefined) {
+            restriction["permitted"] = canonicalizeTokens(kind, restriction["permitted"]);
+        }
+        if (restriction["prohibited"] !== undefined) {
+            restriction["prohibited"] = canonicalizeTokens(kind, restriction["prohibited"]);
+        }
+    }
+    return out;
+}
+/** normalizeResourceEntry returns a deep copy with every term normalised. */
+export function normalizeResourceEntry(entry) {
+    const out = structuredClone(entry);
+    const terms = asArr(out["terms"]);
+    if (terms.length) {
+        out["terms"] = terms.map((t) => {
+            const term = asObj(t);
+            return term ? normalizeLicenseTerm(term) : t;
+        });
+    }
+    return out;
+}
+function bareUnregistered(token, registered) {
+    if (token === "" || isNamespacedToken(token))
+        return false;
+    return !registered(token);
+}
+function restrictionTokenWarning(kind, tok, path) {
+    if (tok === "" || isNamespacedToken(tok) || knownRestrictionToken(kind, tok))
+        return undefined;
+    return {
+        rule: RULE_RESTRICTION_TOKEN_REGISTERED,
+        path,
+        token: tok,
+        // An absent kind is the enum's zero, and the oracle names it: Go formats the
+        // enum, which spells the unset value rather than leaving a gap. These strings
+        // are the exact bytes an Exchange puts in warnings[], so a doubled space here
+        // is a real difference in what a publisher is told, not a rendering detail.
+        message: `unregistered ${kind || KIND_UNSPECIFIED} restriction token "${tok}" (term accepted)`,
+    };
+}
+/**
+ * canonicalDisjointViolation returns the violation for the first permitted token
+ * of r whose canonical form is also the canonical form of one of its prohibited
+ * tokens, or undefined when the two lists name no token in common. It
+ * canonicalises what it compares rather than trusting the term to have been
+ * normalised, and it runs on every axis — where the fold is a no-op the check is
+ * plain equality, which is what a server that never asked for the wire tier
+ * needs. The finding names the canonical token, not the spellings that produced
+ * it, so the message does not depend on whether the caller folded first.
+ *
+ * An element that is not a string is SKIPPED rather than coerced. Coercing it to ""
+ * would report two ill-typed elements as a collision on the empty token, which names
+ * the wrong fault; the wire tier already refuses a non-string where the schema says
+ * string, the same division this file applies to an empty or namespaced token. Two
+ * genuinely empty strings still collide, which is what the Go oracle answers.
+ */
+function canonicalDisjointViolation(i, r) {
+    const permitted = asArr(r["permitted"]);
+    const prohibited = asArr(r["prohibited"]);
+    if (permitted.length === 0 || prohibited.length === 0)
+        return undefined;
+    const kind = str(r["kind"]);
+    const banned = new Set(prohibited.filter((t) => typeof t === "string").map((t) => canonicalRestrictionToken(kind, t)));
+    for (let j = 0; j < permitted.length; j++) {
+        const tok = permitted[j];
+        if (typeof tok !== "string")
+            continue;
+        const canon = canonicalRestrictionToken(kind, tok);
+        if (!banned.has(canon))
+            continue;
+        return {
+            rule: RULE_RESTRICTION_CANONICAL_DISJOINT,
+            path: `restrictions[${i}].permitted[${j}]`,
+            token: canon,
+            message: `restriction token "${canon}" is both permitted and prohibited after canonicalisation`,
+        };
+    }
+    return undefined;
+}
+/**
+ * validateLicenseTerm runs the ingest-tier checks over one term, in a fixed
+ * order: a bare Pricing.unit that is not registered, then the first offending
+ * quota metric, then the first restriction whose permitted and prohibited lists
+ * name one token once canonicalised. An accepted term carries one warning per
+ * unregistered bare restriction token — restriction order, permitted before
+ * prohibited — then one per OBLIGATION_KIND_OTHER obligation without detail.
+ *
+ * Every check but the disjointness one reads the term as already canonical. The
+ * wire tier is not re-run here; disjointness is the one property both tiers
+ * assert, over different values, so a term the boundary clears can still fail
+ * here.
+ */
+export function validateLicenseTerm(term) {
+    const unit = str(asObj(term["pricing"])?.["unit"]);
+    if (bareUnregistered(unit, pricingunits.isRegistered)) {
+        return {
+            violation: {
+                rule: RULE_PRICING_UNIT_REGISTERED,
+                path: "pricing.unit",
+                token: unit,
+                message: `pricing unit "${unit}" is not a registered metering token`,
+            },
+            warnings: [],
+        };
+    }
+    const quotas = asArr(term["quotas"]);
+    for (let i = 0; i < quotas.length; i++) {
+        const metric = str(asObj(quotas[i])?.["metric"]);
+        if (bareUnregistered(metric, quotametrics.isRegistered)) {
+            return {
+                violation: {
+                    rule: RULE_QUOTA_METRIC_REGISTERED,
+                    path: `quotas[${i}].metric`,
+                    token: metric,
+                    message: `quota metric "${metric}" is not a registered quota token`,
+                },
+                warnings: [],
+            };
+        }
+    }
+    const restrictions = asArr(term["restrictions"]);
+    for (let i = 0; i < restrictions.length; i++) {
+        const r = asObj(restrictions[i]);
+        if (!r)
+            continue;
+        const violation = canonicalDisjointViolation(i, r);
+        if (violation)
+            return { violation, warnings: [] };
+    }
+    const warnings = [];
+    for (let i = 0; i < restrictions.length; i++) {
+        const r = asObj(restrictions[i]);
+        if (!r)
+            continue;
+        const kind = str(r["kind"]);
+        const permitted = asArr(r["permitted"]);
+        for (let j = 0; j < permitted.length; j++) {
+            const w = restrictionTokenWarning(kind, str(permitted[j]), `restrictions[${i}].permitted[${j}]`);
+            if (w)
+                warnings.push(w);
+        }
+        const prohibited = asArr(r["prohibited"]);
+        for (let j = 0; j < prohibited.length; j++) {
+            const w = restrictionTokenWarning(kind, str(prohibited[j]), `restrictions[${i}].prohibited[${j}]`);
+            if (w)
+                warnings.push(w);
+        }
+    }
+    const obligations = asArr(term["obligations"]);
+    for (let i = 0; i < obligations.length; i++) {
+        const o = asObj(obligations[i]);
+        if (!o)
+            continue;
+        if (str(o["kind"]) === OBLIGATION_KIND_OTHER && str(o["detail"]) === "") {
+            warnings.push({
+                rule: RULE_OBLIGATION_OTHER_REQUIRES_DETAIL,
+                path: `obligations[${i}].detail`,
+                token: "",
+                message: "obligation of kind OTHER has no detail (term accepted)",
+            });
+        }
+    }
+    return { violation: null, warnings };
+}
+// Zod 3 types an issue path as (string | number)[]; Zod 4 widens it to PropertyKey[].
+// A symbol segment cannot occur on a JSON document, so it is rendered by name.
+function zodPath(path) {
+    let out = "";
+    for (const seg of path) {
+        if (typeof seg === "number")
+            out += `[${seg}]`;
+        else
+            out = out === "" ? String(seg) : `${out}.${String(seg)}`;
+    }
+    return out;
+}
+// Every message instance reachable from an entry that carries a cross-field
+// rule, with its entry-relative path. The generated schema is field-level and
+// the composed cross-field schemas attach per message, so the walk is explicit.
+function crossFieldSites(entry) {
+    const sites = [];
+    const terms = asArr(entry["terms"]);
+    for (let i = 0; i < terms.length; i++) {
+        const term = asObj(terms[i]);
+        if (!term)
+            continue;
+        const base = `terms[${i}]`;
+        sites.push({ path: base, message: "LicenseTerm", value: term });
+        if (term["license"] !== undefined)
+            sites.push({ path: `${base}.license`, message: "License", value: term["license"] });
+        if (term["pricing"] !== undefined)
+            sites.push({ path: `${base}.pricing`, message: "Pricing", value: term["pricing"] });
+        const restrictions = asArr(term["restrictions"]);
+        for (let j = 0; j < restrictions.length; j++) {
+            sites.push({ path: `${base}.restrictions[${j}]`, message: "Restriction", value: restrictions[j] });
+        }
+        const obligations = asArr(term["obligations"]);
+        for (let k = 0; k < obligations.length; k++) {
+            const o = asObj(obligations[k]);
+            sites.push({ path: `${base}.obligations[${k}]`, message: "Obligation", value: obligations[k] });
+            if (o?.["scope_license"] !== undefined) {
+                sites.push({ path: `${base}.obligations[${k}].scope_license`, message: "License", value: o["scope_license"] });
+            }
+        }
+    }
+    return sites;
+}
+/**
+ * validateResourceEntry reports the verdict the Exchange reaches for one entry
+ * (proto-JSON, snake_case), both tiers in the Exchange's order: the wire tier —
+ * the generated field-level schema over the entry as given, plus every
+ * cross-field rule reachable from it — then the ingest tier over a normalised
+ * copy of the terms. The entry passed in is never modified. The Exchange stops
+ * at the first tier that fails; this face reports both so a publisher fixes
+ * everything in one round. Paths are relative to the entry.
+ *
+ * The wire tier runs UNDER THE WIRE POLICY, the same seam every other parse of a
+ * generated schema in this SDK goes through. A generated schema describes the
+ * message and cannot describe the two things that are true of the wire: a `null`
+ * is how proto-JSON spells "no value" for any field, and a lowerCamelCase
+ * json_name alias is out of contract. A bare safeParse would answer wrongly in
+ * both directions on bodies a publisher really produces — an Exchange serving
+ * EmitUnpopulated renders an unset message field as null, and stock
+ * protojson.Marshal emits camelCase, which the schemas STRIP, so an entry whose
+ * every multiword field was silently dropped would come back accepted. This
+ * face exists to predict the Exchange's verdict, so it applies the Exchange's
+ * reading of the bytes.
+ */
+export function validateResourceEntry(entry) {
+    const violations = [];
+    try {
+        const parsed = ResourceEntrySchema.safeParse(underWirePolicy(ResourceEntrySchema, entry, ""));
+        if (!parsed.success) {
+            for (const issue of parsed.error.issues) {
+                violations.push({ rule: `field.${issue.code}`, path: zodPath(issue.path), token: "", message: issue.message });
+            }
+        }
+    }
+    catch (cause) {
+        // The naming refusal is the one policy failure that throws rather than
+        // returning an issue, so it is mapped to a violation here. Same id as the
+        // Python port reports it under, so a consumer branches on one string.
+        if (!(cause instanceof WireNamingError))
+            throw cause;
+        violations.push({
+            rule: `field.${JSON_NAME_ALIAS_ERROR}`,
+            path: cause.path,
+            token: "",
+            message: cause.message,
+        });
+    }
+    // Everything below reads members off the entry, so a value that is not an object
+    // has nothing to walk. The parse above has already said so — a non-object yields
+    // the schema's own type violation — and continuing would throw instead of
+    // returning that verdict. A publisher feeding this a parsed JSONL line reaches
+    // it with whatever the line held, so a malformed row must get a verdict like any
+    // other refusal rather than an exception the Python port does not raise either.
+    if (!asObj(entry))
+        return { ok: violations.length === 0, violations, warnings: [] };
+    for (const site of crossFieldSites(entry)) {
+        for (const id of crossFieldRuleIds(site.message, site.value)) {
+            violations.push({ rule: id, path: site.path, token: "", message: `cross-field rule violated: ${id}` });
+        }
+    }
+    const warnings = [];
+    const normalized = normalizeResourceEntry(entry);
+    const terms = asArr(normalized["terms"]);
+    for (let i = 0; i < terms.length; i++) {
+        const term = asObj(terms[i]);
+        if (!term)
+            continue;
+        const prefix = `terms[${i}].`;
+        const verdict = validateLicenseTerm(term);
+        if (verdict.violation) {
+            violations.push({ ...verdict.violation, path: prefix + verdict.violation.path });
+            continue;
+        }
+        for (const w of verdict.warnings)
+            warnings.push({ ...w, path: prefix + w.path });
+    }
+    return { ok: violations.length === 0, violations, warnings };
+}

package/sdk/ts/src/money.d.ts

@@ -0,0 +1,21 @@
+/**
+ * parseMoney validates a canonical wire decimal string, rejecting the empty
+ * (unset) string and any value the wire pattern forbids — signs, exponents, a
+ * leading dot — so a value that would fail the server's protovalidate never
+ * silently parses here. Returns the validated string (the TS decimal surface).
+ */
+export declare function parseMoney(s: string): string;
+/**
+ * formatMoney renders a validated money string as the canonical wire form: no
+ * sign, no exponent, insignificant LEADING integer zeros dropped ("007" -> "7",
+ * "00.5" -> "0.5", "000" -> "0") and insignificant trailing fractional zeros +
+ * a bare trailing dot stripped ("0.050" -> "0.05", "1.00" -> "1"). A negative
+ * value is rejected — FORA money is non-negative.
+ */
+export declare function formatMoney(s: string): string;
+/**
+ * canonicalizeMoney normalizes a wire decimal string to its canonical form
+ * (parse then format) — the convenience used when echoing a money value back
+ * onto the wire without doing arithmetic.
+ */
+export declare function canonicalizeMoney(s: string): string;

package/sdk/ts/src/money.js

@@ -0,0 +1,60 @@
+// Money (ADR-020) — TS port of the sdk/go oracle (helpers/money.go). FORA money
+// fields (Pricing.rate, Cost.amount, *.unit_cost) are exact decimal strings —
+// never floats — constrained by protovalidate to the wire pattern below:
+// non-negative, no sign, no exponent, optional fractional part, empty string
+// for "unset". The Go oracle round-trips shopspring decimal (NewFromString then
+// String); TS has no stdlib decimal, so the surface is a validated canonical
+// STRING. canonicalizeMoney reproduces the Go bytes: strip insignificant
+// LEADING integer zeros AND trailing fractional zeros + a bare trailing dot.
+// moneyWire mirrors the protovalidate constraint `^([0-9]+([.][0-9]+)?)?$`
+// exactly (kept in lockstep with fora.proto Pricing.rate). The empty string
+// matches the pattern but is rejected by parseMoney as "unset".
+const moneyWire = /^([0-9]+([.][0-9]+)?)?$/;
+/**
+ * parseMoney validates a canonical wire decimal string, rejecting the empty
+ * (unset) string and any value the wire pattern forbids — signs, exponents, a
+ * leading dot — so a value that would fail the server's protovalidate never
+ * silently parses here. Returns the validated string (the TS decimal surface).
+ */
+export function parseMoney(s) {
+    if (s === "") {
+        throw new Error("money: empty money string (field is unset)");
+    }
+    // Mirror protovalidate string.max_len = 32 (fora.proto Pricing.rate) so a
+    // pattern-valid but over-length value is rejected here, not only server-side.
+    if (s.length > 32) {
+        throw new Error(`money: string length ${s.length} exceeds max 32`);
+    }
+    if (!moneyWire.test(s)) {
+        throw new Error(`money: ${JSON.stringify(s)} is not a canonical money string`);
+    }
+    return s;
+}
+/**
+ * formatMoney renders a validated money string as the canonical wire form: no
+ * sign, no exponent, insignificant LEADING integer zeros dropped ("007" -> "7",
+ * "00.5" -> "0.5", "000" -> "0") and insignificant trailing fractional zeros +
+ * a bare trailing dot stripped ("0.050" -> "0.05", "1.00" -> "1"). A negative
+ * value is rejected — FORA money is non-negative.
+ */
+export function formatMoney(s) {
+    if (s.startsWith("-")) {
+        throw new Error(`money: negative money ${JSON.stringify(s)} is not representable on the wire`);
+    }
+    const dot = s.indexOf(".");
+    let intPart = dot === -1 ? s : s.slice(0, dot);
+    let fracPart = dot === -1 ? "" : s.slice(dot + 1);
+    intPart = intPart.replace(/^0+/, "");
+    if (intPart === "")
+        intPart = "0";
+    fracPart = fracPart.replace(/0+$/, "");
+    return fracPart === "" ? intPart : `${intPart}.${fracPart}`;
+}
+/**
+ * canonicalizeMoney normalizes a wire decimal string to its canonical form
+ * (parse then format) — the convenience used when echoing a money value back
+ * onto the wire without doing arithmetic.
+ */
+export function canonicalizeMoney(s) {
+    return formatMoney(parseMoney(s));
+}

package/sdk/ts/src/offer-sign.d.ts

@@ -0,0 +1,11 @@
+import { OFFER_SIGNATURE_ALGORITHM } from "../core/verifier.ts";
+export { OFFER_SIGNATURE_ALGORITHM };
+/**
+ * signOffer signs the canonical offer payload (JCS over the offer with its
+ * signature/signature_algorithm cleared) with the exchange's Ed25519 private key
+ * and returns the hex signature for Offer.signature. The offer must already be
+ * canonical proto-JSON (snake_case, enums-as-names, omit-unpopulated), as the
+ * verify face requires — canonicalOfferPayload clears the two signature keys and
+ * re-JCS-es.
+ */
+export declare function signOffer(offer: Record<string, unknown>, privateKey: CryptoKey): Promise<string>;

package/sdk/ts/src/offer-sign.js

@@ -0,0 +1,31 @@
+// sdk/ts offer SIGN face — the Exchange-minting sibling of the core Verifier's
+// offer-verification path. Mirror of the Go oracle helpers.SignOffer and Python
+// core.sign_offer_jcs.
+//
+// The signed bytes are JCS(protojson(offer with signature+signature_algorithm
+// cleared)) — the SAME canonical builder the verify face reuses
+// (core/verifier.ts canonicalOfferPayload), never a re-derived canonicalization.
+// Ed25519 is deterministic (RFC 8032), so the hex signature is byte-identical to
+// the Go oracle. This half is UNAFFECTED by the signed-URL opaque-bytes decision:
+// JCS over proto-JSON is already deterministic and cross-language byte-agreed.
+//
+// WebCrypto is the crypto primitive (the same one the acceptance/verify faces
+// use); the caller supplies the imported CryptoKey, exactly as acceptance.ts does.
+import { canonicalOfferPayload, OFFER_SIGNATURE_ALGORITHM } from "../core/verifier.js";
+export { OFFER_SIGNATURE_ALGORITHM };
+/**
+ * signOffer signs the canonical offer payload (JCS over the offer with its
+ * signature/signature_algorithm cleared) with the exchange's Ed25519 private key
+ * and returns the hex signature for Offer.signature. The offer must already be
+ * canonical proto-JSON (snake_case, enums-as-names, omit-unpopulated), as the
+ * verify face requires — canonicalOfferPayload clears the two signature keys and
+ * re-JCS-es.
+ */
+export async function signOffer(offer, privateKey) {
+    const payload = canonicalOfferPayload(offer);
+    const sig = new Uint8Array(await crypto.subtle.sign("Ed25519", privateKey, payload));
+    let hex = "";
+    for (const b of sig)
+        hex += b.toString(16).padStart(2, "0");
+    return hex;
+}

package/sdk/ts/src/opaque-url.d.ts

@@ -0,0 +1,3 @@
+export declare function opaqueUrl(url: string | {
+    toString(): string;
+}): string;

package/sdk/ts/src/opaque-url.js

@@ -0,0 +1,20 @@
+// opaqueUrl coerces a URL-like input to the primitive string the OPAQUE-URL-BYTES
+// contract (signurl.ts) operates on, ONCE at each public SDK boundary.
+//
+// The URL-consuming faces (Ed25519 signed-URL verify, RFC 9421 GET-PoP verify)
+// type their input as `string`, but some edge runtimes — Fastly Compute — hand
+// the request URL as a URL-LIKE OBJECT. Left uncoerced, that object either throws
+// (canonicalUrl's indexOf/slice string ops) or silently WHATWG-normalizes (a
+// `@target-uri` template literal calls toString(): lowercased host, stripped
+// :443, re-escaped path) — producing a signature base that diverges from the
+// verbatim bytes the signer covered.
+//
+// Coercing here is a NO-OP for the common server-to-server string caller
+// (String(s) === s, so the verbatim bytes are preserved) and gives a URL-like
+// object a single, explicit string form instead of an implicit toString() at
+// every downstream parse/interpolation site. It is deliberately NOT
+// `new URL(x).toString()`: that re-normalizes and would break byte-parity with
+// the Go signer's verbatim @target-uri (sigbase.go reconstructTargetURI).
+export function opaqueUrl(url) {
+    return String(url);
+}

package/sdk/ts/src/pop.d.ts

@@ -0,0 +1,51 @@
+export declare const AGENT_KEY_HEADER: string;
+export type PopFailure = "missing_agent_key" | "bad_agent_key" | "missing_sig" | "malformed_sig_input" | "unsupported_alg" | "bad_covered_components" | "keyid_mismatch" | "thumbprint_mismatch" | "pop_missing_created" | "pop_future_created" | "pop_missing_exp" | "pop_expired" | "pop_sig_invalid";
+export interface PopResult {
+    ok: boolean;
+    reason?: PopFailure;
+}
+/**
+ * Ed25519 verify primitive: (publicKey, signature, message) -> valid?. Injected
+ * so non-WebCrypto runtimes can supply their own without changing the byte
+ * contract. Defaults to WebCrypto. Byte params are `Uint8Array<ArrayBuffer>`
+ * (never SharedArrayBuffer-backed) so the default can hand them to WebCrypto's
+ * BufferSource without casts.
+ */
+export type Ed25519Verify = (publicKey: Uint8Array<ArrayBuffer>, signature: Uint8Array<ArrayBuffer>, message: Uint8Array<ArrayBuffer>) => Promise<boolean>;
+export interface PopInput {
+    /** Full request URL — the value the agent signed as `@target-uri`. */
+    url: string;
+    method: string;
+    headers: Headers;
+    /** The bound thumbprint carried in the URL's `agent_id` param. */
+    agentId: string;
+    now?: () => number;
+    /** Optional Ed25519 verify primitive; defaults to WebCrypto crypto.subtle. */
+    verifyEd25519?: Ed25519Verify;
+}
+interface SignatureInput {
+    covered: string[];
+    /** Verbatim params string after `label=`, used to rebuild @signature-params. */
+    rawParams: string;
+    keyid: string;
+    alg: string;
+    created?: number;
+    expires?: number;
+}
+/**
+ * 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 declare function verifyAgentBinding(input: PopInput): Promise<PopResult>;
+/**
+ * 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 declare function signatureBase(method: string, url: string, rawParams: string): string;
+/** Parse `label=("@method" "@target-uri");keyid="..";alg="..";created=..;expires=..`. */
+export declare function parseSignatureInput(raw: string | null): SignatureInput | undefined;
+/** Parse the RFC 9421 `Signature` header value `label=:<base64>:`. */
+export declare function parseSignature(raw: string | null): Uint8Array<ArrayBuffer> | undefined;
+export {};