@ixo/decision-oracle 0.0.0-stage → 0.2.0

package/dist/middleware/api/oauth.d.ts

@@ -0,0 +1,28 @@
+/**
+ * The `oauth` caller (S7, spec 2026-10-06; S3 review §1): a user acting through an AI app on
+ * `/v1/mcp`. The MCP handler verifies the token, then calls this app's own `/v1/api` routes
+ * in-process; THIS is how the route learns who it is serving. The mark is a `WeakMap` entry on the
+ * very `Request` object the handler builds, lifted into the `oauth` Hono var by `inProcessOAuth`
+ * before any middleware can replace `c.req.raw` — no header carries it, so nothing a remote client
+ * sends can make a request an OAuth one. `access()` builds the caller from that var alone.
+ *
+ * Rights: the user's standing on the source RIGHT NOW (`storedGrant` — a current controller of its
+ * organisation as root, or a live member, read on every request) intersected with the token's scopes. A route a key may not call
+ * (`scope: "none"`) or needing a scope the token lacks is `SCOPE`; the role's capability
+ * `FORBIDDEN` — so an OAuth token never reaches keys, members, webhooks, settings or caps.
+ */
+import type { AppEnv, OAuthSeam } from "../../context.js";
+import type { Access, AnonymousCaller, ApiContext, OAuthCaller } from "./types.js";
+/** Mark a request the MCP handler is about to send in-process as made for this OAuth caller. */
+export declare function markOAuth(req: Request, seam: OAuthSeam): Request;
+/** App middleware: the mark, as the `oauth` var. Runs before anything can swap `c.req.raw`. */
+export declare const inProcessOAuth: import("hono").MiddlewareHandler<AppEnv, string, {}, Response>;
+/**
+ * The submit route around `/verify` (S3 review F3): on before it, off only when the gate's answer
+ * proves nothing was reserved. A throw (an outage mid-verify) or a reservation leaves it on, so
+ * the MCP handler never gives that approval back. Returns what it was: once an earlier attempt
+ * (the SDK's resend after a 5xx) left it on, a later refusal must not clear it (S3 review N4).
+ */
+export declare function noteReserving(c: ApiContext, on: boolean): boolean;
+export declare function oauthCaller(c: ApiContext, spec: Access, seam: OAuthSeam): Promise<OAuthCaller | AnonymousCaller>;
+//# sourceMappingURL=oauth.d.ts.map

package/dist/middleware/api/oauth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth.d.ts","sourceRoot":"","sources":["../../../src/middleware/api/oauth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAIH,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AAQvD,OAAO,KAAK,EAAE,MAAM,EAAE,eAAe,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,SAAS,CAAC;AAgBhF,gGAAgG;AAChG,wBAAgB,SAAS,CAAC,GAAG,EAAE,OAAO,EAAE,IAAI,EAAE,SAAS,GAAG,OAAO,CAGhE;AAED,+FAA+F;AAC/F,eAAO,MAAM,cAAc,gEAIzB,CAAC;AAEH;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,UAAU,EAAE,EAAE,EAAE,OAAO,GAAG,OAAO,CAKjE;AAED,wBAAsB,WAAW,CAC/B,CAAC,EAAE,UAAU,EACb,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,SAAS,GACd,OAAO,CAAC,WAAW,GAAG,eAAe,CAAC,CAmExC"}

package/dist/middleware/api/oauth.js

@@ -0,0 +1,109 @@
+/**
+ * The `oauth` caller (S7, spec 2026-10-06; S3 review §1): a user acting through an AI app on
+ * `/v1/mcp`. The MCP handler verifies the token, then calls this app's own `/v1/api` routes
+ * in-process; THIS is how the route learns who it is serving. The mark is a `WeakMap` entry on the
+ * very `Request` object the handler builds, lifted into the `oauth` Hono var by `inProcessOAuth`
+ * before any middleware can replace `c.req.raw` — no header carries it, so nothing a remote client
+ * sends can make a request an OAuth one. `access()` builds the caller from that var alone.
+ *
+ * Rights: the user's standing on the source RIGHT NOW (`storedGrant` — a current controller of its
+ * organisation as root, or a live member, read on every request) intersected with the token's scopes. A route a key may not call
+ * (`scope: "none"`) or needing a scope the token lacks is `SCOPE`; the role's capability
+ * `FORBIDDEN` — so an OAuth token never reaches keys, members, webhooks, settings or caps.
+ */
+import { eq } from "drizzle-orm";
+import { createMiddleware } from "hono/factory";
+import { Capability, covers } from "../../contracts/index.js";
+import { apiSources } from "../../db/schema.js";
+import { sourceRoots } from "../../lib/api-lane/company.js";
+import { oracleWebDid } from "../../lib/ixo/ucan.js";
+import { chainOf, storedGrant } from "./console.js";
+import { ApiError, assertLinkedFor } from "./errors.js";
+import { limitCaller } from "./rate-limit.js";
+const marked = new WeakMap();
+/** The routes `routes/v1/mcp/tools.ts` calls for an OAuth caller, and no others. */
+const OAUTH_OPS = new Set([
+    "submitClaim",
+    "getClaim",
+    "getClaimReceipt",
+    "listProtocols",
+    "getProtocol",
+    // `upload_file`'s link and `submit_claim`'s cid read — never the raw `PUT /uploads`.
+    "createUploadLink",
+    "getUpload",
+]);
+/** Mark a request the MCP handler is about to send in-process as made for this OAuth caller. */
+export function markOAuth(req, seam) {
+    marked.set(req, seam);
+    return req;
+}
+/** App middleware: the mark, as the `oauth` var. Runs before anything can swap `c.req.raw`. */
+export const inProcessOAuth = createMiddleware(async (c, next) => {
+    const seam = marked.get(c.req.raw);
+    if (seam)
+        c.set("oauth", seam);
+    await next();
+});
+/**
+ * The submit route around `/verify` (S3 review F3): on before it, off only when the gate's answer
+ * proves nothing was reserved. A throw (an outage mid-verify) or a reservation leaves it on, so
+ * the MCP handler never gives that approval back. Returns what it was: once an earlier attempt
+ * (the SDK's resend after a 5xx) left it on, a later refusal must not clear it (S3 review N4).
+ */
+export function noteReserving(c, on) {
+    const seam = c.get("oauth");
+    const was = seam?.reserving === true;
+    if (seam)
+        seam.reserving = on;
+    return was;
+}
+export async function oauthCaller(c, spec, seam) {
+    const { identity, sourceId } = seam;
+    // Exactly what the MCP tools call (S3 review F2): an app over OAuth reaches nothing else,
+    // whatever the user's role — no erasure, review, raw upload, batch, settings or console route.
+    if (!OAUTH_OPS.has(spec.op)) {
+        throw new ApiError("SCOPE", "An AI app connected with OAuth can't do this. Sign in to the Decision Console to do it.");
+    }
+    if (sourceId === null) {
+        if (spec.capability === "public")
+            return { kind: "anonymous" };
+        throw new ApiError("NOT_FOUND", "Say which source this is for.");
+    }
+    const db = await c.var.db();
+    const source = await db.query.apiSources.findFirst({ where: eq(apiSources.sourceId, sourceId) });
+    const grant = source
+        ? await storedGrant(db, await sourceRoots(chainOf(c), source), oracleWebDid(c.get("config")), source, identity.did)
+        : null;
+    if (!source || !grant) {
+        // The id is not echoed: the message is logged, and a pending source's id never is.
+        throw new ApiError("NOT_FOUND", "This source was not found, or you are not a member of it.");
+    }
+    // D10, as for a console member: an unlinked source answers only what `assertLinkedFor` allows.
+    assertLinkedFor(source, spec.op);
+    const caller = {
+        kind: "oauth",
+        source,
+        did: identity.did,
+        clientId: identity.clientId,
+        clientName: identity.clientName,
+        clientVerified: identity.clientVerified,
+        grantId: identity.grantId,
+        scopes: identity.scopes,
+        ...grant,
+    };
+    // As every source caller: counted once identified, before the route's own check.
+    await limitCaller(c, caller);
+    const { scope, capability } = spec;
+    if (scope === "none" || (scope !== null && !caller.scopes.includes(scope))) {
+        throw new ApiError("SCOPE", scope === "none"
+            ? "An AI app connected with OAuth can't do this. Sign in to the Decision Console to do it."
+            : `This AI app's connection doesn't have the ${scope} permission. Reconnect it and allow ${scope}.`, scope === "none" ? undefined : { required: scope });
+    }
+    if (capability !== null &&
+        Capability.safeParse(capability).success &&
+        !covers(caller.capabilities, capability)) {
+        throw new ApiError("FORBIDDEN", `Your role on this source doesn't allow this (it needs the ${capability} permission). Ask the source's owner for a role that includes it.`, { required: capability });
+    }
+    return caller;
+}
+//# sourceMappingURL=oauth.js.map

package/dist/middleware/api/oauth.js.map

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

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

@@ -0,0 +1,23 @@
+/**
+ * Per-key and per-source limits (go-prod spec §4.1): `RateLimit-Limit`, `RateLimit-Remaining`,
+ * `RateLimit-Reset` on every answer; `429 RATE_LIMITED` + `Retry-After` past either.
+ *
+ * Cloudflare's `ratelimit` binding (`API_KEY_RATE_LIMITER`) DECIDES — it is the platform's way,
+ * per-colo and eventually consistent, and a no-op in local dev and tests. It reports only
+ * allow/deny, so the headers' `Remaining` is this isolate's own count within the same window: an
+ * honest hint that never promises more than the binding will allow. `API_KEY_LIMIT` must match the
+ * binding's `simple` block in wrangler.jsonc (the package's and the template's).
+ *
+ * Runs after `access()` has named the caller: a key is limited by its prefix and by its source, a
+ * console member by its DID and by its source, an AI app over OAuth by its grant and by its source — one busy integration never starves its source's
+ * console, and no source can starve the oracle.
+ */
+import type { Context } from "hono";
+import type { ApiEnv, SourceCaller } from "./types.js";
+/** Mirrors `API_KEY_RATE_LIMITER`'s `simple: { limit: 600, period: 60 }`. */
+export declare const API_KEY_LIMIT: {
+    readonly limit: 600;
+    readonly periodSec: 60;
+};
+export declare function limitCaller(c: Context<ApiEnv>, caller: SourceCaller): Promise<void>;
+//# sourceMappingURL=rate-limit.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"rate-limit.d.ts","sourceRoot":"","sources":["../../../src/middleware/api/rate-limit.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAGpC,OAAO,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAEpD,6EAA6E;AAC7E,eAAO,MAAM,aAAa;aAAK,KAAK,EAAE,GAAG;aAAE,SAAS,EAAE,EAAE;CAAW,CAAC;AAKpE,wBAAsB,WAAW,CAAC,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,MAAM,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAsCzF"}

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

@@ -0,0 +1,70 @@
+/**
+ * Per-key and per-source limits (go-prod spec §4.1): `RateLimit-Limit`, `RateLimit-Remaining`,
+ * `RateLimit-Reset` on every answer; `429 RATE_LIMITED` + `Retry-After` past either.
+ *
+ * Cloudflare's `ratelimit` binding (`API_KEY_RATE_LIMITER`) DECIDES — it is the platform's way,
+ * per-colo and eventually consistent, and a no-op in local dev and tests. It reports only
+ * allow/deny, so the headers' `Remaining` is this isolate's own count within the same window: an
+ * honest hint that never promises more than the binding will allow. `API_KEY_LIMIT` must match the
+ * binding's `simple` block in wrangler.jsonc (the package's and the template's).
+ *
+ * Runs after `access()` has named the caller: a key is limited by its prefix and by its source, a
+ * console member by its DID and by its source, an AI app over OAuth by its grant and by its source — one busy integration never starves its source's
+ * console, and no source can starve the oracle.
+ */
+import { endpointOf } from "../observability.js";
+import { ApiError } from "./errors.js";
+/** Mirrors `API_KEY_RATE_LIMITER`'s `simple: { limit: 600, period: 60 }`. */
+export const API_KEY_LIMIT = { limit: 600, periodSec: 60 };
+/** window-start → count, per limiter key; old windows are dropped as they are passed. */
+const counts = new Map();
+export async function limitCaller(c, caller) {
+    const limiter = c.env.API_KEY_RATE_LIMITER;
+    if (!limiter)
+        return; // optional binding: an oracle that set none limits per IP only
+    const who = caller.kind === "key"
+        ? `key:${caller.key.prefix}`
+        : caller.kind === "oauth"
+            ? `oauth:${caller.grantId}`
+            : `member:${caller.did}`;
+    const keys = [who, `source:${caller.source.sourceId}`];
+    const now = Date.now();
+    const periodMs = API_KEY_LIMIT.periodSec * 1000;
+    const window = Math.floor(now / periodMs) * periodMs;
+    const reset = Math.ceil((window + periodMs - now) / 1000);
+    let allowed = true;
+    try {
+        for (const key of keys) {
+            if (!(await limiter.limit({ key })).success)
+                allowed = false;
+        }
+    }
+    catch (err) {
+        // Fail OPEN, as the per-IP guard does: a limiter glitch must never take the API down.
+        c.get("logger").warn("api.ratelimit.errored", { detail: String(err) });
+    }
+    const used = Math.max(...keys.map((key) => bump(key, window)));
+    c.header("RateLimit-Limit", String(API_KEY_LIMIT.limit));
+    c.header("RateLimit-Remaining", String(allowed ? Math.max(0, API_KEY_LIMIT.limit - used) : 0));
+    c.header("RateLimit-Reset", String(reset));
+    if (!allowed) {
+        c.header("Retry-After", String(reset));
+        c.get("metrics").count("api.rate_limited", 1, { route: endpointOf(c) });
+        throw new ApiError("RATE_LIMITED", `Rate limit reached for this ${caller.kind === "key" ? "API key" : caller.kind === "oauth" ? "AI app connection" : "account"} or its source (${API_KEY_LIMIT.limit} requests a minute). Wait and retry; the Retry-After header says how many seconds.`);
+    }
+}
+function bump(key, window) {
+    const entry = counts.get(key);
+    if (!entry || entry.window !== window) {
+        counts.set(key, { window, n: 1 });
+        if (counts.size > 10_000) {
+            for (const [k, v] of counts)
+                if (v.window !== window)
+                    counts.delete(k);
+        }
+        return 1;
+    }
+    entry.n += 1;
+    return entry.n;
+}
+//# sourceMappingURL=rate-limit.js.map

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

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

package/dist/middleware/api/types.d.ts

@@ -0,0 +1,92 @@
+/**
+ * The `/v1/api` router's Hono environment (go-prod spec §3.1): the app's variables plus the
+ * resolved CALLER — who is asking, for which source, allowed to do what. Set once by `access()`
+ * (`auth.ts`) on every guarded route; a route never re-derives it.
+ */
+import type { Context } from "hono";
+import type { AppEnv, Variables } from "../../context.js";
+import type { ApiOp, Capability, MemberRole, Scope } from "../../contracts/index.js";
+import type { ApiKey as ApiKeyRow, ApiSource } from "../../db/schema.js";
+/** An integration: an API key of a source, gated by its scopes (§3.2). */
+export interface KeyCaller {
+    kind: "key";
+    source: ApiSource;
+    key: ApiKeyRow;
+}
+/**
+ * A console member (§3.4): a UCAN invocation whose proof chain roots at a current controller of the
+ * source's organisation (D10). `capabilities`/`protocols` are the chain's EFFECTIVE grant
+ * (intersection along the chain); a controller invoking directly is root — `source/*`, no
+ * narrowing, `controller: true`, whether or not it also has a member row.
+ */
+export interface MemberCaller {
+    kind: "member";
+    source: ApiSource;
+    /** The signed-in account that invoked (the chain's leaf audience). */
+    did: string;
+    /** Root: a current controller of `source.companyEntityDid`, invoking with no proof. */
+    controller: boolean;
+    /** Null for a controller with no member row. */
+    memberId: string | null;
+    role: MemberRole;
+    capabilities: readonly Capability[];
+    /** `nb.protocols`: the protocols `claims/*` are narrowed to; null = all. */
+    protocols: readonly string[] | null;
+}
+/**
+ * A user acting through an AI app connected to `/v1/mcp` over OAuth (S7, spec 2026-10-06). Built
+ * ONLY from the MCP handler's in-process mark (`oauth.ts`), never from anything a remote request
+ * carries: an OAuth token sent to `/v1/api` is a 401 like any other non-key. Its rights are the
+ * user's live standing on the source (`storedGrant`) intersected with the token's scopes.
+ */
+export interface OAuthCaller {
+    kind: "oauth";
+    source: ApiSource;
+    /** The user (`sub`). */
+    did: string;
+    clientId: string;
+    clientName: string;
+    /** AuthHub vouches the app is Claude or ChatGPT (`OAuthIdentity.clientVerified`). */
+    clientVerified: boolean;
+    /** AuthHub's grant: the rate-limit and spend-cap key. */
+    grantId: string;
+    scopes: readonly Scope[];
+    role: MemberRole;
+    capabilities: readonly Capability[];
+    protocols: readonly string[] | null;
+}
+/** A request with no credential on a `public` route (the protocols catalogue). */
+export interface AnonymousCaller {
+    kind: "anonymous";
+}
+/** A signed-in IXO account on an `account` route (sign-up, my sources, accept) — no source yet. */
+export interface AccountCaller {
+    kind: "account";
+    did: string;
+}
+/** An `ORACLE_ADMIN_DIDS` invoker on `/v1/api/admin/*`. */
+export interface OperatorCaller {
+    kind: "operator";
+    did: string;
+}
+export type SourceCaller = KeyCaller | MemberCaller | OAuthCaller;
+export type ApiCaller = SourceCaller | AnonymousCaller | AccountCaller | OperatorCaller;
+export interface ApiVariables extends Variables {
+    caller: ApiCaller;
+}
+export interface ApiEnv {
+    Bindings: AppEnv["Bindings"];
+    Variables: ApiVariables;
+}
+export type ApiContext = Context<ApiEnv>;
+/** What a route is: its OpenAPI `operationId`, and who may call it (`x-required-scope`,
+ *  `x-capability`). The snapshot test holds these to the OpenAPI file. `op` is an `API_ACTIONS`
+ *  key, so a new route does not compile until it has its console action. */
+export interface Access {
+    op: ApiOp;
+    /** What an API key needs; null = any key; `none` = keys may not call it (console/operator only). */
+    scope: Scope | null | "none";
+    /** What a console grant needs; null = any grant on the source. */
+    capability: Capability | null | "public" | "account" | "operator";
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/middleware/api/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/middleware/api/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AACpC,OAAO,KAAK,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,eAAe,CAAC;AACvD,OAAO,KAAK,EAAE,KAAK,EAAE,UAAU,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,iBAAiB,CAAC;AAC5E,OAAO,KAAK,EAAE,MAAM,IAAI,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAEtE,0EAA0E;AAC1E,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,KAAK,CAAC;IACZ,MAAM,EAAE,SAAS,CAAC;IAClB,GAAG,EAAE,SAAS,CAAC;CAChB;AAED;;;;;GAKG;AACH,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,QAAQ,CAAC;IACf,MAAM,EAAE,SAAS,CAAC;IAClB,sEAAsE;IACtE,GAAG,EAAE,MAAM,CAAC;IACZ,uFAAuF;IACvF,UAAU,EAAE,OAAO,CAAC;IACpB,gDAAgD;IAChD,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,IAAI,EAAE,UAAU,CAAC;IACjB,YAAY,EAAE,SAAS,UAAU,EAAE,CAAC;IACpC,4EAA4E;IAC5E,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;CACrC;AAED;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,OAAO,CAAC;IACd,MAAM,EAAE,SAAS,CAAC;IAClB,wBAAwB;IACxB,GAAG,EAAE,MAAM,CAAC;IACZ,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,MAAM,CAAC;IACnB,qFAAqF;IACrF,cAAc,EAAE,OAAO,CAAC;IACxB,yDAAyD;IACzD,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IACzB,IAAI,EAAE,UAAU,CAAC;IACjB,YAAY,EAAE,SAAS,UAAU,EAAE,CAAC;IACpC,SAAS,EAAE,SAAS,MAAM,EAAE,GAAG,IAAI,CAAC;CACrC;AAED,kFAAkF;AAClF,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,CAAC;CACnB;AAED,mGAAmG;AACnG,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,SAAS,CAAC;IAChB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,2DAA2D;AAC3D,MAAM,WAAW,cAAc;IAC7B,IAAI,EAAE,UAAU,CAAC;IACjB,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,YAAY,GAAG,WAAW,CAAC;AAClE,MAAM,MAAM,SAAS,GAAG,YAAY,GAAG,eAAe,GAAG,aAAa,GAAG,cAAc,CAAC;AAExF,MAAM,WAAW,YAAa,SAAQ,SAAS;IAC7C,MAAM,EAAE,SAAS,CAAC;CACnB;AAED,MAAM,WAAW,MAAM;IACrB,QAAQ,EAAE,MAAM,CAAC,UAAU,CAAC,CAAC;IAC7B,SAAS,EAAE,YAAY,CAAC;CACzB;AAED,MAAM,MAAM,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;AAEzC;;4EAE4E;AAC5E,MAAM,WAAW,MAAM;IACrB,EAAE,EAAE,KAAK,CAAC;IACV,oGAAoG;IACpG,KAAK,EAAE,KAAK,GAAG,IAAI,GAAG,MAAM,CAAC;IAC7B,kEAAkE;IAClE,UAAU,EAAE,UAAU,GAAG,IAAI,GAAG,QAAQ,GAAG,SAAS,GAAG,UAAU,CAAC;CACnE"}

package/dist/middleware/api/types.js

@@ -0,0 +1,7 @@
+/**
+ * The `/v1/api` router's Hono environment (go-prod spec §3.1): the app's variables plus the
+ * resolved CALLER — who is asking, for which source, allowed to do what. Set once by `access()`
+ * (`auth.ts`) on every guarded route; a route never re-derives it.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/middleware/api/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/middleware/api/types.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

package/dist/middleware/api/wait.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Sync and async are one path (go-prod spec §4.6): every submission starts a `ClaimIngest`
+ * instance, and a caller that asked to wait (`Prefer: wait=N` on submit, `?wait=N` on GET) polls
+ * the ledger — 500 ms rising to 2 s — until the decision lands or the budget runs out. The workflow
+ * never knows anyone is waiting, so a client that hangs up orphans nothing.
+ *
+ * At most 20 waiters per source in this isolate; past that the answer is an immediate `202`. The
+ * cap protects what a waiter holds — this isolate's open requests and D1 reads — so it is counted
+ * where that cost is paid, not globally.
+ */
+import type { Database } from "../../db/client.js";
+export declare const MAX_WAITERS_PER_SOURCE = 20;
+/** `Prefer: wait=N` (RFC 7240, one of possibly several comma-separated preferences) → seconds,
+ *  capped at 90; absent or malformed ⇒ null (no wait). */
+export declare function preferredWait(prefer: string | undefined): number | null;
+/**
+ * Wait up to `seconds` for the claim to land. `true` once it has (answer 200 + the record, with
+ * `Preference-Applied`), `false` when the budget ran out or no waiter slot was free (answer 202).
+ */
+export declare function awaitLanding(db: Database, sourceId: string, claimId: string, seconds: number): Promise<boolean>;
+//# sourceMappingURL=wait.d.ts.map

package/dist/middleware/api/wait.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"wait.d.ts","sourceRoot":"","sources":["../../../src/middleware/api/wait.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAKH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,iBAAiB,CAAC;AAGhD,eAAO,MAAM,sBAAsB,KAAK,CAAC;AAUzC;0DAC0D;AAC1D,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAGvE;AAsBD;;;GAGG;AACH,wBAAsB,YAAY,CAChC,EAAE,EAAE,QAAQ,EACZ,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE,MAAM,EACf,OAAO,EAAE,MAAM,GACd,OAAO,CAAC,OAAO,CAAC,CA8BlB"}

package/dist/middleware/api/wait.js

@@ -0,0 +1,85 @@
+/**
+ * Sync and async are one path (go-prod spec §4.6): every submission starts a `ClaimIngest`
+ * instance, and a caller that asked to wait (`Prefer: wait=N` on submit, `?wait=N` on GET) polls
+ * the ledger — 500 ms rising to 2 s — until the decision lands or the budget runs out. The workflow
+ * never knows anyone is waiting, so a client that hangs up orphans nothing.
+ *
+ * At most 20 waiters per source in this isolate; past that the answer is an immediate `202`. The
+ * cap protects what a waiter holds — this isolate's open requests and D1 reads — so it is counted
+ * where that cost is paid, not globally.
+ */
+import * as Sentry from "@sentry/cloudflare";
+import { eq } from "drizzle-orm";
+import { MAX_WAIT_SECONDS } from "../../contracts/index.js";
+import { claimIngests, decisions } from "../../db/schema.js";
+export const MAX_WAITERS_PER_SOURCE = 20;
+const FIRST_POLL_MS = 500;
+const MAX_POLL_MS = 2000;
+/** After the decision row lands, how long the ledger gets to catch up (the workflow's notify and
+ *  mark-processed steps) before the answer goes out anyway — so a sync 200 reads `processed`
+ *  beside its decision, not a stale `processing` (S7, 2026-09-30). `decision` stays the truth. */
+const SETTLE_GRACE_MS = 3000;
+const waiters = new Map();
+/** `Prefer: wait=N` (RFC 7240, one of possibly several comma-separated preferences) → seconds,
+ *  capped at 90; absent or malformed ⇒ null (no wait). */
+export function preferredWait(prefer) {
+    const m = prefer && /(?:^|[,;\s])wait\s*=\s*(\d+)/i.exec(prefer);
+    return m ? Math.min(Number(m[1]), MAX_WAIT_SECONDS) : null;
+}
+/** Where the claim is: `stopped` once the ledger is `processed` / `failed`; `decided` once a
+ *  decision row exists (any status, a pending review included). Untraced: a waiter repeats this one
+ *  read every 0.5–2 s by design, which Sentry's N+1 detector would flag on every sync submit. */
+async function progress(db, claimId) {
+    const [row] = await Sentry.suppressTracing(() => db
+        .select({ status: claimIngests.status, decided: decisions.claimId })
+        .from(claimIngests)
+        .leftJoin(decisions, eq(decisions.claimId, claimIngests.claimId))
+        .where(eq(claimIngests.claimId, claimId)));
+    return {
+        decided: !!row && row.decided !== null,
+        stopped: !!row && (row.status === "processed" || row.status === "failed"),
+    };
+}
+/**
+ * Wait up to `seconds` for the claim to land. `true` once it has (answer 200 + the record, with
+ * `Preference-Applied`), `false` when the budget ran out or no waiter slot was free (answer 202).
+ */
+export async function awaitLanding(db, sourceId, claimId, seconds) {
+    const first = await progress(db, claimId);
+    if (first.stopped)
+        return true;
+    if (seconds <= 0)
+        return first.decided;
+    const inFlight = waiters.get(sourceId) ?? 0;
+    if (inFlight >= MAX_WAITERS_PER_SOURCE)
+        return false;
+    waiters.set(sourceId, inFlight + 1);
+    try {
+        let deadline = Date.now() + seconds * 1000;
+        let decided = first.decided;
+        // Decided already: only the ledger's catch-up is left, so the grace (not the full budget) bounds it.
+        if (decided)
+            deadline = Math.min(deadline, Date.now() + SETTLE_GRACE_MS);
+        let delay = FIRST_POLL_MS;
+        for (let left = deadline - Date.now(); left > 0; left = deadline - Date.now()) {
+            await new Promise((r) => setTimeout(r, Math.min(delay, left)));
+            const now = await progress(db, claimId);
+            if (now.stopped)
+                return true;
+            if (now.decided && !decided) {
+                decided = true;
+                deadline = Math.min(deadline, Date.now() + SETTLE_GRACE_MS);
+            }
+            delay = Math.min(delay * 1.5, MAX_POLL_MS);
+        }
+        return decided;
+    }
+    finally {
+        const n = (waiters.get(sourceId) ?? 1) - 1;
+        if (n > 0)
+            waiters.set(sourceId, n);
+        else
+            waiters.delete(sourceId);
+    }
+}
+//# sourceMappingURL=wait.js.map

package/dist/middleware/api/wait.js.map

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

package/dist/middleware/capability.d.ts

@@ -0,0 +1,32 @@
+/**
+ * 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 type { AppEnv } from "../context.js";
+/** Until the strict step: an invocation still minting `{ can: "*" }` keeps working. */
+export declare const ACCEPT_WILDCARD = true;
+/** [method, path pattern (`:param` = one segment), the one action it accepts]. */
+export declare const ROUTE_ACTIONS: readonly [readonly ["POST", "/v1/collections/register", "collections/register"], readonly ["GET", "/v1/collections", "collections/read"], readonly ["POST", "/v1/collections/:collectionId/pause", "collections/pause"], readonly ["POST", "/v1/collections/:collectionId/resume", "collections/resume"], readonly ["POST", "/v1/collections/:collectionId/scan", "collections/scan"], readonly ["PATCH", "/v1/collections/:collectionId/settings", "collections/settings"], readonly ["GET", "/v1/collections/:collectionId/settings", "collections/settings-read"], readonly ["POST", "/v1/collections/:collectionId/reviewers", "collections/reviewers-grant"], readonly ["GET", "/v1/collections/:collectionId/reviewers", "collections/reviewers-read"], readonly ["POST", "/v1/collections/:collectionId/reviewers/:delegationCid/revoke", "collections/reviewers-revoke"], readonly ["GET", "/v1/claims", "claims/read"], readonly ["GET", "/v1/claims/:claimId", "claims/read"], readonly ["DELETE", "/v1/claims/:claimId/body", "claims/erase"], readonly ["GET", "/v1/reviews/:claimId", "reviews/read"], readonly ["POST", "/v1/reviews/:claimId", "reviews/submit"], readonly ["GET", "/v1/admin/status", "admin/status"], readonly ["POST", "/v1/admin/collections/relink", "admin/collections-relink"], readonly ["GET", "/v1/oauth/approvals/:approvalId", "oauth/approval/read"], readonly ["POST", "/v1/oauth/approvals/:approvalId", "oauth/approval/approve"], readonly ["GET", "/v1/oauth/standing/:grantId", "oauth/standing/read"], readonly ["PUT", "/v1/oauth/standing/:grantId", "oauth/standing/set"], readonly ["DELETE", "/v1/oauth/standing/:grantId", "oauth/standing/revoke"]];
+export type OracleAction = (typeof ROUTE_ACTIONS)[number][2];
+/** Actions the legacy `*` NEVER stands in for, whatever `ACCEPT_WILDCARD` says (S3 review §3). */
+export declare const STRICT_ACTIONS: ReadonlySet<OracleAction>;
+/** Every `can` `ucanAuth` will validate at all: the table's actions, plus `*` while it is accepted. */
+export declare const ACCEPTED_CANS: readonly string[];
+/** 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 declare function actionFor(method: string, path: string): {
+    pattern: string;
+    action: OracleAction;
+} | 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 declare const requireAction: import("hono").MiddlewareHandler<AppEnv, string, {}, Response>;
+//# sourceMappingURL=capability.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"capability.d.ts","sourceRoot":"","sources":["../../src/middleware/capability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAC;AAGzC,uFAAuF;AACvF,eAAO,MAAM,eAAe,OAAO,CAAC;AAEpC,kFAAkF;AAClF,eAAO,MAAM,aAAa,sBACvB,MAAM,EAAE,0BAA0B,EAAE,sBAAsB,aAC1D,KAAK,EAAE,iBAAiB,EAAE,kBAAkB,aAC5C,MAAM,EAAE,qCAAqC,EAAE,mBAAmB,aAClE,MAAM,EAAE,sCAAsC,EAAE,oBAAoB,aACpE,MAAM,EAAE,oCAAoC,EAAE,kBAAkB,aAEhE,OAAO,EAAE,wCAAwC,EAAE,sBAAsB,aACzE,KAAK,EAAE,wCAAwC,EAAE,2BAA2B,aAE5E,MAAM,EAAE,yCAAyC,EAAE,6BAA6B,aAChF,KAAK,EAAE,yCAAyC,EAAE,4BAA4B,aAE7E,MAAM,EACN,+DAA+D,EAC/D,8BAA8B,aAE/B,KAAK,EAAE,YAAY,EAAE,aAAa,aAClC,KAAK,EAAE,qBAAqB,EAAE,aAAa,aAE3C,QAAQ,EAAE,0BAA0B,EAAE,cAAc,aACpD,KAAK,EAAE,sBAAsB,EAAE,cAAc,aAC7C,MAAM,EAAE,sBAAsB,EAAE,gBAAgB,aAChD,KAAK,EAAE,kBAAkB,EAAE,cAAc,aAEzC,MAAM,EAAE,8BAA8B,EAAE,0BAA0B,aAElE,KAAK,EAAE,iCAAiC,EAAE,qBAAqB,aAC/D,MAAM,EAAE,iCAAiC,EAAE,wBAAwB,aAEnE,KAAK,EAAE,6BAA6B,EAAE,qBAAqB,aAC3D,KAAK,EAAE,6BAA6B,EAAE,oBAAoB,aAC1D,QAAQ,EAAE,6BAA6B,EAAE,uBAAuB,EACzD,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC;AAE7D,kGAAkG;AAClG,eAAO,MAAM,cAAc,EAAE,WAAW,CAAC,YAAY,CAgBnD,CAAC;AAEH,uGAAuG;AACvG,eAAO,MAAM,aAAa,EAAE,SAAS,MAAM,EAK1C,CAAC;AAUF;sFACsF;AACtF,wBAAgB,SAAS,CACvB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,GACX;IAAE,OAAO,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,YAAY,CAAA;CAAE,GAAG,IAAI,CAIlD;AAED;;gCAEgC;AAChC,eAAO,MAAM,aAAa,gEAuBxB,CAAC"}