create-safest-tools 0.2.0

package/template/scripts/reports-backup.mjs

@@ -0,0 +1,276 @@
+import { spawn } from "node:child_process";
+import { createHash, randomUUID } from "node:crypto";
+import { createReadStream, createWriteStream } from "node:fs";
+import { mkdir, readFile, unlink, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { Readable, Transform } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { fileURLToPath } from "node:url";
+import { loadReportsPlan } from "./reports-plan.mjs";
+
+const projectRoot = fileURLToPath(new URL("..", import.meta.url));
+const wrangler = fileURLToPath(new URL("../node_modules/wrangler/bin/wrangler.js", import.meta.url));
+const BUCKETS = ["profile_media", "workflow_artifacts", "evidence", "exports"];
+
+function parseArguments(argv) {
+  const result = { planOnly: false, config: "reports.config.json", secrets: ".safest/secrets.env" };
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--plan") result.planOnly = true;
+    else if (argument === "--config" || argument === "--secrets-file") {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("-")) throw new Error(`${argument} needs a value`);
+      index += 1;
+      if (argument === "--config") result.config = value;
+      else result.secrets = value;
+    } else throw new Error(`unknown option: ${argument}`);
+  }
+  return result;
+}
+
+function run(args) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(process.execPath, [wrangler, ...args], { cwd: projectRoot, env: process.env, stdio: "inherit" });
+    child.once("error", reject);
+    child.once("exit", (code) => code === 0 ? resolvePromise() : reject(new Error(`D1 export failed with exit code ${code}`)));
+  });
+}
+
+function parseSecrets(raw) {
+  const values = new Map();
+  for (const line of raw.split(/\r?\n/u)) {
+    const normalized = line.trim();
+    if (!normalized || normalized.startsWith("#")) continue;
+    const separator = normalized.indexOf("=");
+    if (separator > 0) values.set(normalized.slice(0, separator).trim(), normalized.slice(separator + 1).trim());
+  }
+  return values;
+}
+
+function sha256Bytes(value) {
+  return `sha256:${createHash("sha256").update(value).digest("hex")}`;
+}
+
+async function sha256File(path) {
+  const hash = createHash("sha256");
+  let bytes = 0;
+  for await (const chunk of createReadStream(path)) {
+    hash.update(chunk);
+    bytes += chunk.length;
+  }
+  return { digest: `sha256:${hash.digest("hex")}`, bytes };
+}
+
+async function apiJson(baseUrl, adminKey, path, init = {}) {
+  const response = await fetch(new URL(path, baseUrl), {
+    ...init,
+    headers: {
+      accept: "application/json",
+      "x-admin-key": adminKey,
+      ...(init.body ? { "content-type": "application/json" } : {}),
+      ...init.headers,
+    },
+    redirect: "error",
+  });
+  const body = await response.json().catch(() => ({}));
+  if (!response.ok) {
+    const message = body?.error?.message;
+    throw new Error(typeof message === "string" ? message : `Backup API failed with HTTP ${response.status}`);
+  }
+  return body;
+}
+
+function inventoryFingerprint(inventory) {
+  return sha256Bytes(JSON.stringify(inventory.map(({ key, size, etag, version }) => ({ key, size, etag, version }))));
+}
+
+async function inventoryBucket(config, adminKey, backupId, bucket) {
+  const objects = [];
+  let cursor = null;
+  do {
+    const url = new URL(`/v1/admin/backups/${encodeURIComponent(backupId)}/r2`, config.publicBaseUrl);
+    url.searchParams.set("bucket", bucket);
+    url.searchParams.set("limit", "1000");
+    if (cursor) url.searchParams.set("cursor", cursor);
+    const page = await apiJson(config.publicBaseUrl, adminKey, url.pathname + url.search);
+    if (!Array.isArray(page.objects)) throw new Error(`Backup inventory for ${bucket} was malformed`);
+    for (const object of page.objects) {
+      if (!object || typeof object.key !== "string" || !Number.isSafeInteger(object.size) || object.size < 0
+        || typeof object.etag !== "string" || typeof object.version !== "string") {
+        throw new Error(`Backup inventory for ${bucket} contained an invalid object`);
+      }
+      objects.push({ key: object.key, size: object.size, etag: object.etag, version: object.version, uploadedAt: object.uploadedAt });
+    }
+    cursor = typeof page.next_cursor === "string" && page.next_cursor ? page.next_cursor : null;
+  } while (cursor);
+  objects.sort((left, right) => left.key.localeCompare(right.key) || left.version.localeCompare(right.version));
+  return objects;
+}
+
+async function downloadObject(config, adminKey, backupId, bucket, object, backupDirectory) {
+  const fileName = createHash("sha256").update(`${bucket}\0${object.key}`).digest("hex");
+  const relativePath = `r2/${bucket}/${fileName}.object`;
+  const outputPath = resolve(backupDirectory, relativePath);
+  await mkdir(resolve(backupDirectory, `r2/${bucket}`), { recursive: true, mode: 0o700 });
+  const url = new URL(`/v1/admin/backups/${encodeURIComponent(backupId)}/r2/object`, config.publicBaseUrl);
+  url.searchParams.set("bucket", bucket);
+  url.searchParams.set("key", object.key);
+  url.searchParams.set("etag", object.etag);
+  const response = await fetch(url, { headers: { "x-admin-key": adminKey }, redirect: "error" });
+  if (!response.ok || !response.body) {
+    const body = await response.json().catch(() => ({}));
+    throw new Error(body?.error?.message ?? `R2 object download failed with HTTP ${response.status}`);
+  }
+  const hash = createHash("sha256");
+  let bytes = 0;
+  const meter = new Transform({
+    transform(chunk, _encoding, callback) {
+      hash.update(chunk);
+      bytes += chunk.length;
+      callback(null, chunk);
+    },
+  });
+  try {
+    await pipeline(Readable.fromWeb(response.body), meter, createWriteStream(outputPath, { flags: "wx", mode: 0o600 }));
+  } catch (error) {
+    await unlink(outputPath).catch(() => {});
+    throw error;
+  }
+  if (bytes !== object.size) throw new Error(`R2 object size changed during backup: ${bucket}/${object.key}`);
+  return { ...object, file: relativePath, digest: `sha256:${hash.digest("hex")}` };
+}
+
+async function downloadInventory(config, adminKey, backupId, inventories, backupDirectory) {
+  const jobs = BUCKETS.flatMap((bucket) => inventories[bucket].map((object) => ({ bucket, object })));
+  const results = new Array(jobs.length);
+  let next = 0;
+  const workers = Array.from({ length: Math.min(4, Math.max(1, jobs.length)) }, async () => {
+    while (true) {
+      const index = next;
+      next += 1;
+      if (index >= jobs.length) return;
+      const job = jobs[index];
+      results[index] = { bucket: job.bucket, ...await downloadObject(config, adminKey, backupId, job.bucket, job.object, backupDirectory) };
+    }
+  });
+  await Promise.all(workers);
+  return results;
+}
+
+async function markBackupFailed(config, adminKey, backupId) {
+  await apiJson(config.publicBaseUrl, adminKey, `/v1/admin/backups/${encodeURIComponent(backupId)}`, {
+    method: "PATCH",
+    headers: { "idempotency-key": randomUUID() },
+    body: JSON.stringify({ state: "failed", failure_code: "backup_client_failed" }),
+  }).catch(() => {});
+}
+
+export async function backupReports(argv = process.argv.slice(2)) {
+  const options = parseArguments(argv);
+  const { config } = await loadReportsPlan(options.config);
+  const plan = {
+    action: "backup",
+    database: config.resources.databaseName,
+    r2Buckets: [config.resources.profileMediaBucketName, config.resources.workflowArtifactsBucketName, config.resources.evidenceBucketName, config.resources.exportsBucketName],
+    outputDirectory: ".safest/backups/<installation>-<timestamp>-<backup-id>/",
+    includes: ["Committed D1 schema and rows", "All four private R2 bucket inventories and object bytes", "Per-object and manifest SHA-256 digests", "Durable backup verification record"],
+    excludes: ["pending Queue messages", "live Workflow engine internal state", "Worker secrets", "live Durable Object presence", "external webhook systems"],
+  };
+  console.log(JSON.stringify(plan, null, 2));
+  if (options.planOnly) return plan;
+
+  const secrets = parseSecrets(await readFile(resolve(projectRoot, options.secrets), "utf8"));
+  const adminKey = secrets.get("ADMIN_API_KEY");
+  if (!adminKey || adminKey.length < 32) throw new Error("The secrets file must contain ADMIN_API_KEY with at least 32 characters");
+  const versionResponse = await apiJson(config.publicBaseUrl, adminKey, "/v1/meta/version");
+  const versions = versionResponse?.version;
+  if (!versions || typeof versions.application !== "string" || typeof versions.databaseMigration !== "string"
+    || typeof versions.workflowCompiler !== "string" || typeof versions.workflowRuntimeProtocol !== "string") {
+    throw new Error("The deployed service did not return a complete version inventory");
+  }
+  const backupId = randomUUID();
+  const started = await apiJson(config.publicBaseUrl, adminKey, "/v1/admin/backups", {
+    method: "POST",
+    headers: { "idempotency-key": backupId },
+    body: JSON.stringify({
+      backup_id: backupId,
+      environment: new URL(config.publicBaseUrl).hostname,
+      application_version: versions.application,
+    }),
+  });
+  if (started.backupId !== backupId || started.state !== "running") throw new Error("The backup API did not start the requested backup");
+
+  const stamp = new Date().toISOString().replaceAll(":", "-");
+  const backupDirectory = resolve(projectRoot, `.safest/backups/${config.installationId}-${stamp}-${backupId}`);
+  const sqlPath = resolve(backupDirectory, "database.sql");
+  await mkdir(backupDirectory, { recursive: true, mode: 0o700 });
+
+  try {
+    await run(["d1", "export", "DB", "--remote", "--output", sqlPath, "--skip-confirmation"]);
+    const d1 = await sha256File(sqlPath);
+    const inventories = Object.fromEntries(await Promise.all(BUCKETS.map(async (bucket) => [bucket, await inventoryBucket(config, adminKey, backupId, bucket)])));
+    const downloaded = await downloadInventory(config, adminKey, backupId, inventories, backupDirectory);
+    const verificationInventories = Object.fromEntries(await Promise.all(BUCKETS.map(async (bucket) => [bucket, await inventoryBucket(config, adminKey, backupId, bucket)])));
+    for (const bucket of BUCKETS) {
+      if (inventoryFingerprint(inventories[bucket]) !== inventoryFingerprint(verificationInventories[bucket])) {
+        throw new Error(`R2 inventory changed during backup for ${bucket}; retry after writes settle`);
+      }
+    }
+    const objectBytes = downloaded.reduce((total, object) => total + object.size, 0);
+    const r2Manifest = {
+      schemaVersion: 1,
+      backupId,
+      installationId: config.installationId,
+      generatedAt: new Date().toISOString(),
+      verifiedStableInventory: true,
+      objectCount: downloaded.length,
+      objectBytes,
+      objects: downloaded,
+    };
+    const r2ManifestBytes = Buffer.from(`${JSON.stringify(r2Manifest, null, 2)}\n`);
+    const r2ManifestPath = resolve(backupDirectory, "r2-manifest.json");
+    await writeFile(r2ManifestPath, r2ManifestBytes, { mode: 0o600 });
+    const r2ManifestDigest = sha256Bytes(r2ManifestBytes);
+    await apiJson(config.publicBaseUrl, adminKey, `/v1/admin/backups/${encodeURIComponent(backupId)}`, {
+      method: "PATCH",
+      headers: { "idempotency-key": randomUUID() },
+      body: JSON.stringify({
+        state: "verified",
+        d1_export_reference: "database.sql",
+        d1_digest: d1.digest,
+        r2_manifest_reference: "r2-manifest.json",
+        r2_manifest_digest: r2ManifestDigest,
+        object_count: downloaded.length,
+        object_bytes: objectBytes,
+      }),
+    });
+    const manifest = {
+      schemaVersion: 2,
+      status: "verified",
+      backupId,
+      installationId: config.installationId,
+      sourcePublicBaseUrl: config.publicBaseUrl,
+      versions,
+      exportedAt: new Date().toISOString(),
+      d1: { file: "database.sql", bytes: d1.bytes, digest: d1.digest },
+      r2: { manifest: "r2-manifest.json", digest: r2ManifestDigest, objectCount: downloaded.length, objectBytes },
+      excludedState: ["pending Queue messages", "live Workflow engine internal state", "Worker secrets", "live Durable Object presence", "external provider state"],
+      verification: { d1Digest: true, r2ObjectSizes: true, r2ObjectDigests: true, stableR2Inventory: true, durableManifest: true },
+    };
+    const manifestBytes = Buffer.from(`${JSON.stringify(manifest, null, 2)}\n`);
+    await writeFile(resolve(backupDirectory, "manifest.json"), manifestBytes, { mode: 0o600 });
+    await writeFile(resolve(backupDirectory, "manifest.sha256"), `${sha256Bytes(manifestBytes)}  manifest.json\n`, { mode: 0o600 });
+    console.log(`Verified D1 and R2 backup: ${backupDirectory}`);
+    return manifest;
+  } catch (error) {
+    await markBackupFailed(config, adminKey, backupId);
+    throw error;
+  }
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  backupReports().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}

package/template/scripts/reports-cloudflare-preflight.mjs

@@ -0,0 +1,152 @@
+import * as clack from "@clack/prompts";
+import { spawn } from "node:child_process";
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+
+function runProcess(program, args, { cwd, inherit = false } = {}) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(program, args, {
+      cwd,
+      env: { ...process.env, WRANGLER_LOG: "none" },
+      stdio: inherit ? "inherit" : ["ignore", "pipe", "pipe"],
+    });
+    let stdout = "";
+    let stderr = "";
+    if (!inherit) {
+      child.stdout.on("data", (chunk) => { stdout += chunk; });
+      child.stderr.on("data", (chunk) => { stderr += chunk; });
+    }
+    child.once("error", reject);
+    child.once("exit", (code, signal) => resolvePromise({ code, signal, stdout, stderr }));
+  });
+}
+
+function jsonOutput(result, label) {
+  if (result.code !== 0) throw new Error(`${label} failed`);
+  try { return JSON.parse(result.stdout.trim()); } catch { throw new Error(`${label} returned an unreadable response`); }
+}
+
+export function findWorkersPaidSubscription(subscriptions) {
+  if (!Array.isArray(subscriptions)) return null;
+  return subscriptions.find((subscription) => {
+    const plan = subscription?.rate_plan ?? {};
+    const identity = [plan.id, plan.public_name, plan.scope, ...(Array.isArray(plan.sets) ? plan.sets : [])]
+      .filter(Boolean).join(" ").toLowerCase();
+    const isWorkersPlan = identity.includes("worker");
+    const isFree = /\bfree\b/u.test(identity);
+    const activePaidState = subscription?.state === "Paid" || subscription?.state === "Provisioned";
+    const hasPaidContract = plan.is_contract === true || (typeof subscription?.price === "number" && subscription.price > 0);
+    return isWorkersPlan && !isFree && (activePaidState || hasPaidContract);
+  }) ?? null;
+}
+
+async function fetchSubscriptions(accountId, token, fetchImpl) {
+  const response = await fetchImpl(`https://api.cloudflare.com/client/v4/accounts/${encodeURIComponent(accountId)}/subscriptions`, {
+    headers: { authorization: `Bearer ${token}`, accept: "application/json" },
+  });
+  const body = await response.json().catch(() => null);
+  if (!response.ok || body?.success !== true || !Array.isArray(body.result)) {
+    return { ok: false, status: response.status, body };
+  }
+  return { ok: true, subscriptions: body.result };
+}
+
+async function billingTokenFromUser(account, ui) {
+  ui.note(
+    `Wrangler is authenticated, but its OAuth grant cannot read billing subscriptions.\n\n` +
+      `Create a temporary read-only token for account “${account.name}”:\n` +
+      `1. Open https://dash.cloudflare.com/profile/api-tokens\n` +
+      `2. Create a custom token.\n` +
+      `3. Add Account → Billing → Read.\n` +
+      `4. Limit Account Resources to this account only.\n` +
+      `5. Paste the token here. It is used once, is never written to disk, and is never deployed.`,
+    "Workers Paid verification",
+  );
+  const action = await ui.select({
+    message: "Verify the Workers subscription",
+    options: [
+      { value: "token", label: "Enter read-only billing token" },
+      { value: "back", label: "Back", hint: "stop before provisioning anything" },
+    ],
+  });
+  if (clack.isCancel(action) || action === "back") return null;
+  const token = await ui.password({
+    message: "Temporary Cloudflare Billing Read token (input is masked)",
+    validate: (value) => value.trim() ? undefined : "Token is required",
+  });
+  return clack.isCancel(token) ? null : token.trim();
+}
+
+export async function verifyWorkersPaid({ account, wranglerToken, interactive, fetchImpl = fetch, ui = clack }) {
+  let verification = await fetchSubscriptions(account.id, process.env.CLOUDFLARE_BILLING_API_TOKEN || wranglerToken, fetchImpl);
+  if (!verification.ok && (verification.status === 401 || verification.status === 403) && !process.env.CLOUDFLARE_BILLING_API_TOKEN) {
+    if (!interactive) {
+      throw new Error("Workers Paid could not be verified. Set CLOUDFLARE_BILLING_API_TOKEN to a temporary Account Billing Read token and run setup again.");
+    }
+    const billingToken = await billingTokenFromUser(account, ui);
+    if (!billingToken) throw new Error("Setup cancelled before provisioning: Workers Paid was not verified.");
+    verification = await fetchSubscriptions(account.id, billingToken, fetchImpl);
+  }
+  if (!verification.ok) {
+    throw new Error(`Workers Paid could not be verified for “${account.name}” (Cloudflare API ${verification.status}). No resources were provisioned.`);
+  }
+  const subscription = findWorkersPaidSubscription(verification.subscriptions);
+  if (!subscription) {
+    throw new Error(`“${account.name}” does not have an active Workers Paid subscription. Upgrade it in Cloudflare, then run setup again. No resources were provisioned.`);
+  }
+  return subscription;
+}
+
+export async function ensureWranglerAuthentication({ wrangler, projectRoot, interactive, ui = clack, runner = runProcess }) {
+  let result = await runner(process.execPath, [wrangler, "whoami", "--json"], { cwd: projectRoot });
+  if (result.code !== 0) {
+    if (!interactive) throw new Error("Cloudflare login is required. Run `npx wrangler login`, approve the requested permissions, then run setup again.");
+    ui.note(
+      "Your browser will open Cloudflare. Sign in to the account that will own Safest Resolve, review the Wrangler permissions, and approve them.",
+      "Cloudflare login",
+    );
+    const login = await runner(process.execPath, [wrangler, "login"], { cwd: projectRoot, inherit: true });
+    if (login.code !== 0) throw new Error("Cloudflare login was not completed. No resources were provisioned.");
+    result = await runner(process.execPath, [wrangler, "whoami", "--json"], { cwd: projectRoot });
+  }
+  const identity = jsonOutput(result, "Wrangler authentication check");
+  if (identity.loggedIn !== true || !Array.isArray(identity.accounts) || !identity.accounts.length) {
+    throw new Error("Wrangler is authenticated but no accessible Cloudflare account was found.");
+  }
+  const tokenResult = await runner(process.execPath, [wrangler, "auth", "token", "--json"], { cwd: projectRoot });
+  const token = jsonOutput(tokenResult, "Wrangler token lookup");
+  if (typeof token.token !== "string" || !token.token) throw new Error("Wrangler did not provide an API token for preflight checks.");
+  return { identity, token: token.token };
+}
+
+export async function chooseCloudflareAccount({ identity, wranglerConfigPath, interactive, ui = clack }) {
+  const absolute = resolve(wranglerConfigPath);
+  const wranglerConfig = JSON.parse(await readFile(absolute, "utf8"));
+  const configured = typeof wranglerConfig.account_id === "string" ? wranglerConfig.account_id : "";
+  if (configured) {
+    const account = identity.accounts.find(({ id }) => id === configured);
+    if (!account) throw new Error(`wrangler.jsonc selects account ${configured}, but the current Wrangler login cannot access it.`);
+    return { account, wranglerConfig, path: absolute, changed: false };
+  }
+  let account;
+  if (identity.accounts.length === 1) account = identity.accounts[0];
+  else {
+    if (!interactive) throw new Error("Multiple Cloudflare accounts are available. Add the intended account_id to wrangler.jsonc, then run setup again.");
+    const selected = await ui.select({
+      message: "Which Cloudflare account should own Safest Resolve?",
+      options: [
+        ...identity.accounts.map((candidate) => ({ value: candidate.id, label: candidate.name, hint: candidate.id })),
+        { value: "back", label: "Back", hint: "stop before provisioning anything" },
+      ],
+    });
+    if (clack.isCancel(selected) || selected === "back") throw new Error("Setup cancelled before provisioning: no Cloudflare account was selected.");
+    account = identity.accounts.find(({ id }) => id === selected);
+  }
+  if (!account) throw new Error("The selected Cloudflare account is unavailable.");
+  return { account, wranglerConfig: { ...wranglerConfig, account_id: account.id }, path: absolute, changed: true };
+}
+
+export async function saveCloudflareAccountSelection(selection) {
+  if (!selection.changed) return;
+  await writeFile(selection.path, `${JSON.stringify(selection.wranglerConfig, null, 2)}\n`, "utf8");
+}

package/template/scripts/reports-deploy.mjs

@@ -0,0 +1,173 @@
+import { spawn } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import { dirname, resolve } from "node:path";
+import { createInterface } from "node:readline/promises";
+import { fileURLToPath } from "node:url";
+import { configureAuthentication, requiredOAuthSecrets } from "./reports-auth-onboarding.mjs";
+import {
+  chooseCloudflareAccount,
+  ensureWranglerAuthentication,
+  saveCloudflareAccountSelection,
+  verifyWorkersPaid,
+} from "./reports-cloudflare-preflight.mjs";
+import { loadReportsPlan } from "./reports-plan.mjs";
+import { initializeSecrets, parseSecrets } from "./reports-secrets.mjs";
+
+const projectRoot = fileURLToPath(new URL("..", import.meta.url));
+const wrangler = fileURLToPath(new URL("../node_modules/wrangler/bin/wrangler.js", import.meta.url));
+const REQUIRED_SECRETS = ["BETTER_AUTH_SECRET", "ADMIN_API_KEY", "CONTEXT_SIGNING_SECRET", "CREDENTIAL_ENCRYPTION_KEY", "RATE_LIMIT_PEPPER", "INTEGRATION_API_KEYS_JSON"];
+
+function parseArguments(argv) {
+  const result = { planOnly: false, yes: false, upgrade: false, config: "reports.config.json", secrets: ".safest/secrets.env" };
+  for (let index = 0; index < argv.length; index += 1) {
+    const argument = argv[index];
+    if (argument === "--plan") result.planOnly = true;
+    else if (argument === "--yes") result.yes = true;
+    else if (argument === "--upgrade") result.upgrade = true;
+    else if (argument === "--config" || argument === "--secrets-file") {
+      const value = argv[index + 1];
+      if (!value || value.startsWith("-")) throw new Error(`${argument} needs a value`);
+      index += 1;
+      if (argument === "--config") result.config = value;
+      else result.secrets = value;
+    } else throw new Error(`unknown option: ${argument}`);
+  }
+  return result;
+}
+
+function runWrangler(args, label) {
+  return new Promise((resolvePromise, reject) => {
+    console.log(`\n${label}`);
+    const child = spawn(process.execPath, [wrangler, ...args], { cwd: projectRoot, env: process.env, stdio: "inherit" });
+    child.once("error", reject);
+    child.once("exit", (code, signal) => code === 0 ? resolvePromise() : reject(new Error(`${label} failed${signal ? ` with signal ${signal}` : ` with exit code ${code}`}`)));
+  });
+}
+
+export function isExistingResourceError(output) {
+  return /already exists|already (?:been )?taken|duplicate resource/iu.test(output);
+}
+
+function ensureWranglerResource(args, label) {
+  return new Promise((resolvePromise, reject) => {
+    console.log(`\n${label}`);
+    const child = spawn(process.execPath, [wrangler, ...args], { cwd: projectRoot, env: process.env, stdio: ["inherit", "pipe", "pipe"] });
+    let output = "";
+    child.stdout.on("data", (chunk) => { output += chunk; process.stdout.write(chunk); });
+    child.stderr.on("data", (chunk) => { output += chunk; process.stderr.write(chunk); });
+    child.once("error", reject);
+    child.once("exit", (code, signal) => {
+      if (code === 0) return resolvePromise();
+      if (isExistingResourceError(output)) {
+        console.log("Resource already exists; reusing the exact configured name.");
+        return resolvePromise();
+      }
+      reject(new Error(`${label} failed${signal ? ` with signal ${signal}` : ` with exit code ${code}`}`));
+    });
+  });
+}
+
+async function validateSecrets(path, config) {
+  const raw = await readFile(path, "utf8");
+  const values = parseSecrets(raw);
+  const missing = [...REQUIRED_SECRETS, ...requiredOAuthSecrets(config)].filter((name) => !values[name]);
+  if (missing.length) throw new Error(`secrets file is missing: ${missing.join(", ")}`);
+  for (const name of ["BETTER_AUTH_SECRET", "ADMIN_API_KEY", "CONTEXT_SIGNING_SECRET", "CREDENTIAL_ENCRYPTION_KEY", "RATE_LIMIT_PEPPER"]) {
+    if ((values[name] ?? "").length < 32) throw new Error(`${name} must contain at least 32 characters`);
+  }
+  try {
+    const keys = JSON.parse(values.INTEGRATION_API_KEYS_JSON);
+    if (!keys || typeof keys !== "object" || Array.isArray(keys) || !Object.keys(keys).length) throw new Error();
+  } catch { throw new Error("INTEGRATION_API_KEYS_JSON must be a non-empty JSON object"); }
+}
+
+async function hasDatabaseId() {
+  const config = JSON.parse(await readFile(resolve(projectRoot, "wrangler.jsonc"), "utf8"));
+  return typeof config?.d1_databases?.[0]?.database_id === "string" && config.d1_databases[0].database_id.length > 0;
+}
+
+async function confirmation(installationId, yes) {
+  if (yes) return;
+  if (!process.stdin.isTTY) throw new Error("interactive confirmation is required; use --yes only after reviewing setup:plan");
+  const input = createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const expected = `DEPLOY ${installationId}`;
+    const actual = (await input.question(`\nType ${expected} to create or update these customer-owned resources: `)).trim();
+    if (actual !== expected) throw new Error("deployment confirmation did not match");
+  } finally { input.close(); }
+}
+
+export async function deployReports(argv = process.argv.slice(2)) {
+  const options = parseArguments(argv);
+  let { config, plan } = await loadReportsPlan(options.config);
+  console.log(JSON.stringify({ action: options.upgrade ? "upgrade" : "install", ...plan }, null, 2));
+  if (options.planOnly) return { status: "planned", plan };
+  if (!plan.ready) throw new Error(plan.blockers.join(" "));
+  const interactive = process.stdin.isTTY && !options.yes;
+  const authentication = await ensureWranglerAuthentication({ wrangler, projectRoot, interactive });
+  const accountSelection = await chooseCloudflareAccount({
+    identity: authentication.identity,
+    wranglerConfigPath: resolve(projectRoot, "wrangler.jsonc"),
+    interactive,
+  });
+  const subscription = await verifyWorkersPaid({
+    account: accountSelection.account,
+    wranglerToken: authentication.token,
+    interactive,
+  });
+  await saveCloudflareAccountSelection(accountSelection);
+  console.log(`\nWorkers Paid verified for ${accountSelection.account.name} (${subscription.rate_plan?.public_name ?? "active Workers subscription"}).`);
+  const secretsPath = resolve(projectRoot, options.secrets);
+  try {
+    await readFile(secretsPath, "utf8");
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+    await initializeSecrets(secretsPath);
+    console.log(`Created ${secretsPath} with generated owner-only secrets.`);
+  }
+  if (!options.upgrade) {
+    const configured = await configureAuthentication({
+      configPath: resolve(projectRoot, options.config),
+      secretsPath,
+      config,
+      interactive,
+    });
+    if (configured.cancelled) throw new Error("Setup cancelled before provisioning. No Cloudflare resources were created.");
+    ({ config, plan } = await loadReportsPlan(options.config));
+  }
+  await validateSecrets(secretsPath, config);
+  await confirmation(config.installationId, options.yes);
+  const databaseConfigured = await hasDatabaseId();
+  if (options.upgrade && !databaseConfigured) throw new Error("upgrade requires an existing D1 database_id in wrangler.jsonc");
+  if (!options.upgrade && databaseConfigured) throw new Error("this project already has a D1 database_id; use npm run upgrade instead of setup");
+  if (!options.upgrade) {
+    await runWrangler(["d1", "create", config.resources.databaseName, "--binding", "DB", "--update-config"], "Create the customer-owned D1 database");
+  }
+  await ensureWranglerResource(["r2", "bucket", "create", config.resources.profileMediaBucketName], "Ensure the private profile-media R2 bucket exists");
+  await ensureWranglerResource(["r2", "bucket", "create", config.resources.workflowArtifactsBucketName], "Ensure the private workflow-artifacts R2 bucket exists");
+  await ensureWranglerResource(["r2", "bucket", "create", config.resources.evidenceBucketName], "Ensure the private evidence R2 bucket exists");
+  await ensureWranglerResource(["r2", "bucket", "create", config.resources.exportsBucketName], "Ensure the private exports R2 bucket exists");
+  await ensureWranglerResource(["queues", "create", config.resources.reportQueueName], "Ensure the report jobs Queue exists");
+  await ensureWranglerResource(["queues", "create", config.resources.deliveryQueueName], "Ensure the delivery jobs Queue exists");
+  await ensureWranglerResource(["queues", "create", config.resources.operationsDlqName], "Ensure the operations dead-letter Queue exists");
+  await runWrangler(["d1", "migrations", "apply", "DB", "--remote"], "Apply forward-only report migrations");
+  await runWrangler(["deploy", "--secrets-file", secretsPath, "--strict"], "Deploy the reports Worker and bindings");
+  const installationPath = resolve(projectRoot, ".safest/installation.json");
+  await mkdir(dirname(installationPath), { recursive: true, mode: 0o700 });
+  await writeFile(installationPath, `${JSON.stringify({
+    schemaVersion: 1,
+    installationId: config.installationId,
+    installedAt: new Date().toISOString(),
+    resources: config.resources,
+    accessAudience: config.access.audience,
+  }, null, 2)}\n`, { mode: 0o600 });
+  console.log("\nDeployment finished. Verify public /health, bootstrap the infrastructure owner through Access, run the authenticated setup feature checks until /ready succeeds, invite an administrator and analyst, then verify one server report and Queue consumption before production traffic.");
+  return { status: "deployed", plan };
+}
+
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+  deployReports().catch((error) => {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  });
+}