@ixo/decision-oracle 0.0.0-stage → 0.2.0

package/dist/lib/ixo/payment.js

@@ -0,0 +1,136 @@
+/**
+ * A claim's PAYMENT plane — the one place that reads the chain's intent/escrow semantics, verified
+ * against `ixo-blockchain/x/claims/keeper/msg_server.go`.
+ *
+ * Two lanes, and the oracle must act differently in each:
+ *
+ *   useIntent = false — an ORDINARY claim. The agent's requested `amount` is a request; the
+ *     evaluator's `MsgEvaluateClaim.amount` is what actually pays (falling back to the collection's
+ *     default approval payment when empty), authz-capped by `EvaluateClaimConstraints.MaxCustomAmount`.
+ *     ⇒ we ECHO the claim's own amount so the agent is paid what they asked for.
+ *
+ *   useIntent = true — an ESCROWED claim. `MsgClaimIntent` moved the payout into the collection's
+ *     escrow account BEFORE the claim existed; `MsgSubmitClaim{useIntent:true}` copied the intent's
+ *     terms onto the claim, set `paymentsStatus.approval = GUARANTEED`, and DELETED the intent
+ *     record (so there is nothing left to query at evaluation time — the claim IS the record).
+ *     `EvaluateClaim` then OVERWRITES `msg.Amount` with `claim.Amount` (msg_server.go:409-413) and
+ *     pays the full escrowed sum on approve / refunds it on any other terminal status.
+ *     ⇒ we send NO amount: the chain ignores it, and a non-empty amount is still checked against
+ *     `MaxCustomAmount` (authz.go:231), so echoing it can fail the whole MsgExec for zero benefit.
+ *
+ * The denom is always the CLAIM's — the oracle never picks one.
+ */
+import { AppError } from "../errors.js";
+/** The claim's payment plane, normalized. Missing/legacy fields read as an ordinary unpaid claim. */
+export function claimPayment(claim) {
+    return {
+        useIntent: claim.useIntent === true,
+        guaranteed: claim.paymentsStatus?.approval === "GUARANTEED",
+        amount: claim.amount ?? [],
+    };
+}
+/**
+ * The coins to put on `MsgEvaluateClaim`, or `undefined` to let the chain decide (§payment above).
+ * Intent claims ALWAYS get `undefined`.
+ */
+export function evaluationAmount(payment) {
+    if (!payment || payment.useIntent)
+        return undefined;
+    return payment.amount[0];
+}
+/** Any strictly positive coin? Amounts are integer strings; float loss can't flip a > 0 test. */
+function hasCoins(coins) {
+    return (coins ?? []).some((coin) => Number(coin.amount) > 0);
+}
+/**
+ * Would an on-chain APPROVE actually pay something without the evaluator inventing an amount?
+ * True on the escrow lane (the intent priced it), on a claim carrying its own coins, or when the
+ * collection's approval lane has a default. False means approval needs a CUSTOM amount — a money
+ * judgement that belongs to the owner, not this oracle (the act lane leaves such a claim for the
+ * portal rather than signing a zero payout).
+ *
+ * Deliberately a question about the CHAIN, not about settings: it reports whether money would move,
+ * and the caller decides what that means.
+ */
+export function hasApprovalPayout(payment, collectionPayments) {
+    if (payment.useIntent)
+        return true;
+    return hasCoins(payment.amount) || hasCoins(collectionPayments?.approval?.amount);
+}
+/**
+ * What ONE `MsgEvaluateClaim` draws from the collection's admin account, summed per denom — the
+ * act lane's `admin-unfunded` notice and the funding cron's resume threshold read the same rule.
+ * Proven on chain v8 (S4): the message fails WHOLE ("insufficient funds") unless the admin covers
+ * every leg it pays, and a failed one records nothing, so a retry after a top-up succeeds.
+ *
+ *   evaluation — every evaluation, approve or reject: the collection's `payments.evaluation`
+ *     (all its coins); the watched row's accepted `fee` only when Blocksync has no payments.
+ *   approval — an ORDINARY claim's payout: `claimAmount` (what step 9 puts on the message), else
+ *     the collection's approval default. An INTENT claim adds nothing: the escrow pays it.
+ *   rejection — the collection's rejection payment, whatever the lane.
+ *
+ * Omit `verdict` for the evaluation leg alone. An empty or absent leg adds nothing, and so does
+ * a coin whose amount is not an integer (the chain's coins always are; a ragged jsonb row must
+ * not throw a notice or a probe). Zero sums are dropped.
+ */
+export function adminDraw(input) {
+    const { payments, fee, verdict } = input;
+    const evaluation = payments?.evaluation?.amount ?? [];
+    const legs = evaluation.length > 0 ? [...evaluation] : fee ? [fee] : [];
+    if (verdict?.approve && !verdict.payment.useIntent) {
+        legs.push(...(verdict.claimAmount ? [verdict.claimAmount] : (payments?.approval?.amount ?? [])));
+    }
+    if (verdict && !verdict.approve)
+        legs.push(...(payments?.rejection?.amount ?? []));
+    const sums = new Map();
+    for (const { denom, amount } of legs) {
+        if (!/^\d+$/.test(amount))
+            continue;
+        sums.set(denom, (sums.get(denom) ?? 0n) + BigInt(amount));
+    }
+    return [...sums]
+        .filter(([, amount]) => amount > 0n)
+        .map(([denom, amount]) => ({ denom, amount: amount.toString() }));
+}
+/** The watched row's accepted evaluation fee as a coin, when it carries one. */
+export function rowFee(row) {
+    return row?.evaluationDenom && row.evaluationAmount
+        ? { denom: row.evaluationDenom, amount: row.evaluationAmount }
+        : null;
+}
+/**
+ * The register-time money gate: the collection's `Payments.evaluation` is the
+ * ONLY way this oracle gets paid — the chain splits that coin 80/10/10 on every `MsgEvaluateClaim`
+ * — so a collection paying nothing, in another denom, or below the fee is refused (402) rather than
+ * evaluated for free. Returns the accepted coin (what the watched row records). The whole coin list
+ * is scanned because an evaluation payment may carry several denoms; the message states required
+ * vs offered so the commissioner can fix the collection's payments, not guess.
+ */
+export function requireEvaluationPayment(required, payments) {
+    const coins = payments?.evaluation?.amount ?? [];
+    const offered = coins.find((coin) => coin.denom === required.denom);
+    // A zero-price fee (`minAmount: "0"`, e.g. a `pricing.byProtocol` entry — oracle.ts) earns
+    // nothing from the chain's evaluation split by design, so an absent/empty/wrong-denom leg is
+    // legal, not a refusal — record what was actually offered in the required denom, or "0" when
+    // there was none. NEVER echoed onto `MsgEvaluateClaim`: that message's only `amount` field is
+    // the claim's own ordinary-lane payout (`evaluationAmount()` in this file, read from
+    // `claimPayment()`), which chain-write.ts builds independently of this fee entirely.
+    // `offered.amount` is the chain's jsonb as Blocksync relays it — typed a string, never proven an
+    // integer. `BigInt("1.5")` throws (an anonymous 500, and once recorded on the watched row, again in
+    // the funding cron every tick) and `BigInt("")` is silently 0n. So a malformed amount is refused
+    // by name here, before anything compares or records it.
+    if (offered && !/^\d+$/.test(offered.amount)) {
+        throw AppError.paymentRequired(`The collection's evaluation payment amount "${offered.amount}" is not an integer base-unit amount of ${required.denom}`, { reason: "evaluation_underpaid", required, offered: coins });
+    }
+    if (BigInt(required.minAmount) === 0n) {
+        return { denom: required.denom, amount: offered?.amount ?? "0" };
+    }
+    if (!offered || BigInt(offered.amount) < BigInt(required.minAmount)) {
+        const offers = coins.length > 0
+            ? coins.map((coin) => `${coin.amount}${coin.denom}`).join(", ")
+            : "no evaluation payment";
+        throw AppError.paymentRequired(`This oracle requires an evaluation payment of at least ${required.minAmount}${required.denom}; the collection offers ${offers}`, { reason: "evaluation_underpaid", required, offered: coins });
+    }
+    return { denom: offered.denom, amount: offered.amount };
+}
+//# sourceMappingURL=payment.js.map

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

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

package/dist/lib/ixo/ucan-store.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The UCAN Store inbox — where the collection owner deposits the owner→oracle delegation (§3.5).
+ *
+ * We self-sign a `store/get` invocation (acting as ourselves → our inbox) and read the delegations
+ * addressed to `ORACLE_DID`. The store has replay ON (single-use), so we MINT A FRESH invocation on
+ * every request and NEVER cache it — a retry re-mints. The returned `.token` is the raw base64-CAR
+ * delegation, ready to use as the proof for the bot invocation.
+ */
+import type { Config } from "../../config.js";
+import type { Logger } from "../logger.js";
+import type { TraceContext } from "../tracing.js";
+export interface StoreDeps {
+    config: Config;
+    trace: TraceContext;
+    cache: KVNamespace;
+    logger: Logger;
+}
+export interface OwnerDelegation {
+    /** The raw base64-CAR delegation, ready to use as a proof. */
+    car: string;
+    /** Unix seconds the delegation expires at, or null if it never expires. */
+    expiresAt: number | null;
+}
+/**
+ * Fetch the newest non-expired claim-bot delegation from our store inbox that VERIFIES as
+ * `rootIssuerDid`'s (the chain owner's). Returns the delegation + its own expiry, or null if none on
+ * deposit does (the caller maps that to a fail-closed `forbidden`).
+ */
+export declare function fetchOwnerDelegation(deps: StoreDeps, rootIssuerDid: string): Promise<OwnerDelegation | null>;
+//# sourceMappingURL=ucan-store.d.ts.map

package/dist/lib/ixo/ucan-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ucan-store.d.ts","sourceRoot":"","sources":["../../../src/lib/ixo/ucan-store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAG3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAU/C,MAAM,WAAW,SAAS;IACxB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,YAAY,CAAC;IACpB,KAAK,EAAE,WAAW,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC;CAChB;AAaD,MAAM,WAAW,eAAe;IAC9B,8DAA8D;IAC9D,GAAG,EAAE,MAAM,CAAC;IACZ,2EAA2E;IAC3E,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAsB,oBAAoB,CACxC,IAAI,EAAE,SAAS,EACf,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,eAAe,GAAG,IAAI,CAAC,CAmHjC"}

package/dist/lib/ixo/ucan-store.js

@@ -0,0 +1,134 @@
+/**
+ * The UCAN Store inbox — where the collection owner deposits the owner→oracle delegation (§3.5).
+ *
+ * We self-sign a `store/get` invocation (acting as ourselves → our inbox) and read the delegations
+ * addressed to `ORACLE_DID`. The store has replay ON (single-use), so we MINT A FRESH invocation on
+ * every request and NEVER cache it — a retry re-mints. The returned `.token` is the raw base64-CAR
+ * delegation, ready to use as the proof for the bot invocation.
+ */
+import { AppError } from "../errors.js";
+import { fetchClient, readCappedBytes } from "../http/client.js";
+import { resolveIssuerKeys } from "./delegation-verify.js";
+import { resolveServiceDid } from "./did.js";
+import { mintInvocation, verifyOwnerDelegation } from "./ucan.js";
+const STORE_RESOURCE = "ixo:ucan-store";
+const CLAIM_BOT_RESOURCE = "ixo:matrix-claims-bot";
+/** The newest deposits tried per lookup — anyone may deposit a CAR naming the owner. */
+const MAX_CANDIDATES = 10;
+/** One inbox page: 50 deposits × a CAR of tens of KiB is a few MiB at the very most. */
+const MAX_INBOX_BYTES = 8 * 1024 * 1024;
+/**
+ * Fetch the newest non-expired claim-bot delegation from our store inbox that VERIFIES as
+ * `rootIssuerDid`'s (the chain owner's). Returns the delegation + its own expiry, or null if none on
+ * deposit does (the caller maps that to a fail-closed `forbidden`).
+ */
+export async function fetchOwnerDelegation(deps, rootIssuerDid) {
+    const { config } = deps;
+    if (!config.ORACLE_DID) {
+        throw AppError.internal("ORACLE_DID not configured");
+    }
+    const storeDid = await resolveServiceDid(deps.trace, deps.cache, config.UCAN_STORE_URL);
+    const url = `${config.UCAN_STORE_URL}/api/delegations?rootIssuer=${encodeURIComponent(rootIssuerDid)}&resource=${CLAIM_BOT_RESOURCE}&order=desc`;
+    // Single-use tokens: re-mint per attempt, never retry the same bearer (replay ON). `unique`
+    // guards against concurrent pulls minting byte-identical tokens in the same second — the store's
+    // replay protection would reject the twin as a replay.
+    let lastError;
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const { token } = await mintInvocation(config, {
+            // The store indexes our inbox by our chain DID (lib/ixo/ucan.ts header).
+            issuer: config.ORACLE_DID,
+            audience: storeDid,
+            capability: { can: "store/get", with: STORE_RESOURCE },
+            ttlSec: 120,
+            unique: true,
+        });
+        let res;
+        try {
+            // Single attempt on purpose (default): the token is single-use (replay ON) — the outer loop
+            // re-mints a fresh one rather than ever re-sending this request.
+            res = await fetchClient(url, {
+                trace: deps.trace,
+                headers: {
+                    accept: "application/json",
+                    authorization: `Bearer ${token}`,
+                    "x-auth-type": "ucan",
+                },
+            });
+        }
+        catch (err) {
+            lastError = err;
+            continue;
+        }
+        if (!res.ok) {
+            // Includes 401/403: a rejection of OUR invocation (replay collision, clock skew) is store
+            // contention, NOT "this claim is forbidden" — retry with a FRESH token, and surface as
+            // `unavailable` (retryable) if it persists. Deterministic authz denials belong to the claim
+            // bot, not here.
+            lastError = new Error(`store returned ${res.status}`);
+            // Discarded bodies pin one of the isolate's 6 open connections until GC.
+            await res.body?.cancel().catch(() => { });
+            continue;
+        }
+        // Under a cap: one page is at most 50 deposits of a CAR each (tens of KiB), and anyone can
+        // deposit to our inbox — an unbounded read would let a flood of them take the isolate down.
+        const bytes = await readCappedBytes(res, MAX_INBOX_BYTES).catch(() => new Uint8Array(0));
+        if (!bytes) {
+            lastError = new Error(`store answer over ${MAX_INBOX_BYTES} bytes`);
+            continue;
+        }
+        let body = null;
+        try {
+            body = JSON.parse(new TextDecoder().decode(bytes));
+        }
+        catch {
+            /* not JSON — no deposits we can read, as before */
+        }
+        const now = Math.floor(Date.now() / 1000);
+        const matches = (body?.delegations ?? []).filter((d) => d.audienceDid === config.ORACLE_DID &&
+            (d.expiresAt == null || d.expiresAt > now) &&
+            d.capabilities?.some((c) => c.with === CLAIM_BOT_RESOURCE));
+        // The `rootIssuer=` filter above is the STORE's own claim about what it's returning, and anyone
+        // can deposit a CAR naming the owner. So each match is verified exactly as the caller-supplied
+        // path is at register time (`verifyOwnerDelegation`: issuer, audience, resource, expiry AND
+        // signature), newest first (`order=desc`), and the first that passes is the one — a bad newest
+        // deposit must not hide an older good one. A refusal (400) is logged and skipped; anything else
+        // (Blocksync down, 503) is thrown, never read as "no delegation". The expiry returned is the
+        // verified CAR's own, not the store's metadata.
+        // The owner's keys are resolved ONCE for every candidate, and only when one passes the free
+        // field checks; the candidates are capped, so a flood of deposits costs at most MAX_CANDIDATES
+        // signature checks.
+        let keys;
+        const issuerKeys = () => {
+            keys ??= resolveIssuerKeys(config, rootIssuerDid, deps.trace);
+            return keys;
+        };
+        for (const match of matches.slice(0, MAX_CANDIDATES)) {
+            let verified;
+            try {
+                verified = await verifyOwnerDelegation(config, match.token, rootIssuerDid, issuerKeys);
+            }
+            catch (err) {
+                if (err instanceof AppError && err.status === 400) {
+                    deps.logger.warn("ucan-store.delegation-refused", {
+                        rootIssuerDid,
+                        reason: err.message,
+                        code: err.details?.code,
+                    });
+                    continue;
+                }
+                throw err;
+            }
+            deps.logger.debug("ucan-store.delegation-found", {
+                rootIssuerDid,
+                expiresAt: verified.expiresAt?.toISOString() ?? null,
+            });
+            return {
+                car: verified.car,
+                expiresAt: verified.expiresAt ? Math.floor(verified.expiresAt.getTime() / 1000) : null,
+            };
+        }
+        return null;
+    }
+    throw AppError.unavailable("UCAN Store inbox unreachable", lastError);
+}
+//# sourceMappingURL=ucan-store.js.map

package/dist/lib/ixo/ucan-store.js.map

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

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

@@ -0,0 +1,96 @@
+/**
+ * Minting UCAN invocations as the Evaluation Oracle.
+ *
+ * ONE key, two DIDs. `signerFromMnemonic(SERVICE_ED25519_MNEMONIC)` derives the same Ed25519 key
+ * as identity.ts (SHA256(mnemonic) → seed), so whichever DID is stamped on the signer, the key is
+ * the one `/.well-known/did.json` publishes. The DEFAULT issuer is our did:web
+ * (`did:web:<ORACLE_HOSTNAME>`, docs/ENGINE-CONTRACT.md): the engine's validator resolves it from
+ * that document, so a cloned kit needs no on-chain IID key. `ORACLE_DID` (did:ixo) is the issuer
+ * ONLY where the counterparty knows us by our chain identity: the owner→oracle delegation names it
+ * as its audience (so the bot invocation that carries it as proof must be issued by that same
+ * principal), the UCAN Store indexes our inbox by it, and the VFS matches our evaluate grant by
+ * its address. Four invocation shapes are minted (see pull-claim-spec §13, replay differs), plus
+ * one delegation:
+ *
+ *   - engine invocations (lib/engine): SELF-SIGNED as did:web, resource `ixo:eval-engine`. Replay
+ *     is OFF; the client reuses a token until it nears expiry.
+ *   - store invocations (§3.5): SELF-SIGNED as ORACLE_DID, resource `ixo:ucan-store`. Replay is ON
+ *     (single-use), so `mintInvocation` is called fresh every store request and NEVER cached.
+ *   - bot invocations (§3.6): DELEGATION-BACKED (proofs:[owner→oracle]) as ORACLE_DID, resource
+ *     `ixo:matrix-claims-bot`. Replay is OFF, so `mintBotInvocation` caches the token per
+ *     (botDid, delegation) until it expires.
+ *   - VFS claims-lane invocations (vfs.ts): SELF-SIGNED as ORACLE_DID, `fs/read` on
+ *     `ixo:filesystem/<entity>/.claims/<collection>`. Replay is ON (single-use), so one is minted
+ *     per request and NEVER cached.
+ *   - the facilitator delegation (`mintDelegation`, routes/v1/api/admin-facilitator.ts): a
+ *     DELEGATION, as did:web, to an operator's did:ixo — one `operators/<action>` per requested
+ *     action on the card facilitator, never `*`. A nonce on every mint, NEVER cached: each one is a fresh short-lived credential.
+ */
+import type { Capability, Delegation } from "@ixo/ucan";
+import type { Config } from "../../config.js";
+import { type IssuerKeys } from "./delegation-verify.js";
+/** `did:web:<ORACLE_HOSTNAME>` — encoded exactly as identity.ts publishes it. */
+export declare function oracleWebDid(config: Pick<Config, "ORACLE_HOSTNAME">): string;
+export interface MintOptions {
+    audience: string;
+    capability: Capability;
+    /** Which of our DIDs signs — default our did:web; `ORACLE_DID` where the counterparty knows us by chain identity (header). */
+    issuer?: string;
+    /** Empty/omitted => self-signed (act as the oracle). Present => act as the delegation root. */
+    proofs?: Delegation[];
+    ttlSec?: number;
+    /**
+     * Make the token unique. Ed25519 signing is deterministic, so two mints in the same second with
+     * identical fields produce BYTE-IDENTICAL tokens — a replay-protected service (the UCAN Store)
+     * rejects the second as a replay. Set for single-use invocations minted concurrently.
+     */
+    unique?: boolean;
+}
+export interface MintedInvocation {
+    token: string;
+    /** Unix seconds the invocation expires at. */
+    exp: number;
+}
+/** Mint + serialize a single invocation. Callers that are single-use (store) MUST NOT cache this. */
+export declare function mintInvocation(config: Config, opts: MintOptions): Promise<MintedInvocation>;
+export interface MintDelegationOptions {
+    audience: string;
+    capabilities: Capability[];
+    ttlSec: number;
+    /** The cap on `exp − nbf` — the lifetime a verifier measures, backdate included. */
+    maxLifetimeSec: number;
+}
+export interface MintedDelegation {
+    /** The base64 CAR — the same encoding as a console role grant. */
+    car: string;
+    cid: string;
+    /** Unix seconds the delegation expires at. */
+    exp: number;
+}
+/** Mint + serialize a delegation from our did:web. Always a nonce (see MintOptions.unique): two
+ *  mints in one second are two credentials, never one CID. Always an `nbf` — the issue time less
+ *  NBF_BACKDATE_SEC, from the same clock read as `exp` — and `exp = min(issue + ttl, nbf +
+ *  maxLifetime)`: the facilitator (S10) refuses a grant without `nbf` or whose `exp − nbf` is
+ *  longer than an hour. Never cache it. */
+export declare function mintDelegation(config: Config, opts: MintDelegationOptions): Promise<MintedDelegation>;
+/**
+ * Verify a caller-supplied owner→oracle delegation CAR before persisting it (§6): parseable, issued
+ * by `expectedIssuer` (the chain owner), addressed to OUR oracle, scoped to the claim bot, not
+ * expired — and SIGNED by that issuer (delegation-verify.ts: `parseDelegation` checks no signature,
+ * so without it any evaluate-grant holder could store a forgery naming the owner). Anything off →
+ * 400 — we never store a delegation we couldn't use or didn't get from its rightful owner; only an
+ * unreachable Blocksync is a 503. The field checks run first: they are free, and a CAR that fails
+ * them never costs a DID resolution. The returned expiry is the verified CAR's own.
+ */
+export declare function verifyOwnerDelegation(config: Config, car: string, expectedIssuer: string, 
+/** The issuer's keys, resolved once by a caller verifying several CARs (ucan-store.ts). */
+issuerKeys?: () => Promise<IssuerKeys>): Promise<{
+    car: string;
+    expiresAt: Date | null;
+}>;
+/**
+ * Mint (and cache per (botDid, delegation)) a delegation-backed invocation for the claim bot.
+ * The `delegationCar` is the owner→oracle delegation retrieved from the UCAN Store (§3.5).
+ */
+export declare function mintBotInvocation(config: Config, cache: KVNamespace, botDid: string, delegationCar: string): Promise<string>;
+//# sourceMappingURL=ucan.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"ucan.d.ts","sourceRoot":"","sources":["../../../src/lib/ixo/ucan.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,UAAU,EAAU,MAAM,WAAW,CAAC;AAChE,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,cAAc,CAAC;AAI3C,OAAO,EAAE,KAAK,UAAU,EAA6B,MAAM,qBAAqB,CAAC;AAGjF,iFAAiF;AACjF,wBAAgB,YAAY,CAAC,MAAM,EAAE,IAAI,CAAC,MAAM,EAAE,iBAAiB,CAAC,GAAG,MAAM,CAE5E;AAmCD,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,UAAU,CAAC;IACvB,8HAA8H;IAC9H,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+FAA+F;IAC/F,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;IACtB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;OAIG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB;AAED,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;CACb;AAED,qGAAqG;AACrG,wBAAsB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,gBAAgB,CAAC,CAkBjG;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,UAAU,EAAE,CAAC;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,oFAAoF;IACpF,cAAc,EAAE,MAAM,CAAC;CACxB;AAMD,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,GAAG,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE,MAAM,CAAC;IACZ,8CAA8C;IAC9C,GAAG,EAAE,MAAM,CAAC;CACb;AAED;;;;2CAI2C;AAC3C,wBAAsB,cAAc,CAClC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,qBAAqB,GAC1B,OAAO,CAAC,gBAAgB,CAAC,CAmB3B;AAID;;;;;;;;GAQG;AACH,wBAAsB,qBAAqB,CACzC,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,MAAM,EACX,cAAc,EAAE,MAAM;AACtB,2FAA2F;AAC3F,UAAU,CAAC,EAAE,MAAM,OAAO,CAAC,UAAU,CAAC,GACrC,OAAO,CAAC;IAAE,GAAG,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,IAAI,GAAG,IAAI,CAAA;CAAE,CAAC,CA0ClD;AASD;;;GAGG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,MAAM,EACd,KAAK,EAAE,WAAW,EAClB,MAAM,EAAE,MAAM,EACd,aAAa,EAAE,MAAM,GACpB,OAAO,CAAC,MAAM,CAAC,CAgDjB"}

package/dist/lib/ixo/ucan.js

@@ -0,0 +1,216 @@
+/**
+ * Minting UCAN invocations as the Evaluation Oracle.
+ *
+ * ONE key, two DIDs. `signerFromMnemonic(SERVICE_ED25519_MNEMONIC)` derives the same Ed25519 key
+ * as identity.ts (SHA256(mnemonic) → seed), so whichever DID is stamped on the signer, the key is
+ * the one `/.well-known/did.json` publishes. The DEFAULT issuer is our did:web
+ * (`did:web:<ORACLE_HOSTNAME>`, docs/ENGINE-CONTRACT.md): the engine's validator resolves it from
+ * that document, so a cloned kit needs no on-chain IID key. `ORACLE_DID` (did:ixo) is the issuer
+ * ONLY where the counterparty knows us by our chain identity: the owner→oracle delegation names it
+ * as its audience (so the bot invocation that carries it as proof must be issued by that same
+ * principal), the UCAN Store indexes our inbox by it, and the VFS matches our evaluate grant by
+ * its address. Four invocation shapes are minted (see pull-claim-spec §13, replay differs), plus
+ * one delegation:
+ *
+ *   - engine invocations (lib/engine): SELF-SIGNED as did:web, resource `ixo:eval-engine`. Replay
+ *     is OFF; the client reuses a token until it nears expiry.
+ *   - store invocations (§3.5): SELF-SIGNED as ORACLE_DID, resource `ixo:ucan-store`. Replay is ON
+ *     (single-use), so `mintInvocation` is called fresh every store request and NEVER cached.
+ *   - bot invocations (§3.6): DELEGATION-BACKED (proofs:[owner→oracle]) as ORACLE_DID, resource
+ *     `ixo:matrix-claims-bot`. Replay is OFF, so `mintBotInvocation` caches the token per
+ *     (botDid, delegation) until it expires.
+ *   - VFS claims-lane invocations (vfs.ts): SELF-SIGNED as ORACLE_DID, `fs/read` on
+ *     `ixo:filesystem/<entity>/.claims/<collection>`. Replay is ON (single-use), so one is minted
+ *     per request and NEVER cached.
+ *   - the facilitator delegation (`mintDelegation`, routes/v1/api/admin-facilitator.ts): a
+ *     DELEGATION, as did:web, to an operator's did:ixo — one `operators/<action>` per requested
+ *     action on the card facilitator, never `*`. A nonce on every mint, NEVER cached: each one is a fresh short-lived credential.
+ */
+import { AppError } from "../errors.js";
+import { sha256Hex } from "../hash.js";
+import { countCache, readCache } from "../metrics.js";
+import { verifyDelegationSignature } from "./delegation-verify.js";
+import { webDidOf } from "./web-did.js";
+/** `did:web:<ORACLE_HOSTNAME>` — encoded exactly as identity.ts publishes it. */
+export function oracleWebDid(config) {
+    return webDidOf(config.ORACLE_HOSTNAME);
+}
+// Memoize the signer per (mnemonic, did) so we derive the Ed25519 key once per isolate per DID.
+const signerCache = new Map();
+function getSigner(config, did) {
+    const mnemonic = config.SERVICE_ED25519_MNEMONIC;
+    if (!mnemonic) {
+        // Loud 500 — an expected failure of config, not of the request (spec §11 row 8).
+        throw AppError.internal("Oracle signing identity not configured (SERVICE_ED25519_MNEMONIC)");
+    }
+    const key = `${did}::${mnemonic}`;
+    let signer = signerCache.get(key);
+    if (!signer) {
+        signer = (async () => {
+            const { signerFromMnemonic } = await import("@ixo/ucan");
+            // `withDID` stamps any DID on the key at runtime; only the parameter TYPE is narrower.
+            const { signer } = await signerFromMnemonic(mnemonic, did);
+            return signer;
+        })();
+        signerCache.set(key, signer);
+        // A failed derivation is not memoized: the next mint tries again instead of replaying it.
+        const pending = signer;
+        pending.catch(() => {
+            if (signerCache.get(key) === pending)
+                signerCache.delete(key);
+        });
+    }
+    return signer;
+}
+const DEFAULT_TTL_SEC = 300;
+/** Mint + serialize a single invocation. Callers that are single-use (store) MUST NOT cache this. */
+export async function mintInvocation(config, opts) {
+    const { createInvocation, serializeInvocation } = await import("@ixo/ucan");
+    const signer = await getSigner(config, opts.issuer ?? oracleWebDid(config));
+    const exp = Math.floor(Date.now() / 1000) + (opts.ttlSec ?? DEFAULT_TTL_SEC);
+    try {
+        const inv = await createInvocation({
+            issuer: signer,
+            audience: opts.audience,
+            capability: opts.capability,
+            proofs: opts.proofs,
+            expiration: exp,
+            // A random fact (UCAN §3.2.4) guarantees a distinct CID per mint — see MintOptions.unique.
+            ...(opts.unique ? { facts: [{ nonce: crypto.randomUUID() }] } : {}),
+        });
+        return { token: await serializeInvocation(inv), exp };
+    }
+    catch (err) {
+        throw AppError.internal("Failed to mint UCAN invocation", err);
+    }
+}
+/** How far `nbf` is backdated: ucanto accepts only `now > nbf` (strict), so an `nbf` of the issue
+ *  time is refused for the rest of that second and under any clock skew. */
+const NBF_BACKDATE_SEC = 60;
+/** Mint + serialize a delegation from our did:web. Always a nonce (see MintOptions.unique): two
+ *  mints in one second are two credentials, never one CID. Always an `nbf` — the issue time less
+ *  NBF_BACKDATE_SEC, from the same clock read as `exp` — and `exp = min(issue + ttl, nbf +
+ *  maxLifetime)`: the facilitator (S10) refuses a grant without `nbf` or whose `exp − nbf` is
+ *  longer than an hour. Never cache it. */
+export async function mintDelegation(config, opts) {
+    const { createDelegation, serializeDelegation } = await import("@ixo/ucan");
+    const signer = await getSigner(config, oracleWebDid(config));
+    const issued = Math.floor(Date.now() / 1000);
+    const nbf = issued - NBF_BACKDATE_SEC;
+    const exp = Math.min(issued + opts.ttlSec, nbf + opts.maxLifetimeSec);
+    try {
+        const d = await createDelegation({
+            issuer: signer,
+            audience: opts.audience,
+            capabilities: opts.capabilities,
+            notBefore: nbf,
+            expiration: exp,
+            facts: [{ nonce: crypto.randomUUID() }],
+        });
+        return { car: await serializeDelegation(d), cid: d.cid.toString(), exp };
+    }
+    catch (err) {
+        throw AppError.internal("Failed to mint UCAN delegation", err);
+    }
+}
+// --- Owner delegation verification (register-time) ----------------------------------------------
+/**
+ * Verify a caller-supplied owner→oracle delegation CAR before persisting it (§6): parseable, issued
+ * by `expectedIssuer` (the chain owner), addressed to OUR oracle, scoped to the claim bot, not
+ * expired — and SIGNED by that issuer (delegation-verify.ts: `parseDelegation` checks no signature,
+ * so without it any evaluate-grant holder could store a forgery naming the owner). Anything off →
+ * 400 — we never store a delegation we couldn't use or didn't get from its rightful owner; only an
+ * unreachable Blocksync is a 503. The field checks run first: they are free, and a CAR that fails
+ * them never costs a DID resolution. The returned expiry is the verified CAR's own.
+ */
+export async function verifyOwnerDelegation(config, car, expectedIssuer, 
+/** The issuer's keys, resolved once by a caller verifying several CARs (ucan-store.ts). */
+issuerKeys) {
+    const { ORACLE_DID } = config;
+    if (!ORACLE_DID)
+        throw AppError.internal("ORACLE_DID not configured");
+    const { parseDelegation } = await import("@ixo/ucan");
+    let d;
+    try {
+        d = (await parseDelegation(car));
+    }
+    catch (err) {
+        throw AppError.badRequest("delegation is not a valid UCAN CAR", { cause: String(err) });
+    }
+    if (d.issuer?.did() !== expectedIssuer) {
+        throw AppError.badRequest("delegation must be issued by the registering wallet");
+    }
+    // A ROOT: the claim bot reads authority off the chain's root, so a proof inside would make
+    // someone other than the owner the root — whoever signed it. The portal and the CLI mint roots.
+    if (d.proofs?.length) {
+        throw AppError.badRequest("delegation must be the owner's own root delegation (no proofs)");
+    }
+    if (d.audience?.did() !== ORACLE_DID) {
+        throw AppError.badRequest("delegation must be addressed to the evaluation oracle");
+    }
+    if (!d.capabilities?.some((cap) => cap.with === CLAIM_BOT_RESOURCE)) {
+        throw AppError.badRequest(`delegation must grant the ${CLAIM_BOT_RESOURCE} resource`);
+    }
+    // No `exp` is accepted: the owner chose a delegation that never expires, and it is signed (below).
+    // It is never refreshed from the store, but it IS re-verified on use (lib/ixo/index.ts).
+    const exp = typeof d.expiration === "number" && Number.isFinite(d.expiration) ? d.expiration : null;
+    if (exp !== null && exp <= Math.floor(Date.now() / 1000)) {
+        throw AppError.badRequest("delegation is already expired");
+    }
+    await verifyDelegationSignature(config, car, expectedIssuer, issuerKeys);
+    return { car, expiresAt: exp ? new Date(exp * 1000) : null };
+}
+// --- Bot invocation (delegation-backed, reusable → cached) --------------------------------------
+const CLAIM_BOT_RESOURCE = "ixo:matrix-claims-bot";
+// Bot tokens are reusable until expiry; 1h keeps them fresh while surviving a burst of pulls.
+const BOT_TTL_SEC = 3600;
+const l1BotTokens = new Map();
+/**
+ * Mint (and cache per (botDid, delegation)) a delegation-backed invocation for the claim bot.
+ * The `delegationCar` is the owner→oracle delegation retrieved from the UCAN Store (§3.5).
+ */
+export async function mintBotInvocation(config, cache, botDid, delegationCar) {
+    const now = Math.floor(Date.now() / 1000);
+    const cacheKey = `bot-inv:${botDid}:${await sha256Hex(delegationCar)}`;
+    const l1 = l1BotTokens.get(cacheKey);
+    countCache("bot-inv-l1", !!l1 && l1.exp - 30 > now);
+    if (l1 && l1.exp - 30 > now)
+        return l1.token;
+    const l2 = await readCache("bot-inv", () => cache.get(cacheKey, "json"));
+    if (l2 && l2.exp - 30 > now) {
+        l1BotTokens.set(cacheKey, l2);
+        return l2.token;
+    }
+    const { parseDelegation } = await import("@ixo/ucan");
+    let proof;
+    try {
+        proof = await parseDelegation(delegationCar);
+    }
+    catch (err) {
+        throw AppError.internal("Owner delegation is not a valid UCAN CAR", err);
+    }
+    // An invocation must never outlive its proof: cap the token (and thus the cache) at the
+    // delegation's own expiry, so a delegation nearing its end can't leave behind a cached token the
+    // bot would reject mid-pull.
+    const proofExp = proof.expiration;
+    const ttlCap = typeof proofExp === "number" && Number.isFinite(proofExp)
+        ? Math.min(BOT_TTL_SEC, proofExp - now)
+        : BOT_TTL_SEC;
+    if (ttlCap <= 30) {
+        throw AppError.forbidden("Owner delegation is expired — the owner must re-register");
+    }
+    const minted = await mintInvocation(config, {
+        // The proof's audience is ORACLE_DID — the invocation carrying it must be issued by that principal.
+        issuer: config.ORACLE_DID,
+        audience: botDid,
+        capability: { can: "*", with: CLAIM_BOT_RESOURCE },
+        proofs: [proof],
+        ttlSec: ttlCap,
+    });
+    l1BotTokens.set(cacheKey, minted);
+    await cache
+        .put(cacheKey, JSON.stringify(minted), { expirationTtl: Math.max(minted.exp - now, 60) })
+        .catch(() => { });
+    return minted.token;
+}
+//# sourceMappingURL=ucan.js.map