getmyenv 0.9.8 → 0.10.0

package/README.md

@@ -23,7 +23,7 @@ npx getmyenv run staging -- npm start # or pick one
 - `export [-o file | --stdout] [--yes]`: for tools that need a file. The file is added to `.gitignore` and gets owner-only permissions on macOS and Linux.
 - `guest [--name <name>]`: a project without an account. It works for 30 days. Claim it within 60.
 - `claim`: claim a guest project. Reads `.getmyenv/claim.json`, or asks for the claim code and guest passphrase that `guest` printed once at a terminal.
-- `backup [-o file]`: encrypted backup of open contexts (default `<project>.getmyenv-backup`). It opens with the Vault password in effect when it was made.
+- `backup [-o file]`: encrypted backup of open contexts (default `<project>.getmyenv-backup`). It opens with the Vault password or the recovery code in effect when it was made.
 - `restore <file> [--dry-run] [--yes]`: restore a backup into this folder's project. Values go into open contexts with the same slug and replace values with the same name. Read-only and missing contexts are skipped.
 - `start`: same as bare `getmyenv`. `start --template <id or link>` adds a template's variable names and asks for each value.
 - `lock`: forget every unlocked context key on this machine. `unlink [--yes]`, `help [command]`
@@ -35,7 +35,7 @@ Prompts and status lines go to stderr, so `export --stdout > .env` stays clean.
 Commit `.getmyenv/project.json`. `token.json` and `claim.json` stay local and are gitignored.
 
 <!-- cli:help -->
-Output of `npx getmyenv --help` (0.9.8):
+Output of `npx getmyenv --help` (0.10.0):
 
 ```text
 Usage: getmyenv [options] [command]

package/dist/commands/backup.d.ts

@@ -2,6 +2,6 @@ type BackupOpts = {
     output?: string;
     apiUrl?: string;
 };
-/** Encrypted backup of open contexts. Opens offline with the current Vault password. */
+/** Encrypted backup of open contexts. Opens offline with the current Vault password or recovery code. */
 export declare function backupCommand(opts: BackupOpts): Promise<void>;
 export {};

package/dist/commands/backup.js

@@ -4,7 +4,7 @@ import { createBackupEnvelope, parsePayload, parseWrappedKey, serializeBackup, }
 import { slugify } from "@getmyenv/shared";
 import { ensureTokenAndLink } from "../lib/bootstrap.js";
 import { writePrivateFile } from "../lib/fs.js";
-/** Encrypted backup of open contexts. Opens offline with the current Vault password. */
+/** Encrypted backup of open contexts. Opens offline with the current Vault password or recovery code. */
 export async function backupCommand(opts) {
     const { client } = await ensureTokenAndLink({ apiUrl: opts.apiUrl });
     const data = await client.request("GET", "/api/cli/backup");
@@ -15,6 +15,9 @@ export async function backupCommand(opts) {
         projectName: data.projectName,
         publicKey: data.publicKey,
         wrappedPrivateKey: parseWrappedKey(JSON.stringify(data.wrappedPrivateKey)),
+        recoveryWrappedKey: data.recoveryWrappedKey
+            ? parseWrappedKey(JSON.stringify(data.recoveryWrappedKey))
+            : null,
         contexts: data.contexts,
         keys: data.keys,
         tags: data.tags,
@@ -29,5 +32,7 @@ export async function backupCommand(opts) {
         path.join(process.cwd(), `${slugify(data.projectName) || "project"}.getmyenv-backup`);
     writePrivateFile(out, serializeBackup(envelope), { overwrite: false });
     console.log(`${pc.green("✓")} Encrypted backup: ${out} (${data.values.length} values, ${data.contexts.length} open contexts)`);
-    console.log(pc.dim("It opens with your current Vault password. Read-only contexts are backed up from the dashboard."));
+    console.log(pc.dim(data.recoveryWrappedKey
+        ? "It opens with your current Vault password or recovery code. Read-only contexts are backed up from the dashboard."
+        : "It opens with your current Vault password. Read-only contexts are backed up from the dashboard."));
 }

package/dist/commands/claim.js

@@ -1,15 +1,14 @@
 import pc from "picocolors";
 import { GUEST_GRACE_DAYS } from "@getmyenv/shared";
-import { createUserKeys, openSealedKey, sealContextKey, unwrapPrivateKey, wipe, } from "@getmyenv/crypto";
+import { openSealedKey, sealContextKey, unwrapPrivateKey, wipe, } from "@getmyenv/crypto";
 import { clearClaimFile, ensureGitignoreHasEnv, promptHidden, readClaimFile, readLine, readProjectMeta, writeClaimFile, writeProjectMeta, } from "../lib/fs.js";
 import { readFolderToken, writeFolderToken } from "../lib/credentials.js";
 import { ApiClient, ApiError, resolveApiUrl } from "../lib/api.js";
 import { authorizeFolder, openBrowser, sleep } from "../lib/authorize.js";
-import { promptNewVaultPassword } from "../lib/guest-key.js";
-async function askNewVaultPassword() {
-    console.error(pc.dim("Choose a Vault password. It stays on this machine. We store an encrypted key blob only.\n"));
+import { createAccountKeys } from "../lib/recovery-code.js";
+async function askNewAccountKeys() {
     try {
-        return await promptNewVaultPassword();
+        return await createAccountKeys();
     }
     catch (err) {
         throw new Error(`${err instanceof Error ? err.message : "Vault password required."} Run claim again.`);
@@ -38,10 +37,10 @@ async function finishClaim(owned, claim) {
     let keys;
     try {
         if (!ownerPublicKey) {
-            const created = await createUserKeys(await askNewVaultPassword());
+            const created = await askNewAccountKeys();
             wipe(created.privateKey);
             ownerPublicKey = created.publicKey;
-            keys = { publicKey: created.publicKey, wrappedPrivateKey: created.wrapped };
+            keys = created.keys;
         }
         const shares = vault.claim.shares.map((s) => {
             const key = openSealedKey(s.sealedKey, guestKey, s.contextId);
@@ -63,7 +62,7 @@ async function finishClaim(owned, claim) {
     }
     clearClaimFile();
     ensureGitignoreHasEnv();
-    console.error(`\n${pc.green("✓")} Claimed ${pc.bold(claim.projectName)}. ${keys ? "Vault password set." : "It opens with your Vault password."}`);
+    console.error(`\n${pc.green("✓")} Claimed ${pc.bold(claim.projectName)}. ${keys ? "Vault password and recovery code set." : "It opens with your Vault password."}`);
     console.error(pc.dim("claim.json was removed. Read-only contexts like Production are now available in the dashboard.\n"));
 }
 /** A signed-in folder token for the claimed project: reuse this folder's, or sign in. */

package/dist/commands/restore.d.ts

@@ -5,7 +5,7 @@ type RestoreOpts = {
 };
 /**
  * Restore a backup into this folder's project. The backup opens locally with
- * the Vault password it was made with. Values are encrypted again with this
+ * the Vault password or recovery code it was made with. Values are encrypted again with this
  * project's context keys. Read-only and unknown contexts are skipped.
  */
 export declare function restoreCommand(file: string, opts: RestoreOpts): Promise<void>;

package/dist/commands/restore.js

@@ -5,10 +5,10 @@ import { ensureTokenAndLink } from "../lib/bootstrap.js";
 import { findContext } from "../lib/context.js";
 import { promptConfirm } from "../lib/fs.js";
 import { resolveVaultPassword } from "../lib/guest-key.js";
-import { contextKey } from "../lib/vault.js";
+import { writeKey } from "../lib/vault.js";
 /**
  * Restore a backup into this folder's project. The backup opens locally with
- * the Vault password it was made with. Values are encrypted again with this
+ * the Vault password or recovery code it was made with. Values are encrypted again with this
  * project's context keys. Read-only and unknown contexts are skipped.
  */
 export async function restoreCommand(file, opts) {
@@ -32,16 +32,23 @@ export async function restoreCommand(file, opts) {
     if (who.token.kind !== "folder") {
         throw new Error("Restore needs a signed-in folder token. Guest and server tokens cannot restore.");
     }
-    const password = await resolveVaultPassword({
+    const secret = await resolveVaultPassword({
         isGuest: false,
-        prompt: "Vault password for this backup (hidden): ",
+        prompt: envelope.recoveryWrappedKey
+            ? "Vault password or recovery code for this backup (hidden): "
+            : "Vault password for this backup (hidden): ",
     });
     let opened;
     try {
-        opened = await restoreValuesFromBackup(password, envelope);
+        opened = await restoreValuesFromBackup(secret, envelope);
     }
-    catch {
-        throw new Error("Could not open the backup. Check the Vault password.");
+    catch (err) {
+        const msg = err instanceof Error ? err.message : "";
+        if (/^(That recovery code|This backup|A recovery code)/.test(msg))
+            throw new Error(msg);
+        throw new Error(envelope.recoveryWrappedKey
+            ? "Could not open the backup. Check the Vault password or recovery code."
+            : "Could not open the backup. Check the Vault password.");
     }
     console.error(`Backup checked: ${opened.values.length} values in ${envelope.contexts.length} contexts.\n`);
     const targets = new Map();
@@ -73,11 +80,13 @@ export async function restoreCommand(file, opts) {
         }
     }
     const values = [];
+    const keyVersions = {};
     for (const v of opened.values) {
         if (!writable(v.context))
             continue;
         const target = targets.get(v.context);
-        const key = await contextKey(linked, target, { create: true });
+        const { key, keyVersion } = await writeKey(linked, target);
+        keyVersions[v.context] = keyVersion;
         values.push({
             key: v.key,
             context: v.context,
@@ -89,6 +98,7 @@ export async function restoreCommand(file, opts) {
         keys: envelope.keys,
         tags: envelope.tags ?? {},
         values,
+        keyVersions,
     });
     const skipped = [...perContext.keys()].filter((slug) => !writable(slug));
     console.log(`${pc.green("✓")} Restored ${res.restored} values into ${res.projectName}`);

package/dist/lib/recovery-code.d.ts

@@ -0,0 +1,19 @@
+import { type WrappedPrivateKey } from "@getmyenv/crypto";
+export declare const NO_TTY_FOR_VAULT = "No terminal to set a Vault password. Set it in the dashboard, Settings, or run this command in a terminal.";
+export type NewAccountKeys = {
+    publicKey: string;
+    /** Caller wipes it. */
+    privateKey: Uint8Array;
+    keys: {
+        publicKey: string;
+        wrappedPrivateKey: WrappedPrivateKey;
+        recoveryWrappedKey: WrappedPrivateKey;
+    };
+};
+/** The user types the code back. Nothing is saved until it matches. */
+export declare function confirmRecoveryCode(code: string, ask?: (question: string) => Promise<string>): Promise<void>;
+/**
+ * New account keys: a Vault password typed twice, then a recovery code shown
+ * once and typed back. Needs a terminal. Checks both wraps open the same key.
+ */
+export declare function createAccountKeys(): Promise<NewAccountKeys>;

package/dist/lib/recovery-code.js

@@ -0,0 +1,57 @@
+import pc from "picocolors";
+import { assertRecoveryWrap, createRecoveryWrap, createUserKeys, formatRecoveryCode, recoveryCodesMatch, wipe, } from "@getmyenv/crypto";
+import { FACTS } from "@getmyenv/shared";
+import { readLine } from "./fs.js";
+import { promptNewVaultPassword } from "./guest-key.js";
+export const NO_TTY_FOR_VAULT = "No terminal to set a Vault password. Set it in the dashboard, Settings, or run this command in a terminal.";
+const TYPE_BACK_ATTEMPTS = 3;
+function printRecoveryCode(code) {
+    const shown = formatRecoveryCode(code);
+    const width = shown.length + 4;
+    console.error("");
+    console.error(pc.bold("Your recovery code"));
+    console.error(`┌${"─".repeat(width)}┐`);
+    console.error(`│  ${pc.bold(shown)}  │`);
+    console.error(`└${"─".repeat(width)}┘`);
+    console.error(pc.dim(`${FACTS.recoveryCode} Write it down or save it in a password manager.\n`));
+}
+/** The user types the code back. Nothing is saved until it matches. */
+export async function confirmRecoveryCode(code, ask = readLine) {
+    for (let attempt = 1; attempt <= TYPE_BACK_ATTEMPTS; attempt++) {
+        const typed = await ask("Type the recovery code to confirm: ");
+        if (recoveryCodesMatch(code, typed))
+            return;
+        if (attempt < TYPE_BACK_ATTEMPTS)
+            console.error(pc.red("That does not match. Try again.\n"));
+    }
+    throw new Error("The recovery code did not match. Nothing was saved. Run the command again.");
+}
+/**
+ * New account keys: a Vault password typed twice, then a recovery code shown
+ * once and typed back. Needs a terminal. Checks both wraps open the same key.
+ */
+export async function createAccountKeys() {
+    if (!process.stdin.isTTY)
+        throw new Error(NO_TTY_FOR_VAULT);
+    console.error(pc.dim("Choose a Vault password. It stays on this machine. We store an encrypted key blob only.\n"));
+    const created = await createUserKeys(await promptNewVaultPassword());
+    try {
+        const recovery = await createRecoveryWrap(created.privateKey);
+        printRecoveryCode(recovery.code);
+        await confirmRecoveryCode(recovery.code);
+        await assertRecoveryWrap(recovery.code, recovery.wrapped, created.publicKey);
+        return {
+            publicKey: created.publicKey,
+            privateKey: created.privateKey,
+            keys: {
+                publicKey: created.publicKey,
+                wrappedPrivateKey: created.wrapped,
+                recoveryWrappedKey: recovery.wrapped,
+            },
+        };
+    }
+    catch (err) {
+        wipe(created.privateKey);
+        throw err;
+    }
+}

package/dist/lib/upload.js

@@ -1,7 +1,7 @@
 import { encryptSecret, serializePayload } from "@getmyenv/crypto";
 import { FACTS } from "@getmyenv/shared";
 import { ApiError } from "./api.js";
-import { contextKey } from "./vault.js";
+import { writeKey } from "./vault.js";
 /** Fail fast before prompting or encrypting. Mirrors the server's `checkWrite`, which still enforces it. */
 export function assertWritable(linked, ctx) {
     if (linked.who.token.kind === "server") {
@@ -23,17 +23,20 @@ export async function uploadValues(input) {
         .filter(([, v]) => v === "")
         .map(([k]) => k);
     let values = [];
+    let keyVersion;
     if (filled.length > 0) {
-        const key = await contextKey(linked, context, { create: true });
+        const write = await writeKey(linked, context);
+        keyVersion = write.keyVersion;
         values = filled.map(([name, value]) => ({
             name,
-            ciphertext: serializePayload(encryptSecret(key, name, value)),
+            ciphertext: serializePayload(encryptSecret(write.key, name, value)),
             ...(input.expiresAt !== undefined ? { expiresAt: input.expiresAt } : {}),
         }));
     }
     const body = {
         context: context.slug,
         values,
+        ...(keyVersion !== undefined ? { keyVersion } : {}),
         ...(input.prune ? { prune: true } : {}),
         ...(declare.length > 0 ? { declare } : {}),
     };

package/dist/lib/vault.d.ts

@@ -18,6 +18,8 @@ export type VaultContext = {
     protection: Protection;
     hasKey: boolean;
     sealedKey: SealedKey | null;
+    /** Version of the key in sealedKey. Sent back with every write. */
+    keyVersion: number;
 };
 export type VaultInfo = {
     holder: "user" | "guest" | "token";
@@ -45,6 +47,15 @@ export type KeyOpts = {
     create?: boolean;
 };
 export declare function fetchVault(linked: Linked): Promise<VaultInfo>;
+/**
+ * The context key and its version, for a write. The server refuses ciphertext
+ * written with a key that was replaced since, so the version comes from the
+ * same vault response as the sealed key.
+ */
+export declare function writeKey(linked: Linked, target: KeyTarget): Promise<{
+    key: Uint8Array;
+    keyVersion: number;
+}>;
 /** The context key, unlocking with the Vault password when needed. */
 export declare function contextKey(linked: Linked, target: KeyTarget, opts?: KeyOpts): Promise<Uint8Array>;
 /** Unlock with the Vault password and return the private key. Caller wipes it. */

package/dist/lib/vault.js

@@ -4,11 +4,28 @@ import { VAULT_UNLOCK_DURATION } from "@getmyenv/shared";
 import { ApiError } from "./api.js";
 import { resolveVaultPassword } from "./guest-key.js";
 import { keychainAccount, keychainEnabled, readCachedContextKey, storeCachedContextKeys, } from "./keychain.js";
+import { createAccountKeys } from "./recovery-code.js";
 /** One unlock per process: several contexts in one command prompt once. */
 const memo = new Map();
+/** Key version of each memo entry opened from the vault response. Keys from the keychain have none. */
+const versions = new Map();
 export function fetchVault(linked) {
     return linked.client.request("GET", "/api/cli/vault");
 }
+/**
+ * The context key and its version, for a write. The server refuses ciphertext
+ * written with a key that was replaced since, so the version comes from the
+ * same vault response as the sealed key.
+ */
+export async function writeKey(linked, target) {
+    if (!versions.has(target.id))
+        memo.delete(target.id);
+    const key = await contextKey(linked, { ...target, sealedKey: undefined }, { create: true });
+    const keyVersion = versions.get(target.id);
+    if (keyVersion === undefined)
+        throw new Error(`No key version for ${target.slug}. Run the command again.`);
+    return { key, keyVersion };
+}
 /** The context key, unlocking with the Vault password when needed. */
 export async function contextKey(linked, target, opts = {}) {
     const cached = memo.get(target.id);
@@ -45,10 +62,14 @@ export async function contextKey(linked, target, opts = {}) {
         if (!key) {
             throw new Error(member
                 ? `Waiting for the owner to send the key for ${target.slug}. It arrives the next time they unlock the vault in the dashboard.`
-                : `No key for ${target.slug} on this account. Open the project in the dashboard once.`);
+                : `This account has no key for ${target.slug}. If you reset your vault, reset ${target.slug} in the dashboard to set new values.`);
         }
         for (const [id, k] of opened)
             memo.set(id, k);
+        for (const c of vault.contexts) {
+            if (opened.has(c.id))
+                versions.set(c.id, c.keyVersion);
+        }
         if (account)
             await remember(account, vault, opened);
         return key;
@@ -109,6 +130,7 @@ async function initContextKey(linked, vault, ctx) {
     const key = generateContextKey();
     try {
         await linked.client.request("POST", "/api/cli/vault", {
+            publicKey: vault.publicKey,
             shares: [{ contextId: ctx.id, sealedKey: sealContextKey(key, vault.publicKey, ctx.id) }],
         });
     }
@@ -131,22 +153,16 @@ async function holderPrivateKey(linked, vault, opts) {
         if (!opts.create) {
             throw new Error("No Vault password yet. Set it in the dashboard, or set a value: npx getmyenv set KEY");
         }
-        if (!isGuest) {
-            console.error(pc.dim("Choose a Vault password. It stays on this machine. We store an encrypted key blob only.\n"));
-        }
-        const password = await resolveVaultPassword({ isGuest, create: true });
-        const created = await createUserKeys(password);
+        const created = isGuest ? await createGuestKeys() : await createAccountKeys();
         try {
-            await linked.client.request("POST", "/api/cli/vault", {
-                keys: { publicKey: created.publicKey, wrappedPrivateKey: created.wrapped },
-            });
+            await linked.client.request("POST", "/api/cli/vault", { keys: created.keys });
         }
         catch (err) {
             wipe(created.privateKey);
             throw err;
         }
         vault.publicKey = created.publicKey;
-        vault.wrappedPrivateKey = created.wrapped;
+        vault.wrappedPrivateKey = created.keys.wrappedPrivateKey;
         return created.privateKey;
     }
     const interactive = process.stdin.isTTY && !isGuest;
@@ -164,10 +180,19 @@ async function holderPrivateKey(linked, vault, opts) {
                 console.error(pc.red("Wrong Vault password. Try again.\n"));
                 continue;
             }
-            throw new Error("Could not unlock. Check your Vault password.");
+            throw new Error("Could not unlock. Check your Vault password. Forgot it? Use your recovery code in the dashboard, Settings.");
         }
     }
 }
+/** Guest keys wrap with the claim.json passphrase. No recovery code. */
+async function createGuestKeys() {
+    const created = await createUserKeys(await resolveVaultPassword({ isGuest: true, create: true }));
+    return {
+        publicKey: created.publicKey,
+        privateKey: created.privateKey,
+        keys: { publicKey: created.publicKey, wrappedPrivateKey: created.wrapped },
+    };
+}
 /** Unlock with the Vault password and return the private key. Caller wipes it. */
 export async function unlockPrivateKey(linked, opts = {}) {
     const vault = await fetchVault(linked);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "getmyenv",
-  "version": "0.9.8",
+  "version": "0.10.0",
   "description": "CLI for getmyenv, an encrypted store for environment variables and secrets. We store ciphertext only.",
   "type": "module",
   "bin": {
@@ -33,8 +33,8 @@
     "access": "public"
   },
   "dependencies": {
-    "@getmyenv/crypto": "0.4.1",
-    "@getmyenv/shared": "0.8.4",
+    "@getmyenv/crypto": "0.5.0",
+    "@getmyenv/shared": "0.9.0",
     "@napi-rs/keyring": "^2.1.0",
     "commander": "^15.0.0",
     "dotenv": "^16.4.7",