@ixo/decision-oracle 0.0.0-stage → 0.2.1

package/dist/middleware/capability.js

@@ -0,0 +1,113 @@
+/**
+ * One capability per route on the chain lane (owner, 2026-09-30 — CLAUDE.md "Capabilities: one
+ * action per route, never `*`"). Every UCAN-guarded chain-lane route accepts exactly ONE `can` on
+ * `ixo:eval-oracle`, listed here: the single source of truth a caller (a portal, the CLI, the
+ * engine's status board) maps its calls against. The Decision API lane (`/v1/api/*`) has its own
+ * auth and is not in this table; the public routes (`/v1/info`, `/health`, did.json) never reach it.
+ *
+ * Transitional: the legacy `*` still passes while portals, consoles and the engine switch, and is
+ * logged (`ucan.wildcard`, route + invoker only) so the strict step knows who still sends it — and
+ * counted (`ucan.wildcard`, the route only) so that step can rest on Analytics Engine data.
+ */
+import { createMiddleware } from "hono/factory";
+import { AppError } from "../lib/errors.js";
+/** Until the strict step: an invocation still minting `{ can: "*" }` keeps working. */
+export const ACCEPT_WILDCARD = true;
+/** [method, path pattern (`:param` = one segment), the one action it accepts]. */
+export const ROUTE_ACTIONS = [
+    ["POST", "/v1/collections/register", "collections/register"],
+    ["GET", "/v1/collections", "collections/read"],
+    ["POST", "/v1/collections/:collectionId/pause", "collections/pause"],
+    ["POST", "/v1/collections/:collectionId/resume", "collections/resume"],
+    ["POST", "/v1/collections/:collectionId/scan", "collections/scan"],
+    // The owner's settings (company authority D7) — strict from day one, below.
+    ["PATCH", "/v1/collections/:collectionId/settings", "collections/settings"],
+    ["GET", "/v1/collections/:collectionId/settings", "collections/settings-read"],
+    // The company's reviewers (company authority D2) — strict from day one, below.
+    ["POST", "/v1/collections/:collectionId/reviewers", "collections/reviewers-grant"],
+    ["GET", "/v1/collections/:collectionId/reviewers", "collections/reviewers-read"],
+    [
+        "POST",
+        "/v1/collections/:collectionId/reviewers/:delegationCid/revoke",
+        "collections/reviewers-revoke",
+    ],
+    ["GET", "/v1/claims", "claims/read"],
+    ["GET", "/v1/claims/:claimId", "claims/read"],
+    // The owner's erase (company authority F14) — strict from day one, below.
+    ["DELETE", "/v1/claims/:claimId/body", "claims/erase"],
+    ["GET", "/v1/reviews/:claimId", "reviews/read"],
+    ["POST", "/v1/reviews/:claimId", "reviews/submit"],
+    ["GET", "/v1/admin/status", "admin/status"],
+    // The operator's company-link backfill (lib/register.ts) — strict from day one, below.
+    ["POST", "/v1/admin/collections/relink", "admin/collections-relink"],
+    // AuthHub's approvals back-channel (MCP over OAuth, S7) — strict from day one, below.
+    ["GET", "/v1/oauth/approvals/:approvalId", "oauth/approval/read"],
+    ["POST", "/v1/oauth/approvals/:approvalId", "oauth/approval/approve"],
+    // …and its auto-approve ("don't ask again") standing authority, per grant.
+    ["GET", "/v1/oauth/standing/:grantId", "oauth/standing/read"],
+    ["PUT", "/v1/oauth/standing/:grantId", "oauth/standing/set"],
+    ["DELETE", "/v1/oauth/standing/:grantId", "oauth/standing/revoke"],
+];
+/** Actions the legacy `*` NEVER stands in for, whatever `ACCEPT_WILDCARD` says (S3 review §3). */
+export const STRICT_ACTIONS = new Set([
+    "collections/settings",
+    "collections/settings-read",
+    "collections/reviewers-grant",
+    "collections/reviewers-read",
+    "collections/reviewers-revoke",
+    // An erase cannot be undone: only a token minted for it.
+    "claims/erase",
+    // A review answer settles a verdict (the fold acts on it): a token that can do anything may not.
+    "reviews/submit",
+    "admin/collections-relink",
+    "oauth/approval/read",
+    "oauth/approval/approve",
+    "oauth/standing/read",
+    "oauth/standing/set",
+    "oauth/standing/revoke",
+]);
+/** Every `can` `ucanAuth` will validate at all: the table's actions, plus `*` while it is accepted. */
+export const ACCEPTED_CANS = [
+    ...new Set([
+        ...ROUTE_ACTIONS.map(([, , action]) => action),
+        ...(ACCEPT_WILDCARD ? ["*"] : []),
+    ]),
+];
+const MATCHERS = ROUTE_ACTIONS.map(([method, pattern, action]) => ({
+    method,
+    pattern,
+    action,
+    // `:param` is one path segment; a trailing slash is the same route (Hono's non-strict routing).
+    re: new RegExp(`^${pattern.replace(/:[A-Za-z]+/g, "[^/]+")}/?$`),
+}));
+/** The route a request hits and the action it needs, or null for a route with no entry. HEAD is
+ *  its GET (Hono answers HEAD with the GET handler), so it takes the GET's action. */
+export function actionFor(method, path) {
+    const verb = method.toUpperCase() === "HEAD" ? "GET" : method.toUpperCase();
+    const m = MATCHERS.find((m) => m.method === verb && m.re.test(path));
+    return m ? { pattern: m.pattern, action: m.action } : null;
+}
+/** After `ucanAuth`: the invocation's one `can` must be this route's action (or, while
+ *  `ACCEPT_WILDCARD`, `*` — never on a `STRICT_ACTIONS` route). A `*` on a route with no entry
+ *  falls through to its 404. */
+export const requireAction = createMiddleware(async (c, next) => {
+    const principal = c.get("principal");
+    const route = actionFor(c.req.method, c.req.path);
+    if (ACCEPT_WILDCARD && principal.can === "*" && !(route && STRICT_ACTIONS.has(route.action))) {
+        if (route) {
+            const pattern = `${c.req.method} ${route.pattern}`;
+            c.get("logger").info("ucan.wildcard", { route: pattern, invoker: principal.invokerDid });
+            // The pattern, never the path or a DID: one series per table row.
+            c.get("metrics").count("ucan.wildcard", 1, { route: pattern });
+        }
+        return next();
+    }
+    if (!route) {
+        throw AppError.forbidden(`No capability opens ${c.req.method} ${c.req.path} on this oracle (got "${principal.can}")`);
+    }
+    if (principal.can !== route.action) {
+        throw AppError.forbidden(`This route accepts only the "${route.action}" capability on ixo:eval-oracle (got "${principal.can}")`);
+    }
+    return next();
+});
+//# sourceMappingURL=capability.js.map

package/dist/middleware/capability.js.map

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

package/dist/middleware/database.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Per-request database access.
+ *
+ * Installs `c.var.db()` on the request context. With D1 there is nothing to open or close — the
+ * getter just wraps the `DB` binding in Drizzle — but it stays a function so handlers read the
+ * same way they do in the eval engine and the call site never cares which database is behind it.
+ *
+ * Usage in a handler:
+ *   const db = await c.var.db();
+ *   const rows = await db.select().from(watchedCollections);
+ */
+import type { AppEnv } from "../context.js";
+export declare const database: import("hono").MiddlewareHandler<AppEnv, string, {}, Response>;
+//# sourceMappingURL=database.d.ts.map

package/dist/middleware/database.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.d.ts","sourceRoot":"","sources":["../../src/middleware/database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGzC,eAAO,MAAM,QAAQ,gEAGnB,CAAC"}

package/dist/middleware/database.js

@@ -0,0 +1,18 @@
+/**
+ * Per-request database access.
+ *
+ * Installs `c.var.db()` on the request context. With D1 there is nothing to open or close — the
+ * getter just wraps the `DB` binding in Drizzle — but it stays a function so handlers read the
+ * same way they do in the eval engine and the call site never cares which database is behind it.
+ *
+ * Usage in a handler:
+ *   const db = await c.var.db();
+ *   const rows = await db.select().from(watchedCollections);
+ */
+import { createMiddleware } from "hono/factory";
+import { getDb } from "../db/client.js";
+export const database = createMiddleware(async (c, next) => {
+    c.set("db", async () => getDb(c.env));
+    await next();
+});
+//# sourceMappingURL=database.js.map

package/dist/middleware/database.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"database.js","sourceRoot":"","sources":["../../src/middleware/database.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAE,KAAK,EAAE,MAAM,cAAc,CAAC;AAErC,MAAM,CAAC,MAAM,QAAQ,GAAG,gBAAgB,CAAS,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;IACjE,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;IACtC,MAAM,IAAI,EAAE,CAAC;AACf,CAAC,CAAC,CAAC"}

package/dist/middleware/error-handler.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Global error handling + 404.
+ *
+ * Every throw in the app funnels through `onError`: it normalizes the error to an
+ * `AppError`, logs it once with full context (stack, requestId, traceId), records
+ * an error metric, and returns the stable JSON envelope. Internal (5xx) details
+ * are never leaked to clients — they live only in Workers Logs.
+ */
+import type { ErrorHandler, NotFoundHandler } from "hono";
+import type { AppEnv } from "../context.js";
+export declare const onError: ErrorHandler<AppEnv>;
+export declare const notFound: NotFoundHandler<AppEnv>;
+//# sourceMappingURL=error-handler.d.ts.map

package/dist/middleware/error-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.d.ts","sourceRoot":"","sources":["../../src/middleware/error-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,MAAM,CAAC;AAI1D,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAmDzC,eAAO,MAAM,OAAO,EAAE,YAAY,CAAC,MAAM,CAmExC,CAAC;AAEF,eAAO,MAAM,QAAQ,EAAE,eAAe,CAAC,MAAM,CAW5C,CAAC"}

package/dist/middleware/error-handler.js

@@ -0,0 +1,127 @@
+/**
+ * Global error handling + 404.
+ *
+ * Every throw in the app funnels through `onError`: it normalizes the error to an
+ * `AppError`, logs it once with full context (stack, requestId, traceId), records
+ * an error metric, and returns the stable JSON envelope. Internal (5xx) details
+ * are never leaked to clients — they live only in Workers Logs.
+ */
+import { HTTPException } from "hono/http-exception";
+import { routePath } from "hono/route";
+import { ZodError } from "zod";
+import { AppError, toErrorBody, VALIDATION_FAILED } from "../lib/errors.js";
+import { createLogger } from "../lib/logger.js";
+import { reportError } from "../lib/sentry.js";
+import { endpointOf, loggedPath } from "./observability.js";
+/** Coerce anything thrown into a typed AppError. */
+function normalize(err) {
+    if (err instanceof AppError)
+        return err;
+    if (err instanceof ZodError) {
+        return AppError.validation(VALIDATION_FAILED, {
+            issues: err.issues.map((i) => ({
+                path: i.path.join("."),
+                message: i.message,
+            })),
+        });
+    }
+    if (err instanceof HTTPException) {
+        const expose = err.status < 500;
+        return new AppError(err.message || "Request failed", {
+            code: err.status === 401 ? "UNAUTHORIZED" : err.status === 403 ? "FORBIDDEN" : "BAD_REQUEST",
+            status: err.status,
+            expose,
+            cause: err,
+        });
+    }
+    return AppError.internal("Unhandled error", err);
+}
+/**
+ * The `cause` chain's messages, outermost first. Bounded at 4 links so a self-referential or deeply
+ * wrapped error can't turn one log line into a wall — and `seen` because a cause cycle would
+ * otherwise loop forever inside the error handler, turning a 500 into a hang.
+ */
+function causeChain(err) {
+    const messages = [];
+    const seen = new Set();
+    let current = err;
+    while (current && messages.length < 4 && !seen.has(current)) {
+        seen.add(current);
+        const next = current.cause;
+        if (!next)
+            break;
+        messages.push(next instanceof Error ? next.message : String(next));
+        current = next;
+    }
+    return messages;
+}
+export const onError = (err, c) => {
+    const appError = normalize(err);
+    const requestId = c.get("requestId") ?? "unknown";
+    // Logger should always be set by the observability middleware; fall back so we
+    // never lose an error to a missing logger.
+    // Fallback fires only if the observability middleware never set a logger
+    // (e.g. config parse threw), so read the raw env var — don't re-run loadConfig.
+    const logger = c.get("logger") ??
+        createLogger({
+            level: "error",
+            pretty: c.env.LOG_PRETTY === "true",
+            base: { requestId },
+        });
+    const logFields = {
+        code: appError.code,
+        status: appError.status,
+        err: appError.expose ? appError : (appError.cause ?? appError),
+        // The REASON, not just the throw site. Drizzle reports `Failed query: select …` and hides the
+        // actual database message (`no such column: x`) one level down in `cause`; the same is
+        // true of most wrapped I/O errors. Without this a schema drift reads as an anonymous 500 and
+        // costs a debugging session to identify — it cost two today.
+        causedBy: causeChain(appError),
+        path: loggedPath(c),
+        method: c.req.method,
+    };
+    // An EXPECTED 5xx is a decision, not a failure (the API lane's `503 SOURCE_PAUSED`): no Sentry.
+    if (appError.status >= 500 && !appError.expected) {
+        logger.error("request_failed", logFields);
+        c.get("metrics")?.count("errors", 1, { route: endpointOf(c), status: appError.code });
+        // 5xx ONLY. Every 4xx here is a negative this service decided on purpose (a bad body, a missing
+        // capability, a claim the dashboard polled too early) — routing those to Sentry would bury the
+        // one class of event nobody chose. Report the ORIGINAL throw, not the normalized envelope: the
+        // envelope's stack ends in this handler, the cause's ends where it broke.
+        reportError(appError.cause ?? err, {
+            lane: "http",
+            context: {
+                code: appError.code,
+                status: appError.status,
+                method: c.req.method,
+                // BOTH: the matched pattern is what makes two failures the same failure, and the concrete
+                // path is what names the claim/collection that hit it (`/v1/claims/bafy…`) — never under
+                // `/v1/api`, where it can name a pending source (`loggedPath`).
+                route: routePath(c),
+                path: loggedPath(c),
+                // The join back to Workers Logs — the request's own log line carries the same id.
+                requestId,
+            },
+        });
+    }
+    else if (appError.expected) {
+        // An expected negative (dashboard polling a not-yet-ingested claim): SILENT in deployed envs.
+        // Debug, not nothing — local dev runs LOG_LEVEL=debug and keeps the breadcrumb.
+        logger.debug("request_rejected", logFields);
+    }
+    else {
+        logger.warn("request_rejected", logFields);
+    }
+    // The readiness contract holds even when the route never ran (a config that fails to load): a
+    // monitor reads `{ ok }`, and the envelope would name what broke to an unauthenticated caller.
+    // A 429 keeps its standard envelope.
+    if (c.req.path === "/health/ready" && appError.status >= 500) {
+        return c.json({ ok: false }, 503);
+    }
+    return c.json(toErrorBody(appError, requestId), appError.status);
+};
+export const notFound = (c) => {
+    const requestId = c.get("requestId") ?? "unknown";
+    return c.json(toErrorBody(AppError.notFound(`There is no ${c.req.method} ${c.req.path} on this oracle. Check the method and path.`), requestId), 404);
+};
+//# sourceMappingURL=error-handler.js.map

package/dist/middleware/error-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.js","sourceRoot":"","sources":["../../src/middleware/error-handler.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,qBAAqB,CAAC;AACpD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,QAAQ,EAAE,MAAM,KAAK,CAAC;AAE/B,OAAO,EAAE,QAAQ,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AACzE,OAAO,EAAE,YAAY,EAAe,MAAM,eAAe,CAAC;AAC1D,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAEzD,oDAAoD;AACpD,SAAS,SAAS,CAAC,GAAY;IAC7B,IAAI,GAAG,YAAY,QAAQ;QAAE,OAAO,GAAG,CAAC;IAExC,IAAI,GAAG,YAAY,QAAQ,EAAE,CAAC;QAC5B,OAAO,QAAQ,CAAC,UAAU,CAAC,iBAAiB,EAAE;YAC5C,MAAM,EAAE,GAAG,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;gBAC7B,IAAI,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC;gBACtB,OAAO,EAAE,CAAC,CAAC,OAAO;aACnB,CAAC,CAAC;SACJ,CAAC,CAAC;IACL,CAAC;IAED,IAAI,GAAG,YAAY,aAAa,EAAE,CAAC;QACjC,MAAM,MAAM,GAAG,GAAG,CAAC,MAAM,GAAG,GAAG,CAAC;QAChC,OAAO,IAAI,QAAQ,CAAC,GAAG,CAAC,OAAO,IAAI,gBAAgB,EAAE;YACnD,IAAI,EAAE,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,cAAc,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,KAAK,GAAG,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,aAAa;YAC5F,MAAM,EAAE,GAAG,CAAC,MAAM;YAClB,MAAM;YACN,KAAK,EAAE,GAAG;SACX,CAAC,CAAC;IACL,CAAC;IAED,OAAO,QAAQ,CAAC,QAAQ,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;AACnD,CAAC;AAED;;;;GAIG;AACH,SAAS,UAAU,CAAC,GAAY;IAC9B,MAAM,QAAQ,GAAa,EAAE,CAAC;IAC9B,MAAM,IAAI,GAAG,IAAI,GAAG,EAAW,CAAC;IAChC,IAAI,OAAO,GAAY,GAAG,CAAC;IAC3B,OAAO,OAAO,IAAI,QAAQ,CAAC,MAAM,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QAC5D,IAAI,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC;QAClB,MAAM,IAAI,GAAa,OAA+B,CAAC,KAAK,CAAC;QAC7D,IAAI,CAAC,IAAI;YAAE,MAAM;QACjB,QAAQ,CAAC,IAAI,CAAC,IAAI,YAAY,KAAK,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,CAAC;QACnE,OAAO,GAAG,IAAI,CAAC;IACjB,CAAC;IACD,OAAO,QAAQ,CAAC;AAClB,CAAC;AAED,MAAM,CAAC,MAAM,OAAO,GAAyB,CAAC,GAAG,EAAE,CAAC,EAAE,EAAE;IACtD,MAAM,QAAQ,GAAG,SAAS,CAAC,GAAG,CAAC,CAAC;IAChC,MAAM,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,SAAS,CAAC;IAElD,+EAA+E;IAC/E,2CAA2C;IAC3C,yEAAyE;IACzE,gFAAgF;IAChF,MAAM,MAAM,GACV,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC;QACf,YAAY,CAAC;YACX,KAAK,EAAE,OAAO;YACd,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,UAAU,KAAK,MAAM;YACnC,IAAI,EAAE,EAAE,SAAS,EAAE;SACpB,CAAC,CAAC;IAEL,MAAM,SAAS,GAAG;QAChB,IAAI,EAAE,QAAQ,CAAC,IAAI;QACnB,MAAM,EAAE,QAAQ,CAAC,MAAM;QACvB,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,CAAC,QAAQ,CAAC,KAAK,IAAI,QAAQ,CAAC;QAC9D,8FAA8F;QAC9F,uFAAuF;QACvF,6FAA6F;QAC7F,6DAA6D;QAC7D,QAAQ,EAAE,UAAU,CAAC,QAAQ,CAAC;QAC9B,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;QACnB,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM;KACrB,CAAC;IAEF,gGAAgG;IAChG,IAAI,QAAQ,CAAC,MAAM,IAAI,GAAG,IAAI,CAAC,QAAQ,CAAC,QAAQ,EAAE,CAAC;QACjD,MAAM,CAAC,KAAK,CAAC,gBAAgB,EAAE,SAAS,CAAC,CAAC;QAC1C,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,EAAE,KAAK,CAAC,QAAQ,EAAE,CAAC,EAAE,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,QAAQ,CAAC,IAAI,EAAE,CAAC,CAAC;QACtF,gGAAgG;QAChG,+FAA+F;QAC/F,+FAA+F;QAC/F,0EAA0E;QAC1E,WAAW,CAAC,QAAQ,CAAC,KAAK,IAAI,GAAG,EAAE;YACjC,IAAI,EAAE,MAAM;YACZ,OAAO,EAAE;gBACP,IAAI,EAAE,QAAQ,CAAC,IAAI;gBACnB,MAAM,EAAE,QAAQ,CAAC,MAAM;gBACvB,MAAM,EAAE,CAAC,CAAC,GAAG,CAAC,MAAM;gBACpB,0FAA0F;gBAC1F,yFAAyF;gBACzF,gEAAgE;gBAChE,KAAK,EAAE,SAAS,CAAC,CAAC,CAAC;gBACnB,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC;gBACnB,kFAAkF;gBAClF,SAAS;aACV;SACF,CAAC,CAAC;IACL,CAAC;SAAM,IAAI,QAAQ,CAAC,QAAQ,EAAE,CAAC;QAC7B,8FAA8F;QAC9F,gFAAgF;QAChF,MAAM,CAAC,KAAK,CAAC,kBAAkB,EAAE,SAAS,CAAC,CAAC;IAC9C,CAAC;SAAM,CAAC;QACN,MAAM,CAAC,IAAI,CAAC,kBAAkB,EAAE,SAAS,CAAC,CAAC;IAC7C,CAAC;IAED,8FAA8F;IAC9F,+FAA+F;IAC/F,qCAAqC;IACrC,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,KAAK,eAAe,IAAI,QAAQ,CAAC,MAAM,IAAI,GAAG,EAAE,CAAC;QAC7D,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,GAAG,CAAC,CAAC;IACpC,CAAC;IACD,OAAO,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,QAAQ,EAAE,SAAS,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,CAAC;AACnE,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,QAAQ,GAA4B,CAAC,CAAC,EAAE,EAAE;IACrD,MAAM,SAAS,GAAG,CAAC,CAAC,GAAG,CAAC,WAAW,CAAC,IAAI,SAAS,CAAC;IAClD,OAAO,CAAC,CAAC,IAAI,CACX,WAAW,CACT,QAAQ,CAAC,QAAQ,CACf,eAAe,CAAC,CAAC,GAAG,CAAC,MAAM,IAAI,CAAC,CAAC,GAAG,CAAC,IAAI,6CAA6C,CACvF,EACD,SAAS,CACV,EACD,GAAG,CACJ,CAAC;AACJ,CAAC,CAAC"}

package/dist/middleware/observability.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The one middleware that wires observability into every request:
+ *   - request id (generated or taken from an inbound `x-request-id`)
+ *   - W3C trace context (continued from `traceparent` or freshly rooted)
+ *   - a request-scoped structured logger, pre-bound with correlation fields
+ *   - a metrics sink (log line + the optional Analytics Engine dataset), ambient for the request
+ *     (`withMetrics`) so the fetch client and cache reads record into it
+ * and, after the response is produced, emits the access log and the `http.request` timing.
+ *
+ * Registered first so `onError` (which runs within the same composed context)
+ * can read `c.get("logger")`, `c.get("requestId")`, etc.
+ */
+import { matchedRoutes } from "hono/route";
+import type { AppEnv } from "../context.js";
+/**
+ * The endpoint pattern (e.g. `/v1/claims/:claimId`) the request matched — the FIRST matched route
+ * that is not an `app.use` middleware (those register as method ALL; the first one is the handler
+ * that answers — a later param route matching the same path never ran) — or `"unmatched"`. Read off
+ * the whole match list, not `routePath`, so a request a middleware rejected before its handler ran
+ * (ucanAuth's 401, a limiter's 429, bodyLimit's 413) is still labelled with its endpoint. Never the
+ * raw path: it carries claim ids and DIDs — unbounded cardinality, and ids a metric must not hold.
+ */
+export declare function endpointOf(c: Parameters<typeof matchedRoutes>[0]): string;
+/**
+ * The request path a log line may carry. Under `/v1/api` the concrete path can name a pending
+ * source (D10: its id never leaves the oracle), so it is the matched route pattern there — its ids
+ * masked when nothing matched. Read before the route runs too (the rate limiter): the router has
+ * matched every handler by then.
+ */
+export declare function loggedPath(c: Parameters<typeof matchedRoutes>[0]): string;
+export declare const observability: import("hono").MiddlewareHandler<AppEnv, string, {}, Response>;
+//# sourceMappingURL=observability.d.ts.map

package/dist/middleware/observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../../src/middleware/observability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,aAAa,EAAE,MAAM,YAAY,CAAC;AAE3C,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAmCzC;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAEzE;AAED;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,UAAU,CAAC,OAAO,aAAa,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,CAKzE;AASD,eAAO,MAAM,aAAa,gEAyExB,CAAC"}

package/dist/middleware/observability.js

@@ -0,0 +1,134 @@
+/**
+ * The one middleware that wires observability into every request:
+ *   - request id (generated or taken from an inbound `x-request-id`)
+ *   - W3C trace context (continued from `traceparent` or freshly rooted)
+ *   - a request-scoped structured logger, pre-bound with correlation fields
+ *   - a metrics sink (log line + the optional Analytics Engine dataset), ambient for the request
+ *     (`withMetrics`) so the fetch client and cache reads record into it
+ * and, after the response is produced, emits the access log and the `http.request` timing.
+ *
+ * Registered first so `onError` (which runs within the same composed context)
+ * can read `c.get("logger")`, `c.get("requestId")`, etc.
+ */
+import { createMiddleware } from "hono/factory";
+import { matchedRoutes } from "hono/route";
+import { loadConfig } from "../config.js";
+import { maskIds } from "../lib/api-lane/ids.js";
+import { createLogger } from "../lib/logger.js";
+import { createMetrics, withMetrics } from "../lib/metrics.js";
+import { toTraceparent, traceContextFromRequest } from "../lib/tracing.js";
+const REQUEST_ID = /^[\w.:-]{1,128}$/;
+function metricFields(metric) {
+    return {
+        method: metric.method,
+        route: metric.route,
+        status: metric.status,
+        durationMs: metric.durationMs,
+        outcome: metric.outcome,
+        ...(metric.colo ? { colo: metric.colo } : {}),
+    };
+}
+function outcomeFor(status) {
+    if (status >= 500)
+        return "server_error";
+    if (status >= 400)
+        return "client_error";
+    return "ok";
+}
+/**
+ * The endpoint pattern (e.g. `/v1/claims/:claimId`) the request matched — the FIRST matched route
+ * that is not an `app.use` middleware (those register as method ALL; the first one is the handler
+ * that answers — a later param route matching the same path never ran) — or `"unmatched"`. Read off
+ * the whole match list, not `routePath`, so a request a middleware rejected before its handler ran
+ * (ucanAuth's 401, a limiter's 429, bodyLimit's 413) is still labelled with its endpoint. Never the
+ * raw path: it carries claim ids and DIDs — unbounded cardinality, and ids a metric must not hold.
+ */
+export function endpointOf(c) {
+    return matchedRoutes(c).find((r) => r.method !== "ALL")?.path ?? "unmatched";
+}
+/**
+ * The request path a log line may carry. Under `/v1/api` the concrete path can name a pending
+ * source (D10: its id never leaves the oracle), so it is the matched route pattern there — its ids
+ * masked when nothing matched. Read before the route runs too (the rate limiter): the router has
+ * matched every handler by then.
+ */
+export function loggedPath(c) {
+    const { path } = c.req;
+    if (!path.startsWith("/v1/api"))
+        return path;
+    const route = endpointOf(c);
+    return route === "unmatched" ? maskIds(path) : route;
+}
+/** The log line's route: the pattern that ran last if more specific than the catch-all, else the
+ *  endpoint (`endpointOf`). */
+function routeOf(c, endpoint) {
+    const rp = c.req.routePath;
+    return rp && rp !== "/*" ? rp : endpoint;
+}
+export const observability = createMiddleware(async (c, next) => {
+    const start = Date.now();
+    const config = loadConfig(c.env);
+    // A client's id is echoed and forwarded into workflow params and every log base, so only a
+    // bounded, plain one is taken; anything else gets a fresh id.
+    const inbound = c.req.header("x-request-id");
+    const requestId = inbound && REQUEST_ID.test(inbound) ? inbound : crypto.randomUUID();
+    const trace = traceContextFromRequest(c.req.raw);
+    const logger = createLogger({
+        level: config.LOG_LEVEL,
+        pretty: config.LOG_PRETTY,
+        base: {
+            service: config.SERVICE_NAME,
+            version: config.SERVICE_VERSION,
+            env: config.ENVIRONMENT,
+            requestId,
+            traceId: trace.traceId,
+            spanId: trace.spanId,
+        },
+    });
+    const metrics = createMetrics(logger, { dataset: c.env.METRICS, network: config.IXO_NETWORK });
+    c.set("requestId", requestId);
+    c.set("trace", trace);
+    c.set("logger", logger);
+    c.set("config", config);
+    c.set("metrics", metrics);
+    c.set("startTime", start);
+    // Correlation headers on the way out (applied to the final response, including
+    // error responses produced by onError).
+    c.header("x-request-id", requestId);
+    c.header("traceparent", toTraceparent(trace));
+    // Because Hono's onError resolves the composed chain (rather than rejecting),
+    // code after `next()` runs for both success and handled-error responses with
+    // `c.res` already set to the final response.
+    // The correlation rides the same scope, so a seam that starts a workflow (`startApiClaims`)
+    // hands the request's trace on without taking it as a parameter.
+    await withMetrics({ metrics, logger, traceparent: toTraceparent(trace), requestId }, next);
+    const durationMs = Date.now() - start;
+    const status = c.res.status;
+    const endpoint = endpointOf(c);
+    const metric = {
+        method: c.req.method,
+        route: routeOf(c, endpoint),
+        status,
+        durationMs,
+        outcome: outcomeFor(status),
+        colo: c.req.raw.cf?.colo ?? undefined,
+    };
+    c.header("server-timing", `total;dur=${durationMs}`);
+    metrics.timing("http.request", durationMs, {
+        op: metric.method,
+        route: endpoint,
+        status: String(status),
+        outcome: metric.outcome,
+    });
+    const fields = metricFields(metric);
+    if (metric.outcome === "server_error") {
+        logger.error("request_completed", fields);
+    }
+    else if (metric.outcome === "client_error") {
+        logger.warn("request_completed", fields);
+    }
+    else {
+        logger.info("request_completed", fields);
+    }
+});
+//# sourceMappingURL=observability.js.map

package/dist/middleware/observability.js.map

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

package/dist/middleware/rate-limit.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Coarse per-IP rate limit on the whole API — a blunt anti-abuse guard, not precise accounting.
+ *
+ * Backed by Cloudflare's native `ratelimit` binding (GA): the limit/period are declared on
+ * `API_RATE_LIMITER` in wrangler.jsonc, so this code only picks a key and asks. The binding is
+ * per-colo, eventually consistent, and a no-op in local dev/tests (always allows).
+ *
+ * Sits after `cors` so a 429 carries CORS headers, and before `bodyLimit` so a limited request is
+ * shed without reading its body. Runs GLOBALLY, before `ucanAuth` resolves a principal — so the key
+ * is the client IP (the only universal signal here), not the caller DID. `/health` and
+ * `/.well-known/*` are exempt: uptime probes and cross-service did:web resolution hit them from a
+ * few IPs at high frequency and must never be throttled.
+ */
+import type { AppEnv } from "../context.js";
+export declare const rateLimit: import("hono").MiddlewareHandler<AppEnv, string, {}, Response>;
+//# sourceMappingURL=rate-limit.d.ts.map

package/dist/middleware/rate-limit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../src/middleware/rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAsBzC,eAAO,MAAM,SAAS,gEAwBpB,CAAC"}

package/dist/middleware/rate-limit.js

@@ -0,0 +1,56 @@
+/**
+ * Coarse per-IP rate limit on the whole API — a blunt anti-abuse guard, not precise accounting.
+ *
+ * Backed by Cloudflare's native `ratelimit` binding (GA): the limit/period are declared on
+ * `API_RATE_LIMITER` in wrangler.jsonc, so this code only picks a key and asks. The binding is
+ * per-colo, eventually consistent, and a no-op in local dev/tests (always allows).
+ *
+ * Sits after `cors` so a 429 carries CORS headers, and before `bodyLimit` so a limited request is
+ * shed without reading its body. Runs GLOBALLY, before `ucanAuth` resolves a principal — so the key
+ * is the client IP (the only universal signal here), not the caller DID. `/health` and
+ * `/.well-known/*` are exempt: uptime probes and cross-service did:web resolution hit them from a
+ * few IPs at high frequency and must never be throttled.
+ */
+import { createMiddleware } from "hono/factory";
+import { AppError } from "../lib/errors.js";
+import { loggedPath } from "./observability.js";
+/**
+ * Requests to these prefixes are never rate limited (infra/probes + did:web resolution).
+ * Deliberately `/health` EXACTLY, not a `/health/` prefix: `/health/ready` probes D1, KV and the
+ * engine, so an unauthenticated, unthrottled path there would be a lever on resources every
+ * authenticated route shares (SEC-07). It, and any future sub-route, stays limited.
+ */
+function isExempt(path) {
+    return path === "/health" || path.startsWith("/.well-known/");
+}
+/** First 16 hex of SHA-256(ip): enough to group one client's lines, not enough to name the client. */
+async function ipHash(ip) {
+    const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(ip));
+    return [...new Uint8Array(digest).slice(0, 8)]
+        .map((b) => b.toString(16).padStart(2, "0"))
+        .join("");
+}
+export const rateLimit = createMiddleware(async (c, next) => {
+    if (isExempt(c.req.path))
+        return next();
+    // Cloudflare sets CF-Connecting-IP at the edge (not client-spoofable). Absent locally/in tests —
+    // fall back to a constant so the limiter still functions (and, being a local no-op, always allows).
+    const key = c.req.header("CF-Connecting-IP") ?? "unknown";
+    let allowed = true;
+    try {
+        const { success } = await c.env.API_RATE_LIMITER.limit({ key });
+        allowed = success;
+    }
+    catch (err) {
+        // Fail OPEN: a limiter glitch must never take down the API. Log and let the request through.
+        c.get("logger").warn("ratelimit.errored", { detail: String(err) });
+    }
+    if (!allowed) {
+        c.get("metrics").count("rate_limited");
+        // A hash, never the IP (observability spec §3): still groups one abuser's lines together.
+        c.get("logger").warn("ratelimit.exceeded", { ipHash: await ipHash(key), path: loggedPath(c) });
+        throw AppError.rateLimited("Too many requests from this address. Wait a minute and retry.");
+    }
+    await next();
+});
+//# sourceMappingURL=rate-limit.js.map

package/dist/middleware/rate-limit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.js","sourceRoot":"","sources":["../../src/middleware/rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AACzC,OAAO,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAC;AAE7C;;;;;GAKG;AACH,SAAS,QAAQ,CAAC,IAAY;IAC5B,OAAO,IAAI,KAAK,SAAS,IAAI,IAAI,CAAC,UAAU,CAAC,eAAe,CAAC,CAAC;AAChE,CAAC;AAED,sGAAsG;AACtG,KAAK,UAAU,MAAM,CAAC,EAAU;IAC9B,MAAM,MAAM,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC;IACnF,OAAO,CAAC,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC;SAC3C,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SAC3C,IAAI,CAAC,EAAE,CAAC,CAAC;AACd,CAAC;AAED,MAAM,CAAC,MAAM,SAAS,GAAG,gBAAgB,CAAS,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;IAClE,IAAI,QAAQ,CAAC,CAAC,CAAC,GAAG,CAAC,IAAI,CAAC;QAAE,OAAO,IAAI,EAAE,CAAC;IAExC,iGAAiG;IACjG,oGAAoG;IACpG,MAAM,GAAG,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,kBAAkB,CAAC,IAAI,SAAS,CAAC;IAE1D,IAAI,OAAO,GAAG,IAAI,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,CAAC,CAAC,GAAG,CAAC,gBAAgB,CAAC,KAAK,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC;QAChE,OAAO,GAAG,OAAO,CAAC;IACpB,CAAC;IAAC,OAAO,GAAG,EAAE,CAAC;QACb,6FAA6F;QAC7F,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,mBAAmB,EAAE,EAAE,MAAM,EAAE,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC,CAAC;IACrE,CAAC;IAED,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,CAAC,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC;QACvC,0FAA0F;QAC1F,CAAC,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAC,IAAI,CAAC,oBAAoB,EAAE,EAAE,MAAM,EAAE,MAAM,MAAM,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC;QAC/F,MAAM,QAAQ,CAAC,WAAW,CAAC,+DAA+D,CAAC,CAAC;IAC9F,CAAC;IAED,MAAM,IAAI,EAAE,CAAC;AACf,CAAC,CAAC,CAAC"}

package/dist/middleware/ucan-auth.d.ts

@@ -0,0 +1,39 @@
+/**
+ * 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 type { AppEnv } from "../context.js";
+export declare const ucanAuth: import("hono").MiddlewareHandler<AppEnv, string, {}, Response>;
+//# sourceMappingURL=ucan-auth.d.ts.map

package/dist/middleware/ucan-auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ucan-auth.d.ts","sourceRoot":"","sources":["../../src/middleware/ucan-auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAa,MAAM,YAAY,CAAC;AAyJpD,eAAO,MAAM,QAAQ,gEAwInB,CAAC"}