create-safest-tools 0.2.0

package/template/src/report-context-schema.ts

@@ -0,0 +1,132 @@
+import { ApiError } from "./report-http";
+
+export type ContextFieldType = "string" | "number" | "boolean";
+export type ContextFieldSensitivity = "standard" | "sensitive";
+
+export interface ContextFieldDefinition {
+  key: string;
+  label: string;
+  type: ContextFieldType;
+  required: boolean;
+  sensitivity: ContextFieldSensitivity;
+  ruleEligible: boolean;
+}
+
+export interface ContextSchema {
+  version: 1;
+  allowUnknown: boolean;
+  fields: ContextFieldDefinition[];
+}
+
+const FIELD_KEY = /^[A-Za-z][A-Za-z0-9_-]{0,63}$/u;
+const TYPES = new Set<ContextFieldType>(["string", "number", "boolean"]);
+const SENSITIVITIES = new Set<ContextFieldSensitivity>(["standard", "sensitive"]);
+
+function object(value: unknown, code: string): Record<string, unknown> {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new ApiError(400, code, "The trusted-context schema must be an object.");
+  }
+  return value as Record<string, unknown>;
+}
+
+function exactFields(value: Record<string, unknown>, allowed: string[], code: string): void {
+  const unknown = Object.keys(value).filter((key) => !allowed.includes(key));
+  if (unknown.length) throw new ApiError(400, code, "The trusted-context schema contains unsupported fields.", { fields: unknown.slice(0, 10) });
+}
+
+export function parseContextSchema(value: unknown, options: { allowLegacy?: boolean } = {}): ContextSchema {
+  if (value === undefined && options.allowLegacy) return { version: 1, allowUnknown: true, fields: [] };
+  const input = object(value ?? { version: 1, fields: [] }, "context_schema_invalid");
+  exactFields(input, ["version", "allow_unknown", "fields"], "context_schema_invalid");
+  if (input.version !== 1) throw new ApiError(400, "context_schema_version_invalid", "The trusted-context schema version must be 1.");
+  if (input.allow_unknown !== undefined && typeof input.allow_unknown !== "boolean") {
+    throw new ApiError(400, "context_schema_invalid", "allow_unknown must be a boolean.");
+  }
+  if (!Array.isArray(input.fields) || input.fields.length > 50) {
+    throw new ApiError(400, "context_schema_invalid", "The trusted-context schema may contain at most 50 fields.");
+  }
+  const fields = input.fields.map((raw, index): ContextFieldDefinition => {
+    const field = object(raw, "context_schema_field_invalid");
+    exactFields(field, ["key", "label", "type", "required", "sensitivity", "rule_eligible"], "context_schema_field_invalid");
+    if (typeof field.key !== "string" || !FIELD_KEY.test(field.key)) {
+      throw new ApiError(400, "context_schema_field_invalid", `Trusted-context field ${index + 1} has an invalid key.`);
+    }
+    if (typeof field.label !== "string" || !field.label.trim() || field.label.trim().length > 120) {
+      throw new ApiError(400, "context_schema_field_invalid", `Trusted-context field ${field.key} needs a label of 1 to 120 characters.`);
+    }
+    if (typeof field.type !== "string" || !TYPES.has(field.type as ContextFieldType)) {
+      throw new ApiError(400, "context_schema_field_invalid", `Trusted-context field ${field.key} has an unsupported type.`);
+    }
+    if (field.required !== undefined && typeof field.required !== "boolean") {
+      throw new ApiError(400, "context_schema_field_invalid", `Trusted-context field ${field.key} has an invalid required value.`);
+    }
+    const sensitivity = field.sensitivity ?? "standard";
+    if (typeof sensitivity !== "string" || !SENSITIVITIES.has(sensitivity as ContextFieldSensitivity)) {
+      throw new ApiError(400, "context_schema_field_invalid", `Trusted-context field ${field.key} has an unsupported sensitivity.`);
+    }
+    if (field.rule_eligible !== undefined && typeof field.rule_eligible !== "boolean") {
+      throw new ApiError(400, "context_schema_field_invalid", `Trusted-context field ${field.key} has an invalid rule_eligible value.`);
+    }
+    return {
+      key: field.key,
+      label: field.label.trim(),
+      type: field.type as ContextFieldType,
+      required: field.required === true,
+      sensitivity: sensitivity as ContextFieldSensitivity,
+      ruleEligible: field.rule_eligible !== false,
+    };
+  });
+  if (new Set(fields.map((field) => field.key)).size !== fields.length) {
+    throw new ApiError(400, "context_schema_field_duplicate", "Trusted-context field keys must be unique.");
+  }
+  return { version: 1, allowUnknown: input.allow_unknown === true, fields };
+}
+
+export function contextSchemaJson(schema: ContextSchema): Record<string, unknown> {
+  return {
+    version: schema.version,
+    allow_unknown: schema.allowUnknown,
+    fields: schema.fields.map((field) => ({
+      key: field.key,
+      label: field.label,
+      type: field.type,
+      required: field.required,
+      sensitivity: field.sensitivity,
+      rule_eligible: field.ruleEligible,
+    })),
+  };
+}
+
+export function validateContextFacts(
+  facts: Record<string, string | number | boolean | null>,
+  schema: ContextSchema,
+): Record<string, string | number | boolean | null> {
+  const definitions = new Map(schema.fields.map((field) => [field.key, field]));
+  for (const field of schema.fields) {
+    if (field.required && (facts[field.key] === undefined || facts[field.key] === null)) {
+      throw new ApiError(400, "trusted_context_required", `The customer backend did not provide ${field.label}.`, { field: `trusted_facts.${field.key}` });
+    }
+  }
+  for (const [key, value] of Object.entries(facts)) {
+    const field = definitions.get(key);
+    if (!field) {
+      if (!schema.allowUnknown) throw new ApiError(400, "trusted_context_unknown", `trusted_facts.${key} is not registered for this reporting channel.`, { field: `trusted_facts.${key}` });
+      continue;
+    }
+    if (value !== null && typeof value !== field.type) {
+      throw new ApiError(400, "trusted_context_type", `trusted_facts.${key} must be ${field.type}.`, { field: `trusted_facts.${key}` });
+    }
+  }
+  return facts;
+}
+
+export function routingContextFacts(
+  facts: Record<string, string | number | boolean | null>,
+  schema: ContextSchema,
+): Record<string, string | number | boolean | null> {
+  const definitions = new Map(schema.fields.map((field) => [field.key, field]));
+  return Object.fromEntries(Object.entries(facts).filter(([key]) => {
+    const definition = definitions.get(key);
+    return definition ? definition.ruleEligible : schema.allowUnknown;
+  }));
+}

package/template/src/report-context.ts

@@ -0,0 +1,126 @@
+import { canonicalJson } from "./audit";
+import { ApiError } from "./report-http";
+import type { ContextMintInput } from "./report-validation";
+import type { StoredReportContext } from "./report-types";
+
+interface ContextRow {
+  id: string;
+  integration_id: string;
+  form_version_id: string;
+  origin: string;
+  reporter_reference: string | null;
+  target_type: string;
+  target_reference: string;
+  target_owner_reference: string | null;
+  target_customer_url: string | null;
+  trusted_facts_json: string;
+  routing_facts_json: string;
+  context_schema_version: number;
+  assertion_source: "customer_backend" | "resolve_hosted";
+  created_at: string;
+  expires_at: string;
+  used_at: string | null;
+}
+
+function decodeFacts(value: string): Record<string, string | number | boolean | null> {
+  try {
+    const parsed: unknown = JSON.parse(value);
+    if (parsed && typeof parsed === "object" && !Array.isArray(parsed)
+      && Object.values(parsed).every((entry) => entry === null || ["string", "number", "boolean"].includes(typeof entry))) {
+      return parsed as Record<string, string | number | boolean | null>;
+    }
+  } catch { /* handled below */ }
+  throw new ApiError(503, "report_context_corrupt", "The trusted report context could not be read.");
+}
+
+function project(row: ContextRow): StoredReportContext {
+  return {
+    id: row.id,
+    integrationId: row.integration_id,
+    formVersionId: row.form_version_id,
+    origin: row.origin,
+    reporter: { ...(row.reporter_reference ? { reference: row.reporter_reference } : {}) },
+    target: {
+      type: row.target_type,
+      reference: row.target_reference,
+      ...(row.target_owner_reference ? { ownerReference: row.target_owner_reference } : {}),
+      ...(row.target_customer_url ? { customerUrl: row.target_customer_url } : {}),
+    },
+    trustedFacts: decodeFacts(row.trusted_facts_json),
+    routingFacts: decodeFacts(row.routing_facts_json),
+    contextSchemaVersion: row.context_schema_version,
+    assertionSource: row.assertion_source,
+    createdAt: row.created_at,
+    expiresAt: row.expires_at,
+    usedAt: row.used_at,
+  };
+}
+
+export async function createStoredReportContext(
+  db: D1Database,
+  input: ContextMintInput & { origin: string },
+  options: {
+    integrationId: string;
+    formVersionId: string;
+    contextSchemaVersion: number;
+    routingFacts: Record<string, string | number | boolean | null>;
+    expiresAt: string;
+    timestamp?: string;
+  },
+): Promise<StoredReportContext> {
+  const id = crypto.randomUUID();
+  const timestamp = options.timestamp ?? new Date().toISOString();
+  await db.prepare(`
+    INSERT INTO report_contexts (
+      id, installation_id, integration_id, form_version_id, origin,
+      reporter_reference, target_type, target_reference, target_owner_reference,
+      target_customer_url, trusted_facts_json, routing_facts_json, context_schema_version,
+      assertion_source, created_at, expires_at
+    ) VALUES (?1, 'default', ?2, ?3, ?4, ?5, ?6, ?7, ?8, ?9, ?10, ?11, ?12, 'customer_backend', ?13, ?14)
+  `).bind(
+    id, options.integrationId, options.formVersionId, input.origin,
+    input.reporter.reference ?? null, input.target.type, input.target.reference,
+    input.target.ownerReference ?? null, input.target.customerUrl ?? null,
+    canonicalJson(input.trustedFacts), canonicalJson(options.routingFacts), options.contextSchemaVersion, timestamp, options.expiresAt,
+  ).run();
+  return {
+    id,
+    integrationId: options.integrationId,
+    formVersionId: options.formVersionId,
+    origin: input.origin,
+    reporter: input.reporter,
+    target: input.target,
+    trustedFacts: input.trustedFacts,
+    routingFacts: options.routingFacts,
+    contextSchemaVersion: options.contextSchemaVersion,
+    assertionSource: "customer_backend",
+    createdAt: timestamp,
+    expiresAt: options.expiresAt,
+    usedAt: null,
+  };
+}
+
+export async function loadStoredReportContext(
+  db: D1Database,
+  contextId: string,
+  now = new Date().toISOString(),
+): Promise<StoredReportContext> {
+  const row = await db.prepare(`
+    SELECT id, integration_id, form_version_id, origin, reporter_reference,
+      target_type, target_reference, target_owner_reference, target_customer_url,
+      trusted_facts_json, routing_facts_json, context_schema_version, assertion_source,
+      created_at, expires_at, used_at
+    FROM report_contexts WHERE id = ?1 LIMIT 1
+  `).bind(contextId).first<ContextRow>();
+  if (!row || row.expires_at <= now) throw new ApiError(401, "report_context_expired", "This report window expired. Close it and try again.");
+  return project(row);
+}
+
+export async function pruneReportContexts(db: D1Database, now = new Date().toISOString()): Promise<number> {
+  const usedRetentionCutoff = new Date(Date.parse(now) - 86_400_000).toISOString();
+  const result = await db.prepare(`
+    DELETE FROM report_contexts
+    WHERE expires_at < ?1 AND (report_id IS NULL OR used_at < ?2)
+  `).bind(now, usedRetentionCutoff).run();
+  return result.meta.changes ?? 0;
+}

package/template/src/report-crypto.ts

@@ -0,0 +1,142 @@
+import { ApiError } from "./report-http";
+import type { ContextClaims, ParticipantAudience } from "./report-types";
+
+const encoder = new TextEncoder();
+const decoder = new TextDecoder();
+const contextHeader = { alg: "HS256", typ: "SECT", v: 2 } as const;
+
+function base64UrlEncode(bytes: Uint8Array): string {
+  let binary = "";
+  for (const byte of bytes) binary += String.fromCharCode(byte);
+  return btoa(binary).replaceAll("+", "-").replaceAll("/", "_").replace(/=+$/u, "");
+}
+
+function base64UrlDecode(value: string): Uint8Array {
+  if (!/^[A-Za-z0-9_-]+$/u.test(value)) throw new ApiError(401, "invalid_context_token", "The signed context token is invalid.");
+  const padded = value.replaceAll("-", "+").replaceAll("_", "/").padEnd(Math.ceil(value.length / 4) * 4, "=");
+  try {
+    const binary = atob(padded);
+    return Uint8Array.from(binary, (character) => character.charCodeAt(0));
+  } catch {
+    throw new ApiError(401, "invalid_context_token", "The signed context token is invalid.");
+  }
+}
+
+async function hmac(secret: string, message: string): Promise<Uint8Array> {
+  if (encoder.encode(secret).byteLength < 32) throw new Error("Signing secrets must contain at least 32 bytes.");
+  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(message)));
+}
+
+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;
+}
+
+export async function signContextToken(claims: ContextClaims, secret: string): Promise<string> {
+  const header = base64UrlEncode(encoder.encode(JSON.stringify(contextHeader)));
+  const payload = base64UrlEncode(encoder.encode(JSON.stringify(claims)));
+  const signingInput = `${header}.${payload}`;
+  return `${signingInput}.${base64UrlEncode(await hmac(secret, signingInput))}`;
+}
+
+export async function verifyContextToken(
+  token: string,
+  secret: string,
+  expectedIssuer: string,
+  now = Math.floor(Date.now() / 1000),
+): Promise<ContextClaims> {
+  if (token.length > 16 * 1024) throw new ApiError(401, "invalid_context_token", "The signed context token is invalid.");
+  const segments = token.split(".");
+  if (segments.length !== 3) throw new ApiError(401, "invalid_context_token", "The signed context token is invalid.");
+  const [header, payload, signature] = segments as [string, string, string];
+  const expected = await hmac(secret, `${header}.${payload}`);
+  if (!constantTimeEqual(base64UrlDecode(signature), expected)) {
+    throw new ApiError(401, "invalid_context_signature", "The signed context token signature is invalid.");
+  }
+  let parsedHeader: unknown;
+  let parsedClaims: unknown;
+  try {
+    parsedHeader = JSON.parse(decoder.decode(base64UrlDecode(header)));
+    parsedClaims = JSON.parse(decoder.decode(base64UrlDecode(payload)));
+  } catch {
+    throw new ApiError(401, "invalid_context_token", "The signed context token is invalid.");
+  }
+  if (!parsedHeader || typeof parsedHeader !== "object" || Array.isArray(parsedHeader)
+    || (parsedHeader as Record<string, unknown>).alg !== "HS256"
+    || (parsedHeader as Record<string, unknown>).typ !== "SECT"
+    || (parsedHeader as Record<string, unknown>).v !== 2) {
+    throw new ApiError(401, "invalid_context_header", "The signed context token header is invalid.");
+  }
+  if (!parsedClaims || typeof parsedClaims !== "object" || Array.isArray(parsedClaims)) {
+    throw new ApiError(401, "invalid_context_claims", "The signed context token claims are invalid.");
+  }
+  const claims = parsedClaims as Partial<ContextClaims>;
+  if (claims.version !== 2 || claims.aud !== "safest-resolve-reports" || claims.iss !== expectedIssuer
+    || typeof claims.integrationId !== "string" || typeof claims.contextId !== "string"
+    || typeof claims.formVersionId !== "string" || typeof claims.jti !== "string"
+    || typeof claims.iat !== "number" || typeof claims.exp !== "number"
+    || claims.iat > now + 30 || claims.exp <= now || claims.exp - claims.iat > 900
+    || typeof claims.origin !== "string") {
+    throw new ApiError(401, "invalid_context_claims", "The signed context token claims are invalid or expired.");
+  }
+  return claims as ContextClaims;
+}
+
+export async function sha256(value: string): Promise<string> {
+  const digest = new Uint8Array(await crypto.subtle.digest("SHA-256", encoder.encode(value)));
+  return [...digest].map((byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
+async function reportContactKey(secret: string): Promise<CryptoKey> {
+  if (encoder.encode(secret).byteLength < 32) {
+    throw new ApiError(503, "contact_encryption_unavailable", "Reporter contact encryption is not configured.");
+  }
+  return crypto.subtle.importKey(
+    "raw",
+    await crypto.subtle.digest("SHA-256", encoder.encode(secret)),
+    { name: "AES-GCM" },
+    false,
+    ["encrypt", "decrypt"],
+  );
+}
+
+export async function encryptReportContact(secret: string, email: string, reportId: string, audience: ParticipantAudience): Promise<string> {
+  const iv = crypto.getRandomValues(new Uint8Array(12));
+  const context = encoder.encode(`report-contact:v1:${reportId}:${audience}`);
+  const ciphertext = new Uint8Array(await crypto.subtle.encrypt(
+    { name: "AES-GCM", iv, additionalData: context },
+    await reportContactKey(secret),
+    encoder.encode(email),
+  ));
+  return `v1.${base64UrlEncode(iv)}.${base64UrlEncode(ciphertext)}`;
+}
+
+export async function decryptReportContact(secret: string, value: string, reportId: string, audience: ParticipantAudience): Promise<string> {
+  const parts = value.split(".");
+  if (parts.length !== 3 || parts[0] !== "v1") {
+    throw new ApiError(503, "contact_decryption_failed", "Stored reporter contact details could not be decrypted.");
+  }
+  try {
+    const plaintext = await crypto.subtle.decrypt(
+      { name: "AES-GCM", iv: base64UrlDecode(parts[1]!), additionalData: encoder.encode(`report-contact:v1:${reportId}:${audience}`) },
+      await reportContactKey(secret),
+      base64UrlDecode(parts[2]!),
+    );
+    return decoder.decode(plaintext);
+  } catch {
+    throw new ApiError(503, "contact_decryption_failed", "Stored reporter contact details could not be decrypted.");
+  }
+}
+
+export async function secretsEqual(supplied: string, expected: string): Promise<boolean> {
+  const [left, right] = await Promise.all([sha256(supplied), sha256(expected)]);
+  return constantTimeEqual(encoder.encode(left), encoder.encode(right));
+}
+
+export function randomPublicReference(): string {
+  const bytes = crypto.getRandomValues(new Uint8Array(12));
+  return `RPT-${base64UrlEncode(bytes).toUpperCase()}`;
+}