@saastemly/voidcommerce 0.2.2 → 0.4.0

package/src/deploy/secrets.ts

@@ -0,0 +1,266 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { spawn } from "node:child_process";
+import { delimiter, dirname, join } from "node:path";
+import { tmpdir } from "node:os";
+import color from "picocolors";
+import { allEnvKeys } from "../generate/env";
+import { keyFor } from "./keys";
+import type { Project } from "../project";
+
+/**
+ * Secrets that live in the repository, encrypted.
+ *
+ * ── The problem this solves ──────────────────────────────────────────────
+ *
+ * A shop's secrets were set by hand, one `wrangler secret put` at a time,
+ * on a machine that happened to have them. Nothing in the repository said
+ * what the values WERE, only what they were called, so the shop could not
+ * be rebuilt from a checkout and a new deploy target needed somebody to
+ * remember. That is the last manual step between "push" and "live".
+ *
+ * dotenvx closes it. `.env.secrets` holds ciphertext and a public key, and
+ * it is COMMITTED: the key names are readable, the values are not, and a
+ * diff shows when a secret changed without showing what it changed to. The
+ * private key is not stored at all — it is derived from the Cloudflare API
+ * token, so whoever can deploy the worker can read its secrets and nobody
+ * else can. See `./keys.ts`, which also spells out what that costs.
+ *
+ * ── Why the values still become worker SECRETS ───────────────────────────
+ *
+ * The lazy version of this would decrypt at build time and let the values
+ * land in the worker's `vars`. That undoes the thing we built the scrub
+ * step for: `vars` are plaintext in the deployed configuration and readable
+ * by anyone with dashboard access. So the plaintext exists only inside the
+ * build, in a temp file, and goes up through `wrangler deploy
+ * --secrets-file`, which stores them as real secrets and — importantly —
+ * applies ADDITIVELY, so a secret this file does not name is left alone
+ * rather than deleted.
+ *
+ * ── The tradeoffs, stated ────────────────────────────────────────────────
+ *
+ * Ciphertext in git is permanent. A key that ever leaks reads every secret
+ * in the history, including ones that were rotated — which is not true of
+ * `wrangler secret put`, where a rotation genuinely retires the old value.
+ *
+ * And because the key is derived, rotating the API token orphans the lot.
+ * `keys.ts` guards that with a public-key check, so the failure is a clear
+ * refusal rather than a decryption error nobody can place — but the guard
+ * cannot recover values, only explain them.
+ *
+ * Both are the price of a shop that rebuilds from a checkout, and both
+ * should be decisions rather than surprises.
+ */
+
+export const SECRETS_FILE = ".env.secrets";
+export const PRIVATE_KEY_VAR = "DOTENV_PRIVATE_KEY_SECRETS";
+
+/** dotenvx, from the project's own install rather than a global one. */
+export function findDotenvx(from: string): string | null {
+	let dir = from;
+	for (;;) {
+		const local = join(dir, "node_modules", ".bin", "dotenvx");
+		if (existsSync(local)) return local;
+		const parent = dirname(dir);
+		if (parent === dir) break;
+		dir = parent;
+	}
+	return (process.env["PATH"] ?? "")
+		.split(delimiter)
+		.filter(Boolean)
+		.some((entry) => existsSync(join(entry, "dotenvx")))
+		? "dotenvx"
+		: null;
+}
+
+function run(cmd: string, args: string[], cwd: string, env: Record<string, string> = {}): Promise<{ code: number; out: string }> {
+	return new Promise((resolve) => {
+		const child = spawn(cmd, args, { cwd, stdio: ["ignore", "pipe", "pipe"], env: { ...process.env, ...env } });
+		let out = "";
+		child.stdout.on("data", (chunk) => {
+			out += chunk;
+		});
+		child.stderr.on("data", (chunk) => {
+			out += chunk;
+		});
+		child.on("error", (error) => resolve({ code: 1, out: String(error) }));
+		child.on("exit", (code) => resolve({ code: code ?? 1, out }));
+	});
+}
+
+/**
+ * The names a `.env.secrets` declares, read WITHOUT decrypting.
+ *
+ * dotenvx leaves keys in plaintext and encrypts only values, so preflight
+ * can say "all five are declared" on a machine that cannot read any of them.
+ */
+export function declaredSecretNames(root: string): Set<string> {
+	const path = join(root, SECRETS_FILE);
+	if (!existsSync(path)) return new Set();
+	const names = new Set<string>();
+	for (const line of readFileSync(path, "utf8").split("\n")) {
+		const match = /^\s*([A-Z][A-Z0-9_]*)\s*=/.exec(line);
+		if (match && !match[1]!.startsWith("DOTENV_")) names.add(match[1]!);
+	}
+	return names;
+}
+
+/** Is a declared value actually encrypted, or was it committed in the clear? */
+export function plaintextSecretNames(root: string): string[] {
+	const path = join(root, SECRETS_FILE);
+	if (!existsSync(path)) return [];
+	const bare: string[] = [];
+	for (const line of readFileSync(path, "utf8").split("\n")) {
+		const match = /^\s*([A-Z][A-Z0-9_]*)\s*=\s*(.*)$/.exec(line);
+		if (!match || match[1]!.startsWith("DOTENV_")) continue;
+		const value = match[2]!.trim().replace(/^['"]|['"]$/g, "");
+		// `unset` is the documented placeholder, not a leak.
+		if (value && value !== "unset" && !value.startsWith("encrypted:")) bare.push(match[1]!);
+	}
+	return bare;
+}
+
+export interface DecryptedSecrets {
+	/** A temp file in `.env` format, for `wrangler deploy --secrets-file`. */
+	path: string;
+	names: string[];
+	cleanup: () => void;
+}
+
+/**
+ * Decrypt into a temp file the deploy can hand to wrangler.
+ *
+ * Written to disk rather than piped because that is what `--secrets-file`
+ * takes, and removed by `cleanup()` whatever happens next.
+ */
+export async function decryptSecrets(project: Project): Promise<DecryptedSecrets | { error: string }> {
+	const root = project.root;
+	if (!existsSync(join(root, SECRETS_FILE))) return { error: `${SECRETS_FILE} does not exist — \`vc secrets init\` writes one` };
+
+	const dotenvx = findDotenvx(root);
+	if (!dotenvx) return { error: "dotenvx is not installed. `bun add -d @dotenvx/dotenvx`" };
+
+	// Derived from the API token, never read from disk. A mismatch is caught
+	// here rather than surfacing as a decryption failure nobody can explain.
+	const key = await keyFor(project.manifest, root);
+	if (!key.ok) return { error: key.reason };
+
+	const result = await run(dotenvx, ["decrypt", "-f", SECRETS_FILE, "--stdout"], root, {
+		[PRIVATE_KEY_VAR]: key.privateKey,
+	});
+	if (result.code !== 0) return { error: `dotenvx could not decrypt ${SECRETS_FILE}: ${result.out.trim().split("\n").slice(-2).join(" ")}` };
+
+	// Keep only the shop's own keys: dotenvx echoes the public key back, and
+	// it has no business being a worker secret.
+	const lines = result.out
+		.split("\n")
+		.filter((line) => /^\s*[A-Z][A-Z0-9_]*\s*=/.test(line) && !line.trimStart().startsWith("DOTENV_"));
+	const names = lines.map((line) => line.slice(0, line.indexOf("=")).trim());
+
+	const path = join(tmpdir(), `vc-secrets-${process.pid}-${Date.now()}.env`);
+	writeFileSync(path, `${lines.join("\n")}\n`, { mode: 0o600 });
+	return {
+		path,
+		names,
+		cleanup: () => {
+			try {
+				writeFileSync(path, "", { mode: 0o600 });
+				// Overwrite before unlinking: the plaintext existed on disk and
+				// should stop existing there promptly.
+				require("node:fs").unlinkSync(path);
+			} catch {
+				// Already gone, or never written. Nothing to do.
+			}
+		},
+	};
+}
+
+/** `vc secrets` — what the repository declares, and whether it is readable here. */
+export async function secretsCommand(project: Project, args: string[]): Promise<number> {
+	const root = project.root;
+	const required = allEnvKeys(project.manifest).filter((key) => !key.plaintext);
+	const declared = declaredSecretNames(root);
+	const bare = plaintextSecretNames(root);
+
+	if (args.includes("--init")) return initSecrets(project);
+
+	if (!existsSync(join(root, SECRETS_FILE))) {
+		console.log(
+			`\n${color.yellow("No " + SECRETS_FILE + " yet.")} Secrets are set by hand with \`wrangler secret put\`,\n` +
+				`which means the shop cannot be rebuilt from a checkout.\n\n` +
+				`  vc secrets --init    write one, with every required key as \`unset\`\n`,
+		);
+		return 1;
+	}
+
+	console.log(`\n${SECRETS_FILE} — committed, encrypted, and read by \`vc deploy --cloudflare\`\n`);
+	for (const key of required) {
+		const state = declared.has(key.key) ? color.green("declared") : color.red("MISSING ");
+		console.log(`  ${state}  ${key.key}`);
+	}
+	const extra = [...declared].filter((name) => !required.some((key) => key.key === name));
+	for (const name of extra) console.log(`  ${color.dim("extra   ")}  ${name} ${color.dim("— not required by this shop")}`);
+
+	if (bare.length > 0) {
+		console.log(
+			`\n${color.red("✗")} ${bare.length} value${bare.length === 1 ? " is" : "s are"} committed IN THE CLEAR: ${bare.join(", ")}\n` +
+				`  Run \`dotenvx encrypt -f ${SECRETS_FILE}\` before committing again.\n`,
+		);
+		return 1;
+	}
+	const missing = required.filter((key) => !declared.has(key.key));
+	if (missing.length > 0) {
+		console.log(
+			`\n${color.red("✗")} ${missing.length} required secret${missing.length === 1 ? "" : "s"} not declared.\n` +
+				`  dotenvx set ${missing[0]!.key} '…' -f ${SECRETS_FILE}\n`,
+		);
+		return 1;
+	}
+	console.log(`\n${color.green("✓")} every secret this shop needs is declared and encrypted.\n`);
+	return 0;
+}
+
+/** Write a `.env.secrets` with every required key as the `unset` sentinel. */
+async function initSecrets(project: Project): Promise<number> {
+	const path = join(project.root, SECRETS_FILE);
+	if (existsSync(path)) {
+		console.error(`vc: ${SECRETS_FILE} already exists; not overwriting it.`);
+		return 1;
+	}
+	// The PUBLIC key goes in the file, so `dotenvx encrypt` uses the derived
+	// pair rather than inventing one and writing a .env.keys.
+	const key = await keyFor(project.manifest, project.root);
+	if (!key.ok) {
+		console.error(`\nvc: ${key.reason}\n`);
+		return 1;
+	}
+	const required = allEnvKeys(project.manifest).filter((key) => !key.plaintext);
+	const body = [
+		"# Secrets, encrypted, and COMMITTED.",
+		"#",
+		"# Values are ciphertext; the key names are readable so a diff shows WHICH",
+		"# secret changed without showing what it changed to. `unset` is the",
+		"# documented placeholder and preflight refuses it.",
+		"#",
+		"# The private key is DERIVED from CLOUDFLARE_API_TOKEN, salted with the",
+		"# account id — it is stored nowhere, so there is no .env.keys to leak.",
+		"#",
+		"# The cost of that: rotating the token makes every value below",
+		"# permanently unreadable. `vc keys --rotate` re-encrypts while you still",
+		"# have the old token; after that there is no recovery.",
+		"",
+		`DOTENV_PUBLIC_KEY_SECRETS="${key.publicKey}"`,
+		"",
+		...required.flatMap((key) => [`# ${key.breaks}${key.where ? ` — from: ${key.where}` : ""}`, `${key.key}=unset`, ""]),
+	].join("\n");
+	writeFileSync(path, body, { mode: 0o600 });
+
+	console.log(
+		`\n${color.green("+")} ${SECRETS_FILE} — ${required.length} keys, all \`unset\`, under the key this token derives\n\n` +
+			`Next:\n` +
+			`  1. put the real values in, then\n` +
+			`  2. ${color.cyan(`bunx dotenvx encrypt -f ${SECRETS_FILE}`)}\n` +
+			`  3. commit it — there is no key file to keep out\n\n` +
+			color.yellow(`! Rotating CLOUDFLARE_API_TOKEN makes these unreadable. \`vc keys\` explains.\n`),
+	);
+	return 0;
+}

package/src/dist.ts

@@ -120,7 +120,9 @@ export async function distCommand(args: string[]): Promise<number> {
 
 	// The patches the pins refer to, and the lockfile, so the install is the
 	// one that was tested rather than whatever resolves today.
-	for (const file of ["bun.lock", "bun.lockb", "package-lock.json", "pnpm-lock.yaml"]) {
+	// The encrypted secrets travel with the app: they are ciphertext, and the
+	// branch Cloudflare builds is where the deploy command reads them.
+	for (const file of ["bun.lock", "bun.lockb", "package-lock.json", "pnpm-lock.yaml", ".env.secrets"]) {
 		const source = join(project.root, file);
 		if (existsSync(source)) await cp(source, join(target, file));
 	}

package/src/dotenvx-primitives.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@dotenvx/primitives` ships no types. Only one function is used here, and
+ * declaring just that is better than an `any` import: the shape is asserted
+ * in one place a reader can check against the package.
+ */
+declare module "@dotenvx/primitives" {
+	/** The secp256k1 public key for a private key, both as lowercase hex. */
+	export function derive(privateKey: string): string;
+	export function keypair(): { publicKey: string; privateKey: string };
+}

package/src/generate/ci.ts

@@ -137,13 +137,27 @@ and \`voidcommerce.json\` so every later generate carries the real ids.
 
 ### 3. The secrets
 
+They live in the repository, encrypted:
+
 \`\`\`sh
-vc preflight --cloudflare
+vc secrets --init                       # every required key, as \`unset\`
+# put the real values in, then
+bunx dotenvx encrypt -f .env.secrets    # ciphertext; commit this
 \`\`\`
 
-lists every required key, says what breaks without it, and prints the
-\`wrangler secret put\` line. On a Worker that has never been deployed, setting
-the first secret is what creates it.
+\`.env.secrets\` is committed and \`.env.keys\` is not. The deploy decrypts it and
+hands the values to \`wrangler deploy --secrets-file\`, which stores them as
+real Worker secrets — not as plaintext \`vars\`, which anyone with dashboard
+access can read.
+
+That turns one \`wrangler secret put\` per value into one build variable, set
+once in step 5. It also means the shop rebuilds from a checkout.
+
+**Know the tradeoff.** Ciphertext in git is permanent: if the private key ever
+leaks, every secret in the history is readable, including ones you rotated.
+\`wrangler secret put\` does not have that property, and stays available for
+anything you would rather never commit. \`vc preflight\` counts a secret the
+repository declares as present, and refuses any value committed in the clear.
 
 ### 4. An API token the build can use
 
@@ -178,9 +192,20 @@ the \`wrangler.jsonc\` at the root directory, or the build fails.
 | branch | \`${DIST_BRANCH}\` |
 | root directory | \`/\` |
 | build command | \`bun install && bunx void prepare && bunx vp build\` |
-| deploy command | \`bunx wrangler d1 migrations apply DB --remote && bunx wrangler deploy -c dist/ssr/wrangler.json\` |
+| deploy command | see below |
+| build variable | \`DOTENV_PRIVATE_KEY_SECRETS\`, marked as a secret — the one value that is not in the repository |
 | API token | the one from step 4 |
 
+The deploy command, on one line:
+
+\`\`\`sh
+bunx dotenvx decrypt -f .env.secrets --stdout > .vc-secrets.env && bunx wrangler d1 migrations apply DB --remote && bunx wrangler deploy -c dist/ssr/wrangler.json --secrets-file .vc-secrets.env
+\`\`\`
+
+Plain \`sh\`, so it does not rely on process substitution. The decrypted file
+exists only inside the build sandbox, and \`--secrets-file\` applies additively:
+a secret it does not name is left alone rather than deleted.
+
 The migration command names the **binding** (\`DB\`), not the database, so it
 still points at the right database if the name ever differs.
 

package/src/generate/index.ts

@@ -320,14 +320,43 @@ async function generateStrictRoot(root: string, manifest: Manifest, result: Gene
 			scripts["deploy"] ??= "vc deploy";
 			scripts["import:catalog"] ??= "vc import";
 			scripts["maildev"] ??= "maildev --smtp 1025 --web 1080";
+			scripts["secrets"] ??= "vc secrets";
+			// husky installs the hook on `bun install`, so a fresh clone is
+			// guarded without anybody remembering to run anything.
+			scripts["prepare"] ??= "husky";
 			pkg["scripts"] = scripts;
 		},
 		result,
 	);
 	// `.void` and `dist` are the STOREFRONT's build artifacts at the root now;
 	// `.vc` holds the generated worker and its own.
-	await put(root, ".gitignore", "node_modules\n.vc\n.void\n.wrangler\n.env\n.env.local\ndist\n*.tsbuildinfo\n.DS_Store\n", result, "own");
+	// `.env.keys` is the ONE thing that must never be committed: it is the
+	// authority to decrypt everything in `.env.secrets`, which is.
+	await put(
+		root,
+		".gitignore",
+		"node_modules\n.vc\n.void\n.wrangler\n.env\n.env.local\n.env.keys\ndist\n*.tsbuildinfo\n.DS_Store\n",
+		result,
+		"own",
+	);
 	await put(root, "patches/void@0.10.13.patch", renderVoidPatch(), result, "regenerate");
+	/**
+	 * The hook lives in `.husky/`, which is COMMITTED, so the guard travels
+	 * with the repository instead of being something each clone remembers to
+	 * install. A secret committed in the clear cannot be un-committed.
+	 */
+	await put(
+		root,
+		".husky/pre-commit",
+		`#!/usr/bin/env sh
+# Generated by \`vc init\`. Refuses a commit that would put a secret in the
+# clear in .env.secrets — which cannot be undone by a later commit,
+# because the value stays in the history.
+bunx vc guard
+`,
+		result,
+		"regenerate",
+	);
 	await put(root, ".github/workflows/void-dist.yml", renderDistWorkflow(manifest), result, "regenerate");
 	await put(root, "DEPLOY.md", renderDeployReadme(manifest, zone(manifest), workerHosts(manifest)), result, "regenerate");
 	await put(root, ".env", renderEnvLocal(manifest), result, "own");

package/src/generate/strict.ts

@@ -63,6 +63,11 @@ export function strictDependencies(manifest: Manifest): {
 		// The storefront at the root prerenders on the node target, whose SSR
 		// bundle imports this. Absent, a cold install builds nothing.
 		"@hono/node-server",
+		// The repository's secrets are encrypted with this; a build needs it to
+		// hand them to wrangler.
+		"@dotenvx/dotenvx",
+		// Installs the committed pre-commit hook on every fresh clone.
+		"husky",
 		"@rolldown/plugin-babel",
 		"@tailwindcss/vite",
 		"@types/node",

package/src/help.ts

@@ -17,6 +17,7 @@ export const EXTENDED_ROWS: Array<[command: string, summary: string]> = [
 	["vc dev | build | preview", "the app's own script, run where the app is — api/ for a monorepo, .vc/app for strict"],
 	["vc dist", "the deployable app as a self-contained tree — what the void-dist branch carries"],
 	["vc import", "push data/ and content/ into the running shop, as the shop itself — an upsert, safe on every deploy"],
+	["vc secrets", "the shop's secrets, encrypted and committed — one key where the deploy runs, instead of one wrangler secret put per value"],
 	["vc preflight", "is the shop ready to advertise on? every required key, and what breaks without it"],
 	["vc deploy", "preflight, then void deploy; or --cloudflare: wrangler, your own account, no Void login"],
 ];