create-safest-tools 0.4.2 → 0.5.1

package/template/src/report-email-inbound.ts

@@ -0,0 +1,169 @@
+import PostalMime from "postal-mime";
+import { canonicalJson } from "./audit";
+import { decryptReportContact, secretsEqual, sha256 } from "./report-crypto";
+import { reporterEmailFrom, verifyReporterReplyToken } from "./report-email";
+import type { ReportState } from "./report-types";
+
+const MAX_INBOUND_BYTES = 5 * 1024 * 1024;
+const MAX_MESSAGE_LENGTH = 8_000;
+
+interface ReplyReportRow {
+  id: string;
+  state: ReportState;
+  participantId: string;
+  contactCiphertext: string | null;
+}
+
+function now(): string {
+  return new Date().toISOString();
+}
+
+function htmlToText(value: string): string {
+  return value
+    .replace(/<(script|style)\b[^>]*>[\s\S]*?<\/\1>/giu, "")
+    .replace(/<\s*br\s*\/?>/giu, "\n")
+    .replace(/<\/(p|div|li|tr|h[1-6])\s*>/giu, "\n")
+    .replace(/<[^>]+>/gu, "")
+    .replaceAll("&nbsp;", " ")
+    .replaceAll("&amp;", "&")
+    .replaceAll("&lt;", "<")
+    .replaceAll("&gt;", ">")
+    .replaceAll("&quot;", '"')
+    .replaceAll("&#39;", "'");
+}
+
+export function readableReplyBody(text: string): string {
+  const normalized = text.replaceAll("\r\n", "\n").replaceAll("\r", "\n");
+  const kept: string[] = [];
+  for (const line of normalized.split("\n")) {
+    const trimmed = line.trim();
+    if (/^On .+wrote:$/iu.test(trimmed)
+      || /^-{2,}\s*(?:Original Message|Forwarded message)\s*-*$/iu.test(trimmed)
+      || (/^From:\s+/iu.test(trimmed) && kept.length > 0)) break;
+    if (/^>/u.test(trimmed)) continue;
+    kept.push(line.replace(/[ \t]+$/u, ""));
+  }
+  return kept.join("\n").replace(/\n{3,}/gu, "\n\n").trim().slice(0, MAX_MESSAGE_LENGTH);
+}
+
+function replyTokenFromRecipient(recipient: string, baseAddress: string): string | null {
+  const recipientAt = recipient.lastIndexOf("@");
+  const baseAt = baseAddress.lastIndexOf("@");
+  if (recipientAt < 1 || baseAt < 1) return null;
+  const local = recipient.slice(0, recipientAt).toLowerCase();
+  const domain = recipient.slice(recipientAt + 1).toLowerCase();
+  const baseLocal = baseAddress.slice(0, baseAt).toLowerCase();
+  const baseDomain = baseAddress.slice(baseAt + 1).toLowerCase();
+  if (domain !== baseDomain || !local.startsWith(`${baseLocal}+`)) return null;
+  return local.slice(baseLocal.length + 1);
+}
+
+async function recordUnmatchedEmail(db: D1Database, message: ForwardableEmailMessage, reason: string): Promise<void> {
+  const timestamp = now();
+  const fingerprint = await sha256(`inbound-email:${reason}:${message.to.toLowerCase()}:${message.from.toLowerCase()}:${message.headers.get("message-id") ?? ""}`);
+  await db.prepare(`
+    INSERT INTO operations_incidents (
+      id, installation_id, incident_key, severity, category, state, title, summary,
+      entity_type, entity_id, occurrence_count, first_seen_at, last_seen_at, metadata_json
+    ) VALUES (?1, 'default', ?2, 'low', 'inbound_email_unmatched', 'open',
+      'Reporter email could not be matched', ?3, 'inbound_email', ?4, 1, ?5, ?5, ?6)
+    ON CONFLICT(installation_id, incident_key) DO UPDATE SET
+      state = 'open', occurrence_count = operations_incidents.occurrence_count + 1,
+      last_seen_at = excluded.last_seen_at, metadata_json = excluded.metadata_json,
+      resolved_by = NULL, resolved_at = NULL, resolution_summary = NULL
+  `).bind(
+    crypto.randomUUID(), `inbound-email:${fingerprint}`, `An inbound reporter email was not attached to a case (${reason}).`,
+    fingerprint.slice(0, 100), timestamp,
+    canonicalJson({ reason, recipientDomain: message.to.split("@").at(-1)?.toLowerCase() ?? "", rawSize: message.rawSize }),
+  ).run();
+}
+
+function nextState(state: ReportState): ReportState {
+  if (state === "awaiting_reporter") return "human_review";
+  if (["resolved_by_human", "resolved_by_ai", "closed"].includes(state)) return "human_review_requested";
+  return state;
+}
+
+export async function receiveReporterEmail(
+  message: ForwardableEmailMessage,
+  env: Env,
+): Promise<{ reportId: string | null; stored: boolean }> {
+  if (message.rawSize > MAX_INBOUND_BYTES) {
+    message.setReject("Reply is too large. Please send a text-only reply under 5 MB.");
+    return { reportId: null, stored: false };
+  }
+  const baseAddress = reporterEmailFrom(env);
+  const token = replyTokenFromRecipient(message.to, baseAddress);
+  const claim = token ? await verifyReporterReplyToken(token, env.CONTEXT_SIGNING_SECRET) : null;
+  if (!claim) {
+    await recordUnmatchedEmail(env.DB, message, token ? "invalid_or_expired_reply_token" : "reply_token_missing");
+    return { reportId: null, stored: false };
+  }
+  const report = await env.DB.prepare(`
+    SELECT r.id, r.state, p.id AS participantId, p.contact_ciphertext AS contactCiphertext
+    FROM reports r
+    JOIN report_participants p ON p.report_id = r.id AND p.audience = 'reporter'
+    WHERE r.public_reference = ?1
+    LIMIT 1
+  `).bind(claim.publicReference).first<ReplyReportRow>();
+  if (!report?.contactCiphertext) {
+    await recordUnmatchedEmail(env.DB, message, "report_or_reporter_contact_missing");
+    return { reportId: null, stored: false };
+  }
+  const expectedSender = (await decryptReportContact(
+    env.CREDENTIAL_ENCRYPTION_KEY, report.contactCiphertext, report.id, "reporter",
+  )).trim().toLowerCase();
+  if (!await secretsEqual(message.from.trim().toLowerCase(), expectedSender)) {
+    await recordUnmatchedEmail(env.DB, message, "sender_mismatch");
+    return { reportId: null, stored: false };
+  }
+  const parsed = await PostalMime.parse(message.raw, {
+    maxNestingDepth: 15,
+    maxHeadersSize: 256 * 1024,
+    maxRfc822NestingDepth: 3,
+  });
+  const body = readableReplyBody(parsed.text || (parsed.html ? htmlToText(parsed.html) : ""));
+  if (!body) {
+    await recordUnmatchedEmail(env.DB, message, "empty_reply_body");
+    return { reportId: report.id, stored: false };
+  }
+  const fingerprint = await sha256(canonicalJson({
+    messageId: parsed.messageId || message.headers.get("message-id") || "",
+    from: message.from.toLowerCase(),
+    reportId: report.id,
+    body,
+  }));
+  const idempotencyKey = `inbound-email:${fingerprint}`;
+  const existing = await env.DB.prepare(`SELECT id FROM case_messages WHERE report_id = ?1 AND idempotency_key = ?2 LIMIT 1`)
+    .bind(report.id, idempotencyKey).first<{ id: string }>();
+  if (existing) return { reportId: report.id, stored: false };
+  const receivedAt = now();
+  const targetState = nextState(report.state);
+  const messageId = crypto.randomUUID();
+  const statements: D1PreparedStatement[] = [
+    env.DB.prepare(`
+      INSERT OR IGNORE INTO case_messages (
+        id, report_id, audience, direction, sender_type, sender_id, body,
+        automated, delivery_state, created_at, idempotency_key, audience_checked_at
+      ) VALUES (?1, ?2, 'reporter', 'inbound', 'reporter', ?3, ?4, 0, 'not_required', ?5, ?6, ?5)
+    `).bind(messageId, report.id, report.participantId, body, receivedAt, idempotencyKey),
+    env.DB.prepare(`UPDATE reports SET state = ?2, updated_at = ?3 WHERE id = ?1`).bind(report.id, targetState, receivedAt),
+    env.DB.prepare(`
+      INSERT OR IGNORE INTO audit_events (
+        id, idempotency_key, action, actor_type, actor_id, target_type, target_id, details_json, created_at
+      ) VALUES (?1, ?2, 'report.reporter_reply_received', 'participant', ?3, 'report', ?4, ?5, ?6)
+    `).bind(
+      crypto.randomUUID(), `audit:${idempotencyKey}`, report.participantId, report.id,
+      canonicalJson({ messageId, previousState: report.state, nextState: targetState, source: "email" }), receivedAt,
+    ),
+  ];
+  if (targetState !== report.state) {
+    statements.push(env.DB.prepare(`
+      INSERT INTO report_state_history (
+        id, report_id, from_state, to_state, reason_code, actor_type, actor_id, created_at
+      ) VALUES (?1, ?2, ?3, ?4, 'reporter_reply_received', 'participant', ?5, ?6)
+    `).bind(crypto.randomUUID(), report.id, report.state, targetState, report.participantId, receivedAt));
+  }
+  await env.DB.batch(statements);
+  return { reportId: report.id, stored: true };
+}

package/template/src/report-email-template.ts

@@ -0,0 +1,53 @@
+import type { WorkspaceBrand } from "./workspace-branding";
+
+function escapeHtml(value: string): string {
+  return value.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")
+    .replaceAll('"', "&quot;").replaceAll("'", "&#039;");
+}
+
+function kind(templateVersionId: string | null): "receipt" | "followup" | "outcome" {
+  if (templateVersionId?.includes("received")) return "receipt";
+  if (templateVersionId?.includes("outcome")) return "outcome";
+  return "followup";
+}
+
+export function renderReporterEmail(input: {
+  brand: WorkspaceBrand;
+  body: string;
+  reportReference: string;
+  templateVersionId: string | null;
+  subjectPrefix: string;
+}): { subject: string; text: string; html: string } {
+  const messageKind = kind(input.templateVersionId);
+  const heading = messageKind === "receipt"
+    ? "We received your report"
+    : messageKind === "outcome" ? "An outcome is ready" : "A message from the safety team";
+  const preview = messageKind === "receipt"
+    ? `Your report ${input.reportReference} is now with the safety team.`
+    : `There is an update for report ${input.reportReference}.`;
+  const subject = messageKind === "receipt"
+    ? `${input.brand.organization_name} received your report — ${input.reportReference}`
+    : `${input.subjectPrefix} — ${input.reportReference}`;
+  const messageHtml = escapeHtml(input.body).replaceAll("\n", "<br />");
+  const logo = input.brand.logo_url
+    ? `<img src="${escapeHtml(input.brand.logo_url)}" width="40" alt="${escapeHtml(input.brand.logo_alt || input.brand.organization_name)}" style="display:block;max-width:120px;max-height:40px;border:0" />`
+    : `<span style="display:inline-block;width:36px;height:36px;line-height:36px;border-radius:10px;background:${input.brand.primary_color};color:${input.brand.primary_contrast_color};font-size:18px;font-weight:700;text-align:center">${escapeHtml(input.brand.organization_name.slice(0, 1).toUpperCase())}</span>`;
+  const html = `<!doctype html>
+<html lang="en"><head><meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1"><title>${escapeHtml(subject)}</title></head>
+<body style="margin:0;padding:0;background:${input.brand.background_color};color:${input.brand.text_color};font-family:Arial,Helvetica,sans-serif">
+<div style="display:none;max-height:0;overflow:hidden;opacity:0">${escapeHtml(preview)}</div>
+<table role="presentation" width="100%" cellspacing="0" cellpadding="0" border="0" style="background:${input.brand.background_color}"><tr><td align="center" style="padding:32px 16px">
+<table role="presentation" width="100%" cellspacing="0" cellpadding="0" border="0" style="max-width:600px;background:${input.brand.surface_color};border:1px solid ${input.brand.border_color};border-radius:${Math.min(input.brand.border_radius, 16)}px;overflow:hidden">
+<tr><td style="height:6px;background:${input.brand.primary_color};font-size:0">&nbsp;</td></tr>
+<tr><td style="padding:28px 32px 12px"><table role="presentation" width="100%" cellspacing="0" cellpadding="0"><tr><td>${logo}</td><td align="right" style="color:${input.brand.muted_color};font-size:13px;font-weight:700">${escapeHtml(input.brand.organization_name)}</td></tr></table></td></tr>
+<tr><td style="padding:12px 32px 8px"><h1 style="margin:0;font-size:26px;line-height:1.25;color:${input.brand.text_color};font-family:Georgia,'Times New Roman',serif">${escapeHtml(heading)}</h1></td></tr>
+<tr><td style="padding:12px 32px"><div style="padding:20px;border:1px solid ${input.brand.border_color};border-radius:${Math.min(input.brand.border_radius, 14)}px;background:${input.brand.background_color};font-size:16px;line-height:1.6;color:${input.brand.text_color}">${messageHtml}</div></td></tr>
+<tr><td style="padding:10px 32px 24px"><table role="presentation" width="100%" cellspacing="0" cellpadding="0"><tr><td style="color:${input.brand.muted_color};font-size:13px">Report reference</td><td align="right" style="color:${input.brand.text_color};font-size:13px;font-weight:700">${escapeHtml(input.reportReference)}</td></tr></table></td></tr>
+<tr><td style="padding:20px 32px;border-top:1px solid ${input.brand.border_color};color:${input.brand.muted_color};font-size:12px;line-height:1.55">Reply directly to this email to contact the safety team. Keep the reply address unchanged so your message reaches the correct case. This message contains only the information needed for your report update.</td></tr>
+</table></td></tr></table></body></html>`;
+  return {
+    subject,
+    html,
+    text: `${heading}\n\n${input.body}\n\nReport reference: ${input.reportReference}\n\nReply directly to this email to contact the safety team. Keep the reply address unchanged so your message reaches the correct case.`,
+  };
+}

package/template/src/report-email.ts

@@ -10,10 +10,13 @@ export type AuthenticationEmailBinding = {
 
 export type ReporterEmailBinding = {
   send(message: {
-    from: string;
-    to: string;
+    from: string | { email: string; name?: string };
+    to: string | { email: string; name?: string };
     subject: string;
     text: string;
+    html?: string;
+    replyTo?: string | { email: string; name?: string };
+    headers?: Record<string, string>;
   }): Promise<{ messageId?: string }>;
 };
 
@@ -59,6 +62,72 @@ export function reporterEmailConfigured(env: unknown): boolean {
   return Boolean(reporterEmailBinding(env) && reporterEmailFrom(env));
 }
 
+const replyTokenPattern = /^r1\.([a-z0-9_-]{16})\.([0-9a-f]{8})\.([0-9a-f]{24})$/u;
+const encoder = new TextEncoder();
+
+function hex(bytes: Uint8Array): string {
+  return [...bytes].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+function constantTimeEqual(left: Uint8Array, right: Uint8Array): boolean {
+  let difference = left.byteLength ^ right.byteLength;
+  const length = Math.max(left.byteLength, right.byteLength);
+  for (let index = 0; index < length; index += 1) difference |= (left[index] ?? 0) ^ (right[index] ?? 0);
+  return difference === 0;
+}
+
+async function replySignature(secret: string, payload: string): Promise<Uint8Array> {
+  if (encoder.encode(secret).byteLength < 32) throw new Error("Reporter reply signing requires a 32-byte signing secret.");
+  const key = await crypto.subtle.importKey("raw", encoder.encode(secret), { name: "HMAC", hash: "SHA-256" }, false, ["sign"]);
+  return new Uint8Array(await crypto.subtle.sign("HMAC", key, encoder.encode(`reporter-email-reply:${payload}`))).slice(0, 12);
+}
+
+export async function reporterReplyToken(input: {
+  publicReference: string;
+  expiresAt: number;
+  signingSecret: string;
+}): Promise<string> {
+  const reference = input.publicReference.replace(/^RPT-/u, "").toLowerCase();
+  if (!/^[a-z0-9_-]{16}$/u.test(reference)) throw new Error("The report reference cannot be used for an email reply token.");
+  const expiry = input.expiresAt.toString(16).padStart(8, "0");
+  if (!/^[0-9a-f]{8}$/u.test(expiry)) throw new Error("The reporter reply expiry is outside the supported range.");
+  const payload = `r1.${reference}.${expiry}`;
+  return `${payload}.${hex(await replySignature(input.signingSecret, payload))}`;
+}
+
+export async function verifyReporterReplyToken(
+  token: string,
+  signingSecret: string,
+  currentTime = Math.floor(Date.now() / 1_000),
+): Promise<{ publicReference: string; expiresAt: number } | null> {
+  const match = replyTokenPattern.exec(token);
+  if (!match) return null;
+  const expiry = Number.parseInt(match[2]!, 16);
+  const supplied = Uint8Array.from(match[3]!.match(/.{2}/gu) ?? [], (pair) => Number.parseInt(pair, 16));
+  if (!expiry || expiry <= currentTime) return null;
+  const payload = `r1.${match[1]}.${match[2]}`;
+  const expected = await replySignature(signingSecret, payload);
+  if (!constantTimeEqual(supplied, expected)) return null;
+  return { publicReference: `RPT-${match[1]!.toUpperCase()}`, expiresAt: expiry };
+}
+
+export async function reporterReplyAddress(input: {
+  fromAddress: string;
+  publicReference: string;
+  signingSecret: string;
+  expiresAt: number;
+}): Promise<string> {
+  const separator = input.fromAddress.lastIndexOf("@");
+  if (separator < 1) throw new Error("The reporter email address is invalid.");
+  const local = input.fromAddress.slice(0, separator);
+  const domain = input.fromAddress.slice(separator + 1);
+  const token = await reporterReplyToken(input);
+  if (local.length + token.length + 1 > 64) {
+    throw new Error("The reporter email local part is too long for secure reply addresses.");
+  }
+  return `${local.toLowerCase()}+${token}@${domain.toLowerCase()}`;
+}
+
 export type ParticipantDelivery = {
   channel: "email" | "customer_webhook" | null;
   state: "queued" | "suppressed";

package/template/src/report-presence.ts

@@ -282,10 +282,6 @@ export class WorkspacePresence extends DurableObject<Env> {
     if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(value));
   }
 
-  private broadcast(value: unknown): void {
-    for (const ws of this.ctx.getWebSockets()) this.send(ws, value);
-  }
-
   private async broadcastSnapshot(): Promise<void> {
     const snapshots = new Map<string, AnalystPresence[]>();
     for (const ws of this.ctx.getWebSockets()) {
@@ -327,7 +323,15 @@ export class WorkspacePresence extends DurableObject<Env> {
   }
 
   async publish(event: { type: "claim_changed" | "reports_changed"; reportId?: string }): Promise<void> {
-    this.broadcast({ type: event.type, report_id: null, sent_at: now() });
+    const queue = event.reportId
+      ? await this.env.DB.prepare(`SELECT queue_id AS queueId FROM reports WHERE id = ?1 LIMIT 1`)
+        .bind(event.reportId).first<{ queueId: string | null }>()
+      : null;
+    for (const ws of this.ctx.getWebSockets()) {
+      const scope = attachment(ws.deserializeAttachment())?.allowedQueueIds;
+      const canNameReport = Boolean(event.reportId && (scope === null || queue?.queueId && scope?.includes(queue.queueId)));
+      this.send(ws, { type: event.type, report_id: canNameReport ? event.reportId : null, sent_at: now() });
+    }
   }
 
   async webSocketMessage(ws: WebSocket, value: string | ArrayBuffer): Promise<void> {

package/template/src/report-repository.ts

@@ -281,7 +281,7 @@ export async function createReport(
   const receiptMessageId = crypto.randomUUID();
   const receiptNoticeId = crypto.randomUUID();
   const receiptDeliveryId = crypto.randomUUID();
-  const receiptBody = `We received report ${publicReference}. The safety team will send updates through your configured notification channel.`;
+  const receiptBody = `We received your report ${publicReference}. It is now with the safety team. We will email you when there is an update, and you can reply directly to any report email.`;
   const directEmail = Boolean(submission.reporter.email && options.emailEnabled);
   const webhookNotification = Boolean(!directEmail && options.notificationEnabled
     && (submission.reporter.email || submission.reporter.reference));

package/template/src/report-workflow-validation.ts

@@ -1,6 +1,14 @@
 import { ApiError } from "./report-http";
 
 const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/u;
+export const HUMAN_DECISION_CODES = [
+  "violation_confirmed",
+  "no_violation_found",
+  "insufficient_information",
+  "out_of_scope",
+  "duplicate",
+] as const;
+const humanDecisionCodes = new Set<string>(HUMAN_DECISION_CODES);
 
 function known(input: Record<string, unknown>, allowed: readonly string[]): void {
   const unknown = Object.keys(input).filter((key) => !allowed.includes(key));
@@ -79,7 +87,13 @@ export function parseDecision(body: Record<string, unknown>, header: string | nu
     : id(body.action_code, "action_code", 100);
   return {
     idempotencyKey: idempotency(body, header),
-    decisionCode: id(body.decision_code, "decision_code", 100),
+    decisionCode: (() => {
+      const value = id(body.decision_code, "decision_code", 100);
+      if (!humanDecisionCodes.has(value)) {
+        throw new ApiError(400, "decision_code_not_allowed", "Select one of the supported human decision outcomes.", { field: "decision_code" });
+      }
+      return value;
+    })(),
     policyCode: id(body.policy_code, "policy_code", 100),
     rationale: text(body.rationale, "rationale", 8_000),
     evidenceReferences,