@saastemly/voidcommerce 0.4.0 → 0.6.0

package/src/deploy/keys.ts

@@ -1,70 +1,68 @@
-import { hkdfSync } from "node:crypto";
-import { existsSync, readFileSync } from "node:fs";
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import color from "picocolors";
-import type { Manifest } from "../manifest";
-import { SECRETS_FILE } from "./secrets";
+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 the repository's secrets, DERIVED rather than stored.
+ * The key that encrypts this repository's secrets.
  *
- * ── What this buys, and what it costs ────────────────────────────────────
+ * ── The realisation that shaped this ─────────────────────────────────────
  *
- * 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.
+ * 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.
  *
- * The cost is severe and worth stating plainly, because it is invisible until
- * the day it is not:
+ * That collapses the problem. The private key is needed in exactly one
+ * place — wherever the deploy runs — and nowhere else, ever.
  *
- *   **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.
+ * ── Why the key lives in GitHub ──────────────────────────────────────────
  *
- *   **A second admin derives a different key.** Two people with two tokens
- *   cannot read each other's values.
+ * 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.
  *
- *   **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 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.
  *
- * 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.
+ * ── Rotation, and why losing the key is survivable ───────────────────────
  *
- * @see https://developers.cloudflare.com/workers/wrangler/system-environment-variables/
+ * 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.
  */
 
-/**
- * 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 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;
 }
 
-/**
- * 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");
+/** 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;
+	}
 }
 
-/** 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");
@@ -74,139 +72,205 @@ export async function publicKeyFor(privateKey: string): Promise<string | 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 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 type KeyState =
-	| { ok: true; privateKey: string; publicKey: string; fresh: boolean }
-	| { ok: false; reason: string };
+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 };
+}
 
 /**
- * The key for this repository, or a refusal that says exactly what is wrong.
+ * Make a key and give it to GitHub.
  *
- * `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.
+ * 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 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) {
+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:
-				"the account is not pinned, and it salts the derivation.\n" +
-				"  Run `vc deploy --cloudflare --provision` once, or set CLOUDFLARE_ACCOUNT_ID.",
+				"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 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 pair = await generateKeypair();
+	if (!pair) return { ok: false, reason: "@dotenvx/dotenvx is not installed here. `bun add -d @dotenvx/dotenvx`" };
 
-	const committed = committedPublicKey(root);
-	if (!committed) return { ok: true, privateKey, publicKey, fresh: true };
+	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"}` };
 
-	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 };
+	return { ok: true, publicKey: pair.publicKey };
 }
 
-/** `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);
+/** `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`);
 
-	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"));
+	// "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.ok) {
-		console.error(`${color.red("✗")} ${state.reason}\n`);
+	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(`  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`,
+		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(
-		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",
-		),
+		`\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-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.
+ * Re-key. Needs the old private key locally, and says so honestly when there
+ * is none.
  */
-async function rotate(manifest: Manifest, root: string): Promise<number> {
-	const oldToken = process.env["CLOUDFLARE_API_TOKEN_OLD"];
-	const newToken = apiToken();
-	if (!oldToken || !newToken) {
+async function rotate(project: Project): Promise<number> {
+	const state = await keyState(project);
+	const old = state.localKey;
+
+	if (!old) {
 		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",
+			`\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;
 	}
-	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.");
+
+	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;
 	}
-	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`);
+
+	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(
-		`\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"),
+		`\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;
+}