@ixo/decision-oracle 0.0.0-stage → 0.2.1

package/dist/middleware/ucan-auth.js

@@ -0,0 +1,278 @@
+/**
+ * Our own API auth — UCAN only, from day zero. The oracle is a did:web service; every chain-lane
+ * `/v1/*` call must be a UCAN invocation carrying exactly ONE capability
+ * `{ with:'ixo:eval-oracle', can:<the route's action> }` addressed to our DID (CLAUDE.md
+ * "Capabilities: one action per route, never `*`"). Which `can` a route takes is
+ * `middleware/capability.ts`'s call, after this; here the token is validated against a capability
+ * defined for ITS OWN `can` — `@ucanto/validator` compares `can` by exact string — and the `can` is
+ * recorded on the principal.
+ *
+ * AUTHENTICATION, not authorization — this proves the caller holds the key its DID names, the
+ * invocation was addressed to US (audience = our pinned did:web), and names one action on our
+ * resource. `rootIssuers:['*']` is a decision, not an oversight: anyone with a portal wallet must
+ * be able to call the API, so any freshly generated keypair authenticates.
+ *
+ * The invoker must BE the identity it acts as: a delegated chain (root ≠ invoker) is refused (owner,
+ * 2026-09-30 — the engine's rule). Every chain-lane caller signs for itself — a portal wallet, the
+ * CLI's AuthHub session, the engine's status board — and every gate keys on the acting DID, so a
+ * token some root signed for a third party must never let that party act AS the root here. Member
+ * grants belong to the Decision API lane's console auth (`middleware/api/console.ts`), not here.
+ *
+ * So: EVERY `/v1` route MUST still enforce its own identity-based authorization — watched-collection
+ * ownership / on-chain grant (`lib/ixo/authz.ts`), `ORACLE_ADMIN_DIDS`. A route that checks nothing is
+ * open to the internet.
+ *
+ * Mirrors subscriptions-api's middleware but fixes its two gaps:
+ *   1. the validator (service DID + resolvers, static per deploy) is built ONCE per isolate;
+ *   2. the audience is pinned to ORACLE_HOSTNAME — THIS worker's own did:web host, not the engine we
+ *      call — never the attacker-controllable request Host.
+ * Plus a two-tier token cache (L1 bounded in-isolate TtlCache, L2 KV) keyed by sha256(token), and a clean split
+ * between invalid (401, briefly negative-cached) and unavailable (503, never cached).
+ *
+ * Short-lived tokens (as the console lane, `middleware/api/console.ts`): an invocation must expire,
+ * at most MAX_LIFETIME_SEC (600 s) out — every caller signs 60–300 s. Replay protection stays off,
+ * so a token may be presented again within that window (callers do reuse one across a page's
+ * calls); the window, not a nonce store, is what bounds a leaked token.
+ */
+import { createMiddleware } from "hono/factory";
+import { AppError } from "../lib/errors.js";
+import { sha256Hex } from "../lib/hash.js";
+import { getDIDWeb } from "../lib/ixo/identity.js";
+import { countCache, readCache } from "../lib/metrics.js";
+import { TtlCache } from "../lib/ttl-cache.js";
+import { ACCEPTED_CANS } from "./capability.js";
+const RESOURCE = "ixo:eval-oracle";
+/** Deterministic-invalid tokens are negative-cached this long so a bad client can't hammer us. */
+const NEGATIVE_TTL_SEC = 30;
+/** An invocation's longest life — the console lane's bound; every chain-lane caller signs ≤ 300 s. */
+const MAX_LIFETIME_SEC = 600;
+// Built once per isolate (module-level promise). Rebuilt only if the isolate is recycled.
+let validatorPromise = null;
+function getValidator(config) {
+    if (validatorPromise)
+        return validatorPromise;
+    const building = (async () => {
+        if (!config.SERVICE_ED25519_MNEMONIC) {
+            throw AppError.internal("SERVICE_ED25519_MNEMONIC not configured");
+        }
+        const u = await import("@ixo/ucan");
+        // Pin the service DID to our canonical host — NOT new URL(c.req.url).host.
+        const { serviceDid, publicKeyMultibase } = await getDIDWeb(config.SERVICE_ED25519_MNEMONIC, config.ORACLE_HOSTNAME);
+        const local = u.createLocalDIDResolver();
+        local.register(serviceDid, publicKeyMultibase);
+        const didResolver = u.createCompositeDIDResolver([
+            local,
+            u.createIxoDIDResolver({ indexerUrl: config.BLOCKSYNC_GRAPHQL_URL }),
+            u.createWebDIDResolver({ fallbackToHttp: config.ENVIRONMENT !== "production" }),
+        ]);
+        const validator = (await u.createUCANValidator({
+            serverDid: serviceDid,
+            rootIssuers: ["*"],
+            didResolver,
+            // Replay off — a caller may reuse a token within its window; trust is bounded by that
+            // window (≤ MAX_LIFETIME_SEC, checked below) and our token cache, capped to it.
+            invocationStore: { has: async () => false, add: async () => { } },
+        }));
+        // `@ucanto/validator` compares `can` by exact string (`descriptor.can !== capability.can` →
+        // UnknownCapability), so an invocation is validated against a capability defined for ITS OWN
+        // `can`; which route may use that `can` is `middleware/capability.ts`'s call, after this.
+        // The set is fixed (every route's action + the legacy `*`), so an attacker-chosen `can` never
+        // defines anything: it is refused before validation.
+        const capabilities = new Map(ACCEPTED_CANS.map((can) => [
+            can,
+            u.defineCapability({ can: can, protocol: "ixo:" }),
+        ]));
+        return { validator, capabilities, parse: u.parseDelegation, serviceDid };
+    })();
+    validatorPromise = building;
+    // A build that FAILED must not be the isolate's answer forever: a rejected promise parked here
+    // turned one bad dynamic import into a 500 on every `/v1` request until the isolate recycled.
+    // Dropped on rejection (only if it is still the memo), so the next request builds again.
+    building.catch(() => {
+        if (validatorPromise === building)
+            validatorPromise = null;
+    });
+    return building;
+}
+/**
+ * Bounded (lib/ttl-cache.ts): the key is a hash of whatever bearer the caller sent, and this
+ * middleware runs BEFORE anything is authenticated — an unbounded map here grew by one entry per
+ * distinct garbage token (the 30 s negative cache), for the life of the isolate. 5 000 entries is a
+ * few hundred KB and far more live tokens than one isolate sees; past it the oldest go first, and a
+ * token pushed out is simply validated again (KV still holds a good one).
+ */
+const l1 = new TtlCache(5_000);
+const l1Set = (key, entry, now) => l1.set(key, entry, entry.exp, now);
+/**
+ * The verifier's reason in words a person can act on. Its raw message can quote key material and
+ * internals, so only the kind is surfaced (the full reason is logged at the refusal); an unknown
+ * one keeps its code so it stays diagnosable.
+ */
+function plainReason(error) {
+    const message = error?.message ?? "";
+    const audience = /addressed to (\S+), not (\S+)/.exec(message);
+    if (audience) {
+        return `it was signed for ${audience[1]}, but this oracle is ${audience[2]} — use the id from /.well-known/did.json`;
+    }
+    if (error?.code === "EXPIRED" || /expired/i.test(message)) {
+        return "it has expired — sign a fresh request (and check the device clock)";
+    }
+    if (/not valid (yet|before)|too early/i.test(message)) {
+        return "it is not valid yet — check the device clock";
+    }
+    if (/resolve|No keys found/i.test(message)) {
+        return "the signer's DID could not be resolved to an Ed25519 key — check the DID publishes one on chain";
+    }
+    if (error?.code === "INVALID_SIGNATURE" || /signature/i.test(message)) {
+        return "its signature does not match the signer's DID key";
+    }
+    if (/Proof chain broken/i.test(message)) {
+        return "its proof chain does not connect: each grant must be issued to the next signer";
+    }
+    if (/Resource .* does not match/.test(message)) {
+        return `it is not for this service — the capability must be { with: "${RESOURCE}", can: "<the route's action>" }`;
+    }
+    if (error?.code === "INVALID_FORMAT") {
+        return "the Authorization header is not a UCAN token (a base64 CAR)";
+    }
+    return `it was refused (${error?.code ?? "unknown reason"})`;
+}
+/** The 401's message, as the Decision API's console verifier words it. */
+const signInRefused = (reason) => `This request's sign-in could not be verified: ${reason}.`;
+function bearer(c) {
+    const h = c.req.header("Authorization");
+    return h?.startsWith("Bearer ") ? h.slice(7).trim() : null;
+}
+/**
+ * AuthHub's approvals back-channel sends a bare `Authorization: Bearer <UCAN>` (its plan, Task 9):
+ * only a UCAN is accepted there anyway, so it needs no `X-Auth-Type` to say so.
+ */
+const UCAN_ONLY = /^\/v1\/oauth\//;
+export const ucanAuth = createMiddleware(async (c, next) => {
+    if (c.req.header("X-Auth-Type") !== "ucan" && !UCAN_ONLY.test(c.req.path)) {
+        throw AppError.unauthorized("This API needs a signed UCAN request: send the header X-Auth-Type: ucan with the token in Authorization: Bearer <token>.");
+    }
+    const token = bearer(c);
+    if (!token) {
+        throw AppError.unauthorized("This request has no sign-in token. Send the UCAN in the Authorization header as `Bearer <token>`.");
+    }
+    const config = c.get("config");
+    const key = await sha256Hex(token);
+    const now = Math.floor(Date.now() / 1000);
+    let principal;
+    const hit = l1.get(key, now);
+    countCache("ucan-l1", !!hit);
+    if (hit) {
+        // The reason is cached with the refusal, so a retry says what to fix too.
+        if ("invalid" in hit)
+            throw AppError.unauthorized(signInRefused(hit.invalid));
+        principal = hit.principal;
+    }
+    if (!principal) {
+        const l2 = await readCache("ucan", () => c.env.CACHE_KV.get(`ucan:${key}`, "json"));
+        // `invokerDid` and `can` post-date this cache format: an entry without them is re-validated
+        // rather than completed with a guess (SEC-06; the per-route action check needs the real `can`).
+        // So is one whose `exp` lies past the window — cached before the lifetime bound, it is refused
+        // by the re-validation. (Anything cached since passed the window, and `exp - now` only shrinks.)
+        if (l2?.invokerDid && l2.can && l2.exp > now && l2.exp - now <= MAX_LIFETIME_SEC) {
+            principal = l2;
+            l1Set(key, { exp: l2.exp, principal: l2 }, now);
+        }
+    }
+    if (!principal) {
+        const { validator, capabilities, parse, serviceDid } = await getValidator(config);
+        // Exactly ONE capability per invocation, naming an action this oracle has: its `can` is what
+        // the route check reads. Each refusal is deterministic, so it is negative-cached like any other.
+        const refuse = (reason) => {
+            l1Set(key, { exp: now + NEGATIVE_TTL_SEC, invalid: reason }, now);
+            throw AppError.unauthorized(signInRefused(reason));
+        };
+        let parsed;
+        try {
+            parsed = await parse(token);
+        }
+        catch {
+            return refuse(plainReason({ code: "INVALID_FORMAT", message: "" }));
+        }
+        const can = parsed.capabilities.length === 1 ? parsed.capabilities[0]?.can : undefined;
+        if (!can)
+            return refuse("it must carry exactly one capability, the route's action");
+        const capability = capabilities.get(can);
+        if (!capability) {
+            return refuse(`"${can.slice(0, 64)}" is not an action this oracle accepts`);
+        }
+        let result;
+        try {
+            result = await validator.validate(token, capability, RESOURCE);
+        }
+        catch (err) {
+            // Transient (DID resolution / network) — never cache, surface as 503.
+            throw AppError.unavailable("UCAN validation temporarily unavailable", err);
+        }
+        if (!result.ok || !result.invoker) {
+            const reason = plainReason(result.error);
+            l1Set(key, { exp: now + NEGATIVE_TTL_SEC, invalid: reason }, now);
+            // Log the FULL reason (not just the code) so a 401 is diagnosable: audience mismatch vs
+            // bad signature vs unresolvable issuer DID (e.g. no on-chain Ed25519 vm) each read differently.
+            c.get("logger").warn("ucan.invalid", {
+                code: result.error?.code,
+                reason: result.error?.message,
+                invoker: result.invoker ?? null,
+                expectedAudience: serviceDid,
+            });
+            throw AppError.unauthorized(signInRefused(reason));
+        }
+        // Authority is exercised only by the key that holds it (header): an invocation riding a
+        // delegation chain is refused, whatever it delegates.
+        const root = result.proofChain?.[0] ?? result.invoker;
+        if (root !== result.invoker) {
+            const reason = "delegated requests are not accepted — sign with your own key";
+            l1Set(key, { exp: now + NEGATIVE_TTL_SEC, invalid: reason }, now);
+            c.get("logger").warn("ucan.delegated-refused", { root, invoker: result.invoker });
+            throw AppError.unauthorized(signInRefused(reason));
+        }
+        // The window. `expiration` is the validator's (already checked not past); with no chain it is
+        // the invocation's own. ucanto reads a missing `exp` as never-expiring, so none is refused. A
+        // UCAN invocation carries no issued-at, so `exp - now` alone would accept a far-future token
+        // in its last MAX_LIFETIME_SEC; a stated `nbf` (off the parse above) bounds the whole window.
+        const exp = result.expiration;
+        if (typeof exp !== "number" || !Number.isFinite(exp)) {
+            return refuse(`it has no expiry — give it one of at most ${MAX_LIFETIME_SEC} s`);
+        }
+        const nbf = Number.isFinite(parsed.notBefore) ? parsed.notBefore : null;
+        if (exp - now > MAX_LIFETIME_SEC || (nbf !== null && exp - nbf > MAX_LIFETIME_SEC)) {
+            return refuse(`it is valid for too long — at most ${MAX_LIFETIME_SEC} s`);
+        }
+        principal = {
+            did: root,
+            address: root.split(":").at(2) ?? "",
+            invokerDid: result.invoker,
+            can,
+            exp,
+        };
+        // `exp - now` is ≤ MAX_LIFETIME_SEC here, so neither tier holds an entry past the window.
+        l1Set(key, { exp, principal }, now);
+        const ttl = exp - now;
+        if (ttl > 0) {
+            // KV's floor is 60 s; the `exp` inside the value is what a read trusts. The write rides
+            // behind the response (`waitUntil`) — the request already has its answer in L1 — and is
+            // simply awaited where there is no ExecutionContext (a direct `app.request` in a test).
+            const put = c.env.CACHE_KV.put(`ucan:${key}`, JSON.stringify(principal), {
+                expirationTtl: Math.max(60, ttl),
+            }).catch(() => { });
+            let deferred = false;
+            try {
+                c.executionCtx.waitUntil(put);
+                deferred = true;
+            }
+            catch {
+                // Hono throws when the request has no ExecutionContext.
+            }
+            if (!deferred)
+                await put;
+        }
+    }
+    c.set("principal", principal);
+    await next();
+});
+//# sourceMappingURL=ucan-auth.js.map

package/dist/middleware/ucan-auth.js.map

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

package/dist/networks.d.ts

@@ -0,0 +1,34 @@
+/**
+ * The ONE per-network map — what a deployment gets for free from `IXO_NETWORK`, and what the CLI's
+ * `--network` selects. A var set explicitly always wins (config.ts): a self-hosted Blocksync, a
+ * local engine, a tunnel. Engine hosts are the naming the decision engine deploys under.
+ */
+export type IxoNetwork = "devnet" | "testnet" | "mainnet";
+export interface NetworkDefaults {
+    engineHost: string;
+    blocksync: string;
+    rpc: string;
+    /** The chain's REST (LCD) API, beside the RPC — `org balance`'s bank read. */
+    rest: string;
+    matrix: string;
+    ucanStore: string;
+    /** The IXO Virtual Filesystem — the claims lane and public copies a claim body is read from first. */
+    vfs: string;
+    /** The IPFS gateway a claim body is read from when neither the VFS nor Matrix has it. */
+    ipfsGateway: string;
+    portal: string;
+    authHub: string;
+    /** The relayer node entity a new entity is created under (publish scripts). */
+    relayerNodeDid: string;
+    /** The domain indexer a newly created entity is announced to — `oracle init`'s last step. Host
+     *  only; the endpoint is `/index`. Same per-network naming qiforge uses (`src/utils/common.ts:70`),
+     *  where mainnet drops the network segment. */
+    domainIndexer: string;
+    /** IXO's x402 payment facilitator — the audience of a payment delegation the CLI signs
+     *  (`api review-billing enable`; the Decision Console's own per-network preset). The worker
+     *  reads its facilitator from `X402_FACILITATOR_URL`, never from here. */
+    facilitator: string;
+}
+export declare const NETWORKS: Record<IxoNetwork, NetworkDefaults>;
+export declare const networkDefaults: (network: IxoNetwork) => NetworkDefaults;
+//# sourceMappingURL=networks.d.ts.map

package/dist/networks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"networks.d.ts","sourceRoot":"","sources":["../src/networks.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,MAAM,UAAU,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAC1D,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;IAClB,GAAG,EAAE,MAAM,CAAC;IACZ,8EAA8E;IAC9E,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,sGAAsG;IACtG,GAAG,EAAE,MAAM,CAAC;IACZ,yFAAyF;IACzF,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,cAAc,EAAE,MAAM,CAAC;IACvB;;mDAE+C;IAC/C,aAAa,EAAE,MAAM,CAAC;IACtB;;8EAE0E;IAC1E,WAAW,EAAE,MAAM,CAAC;CACrB;AACD,eAAO,MAAM,QAAQ,EAAE,MAAM,CAAC,UAAU,EAAE,eAAe,CA8CxD,CAAC;AACF,eAAO,MAAM,eAAe,YAAa,UAAU,KAAG,eAAoC,CAAC"}

package/dist/networks.js

@@ -0,0 +1,49 @@
+export const NETWORKS = {
+    devnet: {
+        engineHost: "decision-engine.devnet.ixo.earth",
+        blocksync: "https://devnet-blocksync-graphql.ixo.earth/graphql",
+        rpc: "https://devnet.ixo.earth/rpc/",
+        rest: "https://devnet.ixo.earth/rest",
+        matrix: "https://devmx.ixo.earth",
+        ucanStore: "https://devnet.store.ucan.ixo.earth",
+        vfs: "https://devnet.vfs.ixo.earth",
+        ipfsGateway: "https://ipfs.gateway.ixo.world",
+        portal: "https://dev.portal.qi.space",
+        authHub: "https://dev.auth.ixo.earth",
+        relayerNodeDid: "did:ixo:entity:2f22535f8b179a51d77a0e302e68d35d",
+        domainIndexer: "https://domain-indexer.devnet.ixo.earth",
+        facilitator: "https://facilitator.devnet.ixo.earth",
+    },
+    testnet: {
+        engineHost: "decision-engine.testnet.ixo.earth",
+        blocksync: "https://testnet-blocksync-graphql.ixo.earth/graphql",
+        rpc: "https://testnet.ixo.earth/rpc/",
+        rest: "https://testnet.ixo.earth/rest",
+        matrix: "https://testmx.ixo.earth",
+        ucanStore: "https://testnet.store.ucan.ixo.earth",
+        vfs: "https://testnet.vfs.ixo.earth",
+        ipfsGateway: "https://ipfs.gateway.ixo.world",
+        portal: "https://test.portal.qi.space",
+        authHub: "https://test.auth.ixo.earth",
+        relayerNodeDid: "did:ixo:entity:3d079ebc0b332aad3305bb4a51c72edb",
+        domainIndexer: "https://domain-indexer.testnet.ixo.earth",
+        facilitator: "https://facilitator.testnet.ixo.earth",
+    },
+    mainnet: {
+        engineHost: "decision-engine.ixo.earth",
+        blocksync: "https://blocksync-graphql.ixo.earth/graphql",
+        rpc: "https://impacthub.ixo.world/rpc/",
+        rest: "https://impacthub.ixo.world/rest",
+        matrix: "https://mx.ixo.earth",
+        ucanStore: "https://store.ucan.ixo.earth",
+        vfs: "https://vfs.ixo.earth",
+        ipfsGateway: "https://ipfs.gateway.ixo.world",
+        portal: "https://portal.qi.space",
+        authHub: "https://auth.ixo.earth",
+        relayerNodeDid: "did:ixo:entity:2f22535f8b179a51d77a0e302e68d35d",
+        domainIndexer: "https://domain-indexer.ixo.earth",
+        facilitator: "https://facilitator.ixo.earth",
+    },
+};
+export const networkDefaults = (network) => NETWORKS[network];
+//# sourceMappingURL=networks.js.map

package/dist/networks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"networks.js","sourceRoot":"","sources":["../src/networks.ts"],"names":[],"mappings":"AA+BA,MAAM,CAAC,MAAM,QAAQ,GAAwC;IAC3D,MAAM,EAAE;QACN,UAAU,EAAE,kCAAkC;QAC9C,SAAS,EAAE,oDAAoD;QAC/D,GAAG,EAAE,+BAA+B;QACpC,IAAI,EAAE,+BAA+B;QACrC,MAAM,EAAE,yBAAyB;QACjC,SAAS,EAAE,qCAAqC;QAChD,GAAG,EAAE,8BAA8B;QACnC,WAAW,EAAE,gCAAgC;QAC7C,MAAM,EAAE,6BAA6B;QACrC,OAAO,EAAE,4BAA4B;QACrC,cAAc,EAAE,iDAAiD;QACjE,aAAa,EAAE,yCAAyC;QACxD,WAAW,EAAE,sCAAsC;KACpD;IACD,OAAO,EAAE;QACP,UAAU,EAAE,mCAAmC;QAC/C,SAAS,EAAE,qDAAqD;QAChE,GAAG,EAAE,gCAAgC;QACrC,IAAI,EAAE,gCAAgC;QACtC,MAAM,EAAE,0BAA0B;QAClC,SAAS,EAAE,sCAAsC;QACjD,GAAG,EAAE,+BAA+B;QACpC,WAAW,EAAE,gCAAgC;QAC7C,MAAM,EAAE,8BAA8B;QACtC,OAAO,EAAE,6BAA6B;QACtC,cAAc,EAAE,iDAAiD;QACjE,aAAa,EAAE,0CAA0C;QACzD,WAAW,EAAE,uCAAuC;KACrD;IACD,OAAO,EAAE;QACP,UAAU,EAAE,2BAA2B;QACvC,SAAS,EAAE,6CAA6C;QACxD,GAAG,EAAE,kCAAkC;QACvC,IAAI,EAAE,kCAAkC;QACxC,MAAM,EAAE,sBAAsB;QAC9B,SAAS,EAAE,8BAA8B;QACzC,GAAG,EAAE,uBAAuB;QAC5B,WAAW,EAAE,gCAAgC;QAC7C,MAAM,EAAE,yBAAyB;QACjC,OAAO,EAAE,wBAAwB;QACjC,cAAc,EAAE,iDAAiD;QACjE,aAAa,EAAE,kCAAkC;QACjD,WAAW,EAAE,+BAA+B;KAC7C;CACF,CAAC;AACF,MAAM,CAAC,MAAM,eAAe,GAAG,CAAC,OAAmB,EAAmB,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC"}

package/dist/oracle.d.ts

@@ -0,0 +1,193 @@
+/**
+ * YOUR oracle — the shape a provider passes to `defineOracle()` (define-oracle.ts), and the
+ * one-per-worker registry the rest of the kit reads it through.
+ *
+ * Everything else in this package is the machinery every evaluation oracle shares (pull, facts,
+ * decide-via-engine, act). What makes it *your* oracle is here: what it is called, which protocols'
+ * claims it knows how to produce facts for, HOW it produces the facts a rubric asks for, and the
+ * policies it acts under. Deployment-specific values (hosts, DIDs, keys) are NOT here — those are
+ * your wrangler.jsonc `vars` and `.dev.vars` secrets, validated by src/config.ts.
+ */
+import { z } from "zod";
+import type { ActPolicy } from "./act.js";
+import type { Config } from "./config.js";
+import type { FactsConfig } from "./facts/types.js";
+import type { FactsProducer } from "./lib/facts/producer.js";
+/**
+ * A per-protocol price this oracle could never charge is refused at module evaluation, not
+ * discovered as a surprise 402/409 the first time that protocol's collection registers: with a
+ * non-empty `supportedProtocols`, register's PROTOCOL gate (gate 3) turns away every collection
+ * whose protocol is not on the list, so gate 4 never reaches the price keyed under it.
+ */
+export declare const OracleConfigSchema: z.ZodObject<{
+    name: z.ZodString;
+    description: z.ZodString;
+    supportedProtocols: z.ZodArray<z.ZodString>;
+    pricing: z.ZodObject<{
+        evaluation: z.ZodObject<{
+            denom: z.ZodString;
+            minAmount: z.ZodString;
+        }, z.core.$strip>;
+        byProtocol: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            denom: z.ZodString;
+            minAmount: z.ZodString;
+        }, z.core.$strip>>>;
+        api: z.ZodOptional<z.ZodObject<{
+            amountMicroUsd: z.ZodInt;
+            byProtocol: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodInt>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>;
+    payouts: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        amount: z.ZodString;
+        currency: z.ZodUnion<readonly [z.ZodString, z.ZodObject<{
+            path: z.ZodString;
+        }, z.core.$strict>, z.ZodObject<{
+            asset: z.ZodString;
+            decimals: z.ZodInt;
+        }, z.core.$strict>]>;
+    }, z.core.$strict>>>;
+    policies: z.ZodObject<{
+        autoSign: z.ZodBoolean;
+        allowAiChecks: z.ZodBoolean;
+        allowImageChecks: z.ZodBoolean;
+        act: z.ZodOptional<z.ZodCustom<unknown, unknown>>;
+        actSummary: z.ZodOptional<z.ZodString>;
+        allowStandingApprovals: z.ZodBoolean;
+    }, z.core.$strip>;
+    facts: z.ZodOptional<z.ZodCustom<unknown, unknown>>;
+    archive: z.ZodOptional<z.ZodCustom<unknown, unknown>>;
+}, z.core.$strip>;
+/**
+ * The rubric is the work order — read from the engine's rubric manifest (lib/facts/expected.ts),
+ * never from rubric bytes: it lists every `ext.<name>` / `ai.<name>` the rubric declares, with its
+ * expected type and `onError`; a producer returns exactly those, any way it likes — HTTP, a model,
+ * a database, the engine's buyer statement — and the kit validates the answer against the work
+ * order (lib/facts/validate.ts) and assembles the rest of the FactSet (`answers`, `ctx`,
+ * `attachments`, `settings`) around it. The kit never decides and never binds — the engine judges
+ * the facts against the live form.
+ */
+export type OracleConfig = Omit<z.input<typeof OracleConfigSchema>, "facts" | "policies" | "archive"> & {
+    /** The policies, with the act seam typed: Zod carries the hook through, this is its contract. */
+    policies: Omit<z.input<typeof OracleConfigSchema>["policies"], "act"> & {
+        act?: ActPolicy;
+    };
+    /**
+     * `defineFacts({ ext, ai, unique, frequency })` — per-name handlers, every unlisted name still
+     * running its stock lane — or the whole-producer function for an oracle that assembles a
+     * FactSet its own way. Absent ⇒ stock everything.
+     */
+    facts?: FactsConfig | FactsProducer;
+    /**
+     * How the answer archive (`ANSWERS_ARCHIVE`, lib/archive.ts) reads YOUR asks and answers: the
+     * ask's own public documents → `about.json`, a claim body → the answer's text and place. Both
+     * optional; without them `about.json` carries the `#pro` name and the chain's window and pay,
+     * and `answer.json` no text or place (the claim's own `claim.json` always has everything).
+     */
+    archive?: ArchiveHooks;
+};
+/** One public document the ask's entity anchors (a LinkedResource or a setting), read as it is now. */
+export interface ArchiveDoc {
+    /** `{id}#done`, `{id}#pro`, … as anchored. */
+    id: string | null;
+    type: string | null;
+    /** The parsed document; null when it could not be read (`error` says why). */
+    json: unknown;
+    error?: string;
+}
+/** What `archive.describe` is handed: the ask's chain record and its documents, uninterpreted. */
+export interface ArchiveAsk {
+    /** The archive's ask id — the claim collection's id (an API scope's `api:<sourceId>:<protocolDid>`). */
+    askId: string;
+    /** The collection's entity (the deed); null on the API lane. */
+    entity: string | null;
+    alsoKnownAs: string | null;
+    /** The chain collection as Blocksync returns it (window, quota, payments); null on the API lane. */
+    collection: Record<string, unknown> | null;
+    docs: ArchiveDoc[];
+    /** Another entity's documents, read the same way (e.g. the organisation that posted the ask). */
+    docsOf(did: string): Promise<ArchiveDoc[]>;
+}
+export type ArchiveKind = "photo" | "observation" | "url-check" | "other";
+/** `about.json` — what the ask was about, as people saw it. */
+export interface ArchiveAbout {
+    askId: string;
+    title: string | null;
+    /** The ask's text as written. */
+    question: string | null;
+    kind: ArchiveKind;
+    place: {
+        name?: string;
+        lat?: number;
+        lon?: number;
+        radiusM?: number;
+    };
+    /** One approved answer's pay, in base units. */
+    reward: {
+        amount: string;
+        denom: string;
+    } | null;
+    postedBy: {
+        name?: string;
+    };
+    opensAt: string | null;
+    closesAt: string | null;
+    /** The two chain ids the ask can be proven by. */
+    proof: {
+        entity: string | null;
+        collection: string;
+    };
+}
+/** The answer as people read it, out of a claim body (`archive.answer`). */
+export interface ArchiveAnswerView {
+    text?: string | null;
+    /** Exact, as the claim carries it (the bucket is private). */
+    place?: {
+        lat: number;
+        lon: number;
+        accuracyM?: number;
+        at?: string;
+    } | null;
+}
+export interface ArchiveHooks {
+    /** The ask's people-facing view; whatever it leaves out keeps the package's default. */
+    describe?(ask: ArchiveAsk): Partial<ArchiveAbout> | Promise<Partial<ArchiveAbout>>;
+    /** The answer's text and place, from the claim body. */
+    answer?(claim: {
+        body: Record<string, unknown>;
+    }): ArchiveAnswerView;
+}
+/**
+ * The evaluation fee a collection of `protocolDid` is held to — `pricing.byProtocol[protocolDid]`
+ * (own keys only: an inherited name is not a protocol), else `pricing.evaluation`. Register's gate 4
+ * charges by it, and `oracle init` advertises the same number on the Agent Card.
+ */
+export declare function evaluationFeeFor<Fee>(pricing: {
+    evaluation: Fee;
+    byProtocol?: Record<string, Fee>;
+}, protocolDid: string): Fee;
+/**
+ * The pricing this deployment charges by: `pricing` with `evaluation` replaced by the per-network
+ * `EVALUATION_DENOM` / `EVALUATION_MIN_AMOUNT` vars when they are set (config.ts — both or neither,
+ * required on mainnet), else exactly what `defineOracle` was given. Register's gate 4 and
+ * `/v1/info` both read it, so `oracle init` cards the same fee the gate charges.
+ */
+export declare function effectivePricing<P extends {
+    evaluation: {
+        denom: string;
+        minAmount: string;
+    };
+}>(pricing: P, vars: Pick<Config, "EVALUATION_DENOM" | "EVALUATION_MIN_AMOUNT">): P;
+/** The registered oracle: the validated config minus `facts`, and the producer resolved from it. */
+export interface ResolvedOracle {
+    config: Omit<OracleConfig, "facts">;
+    /**
+     * The RAW object the provider passed to `defineOracle()` — kept for its IDENTITY alone (see
+     * `setOracle`), never read. `config` above is Zod's copy, which is a new object every call.
+     */
+    source: OracleConfig;
+    producer: FactsProducer;
+}
+export declare function setOracle(o: ResolvedOracle): void;
+export declare function getOracle(): ResolvedOracle;
+export declare function resetOracleForTests(): void;
+//# sourceMappingURL=oracle.d.ts.map

package/dist/oracle.d.ts.map

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