@saastemly/voidcommerce 0.16.0 → 0.17.0

package/dist/cli.js

@@ -21,7 +21,7 @@ import {
   runVoid,
   version,
   voidAppsIn
-} from "./index-x70qxh3m.js";
+} from "./index-4jz1448c.js";
 import {
   LOCAL_KEY_FILE,
   PRIVATE_KEY_VAR,
@@ -32,6 +32,7 @@ import {
   declaredSecretNames,
   encryptInto,
   envSummary,
+  getVariable,
   ghAuth,
   ignoresKeyFile,
   initSecrets,
@@ -50,7 +51,7 @@ import {
   setVariable,
   variableNames,
   verifyCloudflareToken
-} from "./index-s8se0x2d.js";
+} from "./index-negctpws.js";
 import {
   LAYOUTS,
   oneOrigin,
@@ -118,16 +119,23 @@ async function linkCommand(project, args) {
   } else {
     const parked = localPrivateKey(root);
     if (parked) {
-      const sent = await setSecret(root, PRIVATE_KEY_VAR, parked);
+      const sent = await setVariable(root, PRIVATE_KEY_VAR, parked);
       if (!sent.ok) {
-        p.cancel(`GitHub refused the secret: ${sent.error ?? "unknown error"}`);
+        p.cancel(`GitHub refused the variable: ${sent.error ?? "unknown error"}`);
         return 1;
       }
       const publicKey = await publicKeyFor(parked);
       if (publicKey)
         committedPublicKeyInto(root, publicKey);
-      rmSync(join(root, LOCAL_KEY_FILE), { force: true });
-      p.log.success(`${color.green("✓")} the key waiting in ${LOCAL_KEY_FILE} moved to GitHub, and the file deleted`);
+      const readBack = await getVariable(root, PRIVATE_KEY_VAR);
+      if (readBack !== parked) {
+        p.log.warn(`${color.yellow("!")} ${PRIVATE_KEY_VAR} was written to ${slug} but could not be read back,
+  so ${LOCAL_KEY_FILE} has been LEFT IN PLACE. It is currently the only copy
+` + "  of the key that opens this shop — do not delete it until `vc keys --restore` works.");
+      } else {
+        rmSync(join(root, LOCAL_KEY_FILE), { force: true });
+        p.log.success(`${color.green("✓")} the key moved to ${slug} and ${LOCAL_KEY_FILE} deleted — verified readable, so \`vc keys --restore\` can bring it back`);
+      }
     } else {
       const made = await provisionKey(project);
       if (!made.ok) {
@@ -372,10 +380,15 @@ async function keysHelp() {
     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;
 }

package/dist/deploy/github.d.ts

@@ -66,6 +66,14 @@ export declare function setVariable(cwd: string, name: string, value: string): P
     ok: boolean;
     error?: string;
 }>;
+/**
+ * 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 declare function getVariable(cwd: string, name: string): Promise<string | null>;
 export declare function variableNames(cwd: string): Promise<Set<string>>;
 /**
  * Ask Cloudflare whether a token is real, before it is stored anywhere.

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/{index-x70qxh3m.js → index-4jz1448c.js}

@@ -12,7 +12,7 @@ import {
   renderEnvProduction,
   renderEnvTs,
   unsetSecretNames
-} from "./index-s8se0x2d.js";
+} from "./index-negctpws.js";
 import {
   MANIFEST_FILE,
   has,
@@ -1379,7 +1379,7 @@ import color from "picocolors";
 // package.json
 var package_default = {
   name: "@saastemly/voidcommerce",
-  version: "0.16.0",
+  version: "0.17.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}"
@@ -1898,7 +1907,7 @@ vc link
 
 | 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 +1955,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 +1997,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-negctpws.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-w65kbdp6.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, 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 run, committedPublicKeyInto, declaredSecretNames, unsetSecretNames, plaintextSecretNames, plaintextSecretEntries, decryptSecrets, secretsCommand, initSecrets, encryptInto };

package/dist/index.js

@@ -52,7 +52,7 @@ import {
   routeProblem,
   strictDependencies,
   upsertJsonc
-} from "./index-x70qxh3m.js";
+} from "./index-4jz1448c.js";
 import {
   allEnvKeys,
   envSummary,
@@ -60,7 +60,7 @@ import {
   renderEnvLocal,
   renderEnvProduction,
   renderEnvTs
-} from "./index-s8se0x2d.js";
+} from "./index-negctpws.js";
 import {
   LAYOUTS,
   MANIFEST_FILE,

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

@@ -8,7 +8,7 @@ import {
   localPrivateKey,
   provisionKey,
   publicKeyFor
-} from "./index-s8se0x2d.js";
+} from "./index-negctpws.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.0",
+  "version": "0.17.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/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

@@ -66,11 +66,14 @@ export async function preflightCommand(args: string[]): Promise<number> {
 	printPreflight(project, result, source);
 	if (source !== "repository") return result.ready ? 0 : 1;
 
-	// A repository check is a check on what will be PUSHED, so it also asks
-	// the question CI would ask and cannot answer any earlier: is there a
-	// migration that was generated and never committed? Applied under a fresh
-	// name on the next run, against tables that already exist, it fails the
-	// deploy — and it fails it after the shop is already down for the update.
+	// Is there a migration that was generated and never committed?
+	//
+	// This one has teeth only LOCALLY. A CI checkout is by definition clean,
+	// so `git status` there reports nothing and this passes vacuously — the
+	// job that actually catches it in CI is the one that runs AFTER `vc dist`
+	// regenerates, because that is the moment a new migration can appear.
+	// Both are kept: they catch the same mistake at the two different moments
+	// it can be made.
 	const pending = await uncommittedMigrations(project.root);
 	if (pending.length > 0) {
 		console.error(
@@ -198,10 +201,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;

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`);

package/src/deploy/link.ts

@@ -3,7 +3,7 @@ import { join } from "node:path";
 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 { cloudflareAccounts, getVariable, ghAuth, repoSlug, secretNames, setSecret, setVariable, variableNames, verifyCloudflareToken } from "./github";
 import { LOCAL_KEY_FILE, keyState, localPrivateKey, provisionKey, publicKeyFor } from "./keys";
 import { PRIVATE_KEY_VAR, SECRETS_FILE, committedPublicKeyInto, declaredSecretNames, initSecrets } from "./secrets";
 
@@ -91,17 +91,31 @@ export async function linkCommand(project: Project, args: string[]): Promise<num
 		// ADOPTED, not replaced: it may already have encrypted the whole shop.
 		const parked = localPrivateKey(root);
 		if (parked) {
-			const sent = await setSecret(root, PRIVATE_KEY_VAR, parked);
+			const sent = await setVariable(root, PRIVATE_KEY_VAR, parked);
 			if (!sent.ok) {
-				p.cancel(`GitHub refused the secret: ${sent.error ?? "unknown error"}`);
+				p.cancel(`GitHub refused the variable: ${sent.error ?? "unknown error"}`);
 				return 1;
 			}
 			const publicKey = await publicKeyFor(parked);
 			if (publicKey) committedPublicKeyInto(root, publicKey);
-			// Only now, once GitHub has it: deleting first would lose the key
-			// outright if the upload failed.
-			rmSync(join(root, LOCAL_KEY_FILE), { force: true });
-			p.log.success(`${color.green("✓")} the key waiting in ${LOCAL_KEY_FILE} moved to GitHub, and the file deleted`);
+
+			// READ IT BACK before deleting the only other copy. "The write
+			// returned success" is not the same claim as "the key can be
+			// recovered", and it is the second one this file is about to bet
+			// the shop on. If it cannot be read, the local copy stays.
+			const readBack = await getVariable(root, PRIVATE_KEY_VAR);
+			if (readBack !== parked) {
+				p.log.warn(
+					`${color.yellow("!")} ${PRIVATE_KEY_VAR} was written to ${slug} but could not be read back,\n` +
+						`  so ${LOCAL_KEY_FILE} has been LEFT IN PLACE. It is currently the only copy\n` +
+						"  of the key that opens this shop — do not delete it until `vc keys --restore` works.",
+				);
+			} else {
+				rmSync(join(root, LOCAL_KEY_FILE), { force: true });
+				p.log.success(
+					`${color.green("✓")} the key moved to ${slug} and ${LOCAL_KEY_FILE} deleted — verified readable, so \`vc keys --restore\` can bring it back`,
+				);
+			}
 		} else {
 			const made = await provisionKey(project);
 			if (!made.ok) {

package/src/generate/ci.ts

@@ -50,7 +50,7 @@ export function renderDistWorkflow(manifest: Manifest): string {
 # 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
@@ -147,16 +147,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}"
@@ -230,7 +239,7 @@ vc link
 
 | 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 |
 
@@ -278,6 +287,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
@@ -302,7 +329,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
 \`\`\`