@saastemly/voidcommerce 0.3.0 → 0.4.0

package/dist/index.js

@@ -57,7 +57,7 @@ import {
   routeProblem,
   strictDependencies,
   upsertJsonc
-} from "./index-84wq4qp8.js";
+} from "./index-yzezvy5h.js";
 import {
   LAYOUTS,
   MANIFEST_FILE,
@@ -77,7 +77,7 @@ import {
   writeManifest,
   zone,
   zoneOf
-} from "./index-zh3tmj08.js";
+} from "./index-pz6m2hkm.js";
 import {
   AUTH_PLUGINS,
   CARRIERS,
@@ -94,7 +94,8 @@ import {
   SIGN_IN,
   TAX,
   UI
-} from "./index-z4qazajn.js";
+} from "./index-844b3qn9.js";
+import"./index-0v6na3yp.js";
 export {
   zoneOf,
   zone,

package/dist/manifest.js

@@ -17,8 +17,9 @@ import {
   writeManifest,
   zone,
   zoneOf
-} from "./index-zh3tmj08.js";
-import"./index-z4qazajn.js";
+} from "./index-pz6m2hkm.js";
+import"./index-844b3qn9.js";
+import"./index-0v6na3yp.js";
 export {
   zoneOf,
   zone,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saastemly/voidcommerce",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Void, with a shop in it. `vc init` walks you through Better Auth, betterCommerce and every plugin; everything else passes through to `void`.",
   "type": "module",
   "license": "MIT",
@@ -34,6 +34,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^0.11.0",
+    "@dotenvx/primitives": "^2.2.0",
     "picocolors": "^1.1.1"
   },
   "devDependencies": {

package/src/cli.ts

@@ -1,4 +1,4 @@
-import { deployCommand, deployHelp, preflightCommand, preflightHelp, secretsCliCommand, secretsHelp } from "./deploy/index";
+import { deployCommand, deployHelp, guardCommand, keysCliCommand, keysHelp, preflightCommand, preflightHelp, secretsCliCommand, secretsHelp } from "./deploy/index";
 import { distCommand, distHelp } from "./dist";
 import { importCommand, importHelp } from "./import";
 import { fullHelp, initHelp, version } from "./help";
@@ -39,6 +39,9 @@ export const EXTENDED: Record<string, Extended> = {
 	deploy: { run: deployCommand, help: deployHelp },
 	preflight: { run: preflightCommand, help: preflightHelp },
 	secrets: { run: secretsCliCommand, help: secretsHelp },
+	keys: { run: keysCliCommand, help: keysHelp },
+	// Called by the generated pre-commit hook; exit code is the interface.
+	guard: { run: guardCommand, help: async () => guardCommand() },
 	dev: { run: appScript("dev"), help: appScriptHelp("dev") },
 	build: { run: appScript("build"), help: appScriptHelp("build") },
 	preview: { run: appScript("preview"), help: appScriptHelp("preview") },

package/src/deploy/index.ts

@@ -4,7 +4,8 @@ import { findProject } from "../project";
 import { captureVoid, runVoid } from "../void";
 import { deployCloudflare } from "./cloudflare";
 import { preflight, printPreflight } from "./preflight";
-import { PRIVATE_KEY_VAR, SECRETS_FILE, secretsCommand } from "./secrets";
+import { PRIVATE_KEY_VAR, SECRETS_FILE, plaintextSecretNames, secretsCommand } from "./secrets";
+import { keysCommand } from "./keys";
 
 /**
  * `vc deploy` extends `void deploy`: vc's preflight first, then void's
@@ -134,3 +135,55 @@ export async function secretsHelp(): Promise<number> {
 	);
 	return 0;
 }
+
+/** `vc keys` — what the token derives, and the warning that goes with it. */
+export async function keysCliCommand(args: string[]): Promise<number> {
+	const project = await findProject();
+	if (!project) {
+		console.error("vc: no voidcommerce.json here.");
+		return 1;
+	}
+	return keysCommand(project.manifest, project.root, args);
+}
+
+export async function keysHelp(): Promise<number> {
+	const width = 80;
+	console.log(
+		box("vc keys", [
+			line("The key that encrypts this repository's secrets is DERIVED from", width),
+			line("CLOUDFLARE_API_TOKEN, salted with the account id. Nothing is stored.", width),
+			line("", width),
+			...row("vc keys", "what this token derives, and whether it matches the repository", width, 2),
+			...row("vc keys --rotate", "re-encrypt under a new token, while the old one still works", width, 2),
+			line("", width),
+			line("Whoever can deploy the worker can read its secrets, and nobody else can.", width),
+			line("The price: rotating the token orphans every encrypted value, a second", width),
+			line("admin's token derives a different key, and the build must use the same", width),
+			line("token the values were encrypted under. `vc keys` checks the derived", width),
+			line("public key against the committed one, so a mismatch is a clear refusal", width),
+			line("rather than a decryption error nobody can place.", width),
+		], width),
+	);
+	return 0;
+}
+
+/**
+ * The pre-commit gate: refuse a commit that would put a secret in the clear.
+ *
+ * Exit code is the whole interface — a hook cares about nothing else.
+ */
+export async function guardCommand(): Promise<number> {
+	const project = await findProject();
+	if (!project) return 0; // Not a shop; nothing to guard.
+	const bare = plaintextSecretNames(project.root);
+	if (bare.length === 0) return 0;
+	console.error(
+		`\n${color.red("✗ refusing the commit")}: ${bare.length} value${bare.length === 1 ? "" : "s"} in ${SECRETS_FILE} ${
+			bare.length === 1 ? "is" : "are"
+		} not encrypted.\n\n` +
+			`    ${bare.join("\n    ")}\n\n` +
+			`  bunx dotenvx encrypt -f ${SECRETS_FILE}\n\n` +
+			color.dim("  Committing a secret in the clear cannot be undone by a later commit;\n  the value stays in the history and must be treated as burned.\n"),
+	);
+	return 1;
+}

package/src/deploy/keys.ts

@@ -0,0 +1,212 @@
+import { hkdfSync } from "node:crypto";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import color from "picocolors";
+import type { Manifest } from "../manifest";
+import { SECRETS_FILE } from "./secrets";
+
+/**
+ * The key that encrypts the repository's secrets, DERIVED rather than stored.
+ *
+ * ── What this buys, and what it costs ────────────────────────────────────
+ *
+ * Nothing has to be kept. There is no `.env.keys` to lose, leak, or forget to
+ * gitignore — a real failure that has already happened once here. Whoever can
+ * deploy the worker can read its secrets, and nobody else can, which is the
+ * property that was wanted.
+ *
+ * The cost is severe and worth stating plainly, because it is invisible until
+ * the day it is not:
+ *
+ *   **Rotating the API token orphans every secret in the repository.** The
+ *   key changes with the token, and the ciphertext does not. Every
+ *   `encrypted:` value becomes permanently unreadable, and the only recovery
+ *   is to type them all in again.
+ *
+ *   **A second admin derives a different key.** Two people with two tokens
+ *   cannot read each other's values.
+ *
+ *   **The build derives from whichever token it was given**, so the token in
+ *   the build settings must be the one the values were encrypted under.
+ *
+ * So this module's real job is not deriving a key — that is eight lines. It
+ * is making those three failures LOUD. The committed `.env.secrets` carries
+ * the public key, so the derived private key can always be checked against
+ * what the repository was actually encrypted under, and a mismatch is caught
+ * before anything is attempted rather than surfacing as a decryption failure
+ * nobody can explain.
+ *
+ * @see https://developers.cloudflare.com/workers/wrangler/system-environment-variables/
+ */
+
+/**
+ * Domain separation. A key derived for this purpose must not equal one
+ * derived for any other, so the label is versioned: changing it is how a
+ * future scheme migrates without colliding with this one.
+ */
+const INFO = "voidcommerce/dotenvx/secrets/v1";
+
+/** Where the token comes from, in the order wrangler itself reads them. */
+export function apiToken(): string | null {
+	return process.env["CLOUDFLARE_API_TOKEN"] || process.env["CF_API_TOKEN"] || null;
+}
+
+/**
+ * The private key this token and account derive.
+ *
+ * The account id is the salt rather than a constant, so the same token used
+ * against two accounts does not produce one key — tokens are often scoped to
+ * several accounts, and a shared key across them would be a wider blast
+ * radius than anyone asked for.
+ */
+export function derivePrivateKey(token: string, accountId: string): string {
+	const bytes = hkdfSync("sha256", Buffer.from(token, "utf8"), Buffer.from(accountId, "utf8"), Buffer.from(INFO), 32);
+	return Buffer.from(bytes).toString("hex");
+}
+
+/** The public key for a private one, via dotenvx's own primitive. */
+export async function publicKeyFor(privateKey: string): Promise<string | null> {
+	try {
+		const { derive } = await import("@dotenvx/primitives");
+		return derive(privateKey);
+	} catch {
+		return null;
+	}
+}
+
+/** The public key the repository was actually encrypted under. */
+export function committedPublicKey(root: string): string | null {
+	const path = join(root, SECRETS_FILE);
+	if (!existsSync(path)) return null;
+	const match = /^\s*DOTENV_PUBLIC_KEY_SECRETS\s*=\s*["']?([0-9a-fA-F]+)["']?/m.exec(readFileSync(path, "utf8"));
+	return match?.[1] ?? null;
+}
+
+export type KeyState =
+	| { ok: true; privateKey: string; publicKey: string; fresh: boolean }
+	| { ok: false; reason: string };
+
+/**
+ * The key for this repository, or a refusal that says exactly what is wrong.
+ *
+ * `fresh` means the repository has no secrets yet, so there is nothing to
+ * check the derivation against and any token is as good as another.
+ */
+export async function keyFor(manifest: Manifest, root: string): Promise<KeyState> {
+	const token = apiToken();
+	if (!token) {
+		return {
+			ok: false,
+			reason:
+				"CLOUDFLARE_API_TOKEN is not set.\n" +
+				"  The key is derived from it, so there is nothing to derive from. Note that\n" +
+				"  `wrangler login` does NOT set one — this scheme needs an API token, from\n" +
+				"  My Profile → API Tokens.",
+		};
+	}
+	const accountId = manifest.cloudflare?.accountId || process.env["CLOUDFLARE_ACCOUNT_ID"] || "";
+	if (!accountId) {
+		return {
+			ok: false,
+			reason:
+				"the account is not pinned, and it salts the derivation.\n" +
+				"  Run `vc deploy --cloudflare --provision` once, or set CLOUDFLARE_ACCOUNT_ID.",
+		};
+	}
+
+	const privateKey = derivePrivateKey(token, accountId);
+	const publicKey = await publicKeyFor(privateKey);
+	if (!publicKey) {
+		return { ok: false, reason: "@dotenvx/dotenvx is not installed here, so a key cannot be derived. `bun add -d @dotenvx/dotenvx`" };
+	}
+
+	const committed = committedPublicKey(root);
+	if (!committed) return { ok: true, privateKey, publicKey, fresh: true };
+
+	if (committed.toLowerCase() !== publicKey.toLowerCase()) {
+		return {
+			ok: false,
+			reason:
+				`this token does not derive the key ${SECRETS_FILE} was encrypted under.\n\n` +
+				`  encrypted under:  ${committed.slice(0, 16)}…\n` +
+				`  this token gives: ${publicKey.slice(0, 16)}…\n\n` +
+				"  That is one of three things, and all of them are the same fix:\n" +
+				"    · the token was rotated since the secrets were encrypted\n" +
+				"    · this is a different admin's token\n" +
+				"    · CLOUDFLARE_ACCOUNT_ID is not the account they were encrypted for\n\n" +
+				`  If you still have the ORIGINAL token, \`vc keys rotate\` re-encrypts\n` +
+				"  everything under the new one. If you do not, the values are unrecoverable\n" +
+				"  and must be entered again.",
+		};
+	}
+	return { ok: true, privateKey, publicKey, fresh: false };
+}
+
+/** `vc keys` — what the derivation says, without printing anything secret. */
+export async function keysCommand(manifest: Manifest, root: string, args: string[]): Promise<number> {
+	if (args.includes("--rotate")) return rotate(manifest, root);
+
+	const state = await keyFor(manifest, root);
+	console.log(`\nThe key is DERIVED from CLOUDFLARE_API_TOKEN, salted with the account id.`);
+	console.log(color.dim("Nothing is stored, so nothing can leak — and nothing can be recovered.\n"));
+
+	if (!state.ok) {
+		console.error(`${color.red("✗")} ${state.reason}\n`);
+		return 1;
+	}
+	console.log(`  derives public key  ${state.publicKey.slice(0, 20)}…`);
+	console.log(
+		state.fresh
+			? `  ${color.dim(`${SECRETS_FILE} does not exist yet, so there is nothing to check against`)}`
+			: `  ${color.green("✓")} matches what ${SECRETS_FILE} was encrypted under`,
+	);
+	console.log(
+		color.yellow(
+			`\n! Rotating this API token makes every secret in ${SECRETS_FILE} unreadable.\n` +
+				"  Run `vc keys --rotate` with the NEW token exported and the old one in\n" +
+				"  CLOUDFLARE_API_TOKEN_OLD, BEFORE the old one stops working.\n",
+		),
+	);
+	return 0;
+}
+
+/**
+ * Re-encrypt under a new token's key, while the old one still works.
+ *
+ * This is the escape hatch that makes a derived key survivable, and it only
+ * exists in the window where both tokens are known. Outside that window there
+ * is no recovery, which is why `vc keys` says so every time it runs.
+ */
+async function rotate(manifest: Manifest, root: string): Promise<number> {
+	const oldToken = process.env["CLOUDFLARE_API_TOKEN_OLD"];
+	const newToken = apiToken();
+	if (!oldToken || !newToken) {
+		console.error(
+			"\nvc: rotation needs BOTH tokens:\n" +
+				"  CLOUDFLARE_API_TOKEN_OLD=<the one the secrets were encrypted under>\n" +
+				"  CLOUDFLARE_API_TOKEN=<the new one>\n\n" +
+				"  The old one is the only thing that can read the current values.\n",
+		);
+		return 1;
+	}
+	const accountId = manifest.cloudflare?.accountId || process.env["CLOUDFLARE_ACCOUNT_ID"] || "";
+	if (!accountId) {
+		console.error("vc: the account is not pinned, and it salts the derivation.");
+		return 1;
+	}
+	const oldKey = derivePrivateKey(oldToken, accountId);
+	const oldPublic = await publicKeyFor(oldKey);
+	const committed = committedPublicKey(root);
+	if (committed && oldPublic && committed.toLowerCase() !== oldPublic.toLowerCase()) {
+		console.error(`\nvc: CLOUDFLARE_API_TOKEN_OLD does not derive the key ${SECRETS_FILE} was encrypted under either.\n`);
+		return 1;
+	}
+	console.log(
+		`\nRotation is a decrypt with the old key and an encrypt with the new one.\n` +
+			`Run these two, in this order, from ${root}:\n\n` +
+			`  ${color.cyan(`DOTENV_PRIVATE_KEY_SECRETS=<old> bunx dotenvx decrypt -f ${SECRETS_FILE}`)}\n` +
+			`  ${color.cyan(`bunx dotenvx encrypt -f ${SECRETS_FILE}`)}   ${color.dim("# under the new derived key")}\n\n` +
+			color.dim("vc does not run them for you: the middle state is your secrets in\nplaintext on disk, and that is a moment to be deliberate about.\n"),
+	);
+	return 0;
+}

package/src/deploy/secrets.ts

@@ -4,6 +4,7 @@ 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";
 
 /**
@@ -20,8 +21,9 @@ import type { Project } from "../project";
  * 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 the one thing that stays out — a single value, set once
- * where the deploy runs.
+ * 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 ───────────────────────────
  *
@@ -34,14 +36,19 @@ import type { Project } from "../project";
  * applies ADDITIVELY, so a secret this file does not name is left alone
  * rather than deleted.
  *
- * ── The tradeoff, stated ─────────────────────────────────────────────────
+ * ── The tradeoffs, stated ────────────────────────────────────────────────
  *
- * Ciphertext in git is permanent. If the private key ever leaks, every
- * secret in the history is readable, including ones that were rotated —
- * which is not true of `wrangler secret put`, where a rotation genuinely
- * retires the old value. Rotating the dotenvx key re-encrypts the present,
- * not the past. That is the price of a shop that rebuilds from a checkout,
- * and it should be a decision rather than a surprise.
+ * 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";
@@ -131,13 +138,15 @@ export async function decryptSecrets(project: Project): Promise<DecryptedSecrets
 
 	const dotenvx = findDotenvx(root);
 	if (!dotenvx) return { error: "dotenvx is not installed. `bun add -d @dotenvx/dotenvx`" };
-	if (!process.env[PRIVATE_KEY_VAR] && !existsSync(join(root, ".env.keys"))) {
-		return {
-			error: `${PRIVATE_KEY_VAR} is not set and there is no .env.keys here.\n  It is the one value that stays out of the repository; set it where the deploy runs.`,
-		};
-	}
 
-	const result = await run(dotenvx, ["decrypt", "-f", SECRETS_FILE, "--stdout"], root);
+	// 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
@@ -217,6 +226,13 @@ async function initSecrets(project: Project): Promise<number> {
 		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.",
@@ -225,20 +241,26 @@ async function initSecrets(project: Project): Promise<number> {
 		"# secret changed without showing what it changed to. `unset` is the",
 		"# documented placeholder and preflight refuses it.",
 		"#",
-		"# The private key stays out of the repository. It lives in .env.keys",
-		"# locally (gitignored) and as one build variable where the deploy runs.",
+		"# 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\`\n\n` +
+		`\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(`dotenvx encrypt -f ${SECRETS_FILE}`)}\n` +
-			`  3. commit ${SECRETS_FILE}; never commit .env.keys\n` +
-			`  4. set ${PRIVATE_KEY_VAR} where the deploy runs\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/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/index.ts

@@ -320,6 +320,10 @@ 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,
@@ -336,6 +340,23 @@ async function generateStrictRoot(root: string, manifest: Manifest, result: Gene
 		"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

@@ -66,6 +66,8 @@ export function strictDependencies(manifest: Manifest): {
 		// 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",