create-safest-tools 0.4.2 → 0.5.0

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,