@ixo/decision-oracle 0.0.0-stage → 0.2.0

package/dist/routes/v1/api/claims-read.js

@@ -0,0 +1,123 @@
+/**
+ * The claim reads that are not the record itself (go-prod spec §4.2): the list, the timeline and the
+ * receipt. Every one is scoped to the caller's source — its own API claims plus its linked
+ * collections' chain claims (contracts v1.2) — and a console member's `nb.protocols` narrow it
+ * further; a claim outside either is `404`, never `403`: its existence is not the caller's to learn
+ * (§14). `readableClaimOf` is that rule for one claim read, `claimOf` its API-only form for the
+ * routes that touch a body (review, erase).
+ */
+import { and, eq } from "drizzle-orm";
+import { Hono } from "hono";
+import { z } from "zod";
+import { ListClaimsQuery, RecordClaimId } from "../../../contracts/index.js";
+import { apiClaims, apiSourceCollections, claimIngests, decisions, watchedCollections, } from "../../../db/schema.js";
+import { claimPage } from "../../../lib/api-lane/claim-list.js";
+import { apiClaimEvents, chainClaimEvents } from "../../../lib/api-lane/events.js";
+import { engineBaseUrl } from "../../../lib/engine/client.js";
+import { validate } from "../../../lib/validator.js";
+import { access, sourceOf } from "../../../middleware/api/auth.js";
+import { ApiError } from "../../../middleware/api/errors.js";
+export const claimsRead = new Hono();
+/** A member's `nb.protocols` (console or OAuth); null = every protocol (a key, or an un-narrowed grant). */
+const protocolsOf = (caller) => caller.kind === "key" ? null : caller.protocols;
+/** A read route's `:claimId` — either lane's id (contracts v1.2), bounded before any query. */
+export const ClaimParam = z.object({ claimId: RecordClaimId });
+const notFound = (claimId) => new ApiError("NOT_FOUND", `Claim ${claimId} was not found for this source.`);
+/**
+ * The caller's API claim, or `404 NOT_FOUND` — for an unknown id, another source's, one outside the
+ * member's `nb.protocols`, and a linked collection's chain claim alike, so the answer never tells
+ * them apart (§14). What the routes that touch the claim's BODY take (review, erase): a chain
+ * claim's body is not the oracle's to show or erase.
+ */
+export async function claimOf(c, claimId) {
+    const caller = sourceOf(c);
+    const db = await c.var.db();
+    const claim = await db.query.apiClaims.findFirst({
+        where: and(eq(apiClaims.claimId, claimId), eq(apiClaims.sourceId, caller.source.sourceId)),
+        columns: { claimId: true, sourceId: true, protocolDid: true, receivedAt: true },
+    });
+    const protocols = protocolsOf(caller);
+    if (!claim || (protocols && !protocols.includes(claim.protocolDid)))
+        throw notFound(claimId);
+    return claim;
+}
+/**
+ * Any claim the caller may READ (contracts v1.2): its own API claim, or a chain claim of a
+ * collection linked to its source (`api_source_collections`, any live link — lib/api-lane/linked.ts),
+ * inside the member's `nb.protocols` by the collection's protocol — else the same
+ * `404` as `claimOf`. The record, timeline, receipt
+ * and report routes take this; nothing that touches a body does.
+ */
+export async function readableClaimOf(c, claimId) {
+    const caller = sourceOf(c);
+    const db = await c.var.db();
+    const [own] = await db
+        .select({ protocolDid: apiClaims.protocolDid })
+        .from(apiClaims)
+        .where(and(eq(apiClaims.claimId, claimId), eq(apiClaims.sourceId, caller.source.sourceId)));
+    const [chain] = own
+        ? []
+        : await db
+            .select({ protocolDid: watchedCollections.protocolDid })
+            .from(claimIngests)
+            .innerJoin(apiSourceCollections, and(eq(apiSourceCollections.collectionId, claimIngests.collectionId), eq(apiSourceCollections.sourceId, caller.source.sourceId)))
+            .innerJoin(watchedCollections, eq(watchedCollections.collectionId, claimIngests.collectionId))
+            .where(and(eq(claimIngests.claimId, claimId), eq(claimIngests.lane, "chain")));
+    const protocolDid = own?.protocolDid ?? chain?.protocolDid;
+    const protocols = protocolsOf(caller);
+    // A chain claim whose collection has no protocol is one the record cannot show (record.ts).
+    if (!protocolDid || (protocols && !protocols.includes(protocolDid)))
+        throw notFound(claimId);
+    return { claimId, lane: own ? "api" : "chain" };
+}
+claimsRead.get("/claims", access({ op: "listClaims", scope: "claims:read", capability: "claims/read" }), validate("query", ListClaimsQuery), async (c) => {
+    const caller = sourceOf(c);
+    const sourceId = caller.source.sourceId;
+    const q = c.req.valid("query");
+    // The linked collections' chain claims ride along (contracts v1.2) — for a console member by
+    // default; an API key sees them only with `lane=chain` (or a `collectionId`), so an integration
+    // written before 1.2 never meets a chain record it did not ask for. `collectionId` names one
+    // linked collection — an unlinked one is simply an empty stream, never a 403 (§14).
+    const lane = q.lane ?? (caller.kind === "key" && !q.collectionId ? "api" : undefined);
+    return c.json(await claimPage(await c.var.db(), q, {
+        api: lane !== "chain" && !q.collectionId ? { sourceId } : null,
+        chain: lane !== "api" ? { linkedTo: sourceId, collectionId: q.collectionId } : null,
+        protocols: protocolsOf(caller),
+        sourceId,
+    }));
+});
+claimsRead.get("/claims/:claimId/events", access({ op: "getClaimEvents", scope: "claims:read", capability: "claims/read" }), validate("param", ClaimParam), async (c) => {
+    const claim = await readableClaimOf(c, c.req.valid("param").claimId);
+    const db = await c.var.db();
+    return c.json({
+        claimId: claim.claimId,
+        items: claim.lane === "api"
+            ? await apiClaimEvents(db, claim.claimId)
+            : await chainClaimEvents(db, claim.claimId),
+    });
+});
+claimsRead.get("/claims/:claimId/receipt", access({ op: "getClaimReceipt", scope: "claims:read", capability: "claims/read" }), validate("param", ClaimParam), async (c) => {
+    const claim = await readableClaimOf(c, c.req.valid("param").claimId);
+    return c.json(await receiptOf(c, claim.claimId));
+});
+/** The claim's receipt with where to verify it — shared with the operator view (admin-claims.ts). */
+export async function receiptOf(c, claimId) {
+    const db = await c.var.db();
+    const row = await db.query.decisions.findFirst({
+        where: eq(decisions.claimId, claimId),
+        columns: { receiptCid: true, receiptJws: true },
+    });
+    // The engine mints a receipt for every decision but `pending_review` (ENGINE-CONTRACT), and
+    // the facts lane's own outcomes have none: either way there is nothing to verify yet.
+    if (!row?.receiptCid || !row.receiptJws) {
+        throw new ApiError("NOT_FOUND", `Claim ${claimId} has no signed receipt yet: it is still being decided or is waiting for review. Check again once it has a decision.`);
+    }
+    const engine = engineBaseUrl(c.get("config").EVAL_ENGINE_HOSTNAME);
+    return {
+        cid: row.receiptCid,
+        jws: row.receiptJws,
+        issuerKeysUrl: `${engine}/v1/issuer-keys`,
+        verifyUrl: `${engine}/v1/receipts/${row.receiptCid}`,
+    };
+}
+//# sourceMappingURL=claims-read.js.map

package/dist/routes/v1/api/claims-read.js.map

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

package/dist/routes/v1/api/claims.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Submit and read one claim (go-prod spec §4.2–§4.6; payments spec §4). The submit order is the
+ * `startApiClaim` seam's, and every step before `recordApiClaims` is free for the caller:
+ *
+ *   repeat? → paused? → protocol allowed? → work order + answers (§4.3) → pay (402 / verify,
+ *     which reserves) → recordApiClaims → startApiClaims → wait → 200 record | 202
+ *
+ * The money moves on the engine's receipt (contracts v1.3): the workflow settles after the decision
+ * row, and a `200` carrying a decision carries that settle answer as `PAYMENT-RESPONSE`.
+ *
+ * **Idempotency is the claim's own id** (§4.6): with an `Idempotency-Key` the claimId is
+ * `apc_` + 40 hex of sha256(sourceId|key), so a repeat finds the claim and answers its CURRENT
+ * state — never a second charge, never a second run; the same key over a different body is
+ * `409 IDEMPOTENCY_MISMATCH`. Without a key, a paid retry takes its claimId from the offer its
+ * nonce names, so a (402, paid retry) pair is one claim either way. The check runs before the
+ * gate (payments spec §0 rule 6).
+ *
+ * **Who pays** (§3.2): a source in billing mode `none` never meets the gate — no 402, no charge
+ * row. An `x402` source pays through S4's `PaymentGate`; with `API_PAYMENTS` off it is
+ * `503 SOURCE_PAUSED { reason: payments-disabled }`, as when the facilitator is down.
+ */
+import { Hono } from "hono";
+import { type ClaimRecord, type PaymentRequiredBody, SubmitClaimRequest } from "../../../contracts/index.js";
+import type { Database } from "../../../db/client.js";
+import { type ApiSource } from "../../../db/schema.js";
+import { createPaymentGate } from "../../../lib/payments/index.js";
+import { ApiError } from "../../../middleware/api/errors.js";
+import type { ApiContext, ApiEnv, SourceCaller } from "../../../middleware/api/types.js";
+export declare const claims: Hono<ApiEnv, import("hono/types").BlankSchema, "/">;
+type Gate = ReturnType<typeof createPaymentGate>;
+/** The gate, or null for a free source; `API_PAYMENTS` off ⇒ `503 payments-disabled`. `run`
+ *  turns a facilitator outage into the same 503 — the payment lane is paused, not the claim. */
+export declare function gateFor(c: ApiContext): Promise<{
+    gate: Gate;
+    run: <T>(f: (g: Gate) => Promise<T>) => Promise<T>;
+} | null>;
+/** The gate's `preflight` (nothing reserved), with "no offer of yours" (`nonce_unknown`) as null —
+ *  the caller answers a fresh 402 instead of one with nothing to pay. */
+export declare function preflightOrNone(pay: NonNullable<Awaited<ReturnType<typeof gateFor>>>, header: string, caller: SourceCaller): Promise<import("../../../contracts/index.js").PaymentRefusal | {
+    ok: true;
+    offerId: string;
+    items: import("../../../contracts/index.js").PaidItem[];
+    payer: string | null;
+} | null>;
+/** The gate's `verify` — it RESERVES; call it only once every check that can refuse has passed. */
+export declare const reserve: (pay: NonNullable<Awaited<ReturnType<typeof gateFor>>>, header: string, caller: SourceCaller) => Promise<import("../../../contracts/index.js").PaymentRefusal | {
+    ok: true;
+    payer: string;
+    offerId: string;
+    items: import("../../../contracts/index.js").PaidItem[];
+}>;
+/** The gate's 402 as it built it (the §4.1 envelope, `docsUrl` included), and the authoritative
+ *  `PAYMENT-REQUIRED` header when there is something to pay (board D30). */
+export declare function paymentRequired(c: ApiContext, body: PaymentRequiredBody): Response;
+/** A console submit has no key: only the payment delegation caps it (§4.1 `SPEND_CAP`). */
+export declare const keyPrefixOf: (caller: SourceCaller) => string | null;
+export declare const submission: (body: SubmitClaimRequest, source: ApiSource, ownClaims: readonly string[], submitter: string | null) => {
+    sourceId: string;
+    ownClaims: readonly string[];
+    answers: Record<string, unknown>;
+    attachments: ({
+        question: string;
+        name?: string | undefined;
+        mediaType?: string | undefined;
+        cid?: string | undefined;
+        url: string;
+    } | {
+        question: string;
+        name?: string | undefined;
+        mediaType?: string | undefined;
+        uploadId: string;
+        cid: string;
+    })[];
+    submitter: string | null;
+    payeeField: string | null;
+};
+/**
+ * An AI app over OAuth acts for ONE person, so the claim can only be about them: an explicit
+ * `submitter` that is not the signed-in user's DID is refused (owner, 2026-10-10). A key or the
+ * console submits for its people and names whom it likes.
+ */
+export declare function checkOAuthSubmitter(caller: SourceCaller, submitter: string | undefined, path?: string): void;
+/** Who sent the claim, server-side: the OAuth user (a person); a key or the console names no one
+ *  here — the key prefix and the audit log say which integration or member it was. */
+export declare const submittedByOf: (caller: SourceCaller) => string | null;
+/** Which AI app sent it. The name is the app's pick at dynamic registration, so untrusted text —
+ *  trimmed and capped at 100 characters, otherwise verbatim (a blank one falls back to the client
+ *  id) — and a display hint only, never an authorisation input; `verified` is AuthHub's. */
+export declare const submittedViaOf: (caller: SourceCaller) => ClaimRecord["submittedVia"];
+export declare function idempotencyKeyOf(c: ApiContext): string | null;
+/** `apc_` + 40 hex of sha256(sourceId|key) — the ledger's primary key IS the duplicate guard. */
+export declare function keyedClaimId(sourceId: string, key: string): Promise<string>;
+export declare const findClaim: (db: Database, claimId: string) => import("drizzle-orm/sqlite-core/query-builders/query").SQLiteRelationalQuery<"async", {
+    attachments: unknown[] | null;
+    body: Record<string, unknown> | null;
+    bodyDigest: string;
+    bodyErasedAt: Date | null;
+    claimId: string;
+    content: {
+        protocolDid: string;
+        answers: Record<string, unknown>;
+        attachments?: unknown[] | undefined;
+        submitter?: string | undefined;
+        metadata?: Record<string, unknown> | undefined;
+    } | null;
+    contentDigest: string | null;
+    idempotencyKey: string | null;
+    metadata: Record<string, unknown> | null;
+    payment: unknown;
+    protocolDid: string;
+    receivedAt: Date;
+    requestDigest: string | null;
+    sourceId: string;
+    submittedBy: string | null;
+    submittedVia: string | null;
+    submittedViaVerified: boolean | null;
+    submitter: string | null;
+    submitterDigest: string | null;
+    via: string | null;
+    webhookUrl: string | null;
+} | undefined>;
+/** S3 review §8: one OAuth grant's charges over 24 h stop at `GRANT_CAP_CENTS_PER_DAY`. */
+export declare const grantCapReached: () => ApiError;
+/** A paused source takes no new claim; the reason stays in `details` as before. */
+export declare const sourcePaused: (reason: string | null) => ApiError;
+/** A member whose role is narrowed to some protocols submits under another. */
+export declare const protocolOutOfReach: (protocolDid: string) => string;
+/** The named protocol, which must be on the allow-list; unnamed ⇒ the source's only one (§4.3). */
+export declare function protocolOf(named: string | undefined, allowed: readonly string[]): string;
+export {};
+//# sourceMappingURL=claims.d.ts.map

package/dist/routes/v1/api/claims.d.ts.map

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