@saastemly/voidcommerce 0.4.0 → 0.5.0

package/dist/index.js

@@ -9,10 +9,8 @@ import {
   MIGRATIONS_README,
   STRICT_APP,
   VOID_VERSION,
-  allEnvKeys,
   deployCloudflare,
   distCommand,
-  envSummary,
   findProject,
   findWrangler,
   finishStrict,
@@ -34,10 +32,6 @@ import {
   renderDeployReadme,
   renderDistWorkflow,
   renderDomainTs,
-  renderEnvExample,
-  renderEnvLocal,
-  renderEnvProduction,
-  renderEnvTs,
   renderFrontendApiTs,
   renderFrontendEnvProduction,
   renderFrontendWorkflow,
@@ -57,7 +51,15 @@ import {
   routeProblem,
   strictDependencies,
   upsertJsonc
-} from "./index-yzezvy5h.js";
+} from "./index-5m3t0zfc.js";
+import {
+  allEnvKeys,
+  envSummary,
+  renderEnvExample,
+  renderEnvLocal,
+  renderEnvProduction,
+  renderEnvTs
+} from "./index-b9b4dawy.js";
 import {
   LAYOUTS,
   MANIFEST_FILE,

package/dist/keys-b91c72zp.js

@@ -0,0 +1,19 @@
+import {
+  committedPublicKey,
+  generateKeypair,
+  keyState,
+  keysCommand,
+  provisionKey,
+  publicKeyFor
+} from "./index-b9b4dawy.js";
+import"./index-pz6m2hkm.js";
+import"./index-844b3qn9.js";
+import"./index-0v6na3yp.js";
+export {
+  publicKeyFor,
+  provisionKey,
+  keysCommand,
+  keyState,
+  generateKeypair,
+  committedPublicKey
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@saastemly/voidcommerce",
-  "version": "0.4.0",
+  "version": "0.5.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",

package/src/cli.ts

@@ -1,4 +1,16 @@
-import { deployCommand, deployHelp, guardCommand, keysCliCommand, keysHelp, preflightCommand, preflightHelp, secretsCliCommand, secretsHelp } from "./deploy/index";
+import {
+	deployCommand,
+	deployHelp,
+	guardCommand,
+	keysCliCommand,
+	keysHelp,
+	linkCliCommand,
+	linkHelp,
+	preflightCommand,
+	preflightHelp,
+	secretsCliCommand,
+	secretsHelp,
+} from "./deploy/index";
 import { distCommand, distHelp } from "./dist";
 import { importCommand, importHelp } from "./import";
 import { fullHelp, initHelp, version } from "./help";
@@ -40,6 +52,7 @@ export const EXTENDED: Record<string, Extended> = {
 	preflight: { run: preflightCommand, help: preflightHelp },
 	secrets: { run: secretsCliCommand, help: secretsHelp },
 	keys: { run: keysCliCommand, help: keysHelp },
+	link: { run: linkCliCommand, help: linkHelp },
 	// 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") },

package/src/deploy/github.ts

@@ -0,0 +1,198 @@
+import { spawn } from "node:child_process";
+import { delimiter, join } from "node:path";
+import { existsSync } from "node:fs";
+
+/**
+ * GitHub as the root of trust.
+ *
+ * ── Why GitHub and not Cloudflare ────────────────────────────────────────
+ *
+ * The shop's credentials have to be reachable by whatever deploys it, and
+ * whatever deploys it has to be reachable by a push. The first design
+ * derived the encryption key from a Cloudflare API token, which put the
+ * bootstrap in the wrong order: the token authorises a worker that does not
+ * exist yet, and getting one means `wrangler login` — the exact step this is
+ * supposed to remove.
+ *
+ * GitHub is already there. A person who can push is logged into `gh`, and
+ * `gh` can write repository secrets. So GitHub holds the credentials, GitHub
+ * Actions is the thing that deploys, and the local machine holds nothing.
+ *
+ * ── What this cannot do, stated plainly ──────────────────────────────────
+ *
+ * It cannot mint a Cloudflare credential. There is no OIDC or workload
+ * identity federation from GitHub Actions to the Cloudflare API — the
+ * request has been open since 2025 with no Cloudflare commitment, and the
+ * official CI guidance is still "store an API token in your CI provider's
+ * secrets". The Cloudflare GitHub App runs one way: it grants Cloudflare
+ * access to the repository, not the repository access to Cloudflare.
+ *
+ * So exactly one long-lived Cloudflare token must exist, and this module's
+ * job is to make sure it exists in ONE place — GitHub's encrypted secrets —
+ * rather than on a laptop, in a shell profile, or in `~/.wrangler`.
+ *
+ * @see https://developers.cloudflare.com/workers/ci-cd/external-cicd/github-actions/
+ * @see https://github.com/cloudflare/workers-sdk/discussions/11434
+ */
+
+export interface GhAuth {
+	/** Logged in, with a token that can write repository secrets. */
+	ok: boolean;
+	user?: string | undefined;
+	scopes?: string[] | undefined;
+	reason?: string | undefined;
+}
+
+/** The scope `gh secret set` needs on a repository. */
+const REPO_SCOPE = "repo";
+
+export function findGh(): string | null {
+	for (const entry of (process.env["PATH"] ?? "").split(delimiter).filter(Boolean)) {
+		if (existsSync(join(entry, "gh"))) return join(entry, "gh");
+	}
+	return null;
+}
+
+export function run(
+	cmd: string,
+	args: string[],
+	cwd: string,
+	stdin?: string,
+): Promise<{ code: number; out: string }> {
+	return new Promise((resolve) => {
+		const child = spawn(cmd, args, { cwd, stdio: ["pipe", "pipe", "pipe"] });
+		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 }));
+		// Always closed: a `gh` subcommand that reads stdin and never sees EOF
+		// hangs forever, and one that does not read it does not mind.
+		child.stdin?.end(stdin ?? "");
+	});
+}
+
+/** Is `gh` here, logged in, and scoped to write secrets? */
+export async function ghAuth(cwd: string): Promise<GhAuth> {
+	const gh = findGh();
+	if (!gh) {
+		return { ok: false, reason: "the GitHub CLI is not installed. https://cli.github.com — then `gh auth login`." };
+	}
+	const status = await run(gh, ["auth", "status"], cwd);
+	if (status.code !== 0) {
+		return { ok: false, reason: "gh is not logged in. Run `gh auth login`." };
+	}
+	const user = /Logged in to \S+ account (\S+)/.exec(status.out)?.[1];
+	const scopes = /Token scopes: (.+)/
+		.exec(status.out)?.[1]
+		?.split(",")
+		.map((scope) => scope.trim().replace(/^'|'$/g, ""));
+	if (scopes && !scopes.includes(REPO_SCOPE)) {
+		return {
+			ok: false,
+			user,
+			scopes,
+			reason: `gh is logged in as ${user ?? "you"} but its token lacks the \`${REPO_SCOPE}\` scope, which writing repository secrets needs.\n  Run \`gh auth refresh -s ${REPO_SCOPE}\`.`,
+		};
+	}
+	return { ok: true, user, scopes };
+}
+
+/** `owner/repo` for this checkout, or null when there is no GitHub remote yet. */
+export async function repoSlug(cwd: string): Promise<string | null> {
+	const gh = findGh();
+	if (!gh) return null;
+	const viewed = await run(gh, ["repo", "view", "--json", "nameWithOwner", "-q", ".nameWithOwner"], cwd);
+	if (viewed.code !== 0) return null;
+	const slug = viewed.out.trim();
+	return /^[^/\s]+\/[^/\s]+$/.test(slug) ? slug : null;
+}
+
+/**
+ * Write a repository secret, with the value on STDIN.
+ *
+ * Never as an argument: an argument is visible in `ps` to every other
+ * process on the machine for as long as the call runs, and this is called
+ * with private keys.
+ */
+export async function setSecret(cwd: string, name: string, value: string): Promise<{ ok: boolean; error?: string }> {
+	const gh = findGh();
+	if (!gh) return { ok: false, error: "gh is not installed" };
+	const result = await run(gh, ["secret", "set", name], cwd, value);
+	return result.code === 0 ? { ok: true } : { ok: false, error: result.out.trim().split("\n").slice(-2).join(" ") };
+}
+
+/** Repository secret NAMES. GitHub never gives a value back, by design. */
+export async function secretNames(cwd: string): Promise<Set<string>> {
+	const gh = findGh();
+	if (!gh) return new Set();
+	const listed = await run(gh, ["secret", "list", "--json", "name", "-q", ".[].name"], cwd);
+	if (listed.code !== 0) return new Set();
+	return new Set(
+		listed.out
+			.split("\n")
+			.map((line) => line.trim())
+			.filter(Boolean),
+	);
+}
+
+/** A repository VARIABLE — readable, for things that are configuration rather than credentials. */
+export async function setVariable(cwd: string, name: string, value: string): Promise<{ ok: boolean; error?: string }> {
+	const gh = findGh();
+	if (!gh) return { ok: false, error: "gh is not installed" };
+	const result = await run(gh, ["variable", "set", name, "--body", value], cwd);
+	return result.code === 0 ? { ok: true } : { ok: false, error: result.out.trim().split("\n").slice(-2).join(" ") };
+}
+
+export async function variableNames(cwd: string): Promise<Set<string>> {
+	const gh = findGh();
+	if (!gh) return new Set();
+	const listed = await run(gh, ["variable", "list", "--json", "name", "-q", ".[].name"], cwd);
+	if (listed.code !== 0) return new Set();
+	return new Set(
+		listed.out
+			.split("\n")
+			.map((line) => line.trim())
+			.filter(Boolean),
+	);
+}
+
+/**
+ * Ask Cloudflare whether a token is real, before it is stored anywhere.
+ *
+ * A token that is wrong should be caught at the moment it is typed, by the
+ * person who has it, and not two minutes into a CI run by someone reading a
+ * log. This is the one Cloudflare call vc makes with the token in hand.
+ *
+ * @see https://developers.cloudflare.com/fundamentals/api/reference/verify-token/
+ */
+export async function verifyCloudflareToken(token: string): Promise<{ ok: boolean; detail: string }> {
+	try {
+		const response = await fetch("https://api.cloudflare.com/client/v4/user/tokens/verify", {
+			headers: { Authorization: `Bearer ${token}` },
+		});
+		const body = (await response.json()) as { success?: boolean; result?: { status?: string }; errors?: Array<{ message?: string }> };
+		if (body.success && body.result?.status === "active") return { ok: true, detail: "active" };
+		const message = body.errors?.[0]?.message ?? `HTTP ${response.status}`;
+		return { ok: false, detail: message };
+	} catch (error) {
+		return { ok: false, detail: `could not reach the Cloudflare API: ${String(error)}` };
+	}
+}
+
+/** The accounts a token can see, so the account id never has to be typed. */
+export async function cloudflareAccounts(token: string): Promise<Array<{ id: string; name: string }>> {
+	try {
+		const response = await fetch("https://api.cloudflare.com/client/v4/accounts?per_page=50", {
+			headers: { Authorization: `Bearer ${token}` },
+		});
+		const body = (await response.json()) as { success?: boolean; result?: Array<{ id: string; name: string }> };
+		return body.success && Array.isArray(body.result) ? body.result.map((a) => ({ id: a.id, name: a.name })) : [];
+	} catch {
+		return [];
+	}
+}

package/src/deploy/index.ts

@@ -6,6 +6,7 @@ import { deployCloudflare } from "./cloudflare";
 import { preflight, printPreflight } from "./preflight";
 import { PRIVATE_KEY_VAR, SECRETS_FILE, plaintextSecretNames, secretsCommand } from "./secrets";
 import { keysCommand } from "./keys";
+import { linkCommand } from "./link";
 
 /**
  * `vc deploy` extends `void deploy`: vc's preflight first, then void's
@@ -79,8 +80,11 @@ export async function deployHelp(): Promise<number> {
 		...row("vc deploy --cloudflare --force", "deploy a shop preflight says is not ready — deliberately", width, 2),
 		line("", width),
 		line(color.bold("Needs, for --cloudflare"), width),
-		...row("wrangler login", "or CLOUDFLARE_API_TOKEN; the account is pinned for you when there is one", width, 2),
-		...row("wrangler secret put <KEY>", "each secret, on the worker — preflight lists them", width, 2),
+		...row("CLOUDFLARE_API_TOKEN", "in the environment; the account is pinned for you when there is one", width, 2),
+		...row(PRIVATE_KEY_VAR, "to decrypt the shop's own secrets", width, 2),
+		line("", width),
+		line("Normally neither is on your machine: `vc link` puts both on the GitHub", width),
+		line("repository and the workflow runs this command for you on every push.", width),
 	], width);
 	if (captured) process.stdout.write(captured.out.replace(/\n*$/, "\n"));
 	console.log(ours);
@@ -119,14 +123,16 @@ export async function secretsHelp(): Promise<number> {
 			line(`Secrets that live in the repository, encrypted, in ${SECRETS_FILE}.`, width),
 			line("", width),
 			...row("vc secrets", "what this shop needs, and whether it is declared and encrypted", width, 2),
-			...row("vc secrets --init", `write ${SECRETS_FILE} with every required key as \`unset\``, width, 2),
-			...row(`dotenvx set KEY '…' -f ${SECRETS_FILE}`, "set one, without decrypting the file", width, 2),
-			...row(`dotenvx encrypt -f ${SECRETS_FILE}`, "encrypt anything still in the clear", width, 2),
+			...row("vc secrets --init", `write ${SECRETS_FILE} and make this shop's key`, width, 2),
+			...row("vc secrets set KEY", "set one value — prompts, so it never reaches your shell history", width, 2),
+			...row("echo v | vc secrets set KEY", "the same, from a pipe, for scripts", width, 2),
 			line("", width),
 			line("The file is COMMITTED: values are ciphertext, key names are not, so a", width),
 			line("diff shows which secret changed without showing what it changed to.", width),
-			line(`The private key stays out — .env.keys locally, and ${PRIVATE_KEY_VAR}`, width),
-			line("as one build variable where the deploy runs.", width),
+			line("", width),
+			line("Setting one needs NO credential. dotenvx is asymmetric, so encryption uses", width),
+			line(`the public key already in ${SECRETS_FILE}. The private key is a GitHub`, width),
+			line(`Actions secret, ${PRIVATE_KEY_VAR}, and only the deploy uses it.`, width),
 			line("", width),
 			line("Tradeoff worth knowing: ciphertext in git is permanent, so a leaked key", width),
 			line("exposes rotated secrets too. `wrangler secret put` does not have that", width),
@@ -143,25 +149,29 @@ export async function keysCliCommand(args: string[]): Promise<number> {
 		console.error("vc: no voidcommerce.json here.");
 		return 1;
 	}
-	return keysCommand(project.manifest, project.root, args);
+	return keysCommand(project, 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("Secrets are encrypted with a PUBLIC key that is committed, and read with", width),
+			line("a PRIVATE key that lives only in GitHub Actions.", width),
+			line("", width),
+			...row("vc keys", "where the key is, and what is missing", width, 2),
+			...row("vc keys --init", "generate one and store it on the GitHub repository", width, 2),
+			...row("vc keys --rotate", "re-key and re-encrypt, if you hold the current private key", width, 2),
 			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("Because the encryption is asymmetric, SETTING a secret needs no credential", width),
+			line("at all: `vc secrets set KEY` encrypts with the public key in the repository.", width),
+			line("A contributor with only a clone can rotate the Stripe key and cannot read", width),
+			line("the one already there. Only the deploy decrypts.", width),
 			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),
+			line("GitHub will not hand a secret back once set, so re-keying without a local", width),
+			line("copy means entering the values again. That is the right trade: a key worth", width),
+			line("rotating is a key that may have leaked, and leaked values need replacing", width),
+			line("at the source anyway.", width),
 		], width),
 	);
 	return 0;
@@ -187,3 +197,41 @@ export async function guardCommand(): Promise<number> {
 	);
 	return 1;
 }
+
+
+/** `vc link` — GitHub holds the credentials; this is what puts them there. */
+export async function linkCliCommand(args: string[]): Promise<number> {
+	const project = await findProject();
+	if (!project) {
+		console.error("vc: no voidcommerce.json here.");
+		return 1;
+	}
+	return linkCommand(project, args);
+}
+
+export async function linkHelp(): Promise<number> {
+	const width = 80;
+	console.log(
+		box("vc link", [
+			line("Put this shop's credentials on its GitHub repository, once, so that", width),
+			line("every deploy after this is a `git push`.", width),
+			line("", width),
+			...row("vc link", "generate the encryption key, take the Cloudflare token, store both", width, 2),
+			...row("vc link --force", "replace what is already there", width, 2),
+			line("", width),
+			line(color.bold("What it stores, and where"), width),
+			...row("DOTENV_PRIVATE_KEY_SECRETS", "generated here, never written to disk — a repository SECRET", width, 2),
+			...row("CLOUDFLARE_API_TOKEN", "yours, checked against the Cloudflare API first — a repository SECRET", width, 2),
+			...row("CLOUDFLARE_ACCOUNT_ID", "an identifier, not a credential — a repository VARIABLE", width, 2),
+			line("", width),
+			line(color.bold("Why one token still has to be typed"), width),
+			line("GitHub cannot mint a Cloudflare credential. There is no OIDC federation", width),
+			line("between them, and the Cloudflare GitHub App runs the other way: it grants", width),
+			line("Cloudflare access to your repository, not your repository access to", width),
+			line("Cloudflare. Something must authorise creating a database in your account,", width),
+			line("and only Cloudflare can issue that. So it is typed once, here, and never", width),
+			line("stored on this machine.", width),
+		], width),
+	);
+	return 0;
+}