create-safest-tools 0.2.0

package/template/src/installation-admin.ts

@@ -0,0 +1,301 @@
+import { canonicalJson } from "./audit";
+import { sha256 } from "./report-crypto";
+import { ApiError } from "./report-http";
+import type { OperatorSession } from "./report-types";
+import { WORKFLOW_COMPILER_VERSION } from "./workflow-compiler";
+import { parseWorkspaceBrand } from "./workspace-branding";
+import { contextSchemaJson, parseContextSchema } from "./report-context-schema";
+
+const integrationKeyPattern = /^[a-z][a-z0-9-]{1,79}$/u;
+const allowedScopes = new Set(["submit_reports", "mint_context_tokens", "evidence_callback", "action_callback"]);
+const channelModes = new Set(["contextual", "anonymous"] as const);
+
+function safeChannelMode(value: unknown): "contextual" | "anonymous" {
+  const mode = value ?? "contextual";
+  if (typeof mode !== "string" || !channelModes.has(mode as "contextual" | "anonymous")) {
+    throw new ApiError(400, "integration_mode_invalid", "channel_mode must be contextual or anonymous.");
+  }
+  return mode as "contextual" | "anonymous";
+}
+
+function now(): string { return new Date().toISOString(); }
+
+function randomSecret(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(32));
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replace(/\+/gu, "-").replace(/\//gu, "_").replace(/=+$/gu, "");
+}
+
+function safeOrigins(value: unknown): string[] {
+  if (!Array.isArray(value) || value.length > 100) throw new ApiError(400, "integration_origins_invalid", "allowed_origins must contain at most 100 HTTPS origins.");
+  const origins = value.map((entry) => {
+    if (typeof entry !== "string") throw new ApiError(400, "integration_origins_invalid", "Each allowed origin must be a string.");
+    let url: URL;
+    try { url = new URL(entry); } catch { throw new ApiError(400, "integration_origins_invalid", "Each allowed origin must be a valid origin."); }
+    const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+    if ((url.protocol !== "https:" && !(local && url.protocol === "http:")) || url.username || url.password || url.pathname !== "/" || url.search || url.hash) {
+      throw new ApiError(400, "integration_origins_invalid", "Origins must be HTTPS origins without paths; localhost HTTP is allowed for development.");
+    }
+    return url.origin;
+  });
+  if (new Set(origins).size !== origins.length) throw new ApiError(400, "integration_origins_invalid", "allowed_origins contains duplicates.");
+  return origins;
+}
+
+function safeScopes(value: unknown): string[] {
+  if (!Array.isArray(value) || value.length < 1 || value.length > allowedScopes.size) throw new ApiError(400, "integration_scopes_invalid", "scopes must be a non-empty list.");
+  const scopes = value.map((entry) => {
+    if (typeof entry !== "string" || !allowedScopes.has(entry)) throw new ApiError(400, "integration_scopes_invalid", "An integration scope is unsupported.");
+    return entry;
+  });
+  if (new Set(scopes).size !== scopes.length) throw new ApiError(400, "integration_scopes_invalid", "scopes contains duplicates.");
+  return scopes;
+}
+
+export async function loadInstallation(db: D1Database): Promise<Record<string, unknown>> {
+  const installation = await db.prepare(`SELECT id, display_name AS displayName, default_locale AS defaultLocale, anonymous_reporting_enabled AS anonymousReportingEnabled, timezone, settings_json AS settingsJson, created_at AS createdAt, updated_at AS updatedAt FROM installations WHERE id = 'default' LIMIT 1`).first<Record<string, unknown>>();
+  if (!installation) throw new ApiError(503, "installation_missing", "The installation has not been initialized.");
+  const features = await db.prepare(`SELECT feature_key AS featureKey, state, capability_json AS capabilityJson, checked_at AS checkedAt, error_code AS errorCode, revision FROM installation_features WHERE installation_id = 'default' ORDER BY feature_key`).all<Record<string, unknown>>();
+  return {
+    ...installation,
+    anonymousReportingEnabled: installation.anonymousReportingEnabled === 1,
+    settings: JSON.parse(String(installation.settingsJson ?? "{}")),
+    settingsJson: undefined,
+    features: features.results.map((feature) => ({ ...feature, capability: JSON.parse(String(feature.capabilityJson ?? "{}")), capabilityJson: undefined })),
+  };
+}
+
+export async function updateInstallation(
+  db: D1Database,
+  value: Record<string, unknown>,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<Record<string, unknown>> {
+  const allowed = new Set(["display_name", "default_locale", "timezone", "anonymous_reporting_enabled", "settings"]);
+  if (Object.keys(value).some((key) => !allowed.has(key))) throw new ApiError(400, "installation_update_invalid", "The installation update contains unsupported fields.");
+  if (value.display_name !== undefined && (typeof value.display_name !== "string" || value.display_name.trim().length < 2 || value.display_name.length > 120)) throw new ApiError(400, "installation_name_invalid", "display_name must contain 2 to 120 characters.");
+  if (value.default_locale !== undefined && (typeof value.default_locale !== "string" || !/^[a-z]{2,3}(?:-[A-Z]{2})?$/u.test(value.default_locale))) throw new ApiError(400, "installation_locale_invalid", "default_locale is invalid.");
+  if (value.timezone !== undefined) {
+    if (typeof value.timezone !== "string" || value.timezone.length > 100) throw new ApiError(400, "installation_timezone_invalid", "timezone is invalid.");
+    try { new Intl.DateTimeFormat("en", { timeZone: value.timezone }).format(); } catch { throw new ApiError(400, "installation_timezone_invalid", "timezone is invalid."); }
+  }
+  if (value.anonymous_reporting_enabled !== undefined && typeof value.anonymous_reporting_enabled !== "boolean") throw new ApiError(400, "installation_anonymous_invalid", "anonymous_reporting_enabled must be boolean.");
+  if (value.settings !== undefined && (!value.settings || typeof value.settings !== "object" || Array.isArray(value.settings))) throw new ApiError(400, "installation_settings_invalid", "settings must be an object.");
+  const current = await db.prepare(`SELECT display_name AS displayName, default_locale AS defaultLocale, timezone, anonymous_reporting_enabled AS anonymousReportingEnabled, settings_json AS settingsJson FROM installations WHERE id = 'default'`).first<Record<string, unknown>>();
+  if (!current) throw new ApiError(503, "installation_missing", "The installation has not been initialized.");
+  const settingsValue = value.settings ?? JSON.parse(String(current.settingsJson));
+  const settings = settingsValue as Record<string, unknown>;
+  if (settings.brand !== undefined) {
+    settings.brand = parseWorkspaceBrand(settings.brand, typeof value.display_name === "string" ? value.display_name.trim() : String(current.displayName));
+  }
+  const timestamp = now();
+  await db.batch([
+    db.prepare(`UPDATE installations SET display_name = ?1, default_locale = ?2, timezone = ?3, anonymous_reporting_enabled = ?4, settings_json = ?5, updated_at = ?6 WHERE id = 'default'`).bind(
+      typeof value.display_name === "string" ? value.display_name.trim() : current.displayName,
+      typeof value.default_locale === "string" ? value.default_locale : current.defaultLocale,
+      typeof value.timezone === "string" ? value.timezone : current.timezone,
+      typeof value.anonymous_reporting_enabled === "boolean" ? (value.anonymous_reporting_enabled ? 1 : 0) : current.anonymousReportingEnabled,
+      canonicalJson(settings), 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, 'installation.updated', ?3, ?4, 'installation', 'default', ?5, ?6)`)
+      .bind(crypto.randomUUID(), `installation-update:${idempotencyKey}`, session.actor.type, session.actor.id, canonicalJson({ changedFields: Object.keys(value) }), timestamp),
+  ]);
+  return loadInstallation(db);
+}
+
+export async function listIntegrations(db: D1Database): Promise<Record<string, unknown>[]> {
+  const rows = await db.prepare(`
+    SELECT i.id, i.name, i.allowed_origins_json AS allowedOriginsJson,
+      i.scopes_json AS scopesJson, i.channel_mode AS channelMode,
+      i.form_version_id AS formVersionId, i.context_schema_json AS contextSchemaJson,
+      i.enabled, i.created_at AS createdAt, i.updated_at AS updatedAt,
+      (SELECT COUNT(*) FROM integration_api_keys k WHERE k.integration_id = i.id AND k.status = 'active' AND (k.expires_at IS NULL OR k.expires_at > ?1)) AS activeKeyCount,
+      (SELECT MAX(k.created_at) FROM integration_api_keys k WHERE k.integration_id = i.id) AS lastKeyCreatedAt
+    FROM application_integrations i WHERE i.installation_id = 'default' ORDER BY i.name, i.id
+  `).bind(now()).all<Record<string, unknown>>();
+  return rows.results.map((row) => ({
+    ...row,
+    enabled: row.enabled === 1,
+    allowedOrigins: JSON.parse(String(row.allowedOriginsJson)),
+    scopes: JSON.parse(String(row.scopesJson)),
+    contextSchema: JSON.parse(String(row.contextSchemaJson)),
+    allowedOriginsJson: undefined,
+    scopesJson: undefined,
+    contextSchemaJson: undefined,
+  }));
+}
+
+export async function loadIntegrationAdmin(db: D1Database, id: string): Promise<Record<string, unknown> | null> {
+  const integration = (await listIntegrations(db)).find((entry) => entry.id === id);
+  if (!integration) return null;
+  const keys = await db.prepare(`SELECT id, key_id AS keyId, status, valid_from AS validFrom, expires_at AS expiresAt, created_by AS createdBy, created_at AS createdAt, revoked_by AS revokedBy, revoked_at AS revokedAt FROM integration_api_keys WHERE integration_id = ?1 ORDER BY created_at DESC, id DESC`).bind(id).all<Record<string, unknown>>();
+  return { ...integration, keys: keys.results };
+}
+
+export async function createIntegration(
+  db: D1Database,
+  value: Record<string, unknown>,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ integrationId: string; keyId: string | null; apiKey: string | null; idempotentReplay: boolean }> {
+  const replay = await db.prepare(`SELECT target_id AS targetId FROM audit_events WHERE idempotency_key = ?1 AND action = 'integration.created' LIMIT 1`).bind(`integration-create:${idempotencyKey}`).first<{ targetId: string }>();
+  if (replay) throw new ApiError(409, "integration_key_already_issued", "The integration was created, but its one-time API key cannot be shown again. Rotate the key to issue a replacement.");
+  if (typeof value.integration_key !== "string" || !integrationKeyPattern.test(value.integration_key)) throw new ApiError(400, "integration_key_invalid", "integration_key must use lowercase letters, digits, and hyphens.");
+  if (typeof value.name !== "string" || value.name.trim().length < 2 || value.name.length > 120) throw new ApiError(400, "integration_name_invalid", "name must contain 2 to 120 characters.");
+  const origins = safeOrigins(value.allowed_origins ?? []);
+  const scopes = safeScopes(value.scopes ?? ["submit_reports", "mint_context_tokens"]);
+  const channelMode = safeChannelMode(value.channel_mode);
+  const formVersionId = typeof value.form_version_id === "string" && value.form_version_id.trim()
+    ? value.form_version_id.trim()
+    : null;
+  if (formVersionId && formVersionId.length > 100) throw new ApiError(400, "integration_form_invalid", "form_version_id is too long.");
+  if (formVersionId && !await db.prepare(`SELECT id FROM report_form_versions WHERE id = ?1 AND published_at IS NOT NULL AND retired_at IS NULL LIMIT 1`).bind(formVersionId).first()) {
+    throw new ApiError(400, "integration_form_unpublished", "Choose a published report form for this channel.");
+  }
+  const contextSchema = parseContextSchema(value.context_schema ?? { version: 1, allow_unknown: false, fields: [] });
+  if (channelMode === "anonymous" && scopes.includes("mint_context_tokens")) {
+    throw new ApiError(400, "integration_scope_denied", "Anonymous channels cannot mint authenticated context.");
+  }
+  const integrationId = crypto.randomUUID();
+  const issueApiKey = channelMode === "contextual";
+  const keyId = issueApiKey ? `runtime-${crypto.randomUUID()}` : null;
+  const apiKey = issueApiKey ? `safest_${randomSecret()}` : null;
+  const timestamp = now();
+  const statements = [
+    db.prepare(`INSERT INTO application_integrations (
+      id, installation_id, name, key_id, allowed_origins_json, enabled,
+      created_at, updated_at, scopes_json, channel_mode, form_version_id, context_schema_json
+    ) VALUES (?1, 'default', ?2, ?3, ?4, 1, ?5, ?5, ?6, ?7, ?8, ?9)`)
+      .bind(
+        integrationId, value.name.trim(), `managed:${value.integration_key}`,
+        canonicalJson(origins), timestamp, canonicalJson(scopes), channelMode,
+        formVersionId, canonicalJson(contextSchemaJson(contextSchema)),
+      ),
+    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, 'integration.created', ?3, ?4, 'application_integration', ?5, ?6, ?7)`)
+      .bind(crypto.randomUUID(), `integration-create:${idempotencyKey}`, session.actor.type, session.actor.id, integrationId, canonicalJson({ keyId, scopes, allowedOrigins: origins, channelMode, formVersionId, contextSchema: contextSchemaJson(contextSchema) }), timestamp),
+  ];
+  if (issueApiKey && keyId && apiKey) {
+    statements.splice(1, 0, db.prepare(`INSERT INTO integration_api_keys (id, integration_id, key_id, key_hash, status, valid_from, created_by, created_at) VALUES (?1, ?2, ?3, ?4, 'active', ?5, ?6, ?5)`)
+      .bind(crypto.randomUUID(), integrationId, keyId, await sha256(`integration-key-v1:${apiKey}`), timestamp, session.actor.id));
+  }
+  await db.batch(statements);
+  return { integrationId, keyId, apiKey, idempotentReplay: false };
+}
+
+export async function updateIntegration(
+  db: D1Database,
+  id: string,
+  value: Record<string, unknown>,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<Record<string, unknown>> {
+  const allowed = new Set(["name", "allowed_origins", "scopes", "enabled", "channel_mode", "form_version_id", "context_schema"]);
+  if (Object.keys(value).some((key) => !allowed.has(key))) throw new ApiError(400, "integration_update_invalid", "The integration update contains unsupported fields.");
+  const current = await db.prepare(`SELECT name, allowed_origins_json AS originsJson, scopes_json AS scopesJson,
+    channel_mode AS channelMode, form_version_id AS formVersionId, context_schema_json AS contextSchemaJson, enabled
+    FROM application_integrations WHERE id = ?1 LIMIT 1`).bind(id).first<{
+      name: string; originsJson: string; scopesJson: string; channelMode: "contextual" | "anonymous";
+      formVersionId: string | null; contextSchemaJson: string; enabled: number;
+    }>();
+  if (!current) throw new ApiError(404, "integration_not_found", "The integration does not exist.");
+  if (value.name !== undefined && (typeof value.name !== "string" || value.name.trim().length < 2 || value.name.length > 120)) throw new ApiError(400, "integration_name_invalid", "name is invalid.");
+  if (value.enabled !== undefined && typeof value.enabled !== "boolean") throw new ApiError(400, "integration_enabled_invalid", "enabled must be boolean.");
+  const origins = value.allowed_origins === undefined ? JSON.parse(current.originsJson) : safeOrigins(value.allowed_origins);
+  const scopes = value.scopes === undefined ? JSON.parse(current.scopesJson) : safeScopes(value.scopes);
+  const channelMode = value.channel_mode === undefined ? current.channelMode : safeChannelMode(value.channel_mode);
+  const formVersionId = value.form_version_id === undefined ? current.formVersionId
+    : value.form_version_id === null || value.form_version_id === "" ? null
+      : typeof value.form_version_id === "string" ? value.form_version_id.trim() : "";
+  if (formVersionId && (formVersionId.length > 100 || !await db.prepare(`SELECT id FROM report_form_versions WHERE id = ?1 AND published_at IS NOT NULL AND retired_at IS NULL LIMIT 1`).bind(formVersionId).first())) {
+    throw new ApiError(400, "integration_form_unpublished", "Choose a published report form for this channel.");
+  }
+  const contextSchema = value.context_schema === undefined
+    ? parseContextSchema(JSON.parse(current.contextSchemaJson), { allowLegacy: true })
+    : parseContextSchema(value.context_schema);
+  if (channelMode === "anonymous" && scopes.includes("mint_context_tokens")) {
+    throw new ApiError(400, "integration_scope_denied", "Anonymous channels cannot mint authenticated context.");
+  }
+  const timestamp = now();
+  await db.batch([
+    db.prepare(`UPDATE application_integrations SET name = ?2, allowed_origins_json = ?3, scopes_json = ?4,
+      enabled = ?5, channel_mode = ?6, form_version_id = ?7, context_schema_json = ?8, updated_at = ?9
+      WHERE id = ?1`).bind(
+        id, typeof value.name === "string" ? value.name.trim() : current.name,
+        canonicalJson(origins), canonicalJson(scopes),
+        typeof value.enabled === "boolean" ? (value.enabled ? 1 : 0) : current.enabled,
+        channelMode, formVersionId, canonicalJson(contextSchemaJson(contextSchema)), 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, 'integration.updated', ?3, ?4, 'application_integration', ?5, ?6, ?7)`).bind(crypto.randomUUID(), `integration-update:${idempotencyKey}`, session.actor.type, session.actor.id, id, canonicalJson({ changedFields: Object.keys(value) }), timestamp),
+  ]);
+  return (await loadIntegrationAdmin(db, id))!;
+}
+
+export async function rotateIntegrationKey(
+  db: D1Database,
+  id: string,
+  overlapSeconds: number,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<{ integrationId: string; keyId: string; apiKey: string }> {
+  if (!Number.isInteger(overlapSeconds) || overlapSeconds < 0 || overlapSeconds > 604_800) throw new ApiError(400, "integration_overlap_invalid", "overlap_seconds must be from 0 to 604800.");
+  if (!await db.prepare(`SELECT id FROM application_integrations WHERE id = ?1 LIMIT 1`).bind(id).first()) throw new ApiError(404, "integration_not_found", "The integration does not exist.");
+  if (await db.prepare(`SELECT id FROM audit_events WHERE idempotency_key = ?1 LIMIT 1`).bind(`integration-rotate:${idempotencyKey}`).first()) throw new ApiError(409, "integration_key_already_issued", "The replacement key was already issued and cannot be shown again. Rotate again with a new Idempotency-Key.");
+  const apiKey = `safest_${randomSecret()}`;
+  const keyId = `runtime-${crypto.randomUUID()}`;
+  const timestamp = now();
+  const oldExpiry = new Date(Date.now() + overlapSeconds * 1_000).toISOString();
+  await db.batch([
+    db.prepare(`UPDATE integration_api_keys SET expires_at = COALESCE(expires_at, ?2) WHERE integration_id = ?1 AND status = 'active'`).bind(id, oldExpiry),
+    db.prepare(`INSERT INTO integration_api_keys (id, integration_id, key_id, key_hash, status, valid_from, created_by, created_at) VALUES (?1, ?2, ?3, ?4, 'active', ?5, ?6, ?5)`).bind(crypto.randomUUID(), id, keyId, await sha256(`integration-key-v1:${apiKey}`), timestamp, session.actor.id),
+    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, 'integration.key_rotated', ?3, ?4, 'application_integration', ?5, ?6, ?7)`).bind(crypto.randomUUID(), `integration-rotate:${idempotencyKey}`, session.actor.type, session.actor.id, id, canonicalJson({ keyId, overlapSeconds }), timestamp),
+  ]);
+  return { integrationId: id, keyId, apiKey };
+}
+
+export async function revokeIntegrationKeys(
+  db: D1Database,
+  id: string,
+  keyId: string | null,
+  session: OperatorSession,
+  idempotencyKey: string,
+): Promise<number> {
+  const timestamp = now();
+  const changed = await db.prepare(`UPDATE integration_api_keys SET status = 'revoked', revoked_by = ?3, revoked_at = ?4 WHERE integration_id = ?1 AND (?2 IS NULL OR key_id = ?2) AND status = 'active'`)
+    .bind(id, keyId, session.actor.id, timestamp).run();
+  await 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, 'integration.key_revoked', ?3, ?4, 'application_integration', ?5, ?6, ?7)`)
+    .bind(crypto.randomUUID(), `integration-revoke:${idempotencyKey}`, session.actor.type, session.actor.id, id, canonicalJson({ keyId, count: changed.meta.changes }), timestamp).run();
+  return changed.meta.changes ?? 0;
+}
+
+export async function verifyFeature(env: Env, feature: string, actorId: string): Promise<Record<string, unknown>> {
+  const supported = new Set(["database", "workflow_runtime", "workers_ai", "object_storage", "queues", "email"]);
+  if (!supported.has(feature)) throw new ApiError(404, "feature_not_found", "The setup feature does not exist.");
+  let ready = false;
+  let capability: Record<string, unknown> = {};
+  let errorCode: string | null = null;
+  try {
+    if (feature === "database") { await env.DB.prepare("SELECT 1").first(); ready = true; }
+    else if (feature === "workflow_runtime") { ready = Boolean(env.WORKFLOWS && env.LOADER && env.WORKFLOW_ARTIFACTS); capability = { dynamicWorkflows: ready }; }
+    else if (feature === "workers_ai") { ready = Boolean((env as unknown as { AI?: unknown }).AI); }
+    else if (feature === "object_storage") { ready = Boolean(env.PROFILE_MEDIA && env.WORKFLOW_ARTIFACTS && env.EVIDENCE_OBJECTS && env.EXPORTS); capability = { buckets: ready ? 4 : 0 }; }
+    else if (feature === "queues") { ready = Boolean(env.REPORT_JOBS && env.DELIVERY_JOBS && env.CONTROL_JOBS); capability = { producers: ready ? 3 : 0 }; }
+    else { ready = Boolean((env as unknown as { EMAIL?: unknown }).EMAIL && env.EMAIL_FROM_ADDRESS); capability = { optional: true }; }
+  } catch { errorCode = "feature_probe_failed"; }
+  const state = ready ? "ready" : feature === "email" ? "disabled" : "setup_required";
+  const timestamp = now();
+  await env.DB.prepare(`INSERT INTO installation_features (installation_id, feature_key, state, capability_json, checked_at, error_code, revision) VALUES ('default', ?1, ?2, ?3, ?4, ?5, 1) ON CONFLICT(installation_id, feature_key) DO UPDATE SET state = excluded.state, capability_json = excluded.capability_json, checked_at = excluded.checked_at, error_code = excluded.error_code, revision = installation_features.revision + 1`)
+    .bind(feature, state, canonicalJson({ ...capability, checkedBy: actorId }), timestamp, errorCode).run();
+  return { feature, state, capability, checkedAt: timestamp, errorCode };
+}
+
+export async function metaVersion(db: D1Database): Promise<Record<string, unknown>> {
+  const migration = await db.prepare(`SELECT name FROM d1_migrations ORDER BY id DESC LIMIT 1`).first<{ name: string }>().catch(() => null);
+  return {
+    application: "0.1.0",
+    apiSchema: "1",
+    databaseMigration: migration?.name ?? "unknown",
+    workflowCompiler: WORKFLOW_COMPILER_VERSION,
+    workflowRuntimeProtocol: "1",
+  };
+}

package/template/src/intake-abuse.ts

@@ -0,0 +1,156 @@
+import { canonicalJson } from "./audit";
+import { sha256 } from "./report-crypto";
+import { ApiError } from "./report-http";
+import type { ReportSubmission } from "./report-types";
+
+export type IntakeDisposition = "accept" | "group" | "quarantine";
+
+export interface IntakeProtectionPlan {
+  decisionId: string;
+  requestId: string;
+  disposition: IntakeDisposition;
+  reasonCodes: string[];
+  networkKeyHash: string | null;
+  contactKeyHash: string | null;
+  targetKeyHash: string;
+  campaignFingerprint: string;
+  duplicateGroupId: string;
+  canonicalReportId: string | null;
+  existingMemberCount: number;
+  rateSummary: Record<string, number | string | boolean>;
+  surgeState: "normal" | "elevated" | "surge" | "recovery";
+  activateSurge: boolean;
+  route: boolean;
+}
+
+interface IntakeCountRow { count: number }
+
+function normalized(value: string): string {
+  return value.normalize("NFKC").trim().toLowerCase().replace(/\s+/gu, " ").slice(0, 2_048);
+}
+
+function networkPrefix(value: string | null): string | null {
+  if (!value) return null;
+  const ip = value.trim().toLowerCase();
+  if (/^\d{1,3}(?:\.\d{1,3}){3}$/u.test(ip)) return ip.split(".").slice(0, 3).join(".") + ".0/24";
+  if (/^[0-9a-f:]+$/u.test(ip) && ip.includes(":")) return ip.split(":").slice(0, 4).join(":") + "::/56";
+  return null;
+}
+
+async function protectedHash(pepper: string, namespace: string, value: string): Promise<string> {
+  return `sha256:${await sha256(`intake-${namespace}-v1:${pepper}:${value}`)}`;
+}
+
+function safeAnswerFingerprint(answers: ReportSubmission["answers"]): Record<string, unknown> {
+  return Object.fromEntries(Object.entries(answers).sort(([left], [right]) => left.localeCompare(right)).slice(0, 50).map(([key, value]) => [key, value]));
+}
+
+export async function planIntakeProtection(
+  db: D1Database,
+  submission: ReportSubmission,
+  input: {
+    pepper: string;
+    networkAddress?: string | null;
+    turnstileOutcome?: string | null;
+    surgeThresholdPerFiveMinutes: number;
+  },
+): Promise<IntakeProtectionPlan> {
+  if (new TextEncoder().encode(input.pepper).byteLength < 32) {
+    throw new ApiError(503, "intake_protection_misconfigured", "Report intake protection is not configured.");
+  }
+  const targetKey = `${normalized(submission.target.type)}:${normalized(submission.target.reference)}`;
+  const targetKeyHash = await protectedHash(input.pepper, "target", targetKey);
+  const contact = submission.reporter.email ?? submission.reporter.reference;
+  const contactKeyHash = contact
+    ? await protectedHash(input.pepper, "contact", normalized(contact)) : null;
+  const prefix = networkPrefix(input.networkAddress ?? null);
+  const networkKeyHash = prefix ? await protectedHash(input.pepper, "network", prefix) : null;
+  const fingerprintMaterial = canonicalJson({
+    target: targetKey,
+    reason: normalized(submission.reasonCode),
+    answers: safeAnswerFingerprint(submission.answers),
+    evidence: [...new Set(submission.evidence.references.map(normalized))].sort(),
+    trusted_facts: submission.trustedFacts,
+  });
+  const campaignFingerprint = await protectedHash(input.pepper, "fingerprint", fingerprintMaterial);
+  const duplicateGroupId = `duplicate-v1:${campaignFingerprint.slice("sha256:".length)}`;
+  const requestId = await protectedHash(input.pepper, "request", `${submission.integrationId}:${submission.idempotencyKey}`);
+  const fiveMinutesAgo = new Date(Date.now() - 5 * 60_000).toISOString();
+  const tenMinutesAgo = new Date(Date.now() - 10 * 60_000).toISOString();
+  const [overall, network, target, campaign, group, surge] = await Promise.all([
+    db.prepare(`SELECT COUNT(*) AS count FROM intake_decisions WHERE installation_id = 'default' AND source = 'public_page' AND created_at >= ?1`).bind(fiveMinutesAgo).first<IntakeCountRow>(),
+    networkKeyHash ? db.prepare(`SELECT COUNT(*) AS count FROM intake_decisions WHERE installation_id = 'default' AND network_key_hash = ?1 AND created_at >= ?2`).bind(networkKeyHash, tenMinutesAgo).first<IntakeCountRow>() : Promise.resolve(null),
+    db.prepare(`SELECT COUNT(*) AS count FROM intake_decisions WHERE installation_id = 'default' AND target_key_hash = ?1 AND created_at >= ?2`).bind(targetKeyHash, tenMinutesAgo).first<IntakeCountRow>(),
+    db.prepare(`SELECT COUNT(*) AS count FROM intake_decisions WHERE installation_id = 'default' AND campaign_fingerprint = ?1 AND created_at >= ?2`).bind(campaignFingerprint, tenMinutesAgo).first<IntakeCountRow>(),
+    db.prepare(`SELECT canonical_report_id AS canonicalReportId, member_count AS memberCount FROM duplicate_groups WHERE id = ?1 LIMIT 1`).bind(duplicateGroupId).first<{ canonicalReportId: string | null; memberCount: number }>(),
+    db.prepare(`SELECT state FROM abuse_surge_states WHERE installation_id = 'default' LIMIT 1`).first<{ state: "normal" | "elevated" | "surge" | "recovery" }>(),
+  ]);
+  const overallCount = Number(overall?.count ?? 0);
+  const networkCount = Number(network?.count ?? 0);
+  const targetCount = Number(target?.count ?? 0);
+  const campaignCount = Number(campaign?.count ?? 0);
+  const threshold = Math.max(25, Math.min(100_000, input.surgeThresholdPerFiveMinutes));
+  const activateSurge = submission.source === "public_page" && overallCount >= threshold;
+  const surgeState = activateSurge ? "surge" : surge?.state ?? "normal";
+  const reasonCodes: string[] = [];
+  let disposition: IntakeDisposition = group?.memberCount ? "group" : "accept";
+  if (group?.memberCount) reasonCodes.push("duplicate_fingerprint_match");
+  if (submission.source === "public_page") {
+    if (surgeState === "surge" && (campaignCount >= 1 || targetCount >= 5)) reasonCodes.push("surge_duplicate_quarantine");
+    if (campaignCount >= 5) reasonCodes.push("campaign_velocity_quarantine");
+    if (targetCount >= 20) reasonCodes.push("target_velocity_quarantine");
+    if (networkCount >= 20) reasonCodes.push("network_velocity_quarantine");
+    if (reasonCodes.some((code) => code.endsWith("_quarantine"))) disposition = "quarantine";
+  }
+  if (!reasonCodes.length) reasonCodes.push("intake_policy_passed");
+  return {
+    decisionId: crypto.randomUUID(),
+    requestId,
+    disposition,
+    reasonCodes,
+    networkKeyHash,
+    contactKeyHash,
+    targetKeyHash,
+    campaignFingerprint,
+    duplicateGroupId,
+    canonicalReportId: group?.canonicalReportId ?? null,
+    existingMemberCount: Number(group?.memberCount ?? 0),
+    rateSummary: {
+      public_five_minute_count: overallCount,
+      network_ten_minute_count: networkCount,
+      target_ten_minute_count: targetCount,
+      campaign_ten_minute_count: campaignCount,
+      surge_threshold: threshold,
+      turnstile_verified: input.turnstileOutcome === "verified",
+    },
+    surgeState,
+    activateSurge,
+    route: disposition !== "quarantine",
+  };
+}
+
+export async function maintainIntakeProtection(db: D1Database): Promise<void> {
+  const timestamp = new Date().toISOString();
+  const twoHoursAgo = new Date(Date.now() - 2 * 60 * 60_000).toISOString();
+  const sevenDaysAgo = new Date(Date.now() - 7 * 86_400_000).toISOString();
+  const tenMinutesAgo = new Date(Date.now() - 10 * 60_000).toISOString();
+  await db.batch([
+    db.prepare(`DELETE FROM intake_rate_limits WHERE updated_at < ?1`).bind(twoHoursAgo),
+    db.prepare(`
+      UPDATE intake_decisions SET network_key_hash = NULL, contact_key_hash = NULL
+      WHERE created_at < ?1 AND (network_key_hash IS NOT NULL OR contact_key_hash IS NOT NULL)
+    `).bind(sevenDaysAgo),
+    db.prepare(`
+      UPDATE abuse_surge_states SET state = 'recovery', revision = revision + 1,
+        updated_by = 'system:intake-guard', updated_at = ?1
+      WHERE installation_id = 'default' AND state = 'surge' AND recover_after <= ?1
+        AND (SELECT COUNT(*) FROM intake_decisions WHERE source = 'public_page' AND created_at >= ?2) < 25
+    `).bind(timestamp, tenMinutesAgo),
+    db.prepare(`
+      UPDATE abuse_surge_states SET state = 'normal', reason_codes_json = '[]',
+        activated_at = NULL, recover_after = NULL, revision = revision + 1,
+        updated_by = 'system:intake-guard', updated_at = ?1
+      WHERE installation_id = 'default' AND state = 'recovery' AND updated_at < ?2
+    `).bind(timestamp, tenMinutesAgo),
+  ]);
+}