create-safest-tools 0.2.0

package/template/src/report-turnstile.ts

@@ -0,0 +1,142 @@
+import { sha256 } from "./report-crypto";
+import { ApiError } from "./report-http";
+
+const SITEVERIFY_URL = "https://challenges.cloudflare.com/turnstile/v0/siteverify";
+const TEST_SITE_KEY = "1x00000000000000000000AA";
+const TEST_SECRET = "1x0000000000000000000000000000000AA";
+const MAX_RESPONSE_BYTES = 16 * 1024;
+
+export interface TurnstileConfig {
+  siteKey: string;
+  secret: string;
+  hostname: string;
+  testing: boolean;
+}
+
+export interface TurnstileExpectation {
+  action: string;
+  cdata?: string;
+}
+
+export interface VerifiedTurnstile {
+  hostname: string;
+  action: string;
+  cdata: string | null;
+  challengeTimestamp: string | null;
+}
+
+export function turnstileConfig(env: Env): TurnstileConfig {
+  const siteKey = env.TURNSTILE_SITE_KEY?.trim() ?? "";
+  const secret = env.TURNSTILE_SECRET_KEY?.trim() ?? "";
+  if (!siteKey || !secret) throw new ApiError(503, "public_reporting_not_configured", "Public reporting is unavailable until Turnstile is configured.");
+  const base = new URL(env.PUBLIC_BASE_URL);
+  const local = base.hostname === "localhost" || base.hostname === "127.0.0.1";
+  const testing = siteKey === TEST_SITE_KEY && secret === TEST_SECRET;
+  if ((siteKey === TEST_SITE_KEY) !== (secret === TEST_SECRET) || testing && !local) {
+    throw new ApiError(503, "turnstile_misconfigured", "Turnstile test keys may only be used together on localhost.");
+  }
+  return { siteKey, secret, hostname: base.hostname.toLowerCase(), testing };
+}
+
+async function boundedJson(response: Response): Promise<Record<string, unknown> | null> {
+  const declared = Number.parseInt(response.headers.get("content-length") ?? "0", 10);
+  if (declared > MAX_RESPONSE_BYTES) {
+    await response.body?.cancel().catch(() => {});
+    return null;
+  }
+  const bytes = new Uint8Array(await response.arrayBuffer());
+  if (bytes.byteLength > MAX_RESPONSE_BYTES) return null;
+  try {
+    const value: unknown = JSON.parse(new TextDecoder().decode(bytes));
+    return value && typeof value === "object" && !Array.isArray(value) ? value as Record<string, unknown> : null;
+  } catch {
+    return null;
+  }
+}
+
+export async function verifyTurnstile(
+  token: unknown,
+  remoteIp: string | null,
+  config: TurnstileConfig,
+  expectation: TurnstileExpectation,
+  fetchImpl: typeof fetch = fetch,
+): Promise<VerifiedTurnstile> {
+  if (typeof token !== "string" || !token.trim() || token.length > 2_048) {
+    throw new ApiError(400, "turnstile_token_required", "Complete the anti-abuse check before submitting.");
+  }
+  const controller = new AbortController();
+  const timeout = setTimeout(() => controller.abort("turnstile_timeout"), 5_000);
+  try {
+    const body = new URLSearchParams({
+      secret: config.secret,
+      response: token,
+      idempotency_key: crypto.randomUUID(),
+    });
+    if (remoteIp) body.set("remoteip", remoteIp);
+    const response = await fetchImpl(SITEVERIFY_URL, {
+      method: "POST",
+      headers: { "content-type": "application/x-www-form-urlencoded" },
+      body,
+      signal: controller.signal,
+    });
+    if (!response.ok) throw new ApiError(503, "turnstile_unavailable", "The anti-abuse check is temporarily unavailable.");
+    const result = await boundedJson(response);
+    if (!result) throw new ApiError(503, "turnstile_unavailable", "The anti-abuse check returned an invalid response.");
+    if (result.success !== true) throw new ApiError(400, "turnstile_rejected", "The anti-abuse check was not accepted.");
+    const observedHostname = typeof result.hostname === "string" ? result.hostname.toLowerCase() : "";
+    const acceptedTestHostname = config.testing && observedHostname === "example.com";
+    if (observedHostname !== config.hostname && !acceptedTestHostname) {
+      throw new ApiError(400, "turnstile_hostname_mismatch", "The anti-abuse check was completed for a different site.");
+    }
+    if (!config.testing && result.action !== expectation.action) {
+      throw new ApiError(400, "turnstile_action_mismatch", "The anti-abuse check was completed for a different action.");
+    }
+    if (!config.testing && expectation.cdata !== undefined && result.cdata !== expectation.cdata) {
+      throw new ApiError(400, "turnstile_context_mismatch", "The anti-abuse check does not match this report window.");
+    }
+    return {
+      hostname: observedHostname,
+      action: typeof result.action === "string" ? result.action : expectation.action,
+      cdata: typeof result.cdata === "string" ? result.cdata : null,
+      challengeTimestamp: typeof result.challenge_ts === "string" ? result.challenge_ts : null,
+    };
+  } catch (error) {
+    if (error instanceof ApiError) throw error;
+    const timedOut = controller.signal.aborted || error instanceof DOMException && error.name === "AbortError";
+    throw new ApiError(503, timedOut ? "turnstile_timeout" : "turnstile_unavailable", "The anti-abuse check is temporarily unavailable.");
+  } finally {
+    clearTimeout(timeout);
+  }
+}
+
+export async function verifyPublicTurnstile(
+  token: unknown,
+  remoteIp: string | null,
+  config: TurnstileConfig,
+  fetchImpl: typeof fetch = fetch,
+): Promise<void> {
+  await verifyTurnstile(token, remoteIp, config, { action: "report_submit" }, fetchImpl);
+}
+
+export async function enforcePublicRateLimit(
+  db: D1Database,
+  remoteIp: string | null,
+  pepper: string,
+  maximum: number,
+  timestamp = Date.now(),
+): Promise<void> {
+  if (new TextEncoder().encode(pepper).byteLength < 32) throw new ApiError(503, "rate_limit_misconfigured", "Public reporting rate limits are not configured.");
+  const bucket = new Date(Math.floor(timestamp / 600_000) * 600_000).toISOString();
+  const bucketKey = await sha256(`public-report-v1:${pepper}:${remoteIp ?? "unavailable"}`);
+  const at = new Date(timestamp).toISOString();
+  const row = await db.prepare(`
+    INSERT INTO intake_rate_limits (bucket_key, window_start, request_count, updated_at)
+    VALUES (?1, ?2, 1, ?3)
+    ON CONFLICT(bucket_key, window_start) DO UPDATE SET
+      request_count = intake_rate_limits.request_count + 1,
+      updated_at = excluded.updated_at
+    WHERE intake_rate_limits.request_count < ?4
+    RETURNING request_count
+  `).bind(bucketKey, bucket, at, Math.max(1, Math.min(100, maximum))).first<{ request_count: number }>();
+  if (!row) throw new ApiError(429, "public_report_rate_limited", "Too many public reports were submitted from this network. Try again later.");
+}

package/template/src/report-types.ts

@@ -0,0 +1,224 @@
+export type ReportSource = "signed_widget" | "public_page" | "server_api";
+export type ReportState =
+  | "received"
+  | "human_review"
+  | "ai_review"
+  | "awaiting_reporter"
+  | "resolved_by_human"
+  | "resolved_by_ai"
+  | "human_review_requested"
+  | "appealed"
+  | "closed";
+
+export type ParticipantAudience = "reporter" | "affected_user";
+export type OperatorRole = "owner" | "administrator" | "workflow_author" | "reviewer" | "appeal_reviewer" | "quality_reviewer" | "operations" | "auditor";
+
+export interface OperatorPermissions {
+  readReports: boolean;
+  readEvidence: boolean;
+  readSensitiveEvidence: boolean;
+  manageEvidence: boolean;
+  claimReports: boolean;
+  reviewTasks: boolean;
+  assignTasks: boolean;
+  messageReporters: boolean;
+  messageParticipants: boolean;
+  decideReports: boolean;
+  reassignReports: boolean;
+  approveActions: boolean;
+  operateActions: boolean;
+  reviewAppeals: boolean;
+  decideAppeals: boolean;
+  reviewQuality: boolean;
+  runShadow: boolean;
+  runEnrichments: boolean;
+  manageForms: boolean;
+  managePolicies: boolean;
+  manageTemplates: boolean;
+  manageQueues: boolean;
+  manageRouting: boolean;
+  manageWorkflowPins: boolean;
+  manageConnections: boolean;
+  publishConnections: boolean;
+  manageComponents: boolean;
+  publishComponents: boolean;
+  manageWorkflows: boolean;
+  publishWorkflows: boolean;
+  manageAi: boolean;
+  manageBudgets: boolean;
+  useAssistant: boolean;
+  readRuns: boolean;
+  operateRuns: boolean;
+  searchWorkspace: boolean;
+  readAnalytics: boolean;
+  readAi: boolean;
+  readOperations: boolean;
+  operateSystem: boolean;
+  manageConfiguration: boolean;
+  managePeople: boolean;
+  manageInstallation: boolean;
+  viewAudit: boolean;
+  exportData: boolean;
+  manageGovernance: boolean;
+  manageIntegrations: boolean;
+}
+
+export interface OperatorSession {
+  actor: { type: "cloudflare_access" | "admin_key" | "operator_user"; id: string };
+  authMethod: "cloudflare_access" | "admin_key" | "better_auth";
+  verified: boolean;
+  displayName: string;
+  email?: string;
+  avatarUrl?: string;
+  roles: OperatorRole[];
+  permissions: OperatorPermissions;
+  queueScope?: string[] | null;
+  fieldScope?: Record<string, string[]> | null;
+}
+
+export interface ReportTargetInput {
+  type: string;
+  reference: string;
+  ownerReference?: string;
+  customerUrl?: string;
+}
+
+export interface ReportReporterInput {
+  reference?: string;
+  email?: string;
+  contactMode: "customer_notification" | "none";
+}
+
+export interface EvidenceInput {
+  mode: "reference_only";
+  references: string[];
+}
+
+export interface ReportSubmission {
+  schemaVersion: "1";
+  idempotencyKey: string;
+  source: ReportSource;
+  integrationId: string;
+  formVersionId: string;
+  reporter: ReportReporterInput;
+  target: ReportTargetInput;
+  reasonCode: string;
+  answers: Record<string, string | boolean | number | string[]>;
+  evidence: EvidenceInput;
+  locale: string;
+  consentNotice: string;
+  consentedAt: string;
+  submittedAt: string;
+  contextToken?: string;
+  trustedFacts: Record<string, string | number | boolean | null>;
+  routingFacts: Record<string, string | number | boolean | null>;
+  contextJti?: string;
+  contextId?: string;
+}
+
+export interface ContextClaims {
+  version: 2;
+  iss: string;
+  aud: "safest-resolve-reports";
+  integrationId: string;
+  contextId: string;
+  formVersionId: string;
+  jti: string;
+  iat: number;
+  exp: number;
+  origin: string;
+}
+
+export interface StoredReportContext {
+  id: string;
+  integrationId: string;
+  formVersionId: string;
+  origin: string;
+  reporter: { reference?: string };
+  target: ReportTargetInput;
+  trustedFacts: Record<string, string | number | boolean | null>;
+  routingFacts: Record<string, string | number | boolean | null>;
+  contextSchemaVersion: number;
+  assertionSource: "customer_backend" | "resolve_hosted";
+  createdAt: string;
+  expiresAt: string;
+  usedAt: string | null;
+}
+
+export interface IntakeReceipt {
+  reportId: string;
+  reference: string;
+  state: ReportState;
+  receivedAt: string;
+  idempotentReplay: boolean;
+}
+
+export interface ReportJob {
+  version: 1;
+  jobId: string;
+  type: "route_report";
+  reportId: string;
+}
+
+export interface AiJob {
+  version: 1;
+  jobId: string;
+  type: "process_ai_report";
+  reportId: string;
+}
+
+export interface WorkflowDispatchJob {
+  version: 1;
+  jobId: string;
+  type: "dispatch_workflow";
+  runId: string;
+  outboxId: string;
+}
+
+export interface EvidenceFetchJob {
+  version: 1;
+  jobId: string;
+  type: "fetch_evidence";
+  reportId: string;
+  requestId: string;
+}
+
+export interface ActionProposalJob {
+  version: 1;
+  jobId: string;
+  type: "apply_action_proposal";
+  proposalId: string;
+  runId: string;
+}
+
+export interface DeliveryJob {
+  version: 1;
+  jobId: string;
+  type: "deliver_action" | "deliver_notification" | "deliver_email";
+  outboxId: string;
+}
+
+export interface InboxReport {
+  id: string;
+  reference: string;
+  state: ReportState;
+  priority: number;
+  reasonCode: string;
+  queueId: string | null;
+  targetType: string;
+  targetReference: string;
+  submittedAt: string;
+  receivedAt: string;
+  updatedAt: string;
+  dueAt: string | null;
+  claim: {
+    reviewerId: string;
+    claimedAt: string;
+    expiresAt: string;
+    analyst: {
+      displayName: string;
+      avatarUrl: string | null;
+      avatarColor: string;
+    };
+  } | null;
+}

package/template/src/report-validation.ts

@@ -0,0 +1,279 @@
+import { ApiError } from "./report-http";
+import type { ContextClaims, ReportSource, ReportSubmission, ReportTargetInput, StoredReportContext } from "./report-types";
+
+const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/u;
+const LOCALE_PATTERN = /^[A-Za-z]{2,3}(?:-[A-Za-z0-9]{2,8})*$/u;
+const SOURCES = new Set<ReportSource>(["signed_widget", "public_page", "server_api"]);
+const CONTACT_MODES = new Set(["customer_notification", "none"] as const);
+const EMAIL_PATTERN = /^[A-Z0-9.!#$%&'*+/=?^_`{|}~-]+@[A-Z0-9](?:[A-Z0-9-]{0,61}[A-Z0-9])?(?:\.[A-Z0-9](?:[A-Z0-9-]{0,61}[A-Z0-9])?)+$/iu;
+const ANSWER_KEYS = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/u;
+const MAX_ANSWER_BYTES = 16 * 1024;
+
+function object(value: unknown, field: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) throw new ApiError(400, "invalid_field", `${field} must be an object.`, { field });
+  return value as Record<string, unknown>;
+}
+
+function knownFields(value: Record<string, unknown>, allowed: readonly string[], field = "body"): void {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length) throw new ApiError(400, "unknown_field", `${field} contains unsupported fields.`, { field, fields: unknown.slice(0, 10) });
+}
+
+function text(value: unknown, field: string, maximum: number, minimum = 1): string {
+  if (typeof value !== "string") throw new ApiError(400, "invalid_field", `${field} must be text.`, { field });
+  const normalized = value.trim();
+  if (normalized.length < minimum || normalized.length > maximum) {
+    throw new ApiError(400, "invalid_field", `${field} must contain ${minimum}-${maximum} characters.`, { field });
+  }
+  return normalized;
+}
+
+function identifier(value: unknown, field: string, maximum = 200): string {
+  const normalized = text(value, field, maximum);
+  if (!ID_PATTERN.test(normalized)) throw new ApiError(400, "invalid_field", `${field} contains unsupported characters.`, { field });
+  return normalized;
+}
+
+function optionalIdentifier(value: unknown, field: string, maximum = 200): string | undefined {
+  return value === undefined || value === null || value === "" ? undefined : identifier(value, field, maximum);
+}
+
+function isoTimestamp(value: unknown, field: string, now: number, maximumSkewMs: number): string {
+  const normalized = text(value, field, 40);
+  const timestamp = Date.parse(normalized);
+  if (!Number.isFinite(timestamp) || Math.abs(timestamp - now) > maximumSkewMs) {
+    throw new ApiError(400, "invalid_field", `${field} is outside the accepted time window.`, { field });
+  }
+  return new Date(timestamp).toISOString();
+}
+
+function safeUrl(value: unknown, field: string): string | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  const normalized = text(value, field, 2_048);
+  try {
+    const url = new URL(normalized);
+    const local = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+    if ((url.protocol !== "https:" && !(local && url.protocol === "http:")) || url.username || url.password) throw new Error("unsafe URL");
+    return url.toString();
+  } catch {
+    throw new ApiError(400, "invalid_field", `${field} must be an HTTPS URL without embedded credentials (localhost HTTP is allowed for development).`, { field });
+  }
+}
+
+function safeOrigin(value: unknown, field: string): string | undefined {
+  if (value === undefined || value === null || value === "") return undefined;
+  const normalized = text(value, field, 2_048);
+  try {
+    const url = new URL(normalized);
+    const local = url.hostname === "localhost" || url.hostname === "127.0.0.1" || url.hostname === "[::1]";
+    if ((url.protocol !== "https:" && !(local && url.protocol === "http:")) || url.username || url.password
+      || url.pathname !== "/" || url.search || url.hash) throw new Error("unsafe origin");
+    return url.origin;
+  } catch {
+    throw new ApiError(400, "invalid_field", `${field} must be an HTTPS origin (HTTP is allowed for localhost).`, { field });
+  }
+}
+
+function target(value: unknown, field: string): ReportTargetInput {
+  const input = object(value, field);
+  knownFields(input, ["type", "reference", "owner_reference", "customer_url"], field);
+  return {
+    type: identifier(input.type, `${field}.type`, 64),
+    reference: identifier(input.reference, `${field}.reference`, 500),
+    ...(optionalIdentifier(input.owner_reference, `${field}.owner_reference`, 500) ? { ownerReference: optionalIdentifier(input.owner_reference, `${field}.owner_reference`, 500) } : {}),
+    ...(safeUrl(input.customer_url, `${field}.customer_url`) ? { customerUrl: safeUrl(input.customer_url, `${field}.customer_url`) } : {}),
+  };
+}
+
+function email(value: unknown, field: string): string {
+  const normalized = text(value, field, 254).toLowerCase();
+  const [local = "", domain = ""] = normalized.split("@");
+  if (!EMAIL_PATTERN.test(normalized) || local.length > 64 || domain.length > 253) {
+    throw new ApiError(400, "invalid_field", `${field} must be a valid email address.`, { field });
+  }
+  return normalized;
+}
+
+function reporter(
+  value: unknown,
+  field: string,
+  options: { requireEmail?: boolean } = {},
+): { reference?: string; email?: string; contactMode: "customer_notification" | "none" } {
+  const input = object(value, field);
+  knownFields(input, ["reference", "email", "contact_mode"], field);
+  const contactMode = text(input.contact_mode ?? "customer_notification", `${field}.contact_mode`, 32) as "customer_notification" | "none";
+  if (!CONTACT_MODES.has(contactMode)) throw new ApiError(400, "invalid_field", `${field}.contact_mode is unsupported.`, { field: `${field}.contact_mode` });
+  const reference = optionalIdentifier(input.reference, `${field}.reference`, 500);
+  const emailAddress = input.email === undefined || input.email === null || input.email === "" ? undefined : email(input.email, `${field}.email`);
+  if (options.requireEmail && !emailAddress) {
+    throw new ApiError(400, "reporter_email_required", "Enter an email address so the safety team can contact you about this report.", { field: `${field}.email` });
+  }
+  if (emailAddress && contactMode === "none") {
+    throw new ApiError(400, "invalid_field", `${field}.contact_mode must allow notifications when an email is provided.`, { field: `${field}.contact_mode` });
+  }
+  return { ...(reference ? { reference } : {}), ...(emailAddress ? { email: emailAddress } : {}), contactMode };
+}
+
+function facts(value: unknown, field: string): Record<string, string | number | boolean | null> {
+  const input = value === undefined ? {} : object(value, field);
+  if (Object.keys(input).length > 50) throw new ApiError(400, "invalid_field", `${field} has too many values.`, { field });
+  const result: Record<string, string | number | boolean | null> = {};
+  for (const [key, child] of Object.entries(input)) {
+    if (!ANSWER_KEYS.test(key) || !["string", "number", "boolean"].includes(typeof child) && child !== null) {
+      throw new ApiError(400, "invalid_field", `${field}.${key} has an unsupported key or value.`, { field: `${field}.${key}` });
+    }
+    if (typeof child === "string" && child.length > 500) throw new ApiError(400, "invalid_field", `${field}.${key} is too long.`, { field: `${field}.${key}` });
+    if (typeof child === "number" && !Number.isFinite(child)) throw new ApiError(400, "invalid_field", `${field}.${key} must be finite.`, { field: `${field}.${key}` });
+    result[key] = child as string | number | boolean | null;
+  }
+  return result;
+}
+
+function answers(value: unknown): Record<string, string | boolean | number | string[]> {
+  const input = object(value, "answers");
+  if (Object.keys(input).length > 50) throw new ApiError(400, "invalid_field", "answers has too many fields.", { field: "answers" });
+  const result: Record<string, string | boolean | number | string[]> = {};
+  for (const [key, child] of Object.entries(input)) {
+    if (!ANSWER_KEYS.test(key)) throw new ApiError(400, "invalid_field", `answers.${key} has an unsupported key.`, { field: `answers.${key}` });
+    const valid = typeof child === "boolean"
+      || typeof child === "number" && Number.isFinite(child)
+      || typeof child === "string" && child.length <= 4_000
+      || Array.isArray(child) && child.length <= 20 && child.every((item) => typeof item === "string" && item.length <= 200);
+    if (!valid) throw new ApiError(400, "invalid_field", `answers.${key} has an unsupported value.`, { field: `answers.${key}` });
+    result[key] = child as string | boolean | number | string[];
+  }
+  if (new TextEncoder().encode(JSON.stringify(result)).byteLength > MAX_ANSWER_BYTES) {
+    throw new ApiError(400, "invalid_field", "answers is too large.", { field: "answers" });
+  }
+  return result;
+}
+
+function evidence(value: unknown): { mode: "reference_only"; references: string[] } {
+  const input = object(value ?? { mode: "reference_only", references: [] }, "evidence");
+  knownFields(input, ["mode", "references"], "evidence");
+  if (input.mode !== "reference_only") throw new ApiError(400, "invalid_field", "Only reference_only evidence is enabled.", { field: "evidence.mode" });
+  if (!Array.isArray(input.references) || input.references.length > 25) {
+    throw new ApiError(400, "invalid_field", "evidence.references must contain at most 25 references.", { field: "evidence.references" });
+  }
+  const references = input.references.map((item, index) => {
+    if (typeof item !== "string") throw new ApiError(400, "invalid_field", `evidence.references[${index}] must be text.`, { field: `evidence.references[${index}]` });
+    const normalized = item.trim();
+    if (!normalized || normalized.length > 2_048) throw new ApiError(400, "invalid_field", `evidence.references[${index}] is invalid.`, { field: `evidence.references[${index}]` });
+    if (normalized.includes("://")) {
+      const url = safeUrl(normalized, `evidence.references[${index}]`);
+      if (!url) throw new ApiError(400, "invalid_field", `evidence.references[${index}] is invalid.`, { field: `evidence.references[${index}]` });
+      return url;
+    }
+    return identifier(normalized, `evidence.references[${index}]`, 500);
+  });
+  if (new Set(references).size !== references.length) throw new ApiError(400, "invalid_field", "evidence.references contains duplicates.", { field: "evidence.references" });
+  return { mode: "reference_only", references };
+}
+
+function source(value: unknown, expected: ReportSource): ReportSource {
+  const normalized = text(value, "source", 32) as ReportSource;
+  if (!SOURCES.has(normalized) || normalized !== expected) throw new ApiError(400, "invalid_source", `source must be ${expected}.`, { field: "source" });
+  return normalized;
+}
+
+export interface ContextMintInput {
+  reporter: { reference?: string };
+  target: ReportTargetInput;
+  trustedFacts: Record<string, string | number | boolean | null>;
+  origin?: string;
+  formVersionId?: string;
+}
+
+export function parseContextMintInput(body: Record<string, unknown>): ContextMintInput {
+  knownFields(body, ["reporter", "target", "trusted_facts", "origin", "form_version"]);
+  const reporterInput = reporter(body.reporter ?? { contact_mode: "customer_notification" }, "reporter");
+  const origin = safeOrigin(body.origin, "origin");
+  const formVersionId = body.form_version === undefined ? undefined : identifier(body.form_version, "form_version", 100);
+  return {
+    reporter: { ...(reporterInput.reference ? { reference: reporterInput.reference } : {}) },
+    target: target(body.target, "target"),
+    trustedFacts: facts(body.trusted_facts, "trusted_facts"),
+    ...(origin ? { origin } : {}),
+    ...(formVersionId ? { formVersionId } : {}),
+  };
+}
+
+function common(
+  body: Record<string, unknown>,
+  expectedSource: ReportSource,
+  now: number,
+): Pick<ReportSubmission, "schemaVersion" | "idempotencyKey" | "source" | "formVersionId" | "reasonCode" | "answers" | "evidence" | "locale" | "consentNotice" | "consentedAt" | "submittedAt"> {
+  if (body.schema_version !== "1") throw new ApiError(400, "unsupported_schema_version", "schema_version must be 1.", { field: "schema_version" });
+  const locale = text(body.locale ?? "en", "locale", 35);
+  if (!LOCALE_PATTERN.test(locale)) throw new ApiError(400, "invalid_field", "locale is invalid.", { field: "locale" });
+  const consent = object(body.consent, "consent");
+  knownFields(consent, ["notice", "accepted_at"], "consent");
+  return {
+    schemaVersion: "1",
+    idempotencyKey: identifier(body.idempotency_key, "idempotency_key", 200),
+    source: source(body.source, expectedSource),
+    formVersionId: identifier(body.form_version, "form_version", 100),
+    reasonCode: identifier(body.reason_code, "reason_code", 100),
+    answers: answers(body.answers),
+    evidence: evidence(body.evidence),
+    locale,
+    consentNotice: text(consent.notice, "consent.notice", 2_000),
+    consentedAt: isoTimestamp(consent.accepted_at, "consent.accepted_at", now, 24 * 60 * 60 * 1_000),
+    submittedAt: isoTimestamp(body.submitted_at, "submitted_at", now, 24 * 60 * 60 * 1_000),
+  };
+}
+
+export function parseWidgetReport(
+  body: Record<string, unknown>,
+  claims: ContextClaims,
+  context: StoredReportContext,
+  now = Date.now(),
+): ReportSubmission {
+  knownFields(body, ["schema_version", "idempotency_key", "source", "form_version", "reason_code", "answers", "evidence", "locale", "consent", "submitted_at", "context_token", "turnstile_token"]);
+  const parsed = common(body, "signed_widget", now);
+  if (parsed.formVersionId !== claims.formVersionId || parsed.formVersionId !== context.formVersionId) {
+    throw new ApiError(400, "form_context_mismatch", "The report form does not match its trusted context.", { field: "form_version" });
+  }
+  return {
+    ...parsed,
+    integrationId: claims.integrationId,
+    reporter: { ...(context.reporter.reference ? { reference: context.reporter.reference } : {}), contactMode: "customer_notification" },
+    target: context.target,
+    trustedFacts: context.trustedFacts,
+    routingFacts: context.routingFacts,
+    contextJti: claims.jti,
+    contextId: claims.contextId,
+    contextToken: text(body.context_token, "context_token", 16 * 1024),
+  };
+}
+
+export function parseServerReport(body: Record<string, unknown>, integrationId: string, now = Date.now()): ReportSubmission {
+  knownFields(body, ["schema_version", "idempotency_key", "source", "form_version", "reporter", "target", "reason_code", "answers", "evidence", "locale", "consent", "submitted_at", "trusted_facts"]);
+  return {
+    ...common(body, "server_api", now),
+    integrationId,
+    reporter: reporter(body.reporter, "reporter"),
+    target: target(body.target, "target"),
+    trustedFacts: facts(body.trusted_facts, "trusted_facts"),
+    routingFacts: facts(body.trusted_facts, "trusted_facts"),
+  };
+}
+
+export function parsePublicReport(body: Record<string, unknown>, integrationId: string, now = Date.now()): ReportSubmission {
+  knownFields(body, [
+    "schema_version", "idempotency_key", "source", "form_version", "reporter", "target", "reason_code",
+    "answers", "evidence", "locale", "consent", "submitted_at", "turnstile_token",
+  ]);
+  const reportTarget = target(body.target, "target");
+  if (reportTarget.ownerReference) {
+    throw new ApiError(400, "untrusted_owner_reference", "Public reports cannot assert who owns the target.", { field: "target.owner_reference" });
+  }
+  return {
+    ...common(body, "public_page", now),
+    integrationId,
+    reporter: reporter(body.reporter, "reporter", { requireEmail: true }),
+    target: reportTarget,
+    trustedFacts: {},
+    routingFacts: {},
+  };
+}