@saastemly/voidcommerce 0.3.0 → 0.5.0

package/src/deploy/keys.ts

@@ -0,0 +1,276 @@
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import color from "picocolors";
+import type { Project } from "../project";
+import { ghAuth, repoSlug, secretNames, setSecret } from "./github";
+import { PRIVATE_KEY_VAR, SECRETS_FILE, committedPublicKeyInto, findDotenvx, run } from "./secrets";
+
+/**
+ * The key that encrypts this repository's secrets.
+ *
+ * ── The realisation that shaped this ─────────────────────────────────────
+ *
+ * dotenvx is ASYMMETRIC. Encryption takes the public key; only decryption
+ * takes the private one. The public key is committed at the top of
+ * `.env.secrets`, so ADDING OR CHANGING A SECRET NEEDS NO CREDENTIAL AT
+ * ALL — not a Cloudflare token, not a wrangler login, not even this file.
+ * Anyone who can clone the repository can set a secret in it; nobody who
+ * can clone it can read one.
+ *
+ * That collapses the problem. The private key is needed in exactly one
+ * place — wherever the deploy runs — and nowhere else, ever.
+ *
+ * ── Why the key lives in GitHub ──────────────────────────────────────────
+ *
+ * The first design derived it from a Cloudflare API token, which put the
+ * bootstrap in the wrong order: the token authorises a worker that does not
+ * exist yet, and obtaining one means `wrangler login`. It also made every
+ * secret unreadable the day the token rotated, and gave two admins two
+ * different keys.
+ *
+ * So the key is generated at random and handed to GitHub, which is where
+ * the deploy runs and the one place a person who can push is already
+ * authenticated. It is never written to disk. `gh secret set` takes it on
+ * stdin, GitHub encrypts it, and no API can read it back — which is the
+ * property that makes it a good home and, unavoidably, the property that
+ * makes rotation a re-key rather than a re-encrypt.
+ *
+ * ── Rotation, and why losing the key is survivable ───────────────────────
+ *
+ * Nothing can read a GitHub secret back, so re-encrypting the existing
+ * ciphertext needs a local copy of the old key. Usually there is none, and
+ * that is fine: the only reason to rotate an encryption key is that it may
+ * have leaked, and a key that may have leaked means the VALUES may have
+ * leaked. Those must be replaced at Stripe and everywhere else regardless.
+ * Re-entering them is not extra work — it is the work.
+ */
+
+/** The public key the repository was encrypted under, from the committed file. */
+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;
+}
+
+/** A fresh secp256k1 pair. The private half must reach GitHub and then be forgotten. */
+export async function generateKeypair(): Promise<{ publicKey: string; privateKey: string } | null> {
+	try {
+		const { keypair } = await import("@dotenvx/primitives");
+		return keypair();
+	} catch {
+		return null;
+	}
+}
+
+export async function publicKeyFor(privateKey: string): Promise<string | null> {
+	try {
+		const { derive } = await import("@dotenvx/primitives");
+		return derive(privateKey);
+	} catch {
+		return null;
+	}
+}
+
+export interface KeyState {
+	/** The public key in `.env.secrets`, if the file exists. */
+	publicKey: string | null;
+	/** Does GitHub hold a private key for this repository? Names only — values never come back. */
+	inGitHub: boolean;
+	/** `owner/repo`, or null when there is no GitHub remote yet. */
+	slug: string | null;
+	/** A local override, for deploying by hand without CI. */
+	localKey: string | null;
+	/** Set when the local override does not match the committed public key. */
+	mismatch?: string | undefined;
+}
+
+export async function keyState(project: Project): Promise<KeyState> {
+	const publicKey = committedPublicKey(project.root);
+	const slug = await repoSlug(project.root);
+	const names = slug ? await secretNames(project.root) : new Set<string>();
+	const localKey = process.env[PRIVATE_KEY_VAR] ?? null;
+
+	let mismatch: string | undefined;
+	if (localKey && publicKey) {
+		const derived = await publicKeyFor(localKey);
+		if (derived && derived.toLowerCase() !== publicKey.toLowerCase()) {
+			mismatch = `${PRIVATE_KEY_VAR} in your environment derives ${derived.slice(0, 16)}…, but ${SECRETS_FILE} was encrypted under ${publicKey.slice(0, 16)}…`;
+		}
+	}
+	return { publicKey, inGitHub: names.has(PRIVATE_KEY_VAR), slug, localKey, mismatch };
+}
+
+/**
+ * Make a key and give it to GitHub.
+ *
+ * Returns the PUBLIC key for the caller to write into `.env.secrets`. The
+ * private key is deliberately not returned and not logged: it exists as a
+ * local variable for the length of one `gh` call and then goes out of scope.
+ */
+export async function provisionKey(project: Project): Promise<{ ok: true; publicKey: string } | { ok: false; reason: string }> {
+	const auth = await ghAuth(project.root);
+	if (!auth.ok) return { ok: false, reason: auth.reason ?? "gh is unavailable" };
+
+	const slug = await repoSlug(project.root);
+	if (!slug) {
+		return {
+			ok: false,
+			reason:
+				"this checkout has no GitHub repository yet, and the key is stored on the repository.\n" +
+				"  Create one first:\n\n" +
+				"    gh repo create --source=. --private --push\n",
+		};
+	}
+
+	const pair = await generateKeypair();
+	if (!pair) return { ok: false, reason: "@dotenvx/dotenvx is not installed here. `bun add -d @dotenvx/dotenvx`" };
+
+	const sent = await setSecret(project.root, PRIVATE_KEY_VAR, pair.privateKey);
+	if (!sent.ok) return { ok: false, reason: `GitHub refused the secret: ${sent.error ?? "unknown error"}` };
+
+	return { ok: true, publicKey: pair.publicKey };
+}
+
+/** `vc keys` — where the key is, and what is missing. */
+export async function keysCommand(project: Project, args: string[]): Promise<number> {
+	if (args.includes("--rotate")) return rotate(project);
+	if (args.includes("--init")) return initKey(project);
+
+	const state = await keyState(project);
+	console.log(`\nSecrets are encrypted with a public key that is COMMITTED, and read with a`);
+	console.log(`private key that lives only in GitHub Actions.\n`);
+
+	// "no file" and "a file with no key in it" are different problems with
+	// different fixes, and saying the wrong one sends a person to the wrong
+	// command.
+	const hasFile = existsSync(join(project.root, SECRETS_FILE));
+	const publicNote = state.publicKey
+		? `${state.publicKey.slice(0, 20)}… in ${SECRETS_FILE}`
+		: color.dim(hasFile ? `${SECRETS_FILE} has no key yet — \`vc link\` makes one` : `no ${SECRETS_FILE} yet — \`vc secrets --init\``);
+	console.log(`  ${state.publicKey ? color.green("✓") : color.dim("·")} public key   ${publicNote}`);
+	console.log(
+		`  ${state.inGitHub ? color.green("✓") : color.red("✗")} private key  ${
+			state.inGitHub ? `${PRIVATE_KEY_VAR} is set on ${state.slug}` : state.slug ? color.red(`not set on ${state.slug} — \`vc keys --init\``) : color.dim("no GitHub repository yet")
+		}`,
+	);
+
+	if (state.mismatch) {
+		console.error(`\n${color.red("✗")} ${state.mismatch}\n  Unset it, or point it at the right repository.\n`);
+		return 1;
+	}
+
+	console.log(
+		color.dim(
+			`\nAdding or changing a secret needs NO credential — encryption uses the public\n` +
+				`key in the repository. Only the deploy decrypts, and only GitHub Actions can.\n`,
+		),
+	);
+
+	if (!state.inGitHub && state.slug) return 1;
+	return 0;
+}
+
+/** Generate a key, store it on the repository, and put the public half in the file. */
+async function initKey(project: Project): Promise<number> {
+	const state = await keyState(project);
+	if (state.inGitHub && state.publicKey) {
+		console.error(
+			`\nvc: ${project.root} already has a key: ${PRIVATE_KEY_VAR} on ${state.slug}, public ${state.publicKey.slice(0, 16)}….\n` +
+				`  Replacing it makes every value in ${SECRETS_FILE} unreadable. \`vc keys --rotate\` is the deliberate way.\n`,
+		);
+		return 1;
+	}
+
+	const made = await provisionKey(project);
+	if (!made.ok) {
+		console.error(`\nvc: ${made.reason}\n`);
+		return 1;
+	}
+
+	// ALWAYS written, creating the file if need be. A private key on GitHub
+	// with no public half in the repository is a key nobody can encrypt to,
+	// and the next command would quietly generate a second one — orphaning
+	// this one and anything already sealed with it.
+	const fresh = !existsSync(join(project.root, SECRETS_FILE));
+	committedPublicKeyInto(project.root, made.publicKey);
+	console.log(
+		`\n${color.green("✓")} ${PRIVATE_KEY_VAR} set on ${state.slug}; public key in ${SECRETS_FILE}\n` +
+			(fresh ? `\n  Next: ${color.cyan("vc secrets --init")} fills in the keys this shop needs.\n` : "\n"),
+	);
+	return 0;
+}
+
+/**
+ * Re-key. Needs the old private key locally, and says so honestly when there
+ * is none.
+ */
+async function rotate(project: Project): Promise<number> {
+	const state = await keyState(project);
+	const old = state.localKey;
+
+	if (!old) {
+		console.error(
+			`\nvc: rotating needs the CURRENT private key, and GitHub cannot give it back —\n` +
+				`  a secret is write-only once set, which is why it is a good place to keep one.\n\n` +
+				`  If you have a copy:\n` +
+				`    ${color.cyan(`${PRIVATE_KEY_VAR}=<the old key> vc keys --rotate`)}\n\n` +
+				`  If you do not, re-key and enter the values again:\n` +
+				`    ${color.cyan(`rm ${SECRETS_FILE} && vc keys --init && vc secrets --init`)}\n\n` +
+				color.dim(
+					`  That is less painful than it sounds. The reason to rotate an encryption key\n` +
+						`  is that it may have leaked — and a key that may have leaked means the VALUES\n` +
+						`  may have leaked. Those have to be replaced at Stripe and everywhere else\n` +
+						`  regardless, so re-entering them is not extra work. It is the work.\n`,
+				),
+		);
+		return 1;
+	}
+
+	if (state.mismatch) {
+		console.error(`\nvc: ${state.mismatch}\n  That key cannot read this repository, so it cannot rotate it either.\n`);
+		return 1;
+	}
+
+	const dotenvx = findDotenvx(project.root);
+	if (!dotenvx) {
+		console.error("vc: dotenvx is not installed here. `bun add -d @dotenvx/dotenvx`");
+		return 1;
+	}
+
+	// Decrypt in place with the old key, then hand the file a new public key
+	// and re-encrypt. The window where plaintext is on disk is this function.
+	const decrypted = await run(dotenvx, ["decrypt", "-f", SECRETS_FILE], project.root, { [PRIVATE_KEY_VAR]: old });
+	if (decrypted.code !== 0) {
+		console.error(`\nvc: could not decrypt ${SECRETS_FILE}: ${decrypted.out.trim().split("\n").slice(-2).join(" ")}\n`);
+		return 1;
+	}
+
+	const made = await provisionKey(project);
+	if (!made.ok) {
+		console.error(
+			`\nvc: ${made.reason}\n\n` +
+				color.red(`  ${SECRETS_FILE} IS NOW PLAINTEXT ON DISK and must not be committed.\n`) +
+				`  Re-encrypt under the old key to undo:  ${color.cyan(`bunx dotenvx encrypt -f ${SECRETS_FILE}`)}\n`,
+		);
+		return 1;
+	}
+
+	committedPublicKeyInto(project.root, made.publicKey);
+
+	const encrypted = await run(dotenvx, ["encrypt", "-f", SECRETS_FILE], project.root);
+	if (encrypted.code !== 0) {
+		console.error(
+			`\nvc: re-encryption failed: ${encrypted.out.trim().split("\n").slice(-2).join(" ")}\n` +
+				color.red(`  ${SECRETS_FILE} IS PLAINTEXT ON DISK. Do not commit it.\n`),
+		);
+		return 1;
+	}
+
+	console.log(
+		`\n${color.green("✓")} re-keyed under ${made.publicKey.slice(0, 20)}… and ${PRIVATE_KEY_VAR} replaced on ${state.slug}\n\n` +
+			`  Commit ${SECRETS_FILE}. The old key reads nothing in it any more.\n` +
+			color.yellow(`  The old ciphertext is still in git history, and the old key still opens THAT.\n`),
+	);
+	return 0;
+}

package/src/deploy/link.ts

@@ -0,0 +1,185 @@
+import color from "picocolors";
+import { writeManifest } from "../manifest";
+import type { Project } from "../project";
+import { cloudflareAccounts, ghAuth, repoSlug, secretNames, setSecret, setVariable, variableNames, verifyCloudflareToken } from "./github";
+import { keyState, provisionKey } from "./keys";
+import { PRIVATE_KEY_VAR, SECRETS_FILE, committedPublicKeyInto, declaredSecretNames, initSecrets } from "./secrets";
+
+/**
+ * `vc link` — the one manual step, done once, from the terminal.
+ *
+ * ── What this is for ─────────────────────────────────────────────────────
+ *
+ * The goal is that publishing to GitHub is the whole deploy. Everything
+ * else in voidcommerce gets there: the app is generated from the manifest,
+ * the secrets are committed as ciphertext, the workflow builds and deploys.
+ * One thing cannot be automated away, and it is worth being exact about
+ * why.
+ *
+ * **GitHub cannot mint a Cloudflare credential.** There is no OIDC or
+ * workload identity federation between them — the feature request has sat
+ * unanswered since 2025, and Cloudflare's own CI guidance still says to
+ * store an API token in your CI provider's secrets. The Cloudflare GitHub
+ * App does not help: it grants Cloudflare access to the repository, not the
+ * repository access to Cloudflare. Something has to authorise creating a
+ * database in someone's account, and only Cloudflare can issue that.
+ *
+ * So exactly one token is typed, once. This command takes it, checks it
+ * against the Cloudflare API before trusting it, and puts it in GitHub's
+ * encrypted secrets — never on disk, never in a shell profile, never in
+ * `~/.wrangler`. After that, `git push` is the deploy, forever.
+ *
+ * ── What it deliberately does not do ─────────────────────────────────────
+ *
+ * It does not create the token. That would need a token. The dashboard is
+ * the only place a first one can come from, so this prints exactly which
+ * permissions to tick and waits.
+ */
+
+const TOKEN_SECRET = "CLOUDFLARE_API_TOKEN";
+const ACCOUNT_VAR = "CLOUDFLARE_ACCOUNT_ID";
+
+/** The scopes the deploy actually uses, and why each one is there. */
+const SCOPES: Array<[string, string]> = [
+	["Account · Workers Scripts: Edit", "deploy the worker"],
+	["Account · D1: Edit", "create the database and apply migrations"],
+	["Account · Queues: Edit", "create the order queue"],
+	["Account · Workers KV Storage: Edit", "sessions and caches"],
+	["Account · Workers R2 Storage: Edit", "product images"],
+	["Account · Account Settings: Read", "confirm which account this is"],
+	["Zone · Workers Routes: Edit", "answer on your domain"],
+	["User · User Details: Read", "wrangler asks at startup"],
+];
+
+export async function linkCommand(project: Project, args: string[]): Promise<number> {
+	const p = await import("@clack/prompts");
+	const root = project.root;
+	const relink = args.includes("--force");
+
+	p.intro(color.bgCyan(color.black(" vc link ")));
+
+	// 1. gh, logged in, scoped.
+	const auth = await ghAuth(root);
+	if (!auth.ok) {
+		p.cancel(auth.reason ?? "gh is unavailable");
+		return 1;
+	}
+	const slug = await repoSlug(root);
+	if (!slug) {
+		p.cancel(
+			"this checkout has no GitHub repository, and everything below is stored on one.\n\n" +
+				`    ${color.cyan("gh repo create --source=. --private --push")}\n\n` +
+				"  then run `vc link` again.",
+		);
+		return 1;
+	}
+	p.log.success(`${color.green("✓")} ${slug}, as ${auth.user ?? "you"}`);
+
+	// 2. The encryption key. Generated here, stored on the repository, never on disk.
+	const keys = await keyState(project);
+	if (keys.inGitHub && !relink) {
+		p.log.info(`${PRIVATE_KEY_VAR} is already set — leaving it alone (--force replaces it, which orphans ${SECRETS_FILE})`);
+	} else if (keys.inGitHub && relink) {
+		p.log.warn(`--force: replacing ${PRIVATE_KEY_VAR} makes every value in ${SECRETS_FILE} unreadable. Use \`vc keys --rotate\` to re-encrypt instead.`);
+		return 1;
+	} else {
+		const made = await provisionKey(project);
+		if (!made.ok) {
+			p.cancel(made.reason);
+			return 1;
+		}
+		committedPublicKeyInto(root, made.publicKey);
+		p.log.success(`${color.green("✓")} ${PRIVATE_KEY_VAR} generated and stored on GitHub; public half in ${SECRETS_FILE}`);
+	}
+
+	// 3. The Cloudflare token — the one thing that cannot be derived.
+	const existing = await secretNames(root);
+	if (existing.has(TOKEN_SECRET) && !relink) {
+		p.log.info(`${TOKEN_SECRET} is already set — pass --force to replace it`);
+	} else {
+		p.log.step(`A Cloudflare API token, from ${color.cyan("https://dash.cloudflare.com/profile/api-tokens")} → Create Token → Custom token`);
+		console.log(SCOPES.map(([scope, why]) => `      ${scope.padEnd(38)} ${color.dim(why)}`).join("\n"));
+		console.log(
+			color.dim(
+				`\n      The token Cloudflare generates for its own Workers Builds will NOT do:\n` +
+					`      it has no D1 and no Queues permission, so it cannot create the database.\n`,
+			),
+		);
+
+		const token = await p.password({
+			message: "Paste it (nothing is written to disk)",
+			validate: (input) => (input && input.length >= 20 ? undefined : "that is too short to be a Cloudflare token"),
+		});
+		if (p.isCancel(token)) {
+			p.cancel("nothing was stored.");
+			return 1;
+		}
+
+		const spinner = p.spinner();
+		spinner.start("asking Cloudflare whether that token is real");
+		const verified = await verifyCloudflareToken(String(token));
+		if (!verified.ok) {
+			spinner.stop(`${color.red("✗")} Cloudflare rejected it: ${verified.detail}`);
+			p.cancel("nothing was stored.");
+			return 1;
+		}
+		const accounts = await cloudflareAccounts(String(token));
+		spinner.stop(`${color.green("✓")} the token is active and sees ${accounts.length} account${accounts.length === 1 ? "" : "s"}`);
+
+		let accountId = project.manifest.cloudflare?.accountId ?? "";
+		if (accounts.length === 1) {
+			accountId = accounts[0]!.id;
+			p.log.info(`account "${accounts[0]!.name}"`);
+		} else if (accounts.length > 1) {
+			const picked = await p.select({
+				message: "Which account is this shop in?",
+				options: accounts.map((account) => ({ value: account.id, label: account.name, hint: account.id })),
+			});
+			if (p.isCancel(picked)) {
+				p.cancel("nothing was stored.");
+				return 1;
+			}
+			accountId = String(picked);
+		}
+
+		const stored = await setSecret(root, TOKEN_SECRET, String(token));
+		if (!stored.ok) {
+			p.cancel(`GitHub refused the secret: ${stored.error ?? "unknown error"}`);
+			return 1;
+		}
+		p.log.success(`${color.green("✓")} ${TOKEN_SECRET} stored on ${slug}`);
+
+		if (accountId) {
+			// A VARIABLE, not a secret: an account id is an identifier, and a
+			// readable one is easier to debug in a workflow log.
+			const varred = await setVariable(root, ACCOUNT_VAR, accountId);
+			if (varred.ok) p.log.success(`${color.green("✓")} ${ACCOUNT_VAR} set as a repository variable`);
+			project.manifest.cloudflare = { ...project.manifest.cloudflare, accountId };
+			await writeManifest(root, project.manifest);
+		}
+	}
+
+	// 4. The shop's own secrets, so `vc link` leaves a repository that is
+	// ready rather than one that is half-configured.
+	if (declaredSecretNames(root).size === 0) {
+		p.log.step(`writing ${SECRETS_FILE}`);
+		await initSecrets(project);
+	}
+
+	// 5. What is left.
+	const secrets = await secretNames(root);
+	const vars = await variableNames(root);
+	p.outro(
+		[
+			`${color.bold("Ready.")} From here, ${color.cyan("git push")} is the deploy.`,
+			"",
+			`  ${secrets.has(PRIVATE_KEY_VAR) ? color.green("✓") : color.red("✗")} ${PRIVATE_KEY_VAR}   ${color.dim("reads the shop's secrets")}`,
+			`  ${secrets.has(TOKEN_SECRET) ? color.green("✓") : color.red("✗")} ${TOKEN_SECRET}      ${color.dim("deploys to Cloudflare")}`,
+			`  ${vars.has(ACCOUNT_VAR) ? color.green("✓") : color.dim("·")} ${ACCOUNT_VAR}     ${color.dim("which account")}`,
+			"",
+			`  Set the shop's own secrets with ${color.cyan("vc secrets set KEY")} — that needs no`,
+			`  credential at all, because encryption uses the public key in the repository.`,
+		].join("\n"),
+	);
+	return 0;
+}