@fora-protocol/sdk 1.0.3

package/sdk/ts/src/hosts.d.ts

@@ -0,0 +1,138 @@
+/**
+ * bareDomainPattern is the wire shape of a domain-valued field: a bare domain
+ * with an optional ":port", never a URL. It carries the same bytes as the Go
+ * `helpers.BareDomainPattern` and as the protovalidate pattern on the contract's
+ * recipient-addressing fields — the `exchange` field on each addressed request,
+ * `Offer.exchange` and their neighbours, not every field in fora.proto that
+ * happens to hold a domain. One rule, so the check a client makes before sending
+ * and the check the wire makes on arrival cannot answer differently. The parity
+ * suite asserts these bytes against the shared vectors.
+ *
+ * The port is a real 1-65535 range rather than "one to five digits", which is why
+ * it is spelled out at this length: `:0`, `:65536` and `:99999` name no port at
+ * all, and `:0443` is not a spelling of 443 but a different string.
+ */
+export declare const bareDomainPattern: string;
+/**
+ * maxBareDomainLen is the length bound belonging to the same rule — the
+ * protovalidate `string.max_len` those fields carry, so this SDK cannot accept a
+ * pattern-valid but over-length value the server then rejects.
+ */
+export declare const maxBareDomainLen = 260;
+/**
+ * isBareDomain reports whether v is a bare domain of the shape the wire admits.
+ *
+ * The length is checked FIRST so the work stays bounded on hostile input. This is
+ * insurance rather than a fix for a known blowup: the pattern is unambiguous —
+ * every repetition is anchored by a literal dot no label class can consume — so it
+ * cannot backtrack catastrophically, and matching it costs time linear in the
+ * input. Bounding that is still worth one comparison on an engine that
+ * backtracks. The order costs nothing in agreement — a value whose length differs
+ * between UTF-16 units, code points and bytes contains something outside ASCII,
+ * and the pattern refuses it regardless.
+ */
+export declare function isBareDomain(v: string): boolean;
+/**
+ * The outcome of checking a request's claimed recipient against this Exchange's
+ * own identity. The tokens are the Go `AudienceVerdict.String()` vocabulary
+ * verbatim, which is what the shared vectors record.
+ *
+ * `no_verdict` means the check did not run because the configured identity is
+ * unusable. It is never RETURNED here — this port throws in that case, since a
+ * deployment fault is not something a caller should be able to read as a value
+ * — but it is in the vocabulary because the shared vectors carry it.
+ */
+export type AudienceVerdict = "no_verdict" | "accepted" | "empty" | "malformed" | "mismatch";
+/**
+ * checkAudience reports whether every claimed recipient names this Exchange.
+ *
+ * `self` is this Exchange's own bare domain — the domain it publishes as its
+ * IDENTITY, which is the value it stamps into the offers it issues. It is not the
+ * host the process happens to listen on, and the two are allowed to differ: an
+ * Exchange at `exchange.example` may serve its API from `api.exchange.example`, so
+ * an operator who configures this from the listening host would refuse every
+ * request that named them correctly.
+ *
+ * `claimed` holds the recipient
+ * values the request carries — ONE for a message with a single `exchange`
+ * field, MANY for a message whose audience lives per item (a TransactionRequest
+ * states it once per item, in each item's signed offer). Every value must name
+ * this Exchange; the first that does not decides the verdict, and a request
+ * carrying no values at all is refused rather than waved through.
+ *
+ * The comparison is EXACT: a subdomain of this Exchange is a different party and
+ * does not name it. That is narrower than the endpoint rule, which does let a
+ * manifest advertise its endpoint on a subdomain of the host that served it —
+ * there the question is which addresses one Exchange may be reached at, here it
+ * is who the Exchange IS.
+ *
+ * Two spellings of the same identity still match: case is folded, and a port of
+ * 443 written out is the same as leaving it off, since a schemeless domain is
+ * read as https throughout this SDK. Port 80 is not folded — it is not the
+ * default of the scheme a bare domain implies.
+ *
+ * Throws when `self` is not a bare domain. That is a fault in this deployment,
+ * never in the request, and the two are kept apart so a caller can map them onto
+ * different status codes without inspecting any message.
+ */
+export declare function checkAudience(self: string, ...claimed: string[]): AudienceVerdict;
+/**
+ * hostOf extracts the host (including any port) from a bare domain, a host:port
+ * pair, or a full URL. A ref with no scheme is read as though it carried https,
+ * since a bare domain is otherwise indistinguishable from a path.
+ *
+ * Throws when the reference cannot be read as a host at all.
+ */
+export declare function hostOf(ref: string): string;
+/**
+ * isBareHost reports whether ref is EXACTLY a host — nothing a URL could carry
+ * besides the authority. It answers false for a ref with a scheme, userinfo, a
+ * path, a query or a fragment, because hostOf had to strip something to reach the
+ * host. A port is NOT a strip: "exchange.example:8443" is a bare host, and the
+ * well-known resolver concatenates host-with-port unchanged.
+ *
+ * It exists for the callers that hand a network-supplied domain to code which
+ * builds a URL by concatenation. There, narrowing a rich reference to its host is
+ * the wrong repair: the value was never a domain, and accepting it silently means
+ * the far side chose the path that gets fetched, not just the host it is fetched
+ * from. Comparing against the extracted host is what makes the rejection
+ * structural rather than a blocklist of the separators anyone thought to name.
+ *
+ * This is NOT isBareDomain. A trailing root dot, a leading or trailing hyphen, an
+ * underscore, an empty label and a bracketed IPv6 literal are all usable hosts and
+ * none of them is a value the wire rule accepts. A caller vetting a value it is
+ * about to dial wants this one; a caller vetting a value that arrived in a message
+ * wants isBareDomain.
+ */
+export declare function isBareHost(ref: string): boolean;
+/**
+ * hostAnchored reports whether candidate is anchored to anchor — the same host and
+ * port, or a subdomain of that host on that port. Either side may be a bare
+ * domain, a host:port pair or a full URL; a reference that does not parse throws,
+ * which callers treat as "not anchored".
+ *
+ * The use is checking a value a remote document supplied against the host that
+ * served that document: it may point at itself or at one of its own subdomains,
+ * and nothing else. Without it, a host could redirect a signed request — or a
+ * revocation poll — to an unrelated third-party address that a dial-time address
+ * guard would happily allow, because the address is perfectly public.
+ *
+ * The PORT is part of the comparison. What is being anchored is a place a signed
+ * call is sent, and a different port is a different service — one the party that
+ * published the anchor need not control. A DEFAULT port and its omission are the
+ * same port, so https://x, https://x:443 and x all anchor to one another; refusing
+ * an operator who merely wrote :443 out in full would be a spelling check wearing
+ * a security check's clothes.
+ *
+ * The SCHEME is still not compared. Whether a leg may run in the clear is the
+ * guarded transport's decision, made in one place from one flag. Its only job here
+ * is choosing which port counts as the default — and a side that NAMED no scheme
+ * borrows the other's for that purpose, rather than being assumed to mean https.
+ * Both anchors in this SDK arrive schemeless: a WBA directory's authority and an
+ * Offer.exchange host are bare host[:port] values. Assuming https for them meant an
+ * anchor of "a.example:80" kept its port (80 is not https's default) while the
+ * candidate "http://a.example:80" folded it away — the same authority reaching two
+ * answers, which silently un-anchored every plaintext directory that spelled :80
+ * in full.
+ */
+export declare function hostAnchored(anchor: string, candidate: string): boolean;

package/sdk/ts/src/hosts.js

@@ -0,0 +1,214 @@
+// Host predicates, the audience check and the bare-domain shape — TS port of the
+// sdk/go oracle (helpers/hosts.go, helpers/audience.go).
+//
+// Two kinds of predicate live here and keeping them apart is the point. The
+// ROUTING predicates — isBareHost and hostAnchored — precede a signed call to an
+// address a network party named: a value that arrives inside an offer, or inside
+// a manifest that offer pointed at, is about to be concatenated into a URL or
+// dialled directly. The SHAPE predicate — isBareDomain — answers a different
+// question: whether a value is the form the wire contract admits at all.
+//
+// Addressed requests carry the recipient's bare domain in a body field. The RFC
+// 9421 signature does not already establish the recipient: it proves the sender
+// signed THE URL IT DIALLED, not that the URL was the right one. That dial target
+// is resolved from a fetched, cached /.well-known/fora.json, so a poisoned or
+// stale resolution redirects the request while every signature still verifies.
+// The field states whom the sender MEANT, independently of that resolution.
+//
+// The field is stamped by whoever authors each request — the agent on the requests
+// it signs, a Broker on the legs it authors as sender. It is a statement BY that
+// sender, not tamper-evidence against it. For transactions the binding audience
+// statement is per item: Offer.exchange inside the Exchange-signed offer.
+//
+// Pure string work, no IO. Byte-parity-guarded against the Go oracle by the
+// shared vectors at sdk/go/helpers/testdata/audience-vectors.json.
+import { anchoredParsed, parseRef } from "./host-ref.js";
+/**
+ * bareDomainPattern is the wire shape of a domain-valued field: a bare domain
+ * with an optional ":port", never a URL. It carries the same bytes as the Go
+ * `helpers.BareDomainPattern` and as the protovalidate pattern on the contract's
+ * recipient-addressing fields — the `exchange` field on each addressed request,
+ * `Offer.exchange` and their neighbours, not every field in fora.proto that
+ * happens to hold a domain. One rule, so the check a client makes before sending
+ * and the check the wire makes on arrival cannot answer differently. The parity
+ * suite asserts these bytes against the shared vectors.
+ *
+ * The port is a real 1-65535 range rather than "one to five digits", which is why
+ * it is spelled out at this length: `:0`, `:65536` and `:99999` name no port at
+ * all, and `:0443` is not a spelling of 443 but a different string.
+ */
+export const bareDomainPattern = String.raw `^[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?(\.[A-Za-z0-9]([A-Za-z0-9-]*[A-Za-z0-9])?)*(:(6553[0-5]|655[0-2][0-9]|65[0-4][0-9]{2}|6[0-4][0-9]{3}|[1-5][0-9]{4}|[1-9][0-9]{0,3}))?$`;
+/**
+ * maxBareDomainLen is the length bound belonging to the same rule — the
+ * protovalidate `string.max_len` those fields carry, so this SDK cannot accept a
+ * pattern-valid but over-length value the server then rejects.
+ */
+export const maxBareDomainLen = 260;
+// Compiled once. JavaScript's `$` (without the `m` flag) matches only at the end
+// of input and — unlike Python's — does NOT match before a trailing newline, so
+// `test` reproduces Go's RE2 anchoring here without further help. The shared
+// vectors carry a trailing-newline case that fails any port which gets this
+// wrong.
+const bareDomainRe = new RegExp(bareDomainPattern);
+/**
+ * isBareDomain reports whether v is a bare domain of the shape the wire admits.
+ *
+ * The length is checked FIRST so the work stays bounded on hostile input. This is
+ * insurance rather than a fix for a known blowup: the pattern is unambiguous —
+ * every repetition is anchored by a literal dot no label class can consume — so it
+ * cannot backtrack catastrophically, and matching it costs time linear in the
+ * input. Bounding that is still worth one comparison on an engine that
+ * backtracks. The order costs nothing in agreement — a value whose length differs
+ * between UTF-16 units, code points and bytes contains something outside ASCII,
+ * and the pattern refuses it regardless.
+ */
+export function isBareDomain(v) {
+    return v.length <= maxBareDomainLen && bareDomainRe.test(v);
+}
+/**
+ * checkAudience reports whether every claimed recipient names this Exchange.
+ *
+ * `self` is this Exchange's own bare domain — the domain it publishes as its
+ * IDENTITY, which is the value it stamps into the offers it issues. It is not the
+ * host the process happens to listen on, and the two are allowed to differ: an
+ * Exchange at `exchange.example` may serve its API from `api.exchange.example`, so
+ * an operator who configures this from the listening host would refuse every
+ * request that named them correctly.
+ *
+ * `claimed` holds the recipient
+ * values the request carries — ONE for a message with a single `exchange`
+ * field, MANY for a message whose audience lives per item (a TransactionRequest
+ * states it once per item, in each item's signed offer). Every value must name
+ * this Exchange; the first that does not decides the verdict, and a request
+ * carrying no values at all is refused rather than waved through.
+ *
+ * The comparison is EXACT: a subdomain of this Exchange is a different party and
+ * does not name it. That is narrower than the endpoint rule, which does let a
+ * manifest advertise its endpoint on a subdomain of the host that served it —
+ * there the question is which addresses one Exchange may be reached at, here it
+ * is who the Exchange IS.
+ *
+ * Two spellings of the same identity still match: case is folded, and a port of
+ * 443 written out is the same as leaving it off, since a schemeless domain is
+ * read as https throughout this SDK. Port 80 is not folded — it is not the
+ * default of the scheme a bare domain implies.
+ *
+ * Throws when `self` is not a bare domain. That is a fault in this deployment,
+ * never in the request, and the two are kept apart so a caller can map them onto
+ * different status codes without inspecting any message.
+ */
+export function checkAudience(self, ...claimed) {
+    if (!isBareDomain(self)) {
+        throw new Error(`hosts: configured Exchange identity is not a bare domain: ${JSON.stringify(self)}`);
+    }
+    if (claimed.length === 0) {
+        return "empty";
+    }
+    const want = normalizeDomain(self);
+    for (const c of claimed) {
+        if (c === "") {
+            return "empty";
+        }
+        if (!isBareDomain(c)) {
+            return "malformed";
+        }
+        if (normalizeDomain(c) !== want) {
+            return "mismatch";
+        }
+    }
+    return "accepted";
+}
+// normalizeDomain renders the two spellings of one identity as one string. It
+// runs only on values isBareDomain has already accepted, so the input is ASCII
+// and holds at most one colon followed by digits — which is what lets it split
+// on that colon rather than parse a URL, and is why it reproduces the Go oracle
+// exactly.
+function normalizeDomain(v) {
+    const i = v.lastIndexOf(":");
+    const host = (i >= 0 ? v.slice(0, i) : v).toLowerCase();
+    const port = i >= 0 ? v.slice(i + 1) : "";
+    // A schemeless domain is read as https everywhere in this SDK, so 443 spelled
+    // out and 443 left implicit are the same port. Any other port is kept, 80
+    // included: folding it would be reading a scheme into a value that names none.
+    if (port === "" || port === "443") {
+        return host;
+    }
+    return `${host}:${port}`;
+}
+// ---------------------------------------------------------------------------
+// Routing predicates
+// ---------------------------------------------------------------------------
+/**
+ * hostOf extracts the host (including any port) from a bare domain, a host:port
+ * pair, or a full URL. A ref with no scheme is read as though it carried https,
+ * since a bare domain is otherwise indistinguishable from a path.
+ *
+ * Throws when the reference cannot be read as a host at all.
+ */
+export function hostOf(ref) {
+    return parseRef(ref).host;
+}
+/**
+ * isBareHost reports whether ref is EXACTLY a host — nothing a URL could carry
+ * besides the authority. It answers false for a ref with a scheme, userinfo, a
+ * path, a query or a fragment, because hostOf had to strip something to reach the
+ * host. A port is NOT a strip: "exchange.example:8443" is a bare host, and the
+ * well-known resolver concatenates host-with-port unchanged.
+ *
+ * It exists for the callers that hand a network-supplied domain to code which
+ * builds a URL by concatenation. There, narrowing a rich reference to its host is
+ * the wrong repair: the value was never a domain, and accepting it silently means
+ * the far side chose the path that gets fetched, not just the host it is fetched
+ * from. Comparing against the extracted host is what makes the rejection
+ * structural rather than a blocklist of the separators anyone thought to name.
+ *
+ * This is NOT isBareDomain. A trailing root dot, a leading or trailing hyphen, an
+ * underscore, an empty label and a bracketed IPv6 literal are all usable hosts and
+ * none of them is a value the wire rule accepts. A caller vetting a value it is
+ * about to dial wants this one; a caller vetting a value that arrived in a message
+ * wants isBareDomain.
+ */
+export function isBareHost(ref) {
+    const host = hostOf(ref);
+    // A trailing colon parses as a host with an empty port and would otherwise
+    // compare equal to itself. It is not a domain anyone meant to write, and the
+    // callers here concatenate the value into a URL, so it is refused rather than
+    // quietly normalized away.
+    if (host.endsWith(":")) {
+        return false;
+    }
+    return host === ref;
+}
+/**
+ * hostAnchored reports whether candidate is anchored to anchor — the same host and
+ * port, or a subdomain of that host on that port. Either side may be a bare
+ * domain, a host:port pair or a full URL; a reference that does not parse throws,
+ * which callers treat as "not anchored".
+ *
+ * The use is checking a value a remote document supplied against the host that
+ * served that document: it may point at itself or at one of its own subdomains,
+ * and nothing else. Without it, a host could redirect a signed request — or a
+ * revocation poll — to an unrelated third-party address that a dial-time address
+ * guard would happily allow, because the address is perfectly public.
+ *
+ * The PORT is part of the comparison. What is being anchored is a place a signed
+ * call is sent, and a different port is a different service — one the party that
+ * published the anchor need not control. A DEFAULT port and its omission are the
+ * same port, so https://x, https://x:443 and x all anchor to one another; refusing
+ * an operator who merely wrote :443 out in full would be a spelling check wearing
+ * a security check's clothes.
+ *
+ * The SCHEME is still not compared. Whether a leg may run in the clear is the
+ * guarded transport's decision, made in one place from one flag. Its only job here
+ * is choosing which port counts as the default — and a side that NAMED no scheme
+ * borrows the other's for that purpose, rather than being assumed to mean https.
+ * Both anchors in this SDK arrive schemeless: a WBA directory's authority and an
+ * Offer.exchange host are bare host[:port] values. Assuming https for them meant an
+ * anchor of "a.example:80" kept its port (80 is not https's default) while the
+ * candidate "http://a.example:80" folded it away — the same authority reaching two
+ * answers, which silently un-anchored every plaintext directory that spelled :80
+ * in full.
+ */
+export function hostAnchored(anchor, candidate) {
+    return anchoredParsed(parseRef(anchor), parseRef(candidate));
+}

package/sdk/ts/src/idempotency.d.ts

@@ -0,0 +1,11 @@
+/**
+ * generateIdempotencyKey returns a fresh cryptographically-random, URL-safe
+ * idempotency key (16 random bytes -> base64url, 22 chars, no padding). Use it
+ * once per logical operation; reuse a stored key only to deliberately replay.
+ */
+export declare function generateIdempotencyKey(): string;
+/**
+ * validateIdempotencyKey enforces the protocol's min_len=1 constraint, so the
+ * SDK rejects an empty key before the server does.
+ */
+export declare function validateIdempotencyKey(key: string): void;

package/sdk/ts/src/idempotency.js

@@ -0,0 +1,27 @@
+// Idempotency (ADR-019 §4) — TS port of the sdk/go oracle (helpers/idempotency.go).
+// idempotency_key is a required, persisted, settlement-bound field on the
+// mutating RPCs: the server dedupes on it so a replay returns the original
+// result and cannot double-charge. The SDK mints a fresh key per call by
+// default; to make a call a deliberate replay the application reuses a stored
+// key. The SDK never tracks keys — the server owns the dedup store.
+import { encodeBase64Url } from "./base64url.js";
+// idempotencyKeyBytes is the entropy per key (128 bits -> 22 base64url chars).
+const idempotencyKeyBytes = 16;
+/**
+ * generateIdempotencyKey returns a fresh cryptographically-random, URL-safe
+ * idempotency key (16 random bytes -> base64url, 22 chars, no padding). Use it
+ * once per logical operation; reuse a stored key only to deliberately replay.
+ */
+export function generateIdempotencyKey() {
+    const b = crypto.getRandomValues(new Uint8Array(idempotencyKeyBytes));
+    return encodeBase64Url(b);
+}
+/**
+ * validateIdempotencyKey enforces the protocol's min_len=1 constraint, so the
+ * SDK rejects an empty key before the server does.
+ */
+export function validateIdempotencyKey(key) {
+    if (key === "") {
+        throw new Error("idempotency: idempotency_key must be non-empty");
+    }
+}

package/sdk/ts/src/jsondepth.d.ts

@@ -0,0 +1,27 @@
+/**
+ * How deep a document this SDK did not write may nest.
+ *
+ * The same 32 the error-detail reader uses and the protocol sets for a stranger's JSON in
+ * AccountRegistration.data_schema, so one number covers how deep any such document may be.
+ * The deepest instance in the whole conformance corpus is 5.
+ *
+ * It lives beside the scan rather than at either call site, because a bound stated twice is
+ * a bound two readers can disagree about.
+ */
+export declare const MAX_BODY_DEPTH = 32;
+/**
+ * rawNestingDepth returns the deepest JSON container nesting in `source`, counted
+ * lexically — no parse, no recursion, one pass.
+ *
+ * It is string-aware, so a brace inside a string literal is text rather than a container,
+ * and escape-aware so a literal quote does not end the string early. It does NOT check that
+ * the brackets balance: an unbalanced document is the parser's to reject, and this only has
+ * to produce an upper bound on how deep a parser would have to descend.
+ *
+ * It takes BYTES or TEXT and answers the same for both. Every delimiter it looks for is
+ * ASCII, and neither a UTF-8 continuation byte nor a UTF-16 code unit above the ASCII range
+ * can collide with one — so a caller that already holds one form never has to pay a
+ * conversion to the other. The registration-schema compiler measures the bytes as served;
+ * the client's readers already hold decoded text.
+ */
+export declare function rawNestingDepth(source: Uint8Array | string): number;

package/sdk/ts/src/jsondepth.js

@@ -0,0 +1,77 @@
+// How deep a JSON document nests, counted without parsing it.
+//
+// Shared, because several readers need the same answer for the same reason and a second
+// transcription of a security rule is how the three languages drifted apart elsewhere.
+// TS mirror of sdk/python/fora_sdk/_jsondepth.py.
+//
+// Every JSON parser across the SDKs descends into a document, and what it does when the
+// document is deeper than it can descend is a property of the runtime rather than a
+// verdict: Python's raises RecursionError, which is neither what a malformed document
+// raises nor a failure any of these packages says it raises. A depth check placed AFTER the
+// parse is reached only by documents harmless enough to parse — precisely the ones that did
+// not need it.
+//
+// So the scan is lexical and runs first. Counting needs no recursion.
+//
+// Three callers today: the registration-schema compiler, reading a schema out of a third
+// party's manifest, and both of the client's readers of a peer's own bytes — the response
+// reader and the delivery edge's refusal reader.
+/**
+ * How deep a document this SDK did not write may nest.
+ *
+ * The same 32 the error-detail reader uses and the protocol sets for a stranger's JSON in
+ * AccountRegistration.data_schema, so one number covers how deep any such document may be.
+ * The deepest instance in the whole conformance corpus is 5.
+ *
+ * It lives beside the scan rather than at either call site, because a bound stated twice is
+ * a bound two readers can disagree about.
+ */
+export const MAX_BODY_DEPTH = 32;
+/**
+ * rawNestingDepth returns the deepest JSON container nesting in `source`, counted
+ * lexically — no parse, no recursion, one pass.
+ *
+ * It is string-aware, so a brace inside a string literal is text rather than a container,
+ * and escape-aware so a literal quote does not end the string early. It does NOT check that
+ * the brackets balance: an unbalanced document is the parser's to reject, and this only has
+ * to produce an upper bound on how deep a parser would have to descend.
+ *
+ * It takes BYTES or TEXT and answers the same for both. Every delimiter it looks for is
+ * ASCII, and neither a UTF-8 continuation byte nor a UTF-16 code unit above the ASCII range
+ * can collide with one — so a caller that already holds one form never has to pay a
+ * conversion to the other. The registration-schema compiler measures the bytes as served;
+ * the client's readers already hold decoded text.
+ */
+export function rawNestingDepth(source) {
+    const text = typeof source === "string";
+    const length = source.length;
+    let depth = 0;
+    let deepest = 0;
+    let inString = false;
+    let escaped = false;
+    for (let i = 0; i < length; i++) {
+        const code = text
+            ? source.charCodeAt(i)
+            : source[i];
+        if (inString) {
+            if (escaped)
+                escaped = false;
+            else if (code === 0x5c)
+                escaped = true; // backslash
+            else if (code === 0x22)
+                inString = false; // quote
+            continue;
+        }
+        if (code === 0x22)
+            inString = true;
+        else if (code === 0x7b || code === 0x5b) {
+            // { [
+            depth++;
+            if (depth > deepest)
+                deepest = depth;
+        }
+        else if (code === 0x7d || code === 0x5d)
+            depth--; // } ]
+    }
+    return deepest;
+}

package/sdk/ts/src/licenseterm.d.ts

@@ -0,0 +1,113 @@
+/** Rejects a bare (non-namespaced) Pricing.unit that is not a registered metering token. */
+export declare const RULE_PRICING_UNIT_REGISTERED = "pricing.unit.registered";
+/** Rejects a bare Quota.metric that is not a registered quota token. */
+export declare 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 declare const RULE_RESTRICTION_CANONICAL_DISJOINT = "restriction.canonical_disjoint";
+/** Warns about a bare restriction token not registered on its axis; the term is accepted. */
+export declare const RULE_RESTRICTION_TOKEN_REGISTERED = "restriction.token.registered";
+/** Warns about an OBLIGATION_KIND_OTHER obligation carrying no detail. */
+export declare const RULE_OBLIGATION_OTHER_REQUIRES_DETAIL = "obligation.other.requires_detail";
+/**
+ * One reason an entry or a term would be refused. `rule` is the rule id (an
+ * ingest-tier id above, a cross-field CEL id, or `field.<zod issue code>` for a
+ * field-level refusal — the field-level ids are language-local); `path` is the
+ * snake_case proto-JSON field path relative to the checked message; `token` is
+ * the offending value when the rule is about one token, else "".
+ */
+export interface RuleViolation {
+    rule: string;
+    path: string;
+    token: string;
+    message: string;
+}
+/** One non-fatal finding; `message` is the exact wire string of the warning. */
+export interface RuleWarning {
+    rule: string;
+    path: string;
+    token: string;
+    message: string;
+}
+/**
+ * What validateLicenseTerm reports for one term. Every check but the disjointness
+ * one reads the term as already canonical; that one folds what it compares, so it
+ * is correct on a term as authored too.
+ */
+export interface TermVerdict {
+    violation: RuleViolation | null;
+    warnings: RuleWarning[];
+}
+/** What validateResourceEntry reports: both tiers, wire tier first. */
+export interface EntryVerdict {
+    ok: boolean;
+    violations: RuleViolation[];
+    warnings: RuleWarning[];
+}
+type Obj = Record<string, unknown>;
+/**
+ * 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 declare function canonicalRestrictionToken(kind: string, token: string): string;
+/**
+ * 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 declare function knownRestrictionToken(kind: string, token: string): boolean;
+/**
+ * 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 declare function normalizeLicenseTerm(term: Obj): Obj;
+/** normalizeResourceEntry returns a deep copy with every term normalised. */
+export declare function normalizeResourceEntry(entry: Obj): Obj;
+/**
+ * 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 declare function validateLicenseTerm(term: Obj): TermVerdict;
+/**
+ * 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 declare function validateResourceEntry(entry: Obj): EntryVerdict;
+export {};