@saastemly/voidcommerce 0.3.0 → 0.5.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 { committedPublicKey, provisionKey } from "./keys";
 import type { Project } from "../project";
 
 /**
@@ -19,9 +20,11 @@ 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.
+ * diff shows when a secret changed without showing what it changed to.
+ *
+ * Because dotenvx is asymmetric, SETTING a secret needs only the committed
+ * public key — no credential, no login, no key file. The private key lives
+ * in one place, GitHub Actions, and only the deploy uses it. See `./keys.ts`.
  *
  * ── Why the values still become worker SECRETS ───────────────────────────
  *
@@ -34,14 +37,18 @@ 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. 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 GitHub will not hand a secret back once set, so re-keying means
+ * entering the values again. That is the right trade: a key worth rotating
+ * is a key that may have leaked, and the values then need replacing anyway.
  *
- * 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.
+ * 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";
@@ -65,7 +72,7 @@ export function findDotenvx(from: string): string | null {
 		: null;
 }
 
-function run(cmd: string, args: string[], cwd: string, env: Record<string, string> = {}): Promise<{ code: number; out: string }> {
+export 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 = "";
@@ -80,6 +87,28 @@ function run(cmd: string, args: string[], cwd: string, env: Record<string, strin
 	});
 }
 
+/**
+ * Put a public key at the top of `.env.secrets`, creating the file if it is
+ * not there yet.
+ *
+ * Only the public half is ever written to disk, and it is meant to be
+ * committed: it is what lets anyone with a clone SET a secret without
+ * holding a credential.
+ */
+export function committedPublicKeyInto(root: string, publicKey: string): void {
+	const path = join(root, SECRETS_FILE);
+	const line = `DOTENV_PUBLIC_KEY_SECRETS="${publicKey}"`;
+	if (!existsSync(path)) {
+		writeFileSync(path, `${line}\n`, { mode: 0o600 });
+		return;
+	}
+	const body = readFileSync(path, "utf8");
+	writeFileSync(
+		path,
+		/^\s*DOTENV_PUBLIC_KEY_SECRETS\s*=.*$/m.test(body) ? body.replace(/^\s*DOTENV_PUBLIC_KEY_SECRETS\s*=.*$/m, line) : `${line}\n${body}`,
+	);
+}
+
 /**
  * The names a `.env.secrets` declares, read WITHOUT decrypting.
  *
@@ -129,15 +158,42 @@ export async function decryptSecrets(project: Project): Promise<DecryptedSecrets
 	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`" };
-	if (!process.env[PRIVATE_KEY_VAR] && !existsSync(join(root, ".env.keys"))) {
+	// The private key comes from the environment, which in the normal case is
+	// GitHub Actions injecting the repository secret. A laptop has no reason
+	// to hold it, so a missing one is explained rather than treated as a fault.
+	const privateKey = process.env[PRIVATE_KEY_VAR];
+	if (!privateKey) {
 		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.`,
+			error:
+				`${PRIVATE_KEY_VAR} is not set, so ${SECRETS_FILE} cannot be decrypted here.\n` +
+				`  That is the normal state on a laptop: the key lives in GitHub Actions and\n` +
+				`  only the deploy uses it. Push, and the workflow does this step.\n` +
+				`  To deploy by hand anyway, export the key for one command.`,
 		};
 	}
+	const expected = committedPublicKey(root);
+	if (expected) {
+		const { publicKeyFor } = await import("./keys");
+		const derived = await publicKeyFor(privateKey);
+		if (derived && derived.toLowerCase() !== expected.toLowerCase()) {
+			return {
+				error:
+					`${PRIVATE_KEY_VAR} does not open this repository.\n` +
+					`  it derives:       ${derived.slice(0, 16)}…\n` +
+					`  encrypted under:  ${expected.slice(0, 16)}…\n` +
+					`  It belongs to a different shop, or the repository has been re-keyed since.`,
+			};
+		}
+	}
+
+	// Last, deliberately: "that key belongs to another shop" is more use than
+	// "install dotenvx" when both are true.
+	const dotenvx = findDotenvx(root);
+	if (!dotenvx) return { error: "dotenvx is not installed. `bun add -d @dotenvx/dotenvx`" };
 
-	const result = await run(dotenvx, ["decrypt", "-f", SECRETS_FILE, "--stdout"], root);
+	const result = await run(dotenvx, ["decrypt", "-f", SECRETS_FILE, "--stdout"], root, {
+		[PRIVATE_KEY_VAR]: 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
@@ -173,6 +229,7 @@ export async function secretsCommand(project: Project, args: string[]): Promise<
 	const bare = plaintextSecretNames(root);
 
 	if (args.includes("--init")) return initSecrets(project);
+	if (args[0] === "set") return setSecretValue(project, args.slice(1));
 
 	if (!existsSync(join(root, SECRETS_FILE))) {
 		console.log(
@@ -211,10 +268,26 @@ export async function secretsCommand(project: Project, args: string[]): Promise<
 }
 
 /** Write a `.env.secrets` with every required key as the `unset` sentinel. */
-async function initSecrets(project: Project): Promise<number> {
+export 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.`);
+
+	// `vc link` leaves a file holding nothing but the public key, so "exists"
+	// is not the same as "is already set up". Refusing on existence alone
+	// stranded anyone who linked first, which is the order the docs recommend.
+	if (existsSync(path) && declaredSecretNames(project.root).size > 0) {
+		console.error(`vc: ${SECRETS_FILE} already declares secrets; not overwriting it.\n  \`vc secrets set KEY\` changes one.`);
+		return 1;
+	}
+
+	// The PUBLIC key goes in the file so encryption uses this shop's pair
+	// rather than inventing one and writing a .env.keys nobody asked for. Its
+	// private half goes straight to GitHub and is never seen again — so an
+	// existing key is REUSED, never replaced: replacing it would orphan
+	// whatever it has already encrypted.
+	const existing = committedPublicKey(project.root);
+	const made = existing ? ({ ok: true, publicKey: existing } as const) : await provisionKey(project);
+	if (!made.ok) {
+		console.error(`\nvc: ${made.reason}\n`);
 		return 1;
 	}
 	const required = allEnvKeys(project.manifest).filter((key) => !key.plaintext);
@@ -225,20 +298,151 @@ 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.",
+		"# Setting a value needs NO credential: dotenvx encrypts with the public key",
+		"# below, which is right here in the repository. Only the deploy decrypts,",
+		"# and the private key for that lives in GitHub Actions.",
+		"#",
+		"# `vc secrets set KEY` is the way to change one — it reads the value from",
+		"# the terminal, so it never reaches a command line where `ps` would show it.",
+		"",
+		`DOTENV_PUBLIC_KEY_SECRETS="${made.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\`\n` +
+			`${existing ? color.dim(`= ${PRIVATE_KEY_VAR} was already on GitHub; reused it`) : `${color.green("+")} ${PRIVATE_KEY_VAR} stored on GitHub; the public key is in the file`}\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`,
+			`${required.map((key) => `  ${color.cyan(`vc secrets set ${key.key}`)}`).join("\n")}\n\n` +
+			`then commit ${SECRETS_FILE}. There is no key file to keep out of git.\n`,
 	);
 	return 0;
 }
+
+
+/**
+ * `vc secrets set KEY` — change one value, with no credential of any kind.
+ *
+ * This is the command the whole design exists to make possible. dotenvx
+ * encrypts with the public key sitting in the committed file, so a
+ * contributor with a clone and nothing else can rotate the Stripe key. They
+ * cannot read the one that is there, which is exactly right.
+ *
+ * The value is read from the terminal or from stdin, never from argv: an
+ * argument is visible in `ps` to every process on the machine while the
+ * command runs, and shells keep it in history besides.
+ */
+export async function setSecretValue(project: Project, args: string[]): Promise<number> {
+	const root = project.root;
+	const name = args.find((arg) => !arg.startsWith("-"));
+	if (!name) {
+		console.error(`\nvc: which secret? \`vc secrets set STRIPE_SECRET_KEY\`\n`);
+		return 1;
+	}
+	if (!/^[A-Z][A-Z0-9_]*$/.test(name)) {
+		console.error(`\nvc: "${name}" is not a key name — they are SHOUTING_SNAKE_CASE.\n`);
+		return 1;
+	}
+	if (!existsSync(join(root, SECRETS_FILE))) {
+		console.error(`\nvc: no ${SECRETS_FILE} yet. \`vc secrets --init\` writes one.\n`);
+		return 1;
+	}
+	const publicKey = committedPublicKey(root);
+	if (!publicKey) {
+		console.error(`\nvc: ${SECRETS_FILE} has no DOTENV_PUBLIC_KEY_SECRETS, so there is nothing to encrypt to.\n  \`vc keys --init\` makes a key and puts the public half here.\n`);
+		return 1;
+	}
+
+	// A known key gets its consequence shown, so a person setting one knows
+	// what it is for without leaving the terminal.
+	const known = allEnvKeys(project.manifest).find((key) => key.key === name);
+	const value = await readValue(name, known?.breaks, known?.where);
+	if (value === null) return 1;
+
+	const written = await encryptInto(root, publicKey, name, value);
+	if (!written.ok) {
+		console.error(`\nvc: ${written.error}\n`);
+		return 1;
+	}
+	const stillBare = plaintextSecretNames(root).includes(name);
+	if (stillBare) {
+		console.error(`\n${color.red("✗")} ${name} was written in the CLEAR — the public key did not encrypt it.\n  Do not commit. Check DOTENV_PUBLIC_KEY_SECRETS in ${SECRETS_FILE}.\n`);
+		return 1;
+	}
+	console.log(`\n${color.green("✓")} ${name} encrypted into ${SECRETS_FILE}. Commit it.\n`);
+	return 0;
+}
+
+/** The value, from a masked prompt or from a pipe. Never from argv. */
+async function readValue(name: string, breaks?: string, where?: string): Promise<string | null> {
+	if (!process.stdin.isTTY) {
+		const chunks: Buffer[] = [];
+		for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+		const piped = Buffer.concat(chunks).toString("utf8").replace(/\r?\n$/, "");
+		if (!piped) {
+			console.error(`\nvc: nothing on stdin to set ${name} to.\n`);
+			return null;
+		}
+		return piped;
+	}
+	const p = await import("@clack/prompts");
+	if (breaks) console.log(`\n${color.dim(breaks)}${where ? color.dim(` — from: ${where}`) : ""}`);
+	const answer = await p.password({
+		message: name,
+		validate: (input) => (input && input.length > 0 ? undefined : "a secret with no value is not a secret"),
+	});
+	if (p.isCancel(answer)) {
+		console.log(color.dim("\ncancelled; nothing changed.\n"));
+		return null;
+	}
+	return String(answer);
+}
+
+
+/**
+ * Encrypt one value into `.env.secrets`, in process.
+ *
+ * Deliberately NOT `dotenvx set NAME value -f …`: that takes the value as an
+ * argument, and an argument is visible in `ps` to every other process on the
+ * machine for as long as the call runs. This uses the same secp256k1 the CLI
+ * uses — it is the CLI's own library — so what it writes is byte-compatible
+ * with what `dotenvx decrypt` expects.
+ */
+export async function encryptInto(root: string, publicKey: string, name: string, value: string): Promise<{ ok: true } | { ok: false; error: string }> {
+	const { encrypt } = await import("@dotenvx/primitives");
+	let ciphertext: string;
+	try {
+		ciphertext = encrypt(publicKey, value);
+	} catch (error) {
+		return { ok: false, error: `could not encrypt to the key in ${SECRETS_FILE}: ${String(error)}` };
+	}
+	// A belt-and-braces check on someone else's library, because the failure
+	// it guards against is writing a secret to a committed file in the clear.
+	//
+	// The containment half is gated on length on purpose: base64 output will
+	// contain almost any short string by chance, so checking it for a
+	// two-character value rejects perfectly good ciphertext. Twelve is above
+	// the length at which a coincidental match stops being plausible.
+	const looksWrong = !ciphertext.startsWith("encrypted:") || ciphertext === value || (value.length >= 12 && ciphertext.includes(value));
+	if (looksWrong) {
+		return { ok: false, error: `refusing to write ${name} — the result does not look encrypted.` };
+	}
+	upsertLine(join(root, SECRETS_FILE), name, ciphertext);
+	return { ok: true };
+}
+
+/**
+ * Replace `NAME=…` in a dotenv file, or add it if it is not there.
+ *
+ * Written by hand rather than with a parser because everything else in the
+ * file — the comments explaining what each secret breaks, the order — is
+ * meant for a person to read, and a round-trip through a parser would
+ * flatten all of it.
+ */
+function upsertLine(path: string, name: string, value: string): void {
+	const body = readFileSync(path, "utf8");
+	const pattern = new RegExp(`^\\s*${name}\\s*=.*$`, "m");
+	writeFileSync(path, pattern.test(body) ? body.replace(pattern, `${name}=${value}`) : `${body.replace(/\n*$/, "\n")}${name}=${value}\n`);
+}

package/src/dotenvx-primitives.d.ts

@@ -0,0 +1,14 @@
+/**
+ * `@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 };
+	/** Ciphertext for a value, given only the PUBLIC key. Note the argument order. */
+	export function encrypt(publicKey: string, value: string): string;
+	/** The value back, given the private key. Throws when the key is the wrong one. */
+	export function decrypt(privateKey: string, ciphertext: string): string;
+}