@saastemly/voidcommerce 0.16.1 → 0.18.0

package/dist/deploy/index.d.ts

@@ -46,3 +46,6 @@ export declare function guardCommand(): Promise<number>;
 /** `vc link` — GitHub holds the credentials; this is what puts them there. */
 export declare function linkCliCommand(args: string[]): Promise<number>;
 export declare function linkHelp(): Promise<number>;
+/** `vc publish` — create the repository, configure it, push. The push deploys. */
+export declare function publishCliCommand(args: string[]): Promise<number>;
+export declare function publishHelp(): Promise<number>;

package/dist/deploy/keys.d.ts

@@ -24,19 +24,30 @@ import type { Project } from "../project";
  *
  * 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.
+ * authenticated.
  *
- * ── Rotation, and why losing the key is survivable ───────────────────────
+ * ── Why it is a VARIABLE and not a secret ────────────────────────────────
  *
- * 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.
+ * `gh secret` has list, set and delete and NO read: a GitHub secret is
+ * write-only forever, even to the person who set it. Keeping the key there
+ * built a one-way door — once the local `.env.keys` was deleted the key
+ * existed nowhere a human could reach, so nobody could ever decrypt again,
+ * including the owner of the shop. CI could deploy, and that was the whole
+ * of it. No reading a value back to check it, no re-keying, no second
+ * machine, no colleague.
+ *
+ * A repository VARIABLE can be read back (`gh variable get`), so the key is
+ * recoverable by anyone with access to the repository — the owner, plus
+ * whoever they invite. That access list IS the answer to "a key several
+ * people can share": adding a colleague is adding a collaborator, and
+ * removing their access removes their ability to decrypt.
+ *
+ * The cost, stated plainly. A variable is shown in the repository's settings
+ * in the clear, and unlike a secret it is NOT masked in workflow logs
+ * automatically. So the generated workflow masks it with `::add-mask::` the
+ * moment it reads it, and the repository must be private. This is the right
+ * trade only because the alternative — a key nobody can ever read — is not a
+ * working system, it is a shop with one deploy left in it.
  */
 /**
  * Where a private key waits before the repository exists.

package/dist/deploy/publish.d.ts

@@ -0,0 +1,32 @@
+import type { Project } from "../project";
+/**
+ * `vc publish` — make the repository, give it what it needs, push.
+ *
+ * ── Why this exists ──────────────────────────────────────────────────────
+ *
+ * The goal was always "publishing to GitHub is the deploy". `vc link` sat in
+ * front of that as a separate step, and it is worth being exact about what
+ * it was actually for, because two of its three jobs never needed a person:
+ *
+ *   DOTENV_PRIVATE_KEY_SECRETS   vc already holds it — automatic
+ *   CLOUDFLARE_ACCOUNT_ID        it is in the manifest — automatic
+ *   CLOUDFLARE_API_TOKEN         exists only in Cloudflare's dashboard
+ *
+ * Only the third needs a human, and it cannot be removed: there is no OIDC
+ * or workload identity federation from GitHub to the Cloudflare API, so
+ * something has to carry a token across, and only a person can fetch one.
+ * Everything else is ceremony that a command can do.
+ *
+ * So this is the one command. It creates the repository, sets all three,
+ * and pushes — and the push is what deploys. After it, `git push` is the
+ * whole loop forever, and `vc` is only needed to read or change a secret.
+ *
+ * ── The order matters ────────────────────────────────────────────────────
+ *
+ * The repository is created WITHOUT pushing, the credentials go on, and only
+ * then does the push happen. `gh repo create --push` would put main there
+ * first, which starts a deploy against a repository that has no key and no
+ * token — a red run, an email, and a shop that did not deploy, for no
+ * reason other than doing two things in the wrong order.
+ */
+export declare function publishCommand(project: Project, args: string[]): Promise<number>;

package/dist/{index-w0c96dxv.js → index-3j6jtjmk.js}

@@ -12,7 +12,7 @@ import {
   renderEnvProduction,
   renderEnvTs,
   unsetSecretNames
-} from "./index-s8se0x2d.js";
+} from "./index-khzk6a9z.js";
 import {
   MANIFEST_FILE,
   has,
@@ -1379,7 +1379,7 @@ import color from "picocolors";
 // package.json
 var package_default = {
   name: "@saastemly/voidcommerce",
-  version: "0.16.1",
+  version: "0.18.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",
@@ -1720,7 +1720,7 @@ function renderDistWorkflow(manifest) {
 # The credentials come from the repository, set once by \`vc link\`:
 #
 #   secrets.CLOUDFLARE_API_TOKEN        deploys, and creates D1 + the queue
-#   secrets.${PRIVATE_KEY_VAR}   opens ${SECRETS_FILE}
+#   vars.${PRIVATE_KEY_VAR}      opens ${SECRETS_FILE} (a VARIABLE, so it can be read back)
 #   vars.CLOUDFLARE_ACCOUNT_ID          which account (an id, not a credential)
 #
 # Nothing here needs a Cloudflare dashboard visit and nothing needs wrangler
@@ -1817,16 +1817,25 @@ jobs:
     env:
       CLOUDFLARE_API_TOKEN: \${{ secrets.CLOUDFLARE_API_TOKEN }}
       CLOUDFLARE_ACCOUNT_ID: \${{ vars.CLOUDFLARE_ACCOUNT_ID }}
-      ${PRIVATE_KEY_VAR}: \${{ secrets.${PRIVATE_KEY_VAR} }}
+      ${PRIVATE_KEY_VAR}: \${{ vars.${PRIVATE_KEY_VAR} }}
     steps:
       - uses: actions/checkout@v6
       - uses: oven-sh/setup-bun@v2
 
       # Checked before anything is built, so a repository that was never
       # linked says so in five seconds rather than four minutes.
+      #
+      # And ${PRIVATE_KEY_VAR} is masked here, first thing. It is a
+      # VARIABLE rather than a secret so that a human can read it back —
+      # that is what makes a new laptop or a second person possible — but
+      # GitHub only masks SECRETS in logs automatically. Registering it with
+      # ::add-mask:: buys back the redaction without giving up recovery.
       - name: Are the credentials here?
         run: |
           set -euo pipefail
+          if [ -n "\${${PRIVATE_KEY_VAR}:-}" ]; then
+            echo "::add-mask::\${${PRIVATE_KEY_VAR}}"
+          fi
           missing=""
           [ -n "\${CLOUDFLARE_API_TOKEN:-}" ] || missing="$missing CLOUDFLARE_API_TOKEN"
           [ -n "\${${PRIVATE_KEY_VAR}:-}" ] || missing="$missing ${PRIVATE_KEY_VAR}"
@@ -1887,18 +1896,25 @@ You do not need wrangler on your machine, and you do not need to be logged
 into it. You do not need to open the Cloudflare dashboard after the one step
 below.
 
-## Once, before the first push
+## Once, to start
 
 \`\`\`sh
-gh repo create --source=. --private --push   # if there is no repo yet
-vc link
+vc publish
 \`\`\`
 
-\`vc link\` does three things and stores all of them on the GitHub repository:
+One command: it creates the repository, gives it what the deploy needs, and
+pushes — and the push is the deploy. After it, \`git push\` is the whole loop.
+
+Two of the three things it sets need nothing from you. The encryption key vc
+already holds; the account id is in \`voidcommerce.json\`. It asks only for a
+Cloudflare API token, because there is no OIDC between GitHub and Cloudflare
+and only a person can fetch one from the dashboard.
+
+It stores three things on the GitHub repository:
 
 | what | where | why |
 |---|---|---|
-| \`${PRIVATE_KEY_VAR}\` | repository **secret** | opens \`${SECRETS_FILE}\`. Generated by \`vc link\`, never written to disk |
+| \`${PRIVATE_KEY_VAR}\` | repository **variable** | opens \`${SECRETS_FILE}\`. A variable, not a secret, so you can get it back — see below |
 | \`CLOUDFLARE_API_TOKEN\` | repository **secret** | deploys, and creates D1 and the queue |
 | \`CLOUDFLARE_ACCOUNT_ID\` | repository **variable** | which account. An identifier, not a credential |
 
@@ -1946,6 +1962,24 @@ vc secrets set STRIPE_SECRET_KEY     # prompts; never touches your shell history
 vc secrets                           # what is set, what is missing
 \`\`\`
 
+### Getting the key back
+
+\`\`\`sh
+vc keys --restore
+\`\`\`
+
+\`${PRIVATE_KEY_VAR}\` is a repository **variable**, not a secret. GitHub
+secrets are write-only — \`gh secret\` has no read command — so a key kept
+there is gone the moment your local copy is, and with it every value in
+\`${SECRETS_FILE}\`. As a variable it can be read back, which is what makes a
+new laptop, a rebuild, or a second person possible at all.
+
+**That means anyone who can read this repository can decrypt its secrets.**
+Keep it private. It is also the answer to sharing: a colleague who is a
+collaborator can run \`vc keys --restore\` and work; removing them removes
+their access. The deploy workflow masks the value with \`::add-mask::\` the
+moment it reads it, because GitHub does not mask variables on its own.
+
 **This needs no credential.** dotenvx is asymmetric: encryption uses the public
 key committed at the top of the file, so anyone with a clone can set or rotate
 a secret. Nobody with a clone can read one. Only the deploy decrypts, with the
@@ -1970,7 +2004,7 @@ The same thing, from a checkout, if CI is ever not the answer:
 
 \`\`\`sh
 export CLOUDFLARE_API_TOKEN=…
-export ${PRIVATE_KEY_VAR}=…        # only if you kept a copy
+export ${PRIVATE_KEY_VAR}=…        # or run \`vc keys --restore\` first
 vc deploy --cloudflare --provision
 \`\`\`
 

package/dist/{index-s8se0x2d.js → index-khzk6a9z.js}

@@ -103,6 +103,16 @@ async function setVariable(cwd, name, value) {
   return result.code === 0 ? { ok: true } : { ok: false, error: result.out.trim().split(`
 `).slice(-2).join(" ") };
 }
+async function getVariable(cwd, name) {
+  const gh = findGh();
+  if (!gh)
+    return null;
+  const got = await run(gh, ["variable", "get", name, "--json", "value", "-q", ".value"], cwd);
+  if (got.code !== 0)
+    return null;
+  const value = got.out.trim();
+  return value.length > 0 ? value : null;
+}
 async function variableNames(cwd) {
   const gh = findGh();
   if (!gh)
@@ -404,7 +414,7 @@ async function decryptSecrets(project) {
   }
   const expected = committedPublicKey(root);
   if (expected) {
-    const { publicKeyFor } = await import("./keys-6neyajsv.js");
+    const { publicKeyFor } = await import("./keys-fn6wbv40.js");
     const derived = await publicKeyFor(privateKey);
     if (derived && derived.toLowerCase() !== expected.toLowerCase()) {
       return {
@@ -749,7 +759,7 @@ async function publicKeyFor(privateKey) {
 async function keyState(project) {
   const publicKey = committedPublicKey(project.root);
   const slug = await repoSlug(project.root);
-  const names = slug ? await secretNames(project.root) : new Set;
+  const names = slug ? await variableNames(project.root) : new Set;
   const localKey = process.env[PRIVATE_KEY_VAR] ?? localPrivateKey(project.root);
   let mismatch;
   if (localKey && publicKey) {
@@ -773,9 +783,9 @@ async function provisionKey(project) {
   const auth = await ghAuth(project.root);
   const slug = auth.ok ? await repoSlug(project.root) : null;
   if (slug) {
-    const sent = await setSecret(project.root, PRIVATE_KEY_VAR, pair.privateKey);
+    const sent = await setVariable(project.root, PRIVATE_KEY_VAR, pair.privateKey);
     if (!sent.ok)
-      return { ok: false, reason: `GitHub refused the secret: ${sent.error ?? "unknown error"}` };
+      return { ok: false, reason: `GitHub refused the variable: ${sent.error ?? "unknown error"}` };
     return { ok: true, publicKey: pair.publicKey, parked: false };
   }
   if (!ignoresKeyFile(project.root)) {
@@ -797,11 +807,65 @@ function ignoresKeyFile(root) {
   return readFileSync2(path, "utf8").split(`
 `).map((line) => line.trim()).some((line) => line === LOCAL_KEY_FILE || line === `/${LOCAL_KEY_FILE}` || line === ".env.keys*" || line === ".env*");
 }
+async function restoreKey(project) {
+  const auth = await ghAuth(project.root);
+  if (!auth.ok) {
+    console.error(`
+vc: ${auth.reason}
+`);
+    return 1;
+  }
+  const slug = await repoSlug(project.root);
+  if (!slug) {
+    console.error(`
+vc: this checkout has no GitHub repository, so there is nowhere to restore from.
+`);
+    return 1;
+  }
+  const key = await getVariable(project.root, PRIVATE_KEY_VAR);
+  if (!key) {
+    console.error(`
+vc: ${slug} has no ${PRIVATE_KEY_VAR} variable.
+  Either this shop was never linked, or the key is held somewhere else.
+  \`vc keys\` shows what this repository has.
+`);
+    return 1;
+  }
+  const committed = committedPublicKey(project.root);
+  const derived = await publicKeyFor(key);
+  if (committed && derived && derived.toLowerCase() !== committed.toLowerCase()) {
+    console.error(`
+vc: the key on ${slug} does not open this repository.
+  it derives:       ${derived.slice(0, 16)}…
+` + `  ${SECRETS_FILE} needs: ${committed.slice(0, 16)}…
+
+` + `  Nothing was written. The repository has been re-keyed since that
+  variable was set, or the two belong to different shops.
+`);
+    return 1;
+  }
+  if (!ignoresKeyFile(project.root)) {
+    console.error(`
+vc: ${LOCAL_KEY_FILE} is not gitignored here, and this would write the key into it.
+  Add it to .gitignore first.
+`);
+    return 1;
+  }
+  writeFileSync2(join3(project.root, LOCAL_KEY_FILE), `${PRIVATE_KEY_VAR}="${key}"
+`, { mode: 384 });
+  console.log(`
+${color2.green("✓")} key restored from ${slug} into ${LOCAL_KEY_FILE}
+` + color2.dim(`  It opens ${SECRETS_FILE}. The file is gitignored; delete it when you are done.
+`));
+  return 0;
+}
 async function keysCommand(project, args) {
   if (args.includes("--rotate"))
     return rotate(project);
   if (args.includes("--init"))
     return initKey(project);
+  if (args.includes("--restore"))
+    return restoreKey(project);
   const state = await keyState(project);
   console.log(`
 Secrets are encrypted with a public key that is COMMITTED, and read with a`);
@@ -931,4 +995,4 @@ ${color2.green("✓")} re-keyed under ${made.publicKey.slice(0, 20)}… and ${PR
   return 0;
 }
 
-export { allEnvKeys, renderEnvTs, renderEnvExample, MANIFEST_OWNED_ENV, renderEnvLocal, renderEnvProduction, envSummary, apiToken, ghAuth, repoSlug, setSecret, secretNames, setVariable, variableNames, verifyCloudflareToken, cloudflareAccounts, LOCAL_KEY_FILE, localPrivateKey, committedPublicKey, generateKeypair, publicKeyFor, keyState, provisionKey, ignoresKeyFile, keysCommand, SECRETS_FILE, PRIVATE_KEY_VAR, run2 as run, committedPublicKeyInto, declaredSecretNames, unsetSecretNames, plaintextSecretNames, plaintextSecretEntries, decryptSecrets, secretsCommand, initSecrets, encryptInto };
+export { allEnvKeys, renderEnvTs, renderEnvExample, MANIFEST_OWNED_ENV, renderEnvLocal, renderEnvProduction, envSummary, apiToken, findGh, run, ghAuth, repoSlug, setSecret, secretNames, setVariable, getVariable, variableNames, verifyCloudflareToken, cloudflareAccounts, LOCAL_KEY_FILE, localPrivateKey, committedPublicKey, generateKeypair, publicKeyFor, keyState, provisionKey, ignoresKeyFile, keysCommand, SECRETS_FILE, PRIVATE_KEY_VAR, run2 as run1, committedPublicKeyInto, declaredSecretNames, unsetSecretNames, plaintextSecretNames, plaintextSecretEntries, decryptSecrets, secretsCommand, initSecrets, encryptInto };

package/dist/index.js

@@ -52,7 +52,7 @@ import {
   routeProblem,
   strictDependencies,
   upsertJsonc
-} from "./index-w0c96dxv.js";
+} from "./index-3j6jtjmk.js";
 import {
   allEnvKeys,
   envSummary,
@@ -60,7 +60,7 @@ import {
   renderEnvLocal,
   renderEnvProduction,
   renderEnvTs
-} from "./index-s8se0x2d.js";
+} from "./index-khzk6a9z.js";
 import {
   LAYOUTS,
   MANIFEST_FILE,

package/dist/{keys-6neyajsv.js → keys-fn6wbv40.js}

@@ -8,7 +8,7 @@ import {
   localPrivateKey,
   provisionKey,
   publicKeyFor
-} from "./index-s8se0x2d.js";
+} from "./index-khzk6a9z.js";
 import"./index-30y19qz5.js";
 import"./index-xyjhy6kp.js";
 import"./index-0v6na3yp.js";

package/package.json

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

@@ -6,6 +6,8 @@ import {
 	keysHelp,
 	linkCliCommand,
 	linkHelp,
+	publishCliCommand,
+	publishHelp,
 	preflightCommand,
 	preflightHelp,
 	secretsCliCommand,
@@ -53,6 +55,7 @@ export const EXTENDED: Record<string, Extended> = {
 	secrets: { run: secretsCliCommand, help: secretsHelp },
 	keys: { run: keysCliCommand, help: keysHelp },
 	link: { run: linkCliCommand, help: linkHelp },
+	publish: { run: publishCliCommand, help: publishHelp },
 	// 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

@@ -153,6 +153,22 @@ export async function setVariable(cwd: string, name: string, value: string): Pro
 	return result.code === 0 ? { ok: true } : { ok: false, error: result.out.trim().split("\n").slice(-2).join(" ") };
 }
 
+/**
+ * A variable's VALUE — the thing a secret can never give back.
+ *
+ * `gh secret` has list, set and delete and no read, by design: a GitHub
+ * secret is write-only forever, even to its owner. A variable is not, and
+ * that single difference is why the encryption key lives in one.
+ */
+export async function getVariable(cwd: string, name: string): Promise<string | null> {
+	const gh = findGh();
+	if (!gh) return null;
+	const got = await run(gh, ["variable", "get", name, "--json", "value", "-q", ".value"], cwd);
+	if (got.code !== 0) return null;
+	const value = got.out.trim();
+	return value.length > 0 ? value : null;
+}
+
 export async function variableNames(cwd: string): Promise<Set<string>> {
 	const gh = findGh();
 	if (!gh) return new Set();

package/src/deploy/index.ts

@@ -9,6 +9,7 @@ import { join } from "node:path";
 import { PRIVATE_KEY_VAR, SECRETS_FILE, encryptInto, plaintextSecretEntries, plaintextSecretNames, run, secretsCommand } from "./secrets";
 import { LOCAL_KEY_FILE, committedPublicKey, ignoresKeyFile, keysCommand } from "./keys";
 import { linkCommand } from "./link";
+import { publishCommand } from "./publish";
 
 /**
  * `vc deploy` extends `void deploy`: vc's preflight first, then void's
@@ -201,10 +202,15 @@ export async function keysHelp(): Promise<number> {
 			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("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),
+			line("The key is a repository VARIABLE, not a secret. GitHub secrets are", width),
+			line("write-only — `gh secret` has no read command — so a key kept there is", width),
+			line("gone the moment your local copy is, and every encrypted value with it.", width),
+			line("As a variable it can be read back, which is what makes a new machine or", width),
+			line("a second person possible: `vc keys --restore`.", width),
+			line("", width),
+			line("So anyone who can READ the repository can decrypt its secrets. Keep it", width),
+			line("private. That access list is also how you share: a collaborator can", width),
+			line("restore the key, and removing them removes their access.", width),
 		], width),
 	);
 	return 0;
@@ -336,3 +342,42 @@ export async function linkHelp(): Promise<number> {
 	);
 	return 0;
 }
+
+
+/** `vc publish` — create the repository, configure it, push. The push deploys. */
+export async function publishCliCommand(args: string[]): Promise<number> {
+	const project = await findProject();
+	if (!project) {
+		console.error("vc: no voidcommerce.json here.");
+		return 1;
+	}
+	return publishCommand(project, args);
+}
+
+export async function publishHelp(): Promise<number> {
+	const width = 80;
+	console.log(
+		box("vc publish", [
+			line("Create this shop's GitHub repository, give it what the deploy needs,", width),
+			line("and push. The push IS the deploy. Run once; after that, `git push`.", width),
+			line("", width),
+			...row("vc publish", "create the repository, set the credentials, push main", width, 2),
+			line("", width),
+			line(color.bold("What it does for you"), width),
+			...row("the encryption key", "vc already holds it — set with no input from you", width, 2),
+			...row("the account id", "read from voidcommerce.json", width, 2),
+			...row("the Cloudflare token", "the one thing it has to ask for", width, 2),
+			line("", width),
+			line(color.bold("Why the token cannot be automated away"), width),
+			line("There is no OIDC between GitHub and Cloudflare, so something must carry", width),
+			line("a token across, and only a person can fetch one from the dashboard. It", width),
+			line("is asked for once, checked against the Cloudflare API, and stored on the", width),
+			line("repository — never on this machine.", width),
+			line("", width),
+			line("The repository is created WITHOUT pushing, then configured, then pushed.", width),
+			line("Pushing first would start a deploy against a repository that has no key", width),
+			line("and no token: a red run, for no reason but the wrong order.", width),
+		], width),
+	);
+	return 0;
+}

package/src/deploy/keys.ts

@@ -2,7 +2,7 @@ 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 { getVariable, ghAuth, repoSlug, setVariable, variableNames } from "./github";
 import { PRIVATE_KEY_VAR, SECRETS_FILE, committedPublicKeyInto, findDotenvx, run } from "./secrets";
 
 /**
@@ -30,19 +30,30 @@ import { PRIVATE_KEY_VAR, SECRETS_FILE, committedPublicKeyInto, findDotenvx, run
  *
  * 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.
+ * authenticated.
  *
- * ── Rotation, and why losing the key is survivable ───────────────────────
+ * ── Why it is a VARIABLE and not a secret ────────────────────────────────
  *
- * 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.
+ * `gh secret` has list, set and delete and NO read: a GitHub secret is
+ * write-only forever, even to the person who set it. Keeping the key there
+ * built a one-way door — once the local `.env.keys` was deleted the key
+ * existed nowhere a human could reach, so nobody could ever decrypt again,
+ * including the owner of the shop. CI could deploy, and that was the whole
+ * of it. No reading a value back to check it, no re-keying, no second
+ * machine, no colleague.
+ *
+ * A repository VARIABLE can be read back (`gh variable get`), so the key is
+ * recoverable by anyone with access to the repository — the owner, plus
+ * whoever they invite. That access list IS the answer to "a key several
+ * people can share": adding a colleague is adding a collaborator, and
+ * removing their access removes their ability to decrypt.
+ *
+ * The cost, stated plainly. A variable is shown in the repository's settings
+ * in the clear, and unlike a secret it is NOT masked in workflow logs
+ * automatically. So the generated workflow masks it with `::add-mask::` the
+ * moment it reads it, and the repository must be private. This is the right
+ * trade only because the alternative — a key nobody can ever read — is not a
+ * working system, it is a shop with one deploy left in it.
  */
 
 /**
@@ -108,7 +119,7 @@ export interface KeyState {
 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 names = slug ? await variableNames(project.root) : new Set<string>();
 	const localKey = process.env[PRIVATE_KEY_VAR] ?? localPrivateKey(project.root);
 
 	let mismatch: string | undefined;
@@ -144,8 +155,8 @@ export async function provisionKey(project: Project): Promise<{ ok: true; public
 	const slug = auth.ok ? await repoSlug(project.root) : null;
 
 	if (slug) {
-		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"}` };
+		const sent = await setVariable(project.root, PRIVATE_KEY_VAR, pair.privateKey);
+		if (!sent.ok) return { ok: false, reason: `GitHub refused the variable: ${sent.error ?? "unknown error"}` };
 		return { ok: true, publicKey: pair.publicKey, parked: false };
 	}
 
@@ -175,10 +186,69 @@ export function ignoresKeyFile(root: string): boolean {
 		.some((line) => line === LOCAL_KEY_FILE || line === `/${LOCAL_KEY_FILE}` || line === ".env.keys*" || line === ".env*");
 }
 
+/**
+ * Bring the key back onto a machine that does not have it.
+ *
+ * This is the command that makes the whole arrangement survivable. A new
+ * laptop, a colleague joining, or simply wanting to read a value back: all
+ * of them were impossible while the key lived somewhere write-only. Here it
+ * is one command, and the only credential involved is being logged into
+ * `gh` as somebody the repository lets in.
+ */
+async function restoreKey(project: Project): Promise<number> {
+	const auth = await ghAuth(project.root);
+	if (!auth.ok) {
+		console.error(`\nvc: ${auth.reason}\n`);
+		return 1;
+	}
+	const slug = await repoSlug(project.root);
+	if (!slug) {
+		console.error("\nvc: this checkout has no GitHub repository, so there is nowhere to restore from.\n");
+		return 1;
+	}
+
+	const key = await getVariable(project.root, PRIVATE_KEY_VAR);
+	if (!key) {
+		console.error(
+			`\nvc: ${slug} has no ${PRIVATE_KEY_VAR} variable.\n` +
+				`  Either this shop was never linked, or the key is held somewhere else.\n` +
+				`  \`vc keys\` shows what this repository has.\n`,
+		);
+		return 1;
+	}
+
+	// Check it opens THIS repository before writing it down. A key that
+	// belongs to another shop would decrypt nothing and confuse everything.
+	const committed = committedPublicKey(project.root);
+	const derived = await publicKeyFor(key);
+	if (committed && derived && derived.toLowerCase() !== committed.toLowerCase()) {
+		console.error(
+			`\nvc: the key on ${slug} does not open this repository.\n` +
+				`  it derives:       ${derived.slice(0, 16)}…\n` +
+				`  ${SECRETS_FILE} needs: ${committed.slice(0, 16)}…\n\n` +
+				"  Nothing was written. The repository has been re-keyed since that\n" +
+				"  variable was set, or the two belong to different shops.\n",
+		);
+		return 1;
+	}
+
+	if (!ignoresKeyFile(project.root)) {
+		console.error(`\nvc: ${LOCAL_KEY_FILE} is not gitignored here, and this would write the key into it.\n  Add it to .gitignore first.\n`);
+		return 1;
+	}
+	writeFileSync(join(project.root, LOCAL_KEY_FILE), `${PRIVATE_KEY_VAR}="${key}"\n`, { mode: 0o600 });
+	console.log(
+		`\n${color.green("✓")} key restored from ${slug} into ${LOCAL_KEY_FILE}\n` +
+			color.dim(`  It opens ${SECRETS_FILE}. The file is gitignored; delete it when you are done.\n`),
+	);
+	return 0;
+}
+
 /** `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);
+	if (args.includes("--restore")) return restoreKey(project);
 
 	const state = await keyState(project);
 	console.log(`\nSecrets are encrypted with a public key that is COMMITTED, and read with a`);