create-safest-tools 0.2.0

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

@@ -0,0 +1,119 @@
+import { ApiError } from "./report-http";
+
+const ID_PATTERN = /^[A-Za-z0-9][A-Za-z0-9._:-]*$/u;
+
+function known(input: Record<string, unknown>, allowed: readonly string[]): void {
+  const unknown = Object.keys(input).filter((key) => !allowed.includes(key));
+  if (unknown.length) throw new ApiError(400, "unknown_field", "The request contains unsupported fields.", { 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().replace(/\r\n/gu, "\n");
+  if (normalized.length < minimum || normalized.length > maximum) {
+    throw new ApiError(400, "invalid_field", `${field} must contain ${minimum}-${maximum} characters.`, { field });
+  }
+  return normalized;
+}
+
+function id(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} is invalid.`, { field });
+  return normalized;
+}
+
+function idempotency(body: Record<string, unknown>, header: string | null): string {
+  const bodyValue = id(body.idempotency_key, "idempotency_key");
+  if (header?.trim() && header.trim() !== bodyValue) {
+    throw new ApiError(400, "idempotency_key_mismatch", "The Idempotency-Key header and body value must match.");
+  }
+  return bodyValue;
+}
+
+export interface ReviewerMessageInput {
+  idempotencyKey: string;
+  body: string;
+  awaitReporter: boolean;
+}
+
+export function parseReviewerMessage(body: Record<string, unknown>, header: string | null): ReviewerMessageInput {
+  known(body, ["idempotency_key", "body", "await_reporter"]);
+  if (body.await_reporter !== undefined && typeof body.await_reporter !== "boolean") {
+    throw new ApiError(400, "invalid_field", "await_reporter must be a boolean.", { field: "await_reporter" });
+  }
+  return {
+    idempotencyKey: idempotency(body, header),
+    body: text(body.body, "body", 4_000),
+    awaitReporter: body.await_reporter !== false,
+  };
+}
+
+export interface DecisionInput {
+  idempotencyKey: string;
+  decisionCode: string;
+  policyCode: string;
+  rationale: string;
+  evidenceReferences: string[];
+  reporterNotice: string;
+  affectedUserNotice?: string;
+  actionCode?: string;
+}
+
+export function parseDecision(body: Record<string, unknown>, header: string | null): DecisionInput {
+  known(body, [
+    "idempotency_key", "decision_code", "policy_code", "rationale", "evidence_references",
+    "reporter_notice", "affected_user_notice", "action_code",
+  ]);
+  if (!Array.isArray(body.evidence_references) || body.evidence_references.length > 50) {
+    throw new ApiError(400, "invalid_field", "evidence_references must contain at most 50 references.", { field: "evidence_references" });
+  }
+  const evidenceReferences = body.evidence_references.map((value, index) => id(value, `evidence_references[${index}]`, 500));
+  if (!evidenceReferences.length || new Set(evidenceReferences).size !== evidenceReferences.length) {
+    throw new ApiError(400, "invalid_field", "evidence_references must be non-empty and unique.", { field: "evidence_references" });
+  }
+  const affectedUserNotice = body.affected_user_notice === undefined || body.affected_user_notice === ""
+    ? undefined
+    : text(body.affected_user_notice, "affected_user_notice", 4_000);
+  const actionCode = body.action_code === undefined || body.action_code === ""
+    ? undefined
+    : id(body.action_code, "action_code", 100);
+  return {
+    idempotencyKey: idempotency(body, header),
+    decisionCode: id(body.decision_code, "decision_code", 100),
+    policyCode: id(body.policy_code, "policy_code", 100),
+    rationale: text(body.rationale, "rationale", 8_000),
+    evidenceReferences,
+    reporterNotice: text(body.reporter_notice, "reporter_notice", 4_000),
+    ...(affectedUserNotice ? { affectedUserNotice } : {}),
+    ...(actionCode ? { actionCode } : {}),
+  };
+}
+
+export interface AppealDecisionInput {
+  idempotencyKey: string;
+  outcome: "upheld" | "modified" | "reversed";
+  rationale: string;
+  participantNotice: string;
+  correctiveActionCode?: string;
+}
+
+export function parseAppealDecision(body: Record<string, unknown>, header: string | null): AppealDecisionInput {
+  known(body, ["idempotency_key", "outcome", "rationale", "participant_notice", "corrective_action_code"]);
+  const outcome = text(body.outcome, "outcome", 20) as AppealDecisionInput["outcome"];
+  if (!["upheld", "modified", "reversed"].includes(outcome)) {
+    throw new ApiError(400, "invalid_field", "outcome must be upheld, modified, or reversed.", { field: "outcome" });
+  }
+  const correctiveActionCode = body.corrective_action_code === undefined || body.corrective_action_code === ""
+    ? undefined
+    : id(body.corrective_action_code, "corrective_action_code", 100);
+  if (correctiveActionCode && outcome !== "reversed" && outcome !== "modified") {
+    throw new ApiError(400, "invalid_field", "A corrective action is only valid for a modified or reversed appeal.", { field: "corrective_action_code" });
+  }
+  return {
+    idempotencyKey: idempotency(body, header),
+    outcome,
+    rationale: text(body.rationale, "rationale", 8_000),
+    participantNotice: text(body.participant_notice, "participant_notice", 4_000),
+    ...(correctiveActionCode ? { correctiveActionCode } : {}),
+  };
+}