@ixo/decision-oracle 0.0.0-stage → 0.2.1

package/dist/lib/hash.js

@@ -0,0 +1,80 @@
+/**
+ * Generic content hashing. `sha256Hex` is the one primitive several unrelated corners share —
+ * rubric ids (§A.10), UCAN token cache keys, claim workflow ids — so it lives in a neutral home
+ * rather than inside any one of them (e.g. rubric resolution should not reach into `ixo/ucan` for
+ * a hash). `cidForBytes` is the claim lane's content address, kept beside it for the same reason.
+ */
+import { CID } from "multiformats/cid";
+import { create as digestOf } from "multiformats/hashes/digest";
+import { sha256 } from "multiformats/hashes/sha2";
+/** Hex SHA-256 of a string or raw bytes (cache keys, rubric ids — never for secrets in logs). */
+export async function sha256Hex(input) {
+    const bytes = typeof input === "string" ? new TextEncoder().encode(input) : input;
+    const digest = await crypto.subtle.digest("SHA-256", bytes);
+    return [...new Uint8Array(digest)].map((b) => b.toString(16).padStart(2, "0")).join("");
+}
+/**
+ * Canonical JSON: recursively sorted keys, no whitespace — so the same value always serializes to
+ * the same bytes. Feeds `resultDigest = sha256(canonicalJson(decision + trace))` (evaluator §9),
+ * the same convention the editor uses to make a rubric's id stable.
+ */
+export function canonicalJson(value) {
+    return JSON.stringify(sortKeys(value));
+}
+function sortKeys(value) {
+    if (Array.isArray(value))
+        return value.map(sortKeys);
+    if (value !== null && typeof value === "object") {
+        const out = {};
+        for (const key of Object.keys(value).sort()) {
+            const v = value[key];
+            if (v !== undefined)
+                out[key] = sortKeys(v);
+        }
+        return out;
+    }
+    return value;
+}
+/**
+ * The Decision API claim's content id (contract "The claim content and `contentDigest`"): the SAME
+ * function the engine and the client SDK run, held to `test/fixtures/content-digest-vectors.json`.
+ * Not the idempotency `requestDigest` — that one covers the transport too. Key order is JavaScript's
+ * (integer-like keys first, ascending; then the rest by UTF-16 code unit): a non-JS implementation
+ * must reproduce it — the vectors pin it.
+ */
+export async function contentDigest(content) {
+    return `sha256:${await sha256Hex(canonicalJson(content))}`;
+}
+/**
+ * The claim lane's content address — CIDv1, `raw` codec (0x55), sha2-256, base32 (`bafkrei…`).
+ * A claim's id IS this CID of its stored body: `ixo-oracles-cli/src/utils/createCIDFromBase64.ts`
+ * builds exactly `CID.create(1, 0x55, sha256(bytes))`, and the Matrix claim bot's `generateCid`
+ * (`ipfs-only-hash` with `cidVersion:1, rawLeaves:true, leafType:'raw'`) produces the identical
+ * string up to its 256 KiB chunk size (beyond it the importer builds a dag-pb root, so a larger body
+ * never matches — ENGINE-CONTRACT treats it as unverifiable). The cellnode lane verifies a body against its claim id with
+ * this (ixo/cellnode.ts) — so it must be byte-identical to the fleet's, hence `multiformats`
+ * rather than a hand-rolled base32: a subtle encoder bug would only surface as every cellnode
+ * claim failing closed.
+ *
+ * NOT the rubric convention: the portal's `publicUploadToMatrix` returns a bare hex sha256 it
+ * calls a "simplified CID", which is why `rubricId` is hex.
+ */
+export async function cidForBytes(bytes) {
+    const digest = await sha256.digest(bytes);
+    return CID.create(1, 0x55, digest).toString();
+}
+/** The same CID from a sha2-256 digest already computed — for bytes hashed incrementally as they
+ *  stream (the data export, `routes/v1/api/export.ts`), never held whole. */
+export function cidForSha256(digest) {
+    return CID.create(1, 0x55, digestOf(sha256.code, digest)).toString();
+}
+/** Chunked btoa — platform-native base64 without blowing the stack on a large attachment. */
+export function base64Of(bytes) {
+    let binary = "";
+    const chunk = 0x8000;
+    for (let i = 0; i < bytes.length; i += chunk) {
+        binary += String.fromCharCode(...bytes.subarray(i, i + chunk));
+    }
+    return btoa(binary);
+}
+//# sourceMappingURL=hash.js.map

package/dist/lib/hash.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hash.js","sourceRoot":"","sources":["../../src/lib/hash.ts"],"names":[],"mappings":"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"}

package/dist/lib/http/client.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Outbound HTTP client — the ONE place for the three policies every external call needs: a hard
+ * timeout (a hung upstream must never hang a Worker), optional bounded retries, and traceparent
+ * propagation. Explicit per-call config over named wrappers: the call site says what it wants.
+ *
+ * Built on the platform-native `fetch` — on Workers any HTTP library is a wrapper over this same
+ * primitive, so we keep zero dependencies and full control of the retry/timeout semantics.
+ */
+import { type TraceContext } from "../tracing.js";
+/**
+ * A request that is not a `fetch` — the AI Gateway binding (lib/facts/stock/ai-provider.ts). It is
+ * handed this attempt's abort signal and timeout, and gets the same retry, backoff and `upstream`
+ * metric as a fetch.
+ */
+export type Transport = (signal: AbortSignal, timeoutMs: number) => Promise<Response>;
+export interface FetchClientConfig extends RequestInit {
+    /** Abort the attempt after this many ms. */
+    timeoutMs?: number;
+    /**
+     * Total attempts, default 1 (no retry). Set > 1 ONLY for idempotent calls — a single-use request
+     * (e.g. a UCAN Store invocation, replay ON) must never be re-sent with the same body; its caller
+     * re-mints and calls again instead.
+     */
+    attempts?: number;
+    /** Propagate this trace as a `traceparent` header. */
+    trace?: TraceContext;
+    /**
+     * Send through this instead of `fetch` (the AI Gateway binding): `url` then only names the call
+     * (the metric's `op`), and the request is the transport's own.
+     */
+    send?: Transport;
+}
+/**
+ * Fetch with timeout/retry/tracing policy. Retries on network errors and transient statuses
+ * (408/429/5xx) with exponential backoff, and returns the last Response even when non-ok — the
+ * caller decides how a status maps to an AppError.
+ */
+export declare function fetchClient(url: string, config?: FetchClientConfig): Promise<Response>;
+/**
+ * A redirect `fetchGuarded` will not follow. Deterministic — the same hop answers the same way on
+ * every attempt — so a caller records it as an outcome and never retries it.
+ */
+export declare class RedirectRefused extends Error {
+    readonly target?: string | undefined;
+    name: string;
+    /** The refused hop's origin, when it was public and refused only for being another origin. */
+    constructor(message: string, target?: string | undefined);
+}
+export interface GuardedFetchConfig extends Omit<FetchClientConfig, "redirect" | "send" | "headers" | "body" | "method"> {
+    method?: "GET" | "HEAD" | "POST";
+    headers?: Record<string, string>;
+    /** Re-sent on a 307/308 hop, so it must be replayable — a string, never a stream. */
+    body?: string;
+    /** The whole walk ends by this epoch-ms; each hop's timeout is capped by what is left of it. */
+    deadline?: number;
+    /**
+     * The request IS the delivery (a signed webhook envelope): it reaches the first URL's own origin
+     * exactly as sent, or not at all. A hop to another origin is refused — stripping the signature
+     * would still hand the body to a host nobody registered — and every hop re-sends the same method
+     * and body, since a POST turned into a body-less GET would "succeed" without delivering anything.
+     */
+    exact?: boolean;
+}
+/**
+ * `fetchClient` with redirects followed BY HAND (`redirect: "manual"`). The platform would follow a
+ * 3xx to anywhere, and the caller's check of the FIRST URL (`assertPublicHttpUrl`) says nothing
+ * about where a public host bounces us next — `302 → http://169.254.169.254/` is the classic. So
+ * every hop is re-checked, at most `MAX_REDIRECTS` of them; an https → http downgrade and an
+ * unparseable `Location` are refused; and a hop to another origin carries NONE of the caller's
+ * headers but `accept`/`content-type` — a store's bearer token, a UCAN minted for the first host's
+ * did:web, a vendor `x-api-key` all belong to the first origin. A 303 — and a 301/302 answering a
+ * POST — continues as a body-less GET, as browsers do (unless `exact`).
+ *
+ * The first URL is the CALLER's to vet (a submitter's attachment URL is, a rubric-authored ext
+ * source is owner-trusted). `attempts` retries each hop's transient failures inside `fetchClient`;
+ * a refused hop throws `RedirectRefused` from out here, after the hop's response, so it is never
+ * re-run by those retries.
+ */
+export declare function fetchGuarded(url: string, config?: GuardedFetchConfig): Promise<Response>;
+/**
+ * The cap for the JSON documents the engine reads off a chain-anchored `serviceEndpoint` (rubric,
+ * claim form, agent card). The kitchen-sink rubric fixture is 23 KB and the kitchen-sink SurveyJS
+ * form 4 KB, so 2 MiB is ~90x the largest document anyone actually authors — generous enough never
+ * to bite a real author, small enough that a hostile endpoint cannot walk a 128 MB isolate to OOM.
+ */
+export declare const MAX_JSON_DOC_BYTES: number;
+/**
+ * Read a response body under a hard byte cap — `null` means "too large", which each caller turns
+ * into its own fail-closed outcome. Same shape as `fetchAttachmentBytes` (ixo/attachments.ts): the
+ * `content-length` pre-check means an oversized document is never buffered into the isolate just to
+ * be discarded, and the discarded body is cancelled rather than left to pin a connection.
+ *
+ * The cap is ALSO enforced while reading: these endpoints are anchored by a third party (and
+ * reachable unauthenticated via /v1/pricing), and a store that streams (the VFS) sends no
+ * `content-length` at all, so a missing or lying length is exactly the case that has to be
+ * survivable. The read stops one chunk past the cap — an oversized body is never counted to its end.
+ */
+export declare function readCappedBytes(res: Response, maxBytes: number): Promise<Uint8Array | null>;
+/**
+ * SSRF guard for a URL taken from claim content a **submitter** controls (a `mediaAttachment`
+ * `serviceEndpoint`/`url`, ixo/attachments.ts) — never for a rubric-authored ext-source endpoint,
+ * which is owner-trusted and already scoped by its own https-only policy
+ * (facts/stock/ext-source.ts `sourceEndpointUrl`). Rejects anything that isn't a public http(s)
+ * host: `localhost` and `*.localhost`, `.internal`/`.local` suffixes, and a bare IP in a
+ * private/loopback/link-local/unspecified range (an IPv4-mapped IPv6 literal checked as its IPv4).
+ * One trailing dot is stripped first — `localhost.` / `metadata.google.internal.` are the same
+ * host to a resolver. A literal-host check, not a DNS-rebinding-proof one — matches the review's own scoping.
+ * Throws `AppError.badRequest`: a bad attachment URL is a claim defect, not a crash.
+ */
+export declare function assertPublicHttpUrl(url: string): void;
+/** RFC 9110 `Retry-After`: delay-seconds or an HTTP-date → ms from now; undefined if absent/garbage. */
+export declare function parseRetryAfter(header: string | null, now?: number): number | undefined;
+//# sourceMappingURL=client.d.ts.map

package/dist/lib/http/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/lib/http/client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAIH,OAAO,EAAE,KAAK,YAAY,EAAe,MAAM,YAAY,CAAC;AAkB5D;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,CAAC,MAAM,EAAE,WAAW,EAAE,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,CAAC,CAAC;AAWtF,MAAM,WAAW,iBAAkB,SAAQ,WAAW;IACpD,4CAA4C;IAC5C,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,sDAAsD;IACtD,KAAK,CAAC,EAAE,YAAY,CAAC;IACrB;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;CAClB;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAAC,GAAG,EAAE,MAAM,EAAE,MAAM,GAAE,iBAAsB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAgDhG;AAQD;;;GAGG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IAKtC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM;IAJjB,IAAI,SAAqB;IAClC,8FAA8F;IAC9F,YACE,OAAO,EAAE,MAAM,EACN,MAAM,CAAC,EAAE,MAAM,YAAA,EAGzB;CACF;AAED,MAAM,WAAW,kBACf,SAAQ,IAAI,CAAC,iBAAiB,EAAE,UAAU,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,CAAC;IACpF,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,MAAM,CAAC;IACjC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,qFAAqF;IACrF,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gGAAgG;IAChG,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAsB,YAAY,CAChC,GAAG,EAAE,MAAM,EACX,MAAM,GAAE,kBAAuB,GAC9B,OAAO,CAAC,QAAQ,CAAC,CA8CnB;AAED;;;;;GAKG;AACH,eAAO,MAAM,kBAAkB,QAAkB,CAAC;AAElD;;;;;;;;;;GAUG;AACH,wBAAsB,eAAe,CAAC,GAAG,EAAE,QAAQ,EAAE,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,UAAU,GAAG,IAAI,CAAC,CA+BjG;AAwED;;;;;;;;;;GAUG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,CAuBrD;AAED,wGAAwG;AACxG,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI,EAAE,GAAG,SAAa,GAAG,MAAM,GAAG,SAAS,CAK3F"}

package/dist/lib/http/client.js

@@ -0,0 +1,330 @@
+/**
+ * Outbound HTTP client — the ONE place for the three policies every external call needs: a hard
+ * timeout (a hung upstream must never hang a Worker), optional bounded retries, and traceparent
+ * propagation. Explicit per-call config over named wrappers: the call site says what it wants.
+ *
+ * Built on the platform-native `fetch` — on Workers any HTTP library is a wrapper over this same
+ * primitive, so we keep zero dependencies and full control of the retry/timeout semantics.
+ */
+import { AppError } from "../errors.js";
+import { currentMetrics } from "../metrics.js";
+import { tracedFetch } from "../tracing.js";
+const DEFAULT_TIMEOUT_MS = 15_000;
+/**
+ * Workers' outbound `fetch` sends NO `User-Agent` of its own, and an empty UA is the first thing a
+ * WAF or a rate-limited public API blocks — CoinGecko answers one with a flat 403 ("please add a
+ * descriptive User-Agent"), which read here as an outage and silently zero-valued every uixo
+ * payment. So every call out of this Worker identifies itself and is contactable; a caller that
+ * needs its own UA still wins (set below only when absent).
+ */
+const USER_AGENT = "eval-oracle/1.0 (+https://github.com/ixofoundation/eval-oracle)";
+/** Transient upstream statuses worth retrying an idempotent call for. */
+const RETRYABLE_STATUS = new Set([408, 429, 500, 502, 503, 504]);
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/** Settles with `p`, or rejects the moment `signal` aborts — for a transport that might ignore it. */
+const abortable = (p, signal) => new Promise((resolve, reject) => {
+    if (signal.aborted)
+        return reject(signal.reason);
+    const onAbort = () => reject(signal.reason);
+    signal.addEventListener("abort", onAbort, { once: true });
+    p.then(resolve, reject).finally(() => signal.removeEventListener("abort", onAbort));
+});
+/**
+ * Fetch with timeout/retry/tracing policy. Retries on network errors and transient statuses
+ * (408/429/5xx) with exponential backoff, and returns the last Response even when non-ok — the
+ * caller decides how a status maps to an AppError.
+ */
+export async function fetchClient(url, config = {}) {
+    const { timeoutMs = DEFAULT_TIMEOUT_MS, attempts = 1, trace, signal, send, ...init } = config;
+    const headers = new Headers(init.headers);
+    if (!headers.has("user-agent"))
+        headers.set("user-agent", USER_AGENT);
+    // `upstream` into the invocation's ambient metrics, one point per call (not per attempt),
+    // labelled by host only — a path carries ids. A transport's name (`cf-aig:<gateway>/…`) has no
+    // host: its scheme stands in.
+    const started = Date.now();
+    const parsed = URL.parse(url);
+    const op = parsed?.hostname || parsed?.protocol.replace(/:$/, "");
+    const record = (status, outcome, tried) => currentMetrics()?.timing("upstream", Date.now() - started, {
+        op,
+        status,
+        outcome,
+        attempts: tried,
+    });
+    let lastError;
+    let attempt = 1;
+    for (; attempt <= attempts; attempt++) {
+        if (attempt > 1)
+            await sleep(200 * 2 ** (attempt - 2));
+        // Compose the caller's signal (if any) with this attempt's timeout.
+        const timeout = AbortSignal.timeout(timeoutMs);
+        const composed = signal ? AbortSignal.any([signal, timeout]) : timeout;
+        try {
+            const res = send
+                ? await abortable(send(composed, timeoutMs), composed)
+                : trace
+                    ? await tracedFetch(trace, url, { ...init, headers, signal: composed })
+                    : await fetch(url, { ...init, headers, signal: composed });
+            if (attempt < attempts && RETRYABLE_STATUS.has(res.status)) {
+                // An unconsumed body pins one of the isolate's 6 simultaneous connections until GC — a
+                // retry storm against a 5xx-ing upstream would otherwise stall concurrent fetches.
+                await res.body?.cancel().catch(() => { });
+                continue;
+            }
+            record(String(res.status), res.ok ? "ok" : "http_error", attempt);
+            return res;
+        }
+        catch (err) {
+            lastError = err;
+        }
+    }
+    // AbortSignal.timeout's reason is a DOMException named TimeoutError — match the name only.
+    const timedOut = lastError?.name === "TimeoutError";
+    record("network", timedOut ? "timeout" : "network_error", attempt - 1);
+    throw lastError ?? new Error(`fetchClient: all ${attempts} attempts failed for ${url}`);
+}
+/** Hops a guarded walk follows — fetch's own ceiling is 20; nothing legitimate needs four. */
+const MAX_REDIRECTS = 3;
+const REDIRECT_STATUS = new Set([301, 302, 303, 307, 308]);
+/** The only caller headers that follow a redirect to another origin — nothing that authenticates. */
+const CROSS_ORIGIN_HEADERS = new Set(["accept", "content-type"]);
+/**
+ * A redirect `fetchGuarded` will not follow. Deterministic — the same hop answers the same way on
+ * every attempt — so a caller records it as an outcome and never retries it.
+ */
+export class RedirectRefused extends Error {
+    target;
+    name = "RedirectRefused";
+    /** The refused hop's origin, when it was public and refused only for being another origin. */
+    constructor(message, target) {
+        super(message);
+        this.target = target;
+    }
+}
+/**
+ * `fetchClient` with redirects followed BY HAND (`redirect: "manual"`). The platform would follow a
+ * 3xx to anywhere, and the caller's check of the FIRST URL (`assertPublicHttpUrl`) says nothing
+ * about where a public host bounces us next — `302 → http://169.254.169.254/` is the classic. So
+ * every hop is re-checked, at most `MAX_REDIRECTS` of them; an https → http downgrade and an
+ * unparseable `Location` are refused; and a hop to another origin carries NONE of the caller's
+ * headers but `accept`/`content-type` — a store's bearer token, a UCAN minted for the first host's
+ * did:web, a vendor `x-api-key` all belong to the first origin. A 303 — and a 301/302 answering a
+ * POST — continues as a body-less GET, as browsers do (unless `exact`).
+ *
+ * The first URL is the CALLER's to vet (a submitter's attachment URL is, a rubric-authored ext
+ * source is owner-trusted). `attempts` retries each hop's transient failures inside `fetchClient`;
+ * a refused hop throws `RedirectRefused` from out here, after the hop's response, so it is never
+ * re-run by those retries.
+ */
+export async function fetchGuarded(url, config = {}) {
+    const { deadline, exact = false, timeoutMs = DEFAULT_TIMEOUT_MS, ...first } = config;
+    let { method = "GET", headers = {}, body, ...rest } = first;
+    let current = url;
+    for (let hop = 0;; hop++) {
+        const remaining = deadline === undefined ? timeoutMs : deadline - Date.now();
+        if (remaining <= 0)
+            throw new Error("call budget spent");
+        const res = await fetchClient(current, {
+            ...rest,
+            method,
+            headers,
+            ...(body === undefined ? {} : { body }),
+            timeoutMs: Math.min(timeoutMs, remaining),
+            redirect: "manual",
+        });
+        const location = res.headers.get("location");
+        if (!REDIRECT_STATUS.has(res.status) || !location)
+            return res;
+        await res.body?.cancel().catch(() => { });
+        if (hop >= MAX_REDIRECTS)
+            throw new RedirectRefused(`more than ${MAX_REDIRECTS} redirects`);
+        const here = new URL(current);
+        let next;
+        try {
+            next = new URL(location, here);
+            if (here.protocol === "https:" && next.protocol !== "https:")
+                throw new Error("downgrade");
+            assertPublicHttpUrl(next.href);
+        }
+        catch {
+            throw new RedirectRefused("redirect to a non-public or downgraded URL refused");
+        }
+        if (next.origin !== here.origin) {
+            if (exact)
+                throw new RedirectRefused("redirect to another origin refused", next.origin);
+            headers = Object.fromEntries(Object.entries(headers).filter(([k]) => CROSS_ORIGIN_HEADERS.has(k.toLowerCase())));
+        }
+        if (!exact &&
+            (res.status === 303 || ((res.status === 301 || res.status === 302) && method === "POST"))) {
+            method = "GET";
+            body = undefined;
+            headers = Object.fromEntries(Object.entries(headers).filter(([k]) => k.toLowerCase() !== "content-type"));
+        }
+        current = next.href;
+    }
+}
+/**
+ * The cap for the JSON documents the engine reads off a chain-anchored `serviceEndpoint` (rubric,
+ * claim form, agent card). The kitchen-sink rubric fixture is 23 KB and the kitchen-sink SurveyJS
+ * form 4 KB, so 2 MiB is ~90x the largest document anyone actually authors — generous enough never
+ * to bite a real author, small enough that a hostile endpoint cannot walk a 128 MB isolate to OOM.
+ */
+export const MAX_JSON_DOC_BYTES = 2 * 1024 * 1024;
+/**
+ * Read a response body under a hard byte cap — `null` means "too large", which each caller turns
+ * into its own fail-closed outcome. Same shape as `fetchAttachmentBytes` (ixo/attachments.ts): the
+ * `content-length` pre-check means an oversized document is never buffered into the isolate just to
+ * be discarded, and the discarded body is cancelled rather than left to pin a connection.
+ *
+ * The cap is ALSO enforced while reading: these endpoints are anchored by a third party (and
+ * reachable unauthenticated via /v1/pricing), and a store that streams (the VFS) sends no
+ * `content-length` at all, so a missing or lying length is exactly the case that has to be
+ * survivable. The read stops one chunk past the cap — an oversized body is never counted to its end.
+ */
+export async function readCappedBytes(res, maxBytes) {
+    const declared = Number(res.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > maxBytes) {
+        await res.body?.cancel().catch(() => { });
+        return null;
+    }
+    const reader = res.body?.getReader();
+    if (!reader)
+        return new Uint8Array(0);
+    const chunks = [];
+    let total = 0;
+    let done = false;
+    try {
+        let chunk = await reader.read();
+        while (!chunk.done) {
+            total += chunk.value.byteLength;
+            if (total > maxBytes)
+                return null;
+            chunks.push(chunk.value);
+            chunk = await reader.read();
+        }
+        done = true;
+    }
+    finally {
+        // Past the cap, or a read that threw mid-stream: release the connection either way.
+        if (!done)
+            await reader.cancel().catch(() => { });
+    }
+    const bytes = new Uint8Array(total);
+    let offset = 0;
+    for (const part of chunks) {
+        bytes.set(part, offset);
+        offset += part.byteLength;
+    }
+    return bytes;
+}
+const PRIVATE_HOST_SUFFIXES = [".internal", ".local"];
+/** IPv4 dotted-quad octets, when `host` is one — else null (a hostname, or an IPv6 literal). */
+function ipv4Octets(host) {
+    const m = host.match(/^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/);
+    if (!m)
+        return null;
+    const octets = [Number(m[1]), Number(m[2]), Number(m[3]), Number(m[4])];
+    return octets.every((o) => o <= 255) ? octets : null;
+}
+/**
+ * 0/8 ("this network" — `0.0.0.0` reaches the local host on Linux), 127/8, 10/8, 100.64/10
+ * (CGNAT — a provider's internal fabric), 172.16/12, 192.168/16, 169.254/16 (which also covers the
+ * 169.254.169.254 cloud metadata IP), 198.18/15 (benchmarking), and 224/4 + 240/4 (multicast,
+ * reserved, broadcast — never a web server).
+ */
+function isPrivateIpv4(host) {
+    const octets = ipv4Octets(host);
+    if (!octets)
+        return false;
+    const [a, b] = octets;
+    return (a === 0 ||
+        a === 127 ||
+        a === 10 ||
+        (a === 100 && b >= 64 && b <= 127) ||
+        (a === 172 && b >= 16 && b <= 31) ||
+        (a === 192 && b === 168) ||
+        (a === 169 && b === 254) ||
+        (a === 198 && (b === 18 || b === 19)) ||
+        a >= 224);
+}
+/**
+ * The IPv4 inside an IPv4-mapped IPv6 literal (`::ffff:a.b.c.d`), as dotted-quad — else null. The
+ * URL parser normalises the dotted form to hex (`[::ffff:127.0.0.1]` → `::ffff:7f00:1`), so both
+ * spellings are unwrapped; the mapped address reaches the IPv4 host, so it gets the IPv4 check.
+ */
+function mappedIpv4(host) {
+    const m = host.match(/^(?:::|(?:0{1,4}:){5})ffff:(.+)$/);
+    if (!m?.[1])
+        return null;
+    if (ipv4Octets(m[1]))
+        return m[1];
+    const hex = m[1].match(/^([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+    if (!hex?.[1] || !hex[2])
+        return null;
+    const hi = Number.parseInt(hex[1], 16);
+    const lo = Number.parseInt(hex[2], 16);
+    return `${hi >> 8}.${hi & 0xff}.${lo >> 8}.${lo & 0xff}`;
+}
+/**
+ * `::` (unspecified — reaches the local host like `0.0.0.0`), `::1` (loopback), `fc00::/7` (unique
+ * local), `fe80::/10` (link-local), and an IPv4-mapped address whose IPv4 is private.
+ * String-prefix, not a full parse; the URL parser has already compressed the literal.
+ */
+function isPrivateIpv6(host) {
+    const h = host.toLowerCase();
+    if (h === "::" || h === "::1" || h === "0:0:0:0:0:0:0:1")
+        return true;
+    // 64:ff9b::/96 — NAT64: the gateway translates it to the IPv4 in its low bits, private or not.
+    if (h.startsWith("64:ff9b::"))
+        return true;
+    const mapped = mappedIpv4(h);
+    if (mapped)
+        return isPrivateIpv4(mapped);
+    const firstGroup = h.split(":")[0] ?? "";
+    return /^fe[89ab][0-9a-f]{0,2}$/.test(firstGroup) || /^f[cd][0-9a-f]{0,2}$/.test(firstGroup);
+}
+/**
+ * SSRF guard for a URL taken from claim content a **submitter** controls (a `mediaAttachment`
+ * `serviceEndpoint`/`url`, ixo/attachments.ts) — never for a rubric-authored ext-source endpoint,
+ * which is owner-trusted and already scoped by its own https-only policy
+ * (facts/stock/ext-source.ts `sourceEndpointUrl`). Rejects anything that isn't a public http(s)
+ * host: `localhost` and `*.localhost`, `.internal`/`.local` suffixes, and a bare IP in a
+ * private/loopback/link-local/unspecified range (an IPv4-mapped IPv6 literal checked as its IPv4).
+ * One trailing dot is stripped first — `localhost.` / `metadata.google.internal.` are the same
+ * host to a resolver. A literal-host check, not a DNS-rebinding-proof one — matches the review's own scoping.
+ * Throws `AppError.badRequest`: a bad attachment URL is a claim defect, not a crash.
+ */
+export function assertPublicHttpUrl(url) {
+    let parsed;
+    try {
+        parsed = new URL(url);
+    }
+    catch {
+        throw AppError.badRequest(`URL is not valid: ${url}`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw AppError.badRequest(`URL must be http(s): ${url}`);
+    }
+    const host = parsed.hostname
+        .replace(/^\[|\]$/g, "")
+        .replace(/\.$/, "")
+        .toLowerCase();
+    const isPrivate = host === "localhost" ||
+        host.endsWith(".localhost") ||
+        PRIVATE_HOST_SUFFIXES.some((suffix) => host.endsWith(suffix)) ||
+        isPrivateIpv4(host) ||
+        isPrivateIpv6(host);
+    if (isPrivate) {
+        throw AppError.badRequest(`URL host is not publicly reachable: ${url}`);
+    }
+}
+/** RFC 9110 `Retry-After`: delay-seconds or an HTTP-date → ms from now; undefined if absent/garbage. */
+export function parseRetryAfter(header, now = Date.now()) {
+    if (!header)
+        return undefined;
+    if (/^\d+$/.test(header))
+        return Number(header) * 1000;
+    const at = Date.parse(header);
+    return Number.isNaN(at) ? undefined : Math.max(0, at - now);
+}
+//# sourceMappingURL=client.js.map

package/dist/lib/http/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../src/lib/http/client.ts"],"names":[],"mappings":"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"}

package/dist/lib/ids.d.ts

@@ -0,0 +1,17 @@
+/** Mapping a claimId to its workflow instance id. */
+/**
+ * The instance id for a claim: the claimId ITSELF whenever Cloudflare accepts it (every CID does —
+ * keeps "find the instance by its claim id" ergonomics in the dashboard), else its sha256 hex —
+ * which is exactly 64 chars of [0-9a-f], i.e. always a valid instance id, and deterministic so
+ * idempotency by id still holds. Real chain data REQUIRES the fallback: ~2% of devnet claimIds are
+ * Matrix event ids (`$…-<ts>`, >64 chars) that no prefix/truncation trick can carry. The ledger's
+ * `instance_id` column records the mapping, and `params.claimId` always carries the real id.
+ */
+export declare function instanceIdFor(claimId: string): Promise<string>;
+/**
+ * The ReviewComplete instance id for a claim. The spec's `review:<claimId>` cannot be literal —
+ * `:` is outside the instance-id charset and a prefixed CID overflows 64 chars — so the logical id
+ * is hashed: still deterministic per claim, which is all the idempotency needs.
+ */
+export declare function reviewInstanceIdFor(claimId: string): Promise<string>;
+//# sourceMappingURL=ids.d.ts.map

package/dist/lib/ids.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.d.ts","sourceRoot":"","sources":["../../src/lib/ids.ts"],"names":[],"mappings":"AAAA,qDAAqD;AAOrD;;;;;;;GAOG;AACH,wBAAsB,aAAa,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAGpE;AAED;;;;GAIG;AACH,wBAAsB,mBAAmB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAE1E"}

package/dist/lib/ids.js

@@ -0,0 +1,26 @@
+/** Mapping a claimId to its workflow instance id. */
+import { sha256Hex } from "./hash.js";
+/** What Cloudflare accepts as a workflow instance id (≤ 64 chars of [A-Za-z0-9_-], sane head). */
+const WORKFLOW_ID_RE = /^[a-zA-Z0-9_][a-zA-Z0-9-_]{0,63}$/;
+/**
+ * The instance id for a claim: the claimId ITSELF whenever Cloudflare accepts it (every CID does —
+ * keeps "find the instance by its claim id" ergonomics in the dashboard), else its sha256 hex —
+ * which is exactly 64 chars of [0-9a-f], i.e. always a valid instance id, and deterministic so
+ * idempotency by id still holds. Real chain data REQUIRES the fallback: ~2% of devnet claimIds are
+ * Matrix event ids (`$…-<ts>`, >64 chars) that no prefix/truncation trick can carry. The ledger's
+ * `instance_id` column records the mapping, and `params.claimId` always carries the real id.
+ */
+export async function instanceIdFor(claimId) {
+    if (WORKFLOW_ID_RE.test(claimId))
+        return claimId;
+    return sha256Hex(claimId);
+}
+/**
+ * The ReviewComplete instance id for a claim. The spec's `review:<claimId>` cannot be literal —
+ * `:` is outside the instance-id charset and a prefixed CID overflows 64 chars — so the logical id
+ * is hashed: still deterministic per claim, which is all the idempotency needs.
+ */
+export async function reviewInstanceIdFor(claimId) {
+    return sha256Hex(`review:${claimId}`);
+}
+//# sourceMappingURL=ids.js.map

package/dist/lib/ids.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ids.js","sourceRoot":"","sources":["../../src/lib/ids.ts"],"names":[],"mappings":"AAAA,qDAAqD;AAErD,OAAO,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAEnC,kGAAkG;AAClG,MAAM,cAAc,GAAG,mCAAmC,CAAC;AAE3D;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,OAAe;IACjD,IAAI,cAAc,CAAC,IAAI,CAAC,OAAO,CAAC;QAAE,OAAO,OAAO,CAAC;IACjD,OAAO,SAAS,CAAC,OAAO,CAAC,CAAC;AAC5B,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,OAAe;IACvD,OAAO,SAAS,CAAC,UAAU,OAAO,EAAE,CAAC,CAAC;AACxC,CAAC"}