@ixo/decision-oracle 0.0.0-stage → 0.2.1

package/dist/lib/readiness.js

@@ -0,0 +1,130 @@
+/**
+ * Readiness (observability spec §6): can this oracle serve right now? One computation feeds two
+ * answers — the public `GET /health/ready` serves only its `ok`, and the operator's
+ * `GET /v1/admin/status` the per-check detail. An unauthenticated probe must learn nothing about
+ * our dependencies (no names, timings or hosts), which is why the detail is operator-only.
+ *
+ * Every check runs in parallel under a 2 s budget, never throws (a throw or a timeout is
+ * `ok: false`), and records its `ms`. `ok` is every CRITICAL check ok; every check here is
+ * critical — the oracle has no gas signer of its own to report as a non-critical one.
+ *
+ * The SETTLED result is cached per isolate for 15 s, and only one caller refreshes it — the rest
+ * keep serving the last answer meanwhile (a refresher is presumed dead after 2 × the check budget
+ * + 1 s). With the per-IP limiter in front of `/health/ready` (middleware/rate-limit.ts exempts
+ * only `/health` itself), a probe storm never fans out to D1/KV/the engine — the lever SEC-07
+ * removed the earlier, uncached probe for.
+ *
+ * `identity` is a config read, not a probe: a DEPLOYED oracle must have its on-chain identity
+ * (`decision-oracle oracle init` → `ORACLE_ENTITY_DID`). It is a readiness failure rather than a boot
+ * refusal because `oracle init` reads the running worker's `/v1/info` before the entity exists,
+ * and health/did.json must boot without config; a local `wrangler dev` host is exempt, so a fresh
+ * project runs before `oracle init`.
+ *
+ * `owner-delegation` is the same kind of config read: a set `OWNER_DELEGATION_CAR` must parse. Unset
+ * is fine (the review gate then skips the owner check); a broken one would fail every review answer
+ * loud (lib/review/reviewer-grant.ts `oracleOwnerDid`) while the console's hints read it as none.
+ */
+import { engineBaseUrl } from "./engine/client.js";
+import { fetchClient } from "./http/client.js";
+import { oracleOwnerDid } from "./review/reviewer-grant.js";
+const CHECK_TIMEOUT_MS = 2000;
+const CACHE_MS = 15_000;
+/** A local `wrangler dev` host — `localhost`, `127.0.0.1` or `*.localhost`, any port. */
+const LOCAL_HOST_RE = /^(localhost|127\.0\.0\.1|[^:]+\.localhost)(:\d+)?$/;
+let last;
+let refreshingSince = 0;
+export async function readiness(env, config, metrics) {
+    const now = Date.now();
+    if (last && now - last.at < CACHE_MS)
+        return last.value;
+    // Stale, but someone is already refreshing: serve the last answer rather than probe again.
+    if (last && now - refreshingSince < 2 * CHECK_TIMEOUT_MS + 1_000)
+        return last.value;
+    refreshingSince = now;
+    const value = await compute(env, config, metrics); // never throws
+    last = { at: Date.now(), value };
+    return value;
+}
+async function compute(env, config, metrics) {
+    const probes = {
+        d1: () => env.DB.prepare("select 1").first(),
+        kv: () => env.CACHE_KV.get("health:probe"),
+        // did.json, not an authenticated route: it proves the engine is up without minting anything.
+        engine: () => reachable(`${engineBaseUrl(config.EVAL_ENGINE_HOSTNAME)}/.well-known/did.json`),
+    };
+    // Only where it is on the request path: the API lane's payment gate. config.ts refuses
+    // API_PAYMENTS without X402_FACILITATOR_URL, so the URL is there whenever this runs.
+    const facilitator = config.API_LANE && config.API_PAYMENTS && config.X402_FACILITATOR_URL;
+    if (facilitator)
+        probes.facilitator = () => reachable(`${facilitator}/supported`);
+    const entries = await Promise.all(Object.entries(probes).map(async ([name, probe]) => {
+        const check = await run(probe);
+        metrics.gauge("health.check", check.ok ? 1 : 0, {
+            op: name,
+            outcome: check.ok ? "ok" : "fail",
+            ms: check.ms,
+        });
+        return [name, check];
+    }));
+    const id = identity(config);
+    metrics.gauge("health.check", id.ok ? 1 : 0, { op: "identity", outcome: id.ok ? "ok" : "fail" });
+    entries.push(["identity", id]);
+    const owner = await ownerDelegation(config);
+    metrics.gauge("health.check", owner.ok ? 1 : 0, {
+        op: "owner-delegation",
+        outcome: owner.ok ? "ok" : "fail",
+    });
+    entries.push(["owner-delegation", owner]);
+    const checks = Object.fromEntries(entries);
+    return { ok: entries.every(([, c]) => c.ok || !c.critical), checks };
+}
+function identity(config) {
+    if (config.ORACLE_ENTITY_DID || LOCAL_HOST_RE.test(config.ORACLE_HOSTNAME)) {
+        return { ok: true, ms: 0, critical: true };
+    }
+    return {
+        ok: false,
+        ms: 0,
+        critical: true,
+        detail: `no on-chain identity — run \`decision-oracle oracle init --protocol <did> --kit-url https://${config.ORACLE_HOSTNAME} --yes\`, then set ORACLE_ENTITY_DID`,
+    };
+}
+async function ownerDelegation(config) {
+    try {
+        await oracleOwnerDid(config);
+        return { ok: true, ms: 0, critical: true };
+    }
+    catch {
+        return {
+            ok: false,
+            ms: 0,
+            critical: true,
+            detail: "OWNER_DELEGATION_CAR is not a UCAN delegation — mint it again with `decision-oracle delegation --for engine` and set it",
+        };
+    }
+}
+async function run(probe) {
+    const started = Date.now();
+    let timer;
+    const timeout = new Promise((_, reject) => {
+        timer = setTimeout(() => reject(new Error("timeout")), CHECK_TIMEOUT_MS);
+    });
+    let ok = true;
+    try {
+        await Promise.race([probe(), timeout]);
+    }
+    catch {
+        ok = false;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+    return { ok, ms: Date.now() - started, critical: true };
+}
+async function reachable(url) {
+    const res = await fetchClient(url, { timeoutMs: CHECK_TIMEOUT_MS });
+    await res.body?.cancel().catch(() => { });
+    if (!res.ok)
+        throw new Error(`HTTP ${res.status}`);
+}
+//# sourceMappingURL=readiness.js.map

package/dist/lib/readiness.js.map

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

package/dist/lib/redact.d.ts

@@ -0,0 +1,23 @@
+/**
+ * What never leaves this service in a log line, a Sentry event or an ops alert (observability spec
+ * §1.3, §3). Its own module, free of any runtime import, so the logger — which the node-safe facts
+ * lane reaches — can redact without pulling `@sentry/cloudflare` in.
+ *
+ * `answers`/`facts` are here for the erasure design, not for secrecy: the engine's immutable signed
+ * receipt can coexist with lawful erasure only because the durable artifacts never carry answer
+ * text, and a log line or a Sentry event is a durable artifact we do not control. The API lane's
+ * personal fields (`submitter`, `metadata`, a contact `email`, a caller's `webhookUrl` — whose query
+ * string may carry the receiver's own credential — and an operator's `notes`) go for the same reason.
+ */
+/**
+ * Matched case-insensitively on a substring, so `accessToken`/`ORACLE_MATRIX_ACCESS_TOKEN` both go.
+ */
+export declare const SENSITIVE_KEYS: string[];
+export declare const isSensitive: (key: string) => boolean;
+/**
+ * Depth-bounded redaction — events are JSON-ish and deep recursion on a cyclic error is a hazard.
+ * Only plain objects and arrays are walked: an `Error` or a `Date` passes through untouched, so the
+ * logger's serializer still sees what it knows how to print.
+ */
+export declare function redact(value: unknown, depth?: number): unknown;
+//# sourceMappingURL=redact.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../../src/lib/redact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,eAAO,MAAM,cAAc,UAmB1B,CAAC;AAWF,eAAO,MAAM,WAAW,QAAS,MAAM,KAAG,OAIzC,CAAC;AAEF;;;;GAIG;AACH,wBAAgB,MAAM,CAAC,KAAK,EAAE,OAAO,EAAE,KAAK,SAAI,GAAG,OAAO,CAUzD"}

package/dist/lib/redact.js

@@ -0,0 +1,67 @@
+/**
+ * What never leaves this service in a log line, a Sentry event or an ops alert (observability spec
+ * §1.3, §3). Its own module, free of any runtime import, so the logger — which the node-safe facts
+ * lane reaches — can redact without pulling `@sentry/cloudflare` in.
+ *
+ * `answers`/`facts` are here for the erasure design, not for secrecy: the engine's immutable signed
+ * receipt can coexist with lawful erasure only because the durable artifacts never carry answer
+ * text, and a log line or a Sentry event is a durable artifact we do not control. The API lane's
+ * personal fields (`submitter`, `metadata`, a contact `email`, a caller's `webhookUrl` — whose query
+ * string may carry the receiver's own credential — and an operator's `notes`) go for the same reason.
+ */
+/**
+ * Matched case-insensitively on a substring, so `accessToken`/`ORACLE_MATRIX_ACCESS_TOKEN` both go.
+ */
+export const SENSITIVE_KEYS = [
+    "authorization",
+    "mnemonic",
+    "secret",
+    "token",
+    "apikey",
+    "api_key",
+    "password",
+    "delegationcar",
+    "answers",
+    "answer",
+    "facts",
+    "trace",
+    "signature",
+    "submitter",
+    "metadata",
+    "email",
+    "webhookurl",
+    "notes",
+];
+/**
+ * The substring match above would also take `traceId`, `factsDigest`, `submitterDigest`,
+ * `answeredAt` and an AI check's `promptTokens`/`completionTokens` — identifiers, hashes, counts and timestamps, which
+ * are exactly what makes a log line joinable and must survive. A key with one of these camelCase
+ * suffixes is never a value, so it is kept.
+ */
+const SAFE_SUFFIX = /(Id|Ids|Hash|Digest|Count|Ms|At|(prompt|completion|cached|total|reasoning)Tokens)$/;
+export const isSensitive = (key) => {
+    if (SAFE_SUFFIX.test(key))
+        return false;
+    const k = key.toLowerCase();
+    return SENSITIVE_KEYS.some((s) => k.includes(s));
+};
+/**
+ * Depth-bounded redaction — events are JSON-ish and deep recursion on a cyclic error is a hazard.
+ * Only plain objects and arrays are walked: an `Error` or a `Date` passes through untouched, so the
+ * logger's serializer still sees what it knows how to print.
+ */
+export function redact(value, depth = 0) {
+    if (depth > 6 || value === null || typeof value !== "object")
+        return value;
+    if (Array.isArray(value))
+        return value.map((v) => redact(v, depth + 1));
+    const proto = Object.getPrototypeOf(value);
+    if (proto !== Object.prototype && proto !== null)
+        return value;
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        out[k] = isSensitive(k) ? "[redacted]" : redact(v, depth + 1);
+    }
+    return out;
+}
+//# sourceMappingURL=redact.js.map

package/dist/lib/redact.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"redact.js","sourceRoot":"","sources":["../../src/lib/redact.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG;IAC5B,eAAe;IACf,UAAU;IACV,QAAQ;IACR,OAAO;IACP,QAAQ;IACR,SAAS;IACT,UAAU;IACV,eAAe;IACf,SAAS;IACT,QAAQ;IACR,OAAO;IACP,OAAO;IACP,WAAW;IACX,WAAW;IACX,UAAU;IACV,OAAO;IACP,YAAY;IACZ,OAAO;CACR,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,GACf,oFAAoF,CAAC;AAEvF,MAAM,CAAC,MAAM,WAAW,GAAG,CAAC,GAAW,EAAW,EAAE;IAClD,IAAI,WAAW,CAAC,IAAI,CAAC,GAAG,CAAC;QAAE,OAAO,KAAK,CAAC;IACxC,MAAM,CAAC,GAAG,GAAG,CAAC,WAAW,EAAE,CAAC;IAC5B,OAAO,cAAc,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,CAAC;AACnD,CAAC,CAAC;AAEF;;;;GAIG;AACH,MAAM,UAAU,MAAM,CAAC,KAAc,EAAE,KAAK,GAAG,CAAC;IAC9C,IAAI,KAAK,GAAG,CAAC,IAAI,KAAK,KAAK,IAAI,IAAI,OAAO,KAAK,KAAK,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC3E,IAAI,KAAK,CAAC,OAAO,CAAC,KAAK,CAAC;QAAE,OAAO,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC,CAAC;IACxE,MAAM,KAAK,GAAG,MAAM,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IAC3C,IAAI,KAAK,KAAK,MAAM,CAAC,SAAS,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,KAAK,CAAC;IAC/D,MAAM,GAAG,GAA4B,EAAE,CAAC;IACxC,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,KAAgC,CAAC,EAAE,CAAC;QACtE,GAAG,CAAC,CAAC,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,YAAY,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,EAAE,KAAK,GAAG,CAAC,CAAC,CAAC;IAChE,CAAC;IACD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/lib/register.d.ts

@@ -0,0 +1,85 @@
+/**
+ * The register logic behind `POST /v1/collections/register` (routes/v1/collections.ts) AND the
+ * `registerCollection` runtime export (../runtime.ts) — one interface, two callers. The route is
+ * UCAN-guarded HTTP; a provider's own Workflow calls this directly when it registers a collection
+ * as the oracle's own principal (after minting its own evaluate grant), where there is no request
+ * to validate a body against and no `c.env` to read bindings off.
+ *
+ * The four gates (WHO/HIRED/PROTOCOL/PAID), the delegation resolution, the upsert and the
+ * paused→active notice are unchanged from the route's original body — see routes/v1/collections.ts'
+ * header comment for the enrollment rules this enforces. `RegisterCtx` is what either caller can
+ * assemble: the route from its request-scoped Hono context, the runtime from `env` via
+ * `cronContext`-style plumbing (cron/scan.ts).
+ */
+import type { Config } from "../config.js";
+import type { Database } from "../db/client.js";
+import { type WatchedCollection } from "../db/schema.js";
+import type { OracleEnv } from "../env.js";
+import type { Logger } from "./logger.js";
+import type { Metrics } from "./metrics.js";
+import type { TraceContext } from "./tracing.js";
+/**
+ * The chain owner or the current enroller of a watched row — who may redirect its notices
+ * (re-register, below) and pause or resume it (routes/v1/shared.ts `assertCanManage`). A plain grant
+ * holder is neither: a competing oracle hired on the same collection holds a grant by definition.
+ */
+export declare function isOwnerOrEnroller(row: Pick<WatchedCollection, "ownerDid" | "enrolledByDid">, did: string): boolean;
+export interface RegisterCtx {
+    config: Config;
+    trace: TraceContext;
+    logger: Logger;
+    metrics: Metrics;
+    db: Database;
+    /** Bindings the delegation resolution and the resume notice need — `c.env` on the route. */
+    env: Pick<OracleEnv, "CACHE_KV" | "EMAIL">;
+}
+export interface RegisterInput {
+    collectionId: string;
+    principal: {
+        did: string;
+        address: string;
+    };
+    contactEmail?: string;
+    delegationCar?: string;
+    /**
+     * Scan watermark applied on FIRST registration only (where the route seeds `cursor: new
+     * Date().toISOString()` today); a re-register never rewinds. `null` = scan from claim zero (the
+     * existing NULL-cursor CLAIMS_FROM_START path); absent = today's behaviour (seed to now). For
+     * collections whose claims may arrive before the oracle registers them.
+     */
+    cursor?: string | null;
+}
+/**
+ * Register (or re-register) a collection with this oracle — the four gates, the delegation
+ * resolution, the upsert and the paused→active notice, in that order. See
+ * routes/v1/collections.ts for the WHO/HIRED/PROTOCOL/PAID rules this enforces; behaviour here is
+ * byte-for-byte what the route did before this function existed.
+ */
+export declare function registerCollection(ctx: RegisterCtx, input: RegisterInput): Promise<WatchedCollection>;
+/** What the engine's company read needs: a register's context, or the backfill's. */
+type CompanyCtx = Pick<RegisterCtx, "config" | "trace" | "logger"> & {
+    env: Pick<OracleEnv, "CACHE_KV">;
+};
+/** Collections one backfill call visits when it names none. */
+export declare const RELINK_CAP = 100;
+export type RelinkOutcome = "linked" | "unchanged" | "no-company" | "disputed" | "unavailable" | "not-watched";
+/**
+ * The backfill of register's company links for collections watched before it linked them
+ * (`POST /v1/admin/collections/relink`): per collection, the SAME engine read and the SAME
+ * `linkCompanySources` register runs, so a re-run is a no-op. `collectionIds` names them (an id
+ * this oracle does not watch is `not-watched`); absent ⇒ every watched collection, lowest id first,
+ * up to `RELINK_CAP` (`truncated` says more exist — name them). A collection with no unlinked
+ * active source is `unchanged` without an engine call.
+ */
+export declare function relinkCollections(ctx: CompanyCtx & {
+    db: Database;
+}, collectionIds?: string[]): Promise<{
+    items: {
+        collectionId: string;
+        outcome: RelinkOutcome;
+        linkedSources: string[];
+    }[];
+    truncated: boolean;
+}>;
+export {};
+//# sourceMappingURL=register.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"register.d.ts","sourceRoot":"","sources":["../../src/lib/register.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAC7C,OAAO,EAAc,KAAK,iBAAiB,EAAsB,MAAM,cAAc,CAAC;AACtF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,QAAQ,CAAC;AAaxC,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AACvC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAQzC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AAE9C;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,IAAI,CAAC,iBAAiB,EAAE,UAAU,GAAG,eAAe,CAAC,EAC1D,GAAG,EAAE,MAAM,GACV,OAAO,CAET;AAED,MAAM,WAAW,WAAW;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,YAAY,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,EAAE,EAAE,QAAQ,CAAC;IACb,4FAA4F;IAC5F,GAAG,EAAE,IAAI,CAAC,SAAS,EAAE,UAAU,GAAG,OAAO,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,aAAa;IAC5B,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC;IAC5C,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACxB;AAED;;;;;GAKG;AACH,wBAAsB,kBAAkB,CACtC,GAAG,EAAE,WAAW,EAChB,KAAK,EAAE,aAAa,GACnB,OAAO,CAAC,iBAAiB,CAAC,CA+T5B;AAsBD,qFAAqF;AACrF,KAAK,UAAU,GAAG,IAAI,CAAC,WAAW,EAAE,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC,GAAG;IACnE,GAAG,EAAE,IAAI,CAAC,SAAS,EAAE,UAAU,CAAC,CAAC;CAClC,CAAC;AAqDF,+DAA+D;AAC/D,eAAO,MAAM,UAAU,MAAM,CAAC;AAE9B,MAAM,MAAM,aAAa,GACrB,QAAQ,GACR,WAAW,GACX,YAAY,GACZ,UAAU,GACV,aAAa,GACb,aAAa,CAAC;AAElB;;;;;;;GAOG;AACH,wBAAsB,iBAAiB,CACrC,GAAG,EAAE,UAAU,GAAG;IAAE,EAAE,EAAE,QAAQ,CAAA;CAAE,EAClC,aAAa,CAAC,EAAE,MAAM,EAAE,GACvB,OAAO,CAAC;IACT,KAAK,EAAE;QAAE,YAAY,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,aAAa,CAAC;QAAC,aAAa,EAAE,MAAM,EAAE,CAAA;KAAE,EAAE,CAAC;IACnF,SAAS,EAAE,OAAO,CAAC;CACpB,CAAC,CAsCD"}