@fora-protocol/sdk 1.0.3

package/sdk/ts/resolvers/registration-requirements.js

@@ -0,0 +1,220 @@
+// Reading what one Exchange asks of a registration — the terms revision that
+// submitting one accepts, and the schema its registration_data must match — out of
+// that Exchange's own /.well-known/fora.json. TS port of the Go oracle
+// (resolvers/registrationrequirements.go).
+//
+// EVERY READ IS A FRESH FETCH, and that is the whole design. The protocol requires
+// it in as many words: a registering client MUST read the terms digest from a
+// freshly fetched manifest rather than a cached copy. A cached ENDPOINT is fine — a
+// wrong one fails loudly — but a cached DIGEST is not, because a client cannot
+// detect staleness locally, so a warm cache would make it echo a value the Exchange
+// has already stopped accepting and retry the same refusal until the cache expired.
+//
+// That is why this is a SEPARATE face rather than a third method on the endpoint
+// resolver. That resolver is built out of exactly the mechanism this value may not
+// touch — a per-host TTL cache with single-flight coalescing on top — and it exposes
+// no bypass. A face that holds no document cache leaves no cache slot to reuse,
+// which is what makes the rule structural rather than a convention callers remember.
+//
+// Not even the compiled validator is held. Memoising it is a cache, and the useful
+// key for one is a property of a deployment's threat model rather than of the
+// protocol; an application that wants it wraps this face.
+import { isBareDomain } from "../src/hosts.js";
+import { invalidHost } from "../src/host-ref.js";
+import { compileRegistrationSchema, } from "../src/regschema.js";
+import { manifestVersionRefusal, WellKnownPath } from "../src/wire.js";
+import { DirectoryUnavailable, ExchangeNotPermitted, ManifestNotExchange, ManifestUnusable, } from "./errors.js";
+import { fetchStrict, guardedFetchFromEnv } from "./http.js";
+/** Read registration requirements from an Exchange's own well-known manifest. */
+export function createWellKnownRequirementsReader(opts = {}) {
+    // Built ONCE per reader, never per read: guardedFetchFromEnv constructs a
+    // dispatcher, so a per-read default would trade an unguarded dial for a socket
+    // leak.
+    const fetchFn = opts.fetch ?? guardedFetchFromEnv();
+    const scheme = opts.scheme && opts.scheme !== "" ? opts.scheme : "https";
+    const allow = opts.allow;
+    return {
+        async resolveRegistrationRequirements(exchange) {
+            // The SHAPE predicate is the contract's isBareDomain, not the routing tier's
+            // isBareHost. The two are kept apart deliberately and this leg is where the
+            // difference bites: nothing upstream has run the contract's rule, and the URL
+            // below is built by concatenation, so a value carrying a path or userinfo
+            // would choose WHAT is fetched rather than merely where from.
+            //
+            // The document's own version is read BEFORE any other member below, which is the
+            // rule the contract states for every consumer of this document and not only for
+            // the face that reads an endpoint out of it. A layout this reader cannot classify
+            // does not get to supply a terms digest that a request signature then covers.
+            if (!isBareDomain(exchange)) {
+                throw invalidHost(exchange, "not a bare domain");
+            }
+            if (allow && !allow(exchange)) {
+                throw new ExchangeNotPermitted(`exchange ${exchange} not permitted by policy`);
+            }
+            const url = `${scheme}://${exchange}${WellKnownPath}`;
+            const body = await fetchStrict(fetchFn, url);
+            let doc;
+            try {
+                doc = JSON.parse(body);
+            }
+            catch (err) {
+                throw new DirectoryUnavailable(`manifest decode ${url}`, { cause: err });
+            }
+            // The document version gate, before any other member is read — the contract's own
+            // ordering, and the same call the sibling endpoint face makes. A document that is
+            // not an object carries no `ver`, so it is refused here as an absent one rather
+            // than through a guard of its own: a body of bare `null` is a body with no
+            // version, whatever else it is, and giving it a separate answer is what made the
+            // three languages disagree about it.
+            //
+            // The refusal wears THIS seam's verdict, never the endpoint seam's
+            // ManifestVersionRefused. The two vocabularies are disjoint on purpose: one
+            // answers whether an endpoint may be dialled, this one whether a document can be
+            // read for what a registration owes.
+            const versionRefusal = manifestVersionRefusal(doc?.ver);
+            if (versionRefusal !== undefined) {
+                throw new ManifestUnusable(versionRefusal);
+            }
+            if (!describesExchange(doc)) {
+                throw new ManifestNotExchange(`host=${exchange}`);
+            }
+            const digest = doc.terms_digest;
+            const out = {
+                termsDigest: typeof digest === "string" ? digest : undefined,
+                schema: null,
+                verdict: "not_published",
+            };
+            // Compiled from the bytes AS SERVED. Every cap the registration-schema rules
+            // state is defined over those bytes, so the member is sliced out of the body
+            // rather than re-serialised from the parsed value: JSON.parse discards
+            // whitespace and reformats numbers, and a document that minifies under the
+            // cap while exceeding it on the wire would be refused by an Exchange and
+            // accepted here — the two-privately-chosen-limits failure the contract's
+            // numbers exist to prevent.
+            const raw = rawMember(body, "account_registration", "data_schema");
+            if (raw !== undefined) {
+                const compiled = compileRegistrationSchema(raw);
+                out.schema = compiled.schema;
+                out.verdict = compiled.verdict;
+            }
+            return out;
+        },
+    };
+}
+/** proto-JSON renders an enum as its name or its number, so both are accepted. An
+ * absent or unrecognised role is not an Exchange. */
+function describesExchange(doc) {
+    const role = doc.role;
+    return role === "ROLE_EXCHANGE" || role === 2;
+}
+/** rawMember returns the EXACT served text of a nested object member, or
+ * `undefined` when any step of the path is absent.
+ *
+ * It exists because JavaScript has no equivalent of a raw-message slice: the only
+ * way to hand a nested member to a rule defined over the bytes AS SERVED is to
+ * find its extent in the body. `body` has already parsed as JSON when this runs,
+ * so the scan below is over known-well-formed input and needs no error path — it
+ * returns `undefined` for anything it cannot walk, and the caller reads that as
+ * "no schema published", which is the safe direction.
+ */
+function rawMember(body, ...path) {
+    let start = 0;
+    for (let step = 0; step < path.length; step++) {
+        const found = memberExtent(body, start, path[step]);
+        if (found === undefined)
+            return undefined;
+        if (step === path.length - 1)
+            return body.slice(found[0], found[1]);
+        start = found[0];
+    }
+    return undefined;
+}
+/** memberExtent finds `key` in the object beginning at `from` and returns the
+ * [start, end) of its VALUE. */
+function memberExtent(body, from, key) {
+    let i = skipWhitespace(body, from);
+    if (body[i] !== "{")
+        return undefined;
+    i = skipWhitespace(body, i + 1);
+    if (body[i] === "}")
+        return undefined;
+    for (;;) {
+        if (body[i] !== '"')
+            return undefined;
+        const keyEnd = skipString(body, i);
+        const name = JSON.parse(body.slice(i, keyEnd));
+        i = skipWhitespace(body, keyEnd);
+        if (body[i] !== ":")
+            return undefined;
+        const valueStart = skipWhitespace(body, i + 1);
+        const valueEnd = skipValue(body, valueStart);
+        if (valueEnd === undefined)
+            return undefined;
+        if (name === key)
+            return [valueStart, valueEnd];
+        i = skipWhitespace(body, valueEnd);
+        if (body[i] === ",") {
+            i = skipWhitespace(body, i + 1);
+            continue;
+        }
+        return undefined;
+    }
+}
+/** RFC 8259 whitespace, and nothing wider — the same four bytes the blank-schema
+ * rule counts. */
+function skipWhitespace(body, i) {
+    while (i < body.length) {
+        const c = body[i];
+        if (c !== " " && c !== "\t" && c !== "\r" && c !== "\n")
+            return i;
+        i++;
+    }
+    return i;
+}
+/** skipString returns the index just past a JSON string starting at `i`. */
+function skipString(body, i) {
+    i++; // the opening quote
+    while (i < body.length) {
+        const c = body[i];
+        if (c === "\\") {
+            i += 2;
+            continue;
+        }
+        if (c === '"')
+            return i + 1;
+        i++;
+    }
+    return i;
+}
+/** skipValue returns the index just past the JSON value starting at `i`, or
+ * `undefined` when the value does not terminate. */
+function skipValue(body, i) {
+    const c = body[i];
+    if (c === '"')
+        return skipString(body, i);
+    if (c === "{" || c === "[") {
+        const close = c === "{" ? "}" : "]";
+        let depth = 0;
+        while (i < body.length) {
+            const ch = body[i];
+            if (ch === '"') {
+                i = skipString(body, i);
+                continue;
+            }
+            if (ch === "{" || ch === "[")
+                depth++;
+            else if (ch === "}" || ch === "]") {
+                depth--;
+                if (depth === 0) {
+                    return body[i] === close ? i + 1 : undefined;
+                }
+            }
+            i++;
+        }
+        return undefined;
+    }
+    // A number, or one of the three literals: everything up to the next structural
+    // character. The body has already parsed, so whatever lies here is well formed.
+    const end = /[\s,}\]]/.exec(body.slice(i));
+    return end === null ? body.length : i + end.index;
+}

package/sdk/ts/resolvers/ssrf.d.ts

@@ -0,0 +1,28 @@
+/** The scheme allowlist the SSRF guard enforces: deny-by-default, only http and
+ * https may be dialed (mirrors the Go oracle's allowedScheme). Blocks
+ * file/data/gopher/dict/ftp/ldap and every other exotic scheme that would let a
+ * caller-supplied URL reach the local filesystem or unintended protocols. The
+ * comparison is case-insensitive (HTTPS ≡ https). */
+export declare function allowedScheme(scheme: string): boolean;
+/** The shared redirect-depth cap. Deny-by-default and IDENTICAL across the three
+ * SDKs (Go maxWBARedirects / httpx max_redirects): the guarded transport follows at
+ * most this many redirect hops and refuses the next, so no SDK inherits its HTTP
+ * library's looser default (undici/fetch follow ~20). The real transport enforces
+ * it via undici's `interceptors.redirect({ maxRedirections })`; the corpus pins the
+ * predicate below. */
+export declare const MAX_REDIRECTS = 5;
+/** Report whether a chain of `hops` redirects must be refused — the shared
+ * redirect-depth policy (refused iff it EXCEEDS MAX_REDIRECTS). Corpus-tested
+ * against the Go oracle's redirectChainRefused so the three SDKs agree on the
+ * boundary. */
+export declare function redirectChainRefused(hops: number): boolean;
+/** Reports whether `ip` (a numeric IPv4 or IPv6 literal — never a hostname) is
+ * a reserved / non-public address the SSRF guard must refuse to dial. It first
+ * unwraps v4-mapped and NAT64 forms and re-checks the embedded v4, so an IPv6
+ * literal embedding a private v4 cannot slip past a v6-only test. An
+ * unparseable input is treated as blocked (fail-closed: never dial what we
+ * cannot classify). */
+export declare function blockedAddress(ip: string): boolean;
+/** Parse an IPv4 or IPv6 literal into its network-order bytes (4 or 16), or
+ * `undefined` when it is not a bare numeric address. */
+export declare function parseAddr(ip: string): Uint8Array | undefined;

package/sdk/ts/resolvers/ssrf.js

@@ -0,0 +1,235 @@
+// The SSRF address guard for the fetching resolvers' DEFAULT transport. Ports
+// sdk/go/helpers/wbakeyresolver.go (ssrfBlockedPrefixes / ssrfBlocked) 1:1.
+//
+// A WBA/well-known resolver fetches a directory from a caller-supplied
+// Signature-Agent host BEFORE the ed25519 signature check, so an unguarded
+// default is a pre-auth SSRF lever against internal networks. blockedAddress is
+// the reserved / non-public address predicate the guarded default transport
+// applies to EVERY resolved address before connecting. It replaces the
+// IsPrivate/IsLinkLocal heuristic, which misses CGNAT (100.64.0.0/10),
+// 0.0.0.0/8, the TEST-NETs, benchmarking, protocol-assignment, and other
+// reserved ranges. IPv4-mapped (::ffff:a.b.c.d) and NAT64 (64:ff9b::a.b.c.d)
+// forms are unwrapped and their embedded v4 re-checked, so an IPv6 literal
+// cannot smuggle a private v4 past a v6-form-only test.
+/** The scheme allowlist the SSRF guard enforces: deny-by-default, only http and
+ * https may be dialed (mirrors the Go oracle's allowedScheme). Blocks
+ * file/data/gopher/dict/ftp/ldap and every other exotic scheme that would let a
+ * caller-supplied URL reach the local filesystem or unintended protocols. The
+ * comparison is case-insensitive (HTTPS ≡ https). */
+export function allowedScheme(scheme) {
+    const s = scheme.toLowerCase();
+    return s === "http" || s === "https";
+}
+/** The shared redirect-depth cap. Deny-by-default and IDENTICAL across the three
+ * SDKs (Go maxWBARedirects / httpx max_redirects): the guarded transport follows at
+ * most this many redirect hops and refuses the next, so no SDK inherits its HTTP
+ * library's looser default (undici/fetch follow ~20). The real transport enforces
+ * it via undici's `interceptors.redirect({ maxRedirections })`; the corpus pins the
+ * predicate below. */
+export const MAX_REDIRECTS = 5;
+/** Report whether a chain of `hops` redirects must be refused — the shared
+ * redirect-depth policy (refused iff it EXCEEDS MAX_REDIRECTS). Corpus-tested
+ * against the Go oracle's redirectChainRefused so the three SDKs agree on the
+ * boundary. */
+export function redirectChainRefused(hops) {
+    return hops > MAX_REDIRECTS;
+}
+// The reserved / non-public prefix set the guard rejects — the EXACT set the Go
+// oracle rejects (ssrfBlockedPrefixes), split v4 / v6.
+const BLOCKED_CIDRS = [
+    // IPv4
+    "0.0.0.0/8",
+    "10.0.0.0/8",
+    "100.64.0.0/10",
+    "127.0.0.0/8",
+    "169.254.0.0/16",
+    "172.16.0.0/12",
+    "192.0.0.0/24",
+    "192.0.2.0/24",
+    "192.88.99.0/24",
+    "192.168.0.0/16",
+    "198.18.0.0/15",
+    "198.51.100.0/24",
+    "203.0.113.0/24",
+    "224.0.0.0/4",
+    "240.0.0.0/4",
+    "255.255.255.255/32",
+    // IPv6
+    "::/128",
+    "::1/128",
+    // IPv4-compatible IPv6 (::a.b.c.d) — deprecated; block the whole ::/96 so an
+    // embedded v4 cannot smuggle a reserved address through a v6 literal.
+    "::/96",
+    "100::/64",
+    "2001:db8::/32",
+    "2001::/23",
+    // 6to4 (RFC 3056) — block wholesale; a 2002:V4ADDR:: literal embeds an
+    // arbitrary v4 in bits 16..48 and must never be dialed.
+    "2002::/16",
+    "fc00::/7",
+    "fe80::/10",
+    "ff00::/8",
+    // NAT64 (the /96 well-known prefix's embedded v4 is also re-checked below)
+    "64:ff9b::/96",
+    "64:ff9b:1::/48",
+];
+// The well-known NAT64 prefix (RFC 6052). An address inside it embeds an IPv4
+// in its trailing 32 bits, which must be re-checked for reserved-ness.
+const NAT64_WELL_KNOWN = parseCidr("64:ff9b::/96");
+const BLOCKED_PARSED = BLOCKED_CIDRS.map(parseCidr);
+/** Reports whether `ip` (a numeric IPv4 or IPv6 literal — never a hostname) is
+ * a reserved / non-public address the SSRF guard must refuse to dial. It first
+ * unwraps v4-mapped and NAT64 forms and re-checks the embedded v4, so an IPv6
+ * literal embedding a private v4 cannot slip past a v6-only test. An
+ * unparseable input is treated as blocked (fail-closed: never dial what we
+ * cannot classify). */
+export function blockedAddress(ip) {
+    const addr = parseAddr(ip);
+    if (!addr)
+        return true;
+    return blockedBytes(addr);
+}
+function blockedBytes(addr) {
+    // Unwrap an IPv4-mapped IPv6 (::ffff:a.b.c.d) to its 4-byte form so the v4
+    // prefix table applies. Then, for any remaining 16-byte address, re-check a
+    // NAT64-embedded v4 before the prefix scan.
+    const unmapped = unmapV4(addr);
+    if (unmapped.length === 16) {
+        const embedded = nat64EmbeddedV4(unmapped);
+        if (embedded && blockedBytes(embedded))
+            return true;
+    }
+    for (const cidr of BLOCKED_PARSED) {
+        if (cidr.bytes.length === unmapped.length && contains(cidr, unmapped))
+            return true;
+    }
+    return false;
+}
+/** Extract the trailing 32 bits of a 64:ff9b::/96 address as a 4-byte v4, or
+ * `undefined` when `addr` is not in the well-known NAT64 prefix. */
+function nat64EmbeddedV4(addr) {
+    if (!contains(NAT64_WELL_KNOWN, addr))
+        return undefined;
+    return addr.slice(12, 16);
+}
+/** Unwrap an IPv4-mapped IPv6 address (::ffff:a.b.c.d) to its 4-byte v4 form;
+ * pass any other address through unchanged. */
+function unmapV4(addr) {
+    if (addr.length !== 16)
+        return addr;
+    for (let i = 0; i < 10; i++)
+        if (addr[i] !== 0)
+            return addr;
+    if (addr[10] !== 0xff || addr[11] !== 0xff)
+        return addr;
+    return addr.slice(12, 16);
+}
+/** Whether `addr` (same byte-length as the CIDR) falls inside `cidr` — a masked
+ * byte comparison over the prefix length. */
+function contains(cidr, addr) {
+    if (addr.length !== cidr.bytes.length)
+        return false;
+    let bits = cidr.bits;
+    for (let i = 0; i < cidr.bytes.length; i++) {
+        if (bits <= 0)
+            break;
+        const take = bits >= 8 ? 8 : bits;
+        const mask = take === 8 ? 0xff : (0xff << (8 - take)) & 0xff;
+        if ((addr[i] & mask) !== (cidr.bytes[i] & mask))
+            return false;
+        bits -= 8;
+    }
+    return true;
+}
+function parseCidr(cidr) {
+    const slash = cidr.lastIndexOf("/");
+    const addrPart = cidr.slice(0, slash);
+    const bits = Number(cidr.slice(slash + 1));
+    const bytes = parseAddr(addrPart);
+    if (!bytes)
+        throw new Error(`ssrf: unparseable CIDR ${cidr}`);
+    return { bytes, bits };
+}
+/** Parse an IPv4 or IPv6 literal into its network-order bytes (4 or 16), or
+ * `undefined` when it is not a bare numeric address. */
+export function parseAddr(ip) {
+    if (ip.includes(":"))
+        return parseV6(ip);
+    return parseV4(ip);
+}
+function parseV4(ip) {
+    const parts = ip.split(".");
+    if (parts.length !== 4)
+        return undefined;
+    const out = new Uint8Array(4);
+    for (let i = 0; i < 4; i++) {
+        const p = parts[i];
+        if (!/^\d{1,3}$/.test(p))
+            return undefined;
+        const n = Number(p);
+        if (n > 255)
+            return undefined;
+        out[i] = n;
+    }
+    return out;
+}
+function parseV6(ip) {
+    // Strip a zone id (fe80::1%eth0) — irrelevant to the prefix check.
+    const zone = ip.indexOf("%");
+    if (zone >= 0)
+        ip = ip.slice(0, zone);
+    const halves = ip.split("::");
+    if (halves.length > 2)
+        return undefined;
+    const head = halves[0] === "" ? [] : halves[0].split(":");
+    const tailStr = halves.length === 2 ? halves[1] : undefined;
+    const tail = tailStr === undefined || tailStr === "" ? [] : tailStr.split(":");
+    const out = new Uint8Array(16);
+    let idx = 0;
+    const writeGroups = (groups, start) => {
+        let pos = start;
+        for (let g = 0; g < groups.length; g++) {
+            const grp = groups[g];
+            // A trailing IPv4 in the last group (e.g. ::ffff:1.2.3.4 or 64:ff9b::a.b.c.d).
+            if (grp.includes(".")) {
+                if (g !== groups.length - 1)
+                    return false;
+                const v4 = parseV4(grp);
+                if (!v4)
+                    return false;
+                if (pos + 4 > 16)
+                    return false;
+                out.set(v4, pos);
+                pos += 4;
+                continue;
+            }
+            if (!/^[0-9a-fA-F]{1,4}$/.test(grp))
+                return false;
+            if (pos + 2 > 16)
+                return false;
+            const val = parseInt(grp, 16);
+            out[pos] = (val >> 8) & 0xff;
+            out[pos + 1] = val & 0xff;
+            pos += 2;
+        }
+        return true;
+    };
+    // Count the bytes each side occupies (an embedded v4 counts as 4, not 2).
+    const byteLen = (groups) => groups.reduce((n, g) => n + (g.includes(".") ? 4 : 2), 0);
+    if (halves.length === 1) {
+        // No "::" — must be a full address.
+        if (byteLen(head) !== 16)
+            return undefined;
+        return writeGroups(head, 0) ? out : undefined;
+    }
+    const headBytes = byteLen(head);
+    const tailBytes = byteLen(tail);
+    if (headBytes + tailBytes > 16)
+        return undefined;
+    if (!writeGroups(head, 0))
+        return undefined;
+    idx = 16 - tailBytes;
+    if (!writeGroups(tail, idx))
+        return undefined;
+    return out;
+}

package/sdk/ts/resolvers/static.d.ts

@@ -0,0 +1,7 @@
+/** The static key face. */
+export interface StaticKeyResolver {
+    resolve(keyid: string): Promise<Uint8Array | undefined>;
+    put(keyid: string, pub: Uint8Array): void;
+}
+/** Return a resolver seeded with `keys` (copied). */
+export declare function createStaticKeyResolver(keys?: Record<string, Uint8Array>): StaticKeyResolver;

package/sdk/ts/resolvers/static.js

@@ -0,0 +1,16 @@
+// The static named key resolver face — a thin in-memory map satisfying the
+// RequestKeyResolver-shaped `resolve(keyid) -> Promise<Uint8Array | undefined>` plus a
+// `put` for dynamic/test seeding. Mirrors the Go NewStaticKeyResolver: a plain
+// unknown key is `undefined` (the fall-through miss), never a thrown error.
+/** Return a resolver seeded with `keys` (copied). */
+export function createStaticKeyResolver(keys = {}) {
+    const map = new Map(Object.entries(keys));
+    return {
+        resolve(keyid) {
+            return Promise.resolve(map.get(keyid));
+        },
+        put(keyid, pub) {
+            map.set(keyid, pub);
+        },
+    };
+}

package/sdk/ts/resolvers/wba.d.ts

@@ -0,0 +1,134 @@
+import { WBAFileSchema } from "../../../gen/ts/wire/schemas.ts";
+import { type FetchLike } from "./http.ts";
+/** The single public well-known path a WBA identity directory is served at (Web
+ * Bot Auth; the identity half of the identity/commercial split — the commercial
+ * overlay stays in /.well-known/fora.json). The one shared copy across the whole SDK. */
+export declare const WBA_DIRECTORY_PATH = "/.well-known/http-message-signatures-directory";
+/** Build the full WBA identity-directory URL from a scheme and an already-joined
+ * host: `${scheme}://${host}` + {@link WBA_DIRECTORY_PATH}. An empty scheme
+ * defaults to https. A PURE string function — the host arrives ALREADY-JOINED (any
+ * port-join / IPv6 bracketing is the caller's concern), there is NO env read and NO
+ * scheme-in-host detection (those stay consumer glue). It mirrors the sdk/go
+ * WBADirectoryURL oracle byte-for-byte, locked by the tri-replayed
+ * wba-url-vectors.json corpus. */
+export declare function wbaDirectoryURL(scheme: string, host: string): string;
+type WBAFile = ReturnType<typeof WBAFileSchema.parse>;
+/** Options for the WBA resolver. Zero values are safe defaults; tests inject the
+ * clock (`now`), the poll timer (`after`), and the armed/cycle seams. */
+export interface WBAKeyResolverOptions {
+    scheme?: string;
+    ttlMs?: number;
+    pollIntervalMs?: number;
+    /** Throttle for the unknown-thumbprint force-refresh, per directory host (≤0 →
+     * 5000). The resolver runs BEFORE the ed25519 check and the host is the
+     * caller-supplied Signature-Agent, so this caps the outbound directory GETs an
+     * unauthenticated caller can drive by presenting unknown thumbprints. The
+     * TTL-cache refresh path is NOT gated by it. */
+    syncDebounceMs?: number;
+    /** When set, `resolve` fails closed with RevocationUnevaluated for a key whose
+     * directory declares a revocation_url but no snapshot has been fetched
+     * (unreachable or not host-anchored) — i.e. revocation could not be evaluated.
+     * Default false keeps the best-effort behavior (a declared-but-unreachable
+     * revocation channel does not block resolution). Set it where a revoked key
+     * must never resolve even if the revocation channel is down. */
+    requireRevocation?: boolean;
+    now?: () => number;
+    after?: (ms: number) => Promise<void>;
+    onPollArmed?: () => void;
+    onPollCycle?: () => void;
+    fetch?: FetchLike;
+}
+/** The WBA key face. `resolve` returns the raw Ed25519 public key, `undefined`
+ * for an unknown/absent thumbprint (fall-through), and throws KeyRevoked /
+ * KeyExpired / DirectoryUnavailable for the distinct fail-closed verdicts. */
+export interface WBAKeyResolver {
+    resolve(thumbprint: string, directory: string): Promise<Uint8Array | undefined>;
+    run(signal: AbortSignal): Promise<void>;
+    /** Whether `keyId` (a thumbprint) is in ANY host's fetched revocation snapshot,
+     * INDEPENDENT of WBA directory membership. `resolve` gates a key only when the
+     * directory lists it (removal is not revocation), so a key resolved from another
+     * source — e.g. a static bootstrap file — is invisible to that path; `revoked`
+     * is the fail-closed hook a composite consults to reject a broker-revoked,
+     * directory-absent thumbprint. False when no snapshot has been fetched. */
+    revoked(keyId: string): boolean;
+}
+/** Construct a WBA resolver with defaults applied. */
+export declare function createWBAKeyResolver(opts?: WBAKeyResolverOptions): WBAKeyResolver;
+/** First window-active, well-formed Ed25519 key (raw 32 bytes) from `directory`,
+ * or `null`. Selects an identity's signing key BY DOCUMENT ORDER when its thumbprint
+ * is not known ahead of time — complementing WBAKeyResolver, which matches a KNOWN
+ * thumbprint. Iterates the directory's keys in document order and returns the FIRST
+ * key that passes ALL of: window-active ([not_before, not_after) half-open covers
+ * `now` (epoch-ms), both bounds RFC 3339-parseable — a missing/unparseable bound
+ * makes the key inactive); `kty === "OKP"` and `crv === "Ed25519"` matched
+ * CASE-INSENSITIVELY (a deliberate lenient SDK convention: RFC 7517/8037 specify the
+ * exact-case "OKP" / "Ed25519", but all three SDKs accept any case IDENTICALLY so a
+ * case-varying directory resolves the SAME key everywhere); and a present `x` that
+ * base64url-decodes to exactly 32 bytes. Any key failing any check is skipped and
+ * iteration continues.
+ *
+ * The result is the first window-active key in document order — this SDK's
+ * deterministic tie-break, NOT a normative "current" key: the protocol permits
+ * several simultaneously-active keys during overlap rotation and defines no "first".
+ *
+ * `maxScan` is an OPTIONAL document-order bound. `undefined` (the default) scans the
+ * WHOLE directory — unbounded, so a valid key at any position is reachable; a silent
+ * cap would make a high-position key indistinguishable from "no active key" (a
+ * DoS-by-directory-padding footgun). A defined bound caps the scan at
+ * `Math.max(0, maxScan)` keys (0 or negative scans none); when a positive bound is
+ * exhausted while more keys remain, the exhaustion is logged. Returns `null` when no
+ * examined key qualifies (or `directory` is null/undefined). Byte-parity with the
+ * Go `ActiveEd25519Key` / Python `active_ed25519_key` oracles.
+ *
+ * REVOCATION: this selector screens ONLY validity windows and key well-formedness —
+ * it does NOT consult any revocation channel. A key that was emergency-revoked but
+ * is still window-active in a (possibly CDN-cached) directory WILL be selected. A
+ * caller on a VERIFICATION path MUST NOT trust the result until it has screened the
+ * selected key's RFC 7638 thumbprint against the resolver's revoked-thumbprint set
+ * (`WBAKeyResolver.revoked` / a revocation snapshot); otherwise adopting this
+ * selector defeats emergency revocation. Prefer {@link activeEd25519KeyScreened},
+ * which folds that screen into selection. This bare form is for non-verification
+ * callers only. */
+export declare function activeEd25519Key(directory: WBAFile, now: number, maxScan?: number): Uint8Array | null;
+/** Like {@link activeEd25519Key}, but ALSO returns the selected key's expiry.
+ * Runs the IDENTICAL document-order selection and returns `{ key, notAfter }` for
+ * the FIRST qualifying key — the raw 32 bytes plus the SAME `not_after` the window
+ * check parsed, as epoch-ms (the module's time convention). A downstream caller
+ * (e.g. an offer-key cache) clamps its cache TTL to `min(now + ttl, notAfter)` so
+ * a cached key never outlives its validity window. `notAfter` is guaranteed
+ * finite — selection required it (a key with a missing/unparseable bound is
+ * inactive and skipped). Returns `null` when no examined key qualifies.
+ * Byte-parity with the Go `ActiveEd25519KeyWithExpiry` / Python
+ * `active_ed25519_key_with_expiry` oracles.
+ *
+ * REVOCATION: like {@link activeEd25519Key}, this bare form does NOT consult
+ * revocation — it can return a window-active-but-revoked key. A VERIFICATION path
+ * MUST screen the result, or use the revocation-aware
+ * {@link activeEd25519KeyWithExpiryScreened} instead. */
+export declare function activeEd25519KeyWithExpiry(directory: WBAFile, now: number, maxScan?: number): {
+    key: Uint8Array;
+    notAfter: number;
+} | null;
+/** {@link activeEd25519Key} made REVOCATION-AWARE. Runs the same document-order
+ * window + well-formedness selection but ALSO skips any key whose RFC 7638
+ * thumbprint `revoked` reports true, so a window-active-but-revoked key is never
+ * returned. It is the selector a VERIFICATION path adopts — folding the revoked-set
+ * screen the bare {@link activeEd25519Key} leaves to the caller into selection
+ * itself, so an emergency-revoked key still listed in a CDN-cached directory is
+ * passed over for the next active, non-revoked key. `revoked` is REQUIRED: pass a
+ * predicate over the resolver's revoked-thumbprint set (e.g. `WBAKeyResolver.revoked`)
+ * or, for a caller with no revocation channel, an explicit `() => false` to make the
+ * waiver visible. It is ASYNC because screening computes each candidate's RFC 7638
+ * thumbprint (the SAME `crypto.subtle` primitive `WBAKeyResolver.resolve` keys on).
+ * Returns `null` when no examined, non-revoked key qualifies. */
+export declare function activeEd25519KeyScreened(directory: WBAFile, now: number, revoked: (thumbprint: string) => boolean, maxScan?: number): Promise<Uint8Array | null>;
+/** {@link activeEd25519KeyWithExpiry} made REVOCATION-AWARE (see
+ * {@link activeEd25519KeyScreened}): the same selection, plus a skip of any key whose
+ * RFC 7638 thumbprint `revoked` reports true, returned with the selected key's
+ * `notAfter` for cache-TTL clamping. `revoked` is REQUIRED; ASYNC for the same
+ * thumbprint reason. Returns `null` when no examined, non-revoked key qualifies. */
+export declare function activeEd25519KeyWithExpiryScreened(directory: WBAFile, now: number, revoked: (thumbprint: string) => boolean, maxScan?: number): Promise<{
+    key: Uint8Array;
+    notAfter: number;
+} | null>;
+export {};