create-safest-tools 0.2.0

package/template/src/report-governance.ts

@@ -0,0 +1,510 @@
+import { AUDIT_GENESIS_HASH, canonicalJson, hashAuditEntry } from "./audit";
+import { ApiError } from "./report-http";
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function subtractDays(timestamp: string, days: number): string {
+  return new Date(Date.parse(timestamp) - days * 86_400_000).toISOString();
+}
+
+function auditEvent(
+  db: D1Database,
+  input: { key: string; action: string; actorType: string; actorId: string; targetType: string; targetId: string; details: unknown; createdAt: string },
+): D1PreparedStatement {
+  return 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, ?3, ?4, ?5, ?6, ?7, ?8, ?9)
+  `).bind(
+    crypto.randomUUID(), input.key, input.action, input.actorType, input.actorId,
+    input.targetType, input.targetId, canonicalJson(input.details), input.createdAt,
+  );
+}
+
+export async function refreshDailyAggregates(db: D1Database, lookbackDays = 90): Promise<void> {
+  const refreshedAt = now();
+  const fromDate = subtractDays(refreshedAt, Math.max(1, Math.min(366, lookbackDays))).slice(0, 10);
+  const statements: D1PreparedStatement[] = [
+    db.prepare(`DELETE FROM daily_aggregates WHERE aggregate_date >= ?1`).bind(fromDate),
+    db.prepare(`
+      INSERT INTO daily_aggregates (aggregate_date, metric_key, dimension_key, dimension_value, value, updated_at)
+      SELECT substr(received_at, 1, 10), 'reports_received', 'source', source, COUNT(*), ?2
+      FROM reports WHERE received_at >= ?1 GROUP BY substr(received_at, 1, 10), source
+    `).bind(fromDate, refreshedAt),
+    db.prepare(`
+      INSERT INTO daily_aggregates (aggregate_date, metric_key, dimension_key, dimension_value, value, updated_at)
+      SELECT substr(received_at, 1, 10), 'reports_received', 'reason', reason_code, COUNT(*), ?2
+      FROM reports WHERE received_at >= ?1 GROUP BY substr(received_at, 1, 10), reason_code
+    `).bind(fromDate, refreshedAt),
+    db.prepare(`
+      INSERT INTO daily_aggregates (aggregate_date, metric_key, dimension_key, dimension_value, value, updated_at)
+      SELECT substr(r.received_at, 1, 10), 'reports_received', 'target_type', t.target_type, COUNT(*), ?2
+      FROM reports r JOIN report_targets t ON t.report_id = r.id
+      WHERE r.received_at >= ?1 GROUP BY substr(r.received_at, 1, 10), t.target_type
+    `).bind(fromDate, refreshedAt),
+    db.prepare(`
+      INSERT INTO daily_aggregates (aggregate_date, metric_key, dimension_key, dimension_value, value, updated_at)
+      SELECT substr(d.created_at, 1, 10), 'decisions', 'outcome', d.decision_code, COUNT(*), ?2
+      FROM decisions d WHERE d.created_at >= ?1 GROUP BY substr(d.created_at, 1, 10), d.decision_code
+    `).bind(fromDate, refreshedAt),
+    db.prepare(`
+      INSERT INTO daily_aggregates (aggregate_date, metric_key, dimension_key, dimension_value, value, updated_at)
+      SELECT substr(d.created_at, 1, 10), 'decisions', 'maker_type', d.maker_type, COUNT(*), ?2
+      FROM decisions d WHERE d.created_at >= ?1 GROUP BY substr(d.created_at, 1, 10), d.maker_type
+    `).bind(fromDate, refreshedAt),
+    db.prepare(`
+      INSERT INTO daily_aggregates (aggregate_date, metric_key, dimension_key, dimension_value, value, updated_at)
+      SELECT substr(submitted_at, 1, 10), 'appeals_filed', 'audience', appellant_audience, COUNT(*), ?2
+      FROM appeals WHERE submitted_at >= ?1 GROUP BY substr(submitted_at, 1, 10), appellant_audience
+    `).bind(fromDate, refreshedAt),
+    db.prepare(`
+      INSERT INTO daily_aggregates (aggregate_date, metric_key, dimension_key, dimension_value, value, updated_at)
+      SELECT substr(created_at, 1, 10), 'appeal_decisions', 'outcome', outcome, COUNT(*), ?2
+      FROM appeal_decisions WHERE created_at >= ?1 GROUP BY substr(created_at, 1, 10), outcome
+    `).bind(fromDate, refreshedAt),
+    db.prepare(`
+      INSERT INTO daily_aggregates (aggregate_date, metric_key, dimension_key, dimension_value, value, updated_at)
+      SELECT substr(created_at, 1, 10), 'application_actions', 'status', status, COUNT(*), ?2
+      FROM decision_action_outbox WHERE created_at >= ?1 GROUP BY substr(created_at, 1, 10), status
+    `).bind(fromDate, refreshedAt),
+    db.prepare(`
+      INSERT INTO daily_aggregates (aggregate_date, metric_key, dimension_key, dimension_value, value, updated_at)
+      SELECT substr(created_at, 1, 10), 'notices', 'delivery_state', delivery_state, COUNT(*), ?2
+      FROM notices WHERE created_at >= ?1 GROUP BY substr(created_at, 1, 10), delivery_state
+    `).bind(fromDate, refreshedAt),
+    db.prepare(`
+      INSERT INTO daily_aggregates (aggregate_date, metric_key, dimension_key, dimension_value, value, updated_at)
+      SELECT substr(started_at, 1, 10), 'ai_runs', 'status', status, COUNT(*), ?2
+      FROM ai_runs WHERE started_at >= ?1 GROUP BY substr(started_at, 1, 10), status
+    `).bind(fromDate, refreshedAt),
+    db.prepare(`
+      INSERT INTO daily_aggregates (aggregate_date, metric_key, dimension_key, dimension_value, value, updated_at)
+      SELECT substr(started_at, 1, 10), 'ai_runs', 'mode', mode, COUNT(*), ?2
+      FROM ai_runs WHERE started_at >= ?1 GROUP BY substr(started_at, 1, 10), mode
+    `).bind(fromDate, refreshedAt),
+  ];
+  await db.batch(statements);
+}
+
+export async function refreshDailyAggregatesIfStale(db: D1Database): Promise<void> {
+  const latest = await db.prepare(`SELECT MAX(updated_at) AS updatedAt FROM daily_aggregates`).first<{ updatedAt: string | null }>();
+  if (latest?.updatedAt && Date.parse(latest.updatedAt) > Date.now() - 15 * 60_000) return;
+  await refreshDailyAggregates(db, 90);
+}
+
+function percentile(values: number[], ratio: number): number | null {
+  if (!values.length) return null;
+  const index = Math.max(0, Math.min(values.length - 1, Math.ceil(values.length * ratio) - 1));
+  return Math.round(values[index] ?? 0);
+}
+
+export async function loadAnalytics(db: D1Database, days = 30): Promise<Record<string, unknown>> {
+  const generatedAt = now();
+  const boundedDays = Math.max(1, Math.min(366, days));
+  const fromDate = subtractDays(generatedAt, boundedDays).slice(0, 10);
+  const [series, durations, backlog, aiUsage] = await Promise.all([
+    db.prepare(`
+      SELECT aggregate_date AS aggregateDate, metric_key AS metricKey, dimension_key AS dimensionKey,
+        dimension_value AS dimensionValue, value
+      FROM daily_aggregates WHERE aggregate_date >= ?1
+      ORDER BY aggregate_date, metric_key, dimension_key, dimension_value LIMIT 10000
+    `).bind(fromDate).all<Record<string, unknown>>(),
+    db.prepare(`
+      SELECT CAST((julianday(resolved_at) - julianday(received_at)) * 86400 AS INTEGER) AS seconds
+      FROM reports WHERE resolved_at IS NOT NULL AND received_at >= ?1
+      ORDER BY seconds LIMIT 10000
+    `).bind(`${fromDate}T00:00:00.000Z`).all<{ seconds: number }>(),
+    db.prepare(`
+      SELECT queue_id AS queueId, state, COUNT(*) AS count,
+        CAST(MAX((julianday(?1) - julianday(received_at)) * 86400) AS INTEGER) AS oldestAgeSeconds
+      FROM reports WHERE state IN ('received', 'human_review', 'ai_review', 'awaiting_reporter', 'human_review_requested', 'appealed')
+      GROUP BY queue_id, state ORDER BY queue_id, state
+    `).bind(generatedAt).all<Record<string, unknown>>(),
+    db.prepare(`
+      SELECT usage_date AS usageDate, SUM(reports_started) AS reportsStarted,
+        SUM(reports_resolved) AS reportsResolved, SUM(reports_escalated) AS reportsEscalated,
+        SUM(failures) AS failures, SUM(estimated_cost_microusd) AS estimatedCostMicrousd,
+        SUM(eligible_reports) AS eligibleReports, SUM(waiting_for_reporter) AS waitingForReporter,
+        SUM(human_review_requests) AS humanReviewRequests, SUM(appeals_filed) AS appealsFiled,
+        SUM(appeal_reversals) AS appealReversals, SUM(invalid_outputs) AS invalidOutputs,
+        SUM(provider_errors) AS providerErrors, SUM(timeouts) AS timeouts
+      FROM ai_usage_daily WHERE usage_date >= ?1 GROUP BY usage_date ORDER BY usage_date
+    `).bind(fromDate).all<Record<string, unknown>>(),
+  ]);
+  const seconds = durations.results.map((row) => row.seconds).filter((value) => Number.isFinite(value));
+  return {
+    generatedAt,
+    fromDate,
+    days: boundedDays,
+    series: series.results,
+    backlog: backlog.results,
+    resolutionSeconds: {
+      count: seconds.length,
+      median: percentile(seconds, 0.5),
+      p90: percentile(seconds, 0.9),
+      p95: percentile(seconds, 0.95),
+    },
+    aiUsage: aiUsage.results,
+    limitations: [
+      "Counts describe reports and decisions, not verified real-world incidents.",
+      "No rate denominator is calculated unless the customer supplies one.",
+      ...(durations.results.length >= 10000 ? ["Resolution percentiles are bounded to the first 10,000 records in the selected period."] : []),
+    ],
+  };
+}
+
+type DeletionScope = "participant_data" | "all_permitted_data";
+
+async function anonymizeReport(
+  db: D1Database,
+  reportId: string,
+  at: string,
+  actorId: string,
+  reason: string,
+  scope: DeletionScope,
+): Promise<void> {
+  await db.batch([
+    db.prepare(`
+      UPDATE case_messages SET body = '[removed participant message]', sender_id = 'redacted', redacted_at = ?2
+      WHERE report_id = ?1 AND direction = 'inbound' AND sender_type IN ('reporter', 'affected_user') AND redacted_at IS NULL
+    `).bind(reportId, at),
+    db.prepare(`UPDATE report_answers SET value_json = 'null', redacted_at = ?2 WHERE report_id = ?1 AND redacted_at IS NULL`).bind(reportId, at),
+    db.prepare(`UPDATE report_participants SET reference = NULL, contact_ciphertext = NULL, reference_redacted_at = ?2 WHERE report_id = ?1 AND reference_redacted_at IS NULL`).bind(reportId, at),
+    db.prepare(`UPDATE appeals SET reason = '[removed participant appeal]', reason_redacted_at = ?2 WHERE report_id = ?1 AND reason_redacted_at IS NULL`).bind(reportId, at),
+    db.prepare(`UPDATE report_state_history SET actor_id = 'redacted' WHERE report_id = ?1 AND actor_type IN ('reporter', 'affected_user')`).bind(reportId),
+    db.prepare(`UPDATE audit_events SET actor_id = 'redacted' WHERE target_id = ?1 AND actor_type IN ('reporter', 'affected_user') AND chained_at IS NULL`).bind(reportId),
+    db.prepare(`DELETE FROM context_token_uses WHERE report_id = ?1`).bind(reportId),
+  ]);
+  if (scope === "all_permitted_data") {
+    await db.batch([
+      db.prepare(`UPDATE case_messages SET body = '[removed by retention]', sender_id = 'redacted', redacted_at = COALESCE(redacted_at, ?2) WHERE report_id = ?1`).bind(reportId, at),
+      db.prepare(`
+        UPDATE report_targets SET target_reference = 'redacted:' || id, owner_reference = NULL,
+          customer_url = NULL, signed_facts_json = '{}', sensitive_redacted_at = ?2
+        WHERE report_id = ?1 AND sensitive_redacted_at IS NULL
+      `).bind(reportId, at),
+      db.prepare(`UPDATE evidence_references SET reference = 'redacted:' || id, availability = 'deleted', retention_class = 'redacted' WHERE report_id = ?1 AND retention_class != 'redacted'`).bind(reportId),
+      db.prepare(`UPDATE decisions SET rationale = '[removed by retention]', evidence_references_json = '[]', sensitive_redacted_at = ?2 WHERE report_id = ?1 AND sensitive_redacted_at IS NULL`).bind(reportId, at),
+      db.prepare(`UPDATE notices SET rendered_body = '[removed by retention]', redacted_at = ?2 WHERE report_id = ?1 AND redacted_at IS NULL`).bind(reportId, at),
+      db.prepare(`
+        UPDATE appeal_decisions SET rationale = '[removed by retention]', rationale_redacted_at = ?2
+        WHERE appeal_id IN (SELECT id FROM appeals WHERE report_id = ?1) AND rationale_redacted_at IS NULL
+      `).bind(reportId, at),
+      db.prepare(`
+        UPDATE decision_action_outbox SET target_reference = 'redacted:' || id, payload_json = '{}', payload_redacted_at = ?2
+        WHERE report_id = ?1 AND terminal = 1 AND payload_redacted_at IS NULL
+      `).bind(reportId, at),
+      db.prepare(`
+        UPDATE notification_outbox SET payload_json = '{}', payload_redacted_at = ?2
+        WHERE notice_id IN (SELECT id FROM notices WHERE report_id = ?1) AND terminal = 1 AND payload_redacted_at IS NULL
+      `).bind(reportId, at),
+      db.prepare(`UPDATE ai_runs SET output_json = NULL, output_redacted_at = ?2 WHERE report_id = ?1 AND output_redacted_at IS NULL`).bind(reportId, at),
+      db.prepare(`
+        UPDATE ai_results SET evidence_references_json = '[]', summary = '[removed by retention]',
+          message_variables_json = NULL, redacted_at = ?2
+        WHERE ai_run_id IN (SELECT id FROM ai_runs WHERE report_id = ?1) AND redacted_at IS NULL
+      `).bind(reportId, at),
+      db.prepare(`UPDATE ai_tool_calls SET input_references_json = '{}' WHERE ai_run_id IN (SELECT id FROM ai_runs WHERE report_id = ?1)`).bind(reportId),
+      db.prepare(`
+        UPDATE quality_reviews SET notes = '[removed by retention]', notes_redacted_at = ?2
+        WHERE sample_id IN (SELECT id FROM ai_quality_samples WHERE report_id = ?1) AND notes_redacted_at IS NULL
+      `).bind(reportId, at),
+    ]);
+  }
+  await db.batch([
+    auditEvent(db, {
+      key: `retention:${reportId}:${reason}`,
+      action: "retention.report_anonymized",
+      actorType: "system",
+      actorId,
+      targetType: "report",
+      targetId: reportId,
+      details: { reason, scope },
+      createdAt: at,
+    }),
+  ]);
+}
+
+export async function runScheduledRetention(db: D1Database, messageRetentionDays: number, reportRetentionDays: number): Promise<void> {
+  const startedAt = now();
+  const jobId = crypto.randomUUID();
+  const messageCutoff = subtractDays(startedAt, Math.max(1, Math.min(3_650, messageRetentionDays)));
+  const reportCutoff = subtractDays(startedAt, Math.max(30, Math.min(3_650, reportRetentionDays)));
+  await db.prepare(`
+    INSERT INTO retention_jobs (id, job_kind, state, cutoff_at, started_at)
+    VALUES (?1, 'scheduled_retention', 'running', ?2, ?3)
+  `).bind(jobId, reportCutoff, startedAt).run();
+  try {
+    const messages = await db.prepare(`
+      UPDATE case_messages SET body = '[removed by retention]', sender_id = 'redacted', redacted_at = ?2
+      WHERE redacted_at IS NULL AND created_at < ?1 AND NOT EXISTS (
+        SELECT 1 FROM legal_holds h WHERE h.report_id = case_messages.report_id AND h.state = 'active'
+      )
+    `).bind(messageCutoff, startedAt).run();
+    await db.prepare(`
+      UPDATE notices SET rendered_body = '[removed by retention]', redacted_at = ?2
+      WHERE redacted_at IS NULL AND created_at < ?1 AND NOT EXISTS (
+        SELECT 1 FROM legal_holds h WHERE h.report_id = notices.report_id AND h.state = 'active'
+      )
+    `).bind(messageCutoff, startedAt).run();
+    const candidates = await db.prepare(`
+      SELECT id FROM reports r
+      WHERE r.updated_at < ?1 AND r.state IN ('resolved_by_human', 'resolved_by_ai', 'closed')
+        AND NOT EXISTS (SELECT 1 FROM legal_holds h WHERE h.report_id = r.id AND h.state = 'active')
+        AND NOT EXISTS (SELECT 1 FROM decision_action_outbox o WHERE o.report_id = r.id AND o.terminal = 0)
+        AND NOT EXISTS (
+          SELECT 1 FROM notification_outbox o JOIN notices n ON n.id = o.notice_id
+          WHERE n.report_id = r.id AND o.terminal = 0
+        )
+        AND EXISTS (SELECT 1 FROM report_participants p WHERE p.report_id = r.id AND p.reference_redacted_at IS NULL)
+      ORDER BY r.updated_at, r.id LIMIT 100
+    `).bind(reportCutoff).all<{ id: string }>();
+    for (const report of candidates.results) {
+      await anonymizeReport(db, report.id, startedAt, "retention-worker", "retention_period_expired", "all_permitted_data");
+    }
+    await db.prepare(`
+      UPDATE retention_jobs SET state = 'complete', messages_redacted = ?2, reports_anonymized = ?3,
+        portal_sessions_revoked = ?4, finished_at = ?5 WHERE id = ?1
+    `).bind(jobId, messages.meta.changes ?? 0, candidates.results.length, 0, now()).run();
+  } catch (error) {
+    await db.prepare(`UPDATE retention_jobs SET state = 'failed', error_code = 'retention_failed', finished_at = ?2 WHERE id = ?1`)
+      .bind(jobId, now()).run();
+    throw error;
+  }
+}
+
+export async function runRetentionIfDue(db: D1Database, messageRetentionDays: number, reportRetentionDays: number): Promise<void> {
+  const latest = await db.prepare(`
+    SELECT started_at AS startedAt FROM retention_jobs
+    WHERE job_kind = 'scheduled_retention' ORDER BY started_at DESC LIMIT 1
+  `).first<{ startedAt: string }>();
+  if (latest?.startedAt && Date.parse(latest.startedAt) > Date.now() - 23 * 60 * 60_000) return;
+  await runScheduledRetention(db, messageRetentionDays, reportRetentionDays);
+}
+
+export async function createLegalHold(
+  db: D1Database,
+  reportId: string,
+  reason: string,
+  actorId: string,
+  idempotencyKey: string,
+): Promise<{ id: string; idempotentReplay: boolean }> {
+  const existing = await db.prepare(`SELECT id FROM legal_holds WHERE idempotency_key = ?1 LIMIT 1`).bind(idempotencyKey).first<{ id: string }>();
+  if (existing) return { id: existing.id, idempotentReplay: true };
+  const report = await db.prepare(`SELECT id FROM reports WHERE id = ?1 LIMIT 1`).bind(reportId).first<{ id: string }>();
+  if (!report) throw new ApiError(404, "report_not_found", "The report does not exist.");
+  const createdAt = now();
+  const id = crypto.randomUUID();
+  try {
+    await db.batch([
+      db.prepare(`
+        INSERT INTO legal_holds (id, report_id, reason, state, placed_by, idempotency_key, created_at)
+        VALUES (?1, ?2, ?3, 'active', ?4, ?5, ?6)
+      `).bind(id, reportId, reason, actorId, idempotencyKey, createdAt),
+      auditEvent(db, {
+        key: `legal-hold:${idempotencyKey}`,
+        action: "retention.legal_hold_placed",
+        actorType: "operator",
+        actorId,
+        targetType: "report",
+        targetId: reportId,
+        details: { legalHoldId: id, reason },
+        createdAt,
+      }),
+    ]);
+  } catch {
+    throw new ApiError(409, "legal_hold_exists", "This report already has an active legal hold.");
+  }
+  return { id, idempotentReplay: false };
+}
+
+export async function releaseLegalHold(db: D1Database, holdId: string, actorId: string, idempotencyKey: string): Promise<boolean> {
+  const releasedAt = now();
+  const result = await db.prepare(`
+    UPDATE legal_holds SET state = 'released', released_by = ?2, release_idempotency_key = ?3, released_at = ?4
+    WHERE id = ?1 AND (state = 'active' OR release_idempotency_key = ?3)
+  `).bind(holdId, actorId, idempotencyKey, releasedAt).run();
+  if ((result.meta.changes ?? 0) < 1) throw new ApiError(404, "legal_hold_not_found", "The active legal hold does not exist.");
+  await db.batch([auditEvent(db, {
+    key: `legal-hold-release:${idempotencyKey}`,
+    action: "retention.legal_hold_released",
+    actorType: "operator",
+    actorId,
+    targetType: "legal_hold",
+    targetId: holdId,
+    details: {},
+    createdAt: releasedAt,
+  })]);
+  return true;
+}
+
+export async function createDeletionRequest(
+  db: D1Database,
+  input: { reportId: string; scope: "participant_data" | "all_permitted_data"; reason: string },
+  actorId: string,
+  idempotencyKey: string,
+): Promise<{ id: string; state: string; idempotentReplay: boolean }> {
+  const existing = await db.prepare(`SELECT id, state FROM deletion_requests WHERE idempotency_key = ?1 LIMIT 1`)
+    .bind(idempotencyKey).first<{ id: string; state: string }>();
+  if (existing) return { ...existing, idempotentReplay: true };
+  const report = await db.prepare(`SELECT id FROM reports WHERE id = ?1 LIMIT 1`).bind(input.reportId).first<{ id: string }>();
+  if (!report) throw new ApiError(404, "report_not_found", "The report does not exist.");
+  const hold = await db.prepare(`SELECT id FROM legal_holds WHERE report_id = ?1 AND state = 'active' LIMIT 1`)
+    .bind(input.reportId).first<{ id: string }>();
+  const state = hold ? "blocked_by_hold" : "pending";
+  const id = crypto.randomUUID();
+  const requestedAt = now();
+  await db.batch([
+    db.prepare(`
+      INSERT INTO deletion_requests (
+        id, report_id, scope, reason, state, requested_by, idempotency_key, requested_at
+      ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, ?8)
+    `).bind(id, input.reportId, input.scope, input.reason, state, actorId, idempotencyKey, requestedAt),
+    auditEvent(db, {
+      key: `deletion-request:${idempotencyKey}`,
+      action: "retention.deletion_requested",
+      actorType: "operator",
+      actorId,
+      targetType: "report",
+      targetId: input.reportId,
+      details: { deletionRequestId: id, scope: input.scope, state },
+      createdAt: requestedAt,
+    }),
+  ]);
+  return { id, state, idempotentReplay: false };
+}
+
+export async function processDeletionRequests(db: D1Database): Promise<void> {
+  const requests = await db.prepare(`
+    SELECT id, report_id, scope FROM deletion_requests WHERE state IN ('pending', 'blocked_by_hold')
+    ORDER BY requested_at, id LIMIT 25
+  `).all<{ id: string; report_id: string; scope: DeletionScope }>();
+  for (const request of requests.results) {
+    const hold = await db.prepare(`SELECT id FROM legal_holds WHERE report_id = ?1 AND state = 'active' LIMIT 1`)
+      .bind(request.report_id).first<{ id: string }>();
+    if (hold) {
+      await db.prepare(`UPDATE deletion_requests SET state = 'blocked_by_hold' WHERE id = ?1`).bind(request.id).run();
+      continue;
+    }
+    const report = await db.prepare(`SELECT state FROM reports WHERE id = ?1 LIMIT 1`).bind(request.report_id).first<{ state: string }>();
+    if (!report || !["resolved_by_human", "resolved_by_ai", "closed"].includes(report.state)) {
+      await db.prepare(`UPDATE deletion_requests SET state = 'pending', last_error_code = 'active_case' WHERE id = ?1`).bind(request.id).run();
+      continue;
+    }
+    const outstandingDelivery = await db.prepare(`
+      SELECT 1 AS pending FROM decision_action_outbox WHERE report_id = ?1 AND terminal = 0
+      UNION ALL
+      SELECT 1 AS pending FROM notification_outbox o JOIN notices n ON n.id = o.notice_id
+      WHERE n.report_id = ?1 AND o.terminal = 0 LIMIT 1
+    `).bind(request.report_id).first<{ pending: number }>();
+    if (outstandingDelivery) {
+      await db.prepare(`UPDATE deletion_requests SET state = 'pending', last_error_code = 'delivery_pending' WHERE id = ?1`).bind(request.id).run();
+      continue;
+    }
+    const completedAt = now();
+    try {
+      await anonymizeReport(db, request.report_id, completedAt, "deletion-worker", `deletion_request:${request.id}`, request.scope);
+      await db.prepare(`UPDATE deletion_requests SET state = 'complete', completed_at = ?2, last_error_code = NULL WHERE id = ?1`)
+        .bind(request.id, completedAt).run();
+    } catch {
+      await db.prepare(`UPDATE deletion_requests SET state = 'failed', last_error_code = 'anonymization_failed' WHERE id = ?1`).bind(request.id).run();
+    }
+  }
+}
+
+export async function listAuditEntries(
+  db: D1Database,
+  afterSequence: number,
+  limit: number,
+): Promise<{ entries: Record<string, unknown>[]; nextSequence: number | null }> {
+  const boundedLimit = Math.max(1, Math.min(500, limit));
+  const result = await db.prepare(`
+    SELECT sequence, id, action, actor_type AS actorType, actor_id AS actorId,
+      target_type AS targetType, target_id AS targetId, details_json AS detailsJson,
+      previous_hash AS previousHash, entry_hash AS entryHash, created_at AS createdAt
+    FROM audit_entries WHERE sequence > ?1 ORDER BY sequence LIMIT ?2
+  `).bind(Math.max(0, afterSequence), boundedLimit + 1).all<Record<string, unknown>>();
+  const entries = result.results.slice(0, boundedLimit)
+    .map<Record<string, unknown>>((row) => ({ ...row, details: JSON.parse(String(row.detailsJson)), detailsJson: undefined }));
+  const last = entries.at(-1);
+  return {
+    entries,
+    nextSequence: result.results.length > boundedLimit && last ? Number(last.sequence) : null,
+  };
+}
+
+export async function verifyAuditChain(db: D1Database): Promise<Record<string, unknown>> {
+  let cursor = 0;
+  let previousHash = AUDIT_GENESIS_HASH;
+  let verified = 0;
+  while (true) {
+    const page = await db.prepare(`
+      SELECT sequence, action, actor_type, actor_id, target_type, target_id,
+        details_json, previous_hash, entry_hash, created_at
+      FROM audit_entries WHERE sequence > ?1 ORDER BY sequence LIMIT 500
+    `).bind(cursor).all<{
+      sequence: number; action: string; actor_type: string; actor_id: string; target_type: string;
+      target_id: string; details_json: string; previous_hash: string; entry_hash: string; created_at: string;
+    }>();
+    if (!page.results.length) break;
+    for (const entry of page.results) {
+      if (entry.previous_hash !== previousHash) return { valid: false, verifiedEntries: verified, failedSequence: entry.sequence, reason: "previous_hash_mismatch" };
+      const expected = await hashAuditEntry({
+        sequence: entry.sequence, action: entry.action, actorType: entry.actor_type, actorId: entry.actor_id,
+        targetType: entry.target_type, targetId: entry.target_id, detailsJson: entry.details_json,
+        previousHash: entry.previous_hash, createdAt: entry.created_at,
+      });
+      if (expected !== entry.entry_hash) return { valid: false, verifiedEntries: verified, failedSequence: entry.sequence, reason: "entry_hash_mismatch" };
+      previousHash = entry.entry_hash;
+      cursor = entry.sequence;
+      verified += 1;
+      if (verified > 100_000) return { valid: false, verifiedEntries: verified, reason: "verification_limit_exceeded" };
+    }
+  }
+  return { valid: true, verifiedEntries: verified, tipHash: previousHash, verifiedAt: now() };
+}
+
+function csvCell(value: unknown): string {
+  const raw = String(value ?? "");
+  const text = /^[=+\-@\t\r]/u.test(raw) ? `'${raw}` : raw;
+  return /[",\r\n]/u.test(text) ? `"${text.replaceAll('"', '""')}"` : text;
+}
+
+export async function reportsCsv(db: D1Database, days: number, allowedQueueIds?: string[] | null): Promise<string> {
+  const from = subtractDays(now(), Math.max(1, Math.min(366, days)));
+  const result = await db.prepare(`
+    SELECT r.public_reference AS reference, r.source, r.reason_code AS allegation,
+      t.target_type AS targetType, r.state, r.queue_id AS queueId, r.priority,
+      r.received_at AS receivedAt, r.resolved_at AS resolvedAt,
+      d.decision_code AS decisionOutcome, d.maker_type AS decisionMakerType,
+      a.state AS appealState
+    FROM reports r JOIN report_targets t ON t.report_id = r.id
+    LEFT JOIN decisions d ON d.id = (SELECT id FROM decisions WHERE report_id = r.id ORDER BY created_at DESC, id DESC LIMIT 1)
+    LEFT JOIN appeals a ON a.id = (SELECT id FROM appeals WHERE report_id = r.id ORDER BY submitted_at DESC, id DESC LIMIT 1)
+    WHERE r.received_at >= ?1
+      AND (?2 = 1 OR r.queue_id IN (SELECT value FROM json_each(?3)))
+    ORDER BY r.received_at DESC, r.id DESC LIMIT 10000
+  `).bind(
+    from,
+    allowedQueueIds === null || allowedQueueIds === undefined ? 1 : 0,
+    canonicalJson(allowedQueueIds ?? []),
+  ).all<Record<string, unknown>>();
+  const columns = ["reference", "source", "allegation", "targetType", "state", "queueId", "priority", "receivedAt", "resolvedAt", "decisionOutcome", "decisionMakerType", "appealState"];
+  return `${columns.join(",")}\r\n${result.results.map((row) => columns.map((column) => csvCell(row[column])).join(",")).join("\r\n")}\r\n`;
+}
+
+export async function recordExportAudit(db: D1Database, actorId: string, days: number): Promise<void> {
+  const createdAt = now();
+  await db.batch([auditEvent(db, {
+    key: `reports-export:${actorId}:${crypto.randomUUID()}`,
+    action: "export.reports_created",
+    actorType: "operator",
+    actorId,
+    targetType: "report_export",
+    targetId: crypto.randomUUID(),
+    details: { format: "csv", days: Math.max(1, Math.min(366, days)), includesMessageBodies: false },
+    createdAt,
+  })]);
+}

package/template/src/report-http.ts

@@ -0,0 +1,90 @@
+export class ApiError extends Error {
+  constructor(
+    readonly status: number,
+    readonly code: string,
+    message: string,
+    readonly details?: Record<string, unknown>,
+  ) {
+    super(message);
+    this.name = "ApiError";
+  }
+}
+
+const securityHeaders = {
+  "content-security-policy": "default-src 'self'; base-uri 'none'; frame-ancestors 'none'; form-action 'self'",
+  "referrer-policy": "no-referrer",
+  "x-content-type-options": "nosniff",
+  "x-frame-options": "DENY",
+} as const;
+
+export function json(data: unknown, init: ResponseInit = {}): Response {
+  const headers = new Headers(init.headers);
+  headers.set("content-type", "application/json; charset=utf-8");
+  headers.set("cache-control", "no-store");
+  for (const [name, value] of Object.entries(securityHeaders)) headers.set(name, value);
+  return new Response(JSON.stringify(data), { ...init, headers });
+}
+
+export function apiErrorResponse(error: unknown): Response {
+  if (error instanceof ApiError) {
+    return json({
+      error: {
+        code: error.code,
+        message: error.message,
+        ...(error.details ? { details: error.details } : {}),
+      },
+    }, { status: error.status });
+  }
+  console.error("unhandled reports request error", error instanceof Error
+    ? { name: error.name, message: error.message }
+    : { valueType: typeof error });
+  return json({ error: { code: "internal_error", message: "The request could not be completed." } }, { status: 500 });
+}
+
+export async function readJsonObject(request: Request, maximumBytes = 64 * 1024): Promise<Record<string, unknown>> {
+  const contentType = request.headers.get("content-type")?.split(";", 1)[0]?.trim().toLowerCase();
+  if (contentType !== "application/json") throw new ApiError(415, "unsupported_media_type", "Content-Type must be application/json.");
+  const declared = Number.parseInt(request.headers.get("content-length") ?? "0", 10);
+  if (Number.isFinite(declared) && declared > maximumBytes) throw new ApiError(413, "request_too_large", "The request body is too large.");
+  const bytes = new Uint8Array(await request.arrayBuffer());
+  if (bytes.byteLength > maximumBytes) throw new ApiError(413, "request_too_large", "The request body is too large.");
+  let value: unknown;
+  try {
+    value = JSON.parse(new TextDecoder().decode(bytes));
+  } catch {
+    throw new ApiError(400, "invalid_json", "The request body must contain valid JSON.");
+  }
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new ApiError(400, "invalid_body", "The request body must be a JSON object.");
+  }
+  return value as Record<string, unknown>;
+}
+
+export function allowedOrigin(origin: string | null, configured: string): string | null {
+  if (!origin) return null;
+  const allowed = new Set(configured.split(",").map((value) => value.trim()).filter(Boolean));
+  return allowed.has(origin) ? origin : null;
+}
+
+export function withCors(response: Response, origin: string | null): Response {
+  if (!origin) return response;
+  const headers = new Headers(response.headers);
+  headers.set("access-control-allow-origin", origin);
+  headers.set("access-control-allow-methods", "GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS");
+  headers.set("access-control-allow-headers", "authorization, content-type, idempotency-key, if-match, x-csrf-token, x-safest-integration-id");
+  headers.set("access-control-max-age", "600");
+  headers.append("vary", "Origin");
+  return new Response(response.body, {
+    status: response.status,
+    statusText: response.statusText,
+    headers,
+    webSocket: response.webSocket,
+  });
+}
+
+export function methodNotAllowed(allowed: string[]): Response {
+  return json({ error: { code: "method_not_allowed", message: "This method is not supported for the route." } }, {
+    status: 405,
+    headers: { allow: allowed.join(", ") },
+  });
+}