create-safest-tools 0.2.0

package/template/src/backup-service.ts

@@ -0,0 +1,269 @@
+import { canonicalJson } from "./audit";
+import { ApiError } from "./report-http";
+import type { OperatorSession } from "./report-types";
+
+export const BACKUP_BUCKETS = ["profile_media", "workflow_artifacts", "evidence", "exports"] as const;
+export type BackupBucketName = typeof BACKUP_BUCKETS[number];
+
+interface BackupRow {
+  id: string;
+  environment: string;
+  applicationVersion: string;
+  state: string;
+  d1ExportReference: string;
+  d1Digest: string;
+  r2ManifestReference: string | null;
+  r2ManifestDigest: string | null;
+  createdBy: string;
+  createdAt: string;
+  completedAt: string | null;
+  verifiedAt: string | null;
+}
+
+export interface BackupCompletionInput {
+  state: "verified" | "failed";
+  d1ExportReference?: string;
+  d1Digest?: string;
+  r2ManifestReference?: string;
+  r2ManifestDigest?: string;
+  failureCode?: string;
+  objectCount?: number;
+  objectBytes?: number;
+}
+
+function safeText(value: unknown, field: string, minimum: number, maximum: number): string {
+  if (typeof value !== "string") throw new ApiError(400, "backup_input_invalid", `${field} is invalid.`);
+  const normalized = value.trim();
+  if (normalized.length < minimum || normalized.length > maximum || /[\u0000-\u001f\u007f]/u.test(normalized)) {
+    throw new ApiError(400, "backup_input_invalid", `${field} is invalid.`);
+  }
+  return normalized;
+}
+
+function backupId(value: unknown): string {
+  const result = safeText(value, "backup_id", 36, 36).toLowerCase();
+  if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u.test(result)) {
+    throw new ApiError(400, "backup_id_invalid", "backup_id must be a UUID.");
+  }
+  return result;
+}
+
+function digest(value: unknown, field: string): string {
+  const result = safeText(value, field, 71, 71).toLowerCase();
+  if (!/^sha256:[0-9a-f]{64}$/u.test(result)) throw new ApiError(400, "backup_digest_invalid", `${field} must be a SHA-256 digest.`);
+  return result;
+}
+
+function reference(value: unknown, field: string): string {
+  const result = safeText(value, field, 1, 500);
+  if (result.startsWith("/") || result.includes("\\") || result.split("/").includes("..")) {
+    throw new ApiError(400, "backup_reference_invalid", `${field} must be a relative archive reference.`);
+  }
+  return result;
+}
+
+export function parseBackupBucket(value: unknown): BackupBucketName {
+  if (typeof value === "string" && (BACKUP_BUCKETS as readonly string[]).includes(value)) return value as BackupBucketName;
+  throw new ApiError(400, "backup_bucket_invalid", "bucket must name one of the installation's private R2 bindings.");
+}
+
+export function validateBackupObjectKey(value: unknown): string {
+  if (typeof value !== "string" || value.length < 1 || /[\u0000-\u001f\u007f]/u.test(value)
+    || new TextEncoder().encode(value).byteLength > 1_024) {
+    throw new ApiError(400, "backup_object_key_invalid", "The R2 object key is invalid or too long.");
+  }
+  return value;
+}
+
+export function parseBackupCompletion(value: Record<string, unknown>): BackupCompletionInput {
+  const allowed = new Set(["state", "d1_export_reference", "d1_digest", "r2_manifest_reference", "r2_manifest_digest", "failure_code", "object_count", "object_bytes"]);
+  const unknown = Object.keys(value).find((key) => !allowed.has(key));
+  if (unknown) throw new ApiError(400, "backup_input_invalid", `Unsupported backup completion field: ${unknown}.`);
+  if (value.state === "failed") {
+    return { state: "failed", failureCode: safeText(value.failure_code, "failure_code", 3, 100) };
+  }
+  if (value.state !== "verified") throw new ApiError(400, "backup_state_invalid", "state must be verified or failed.");
+  const objectCount = Number(value.object_count);
+  const objectBytes = Number(value.object_bytes);
+  if (!Number.isSafeInteger(objectCount) || objectCount < 0 || !Number.isSafeInteger(objectBytes) || objectBytes < 0) {
+    throw new ApiError(400, "backup_inventory_invalid", "object_count and object_bytes must be non-negative safe integers.");
+  }
+  return {
+    state: "verified",
+    d1ExportReference: reference(value.d1_export_reference, "d1_export_reference"),
+    d1Digest: digest(value.d1_digest, "d1_digest"),
+    r2ManifestReference: reference(value.r2_manifest_reference, "r2_manifest_reference"),
+    r2ManifestDigest: digest(value.r2_manifest_digest, "r2_manifest_digest"),
+    objectCount,
+    objectBytes,
+  };
+}
+
+export function backupBucket(env: Env, name: BackupBucketName): R2Bucket {
+  if (name === "profile_media") return env.PROFILE_MEDIA;
+  if (name === "workflow_artifacts") return env.WORKFLOW_ARTIFACTS;
+  if (name === "evidence") return env.EVIDENCE_OBJECTS;
+  return env.EXPORTS;
+}
+
+function audit(
+  db: D1Database,
+  session: OperatorSession,
+  idempotencyKey: string,
+  action: string,
+  backupIdValue: string,
+  details: Record<string, unknown>,
+  createdAt: string,
+): D1PreparedStatement {
+  return 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, ?3, ?4, ?5, 'backup_manifest', ?6, ?7, ?8)
+  `).bind(crypto.randomUUID(), idempotencyKey, action, session.actor.type, session.actor.id, backupIdValue, canonicalJson(details), createdAt);
+}
+
+async function loadBackup(db: D1Database, id: string): Promise<BackupRow | null> {
+  return db.prepare(`
+    SELECT id, environment, application_version AS applicationVersion, state,
+      d1_export_reference AS d1ExportReference, d1_digest AS d1Digest,
+      r2_manifest_reference AS r2ManifestReference, r2_manifest_digest AS r2ManifestDigest,
+      created_by AS createdBy, created_at AS createdAt, completed_at AS completedAt,
+      verified_at AS verifiedAt
+    FROM backup_manifests WHERE id = ?1 AND installation_id = 'default' LIMIT 1
+  `).bind(id).first<BackupRow>();
+}
+
+export async function startBackup(
+  db: D1Database,
+  session: OperatorSession,
+  input: Record<string, unknown>,
+  idempotencyKey: string,
+): Promise<{ backupId: string; state: string; idempotentReplay: boolean }> {
+  const allowed = new Set(["backup_id", "environment", "application_version"]);
+  const unknown = Object.keys(input).find((key) => !allowed.has(key));
+  if (unknown) throw new ApiError(400, "backup_input_invalid", `Unsupported backup start field: ${unknown}.`);
+  const id = backupId(input.backup_id);
+  const environment = safeText(input.environment, "environment", 2, 100);
+  const applicationVersion = safeText(input.application_version, "application_version", 1, 100);
+  const existing = await loadBackup(db, id);
+  if (existing) {
+    if (existing.environment !== environment || existing.applicationVersion !== applicationVersion || existing.createdBy !== session.actor.id) {
+      throw new ApiError(409, "backup_id_reused", "The backup identifier already belongs to another backup request.");
+    }
+    return { backupId: id, state: existing.state, idempotentReplay: true };
+  }
+  const timestamp = new Date().toISOString();
+  await db.batch([
+    db.prepare(`
+      INSERT INTO backup_manifests (
+        id, installation_id, environment, schema_version, application_version,
+        d1_export_reference, d1_digest, state, created_by, created_at
+      ) VALUES (?1, 'default', ?2, 1, ?3, ?4, 'pending', 'running', ?5, ?6)
+    `).bind(id, environment, applicationVersion, `pending/${id}/database.sql`, session.actor.id, timestamp),
+    audit(db, session, `backup-start:${idempotencyKey}`, "backup.started", id, { environment, applicationVersion }, timestamp),
+  ]);
+  return { backupId: id, state: "running", idempotentReplay: false };
+}
+
+export async function assertBackupTransferAllowed(db: D1Database, idValue: string): Promise<string> {
+  const id = backupId(idValue);
+  const row = await loadBackup(db, id);
+  if (!row) throw new ApiError(404, "backup_not_found", "The backup does not exist.");
+  if (row.state !== "running") throw new ApiError(409, "backup_not_running", "R2 backup transfer is only available while the backup is running.");
+  return id;
+}
+
+export async function listBackupObjects(
+  bucket: R2Bucket,
+  cursor: string | undefined,
+  limit: number,
+): Promise<{ objects: Array<{ key: string; size: number; etag: string; version: string; uploadedAt: string }>; nextCursor: string | null }> {
+  const page = await bucket.list({ ...(cursor ? { cursor } : {}), limit });
+  return {
+    objects: page.objects.map((object) => ({
+      key: object.key,
+      size: object.size,
+      etag: object.etag,
+      version: object.version,
+      uploadedAt: object.uploaded.toISOString(),
+    })),
+    nextCursor: page.truncated ? page.cursor : null,
+  };
+}
+
+export async function readBackupObject(bucket: R2Bucket, keyValue: unknown, etagValue: unknown): Promise<R2ObjectBody> {
+  const key = validateBackupObjectKey(keyValue);
+  const etag = safeText(etagValue, "etag", 1, 200);
+  const object = await bucket.get(key, { onlyIf: { etagMatches: etag } });
+  if (!object) throw new ApiError(404, "backup_object_not_found", "The R2 object no longer exists.");
+  if (!("body" in object)) throw new ApiError(409, "backup_object_changed", "The R2 object changed after inventory and the backup must be retried.");
+  return object;
+}
+
+export async function finalizeBackup(
+  db: D1Database,
+  session: OperatorSession,
+  idValue: string,
+  input: BackupCompletionInput,
+  idempotencyKey: string,
+): Promise<{ backupId: string; state: string; idempotentReplay: boolean }> {
+  const id = backupId(idValue);
+  const existing = await loadBackup(db, id);
+  if (!existing) throw new ApiError(404, "backup_not_found", "The backup does not exist.");
+  if (existing.createdBy !== session.actor.id) throw new ApiError(403, "backup_owner_denied", "Only the deployment owner that started the backup can finalize it.");
+  if (existing.state !== "running") {
+    const sameVerified = input.state === "verified" && existing.state === "verified"
+      && existing.d1Digest === input.d1Digest && existing.r2ManifestDigest === input.r2ManifestDigest;
+    const sameFailed = input.state === "failed" && existing.state === "failed";
+    if (sameVerified || sameFailed) return { backupId: id, state: existing.state, idempotentReplay: true };
+    throw new ApiError(409, "backup_state_conflict", "The backup is already finalized with different results.");
+  }
+  const timestamp = new Date().toISOString();
+  if (input.state === "failed") {
+    await db.batch([
+      db.prepare(`UPDATE backup_manifests SET state = 'failed', completed_at = ?2 WHERE id = ?1 AND state = 'running'`).bind(id, timestamp),
+      audit(db, session, `backup-failed:${idempotencyKey}`, "backup.failed", id, { failureCode: input.failureCode }, timestamp),
+    ]);
+    return { backupId: id, state: "failed", idempotentReplay: false };
+  }
+  await db.batch([
+    db.prepare(`
+      UPDATE backup_manifests SET d1_export_reference = ?2, d1_digest = ?3,
+        r2_manifest_reference = ?4, r2_manifest_digest = ?5, state = 'verified',
+        completed_at = ?6, verified_at = ?6
+      WHERE id = ?1 AND state = 'running'
+    `).bind(id, input.d1ExportReference, input.d1Digest, input.r2ManifestReference, input.r2ManifestDigest, timestamp),
+    audit(db, session, `backup-verified:${idempotencyKey}`, "backup.verified", id, {
+      d1Digest: input.d1Digest,
+      r2ManifestDigest: input.r2ManifestDigest,
+      objectCount: input.objectCount,
+      objectBytes: input.objectBytes,
+    }, timestamp),
+  ]);
+  return { backupId: id, state: "verified", idempotentReplay: false };
+}
+
+export async function listBackups(
+  db: D1Database,
+  limit: number,
+  cursor?: { createdAt: string; id: string },
+): Promise<{ backups: Record<string, unknown>[]; nextCursor: { createdAt: string; id: string } | null }> {
+  const rows = await db.prepare(`
+    SELECT id, environment, schema_version AS schemaVersion, application_version AS applicationVersion,
+      d1_digest AS d1Digest, r2_manifest_digest AS r2ManifestDigest, state,
+      created_by AS createdBy, created_at AS createdAt, completed_at AS completedAt,
+      verified_at AS verifiedAt
+    FROM backup_manifests WHERE installation_id = 'default'
+      AND (?1 IS NULL OR created_at < ?1 OR (created_at = ?1 AND id < ?2))
+    ORDER BY created_at DESC, id DESC LIMIT ?3
+  `).bind(cursor?.createdAt ?? null, cursor?.id ?? null, limit + 1).all<Record<string, unknown>>();
+  const hasMore = rows.results.length > limit;
+  const backups = rows.results.slice(0, limit);
+  const last = hasMore ? backups.at(-1) : undefined;
+  return {
+    backups,
+    nextCursor: last && typeof last.createdAt === "string" && typeof last.id === "string"
+      ? { createdAt: last.createdAt, id: last.id }
+      : null,
+  };
+}

package/template/src/budget-control.ts

@@ -0,0 +1,127 @@
+export interface BudgetScope { type: string; id: string }
+
+export interface BudgetReservationHandle {
+  id: string;
+  policyId: string;
+  windowStart: string;
+  amount: number;
+}
+
+export class BudgetControlError extends Error {
+  constructor(
+    readonly code: string,
+    readonly retryable: boolean,
+    readonly delaySeconds: number,
+    readonly fallbackReference: string | null,
+  ) { super(code); this.name = "BudgetControlError"; }
+}
+
+function now(): string { return new Date().toISOString(); }
+
+export async function reserveBudgets(
+  db: D1Database,
+  input: {
+    installationId: string;
+    scopes: BudgetScope[];
+    metric: string;
+    amount: number;
+    operationType: string;
+    operationId: string;
+    attemptId: string;
+  },
+): Promise<BudgetReservationHandle[]> {
+  if (!Number.isInteger(input.amount) || input.amount < 0) throw new BudgetControlError("budget_amount_invalid", false, 0, null);
+  const policies = await db.prepare(`
+    SELECT id, scope_type AS scopeType, scope_id AS scopeId,
+      limit_value AS limitValue, window_seconds AS windowSeconds,
+      behavior, fallback_reference AS fallbackReference
+    FROM budget_policies WHERE installation_id = ?1 AND metric = ?2 AND retired_at IS NULL
+    ORDER BY published_at DESC, id
+  `).bind(input.installationId, input.metric).all<{
+    id: string; scopeType: string; scopeId: string; limitValue: number;
+    windowSeconds: number; behavior: string; fallbackReference: string | null;
+  }>();
+  const allowed = new Set([
+    `installation:${input.installationId}`,
+    ...input.scopes.map((scope) => `${scope.type}:${scope.id}`),
+  ]);
+  const applicable = policies.results.filter((policy) => allowed.has(`${policy.scopeType}:${policy.scopeId}`));
+  const reservations: BudgetReservationHandle[] = [];
+  try {
+    for (const policy of applicable) {
+      const epoch = Math.floor(Date.now() / 1_000);
+      const windowEpoch = Math.floor(epoch / policy.windowSeconds) * policy.windowSeconds;
+      const windowStart = new Date(windowEpoch * 1_000).toISOString();
+      const reservationId = `${policy.id}:${input.operationId}:${input.attemptId}`;
+      const existing = await db.prepare(`SELECT status, reserved_value AS amount FROM budget_reservations WHERE id = ?1 LIMIT 1`)
+        .bind(reservationId).first<{ status: string; amount: number }>();
+      if (existing?.status === "reserved" || existing?.status === "committed") {
+        reservations.push({ id: reservationId, policyId: policy.id, windowStart, amount: existing.amount });
+        continue;
+      }
+      const timestamp = now();
+      await db.prepare(`INSERT INTO budget_usage (policy_id, window_start, reserved_value, consumed_value, revision, updated_at) VALUES (?1, ?2, 0, 0, 1, ?3) ON CONFLICT(policy_id, window_start) DO NOTHING`)
+        .bind(policy.id, windowStart, timestamp).run();
+      const changed = await db.prepare(`
+        UPDATE budget_usage SET reserved_value = reserved_value + ?3,
+          revision = revision + 1, updated_at = ?4
+        WHERE policy_id = ?1 AND window_start = ?2
+          AND reserved_value + consumed_value + ?3 <= ?5
+      `).bind(policy.id, windowStart, input.amount, timestamp, policy.limitValue).run();
+      if (changed.meta.changes !== 1) {
+        const retryable = policy.behavior === "defer";
+        throw new BudgetControlError(
+          policy.behavior === "fallback" ? "budget_fallback_required" : "budget_exhausted",
+          retryable,
+          retryable ? Math.max(1, policy.windowSeconds) : 0,
+          policy.fallbackReference,
+        );
+      }
+      await db.prepare(`
+        INSERT INTO budget_reservations (
+          id, policy_id, window_start, operation_type, operation_id,
+          attempt_id, reserved_value, status, expires_at, created_at, updated_at
+        ) VALUES (?1, ?2, ?3, ?4, ?5, ?6, ?7, 'reserved', ?8, ?9, ?9)
+      `).bind(
+        reservationId, policy.id, windowStart, input.operationType,
+        input.operationId, input.attemptId, input.amount,
+        new Date(Date.now() + 15 * 60_000).toISOString(), timestamp,
+      ).run();
+      reservations.push({ id: reservationId, policyId: policy.id, windowStart, amount: input.amount });
+    }
+    return reservations;
+  } catch (error) {
+    await settleBudgets(db, reservations, false);
+    throw error;
+  }
+}
+
+export async function settleBudgets(
+  db: D1Database,
+  reservations: BudgetReservationHandle[],
+  commit: boolean,
+  actualAmount?: number,
+): Promise<void> {
+  const timestamp = now();
+  for (const reservation of reservations) {
+    const consumed = commit ? Math.max(0, Math.floor(actualAmount ?? reservation.amount)) : 0;
+    const changed = await db.prepare(`
+      UPDATE budget_reservations SET status = ?2, committed_value = ?3, updated_at = ?4
+      WHERE id = ?1 AND status = 'reserved'
+    `).bind(reservation.id, commit ? "committed" : "released", commit ? consumed : null, timestamp).run();
+    if (changed.meta.changes !== 1) continue;
+    await db.prepare(`
+      UPDATE budget_usage SET reserved_value = MAX(0, reserved_value - ?3),
+        consumed_value = consumed_value + ?4, revision = revision + 1,
+        updated_at = ?5 WHERE policy_id = ?1 AND window_start = ?2
+    `).bind(reservation.policyId, reservation.windowStart, reservation.amount, consumed, timestamp).run();
+  }
+}
+
+export async function releaseExpiredBudgetReservations(db: D1Database, limit = 200): Promise<number> {
+  const expired = await db.prepare(`SELECT id, policy_id AS policyId, window_start AS windowStart, reserved_value AS amount FROM budget_reservations WHERE status = 'reserved' AND expires_at <= ?1 ORDER BY expires_at, id LIMIT ?2`)
+    .bind(now(), Math.max(1, Math.min(1_000, limit))).all<{ id: string; policyId: string; windowStart: string; amount: number }>();
+  await settleBudgets(db, expired.results, false);
+  return expired.results.length;
+}
+