create-safest-tools 0.3.1 → 0.4.1

package/README.md

@@ -18,7 +18,7 @@ npx create-safest-tools safest-resolve \
   --email-from reports@example.com
 ```
 
-The `--email-from` address must belong to a domain onboarded under Cloudflare Email Service → Email Sending. Domain onboarding permits delivery to arbitrary invited users; invitations, email verification, and forgot-password delivery use this address.
+The `--email-from` address is used only for reporter receipts, follow-ups, and outcomes, and must belong to a domain onboarded under Cloudflare Email Service → Email Sending. Account verification, invitations, and password recovery use a distinct `accounts@` address on the same domain by default; pass `--auth-email-from` to choose another address.
 
 The command creates a local project and prints a read-only infrastructure plan. It does not change Cloudflare unless `--deploy` is supplied or the generated project’s `npm run setup` command is run and explicitly confirmed.
 
@@ -46,6 +46,8 @@ npm run setup
 
 `setup:plan` lists exact resource names and exits without modifying Cloudflare. `setup` opens Wrangler's Cloudflare login when needed, lets you choose the owning account, and verifies Workers Paid from the account's Workers usage model. Standard accounts need no separate billing token; only legacy or ambiguous account models use the temporary Billing Read fallback. It then guides Google, GitHub, and Cloudflare OAuth configuration with exact callback URLs and masked secret input. Nothing is provisioned until the exact `DEPLOY <installation-id>` confirmation.
 
+A new installation applies one current D1 schema baseline. Later releases add only forward-compatible upgrade migrations.
+
 After deployment, setup prints a 256-bit, single-use owner link that expires after 15 minutes. The raw token stays in the URL fragment, D1 stores only its digest, and the installer never writes it to disk. Open it to create the Safest owner account. If it expires, run `npm run owner:setup`. For later break-glass recovery, authenticate Wrangler and run `npm run owner:recover`.
 
 Custom-domain installations disable both the Worker’s `workers.dev` route and version preview URLs. A `workers.dev` public URL is available only when explicitly supplied as the installation URL.
@@ -57,16 +59,18 @@ Invited users may join with a password or any configured OAuth provider, then ch
 ## Lifecycle
 
 ```bash
+npx create-safest-tools@latest update . --plan
+npx create-safest-tools@latest update .
 npm run backup:plan
 npm run backup
 npm run restore:verify -- .safest/backups/<backup-directory>
 npm run restore:plan -- .safest/backups/<backup-directory> --target-config reports.restore.config.json
-npm run upgrade:plan
-npm run upgrade
 npm run uninstall:plan
 ```
 
-Backups contain the D1 export and every object in the four private R2 buckets, with stable inventories and SHA-256 verification. They intentionally exclude pending Queue messages, live Workflow engine state, Worker secrets, external provider state, and ephemeral presence. Restore verification is local; restore planning requires a separate target installation and never mutates Cloudflare. Upgrade runs a verified backup before forward-only migrations and deployment.
+The updater hashes Safest-owned project files and refuses to overwrite local modifications. It preserves `reports.config.json`, owner-only secrets, backups, Cloudflare resource IDs, the Turnstile site key, customer webhook URLs, and the action allowlist; creates a local rollback snapshot; takes a verified D1/R2 backup; installs and validates the release; then applies forward-only migrations and deploys. `update . --plan` is read-only.
+
+Backups contain the D1 export and every object in the four private R2 buckets, with stable inventories and SHA-256 verification. They intentionally exclude pending Queue messages, live Workflow engine state, Worker secrets, external provider state, and ephemeral presence. Restore verification is local; restore planning requires a separate target installation and never mutates Cloudflare.
 
 The uninstall command is intentionally plan-only: it identifies the exact reporting resources but does not delete them. D1, all private R2 buckets, and secrets are preserved by default.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-safest-tools",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Create customer-owned abuse-reporting infrastructure on Cloudflare",
   "type": "module",
   "license": "Apache-2.0",

package/src/cli.mjs

@@ -5,6 +5,7 @@ import { createInterface } from "node:readline/promises";
 import { fileURLToPath } from "node:url";
 import { buildConfiguration } from "./config.mjs";
 import { scaffoldProject, validateGeneratedConfiguration } from "./scaffold.mjs";
+import { applyProjectUpdate, planProjectUpdate } from "./update.mjs";
 
 const packageRoot = fileURLToPath(new URL("..", import.meta.url));
 const packageVersion = JSON.parse(readFileSync(resolve(packageRoot, "package.json"), "utf8")).version;
@@ -15,6 +16,8 @@ function usage() {
 
 Usage:
   npx create-safest-tools [directory]
+  npx create-safest-tools update [directory] --plan
+  npx create-safest-tools update [directory]
   npx create-safest-tools safest-resolve --yes --name acme-resolve \\
     --public-url https://reports.example.com --origin https://app.example.com \\
     --owner-email infrastructure@example.com \\
@@ -26,11 +29,13 @@ Options:
   --origin origin        Allowed embedding/application origin; repeat as needed
   --owner-email email    Initial infrastructure owner bound to one-time setup
   --admin-email email    Deprecated alias for --owner-email
-  --email-from address   Address on an onboarded Email Sending domain (required)
+  --email-from address   Reporter-update sender on an onboarded Email Sending domain
+  --auth-email-from addr Account/invitation sender (default: accounts@same-domain)
   --yes                  Do not prompt for omitted optional values
   --skip-install         Create files without running npm install or setup:plan
   --deploy               Run setup after scaffolding (still requires exact confirmation)
   --dry-run              Print configuration and resource plan without writing
+  --plan                 Preview an update without changing local files or Cloudflare
   --help                 Show this help
   --version              Show the package version
 
@@ -46,12 +51,14 @@ function valueAfter(argv, index, option) {
 }
 
 export function parseArguments(argv) {
+  const commandName = argv[0] === "update" ? "update" : "create";
   const result = {
+    command: commandName,
     directory: null, installationName: null, publicBaseUrl: null, allowedOrigins: [],
-    ownerEmail: null, emailFromAddress: null, yes: false, skipInstall: false,
-    deploy: false, dryRun: false, help: false, version: false,
+    ownerEmail: null, emailFromAddress: null, authEmailFromAddress: null, yes: false, skipInstall: false,
+    deploy: false, dryRun: false, plan: false, help: false, version: false,
   };
-  for (let index = 0; index < argv.length; index += 1) {
+  for (let index = commandName === "update" ? 1 : 0; index < argv.length; index += 1) {
     const argument = argv[index];
     if (!argument.startsWith("-")) {
       if (result.directory) throw new Error("only one project directory can be provided");
@@ -60,9 +67,10 @@ export function parseArguments(argv) {
     else if (argument === "--skip-install") result.skipInstall = true;
     else if (argument === "--deploy") result.deploy = true;
     else if (argument === "--dry-run") result.dryRun = true;
+    else if (argument === "--plan") result.plan = true;
     else if (argument === "--help" || argument === "-h") result.help = true;
     else if (argument === "--version" || argument === "-v") result.version = true;
-    else if (["--name", "--public-url", "--origin", "--owner-email", "--admin-email", "--email-from"].includes(argument)) {
+    else if (["--name", "--public-url", "--origin", "--owner-email", "--admin-email", "--email-from", "--auth-email-from"].includes(argument)) {
       const value = valueAfter(argv, index, argument);
       index += 1;
       if (argument === "--name") result.installationName = value;
@@ -72,10 +80,16 @@ export function parseArguments(argv) {
         if (result.ownerEmail && result.ownerEmail !== value) throw new Error("provide only one infrastructure owner email");
         result.ownerEmail = value;
       }
-      else result.emailFromAddress = value;
+      else if (argument === "--email-from") result.emailFromAddress = value;
+      else result.authEmailFromAddress = value;
     } else throw new Error(`unknown option: ${argument}`);
   }
   if (result.deploy && result.skipInstall) throw new Error("--deploy cannot be used with --skip-install");
+  if (result.command === "create" && result.plan) throw new Error("--plan is available only with the update command");
+  if (result.command === "update" && (result.installationName || result.publicBaseUrl || result.allowedOrigins.length
+    || result.ownerEmail || result.emailFromAddress || result.authEmailFromAddress || result.skipInstall || result.deploy || result.dryRun)) {
+    throw new Error("update accepts only a project directory, --plan, and --yes");
+  }
   return result;
 }
 
@@ -97,16 +111,47 @@ async function completeInteractive(options, input) {
   options.publicBaseUrl ||= await ask(input, "Public reports origin", "https://reports.example.com");
   if (!options.allowedOrigins.length) options.allowedOrigins.push(await ask(input, "Application origin allowed to embed the report form", "https://app.example.com"));
   options.ownerEmail ||= await ask(input, "Infrastructure owner email");
-  options.emailFromAddress ||= await ask(input, "Sender address on a Cloudflare Email Sending domain");
+  options.emailFromAddress ||= await ask(input, "Reporter-update sender on a Cloudflare Email Sending domain");
   return options;
 }
 
+function publicUpdatePlan(plan) {
+  const { manifest: _manifest, targetFiles: _targetFiles, desiredWrangler: _desiredWrangler, ...result } = plan;
+  return result;
+}
+
+async function confirmUpdate(plan, input) {
+  const expected = `UPDATE ${plan.fromVersion} TO ${plan.toVersion}`;
+  const actual = (await input.question(`Type ${expected} to back up and update this Safest deployment: `)).trim();
+  if (actual !== expected) throw new Error("update confirmation did not match");
+}
+
 export async function runCli(argv, dependencies = {}) {
   const output = dependencies.output ?? console;
   const options = parseArguments(argv);
   if (options.help) { output.log(usage()); return { status: "help" }; }
   if (options.version) { output.log(packageVersion); return { status: "version" }; }
   const interactive = dependencies.interactive ?? (process.stdin.isTTY && !options.yes);
+  if (options.command === "update") {
+    const directory = resolve(options.directory ?? ".");
+    const templateDirectory = dependencies.templateDirectory ?? defaultTemplateDirectory;
+    const planner = dependencies.planProjectUpdate ?? planProjectUpdate;
+    const applier = dependencies.applyProjectUpdate ?? applyProjectUpdate;
+    const updatePlan = await planner({ directory, templateDirectory });
+    output.log(JSON.stringify(publicUpdatePlan(updatePlan), null, 2));
+    if (options.plan) return { status: "update-planned", plan: publicUpdatePlan(updatePlan) };
+    if (!updatePlan.ready) throw new Error(`update is blocked by locally modified managed files: ${updatePlan.conflicts.join(", ")}`);
+    if (!options.yes) {
+      if (!interactive) throw new Error("interactive update confirmation is required; use --yes only after reviewing update --plan");
+      const input = createInterface({ input: process.stdin, output: process.stdout });
+      try { await (dependencies.confirmUpdate ?? confirmUpdate)(updatePlan, input); } finally { input.close(); }
+    }
+    const result = await applier({ plan: updatePlan, templateDirectory, runner: dependencies.commandRunner });
+    output.log(result.status === "current"
+      ? `Safest Resolve is already current at ${result.toVersion}.`
+      : `Updated Safest Resolve from ${result.fromVersion} to ${result.toVersion}.`);
+    return result;
+  }
   if (interactive) {
     const input = createInterface({ input: process.stdin, output: process.stdout });
     try { await completeInteractive(options, input); } finally { input.close(); }

package/src/config.mjs

@@ -23,6 +23,20 @@ function optionalEmail(value, field) {
   return result;
 }
 
+function defaultAuthEmail(reporterEmail) {
+  const at = reporterEmail.lastIndexOf("@");
+  if (at < 1) return "";
+  const domain = reporterEmail.slice(at + 1);
+  return `${reporterEmail.slice(0, at).toLowerCase() === "accounts" ? "auth" : "accounts"}@${domain}`;
+}
+
+function emailAddresses(config) {
+  const reporter = optionalEmail(config.email?.fromAddress, "email.fromAddress");
+  const auth = optionalEmail(config.email?.authFromAddress, "email.authFromAddress") || defaultAuthEmail(reporter);
+  if (reporter && auth === reporter) throw new Error("authentication and reporter email senders must be different addresses");
+  return { reporter, auth };
+}
+
 function resource(base, suffix) {
   const prefix = base.slice(0, 63 - suffix.length - 1).replace(/-+$/u, "");
   return `${prefix}-${suffix}`;
@@ -37,6 +51,9 @@ export function buildConfiguration(options) {
   if (!ownerEmail) throw new Error("--owner-email is required");
   const emailFromAddress = optionalEmail(options.emailFromAddress, "email sender");
   if (!emailFromAddress) throw new Error("--email-from is required and its domain must be onboarded to Cloudflare Email Sending");
+  const authEmailFromAddress = optionalEmail(options.authEmailFromAddress, "authentication email sender")
+    || defaultAuthEmail(emailFromAddress);
+  if (authEmailFromAddress === emailFromAddress) throw new Error("--auth-email-from must differ from --email-from");
   const resources = {
     workerName: resource(installationId, "worker"),
     databaseName: resource(installationId, "db"),
@@ -61,7 +78,7 @@ export function buildConfiguration(options) {
     publicBaseUrl,
     allowedOrigins,
     owner: { email: ownerEmail },
-    email: { enabled: true, fromAddress: emailFromAddress },
+    email: { enabled: true, fromAddress: emailFromAddress, authFromAddress: authEmailFromAddress },
     auth: { password: true, providers: [] },
     retention: { reportsDays: 365, messagesDays: 180, appealWindowDays: 30 },
   };
@@ -70,6 +87,7 @@ export function buildConfiguration(options) {
 export function buildWranglerConfiguration(config) {
   const publicHostname = new URL(config.publicBaseUrl).hostname.toLowerCase();
   const usesWorkersDev = publicHostname.endsWith(".workers.dev");
+  const email = emailAddresses(config);
   const wrangler = {
     $schema: "node_modules/wrangler/config-schema.json",
     name: config.resources.workerName,
@@ -126,15 +144,18 @@ export function buildWranglerConfiguration(config) {
       ACTION_WEBHOOK_URL: "",
       NOTIFICATION_WEBHOOK_URL: "",
       OPERATOR_NOTIFICATION_WEBHOOK_URL: "",
-      AUTH_EMAIL_FROM: config.email.fromAddress,
-      EMAIL_FROM_ADDRESS: config.email.fromAddress,
-      EMAIL_SUBJECT_PREFIX: "Safest report update",
+      AUTH_EMAIL_FROM: email.auth,
+      REPORTER_EMAIL_FROM: email.reporter,
+      REPORTER_EMAIL_SUBJECT_PREFIX: "Safest report update",
     },
     triggers: { crons: ["*/5 * * * *"] },
   };
   if (!usesWorkersDev) {
     wrangler.routes = [{ pattern: publicHostname, custom_domain: true }];
   }
-  wrangler.send_email = [{ name: "EMAIL" }];
+  wrangler.send_email = [
+    { name: "AUTH_EMAIL", allowed_sender_addresses: [email.auth] },
+    { name: "REPORTER_EMAIL", allowed_sender_addresses: [email.reporter] },
+  ];
   return wrangler;
 }

package/src/scaffold.mjs

@@ -2,6 +2,7 @@ import { cp, mkdir, readdir, writeFile } from "node:fs/promises";
 import { resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { buildWranglerConfiguration } from "./config.mjs";
+import { createManagedManifest } from "./update.mjs";
 
 export async function assertEmptyDestination(directory) {
   try {
@@ -18,8 +19,10 @@ export async function scaffoldProject({ directory, templateDirectory, configurat
   await mkdir(destination, { recursive: true });
   await cp(templateDirectory, destination, { recursive: true });
   await writeFile(resolve(destination, "reports.config.json"), `${JSON.stringify(configuration, null, 2)}\n`);
-  await writeFile(resolve(destination, "wrangler.jsonc"), `${JSON.stringify(buildWranglerConfiguration(configuration), null, 2)}\n`);
+  const wranglerConfiguration = buildWranglerConfiguration(configuration);
+  await writeFile(resolve(destination, "wrangler.jsonc"), `${JSON.stringify(wranglerConfiguration, null, 2)}\n`);
   try { await cp(resolve(destination, "gitignore.template"), resolve(destination, ".gitignore")); } catch (error) { if (error?.code !== "ENOENT") throw error; }
+  await createManagedManifest({ directory: destination, templateDirectory, wranglerConfiguration });
   return destination;
 }
 

package/src/update.mjs

@@ -0,0 +1,295 @@
+import { createHash } from "node:crypto";
+import { spawn } from "node:child_process";
+import { copyFile, mkdir, readFile, readdir, rm, stat, writeFile } from "node:fs/promises";
+import { dirname, join, relative, resolve, sep } from "node:path";
+import { buildWranglerConfiguration } from "./config.mjs";
+
+const MANIFEST_PATH = ".safest-managed.json";
+const MANIFEST_SCHEMA_VERSION = 1;
+const REBUILDABLE_PATHS = new Set(["public/console/auth-shell.js"]);
+const CUSTOMER_RUNTIME_VAR_KEYS = new Set([
+  "ALLOWED_ACTION_CODES",
+  "TURNSTILE_SITE_KEY",
+  "ACTION_WEBHOOK_URL",
+  "NOTIFICATION_WEBHOOK_URL",
+  "OPERATOR_NOTIFICATION_WEBHOOK_URL",
+]);
+
+function stableValue(value) {
+  if (Array.isArray(value)) return value.map(stableValue);
+  if (value && typeof value === "object") {
+    return Object.fromEntries(Object.keys(value).sort().map((key) => [key, stableValue(value[key])]));
+  }
+  return value;
+}
+
+function stableJson(value) {
+  return JSON.stringify(stableValue(value));
+}
+
+function sha256(value) {
+  return createHash("sha256").update(value).digest("hex");
+}
+
+async function fileHash(path) {
+  return sha256(await readFile(path));
+}
+
+function portablePath(path) {
+  return path.split(sep).join("/");
+}
+
+async function filesBelow(directory, current = directory) {
+  const entries = await readdir(current, { withFileTypes: true });
+  const result = [];
+  for (const entry of entries.sort((left, right) => left.name.localeCompare(right.name))) {
+    const path = join(current, entry.name);
+    if (entry.isSymbolicLink()) throw new Error(`template contains an unsupported symbolic link: ${path}`);
+    if (entry.isDirectory()) result.push(...await filesBelow(directory, path));
+    else if (entry.isFile()) result.push(portablePath(relative(directory, path)));
+  }
+  return result;
+}
+
+async function templateFileHashes(templateDirectory) {
+  const result = {};
+  for (const path of await filesBelow(templateDirectory)) result[path] = await fileHash(resolve(templateDirectory, path));
+  result[".gitignore"] = result["gitignore.template"];
+  return result;
+}
+
+function normalizedWranglerConfiguration(configuration) {
+  const normalized = structuredClone(configuration);
+  delete normalized.account_id;
+  for (const database of normalized.d1_databases ?? []) {
+    delete database.database_id;
+    delete database.preview_database_id;
+  }
+  for (const key of CUSTOMER_RUNTIME_VAR_KEYS) delete normalized.vars?.[key];
+  return normalized;
+}
+
+function wranglerHash(configuration) {
+  return sha256(stableJson(normalizedWranglerConfiguration(configuration)));
+}
+
+function legacyWranglerHash(configuration) {
+  const normalized = structuredClone(configuration);
+  delete normalized.account_id;
+  for (const database of normalized.d1_databases ?? []) {
+    delete database.database_id;
+    delete database.preview_database_id;
+  }
+  return sha256(stableJson(normalized));
+}
+
+function wranglerMatchesManifest(configuration, expectedHash) {
+  if (wranglerHash(configuration) === expectedHash || legacyWranglerHash(configuration) === expectedHash) return true;
+  const preUpdateDefaults = structuredClone(configuration);
+  for (const key of CUSTOMER_RUNTIME_VAR_KEYS) {
+    if (key in (preUpdateDefaults.vars ?? {})) preUpdateDefaults.vars[key] = "";
+  }
+  return legacyWranglerHash(preUpdateDefaults) === expectedHash;
+}
+
+function mergeWranglerRuntimeState(desired, current) {
+  const result = structuredClone(desired);
+  if (typeof current.account_id === "string" && current.account_id) result.account_id = current.account_id;
+  for (const database of result.d1_databases ?? []) {
+    const installed = (current.d1_databases ?? []).find(({ binding }) => binding === database.binding);
+    if (!installed) continue;
+    for (const field of ["database_id", "preview_database_id"]) {
+      if (typeof installed[field] === "string" && installed[field]) database[field] = installed[field];
+    }
+  }
+  for (const key of CUSTOMER_RUNTIME_VAR_KEYS) {
+    if (typeof current.vars?.[key] === "string") result.vars[key] = current.vars[key];
+  }
+  return result;
+}
+
+async function templateVersion(templateDirectory) {
+  const metadata = JSON.parse(await readFile(resolve(templateDirectory, "package.json"), "utf8"));
+  if (typeof metadata.version !== "string" || !metadata.version) throw new Error("update template has no valid version");
+  return metadata.version;
+}
+
+async function writeManifest(directory, manifest) {
+  const path = resolve(directory, MANIFEST_PATH);
+  await mkdir(dirname(path), { recursive: true, mode: 0o700 });
+  await writeFile(path, `${JSON.stringify(manifest, null, 2)}\n`, { mode: 0o644 });
+}
+
+export async function createManagedManifest({ directory, templateDirectory, wranglerConfiguration }) {
+  const manifest = {
+    schemaVersion: MANIFEST_SCHEMA_VERSION,
+    installedVersion: await templateVersion(templateDirectory),
+    managedFiles: await templateFileHashes(templateDirectory),
+    wranglerHash: wranglerHash(wranglerConfiguration),
+  };
+  await writeManifest(directory, manifest);
+  return manifest;
+}
+
+async function readManifest(directory) {
+  let manifest;
+  try {
+    manifest = JSON.parse(await readFile(resolve(directory, MANIFEST_PATH), "utf8"));
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      throw new Error("this project predates safe updates; create a fresh project with create-safest-tools 0.4.0 or later");
+    }
+    throw error;
+  }
+  if (manifest?.schemaVersion !== MANIFEST_SCHEMA_VERSION || typeof manifest.installedVersion !== "string"
+    || !manifest.managedFiles || typeof manifest.managedFiles !== "object" || typeof manifest.wranglerHash !== "string") {
+    throw new Error("the Safest managed-file manifest is invalid or unsupported");
+  }
+  return manifest;
+}
+
+async function optionalFileHash(path) {
+  try { return await fileHash(path); }
+  catch (error) { if (error?.code === "ENOENT") return null; throw error; }
+}
+
+function numericVersion(version) {
+  const match = /^(\d+)\.(\d+)\.(\d+)(?:[-+].*)?$/u.exec(version);
+  if (!match) throw new Error(`unsupported Safest version: ${version}`);
+  return match.slice(1).map(Number);
+}
+
+function compareVersions(left, right) {
+  const leftParts = numericVersion(left);
+  const rightParts = numericVersion(right);
+  for (let index = 0; index < leftParts.length; index += 1) {
+    if (leftParts[index] !== rightParts[index]) return leftParts[index] - rightParts[index];
+  }
+  return 0;
+}
+
+async function readProjectJson(directory, name) {
+  try { return JSON.parse(await readFile(resolve(directory, name), "utf8")); }
+  catch (error) { throw new Error(`cannot read ${name} from the generated project: ${error instanceof Error ? error.message : String(error)}`); }
+}
+
+export async function planProjectUpdate({ directory, templateDirectory }) {
+  const projectDirectory = resolve(directory);
+  const [manifest, targetVersion, targetFiles, reportsConfiguration, currentWrangler] = await Promise.all([
+    readManifest(projectDirectory),
+    templateVersion(templateDirectory),
+    templateFileHashes(templateDirectory),
+    readProjectJson(projectDirectory, "reports.config.json"),
+    readProjectJson(projectDirectory, "wrangler.jsonc"),
+  ]);
+  if (compareVersions(targetVersion, manifest.installedVersion) < 0) {
+    throw new Error(`refusing to downgrade Safest Resolve from ${manifest.installedVersion} to ${targetVersion}`);
+  }
+
+  const added = [];
+  const updated = [];
+  const removed = [];
+  const conflicts = [];
+  for (const [path, installedHash] of Object.entries(manifest.managedFiles)) {
+    const currentHash = await optionalFileHash(resolve(projectDirectory, path));
+    if (!REBUILDABLE_PATHS.has(path) && currentHash !== installedHash) conflicts.push(path);
+    if (!(path in targetFiles)) removed.push(path);
+    else if (targetFiles[path] !== installedHash) updated.push(path);
+  }
+  for (const [path, targetHash] of Object.entries(targetFiles)) {
+    if (path in manifest.managedFiles) continue;
+    const currentHash = await optionalFileHash(resolve(projectDirectory, path));
+    if (currentHash !== null && currentHash !== targetHash) conflicts.push(path);
+    added.push(path);
+  }
+  if (!wranglerMatchesManifest(currentWrangler, manifest.wranglerHash)) conflicts.push("wrangler.jsonc");
+
+  const desiredWrangler = mergeWranglerRuntimeState(buildWranglerConfiguration(reportsConfiguration), currentWrangler);
+  const deployed = (currentWrangler.d1_databases ?? []).some(({ database_id: id }) => typeof id === "string" && id.length > 0);
+  const uniqueConflicts = [...new Set(conflicts)].sort();
+  return {
+    action: "update",
+    projectDirectory,
+    fromVersion: manifest.installedVersion,
+    toVersion: targetVersion,
+    deployed,
+    ready: uniqueConflicts.length === 0,
+    changes: { added: added.sort(), updated: updated.sort(), removed: removed.sort() },
+    conflicts: uniqueConflicts,
+    preserves: ["reports.config.json", ".safest/secrets.env", ".safest/backups/", "Cloudflare account_id", "D1 database_id", "Turnstile site key", "customer webhook URLs and action allowlist"],
+    manifest,
+    targetFiles,
+    desiredWrangler,
+  };
+}
+
+function defaultRunner(program, args, { cwd, label }) {
+  return new Promise((resolvePromise, reject) => {
+    const child = spawn(program, args, { cwd, 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}`}`)));
+  });
+}
+
+async function copyWithParents(source, destination) {
+  await mkdir(dirname(destination), { recursive: true });
+  await copyFile(source, destination);
+}
+
+async function createRollbackSnapshot(plan, now) {
+  const stamp = now.toISOString().replace(/[^0-9A-Z]+/giu, "-").replace(/-+$/u, "");
+  const snapshot = resolve(plan.projectDirectory, ".safest", "update-rollback", `${plan.fromVersion}-to-${plan.toVersion}-${stamp}`);
+  for (const path of Object.keys(plan.manifest.managedFiles)) {
+    const source = resolve(plan.projectDirectory, path);
+    try { await copyWithParents(source, resolve(snapshot, path)); }
+    catch (error) { if (error?.code !== "ENOENT") throw error; }
+  }
+  for (const path of ["reports.config.json", "wrangler.jsonc", "package-lock.json", MANIFEST_PATH]) {
+    const source = resolve(plan.projectDirectory, path);
+    try { await copyWithParents(source, resolve(snapshot, path)); }
+    catch (error) { if (error?.code !== "ENOENT") throw error; }
+  }
+  return snapshot;
+}
+
+async function syncManagedFiles(plan, templateDirectory) {
+  for (const path of plan.changes.removed) await rm(resolve(plan.projectDirectory, path), { force: true });
+  for (const path of Object.keys(plan.targetFiles)) {
+    const sourcePath = path === ".gitignore" ? "gitignore.template" : path;
+    await copyWithParents(resolve(templateDirectory, sourcePath), resolve(plan.projectDirectory, path));
+  }
+  await writeFile(resolve(plan.projectDirectory, "wrangler.jsonc"), `${JSON.stringify(plan.desiredWrangler, null, 2)}\n`);
+  await writeManifest(plan.projectDirectory, {
+    schemaVersion: MANIFEST_SCHEMA_VERSION,
+    installedVersion: plan.toVersion,
+    managedFiles: plan.targetFiles,
+    wranglerHash: wranglerHash(plan.desiredWrangler),
+  });
+}
+
+export async function applyProjectUpdate({ plan, templateDirectory, runner = defaultRunner, now = new Date() }) {
+  if (!plan.ready) throw new Error(`update is blocked by locally modified managed files: ${plan.conflicts.join(", ")}`);
+  const changed = plan.fromVersion !== plan.toVersion
+    || Object.values(plan.changes).some((paths) => paths.length > 0);
+  if (!changed) return { status: "current", fromVersion: plan.fromVersion, toVersion: plan.toVersion };
+  const snapshot = await createRollbackSnapshot(plan, now);
+  try {
+    if (plan.deployed) {
+      await runner("npm", ["run", "backup"], { cwd: plan.projectDirectory, label: "pre-update customer-data backup" });
+    }
+    await syncManagedFiles(plan, templateDirectory);
+    await runner("npm", ["install"], { cwd: plan.projectDirectory, label: "updated dependency installation" });
+    await runner("npm", ["run", "check"], { cwd: plan.projectDirectory, label: "updated project validation" });
+    if (plan.deployed) {
+      await runner("npm", ["run", "upgrade:plan"], { cwd: plan.projectDirectory, label: "Cloudflare upgrade plan" });
+      await runner("npm", ["run", "upgrade:deploy", "--", "--yes"], { cwd: plan.projectDirectory, label: "Cloudflare upgrade deployment" });
+    } else {
+      await runner("npm", ["run", "setup:plan"], { cwd: plan.projectDirectory, label: "updated setup plan" });
+    }
+  } catch (error) {
+    throw new Error(`Safest update stopped. The local rollback snapshot is ${snapshot}. ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return { status: plan.deployed ? "updated-and-deployed" : "updated-locally", fromVersion: plan.fromVersion, toVersion: plan.toVersion, snapshot };
+}

package/template/README.md

@@ -9,28 +9,30 @@ This project deploys one Worker, one D1 database, four private R2 buckets, a Dyn
 Before deployment:
 
 1. Review `reports.config.json` and `npm run setup:plan`.
-2. Under Cloudflare Email Service → Email Sending, onboard the configured sender domain. Invitations and password recovery to arbitrary recipients depend on domain onboarding.
+2. Under Cloudflare Email Service → Email Sending, onboard the configured sender domain. Reporter updates and account mail use separate sender addresses and sender-restricted bindings.
 3. Run `npm run setup`. The guided setup signs in through Wrangler and verifies Workers Paid from the account's Workers usage model before provisioning. Standard accounts need no separate billing token; only legacy or ambiguous models use the temporary Billing Read fallback. Setup then creates owner-only local secrets and walks through optional Google, GitHub, and Cloudflare OAuth credentials with exact callback URLs.
 4. Type the exact installation confirmation when setup requests it. After deployment, setup prints a 256-bit, single-use owner link that expires after 15 minutes and is never written to disk.
 5. Open the owner link, create the Safest owner account, then invite administrators and analysts from People. Nobody needs a Cloudflare account to sign in. Names and workspace roles are always displayed separately.
 
-Setup creates D1, four private R2 buckets, and three Queues, applies report migrations, and deploys the Worker with Dynamic Workflows. After owner setup, verify the `database`, `workflow_runtime`, `workers_ai`, `object_storage`, and `queues` setup features, then require an authenticated `GET /ready` response of 200. Public `GET /health` is liveness only. Better Auth owns password hashing, OAuth accounts, sessions, and one-time password-reset tokens in D1. Upgrades always back up D1 before migrations and deployment.
+Setup creates D1, four private R2 buckets, and three Queues, applies one current D1 schema baseline, and deploys the Worker with Dynamic Workflows. Later releases add only forward-compatible upgrade migrations. After owner setup, verify the `database`, `workflow_runtime`, `workers_ai`, `object_storage`, and `queues` setup features, then require an authenticated `GET /ready` response of 200. Public `GET /health` is liveness only. Better Auth owns password hashing, OAuth accounts, sessions, and one-time password-reset tokens in D1. Upgrades always back up D1 before migrations and deployment.
 
 If the setup link expires, run `npm run owner:setup`. If the owner loses access later, authenticate Wrangler as the Cloudflare account owner and run `npm run owner:recover`; the resulting single-use link creates a 12-hour break-glass session and is recorded in the audit log.
 
 Administrators build and preview questions in **Configuration → Intake forms**, set the logo, colours, fonts, and shape in **Settings → Branding**, then choose a private hosted page, signed-in product widget, or anonymous product widget in **Settings → Reporting channels**. Hosted pages and anonymous widgets need no API key. Signed-in widgets use one small customer-backend endpoint; verified reporter, target, and registered trusted facts stay server-side while the browser receives only a short-lived opaque token. Every public submission is verified with Turnstile inside a Resolve-owned isolated frame.
 
-Cloudflare Email Service and an `--email-from reports@example.com` address on an onboarded Email Sending domain are required for invitations, email verification, and password recovery. Participant notifications may still use a configured signed customer notification webhook.
+Cloudflare Email Service and an `--email-from reports@example.com` address on an onboarded Email Sending domain are required for reporter receipts, follow-ups, and outcomes. Invitations, email verification, and password recovery use a separate `accounts@` sender by default; `--auth-email-from` overrides it. A configured signed customer notification webhook remains the fallback for reference-only participants.
 
 ```bash
 npm run backup:plan
 npm run backup
 npm run restore:verify -- .safest/backups/<backup-directory>
 npm run restore:plan -- .safest/backups/<backup-directory> --target-config reports.restore.config.json
-npm run upgrade:plan
-npm run upgrade
+npx create-safest-tools@latest update . --plan
+npx create-safest-tools@latest update .
 ```
 
+The updater preserves customer configuration, secrets, backups, Cloudflare resource IDs, Turnstile configuration, customer webhook URLs, and the action allowlist. It blocks on locally modified Safest-owned files, creates a local rollback snapshot, takes a verified D1/R2 backup, validates the new release, then applies forward-only migrations and deploys. `update . --plan` is read-only.
+
 `npm run uninstall:plan` is deliberately read-only. It lists only the resources named by this installation and preserves D1 and all private R2 buckets by default.
 
 Verified backups contain the D1 export plus all objects from the four private R2 buckets, with a stable inventory and SHA-256 digests. They intentionally exclude pending Queue messages, live Workflow engine state, Worker secrets, external webhook state, and ephemeral analyst presence. Restore planning requires a separately named target installation and does not mutate Cloudflare.