@ixo/decision-oracle 0.0.0-stage → 0.2.0

package/dist/lib/ixo/attachments.d.ts

@@ -0,0 +1,116 @@
+/**
+ * Attachments — references, not bytes (pull-claim-spec §15).
+ *
+ * The files live in the store the claim body came from, addressed by CID; the claim body carries
+ * file answers as `{ name, type, content }` (single or array) whose `content` is a claim-bot
+ * `mediaAttachment` (JSON with a `serviceEndpoint`) or a bare CID/http/data ref. The oracle never
+ * duplicates those bytes: `resolveAttachments` is a pure walk that turns each file answer into a
+ * log-safe DESCRIPTOR — no fetch, no copy.
+ *
+ * A ref that carries only a CID resolves to that SAME store (`MediaLane.cidUrl`): the claim bot's
+ * media lane, the VFS claims lane, a VFS public copy, or the IPFS gateway. Never a guess at another
+ * store: the gateway answers a CID it doesn't hold with a 502 after ~40s, and a claim read from a
+ * cellnode (no media lane) leaves the ref unresolved.
+ *
+ * `size` (for `maxSizeMB` rules) is read on demand from the media response's `content-length`
+ * (counted from the body when a store sends none — the VFS) by the facts lane's connectors
+ * (`fetchAttachmentSize`) — only when a rule needs it; an unknown size resolves to null and the
+ * null rule applies. The store's auth (the bot UCAN; a fresh VFS
+ * token per request) is sent ONLY when the resolved host equals the store's host; everything else
+ * is fetched with no auth.
+ */
+import type { TraceContext } from "../tracing.js";
+export interface Attachment {
+    question: string;
+    name: string;
+    mediaType: string;
+    cid?: string;
+    /** Fetchable source ref (the store's media URL, or a public http/data ref). Log-safe (no bytes). */
+    url: string;
+    /** Bytes, when probed on demand (`fetchAttachmentSize`); undefined until then. */
+    size?: number;
+}
+/**
+ * The store a claim's files live in — the one its body was read from. NEVER logged (it holds auth).
+ */
+export interface MediaLane {
+    /** The store's base URL. `auth` goes to this host and no other. */
+    origin: string;
+    /** A bare CID → where this store serves its bytes. */
+    cidUrl(cid: string): string;
+    /**
+     * Headers for ONE request to `origin`, asked per request because the VFS's tokens are single-use
+     * (replay-protected). Absent on the public stores (a VFS public copy, the IPFS gateway).
+     */
+    auth?: () => Promise<Record<string, string>>;
+    /**
+     * A store inside this worker (the Decision API's R2 uploads, Go Prod §6.2): it answers its own
+     * URLs (those under `origin`) without a network hop — null when it holds no such object. Such a
+     * URL is never fetched and never handed to anyone else.
+     */
+    read?: (url: string) => Promise<Response | null>;
+}
+/**
+ * The claim bot's media lane for one collection. The URL mirrors the `serviceEndpoint` the upload
+ * lane writes into every `mediaAttachment` (`POST {bot}/media/upload` →
+ * `{bot}/media/collections/{collection}/{cid}`; portal `lib/matrix/matrixClaims.ts uploadFile`,
+ * scripts/submit-test-claim.ts), and the bot returns the file DECRYPTED. Bot tokens are reusable
+ * (replay off), so the one minted for the body serves every file read.
+ */
+export declare function botMedia(botUrl: string, botToken: string, collectionId: string): MediaLane;
+/** Whether `url` is on the claim's AUTHENTICATED store — the only host its auth is ever sent to. */
+export declare function isPrivateMedia(media: MediaLane | null, url: string): boolean;
+/**
+ * Resolve any claim file reference to a fetchable URL (port of editor resolveClaimFileRef.ts, with
+ * every CID lane pointed at the body's own store). Returns null if unresolvable.
+ */
+export declare function resolveClaimFileRef(raw: unknown, media: MediaLane | null): string | null;
+/** Walk the claim body and describe every file-like answer. Pure — no network, no bytes. */
+export declare function resolveAttachments(body: Record<string, unknown>, media: MediaLane | null): Attachment[];
+/**
+ * "Too large" and "could not be read" are different answers (FactSet `ai.*` errors): an oversized
+ * attachment is a KNOWN file the model can still be told about (name, type, size), while an
+ * unfetchable one taught us nothing and is the AI check's unreachable path.
+ */
+export type AttachmentBody = {
+    ok: true;
+    bytes: Uint8Array;
+} | {
+    ok: false;
+    reason: "too-large";
+    size: number;
+} | {
+    ok: false;
+    reason: "unfetchable";
+};
+/**
+ * On-demand byte fetch (the facts lane — every AI connector that must read the file itself):
+ * the attachment's bytes from its media URL, capped at `maxBytes`. The store's auth goes only to
+ * the store's host — and never across a redirect to another origin (`fetchGuarded`, which also
+ * re-checks every hop is public); a data: URL carries its own bytes. `content-length` is checked
+ * BEFORE the body is read, and the cap holds WHILE reading too: a chunked body (the VFS sends no
+ * length at all) is cut off at the cap, never buffered whole just to be discarded. Its `size` is
+ * then `maxBytes + 1` — a lower bound; the rest is never counted.
+ *
+ * `timeoutMs` overrides the client default for callers that fetch on a hot path (the judge's
+ * best-effort image evidence waits 5s, not 15).
+ */
+export declare function fetchAttachmentBytes(deps: {
+    trace: TraceContext;
+}, media: MediaLane | null, url: string, maxBytes: number, timeoutMs?: number): Promise<AttachmentBody>;
+/**
+ * On-demand size probe for `maxSizeMB` (the facts lane): read `content-length` from the
+ * media endpoint without consuming the body. The store's auth goes only to the store's host; a
+ * data: URL carries its own bytes; any other public http(s) URL (a cellnode claim's file answer —
+ * no media lane at all, `media` null) is probed unauthenticated, exactly like
+ * `fetchAttachmentBytes`. Any failure → null (the null rule decides).
+ *
+ * A 200 WITHOUT `content-length` is counted instead, up to `MAX_COUNTED_BYTES`. The VFS decrypts as
+ * it streams and workerd drops the length it sets — on GET and HEAD alike (seen live on devnet,
+ * both lanes share `buildContentResponse`) — so trusting the header alone left every VFS file's
+ * size null, and every `maxSizeMB` gate refusing a file well inside its limit.
+ */
+export declare function fetchAttachmentSize(deps: {
+    trace: TraceContext;
+}, media: MediaLane | null, url: string): Promise<number | null>;
+//# sourceMappingURL=attachments.d.ts.map

package/dist/lib/ixo/attachments.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"attachments.d.ts","sourceRoot":"","sources":["../../../src/lib/ixo/attachments.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI/C,MAAM,WAAW,UAAU;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,oGAAoG;IACpG,GAAG,EAAE,MAAM,CAAC;IACZ,kFAAkF;IAClF,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED;;GAEG;AACH,MAAM,WAAW,SAAS;IACxB,mEAAmE;IACnE,MAAM,EAAE,MAAM,CAAC;IACf,sDAAsD;IACtD,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC;IAC5B;;;OAGG;IACH,IAAI,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IAC7C;;;;OAIG;IACH,IAAI,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;CAClD;AAOD;;;;;;GAMG;AACH,wBAAgB,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,SAAS,CAO1F;AAED,oGAAoG;AACpG,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,GAAG,IAAI,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAO5E;AAUD;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,OAAO,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,GAAG,MAAM,GAAG,IAAI,CAuDxF;AAkCD,4FAA4F;AAC5F,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,KAAK,EAAE,SAAS,GAAG,IAAI,GACtB,UAAU,EAAE,CAed;AAED;;;;GAIG;AACH,MAAM,MAAM,cAAc,GACtB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GAC/B;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,WAAW,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,GAChD;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,aAAa,CAAA;CAAE,CAAC;AAEzC;;;;;;;;;;;GAWG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE;IAAE,KAAK,EAAE,YAAY,CAAA;CAAE,EAC7B,KAAK,EAAE,SAAS,GAAG,IAAI,EACvB,GAAG,EAAE,MAAM,EACX,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,cAAc,CAAC,CAuCzB;AAKD;;;;;;;;;;;GAWG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE;IAAE,KAAK,EAAE,YAAY,CAAA;CAAE,EAC7B,KAAK,EAAE,SAAS,GAAG,IAAI,EACvB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAyBxB"}

package/dist/lib/ixo/attachments.js

@@ -0,0 +1,290 @@
+/**
+ * Attachments — references, not bytes (pull-claim-spec §15).
+ *
+ * The files live in the store the claim body came from, addressed by CID; the claim body carries
+ * file answers as `{ name, type, content }` (single or array) whose `content` is a claim-bot
+ * `mediaAttachment` (JSON with a `serviceEndpoint`) or a bare CID/http/data ref. The oracle never
+ * duplicates those bytes: `resolveAttachments` is a pure walk that turns each file answer into a
+ * log-safe DESCRIPTOR — no fetch, no copy.
+ *
+ * A ref that carries only a CID resolves to that SAME store (`MediaLane.cidUrl`): the claim bot's
+ * media lane, the VFS claims lane, a VFS public copy, or the IPFS gateway. Never a guess at another
+ * store: the gateway answers a CID it doesn't hold with a 502 after ~40s, and a claim read from a
+ * cellnode (no media lane) leaves the ref unresolved.
+ *
+ * `size` (for `maxSizeMB` rules) is read on demand from the media response's `content-length`
+ * (counted from the body when a store sends none — the VFS) by the facts lane's connectors
+ * (`fetchAttachmentSize`) — only when a rule needs it; an unknown size resolves to null and the
+ * null rule applies. The store's auth (the bot UCAN; a fresh VFS
+ * token per request) is sent ONLY when the resolved host equals the store's host; everything else
+ * is fetched with no auth.
+ */
+import { assertPublicHttpUrl, fetchGuarded, readCappedBytes } from "../http/client.js";
+const CID_REGEX = /(baf[a-z0-9]{20,})/i;
+/** The store's own answer for a URL it holds, or undefined when the URL is not its to answer. */
+async function readOwn(media, url) {
+    return media?.read && url.startsWith(media.origin) ? media.read(url) : undefined;
+}
+/**
+ * The claim bot's media lane for one collection. The URL mirrors the `serviceEndpoint` the upload
+ * lane writes into every `mediaAttachment` (`POST {bot}/media/upload` →
+ * `{bot}/media/collections/{collection}/{cid}`; portal `lib/matrix/matrixClaims.ts uploadFile`,
+ * scripts/submit-test-claim.ts), and the bot returns the file DECRYPTED. Bot tokens are reusable
+ * (replay off), so the one minted for the body serves every file read.
+ */
+export function botMedia(botUrl, botToken, collectionId) {
+    const base = botUrl.replace(/\/+$/, "");
+    return {
+        origin: botUrl,
+        cidUrl: (cid) => `${base}/media/collections/${collectionId}/${cid}`,
+        auth: async () => ({ authorization: `Bearer ${botToken}`, "x-auth-type": "ucan" }),
+    };
+}
+/** Whether `url` is on the claim's AUTHENTICATED store — the only host its auth is ever sent to. */
+export function isPrivateMedia(media, url) {
+    if (!media?.auth || !/^https?:/i.test(url))
+        return false;
+    try {
+        return new URL(url).host === new URL(media.origin).host;
+    }
+    catch {
+        return false;
+    }
+}
+async function authFor(media, url) {
+    return media?.auth && isPrivateMedia(media, url) ? media.auth() : {};
+}
+function extractCid(source) {
+    return source.match(CID_REGEX)?.[1] ?? null;
+}
+/**
+ * Resolve any claim file reference to a fetchable URL (port of editor resolveClaimFileRef.ts, with
+ * every CID lane pointed at the body's own store). Returns null if unresolvable.
+ */
+export function resolveClaimFileRef(raw, media) {
+    if (raw == null)
+        return null;
+    if (typeof raw === "string") {
+        const trimmed = raw.trim();
+        if (!trimmed)
+            return null;
+        if (/^https?:/i.test(trimmed))
+            return trimmed;
+        if (trimmed.startsWith("data:"))
+            return trimmed;
+        // Every CID lane below needs a store to turn a CID into bytes. Without one (the cellnode lane)
+        // the ref stays unresolved rather than being pointed at a store that has never held it.
+        if (!media)
+            return null;
+        // `ipfs:<cid>` still appears on older claims — it's just another spelling of the CID, and the
+        // bytes it names are the ones the body's store holds.
+        if (/^ipfs:/i.test(trimmed)) {
+            const cid = extractCid(trimmed.replace(/^ipfs:\/*/i, ""));
+            return cid ? media.cidUrl(cid) : null;
+        }
+        if (trimmed.startsWith("{")) {
+            try {
+                return resolveClaimFileRef(JSON.parse(trimmed), media);
+            }
+            catch {
+                return null;
+            }
+        }
+        if (/^did:/i.test(trimmed)) {
+            const cid = extractCid(trimmed);
+            return cid ? media.cidUrl(cid) : null;
+        }
+        if (/^baf[a-z0-9]/i.test(trimmed) && trimmed.length < 200 && !trimmed.includes(" ")) {
+            const cid = extractCid(trimmed);
+            return cid ? media.cidUrl(cid) : null;
+        }
+        return null;
+    }
+    if (typeof raw === "object") {
+        const obj = raw;
+        if (typeof obj.serviceEndpoint === "string" && /^https?:/i.test(obj.serviceEndpoint)) {
+            return obj.serviceEndpoint;
+        }
+        if (media && typeof obj.proof === "string") {
+            const cid = extractCid(obj.proof);
+            if (cid)
+                return media.cidUrl(cid);
+        }
+        if (media && typeof obj.id === "string") {
+            const hashIdx = obj.id.indexOf("#");
+            const tail = hashIdx >= 0 ? obj.id.slice(hashIdx + 1) : obj.id;
+            const cid = extractCid(tail);
+            if (cid)
+                return media.cidUrl(cid);
+        }
+        if (typeof obj.content === "string")
+            return resolveClaimFileRef(obj.content, media);
+        if (typeof obj.url === "string" && /^https?:/i.test(obj.url))
+            return obj.url;
+    }
+    return null;
+}
+function isFileEntry(v) {
+    return !!v && typeof v === "object" && typeof v.content === "string";
+}
+/** Metadata (name, mediaType, cid) parsed from a mediaAttachment content, best-effort. */
+function metaOf(entry) {
+    let mediaType = entry.type ?? "application/octet-stream";
+    let cid;
+    const c = entry.content.trim();
+    if (c.startsWith("{")) {
+        try {
+            const parsed = JSON.parse(c);
+            if (parsed.mediaType)
+                mediaType = parsed.mediaType;
+            cid =
+                (parsed.proof && extractCid(parsed.proof)) ||
+                    (parsed.id && extractCid(parsed.id)) ||
+                    undefined;
+        }
+        catch {
+            /* leave defaults */
+        }
+    }
+    else {
+        cid = extractCid(c) ?? undefined;
+    }
+    return { mediaType, cid };
+}
+/** Walk the claim body and describe every file-like answer. Pure — no network, no bytes. */
+export function resolveAttachments(body, media) {
+    const attachments = [];
+    const describe = (question, entry) => {
+        const { mediaType, cid } = metaOf(entry);
+        const url = resolveClaimFileRef(entry.content, media) ?? "";
+        attachments.push({ question, name: entry.name ?? cid ?? question, mediaType, cid, url });
+    };
+    for (const [question, value] of Object.entries(body)) {
+        if (Array.isArray(value)) {
+            for (const v of value)
+                if (isFileEntry(v))
+                    describe(question, v);
+        }
+        else if (isFileEntry(value)) {
+            describe(question, value);
+        }
+    }
+    return attachments;
+}
+/**
+ * On-demand byte fetch (the facts lane — every AI connector that must read the file itself):
+ * the attachment's bytes from its media URL, capped at `maxBytes`. The store's auth goes only to
+ * the store's host — and never across a redirect to another origin (`fetchGuarded`, which also
+ * re-checks every hop is public); a data: URL carries its own bytes. `content-length` is checked
+ * BEFORE the body is read, and the cap holds WHILE reading too: a chunked body (the VFS sends no
+ * length at all) is cut off at the cap, never buffered whole just to be discarded. Its `size` is
+ * then `maxBytes + 1` — a lower bound; the rest is never counted.
+ *
+ * `timeoutMs` overrides the client default for callers that fetch on a hot path (the judge's
+ * best-effort image evidence waits 5s, not 15).
+ */
+export async function fetchAttachmentBytes(deps, media, url, maxBytes, timeoutMs) {
+    if (!url)
+        return { ok: false, reason: "unfetchable" };
+    try {
+        if (url.startsWith("data:")) {
+            const comma = url.indexOf(",");
+            if (comma < 0)
+                return { ok: false, reason: "unfetchable" };
+            const payload = url.slice(comma + 1);
+            const bytes = url.slice(0, comma).includes(";base64")
+                ? Uint8Array.from(atob(payload), (ch) => ch.charCodeAt(0))
+                : new TextEncoder().encode(decodeURIComponent(payload));
+            return bytes.byteLength <= maxBytes
+                ? { ok: true, bytes }
+                : { ok: false, reason: "too-large", size: bytes.byteLength };
+        }
+        const own = await readOwn(media, url);
+        if (own === null)
+            return { ok: false, reason: "unfetchable" };
+        if (own === undefined)
+            assertPublicHttpUrl(url);
+        const res = own ??
+            (await fetchGuarded(url, {
+                trace: deps.trace,
+                ...(timeoutMs !== undefined ? { timeoutMs } : {}),
+                headers: await authFor(media, url),
+            }));
+        if (!res.ok) {
+            await res.body?.cancel().catch(() => { });
+            return { ok: false, reason: "unfetchable" };
+        }
+        const declared = Number(res.headers.get("content-length"));
+        const bytes = await readCappedBytes(res, maxBytes);
+        if (bytes)
+            return { ok: true, bytes };
+        return {
+            ok: false,
+            reason: "too-large",
+            size: Number.isFinite(declared) && declared > maxBytes ? declared : maxBytes + 1,
+        };
+    }
+    catch {
+        return { ok: false, reason: "unfetchable" };
+    }
+}
+/** Past this a length-less body is not counted to the end: its size stays unknown (null rule). */
+const MAX_COUNTED_BYTES = 25 * 1024 * 1024;
+/**
+ * On-demand size probe for `maxSizeMB` (the facts lane): read `content-length` from the
+ * media endpoint without consuming the body. The store's auth goes only to the store's host; a
+ * data: URL carries its own bytes; any other public http(s) URL (a cellnode claim's file answer —
+ * no media lane at all, `media` null) is probed unauthenticated, exactly like
+ * `fetchAttachmentBytes`. Any failure → null (the null rule decides).
+ *
+ * A 200 WITHOUT `content-length` is counted instead, up to `MAX_COUNTED_BYTES`. The VFS decrypts as
+ * it streams and workerd drops the length it sets — on GET and HEAD alike (seen live on devnet,
+ * both lanes share `buildContentResponse`) — so trusting the header alone left every VFS file's
+ * size null, and every `maxSizeMB` gate refusing a file well inside its limit.
+ */
+export async function fetchAttachmentSize(deps, media, url) {
+    if (!url)
+        return null;
+    if (url.startsWith("data:")) {
+        const comma = url.indexOf(",");
+        if (comma < 0)
+            return null;
+        const payload = url.slice(comma + 1);
+        return url.slice(0, comma).includes(";base64")
+            ? Math.floor((payload.length * 3) / 4)
+            : payload.length;
+    }
+    try {
+        const own = await readOwn(media, url);
+        if (own === null)
+            return null;
+        if (own === undefined)
+            assertPublicHttpUrl(url);
+        const res = own ?? (await fetchGuarded(url, { trace: deps.trace, headers: await authFor(media, url) }));
+        const declared = Number(res.headers.get("content-length"));
+        if (!res.ok || (Number.isFinite(declared) && declared > 0)) {
+            await res.body?.cancel().catch(() => { });
+            return res.ok ? declared : null;
+        }
+        return await countBytes(res, MAX_COUNTED_BYTES);
+    }
+    catch {
+        return null;
+    }
+}
+/** A body's length by reading it to the end — nothing kept; null when empty or past `maxBytes`. */
+async function countBytes(res, maxBytes) {
+    const reader = res.body?.getReader();
+    if (!reader)
+        return null;
+    let total = 0;
+    for (let chunk = await reader.read(); !chunk.done; chunk = await reader.read()) {
+        total += chunk.value.byteLength;
+        if (total > maxBytes) {
+            await reader.cancel().catch(() => { });
+            return null;
+        }
+    }
+    return total > 0 ? total : null;
+}
+//# sourceMappingURL=attachments.js.map

package/dist/lib/ixo/attachments.js.map

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

package/dist/lib/ixo/authz.d.ts

@@ -0,0 +1,40 @@
+/**
+ * On-chain evaluate-rights check: the chain, not UCAN paperwork, is the authority on who may
+ * evaluate a collection. A commissioner "hires" this oracle by granting its wallet an
+ * `EvaluateClaimAuthorization` whose constraints name the collection (granter = the collection's
+ * admin account, the entity account from blocksync) — the portal's "Grant Role" flow. The register
+ * route proves that grant exists before watching a collection (README "How a claim flows" step 1), and a reader
+ * of the collection's claims is anyone holding the same right — one permission model, not two.
+ *
+ * Queried via the chain SDK's typed authz client (a keyed `grants` lookup, lazily loaded — see
+ * chain.ts) and cached ~5 min per (grantee, collection) in CACHE_KV. Chain trouble is
+ * 503 (fail loud), never a silent 403.
+ */
+import type { Config } from "../../config.js";
+import type { TraceContext } from "../tracing.js";
+export interface AuthzDeps {
+    config: Config;
+    trace: TraceContext;
+    cache: KVNamespace;
+}
+export declare const isIxoAccountAddress: (address: string) => boolean;
+/**
+ * Does `granteeAddress` hold an active on-chain `EvaluateClaimAuthorization` for `collectionId`?
+ * The owner short-circuit lives at the call site (it needs no chain read); this answers only the
+ * grant question, cached per (grantee, collection).
+ */
+export declare function hasEvaluateGrant(deps: AuthzDeps, granteeAddress: string, collectionId: string): Promise<boolean>;
+/**
+ * The uncached chain read behind `hasEvaluateGrant` — also register's WHO / HIRED gates and the act
+ * lane's pre-flight before `MsgEvaluateClaim`, which must NOT read through the KV cache: a stale
+ * negative would park a claim whose owner granted the right moments ago.
+ *
+ * A grant holds `EvaluateClaimConstraints[]`; one LIVE constraint naming the collection is enough.
+ * Live is the chain's own rule (ixo-blockchain `x/claims/types/authz.go`, `Accept`): a constraint
+ * whose `before_date` has passed OR whose `agent_quota` is 0 is spent, and the chain refuses
+ * `MsgEvaluateClaim` under it. The collection match stays the plain `collectionId` one: the chain
+ * also accepts a constraint that lists the claim in `claim_ids` (an OR, not a narrowing), so
+ * reading `claim_ids` as a scope here would refuse grants the chain honours.
+ */
+export declare function queryEvaluateGrant(config: Config, granter: string, grantee: string, collectionId: string): Promise<boolean>;
+//# sourceMappingURL=authz.d.ts.map

package/dist/lib/ixo/authz.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authz.d.ts","sourceRoot":"","sources":["../../../src/lib/ixo/authz.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAG3C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAI/C,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,WAAW,CAAC;CACpB;AAiBD,eAAO,MAAM,mBAAmB,YAAa,MAAM,KAAG,OAAuC,CAAC;AAE9F;;;;GAIG;AACH,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,SAAS,EACf,cAAc,EAAE,MAAM,EACtB,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,OAAO,CAAC,CAmBlB;AAED;;;;;;;;;;;GAWG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,OAAO,CAAC,CAmDlB"}

package/dist/lib/ixo/authz.js

@@ -0,0 +1,113 @@
+/**
+ * On-chain evaluate-rights check: the chain, not UCAN paperwork, is the authority on who may
+ * evaluate a collection. A commissioner "hires" this oracle by granting its wallet an
+ * `EvaluateClaimAuthorization` whose constraints name the collection (granter = the collection's
+ * admin account, the entity account from blocksync) — the portal's "Grant Role" flow. The register
+ * route proves that grant exists before watching a collection (README "How a claim flows" step 1), and a reader
+ * of the collection's claims is anyone holding the same right — one permission model, not two.
+ *
+ * Queried via the chain SDK's typed authz client (a keyed `grants` lookup, lazily loaded — see
+ * chain.ts) and cached ~5 min per (grantee, collection) in CACHE_KV. Chain trouble is
+ * 503 (fail loud), never a silent 403.
+ */
+import { AppError } from "../errors.js";
+import { readCache } from "../metrics.js";
+import { getCollection } from "./blocksync/index.js";
+import { getIxoSdk, getQueryClient, timedRpc } from "./chain.js";
+const GRANT_CACHE_TTL_SEC = 300;
+const EVALUATE_AUTH_TYPE = "/ixo.claims.v1beta1.EvaluateClaimAuthorization";
+const EVALUATE_MSG_TYPE = "/ixo.claims.v1beta1.MsgEvaluateClaim";
+/**
+ * Could this string be an account on THIS chain at all? `principal.address` is just the third
+ * segment of whatever DID authenticated (`middleware/ucan-auth.ts`), and `rootIssuers: ['*']`
+ * admits any keypair — so a `did:key:z6Mk…` caller arrives here as "z6Mk…", a `did:web` as its
+ * host, a group DID as "wasm". None of those can hold a grant, so none is worth a chain read — and
+ * the read is not safe to make either: `queryEvaluateGrant` treats only a "not found" error as a
+ * negative, so any OTHER refusal of a malformed address would surface as chain trouble (a 503 for a
+ * caller who simply has no rights), never cached. The human-readable part is the cheap, certain half
+ * of bech32; the node remains the judge of the rest.
+ */
+const IXO_ACCOUNT_RE = /^ixo1[0-9a-z]+$/;
+export const isIxoAccountAddress = (address) => IXO_ACCOUNT_RE.test(address);
+/**
+ * Does `granteeAddress` hold an active on-chain `EvaluateClaimAuthorization` for `collectionId`?
+ * The owner short-circuit lives at the call site (it needs no chain read); this answers only the
+ * grant question, cached per (grantee, collection).
+ */
+export async function hasEvaluateGrant(deps, granteeAddress, collectionId) {
+    // Not an account ⇒ no grant, decided here: no KV read, no Blocksync, no RPC (see the guard).
+    if (!isIxoAccountAddress(granteeAddress))
+        return false;
+    const key = `evalauth:${granteeAddress}:${collectionId}`;
+    const cached = await readCache("evalauth", () => deps.cache.get(key));
+    if (cached !== null)
+        return cached === "1";
+    // granter = the collection's on-chain admin (entity account) — the account the portal's grant
+    // flow signs from. No admin resolvable ⇒ no grant can exist.
+    const collection = await getCollection(deps, collectionId);
+    const admin = collection?.admin;
+    const allowed = admin
+        ? await queryEvaluateGrant(deps.config, admin, granteeAddress, collectionId)
+        : false;
+    await deps.cache
+        .put(key, allowed ? "1" : "0", { expirationTtl: GRANT_CACHE_TTL_SEC })
+        .catch(() => { });
+    return allowed;
+}
+/**
+ * The uncached chain read behind `hasEvaluateGrant` — also register's WHO / HIRED gates and the act
+ * lane's pre-flight before `MsgEvaluateClaim`, which must NOT read through the KV cache: a stale
+ * negative would park a claim whose owner granted the right moments ago.
+ *
+ * A grant holds `EvaluateClaimConstraints[]`; one LIVE constraint naming the collection is enough.
+ * Live is the chain's own rule (ixo-blockchain `x/claims/types/authz.go`, `Accept`): a constraint
+ * whose `before_date` has passed OR whose `agent_quota` is 0 is spent, and the chain refuses
+ * `MsgEvaluateClaim` under it. The collection match stays the plain `collectionId` one: the chain
+ * also accepts a constraint that lists the claim in `claim_ids` (an OR, not a narrowing), so
+ * reading `claim_ids` as a scope here would refuse grants the chain honours.
+ */
+export async function queryEvaluateGrant(config, granter, grantee, collectionId) {
+    // The same guard on the uncached read: register's WHO gate hands it `principal.address` too.
+    if (!isIxoAccountAddress(grantee))
+        return false;
+    const [{ ixo, utils }, queryClient] = await Promise.all([getIxoSdk(), getQueryClient(config)]);
+    // The keyed (granter, grantee, msgTypeUrl) lookup — NOT `granteeGrants` + a client-side filter.
+    // The grantee listing is paginated (the node answers the first 100, ordered by granter) and grows
+    // with every commission this oracle takes: past page 1 a perfectly valid grant read as missing,
+    // and every collection whose admin sorted late was refused NO_EVALUATE_GRANT and paused. The
+    // keyed query is one store read whatever the oracle holds. `EvaluateClaimAuthorization` is
+    // stored under the message it authorizes, so `msgTypeUrl` is `MsgEvaluateClaim`'s.
+    let grants;
+    // With `msgTypeUrl` set the node answers an absent grant as a not-found error rather than an
+    // empty list — a deterministic negative. Anything else is chain trouble: fail loud, never a
+    // silent 403.
+    const noGrants = (err) => String(err).toLowerCase().includes("not found");
+    try {
+        ({ grants } = await timedRpc("grants", () => queryClient.cosmos.authz.v1beta1.grants({
+            granter,
+            grantee,
+            msgTypeUrl: EVALUATE_MSG_TYPE,
+        }), noGrants));
+    }
+    catch (err) {
+        if (noGrants(err))
+            return false;
+        throw AppError.unavailable("Chain authz query failed", err);
+    }
+    // Granter and grantee are the query's key, so each answer is already theirs; the type check stays
+    // because a node that ignores `msgTypeUrl` would hand back every grant between the pair.
+    const now = Date.now();
+    const live = (ts) => !ts || utils.proto.fromTimestamp(ts).getTime() > now;
+    return grants.some((grant) => {
+        if (grant.authorization?.typeUrl !== EVALUATE_AUTH_TYPE)
+            return false;
+        if (!live(grant.expiration))
+            return false;
+        const auth = ixo.claims.v1beta1.EvaluateClaimAuthorization.decode(grant.authorization.value);
+        // `agentQuota` is a uint64 Long: compared through its string, never a lossy Number.
+        return auth.constraints.some((c) => c.collectionId === collectionId &&
+            live(c.beforeDate) &&
+            String(c.agentQuota ?? "0") !== "0");
+    });
+}
+//# sourceMappingURL=authz.js.map

package/dist/lib/ixo/authz.js.map

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