create-safest-tools 0.2.0

package/template/src/evidence-service.ts

@@ -0,0 +1,335 @@
+import { canonicalJson } from "./audit";
+import { ConnectionExecutionError, executeConnectionJson } from "./connection-egress";
+import { sha256 } from "./report-crypto";
+import { ApiError } from "./report-http";
+import type { EvidenceFetchJob, OperatorSession } from "./report-types";
+import { BudgetControlError, reserveBudgets, settleBudgets } from "./budget-control";
+
+interface FetchRequestRow {
+  id: string;
+  installationId: string;
+  reportId: string;
+  evidenceReferenceId: string;
+  connectionVersionId: string;
+  requestedFieldsJson: string;
+  state: string;
+  operationId: string;
+  attemptCount: number;
+  requestMethod: string;
+  requestPath: string;
+  reference: string;
+  queueId: string | null;
+}
+
+export class RetryableEvidenceError extends Error {
+  constructor(readonly delaySeconds: number) { super("evidence_fetch_retryable"); this.name = "RetryableEvidenceError"; }
+}
+
+function now(): string { return new Date().toISOString(); }
+
+function fields(value: unknown): string[] {
+  if (!Array.isArray(value) || value.length < 1 || value.length > 50) throw new ApiError(400, "evidence_fields_invalid", "requested_fields must contain 1 to 50 fields.");
+  const result = value.map((entry) => typeof entry === "string" ? entry.trim() : "");
+  if (result.some((entry) => !/^[A-Za-z][A-Za-z0-9_.-]{0,99}$/u.test(entry)) || new Set(result).size !== result.length) throw new ApiError(400, "evidence_fields_invalid", "requested_fields contains invalid or duplicate entries.");
+  return result;
+}
+
+function method(value: unknown): string {
+  const result = typeof value === "string" ? value.toUpperCase() : "POST";
+  if (!["GET", "POST"].includes(result)) throw new ApiError(400, "evidence_method_invalid", "Evidence fetches support GET or POST.");
+  return result;
+}
+
+function path(value: unknown): string {
+  if (typeof value !== "string" || !value.startsWith("/") || value.length > 2_048 || value.includes("..") || value.includes("?") || value.includes("#")) throw new ApiError(400, "evidence_path_invalid", "request_path must be a safe absolute path.");
+  return value;
+}
+
+export async function listReportEvidence(db: D1Database, reportId: string): Promise<Record<string, unknown>> {
+  const [references, snapshots, requests] = await Promise.all([
+    db.prepare(`SELECT id, evidence_kind AS kind, reference, availability, retention_class AS retentionClass, created_at AS createdAt FROM evidence_references WHERE report_id = ?1 ORDER BY created_at, id`).bind(reportId).all<Record<string, unknown>>(),
+    db.prepare(`SELECT id, evidence_reference_id AS evidenceReferenceId, content_type AS contentType, size_bytes AS sizeBytes, digest, retention_class AS retentionClass, source_observed_at AS sourceObservedAt, created_at AS createdAt, deleted_at AS deletedAt FROM evidence_snapshots WHERE report_id = ?1 ORDER BY created_at DESC, id DESC`).bind(reportId).all<Record<string, unknown>>(),
+    db.prepare(`SELECT id, evidence_reference_id AS evidenceReferenceId, connection_version_id AS connectionVersionId, requested_fields_json AS requestedFieldsJson, state, attempt_count AS attemptCount, last_error_code AS lastErrorCode, created_at AS createdAt, updated_at AS updatedAt FROM evidence_fetch_requests WHERE report_id = ?1 ORDER BY created_at DESC, id DESC`).bind(reportId).all<Record<string, unknown>>(),
+  ]);
+  return {
+    references: references.results,
+    snapshots: snapshots.results,
+    fetchRequests: requests.results.map((row) => ({ ...row, requestedFields: JSON.parse(String(row.requestedFieldsJson ?? "[]")) as unknown, requestedFieldsJson: undefined })),
+  };
+}
+
+export async function requestEvidenceFetch(
+  db: D1Database,
+  reportId: string,
+  value: Record<string, unknown>,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ requestId: string; job: EvidenceFetchJob; idempotentReplay: boolean }> {
+  const evidenceReferenceId = typeof value.evidence_reference_id === "string" ? value.evidence_reference_id : "";
+  const connectionVersionId = typeof value.connection_version_id === "string" ? value.connection_version_id : "";
+  if (!evidenceReferenceId || !connectionVersionId) throw new ApiError(400, "evidence_fetch_invalid", "evidence_reference_id and connection_version_id are required.");
+  const requestedFields = fields(value.requested_fields);
+  const requestMethod = method(value.method);
+  const requestPath = path(value.request_path);
+  const freshness = value.freshness_requirement_seconds === null || value.freshness_requirement_seconds === undefined
+    ? null : Number(value.freshness_requirement_seconds);
+  if (freshness !== null && (!Number.isInteger(freshness) || freshness < 0 || freshness > 31_536_000)) throw new ApiError(400, "evidence_freshness_invalid", "freshness_requirement_seconds is invalid.");
+  const operationId = `evidence-fetch:${idempotencyKey}`;
+  const existing = await db.prepare(`SELECT id FROM evidence_fetch_requests WHERE operation_id = ?1 LIMIT 1`).bind(operationId).first<{ id: string }>();
+  if (existing) return { requestId: existing.id, job: { version: 1, jobId: `evidence:${existing.id}`, type: "fetch_evidence", reportId, requestId: existing.id }, idempotentReplay: true };
+  const [reference, connection] = await Promise.all([
+    db.prepare(`SELECT id FROM evidence_references WHERE id = ?1 AND report_id = ?2 AND availability = 'available' LIMIT 1`).bind(evidenceReferenceId, reportId).first(),
+    db.prepare(`SELECT v.id FROM connection_versions v JOIN connection_definitions d ON d.id = v.connection_id WHERE v.id = ?1 AND v.retired_at IS NULL AND d.status = 'active' LIMIT 1`).bind(connectionVersionId).first(),
+  ]);
+  if (!reference) throw new ApiError(404, "evidence_reference_not_found", "The evidence reference is not available for this report.");
+  if (!connection) throw new ApiError(409, "evidence_connection_unavailable", "The evidence connection version is not active.");
+  const requestId = crypto.randomUUID();
+  const timestamp = now();
+  await db.batch([
+    db.prepare(`
+      INSERT INTO evidence_fetch_requests (
+        id, installation_id, report_id, evidence_reference_id,
+        connection_version_id, requested_fields_json, freshness_requirement_seconds,
+        state, operation_id, next_attempt_at, attempt_count,
+        request_method, request_path, created_at, updated_at
+      ) VALUES (?1, 'default', ?2, ?3, ?4, ?5, ?6, 'pending', ?7, ?8, 0, ?9, ?10, ?8, ?8)
+    `).bind(requestId, reportId, evidenceReferenceId, connectionVersionId, canonicalJson(requestedFields), freshness, operationId, timestamp, requestMethod, requestPath),
+    db.prepare(`INSERT OR IGNORE INTO audit_events (id, idempotency_key, action, actor_type, actor_id, target_type, target_id, details_json, created_at) VALUES (?1, ?2, 'evidence.fetch_requested', ?3, ?4, 'evidence_fetch_request', ?5, ?6, ?7)`)
+      .bind(crypto.randomUUID(), `evidence-fetch:${idempotencyKey}`, session.actor.type, session.actor.id, requestId, canonicalJson({ reportId, evidenceReferenceId, connectionVersionId, requestedFields }), timestamp),
+  ]);
+  return { requestId, job: { version: 1, jobId: `evidence:${requestId}`, type: "fetch_evidence", reportId, requestId }, idempotentReplay: false };
+}
+
+function selectedData(value: Record<string, unknown>, requested: string[]): Record<string, unknown> {
+  const result: Record<string, unknown> = {};
+  for (const field of requested) {
+    let current: unknown = value;
+    for (const segment of field.split(".")) {
+      if (["__proto__", "prototype", "constructor"].includes(segment)
+        || !current || typeof current !== "object" || Array.isArray(current)
+        || !Object.prototype.hasOwnProperty.call(current, segment)) {
+        current = undefined;
+        break;
+      }
+      current = (current as Record<string, unknown>)[segment];
+    }
+    if (current !== undefined) result[field] = current;
+  }
+  return result;
+}
+
+export async function processEvidenceFetch(env: Env, job: EvidenceFetchJob): Promise<void> {
+  const claimed = await env.DB.prepare(`
+    UPDATE evidence_fetch_requests SET state = 'fetching', attempt_count = attempt_count + 1,
+      updated_at = ?2 WHERE id = ?1 AND state = 'pending' AND next_attempt_at <= ?2
+    RETURNING id
+  `).bind(job.requestId, now()).first();
+  const row = await env.DB.prepare(`
+    SELECT r.id, r.installation_id AS installationId, r.report_id AS reportId,
+      r.evidence_reference_id AS evidenceReferenceId,
+      r.connection_version_id AS connectionVersionId,
+      r.requested_fields_json AS requestedFieldsJson, r.state,
+      r.operation_id AS operationId, r.attempt_count AS attemptCount,
+      r.request_method AS requestMethod, r.request_path AS requestPath,
+      e.reference, report.queue_id AS queueId
+    FROM evidence_fetch_requests r JOIN evidence_references e ON e.id = r.evidence_reference_id
+    JOIN reports report ON report.id = r.report_id
+    WHERE r.id = ?1 AND r.report_id = ?2 LIMIT 1
+  `).bind(job.requestId, job.reportId).first<FetchRequestRow>();
+  if (!row) throw new ApiError(404, "evidence_fetch_not_found", "The evidence fetch request does not exist.");
+  if (!claimed) {
+    if (row.state === "available") return;
+    throw new RetryableEvidenceError(10);
+  }
+  const requested = JSON.parse(row.requestedFieldsJson) as string[];
+  const startedAt = now();
+  let reservations;
+  try {
+    reservations = await reserveBudgets(env.DB, {
+      installationId: row.installationId,
+      scopes: [
+        { type: "connection", id: row.connectionVersionId },
+        ...(row.queueId ? [{ type: "queue", id: row.queueId }] : []),
+      ],
+      metric: "evidence_fetches", amount: 1, operationType: "evidence_fetch",
+      operationId: row.operationId, attemptId: String(row.attemptCount),
+    });
+  } catch (error) {
+    if (!(error instanceof BudgetControlError)) throw error;
+    const timestamp = now();
+    await env.DB.prepare(`UPDATE evidence_fetch_requests SET state = ?2, next_attempt_at = ?3, last_error_code = ?4, updated_at = ?5 WHERE id = ?1`)
+      .bind(row.id, error.retryable ? "pending" : "failed", new Date(Date.now() + Math.max(1, error.delaySeconds) * 1_000).toISOString(), error.code, timestamp).run();
+    if (error.retryable) throw new RetryableEvidenceError(error.delaySeconds);
+    return;
+  }
+  try {
+    const result = await executeConnectionJson(env, {
+      connectionVersionId: row.connectionVersionId,
+      operationId: row.operationId,
+      attemptNumber: row.attemptCount,
+      method: row.requestMethod,
+      path: row.requestPath,
+      body: {
+        schema_version: "1", operation_id: row.operationId,
+        evidence_reference: row.reference, requested_fields: requested,
+      },
+      headers: { "x-safest-purpose": "controlled-evidence-fetch" },
+    });
+    const data = selectedData(result.data, requested);
+    const body = canonicalJson({ schema_version: "1", data });
+    const digest = `sha256:${await sha256(body)}`;
+    const snapshotId = crypto.randomUUID();
+    const objectKey = `evidence/default/${row.reportId}/${row.id}/${digest.slice(7)}.json`;
+    await env.EVIDENCE_OBJECTS.put(objectKey, body, { httpMetadata: { contentType: "application/json" }, customMetadata: { digest, reportId: row.reportId, requestId: row.id } });
+    const finishedAt = now();
+    await env.DB.batch([
+      env.DB.prepare(`INSERT INTO evidence_fetch_attempts (id, request_id, attempt_number, request_digest, response_status, response_digest, response_class, started_at, finished_at) VALUES (?1, ?2, ?3, ?4, ?5, ?6, 'success', ?7, ?8)`)
+        .bind(crypto.randomUUID(), row.id, row.attemptCount, `sha256:${await sha256(canonicalJson({ reference: row.reference, requested }))}`, result.status, result.responseDigest, startedAt, finishedAt),
+      env.DB.prepare(`INSERT INTO evidence_snapshots (id, installation_id, report_id, evidence_reference_id, fetch_request_id, r2_object_key, content_type, size_bytes, digest, retention_class, access_policy_json, created_by_type, created_by_id, created_at) VALUES (?1, ?2, ?3, ?4, ?5, ?6, 'application/json', ?7, ?8, 'evidence', ?9, 'system', 'evidence-fetcher', ?10)`)
+        .bind(snapshotId, row.installationId, row.reportId, row.evidenceReferenceId, row.id, objectKey, new TextEncoder().encode(body).byteLength, digest, canonicalJson({ permission: "readSensitiveEvidence", fields: requested }), finishedAt),
+      env.DB.prepare(`UPDATE evidence_fetch_requests SET state = 'available', last_error_code = NULL, updated_at = ?2 WHERE id = ?1`).bind(row.id, finishedAt),
+      env.DB.prepare(`INSERT OR IGNORE INTO audit_events (id, idempotency_key, action, actor_type, actor_id, target_type, target_id, details_json, created_at) VALUES (?1, ?2, 'evidence.fetch_succeeded', 'system', 'evidence-fetcher', 'evidence_snapshot', ?3, ?4, ?5)`)
+        .bind(crypto.randomUUID(), `evidence-fetch-succeeded:${row.id}`, snapshotId, canonicalJson({ reportId: row.reportId, digest, fields: requested }), finishedAt),
+    ]);
+    await settleBudgets(env.DB, reservations, true);
+  } catch (error) {
+    const failure = error instanceof ConnectionExecutionError ? error : new ConnectionExecutionError("evidence_storage_error", true, 15);
+    const finishedAt = now();
+    const retryAt = new Date(Date.now() + failure.delaySeconds * 1_000).toISOString();
+    await env.DB.batch([
+      env.DB.prepare(`INSERT OR IGNORE INTO evidence_fetch_attempts (id, request_id, attempt_number, request_digest, response_class, error_code, started_at, finished_at) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)`)
+        .bind(crypto.randomUUID(), row.id, row.attemptCount, `sha256:${await sha256(canonicalJson({ reference: row.reference, requested }))}`, failure.retryable ? "retryable" : "permanent", failure.code, startedAt, finishedAt),
+      env.DB.prepare(`UPDATE evidence_fetch_requests SET state = ?2, next_attempt_at = ?3, last_error_code = ?4, updated_at = ?5 WHERE id = ?1`)
+        .bind(row.id, failure.retryable ? "pending" : "failed", retryAt, failure.code, finishedAt),
+    ]);
+    await settleBudgets(env.DB, reservations, true);
+    if (failure.retryable) throw new RetryableEvidenceError(failure.delaySeconds);
+  }
+}
+
+export async function pendingEvidenceFetchJobs(db: D1Database, limit = 50): Promise<EvidenceFetchJob[]> {
+  const result = await db.prepare(`SELECT id, report_id AS reportId FROM evidence_fetch_requests WHERE state = 'pending' AND next_attempt_at <= ?1 ORDER BY next_attempt_at, id LIMIT ?2`)
+    .bind(now(), Math.max(1, Math.min(100, limit))).all<{ id: string; reportId: string }>();
+  return result.results.map((row) => ({ version: 1, jobId: `evidence:${row.id}`, type: "fetch_evidence", reportId: row.reportId, requestId: row.id }));
+}
+
+export async function acceptEvidenceResponse(
+  env: Env,
+  value: Record<string, unknown>,
+  integrationId: string,
+): Promise<{ requestId: string; snapshotId: string | null; state: string; idempotentReplay: boolean }> {
+  const requestId = typeof value.request_id === "string" ? value.request_id : "";
+  const operationId = typeof value.operation_id === "string" ? value.operation_id : "";
+  const status = value.status;
+  if (!requestId || requestId.length > 100 || !operationId || operationId.length > 300) {
+    throw new ApiError(400, "evidence_response_invalid", "request_id and operation_id are required.");
+  }
+  if (status !== "available" && status !== "unavailable" && status !== "failed") {
+    throw new ApiError(400, "evidence_response_invalid", "status must be available, unavailable, or failed.");
+  }
+  const row = await env.DB.prepare(`
+    SELECT r.id, r.installation_id AS installationId, r.report_id AS reportId,
+      r.evidence_reference_id AS evidenceReferenceId, r.requested_fields_json AS requestedFieldsJson,
+      r.state, r.operation_id AS operationId, r.attempt_count AS attemptCount,
+      s.id AS snapshotId
+    FROM evidence_fetch_requests r LEFT JOIN evidence_snapshots s ON s.fetch_request_id = r.id AND s.deleted_at IS NULL
+    WHERE r.id = ?1 LIMIT 1
+  `).bind(requestId).first<{
+    id: string; installationId: string; reportId: string; evidenceReferenceId: string;
+    requestedFieldsJson: string; state: string; operationId: string; attemptCount: number; snapshotId: string | null;
+  }>();
+  if (!row || row.operationId !== operationId) throw new ApiError(404, "evidence_fetch_not_found", "The evidence fetch request does not exist.");
+  if (row.state === "available" && row.snapshotId) return { requestId, snapshotId: row.snapshotId, state: "available", idempotentReplay: true };
+  if ((row.state === "unavailable" || row.state === "failed") && row.state === status) {
+    return { requestId, snapshotId: null, state: row.state, idempotentReplay: true };
+  }
+  if (!["pending", "fetching", "failed"].includes(row.state)) throw new ApiError(409, "evidence_response_terminal", "The evidence request is already terminal.");
+  const timestamp = now();
+  if (status !== "available") {
+    const errorCode = typeof value.error_code === "string" && value.error_code.length <= 200
+      ? value.error_code : status === "unavailable" ? "evidence_unavailable" : "evidence_callback_failed";
+    await env.DB.batch([
+      env.DB.prepare(`UPDATE evidence_fetch_requests SET state = ?2, last_error_code = ?3, updated_at = ?4 WHERE id = ?1`)
+        .bind(requestId, status, errorCode, timestamp),
+      env.DB.prepare(`INSERT OR IGNORE INTO audit_events (id, idempotency_key, action, actor_type, actor_id, target_type, target_id, details_json, created_at) VALUES (?1, ?2, 'evidence.callback_received', 'service_identity', ?3, 'evidence_fetch_request', ?4, ?5, ?6)`)
+        .bind(crypto.randomUUID(), `evidence-callback:${operationId}`, integrationId, requestId, canonicalJson({ status, errorCode }), timestamp),
+    ]);
+    return { requestId, snapshotId: null, state: status, idempotentReplay: false };
+  }
+  if (!value.data || typeof value.data !== "object" || Array.isArray(value.data)) {
+    throw new ApiError(400, "evidence_response_data_required", "data must be an object for an available response.");
+  }
+  const requested = JSON.parse(row.requestedFieldsJson) as string[];
+  const data = selectedData(value.data as Record<string, unknown>, requested);
+  const body = canonicalJson({ schema_version: "1", data });
+  const bytes = new TextEncoder().encode(body);
+  if (bytes.byteLength > 1_048_576) throw new ApiError(413, "evidence_response_too_large", "The evidence response exceeds one MiB.");
+  const digest = `sha256:${await sha256(body)}`;
+  const snapshotId = crypto.randomUUID();
+  const objectKey = `evidence/${row.installationId}/${row.reportId}/${row.id}/${digest.slice(7)}.json`;
+  await env.EVIDENCE_OBJECTS.put(objectKey, body, {
+    httpMetadata: { contentType: "application/json" },
+    customMetadata: { digest, reportId: row.reportId, requestId: row.id },
+  });
+  try {
+    await env.DB.batch([
+      env.DB.prepare(`INSERT INTO evidence_snapshots (id, installation_id, report_id, evidence_reference_id, fetch_request_id, r2_object_key, content_type, size_bytes, digest, retention_class, access_policy_json, created_by_type, created_by_id, created_at) VALUES (?1, ?2, ?3, ?4, ?5, ?6, 'application/json', ?7, ?8, 'evidence', ?9, 'service_identity', ?10, ?11)`)
+        .bind(snapshotId, row.installationId, row.reportId, row.evidenceReferenceId, row.id, objectKey, bytes.byteLength, digest, canonicalJson({ permission: "readSensitiveEvidence", fields: requested }), integrationId, timestamp),
+      env.DB.prepare(`UPDATE evidence_fetch_requests SET state = 'available', last_error_code = NULL, updated_at = ?2 WHERE id = ?1`).bind(requestId, timestamp),
+      env.DB.prepare(`INSERT OR IGNORE INTO audit_events (id, idempotency_key, action, actor_type, actor_id, target_type, target_id, details_json, created_at) VALUES (?1, ?2, 'evidence.callback_received', 'service_identity', ?3, 'evidence_snapshot', ?4, ?5, ?6)`)
+        .bind(crypto.randomUUID(), `evidence-callback:${operationId}`, integrationId, snapshotId, canonicalJson({ requestId, reportId: row.reportId, digest, fields: requested }), timestamp),
+    ]);
+  } catch (error) {
+    await env.EVIDENCE_OBJECTS.delete(objectKey);
+    throw error;
+  }
+  return { requestId, snapshotId, state: "available", idempotentReplay: false };
+}
+
+export async function createEvidenceSnapshot(
+  env: Env,
+  reportId: string,
+  value: Record<string, unknown>,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ snapshotId: string; digest: string; idempotentReplay: boolean }> {
+  const referenceId = typeof value.evidence_reference_id === "string" ? value.evidence_reference_id : "";
+  const existing = await env.DB.prepare(`SELECT target_id AS snapshotId, details_json AS detailsJson FROM audit_events WHERE idempotency_key = ?1 AND action = 'evidence.snapshot_created' LIMIT 1`)
+    .bind(`evidence-snapshot:${idempotencyKey}`).first<{ snapshotId: string; detailsJson: string }>();
+  if (existing) return { snapshotId: existing.snapshotId, digest: String((JSON.parse(existing.detailsJson) as Record<string, unknown>).digest), idempotentReplay: true };
+  const reference = await env.DB.prepare(`SELECT id FROM evidence_references WHERE id = ?1 AND report_id = ?2 LIMIT 1`).bind(referenceId, reportId).first();
+  if (!reference) throw new ApiError(404, "evidence_reference_not_found", "The evidence reference does not belong to this report.");
+  const data = value.data;
+  if (data === undefined) throw new ApiError(400, "evidence_snapshot_data_required", "data is required.");
+  const body = canonicalJson({ schema_version: "1", data });
+  if (new TextEncoder().encode(body).byteLength > 1_048_576) throw new ApiError(413, "evidence_snapshot_too_large", "Evidence snapshots are limited to 1 MiB through this endpoint.");
+  const digest = `sha256:${await sha256(body)}`;
+  const snapshotId = crypto.randomUUID();
+  const objectKey = `evidence/default/${reportId}/manual/${snapshotId}.json`;
+  const timestamp = now();
+  await env.EVIDENCE_OBJECTS.put(objectKey, body, { httpMetadata: { contentType: "application/json" }, customMetadata: { digest, reportId } });
+  try {
+    await env.DB.batch([
+      env.DB.prepare(`INSERT INTO evidence_snapshots (id, installation_id, report_id, evidence_reference_id, r2_object_key, content_type, size_bytes, digest, retention_class, access_policy_json, source_observed_at, created_by_type, created_by_id, created_at) VALUES (?1, 'default', ?2, ?3, ?4, 'application/json', ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12)`)
+        .bind(snapshotId, reportId, referenceId, objectKey, new TextEncoder().encode(body).byteLength, digest, typeof value.retention_class === "string" ? value.retention_class.slice(0, 100) : "evidence", canonicalJson({ permission: "readSensitiveEvidence" }), typeof value.source_observed_at === "string" ? value.source_observed_at : null, session.actor.type, session.actor.id, timestamp),
+      env.DB.prepare(`INSERT INTO audit_events (id, idempotency_key, action, actor_type, actor_id, target_type, target_id, details_json, created_at) VALUES (?1, ?2, 'evidence.snapshot_created', ?3, ?4, 'evidence_snapshot', ?5, ?6, ?7)`)
+        .bind(crypto.randomUUID(), `evidence-snapshot:${idempotencyKey}`, session.actor.type, session.actor.id, snapshotId, canonicalJson({ reportId, digest, referenceId }), timestamp),
+    ]);
+  } catch (error) {
+    await env.EVIDENCE_OBJECTS.delete(objectKey);
+    throw error;
+  }
+  return { snapshotId, digest, idempotentReplay: false };
+}
+
+export async function readEvidenceContent(env: Env, snapshotId: string, session: OperatorSession, requestId: string): Promise<Response> {
+  const snapshot = await env.DB.prepare(`SELECT id, report_id AS reportId, evidence_reference_id AS evidenceReferenceId, r2_object_key AS objectKey, content_type AS contentType, digest, deleted_at AS deletedAt FROM evidence_snapshots WHERE id = ?1 LIMIT 1`)
+    .bind(snapshotId).first<{ id: string; reportId: string; evidenceReferenceId: string | null; objectKey: string; contentType: string; digest: string; deletedAt: string | null }>();
+  if (!snapshot || snapshot.deletedAt) throw new ApiError(404, "evidence_snapshot_not_found", "The evidence snapshot is unavailable.");
+  const object = await env.EVIDENCE_OBJECTS.get(snapshot.objectKey);
+  if (!object) throw new ApiError(503, "evidence_object_missing", "The evidence object is temporarily unavailable.");
+  const timestamp = now();
+  await env.DB.prepare(`INSERT INTO evidence_access_events (id, installation_id, report_id, evidence_reference_id, snapshot_id, actor_type, actor_id, purpose_code, request_id, accessed_at) VALUES (?1, 'default', ?2, ?3, ?4, ?5, ?6, 'operator_review', ?7, ?8)`)
+    .bind(crypto.randomUUID(), snapshot.reportId, snapshot.evidenceReferenceId, snapshot.id, session.actor.type, session.actor.id, requestId, timestamp).run();
+  return new Response(object.body, { headers: { "content-type": snapshot.contentType, "etag": `"${snapshot.digest}"`, "cache-control": "private, no-store", "x-content-type-options": "nosniff" } });
+}

package/template/src/human-tasks.ts

@@ -0,0 +1,316 @@
+import { canonicalJson } from "./audit";
+import { sha256 } from "./report-crypto";
+import { ApiError } from "./report-http";
+import { assertOperatorQueueAccess } from "./report-auth";
+import type { OperatorSession } from "./report-types";
+import { validateJsonSchemaValue } from "./workflow-expressions";
+import type { JsonObject, JsonValue } from "./workflow-platform-types";
+import { sendWorkflowEvent } from "./workflow-runs";
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function jsonObject(value: unknown): JsonObject {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new ApiError(400, "human_task_response_invalid", "response must be an object.");
+  try {
+    return JSON.parse(canonicalJson(value)) as JsonObject;
+  } catch {
+    throw new ApiError(400, "human_task_response_invalid", "response must contain bounded JSON data.");
+  }
+}
+
+function parsedObject(value: string): JsonObject {
+  try {
+    return jsonObject(JSON.parse(value));
+  } catch {
+    return {};
+  }
+}
+
+export async function listHumanTasks(
+  db: D1Database,
+  input: { state?: string; queueId?: string; operatorId?: string; allowedQueueIds?: string[] | null; limit: number },
+): Promise<Record<string, unknown>[]> {
+  const timestamp = now();
+  await db.batch([
+    db.prepare(`
+      UPDATE human_task_claims SET released_at = ?1, release_reason = 'claim_expired'
+      WHERE released_at IS NULL AND expires_at <= ?1
+    `).bind(timestamp),
+    db.prepare(`
+      UPDATE human_tasks SET state = 'open', assigned_operator_id = NULL, updated_at = ?1
+      WHERE state = 'claimed' AND NOT EXISTS (
+        SELECT 1 FROM human_task_claims c WHERE c.task_id = human_tasks.id
+          AND c.released_at IS NULL AND c.expires_at > ?1
+      )
+    `).bind(timestamp),
+  ]);
+  const rows = await db.prepare(`
+    SELECT t.id, t.report_id AS reportId, t.appeal_id AS appealId,
+      t.run_id AS runId, t.step_run_id AS stepRunId, t.task_type AS taskType,
+      t.state, t.queue_id AS queueId, t.assigned_operator_id AS assignedOperatorId,
+      t.context_json AS contextJson, t.response_schema_json AS responseSchemaJson,
+      t.action_proposal_id AS actionProposalId, t.due_at AS dueAt,
+      t.escalation_at AS escalationAt, t.created_at AS createdAt,
+      t.updated_at AS updatedAt, c.id AS claimId, c.expires_at AS claimExpiresAt
+    FROM human_tasks t LEFT JOIN human_task_claims c
+      ON c.task_id = t.id AND c.released_at IS NULL AND c.expires_at > ?1
+    WHERE (?2 IS NULL OR t.state = ?2) AND (?3 IS NULL OR t.queue_id = ?3)
+      AND (?4 IS NULL OR t.assigned_operator_id = ?4)
+      AND (?5 = 1 OR t.queue_id IN (SELECT value FROM json_each(?6)))
+    ORDER BY CASE WHEN t.due_at IS NULL THEN 1 ELSE 0 END, t.due_at, t.created_at, t.id
+    LIMIT ?7
+  `).bind(
+    timestamp, input.state ?? null, input.queueId ?? null, input.operatorId ?? null,
+    input.allowedQueueIds === null || input.allowedQueueIds === undefined ? 1 : 0,
+    canonicalJson(input.allowedQueueIds ?? []), Math.max(1, Math.min(input.limit, 100)),
+  ).all<Record<string, unknown>>();
+  return rows.results.map((row) => ({
+    ...row,
+    context: parsedObject(String(row.contextJson ?? "")),
+    responseSchema: parsedObject(String(row.responseSchemaJson ?? "")),
+    contextJson: undefined,
+    responseSchemaJson: undefined,
+  }));
+}
+
+export async function loadHumanTask(db: D1Database, taskId: string): Promise<Record<string, unknown> | null> {
+  const task = await db.prepare(`
+    SELECT t.id, t.report_id AS reportId, t.appeal_id AS appealId,
+      t.run_id AS runId, t.step_run_id AS stepRunId, t.task_type AS taskType,
+      t.state, t.queue_id AS queueId, t.assigned_operator_id AS assignedOperatorId,
+      t.context_json AS contextJson, t.response_schema_json AS responseSchemaJson,
+      t.action_proposal_id AS actionProposalId, t.due_at AS dueAt,
+      t.escalation_at AS escalationAt, t.created_at AS createdAt,
+      t.updated_at AS updatedAt, t.completed_at AS completedAt,
+      c.id AS claimId, c.operator_id AS claimOperatorId,
+      c.claimed_at AS claimedAt, c.expires_at AS claimExpiresAt
+    FROM human_tasks t LEFT JOIN human_task_claims c
+      ON c.task_id = t.id AND c.released_at IS NULL AND c.expires_at > ?2
+    WHERE t.id = ?1 LIMIT 1
+  `).bind(taskId, now()).first<Record<string, unknown>>();
+  if (!task) return null;
+  const responses = await db.prepare(`
+    SELECT id, operator_id AS operatorId, response_json AS responseJson,
+      response_digest AS responseDigest, submitted_at AS submittedAt
+    FROM human_task_responses WHERE task_id = ?1 ORDER BY submitted_at, id
+  `).bind(taskId).all<Record<string, unknown>>();
+  return {
+    ...task,
+    context: parsedObject(String(task.contextJson ?? "")),
+    responseSchema: parsedObject(String(task.responseSchemaJson ?? "")),
+    contextJson: undefined,
+    responseSchemaJson: undefined,
+    responses: responses.results.map((response) => ({
+      ...response,
+      response: parsedObject(String(response.responseJson ?? "")),
+      responseJson: undefined,
+    })),
+  };
+}
+
+export async function reassignHumanTask(
+  db: D1Database,
+  taskId: string,
+  queueId: string,
+  reason: string,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ taskId: string; queueId: string; state: string; idempotentReplay: boolean }> {
+  const auditKey = `human-task-reassign:${idempotencyKey}`;
+  const replay = await db.prepare(`SELECT target_id AS targetId FROM audit_events WHERE idempotency_key = ?1 LIMIT 1`)
+    .bind(auditKey).first<{ targetId: string }>();
+  if (replay) {
+    if (replay.targetId !== taskId) throw new ApiError(409, "idempotency_key_reused", "This Idempotency-Key was already used for another task.");
+    const task = await db.prepare(`SELECT queue_id AS queueId, state FROM human_tasks WHERE id = ?1 LIMIT 1`).bind(taskId).first<{ queueId: string; state: string }>();
+    if (!task) throw new ApiError(404, "human_task_not_found", "The task does not exist.");
+    return { taskId, queueId: task.queueId, state: task.state, idempotentReplay: true };
+  }
+  const [task, queue] = await Promise.all([
+    db.prepare(`SELECT state, queue_id AS queueId FROM human_tasks WHERE id = ?1 LIMIT 1`).bind(taskId).first<{ state: string; queueId: string | null }>(),
+    db.prepare(`SELECT id FROM queue_definitions WHERE id = ?1 AND status = 'active' LIMIT 1`).bind(queueId).first<{ id: string }>(),
+  ]);
+  if (!task) throw new ApiError(404, "human_task_not_found", "The task does not exist.");
+  if (!queue) throw new ApiError(409, "human_task_queue_unavailable", "The destination queue is not active.");
+  if (!["open", "claimed"].includes(task.state)) throw new ApiError(409, "human_task_not_reassignable", "Only an open or claimed task can be reassigned.");
+  const timestamp = now();
+  await db.batch([
+    db.prepare(`UPDATE human_task_claims SET released_at = ?2, release_reason = 'task_reassigned' WHERE task_id = ?1 AND released_at IS NULL`)
+      .bind(taskId, timestamp),
+    db.prepare(`UPDATE human_tasks SET state = 'open', queue_id = ?2, assigned_operator_id = NULL, updated_at = ?3 WHERE id = ?1`)
+      .bind(taskId, queueId, timestamp),
+    db.prepare(`
+      INSERT INTO audit_events (id, idempotency_key, action, actor_type, actor_id, target_type, target_id, details_json, created_at)
+      VALUES (?1, ?2, 'human_task.reassigned', ?3, ?4, 'human_task', ?5, ?6, ?7)
+    `).bind(crypto.randomUUID(), auditKey, session.actor.type, session.actor.id, taskId, canonicalJson({ previousQueueId: task.queueId, queueId, reason }), timestamp),
+  ]);
+  return { taskId, queueId, state: "open", idempotentReplay: false };
+}
+
+export async function cancelHumanTask(
+  db: D1Database,
+  taskId: string,
+  reason: string,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ taskId: string; runId: string; state: "cancelled"; idempotentReplay: boolean }> {
+  const auditKey = `human-task-cancel:${idempotencyKey}`;
+  const task = await db.prepare(`SELECT run_id AS runId, state FROM human_tasks WHERE id = ?1 LIMIT 1`)
+    .bind(taskId).first<{ runId: string; state: string }>();
+  if (!task) throw new ApiError(404, "human_task_not_found", "The task does not exist.");
+  const replay = await db.prepare(`SELECT target_id AS targetId FROM audit_events WHERE idempotency_key = ?1 LIMIT 1`)
+    .bind(auditKey).first<{ targetId: string }>();
+  if (replay) {
+    if (replay.targetId !== taskId) throw new ApiError(409, "idempotency_key_reused", "This Idempotency-Key was already used for another task.");
+    return { taskId, runId: task.runId, state: "cancelled", idempotentReplay: true };
+  }
+  if (!["open", "claimed"].includes(task.state)) throw new ApiError(409, "human_task_not_cancellable", "Only an open or claimed task can be cancelled.");
+  const timestamp = now();
+  await db.batch([
+    db.prepare(`UPDATE human_task_claims SET released_at = ?2, release_reason = 'task_cancelled' WHERE task_id = ?1 AND released_at IS NULL`)
+      .bind(taskId, timestamp),
+    db.prepare(`UPDATE human_tasks SET state = 'cancelled', assigned_operator_id = NULL, updated_at = ?2 WHERE id = ?1`)
+      .bind(taskId, timestamp),
+    db.prepare(`
+      INSERT INTO audit_events (id, idempotency_key, action, actor_type, actor_id, target_type, target_id, details_json, created_at)
+      VALUES (?1, ?2, 'human_task.cancelled', ?3, ?4, 'human_task', ?5, ?6, ?7)
+    `).bind(crypto.randomUUID(), auditKey, session.actor.type, session.actor.id, taskId, canonicalJson({ reason, runId: task.runId }), timestamp),
+  ]);
+  return { taskId, runId: task.runId, state: "cancelled", idempotentReplay: false };
+}
+
+export async function claimHumanTask(
+  db: D1Database,
+  taskId: string,
+  session: OperatorSession,
+  ttlMinutes: number,
+): Promise<{ claimId: string; expiresAt: string }> {
+  const timestamp = now();
+  const expiresAt = new Date(Date.now() + Math.max(1, Math.min(ttlMinutes, 1_440)) * 60_000).toISOString();
+  await db.prepare(`
+    UPDATE human_task_claims SET released_at = ?2, release_reason = 'claim_expired'
+    WHERE task_id = ?1 AND released_at IS NULL AND expires_at <= ?2
+  `).bind(taskId, timestamp).run();
+  const task = await db.prepare(`SELECT state, queue_id AS queueId FROM human_tasks WHERE id = ?1 LIMIT 1`).bind(taskId).first<{ state: string; queueId: string | null }>();
+  if (!task) throw new ApiError(404, "human_task_not_found", "The task does not exist.");
+  assertOperatorQueueAccess(session, task.queueId);
+  if (!['open', 'claimed'].includes(task.state)) throw new ApiError(409, "human_task_not_claimable", "The task is not open for claiming.");
+  const active = await db.prepare(`SELECT id, operator_id AS operatorId, expires_at AS expiresAt FROM human_task_claims WHERE task_id = ?1 AND released_at IS NULL LIMIT 1`)
+    .bind(taskId).first<{ id: string; operatorId: string; expiresAt: string }>();
+  if (active) {
+    if (active.operatorId === session.actor.id) return { claimId: active.id, expiresAt: active.expiresAt };
+    throw new ApiError(409, "human_task_already_claimed", "The task is already claimed by another operator.");
+  }
+  const claimId = crypto.randomUUID();
+  await db.batch([
+    db.prepare(`INSERT INTO human_task_claims (id, task_id, operator_id, claimed_at, expires_at) VALUES (?1, ?2, ?3, ?4, ?5)`)
+      .bind(claimId, taskId, session.actor.id, timestamp, expiresAt),
+    db.prepare(`UPDATE human_tasks SET state = 'claimed', assigned_operator_id = ?2, updated_at = ?3 WHERE id = ?1 AND state IN ('open','claimed')`)
+      .bind(taskId, session.actor.id, timestamp),
+  ]);
+  return { claimId, expiresAt };
+}
+
+export async function releaseHumanTaskClaim(
+  db: D1Database,
+  taskId: string,
+  session: OperatorSession,
+): Promise<void> {
+  const timestamp = now();
+  const released = await db.prepare(`
+    UPDATE human_task_claims SET released_at = ?3, release_reason = 'operator_released'
+    WHERE task_id = ?1 AND operator_id = ?2 AND released_at IS NULL
+  `).bind(taskId, session.actor.id, timestamp).run();
+  if (released.meta.changes !== 1) throw new ApiError(409, "human_task_claim_missing", "You do not hold the active claim for this task.");
+  await db.prepare(`UPDATE human_tasks SET state = 'open', assigned_operator_id = NULL, updated_at = ?2 WHERE id = ?1 AND state = 'claimed'`)
+    .bind(taskId, timestamp).run();
+}
+
+export async function respondToHumanTask(
+  env: Env,
+  taskId: string,
+  responseValue: unknown,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ responseId: string; eventId: string; eventDelivered: boolean; idempotentReplay: boolean }> {
+  const existing = await env.DB.prepare(`
+    SELECT r.id, t.run_id AS runId, t.action_proposal_id AS actionProposalId FROM human_task_responses r
+    JOIN human_tasks t ON t.id = r.task_id
+    WHERE r.operator_id = ?1 AND r.idempotency_key = ?2 LIMIT 1
+  `).bind(session.actor.id, idempotencyKey).first<{ id: string; runId: string; actionProposalId: string | null }>();
+  if (existing) {
+    const event = await sendWorkflowEvent(env, existing.runId, {
+      eventType: existing.actionProposalId ? `action.${existing.actionProposalId}.resolved` : `task.${taskId}.completed`, eventKey: `task-response:${existing.id}`,
+      sourceType: "operator", sourceId: session.actor.id, payload: { task_id: taskId, response_id: existing.id },
+    });
+    return { responseId: existing.id, eventId: event.eventId, eventDelivered: event.delivered, idempotentReplay: true };
+  }
+  const timestamp = now();
+  const task = await env.DB.prepare(`
+    SELECT t.run_id AS runId, t.state, t.queue_id AS queueId, t.response_schema_json AS responseSchemaJson,
+      t.action_proposal_id AS actionProposalId, p.payload_digest AS actionPayloadDigest,
+      p.state AS actionState, c.id AS claimId, c.operator_id AS operatorId,
+      c.expires_at AS expiresAt
+    FROM human_tasks t LEFT JOIN human_task_claims c ON c.task_id = t.id AND c.released_at IS NULL
+    LEFT JOIN action_proposals p ON p.id = t.action_proposal_id
+    WHERE t.id = ?1 LIMIT 1
+  `).bind(taskId).first<{
+    runId: string; state: string; responseSchemaJson: string; actionProposalId: string | null;
+    actionPayloadDigest: string | null; actionState: string | null; claimId: string | null;
+    operatorId: string | null; expiresAt: string | null; queueId: string | null;
+  }>();
+  if (!task) throw new ApiError(404, "human_task_not_found", "The task does not exist.");
+  assertOperatorQueueAccess(session, task.queueId);
+  if (task.state !== "claimed" || task.operatorId !== session.actor.id || !task.claimId || !task.expiresAt || task.expiresAt <= timestamp) {
+    throw new ApiError(409, "human_task_claim_required", "A current claim held by this operator is required.");
+  }
+  const response = jsonObject(responseValue);
+  const errors = validateJsonSchemaValue(response as JsonValue, parsedObject(task.responseSchemaJson));
+  if (errors.length) throw new ApiError(422, "human_task_response_schema_invalid", "The task response does not match its published schema.", { errors });
+  const responseJson = canonicalJson(response);
+  const responseId = crypto.randomUUID();
+  const statements: D1PreparedStatement[] = [
+    env.DB.prepare(`
+      INSERT INTO human_task_responses (
+        id, task_id, claim_id, operator_id, response_json, response_digest,
+        idempotency_key, submitted_at
+      ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)
+    `).bind(responseId, taskId, task.claimId, session.actor.id, responseJson, `sha256:${await sha256(responseJson)}`, idempotencyKey, timestamp),
+    env.DB.prepare(`UPDATE human_task_claims SET released_at = ?2, release_reason = 'task_completed' WHERE id = ?1 AND released_at IS NULL`)
+      .bind(task.claimId, timestamp),
+    env.DB.prepare(`UPDATE human_tasks SET state = 'completed', completed_at = ?2, updated_at = ?2 WHERE id = ?1 AND state = 'claimed'`)
+      .bind(taskId, timestamp),
+  ];
+  if (task.actionProposalId) {
+    if (!session.permissions.approveActions) throw new ApiError(403, "action_approval_permission_denied", "Your role cannot approve or reject actions.");
+    const decision = response.decision;
+    if ((decision !== "approved" && decision !== "rejected") || !task.actionPayloadDigest || task.actionState !== "approval_required") {
+      throw new ApiError(409, "action_approval_invalid", "The linked action proposal is not awaiting this exact approval.");
+    }
+    statements.push(
+      env.DB.prepare(`
+        INSERT INTO action_approvals (
+          id, proposal_id, task_id, approver_id, payload_digest,
+          decision, reason, idempotency_key, created_at
+        ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9)
+      `).bind(
+        crypto.randomUUID(), task.actionProposalId, taskId, session.actor.id,
+        task.actionPayloadDigest, decision,
+        typeof response.reason === "string" ? response.reason : null,
+        idempotencyKey, timestamp,
+      ),
+      env.DB.prepare(`
+        UPDATE action_proposals SET state = ?2, updated_at = ?3
+        WHERE id = ?1 AND state = 'approval_required'
+      `).bind(task.actionProposalId, decision, timestamp),
+    );
+  }
+  await env.DB.batch(statements);
+  const event = await sendWorkflowEvent(env, task.runId, {
+    eventType: task.actionProposalId ? `action.${task.actionProposalId}.resolved` : `task.${taskId}.completed`, eventKey: `task-response:${responseId}`,
+    sourceType: "operator", sourceId: session.actor.id,
+    payload: { task_id: taskId, response_id: responseId, response },
+  });
+  return { responseId, eventId: event.eventId, eventDelivered: event.delivered, idempotentReplay: false };
+}