@ixo/decision-oracle 0.0.0-stage → 0.2.0

package/dist/routes/v1/api/openapi.gen.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"openapi.gen.js","sourceRoot":"","sources":["../../../../src/routes/v1/api/openapi.gen.ts"],"names":[],"mappings":"AAAA,+FAA+F;AAC/F,iGAAiG;AACjG,sEAAsE;AAEtE,mGAAmG;AACnG,wEAAwE;AACxE,MAAM,CAAC,MAAM,gBAAgB,GAA4B,IAAI,CAAC,KAAK,CAAC,++jXAA++jX,CAAC,CAAC"}

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

@@ -0,0 +1,22 @@
+/**
+ * The protocols a caller can submit under (go-prod spec §4.2) and each one's work order, with the
+ * oracle's published price (payments spec §3.1). PUBLIC: without a credential they answer the
+ * oracle's catalogue — the facilitator reads `price` here to check every offer (cached 5 min, as
+ * the `Cache-Control` says) — and with one, the source's allow-list, narrowed by a member's
+ * `nb.protocols`. A protocol outside what the caller can see is `404`, never `403` (§14).
+ *
+ * The price is `publishedPrice` — the SAME function the gate's `quote`/`offer` charge by — so what
+ * this route serves and what an offer charges cannot differ; it is the protocol's alone, whoever
+ * asks. `price: null` = none published (the facilitator reads it as "not published").
+ */
+import { Hono } from "hono";
+import type { OracleEnv } from "../../../env.js";
+import type { ApiEnv } from "../../../middleware/api/types.js";
+export declare const protocols: Hono<ApiEnv, import("hono/types").BlankSchema, "/">;
+/**
+ * A protocol's display name: its entity's `#pro` profile name (what the portal shows), else its
+ * claim form's title, else null — a listing never fails on one protocol (an unusable rubric, an
+ * outage); `GET /protocols/:did` says why.
+ */
+export declare function nameOf(env: OracleEnv, protocolDid: string): Promise<string | null>;
+//# sourceMappingURL=protocols.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"protocols.d.ts","sourceRoot":"","sources":["../../../../src/routes/v1/api/protocols.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAK5B,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,cAAc,CAAC;AAU9C,OAAO,KAAK,EAAc,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAIxE,eAAO,MAAM,SAAS,qDAAqB,CAAC;AA2D5C;;;;GAIG;AACH,wBAAsB,MAAM,CAAC,GAAG,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAQxF"}

package/dist/routes/v1/api/protocols.js

@@ -0,0 +1,153 @@
+/**
+ * The protocols a caller can submit under (go-prod spec §4.2) and each one's work order, with the
+ * oracle's published price (payments spec §3.1). PUBLIC: without a credential they answer the
+ * oracle's catalogue — the facilitator reads `price` here to check every offer (cached 5 min, as
+ * the `Cache-Control` says) — and with one, the source's allow-list, narrowed by a member's
+ * `nb.protocols`. A protocol outside what the caller can see is `404`, never `403` (§14).
+ *
+ * The price is `publishedPrice` — the SAME function the gate's `quote`/`offer` charge by — so what
+ * this route serves and what an offer charges cannot differ; it is the protocol's alone, whoever
+ * asks. `price: null` = none published (the facilitator reads it as "not published").
+ */
+import { sql } from "drizzle-orm";
+import { Hono } from "hono";
+import { loadConfig } from "../../../config.js";
+import { apiSources } from "../../../db/schema.js";
+import { readLinkedDoc } from "../../../facts/linked-doc.js";
+import { fetchClient } from "../../../lib/http/client.js";
+import { getEntityDocs } from "../../../lib/ixo/blocksync/index.js";
+import { readCache } from "../../../lib/metrics.js";
+import { publishedPrice } from "../../../lib/payments/index.js";
+import { perReviewProtocols, reviewBillingActive } from "../../../lib/payments/review-billing.js";
+import { generateTraceContext } from "../../../lib/tracing.js";
+import { access } from "../../../middleware/api/auth.js";
+import { ApiError } from "../../../middleware/api/errors.js";
+import { getOracle } from "../../../oracle.js";
+import { workOrderFor } from "./work-orders.js";
+export const protocols = new Hono();
+/** The facilitator's price cache (payments spec §3.1): a shared cache may keep the anonymous
+ *  answer as long. A credentialed answer differs, hence the `Vary` — and it is one source's
+ *  allow-list, so no cache may keep it at all (a `Vary` alone leaves that to the cache). */
+const PUBLIC_CACHE = "public, max-age=300";
+const PRIVATE_CACHE = "private, no-store";
+/**
+ * What the caller may see. Anonymous ⇒ the catalogue: `supportedProtocols` plus every protocol an
+ * operator enabled for a source (`PUT /admin/sources/:id/protocols` is not held to the list, and an
+ * oracle with an empty list publishes nothing else) plus, while per-review billing is active, the
+ * protocols of the watched chain collections billed per review (a chain review's offer names one,
+ * and an open oracle lists none) — every protocol an offer can name, so the facilitator can check
+ * each one. A credential ⇒ the source's allow-list, narrowed by `nb.protocols`.
+ */
+async function visible(c) {
+    const caller = c.get("caller");
+    if (caller.kind === "key")
+        return caller.source.allowedProtocols;
+    if (caller.kind === "member" || caller.kind === "oauth") {
+        const narrow = caller.protocols;
+        return caller.source.allowedProtocols.filter((p) => !narrow || narrow.includes(p));
+    }
+    return catalogue(c, await c.var.db());
+}
+async function catalogue(c, db) {
+    const [enabled, watched] = await Promise.all([
+        db.all(sql `select distinct j.value from ${apiSources}, json_each(${apiSources.allowedProtocols}) j`),
+        perReviewProtocols(db),
+    ]);
+    // The plan is read only when it could add something (it may ask the engine).
+    const billed = watched.length > 0 &&
+        (await reviewBillingActive({
+            config: c.get("config"),
+            logger: c.get("logger"),
+            trace: c.get("trace"),
+            cache: c.env.CACHE_KV,
+        }));
+    return [
+        ...new Set([
+            ...getOracle().config.supportedProtocols,
+            ...enabled.map((r) => r.value),
+            ...(billed ? watched : []),
+        ]),
+    ];
+}
+function cacheHeaders(c) {
+    c.header("Vary", "Authorization, X-Source-Id");
+    c.header("Cache-Control", c.get("caller").kind === "anonymous" ? PUBLIC_CACHE : PRIVATE_CACHE);
+}
+/** How long a protocol entity's profile name is kept: a rename on chain shows within the hour. */
+const PROFILE_NAME_TTL_SEC = 3600;
+/**
+ * A protocol's display name: its entity's `#pro` profile name (what the portal shows), else its
+ * claim form's title, else null — a listing never fails on one protocol (an unusable rubric, an
+ * outage); `GET /protocols/:did` says why.
+ */
+export async function nameOf(env, protocolDid) {
+    const profile = await profileName(env, protocolDid);
+    if (profile)
+        return profile;
+    try {
+        return (await workOrderFor(env, protocolDid)).order.name;
+    }
+    catch {
+        return null;
+    }
+}
+/** The `#pro` profile's `name`, hash-checked against its anchored proof (`readLinkedDoc`). Kept
+ *  `PROFILE_NAME_TTL_SEC` in KV (`""` = the entity has none); a failed read is null and never
+ *  kept, so a Blocksync or gateway blip costs one listing its names, not an hour of them. */
+async function profileName(env, protocolDid) {
+    const key = `protocol-name:${protocolDid}`;
+    const cached = await readCache("protocol-name", () => env.CACHE_KV.get(key));
+    if (cached !== null)
+        return cached || null;
+    try {
+        const config = loadConfig(env);
+        const trace = generateTraceContext();
+        const docs = await getEntityDocs({ config, trace }, protocolDid);
+        const pro = docs?.resources.find((r) => r.id?.endsWith("#pro"));
+        let name = "";
+        if (pro) {
+            const read = await readLinkedDoc(pro, {
+                ipfsGateway: config.IPFS_GATEWAY_URL,
+                fetch: (u, init) => fetchClient(u, { ...init, trace, attempts: 2 }),
+            });
+            if (!read.ok)
+                return null;
+            const raw = read.json?.name;
+            name = typeof raw === "string" ? raw.trim() : "";
+        }
+        await env.CACHE_KV.put(key, name, { expirationTtl: PROFILE_NAME_TTL_SEC }).catch(() => { });
+        return name || null;
+    }
+    catch {
+        return null;
+    }
+}
+protocols.get("/protocols", access({ op: "listProtocols", scope: null, capability: "public" }), async (c) => {
+    const config = c.get("config");
+    const dids = await visible(c);
+    const items = await Promise.all(dids.map(async (protocolDid) => ({
+        protocolDid,
+        name: await nameOf(c.env, protocolDid),
+        price: publishedPrice(config, protocolDid),
+    })));
+    cacheHeaders(c);
+    return c.json({ items });
+});
+protocols.get("/protocols/:did", access({ op: "getProtocol", scope: null, capability: "public" }), async (c) => {
+    const protocolDid = c.req.param("did");
+    if (!(await visible(c)).includes(protocolDid)) {
+        const anonymous = c.get("caller").kind === "anonymous";
+        throw new ApiError("NOT_FOUND", anonymous
+            ? `Protocol ${protocolDid} is not offered by this oracle.`
+            : `Protocol ${protocolDid} is not enabled for this source. Ask this oracle's operator to enable it.`);
+    }
+    // An unusable rubric is `503 SOURCE_PAUSED { rubric-unusable }`, as the submit answers it.
+    const { order } = await workOrderFor(c.env, protocolDid);
+    const body = {
+        ...order,
+        price: publishedPrice(c.get("config"), protocolDid),
+    };
+    cacheHeaders(c);
+    return c.json(body);
+});
+//# sourceMappingURL=protocols.js.map

package/dist/routes/v1/api/protocols.js.map

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

package/dist/routes/v1/api/review-billing.d.ts

@@ -0,0 +1,18 @@
+/**
+ * A source's review-billing delegation (contracts 1.22.0; per-review checker billing for chain
+ * claims, payments/review-billing.ts): `PUT` stores the organisation's standing x402 payment
+ * delegation, `GET` shows where it stands (never the token), `DELETE` drops it. Only while
+ * per-review billing is active (IXO's plan for the oracle, `reviewBillingActive`); otherwise every
+ * path is a 404, like a route that does not exist.
+ *
+ * Console-only (`scope: none`): storing or dropping it needs `keys/manage` ("API keys and payment
+ * delegations") — a member's grant, or a controller of the organisation; reading it `spend/read`
+ * (every preset that holds `keys/manage` holds it too). Whoever stores it, the delegation must be
+ * SIGNED by the organisation's CURRENT chain owner (owner, 2026-10-14): the facilitator debits the
+ * issuer's subscription deed, and the organisation's credits are its owner's. Every check runs
+ * before anything is written; the token is never logged, audited or returned.
+ */
+import { Hono } from "hono";
+import type { ApiEnv } from "../../../middleware/api/types.js";
+export declare const reviewBilling: Hono<ApiEnv, import("hono/types").BlankSchema, "/">;
+//# sourceMappingURL=review-billing.d.ts.map

package/dist/routes/v1/api/review-billing.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"review-billing.d.ts","sourceRoot":"","sources":["../../../../src/routes/v1/api/review-billing.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAqB5B,OAAO,KAAK,EAAc,MAAM,EAAE,MAAM,+BAA+B,CAAC;AAExE,eAAO,MAAM,aAAa,qDAAqB,CAAC"}

package/dist/routes/v1/api/review-billing.js

@@ -0,0 +1,196 @@
+/**
+ * A source's review-billing delegation (contracts 1.22.0; per-review checker billing for chain
+ * claims, payments/review-billing.ts): `PUT` stores the organisation's standing x402 payment
+ * delegation, `GET` shows where it stands (never the token), `DELETE` drops it. Only while
+ * per-review billing is active (IXO's plan for the oracle, `reviewBillingActive`); otherwise every
+ * path is a 404, like a route that does not exist.
+ *
+ * Console-only (`scope: none`): storing or dropping it needs `keys/manage` ("API keys and payment
+ * delegations") — a member's grant, or a controller of the organisation; reading it `spend/read`
+ * (every preset that holds `keys/manage` holds it too). Whoever stores it, the delegation must be
+ * SIGNED by the organisation's CURRENT chain owner (owner, 2026-10-14): the facilitator debits the
+ * issuer's subscription deed, and the organisation's credits are its owner's. Every check runs
+ * before anything is written; the token is never logged, audited or returned.
+ */
+import { parsePaymentDelegation } from "@ixo/x402-ixo-pay";
+import { and, eq, gt, ne } from "drizzle-orm";
+import { Hono } from "hono";
+import { SetReviewBillingRequest } from "../../../contracts/index.js";
+import { resumePayerBilling } from "../../../cron/payer-billing.js";
+import { apiSources, reviewBillingDelegations } from "../../../db/schema.js";
+import { getEntityOwner } from "../../../lib/ixo/blocksync/index.js";
+import { resolveIssuerKeys, verifyDelegationSignature } from "../../../lib/ixo/delegation-verify.js";
+import { resolveServiceDid } from "../../../lib/ixo/did.js";
+import { oracleWebDid } from "../../../lib/ixo/ucan.js";
+import { createFacilitatorClient, facilitatorUrl } from "../../../lib/payments/facilitator.js";
+import { lowestPrice, MIN_DELEGATION_LIFE_MS, reviewBillingActive, reviewBillingView, storeDelegation, } from "../../../lib/payments/review-billing.js";
+import { validate } from "../../../lib/validator.js";
+import { audit } from "../../../middleware/api/audit.js";
+import { access, sourceOf } from "../../../middleware/api/auth.js";
+import { ApiError } from "../../../middleware/api/errors.js";
+import { idempotent } from "../../../middleware/api/idempotency.js";
+export const reviewBilling = new Hono();
+const PATH = "/source/review-billing";
+/** `nbf` a little ahead of our clock is a clock skew, not a delegation for later. */
+const NBF_SKEW_MS = 5 * 60_000;
+const DELETED_MESSAGE = "This oracle no longer holds a review-billing delegation for this source, so its collections' reviews pause until one is stored again. The delegation itself stays valid until it expires: to stop it everywhere, revoke it in the UCAN store (the Decision Console does this).";
+// Before `access()`: an oracle whose plan does not bill reviews has no such route, for anyone.
+reviewBilling.use(PATH, async (c, next) => {
+    const active = await reviewBillingActive({
+        config: c.get("config"),
+        logger: c.get("logger"),
+        trace: c.get("trace"),
+        cache: c.env.CACHE_KV,
+    });
+    if (!active) {
+        throw new ApiError("NOT_FOUND", `This oracle does not bill reviews per review, so there is no ${c.req.method} ${c.req.path}.`);
+    }
+    await next();
+});
+const invalid = (reason, message, detail) => new ApiError("VALIDATION", message, { reason, ...(detail ? { detail } : {}) });
+/** The chain deps the owner read needs. */
+const chainOf = (c) => ({ config: c.get("config"), trace: c.get("trace") });
+/** The organisation's CURRENT chain owner, read uncached (Blocksync trouble is a 503). */
+async function orgOwner(c, entityDid) {
+    if (!entityDid)
+        return null;
+    const owner = await getEntityOwner(chainOf(c), entityDid);
+    return owner ? `did:ixo:${owner}` : null;
+}
+function facilitator(c) {
+    return createFacilitatorClient({
+        config: c.get("config"),
+        logger: c.get("logger"),
+        trace: c.get("trace"),
+        cache: c.env.CACHE_KV,
+    });
+}
+reviewBilling.put(PATH, access({ op: "setReviewBilling", scope: "none", capability: "keys/manage" }), idempotent(), validate("json", SetReviewBillingRequest), async (c) => {
+    const caller = sourceOf(c);
+    if (caller.kind !== "member") {
+        throw new ApiError("FORBIDDEN", "Review billing is set from the Decision Console, signed in as a member of the source.");
+    }
+    const { source } = caller;
+    const config = c.get("config");
+    const { delegation } = c.req.valid("json");
+    // 1 · The source: one that pays (a `none` source never does), with payments wired.
+    if (source.billingMode !== "x402") {
+        throw new ApiError("CONFLICT", "This source is not billed (its billing mode is none), so it cannot pay for reviews. Ask the oracle's operator to bill it.", { reason: "billing_mode_none" });
+    }
+    if (!config.API_PAYMENTS || !config.X402_FACILITATOR_URL) {
+        throw new ApiError("SOURCE_PAUSED", "Payments are off on this oracle, so it cannot bill reviews. Ask its operator.", { reason: "payments-disabled" });
+    }
+    // 2 · The token: a payment delegation, signed by the issuer it names.
+    const parsed = await parsePaymentDelegation(delegation);
+    if (!parsed.ok) {
+        throw invalid("not_a_payment_delegation", "This is not a payment delegation (an x402-ixo-pay billing/pay delegation, base64 CAR). Sign a new one in the Decision Console.", parsed.reason);
+    }
+    const d = parsed.delegation;
+    const facilitatorDid = await resolveServiceDid(c.get("trace"), c.env.CACHE_KV, facilitatorUrl(config));
+    // 3 · Its signer: the organisation's owner on chain NOW — whoever stores it.
+    const owner = await orgOwner(c, source.companyEntityDid);
+    if (owner === null || d.issuer !== owner) {
+        throw new ApiError("FORBIDDEN", "Review billing must be signed by the organisation's owner on chain: the owner's subscription credits pay for the reviews. Ask the owner to sign it.", { reason: "not_org_owner" });
+    }
+    // 4 · To the facilitator this oracle pays through.
+    if (d.audience !== facilitatorDid) {
+        throw invalid("wrong_audience", `This delegation is for another payment facilitator (${d.audience}), not this oracle's (${facilitatorDid}).`);
+    }
+    // 5 · Bound to this oracle alone: nobody else can spend it, so this oracle's count is exact.
+    const oracleDid = oracleWebDid(config);
+    if (d.oracles?.length !== 1 || d.oracles[0] !== oracleDid) {
+        throw invalid("not_oracle_bound", `This delegation must name this oracle, and only it, in nb.oracles: ["${oracleDid}"].`);
+    }
+    // 6 · Long enough to be worth storing; usable now.
+    const now = Date.now();
+    if (d.expiration * 1000 < now + MIN_DELEGATION_LIFE_MS) {
+        throw invalid("expires_too_soon", "This delegation expires within 24 hours. Sign one that lasts longer.");
+    }
+    if (d.notBefore !== null && d.notBefore * 1000 > now + NBF_SKEW_MS) {
+        throw invalid("not_yet_valid", "This delegation is not valid yet (its nbf is in the future).");
+    }
+    // 7 · Its cap pays for at least one review.
+    const lowest = lowestPrice(config);
+    if (lowest === null || BigInt(d.maxAmount) < lowest) {
+        throw invalid("cap_below_price", lowest === null
+            ? "This oracle publishes no per-review price, so it cannot bill reviews. Ask its operator."
+            : `Its maxAmount (${d.maxAmount} upay) is below the price of one review (${lowest} upay).`);
+    }
+    // The signature last of the token checks: it costs a chain read of the owner's keys.
+    await verifyDelegationSignature(config, delegation, d.issuer, () => resolveIssuerKeys(config, d.issuer, c.get("trace")), facilitatorDid).catch((err) => {
+        if (err instanceof ApiError || err.status !== 400)
+            throw err;
+        throw invalid("bad_signature", "This delegation's signature does not verify against its signer's keys on chain.");
+    });
+    // 8 · One per organisation: "which source pays" is never a guess.
+    const db = await c.var.db();
+    const [elsewhere] = await db
+        .select({ sourceId: reviewBillingDelegations.sourceId })
+        .from(reviewBillingDelegations)
+        .innerJoin(apiSources, eq(apiSources.sourceId, reviewBillingDelegations.sourceId))
+        .where(and(eq(apiSources.companyEntityDid, source.companyEntityDid), ne(reviewBillingDelegations.sourceId, source.sourceId), gt(reviewBillingDelegations.expiresAt, new Date(now))))
+        .limit(1);
+    if (elsewhere) {
+        throw new ApiError("CONFLICT", "Another source of this organisation already pays for its reviews on this oracle. Remove it there first.", { reason: "review_billing_elsewhere", sourceId: elsewhere.sourceId });
+    }
+    const row = await storeDelegation(db, config, {
+        sourceId: source.sourceId,
+        payerDid: d.issuer,
+        delegationCid: d.cid,
+        maxAmount: d.maxAmount,
+        expiresAt: new Date(d.expiration * 1000),
+        notBefore: d.notBefore === null ? null : new Date(d.notBefore * 1000),
+        delegation,
+        createdBy: caller.did,
+    });
+    await audit(c, "source.review_billing_set", d.cid, {
+        payer: d.issuer,
+        maxAmount: d.maxAmount,
+        expiresAt: row.expiresAt.toISOString(),
+    });
+    // The organisation's collections paused for want of payment resume now, not on the next tick.
+    // Fail-soft: the tick does the same a minute later.
+    await resumePayerBilling({
+        db,
+        config,
+        logger: c.get("logger"),
+        metrics: c.get("metrics"),
+        trace: c.get("trace"),
+        cache: c.env.CACHE_KV,
+        env: c.env,
+    }, { entityDid: source.companyEntityDid }).catch((err) => c.get("logger").warn("review-billing.resume-failed", { detail: String(err) }));
+    return c.json(await reviewBillingView({ db, config }, row, {
+        ownerDid: owner,
+        credits: await facilitator(c).balances(d.issuer),
+    }));
+});
+reviewBilling.get(PATH, access({ op: "getReviewBilling", scope: "none", capability: "spend/read" }), async (c) => {
+    const { source } = sourceOf(c);
+    const config = c.get("config");
+    const db = await c.var.db();
+    const row = await db.query.reviewBillingDelegations.findFirst({
+        where: eq(reviewBillingDelegations.sourceId, source.sourceId),
+    });
+    if (!row) {
+        throw new ApiError("NOT_FOUND", "This source holds no review-billing delegation. Set one up in the Decision Console.");
+    }
+    // A page to look at: an unreadable chain never fails it, it just cannot say `payer_not_owner`.
+    const ownerDid = await orgOwner(c, source.companyEntityDid).catch(() => null);
+    const credits = config.API_PAYMENTS && config.X402_FACILITATOR_URL
+        ? await facilitator(c).balances(row.payerDid)
+        : null;
+    return c.json(await reviewBillingView({ db, config }, row, { ownerDid, credits }));
+});
+reviewBilling.delete(PATH, access({ op: "deleteReviewBilling", scope: "none", capability: "keys/manage" }), idempotent(), async (c) => {
+    const { source } = sourceOf(c);
+    const db = await c.var.db();
+    const [row] = await db
+        .delete(reviewBillingDelegations)
+        .where(eq(reviewBillingDelegations.sourceId, source.sourceId))
+        .returning({ delegationCid: reviewBillingDelegations.delegationCid });
+    // Idempotent: none held is the answer asked for, audited only when one went.
+    if (row)
+        await audit(c, "source.review_billing_deleted", row.delegationCid);
+    return c.json({ deleted: row !== undefined, message: DELETED_MESSAGE });
+});
+//# sourceMappingURL=review-billing.js.map

package/dist/routes/v1/api/review-billing.js.map

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

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

@@ -0,0 +1,30 @@
+/**
+ * A claim's review, its erasure and its report (go-prod spec §3.4, §4.2, §6.3, §10). The review and
+ * erase routes find the claim through `claimOf` — another source's, one outside a member's
+ * `nb.protocols`, or a linked collection's chain claim (its body is not ours to show or erase) is
+ * `404`, never `403` (§14); the report, a read, through `readableClaimOf`.
+ *
+ * `GET …/review` is the ONLY read that returns a claim's answers (§3.4 `claims/review`), and only
+ * while the claim awaits review: every successful read is a `claim.review_viewed` audit row, and
+ * neither the answers nor the file URLs ever go in a log line or an audit `details`. The POST's
+ * checks are `answerApiReview`'s (lib/api-lane/review.ts), which answers refusals as values; this
+ * file only puts them in the envelope. The report is the engine's, proxied under the oracle's UCAN.
+ */
+import { Hono } from "hono";
+import { type ReviewBlock } from "../../../contracts/index.js";
+import type { ApiContext, ApiEnv, SourceCaller } from "../../../middleware/api/types.js";
+export declare const review: Hono<ApiEnv, import("hono/types").BlankSchema, "/">;
+/**
+ * Why `caller` can answer no review on its source (`ReviewBlock`), or null — the console's hint on
+ * the review read and `/me`, so it disables the form instead of meeting a 403. Only the cheap and
+ * certain cases: the answer itself runs every check (`answerApiReview`) whatever this said. A key
+ * signs nothing (it may relay a member's signed answer); an AI app needs `claims:write` too. The
+ * protocol limit needs no check here: the review read already 404s a claim outside it.
+ */
+export declare function reviewBlockOf(c: ApiContext, caller: SourceCaller): Promise<ReviewBlock | null>;
+/**
+ * The claim's report as the caller's `Accept` asks — JSON, or a self-contained HTML page. Shared
+ * with the operator view (admin-claims.ts); the caller has already proved it may see the claim.
+ */
+export declare function reportResponse(c: ApiContext, claimId: string): Promise<Response>;
+//# sourceMappingURL=review.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"review.d.ts","sourceRoot":"","sources":["../../../../src/routes/v1/api/review.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAGH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAE5B,OAAO,EAGL,KAAK,WAAW,EAGjB,MAAM,oBAAoB,CAAC;AAoB5B,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,+BAA+B,CAAC;AAItF,eAAO,MAAM,MAAM,qDAAqB,CAAC;AAyKzC;;;;;;GAMG;AACH,wBAAsB,aAAa,CACjC,CAAC,EAAE,UAAU,EACb,MAAM,EAAE,YAAY,GACnB,OAAO,CAAC,WAAW,GAAG,IAAI,CAAC,CAO7B;AA4ED;;;GAGG;AACH,wBAAsB,cAAc,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC,CA2BtF"}