@ldgr/cli 0.1.1 → 0.2.1

package/README.md

@@ -1,11 +1,12 @@
 # @ldgr/cli
 
-LDGR's self-custody terminal wallet. Version 0.1.0 creates or imports encrypted local wallets, lets you select between them, shows addresses and balances, sends native LDGR or a token, and persistently switches the selected wallet between mainnet and testnet.
+LDGR's self-custody terminal wallet. Version 0.2.0 creates or imports local wallets, lets you select between them, shows addresses and balances, sends native LDGR or a token, and persistently switches the selected wallet between mainnet and testnet.
 
 ```bash
 npm install -g @ldgr/cli
 ldgr wallet create
-ldgr wallet import
+ldgr wallet import ~/Downloads/ldgr-recovery-key.txt
+ldgr wallet export ~/Desktop/ldgr-recovery-key.txt
 ldgr wallet list
 ldgr wallet select 2
 ldgr address
@@ -15,4 +16,4 @@ ldgr send-token t1abcdef01234567 ldgr1… 10
 ldgr network set testnet
 ```
 
-The default owner-only wallet store lives at `~/.config/ldgr/wallet.json`. Each added wallet is encrypted separately using a passphrase requested on the terminal. `wallet list` shows one-based indexes and marks the active wallet; `wallet select <index>` changes it without exposing a secret. Record the recovery key shown at creation offline. `wallet import --testnet` imports a recovery key as a testnet wallet. Testnet prints a warning on every wallet command and only uses `https://tst.ldgr.ltd`.
+The default owner-only wallet store lives at `~/.ldgr/wallet.json`. On first use, an existing `~/.config/ldgr/wallet.json` store is validated, copied to the new owner-only location, and removed from its former location. At creation/import you can choose passphrase protection or an **unprotected** wallet, which follows the extension model and relies only on the local file's permissions. `wallet list` shows one-based indexes and marks the active wallet; `wallet select <index>` changes it without exposing a secret. `wallet export <path>` writes a `0600` `ldgr-recovery-key.txt` file containing the raw recovery-key value accepted by the extension; `wallet import <path>` reads the same file. Testnet prints a warning on every wallet command and only uses `https://tst.ldgr.ltd`.

package/dist/cli.js

@@ -8,6 +8,7 @@ import {
   nativeAssetDefinitionForLedger,
   resolvePublicAssetCode
 } from "@ldgr/protocol";
+import { readFile as readFile2 } from "node:fs/promises";
 
 // src/transfer.ts
 import {
@@ -49,7 +50,7 @@ async function buildTransferSubmission(input) {
 
 // src/wallet-file.ts
 import { generateLocalWallet, loadLocalWallet } from "@ldgr/client";
-import { canonicalizeLedgerAddress as canonicalizeLedgerAddress2 } from "@ldgr/protocol";
+import { canonicalizeLedgerAddress as canonicalizeLedgerAddress2, decodeEd25519RecoveryKey } from "@ldgr/protocol";
 import { lstat, mkdir, open, readFile, rename, unlink } from "node:fs/promises";
 import { dirname, join } from "node:path";
 var KDF_ITERATIONS = 310000;
@@ -82,11 +83,21 @@ function parseWalletEntry(value) {
   if (!value || typeof value !== "object" || Array.isArray(value))
     throw new TypeError("Wallet file is not a JSON object");
   const file = value;
-  if (file.format !== "ldgr-cli-wallet" || file.version !== 1 || file.network !== "mainnet" && file.network !== "testnet" || file.ledgerId !== 0 && file.ledgerId !== 1 || typeof file.address !== "string" || typeof file.publicKey !== "string" || typeof file.ciphertext !== "string" || typeof file.iv !== "string" || !file.kdf || file.kdf.name !== "PBKDF2" || file.kdf.hash !== "SHA-256" || file.kdf.iterations !== KDF_ITERATIONS || typeof file.kdf.salt !== "string")
+  if (file.format !== "ldgr-cli-wallet" || file.version !== 1 || file.network !== "mainnet" && file.network !== "testnet" || file.ledgerId !== 0 && file.ledgerId !== 1 || typeof file.address !== "string" || typeof file.publicKey !== "string")
     throw new TypeError("Unsupported wallet file format");
   if (file.network !== networkForLedger(file.ledgerId))
     throw new TypeError("Wallet file network does not match ledgerId");
   canonicalizeLedgerAddress2(file.address, file.ledgerId);
+  if (file.protection === "none") {
+    if (typeof file.recoveryKey !== "string")
+      throw new TypeError("Unsupported wallet file format");
+    decodeEd25519RecoveryKey(file.recoveryKey);
+    return file;
+  }
+  if (file.protection !== undefined && file.protection !== "passphrase")
+    throw new TypeError("Unsupported wallet file format");
+  if (typeof file.ciphertext !== "string" || typeof file.iv !== "string" || !file.kdf || file.kdf.name !== "PBKDF2" || file.kdf.hash !== "SHA-256" || file.kdf.iterations !== KDF_ITERATIONS || typeof file.kdf.salt !== "string")
+    throw new TypeError("Unsupported wallet file format");
   return file;
 }
 function parseWalletStore(value) {
@@ -118,13 +129,35 @@ function defaultWalletPath(input = {}) {
   const home = input.home ?? process.env.HOME;
   if (!home)
     throw new Error("Could not determine your home directory; use --wallet <path>");
-  const configHome = process.env.XDG_CONFIG_HOME?.trim() || join(home, ".config");
+  return join(home, ".ldgr", "wallet.json");
+}
+function legacyDefaultWalletPath(input = {}) {
+  const home = input.home ?? process.env.HOME;
+  if (!home)
+    throw new Error("Could not determine your home directory; use --wallet <path>");
+  const configHome = input.configHome ?? (process.env.XDG_CONFIG_HOME?.trim() || join(home, ".config"));
   return join(configHome, "ldgr", "wallet.json");
 }
 async function createEncryptedWalletFile(input) {
   const wallet = await generateLocalWallet({ ledgerId: input.ledgerId });
+  if (input.passphrase === undefined)
+    return createUnprotectedWallet({ wallet, recoveryKey: wallet.recoveryKey });
   return encryptWallet({ wallet, recoveryKey: wallet.recoveryKey, passphrase: input.passphrase });
 }
+function createUnprotectedWallet(input) {
+  const file = {
+    format: "ldgr-cli-wallet",
+    version: 1,
+    protection: "none",
+    network: networkForLedger(input.wallet.ledgerId),
+    ledgerId: input.wallet.ledgerId,
+    address: input.wallet.address,
+    publicKey: input.wallet.publicKey,
+    recoveryKey: input.recoveryKey
+  };
+  return { file, serialized: `${JSON.stringify(file, null, 2)}
+`, recoveryKey: input.recoveryKey };
+}
 async function encryptWallet(input) {
   const salt = crypto.getRandomValues(new Uint8Array(16));
   const iv = crypto.getRandomValues(new Uint8Array(12));
@@ -146,7 +179,7 @@ async function encryptWallet(input) {
   return { file, serialized: `${JSON.stringify(file, null, 2)}
 `, recoveryKey: input.recoveryKey };
 }
-async function writeNewWalletFile(path, file) {
+async function writeNewWalletStore(path, store) {
   await mkdir(dirname(path), { recursive: true, mode: 448 });
   const handle = await open(path, "wx", 384).catch((error) => {
     if (error.code === "EEXIST")
@@ -154,12 +187,15 @@ async function writeNewWalletFile(path, file) {
     throw error;
   });
   try {
-    await handle.writeFile(serializeWalletStore(newWalletStore(file)), "utf8");
+    await handle.writeFile(serializeWalletStore(store), "utf8");
     await handle.sync();
   } finally {
     await handle.close();
   }
 }
+async function writeNewWalletFile(path, file) {
+  await writeNewWalletStore(path, newWalletStore(file));
+}
 async function readWalletStore(path) {
   const details = await lstat(path).catch((error) => {
     if (error.code === "ENOENT")
@@ -178,7 +214,43 @@ async function readWalletStore(path) {
   }
   return parseWalletStore(parsed);
 }
+async function migrateDefaultWalletPath(input = {}) {
+  const path = defaultWalletPath(input);
+  try {
+    await lstat(path);
+    return { path, migrated: false };
+  } catch (error) {
+    if (error.code !== "ENOENT")
+      throw error;
+  }
+  const legacyPath = legacyDefaultWalletPath(input);
+  let legacyStore;
+  try {
+    legacyStore = await readWalletStore(legacyPath);
+  } catch (error) {
+    if (error instanceof Error && error.message === `Wallet file not found: ${legacyPath}`)
+      return { path, migrated: false };
+    throw error;
+  }
+  await writeNewWalletStore(path, legacyStore);
+  try {
+    await unlink(legacyPath);
+  } catch (error) {
+    throw new Error(`Migrated wallet to ${path}, but could not remove legacy wallet file ${legacyPath}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return { path, migrated: true };
+}
+async function walletFromRecoveryKey(file, recoveryKey) {
+  const wallet = await loadLocalWallet({ recoveryKey, ledgerId: file.ledgerId });
+  if (wallet.address !== file.address || wallet.publicKey !== file.publicKey)
+    throw new Error("wallet identity mismatch");
+  return { wallet, recoveryKey };
+}
 async function unlockWalletFile(file, passphrase) {
+  if (file.protection === "none")
+    return walletFromRecoveryKey(file, file.recoveryKey);
+  if (passphrase === undefined)
+    throw new Error("This wallet requires a passphrase");
   try {
     const key = await deriveEncryptionKey(passphrase, decodeBase64Url(file.kdf.salt));
     const plaintext = new Uint8Array(await crypto.subtle.decrypt({ name: AES_GCM, iv: arrayBuffer(decodeBase64Url(file.iv)) }, key, arrayBuffer(decodeBase64Url(file.ciphertext))));
@@ -186,10 +258,7 @@ async function unlockWalletFile(file, passphrase) {
     plaintext.fill(0);
     if (typeof value.recoveryKey !== "string")
       throw new Error("missing recovery key");
-    const wallet = await loadLocalWallet({ recoveryKey: value.recoveryKey, ledgerId: file.ledgerId });
-    if (wallet.address !== file.address || wallet.publicKey !== file.publicKey)
-      throw new Error("wallet identity mismatch");
-    return { wallet, recoveryKey: value.recoveryKey };
+    return await walletFromRecoveryKey(file, value.recoveryKey);
   } catch {
     throw new Error("Could not unlock wallet: check your passphrase or wallet file");
   }
@@ -199,6 +268,22 @@ async function readEncryptedWalletFile(path, passphrase) {
   const file = store.wallets[store.activeWalletIndex];
   return (await unlockWalletFile(file, passphrase)).wallet;
 }
+async function exportRecoveryKeyFile(input) {
+  const store = await readWalletStore(input.walletPath);
+  const unlocked = await unlockWalletFile(store.wallets[store.activeWalletIndex], input.passphrase);
+  await mkdir(dirname(input.backupPath), { recursive: true, mode: 448 });
+  const handle = await open(input.backupPath, "wx", 384).catch((error) => {
+    if (error.code === "EEXIST")
+      throw new Error(`Recovery-key file already exists: ${input.backupPath}`);
+    throw error;
+  });
+  try {
+    await handle.writeFile(unlocked.recoveryKey, "utf8");
+    await handle.sync();
+  } finally {
+    await handle.close();
+  }
+}
 async function replaceWalletStore(path, store) {
   await readWalletStore(path);
   const temporaryPath = join(dirname(path), `.${crypto.randomUUID()}.wallet.tmp`);
@@ -238,8 +323,8 @@ async function addWalletFile(path, file) {
 }
 async function importEncryptedWalletFile(input) {
   const wallet = await loadLocalWallet({ recoveryKey: input.recoveryKey, ledgerId: input.ledgerId });
-  const encrypted = await encryptWallet({ wallet, recoveryKey: input.recoveryKey, passphrase: input.passphrase });
-  return { file: encrypted.file, index: await addWalletFile(input.path, encrypted.file) };
+  const created = input.passphrase === undefined ? createUnprotectedWallet({ wallet, recoveryKey: input.recoveryKey }) : await encryptWallet({ wallet, recoveryKey: input.recoveryKey, passphrase: input.passphrase });
+  return { file: created.file, index: await addWalletFile(input.path, created.file) };
 }
 async function listWalletFileMetadata(path) {
   const store = await readWalletStore(path);
@@ -261,14 +346,14 @@ async function switchWalletNetwork(path, passphrase, ledgerId) {
     return existing;
   const unlocked = await unlockWalletFile(existing, passphrase);
   const wallet = await loadLocalWallet({ recoveryKey: unlocked.recoveryKey, ledgerId });
-  const encrypted = await encryptWallet({ wallet, recoveryKey: unlocked.recoveryKey, passphrase });
+  const updated = existing.protection === "none" ? createUnprotectedWallet({ wallet, recoveryKey: unlocked.recoveryKey }) : await encryptWallet({ wallet, recoveryKey: unlocked.recoveryKey, passphrase });
   if (store.wallets.some((entry, index) => index !== store.activeWalletIndex && entry.ledgerId === ledgerId && entry.publicKey === wallet.publicKey)) {
     throw new Error("This recovery key already has a wallet in the selected network; select that wallet instead");
   }
   const wallets = [...store.wallets];
-  wallets[store.activeWalletIndex] = encrypted.file;
+  wallets[store.activeWalletIndex] = updated.file;
   await replaceWalletStore(path, { ...store, wallets });
-  return encrypted.file;
+  return updated.file;
 }
 async function walletFileMetadata(path) {
   const store = await readWalletStore(path);
@@ -277,11 +362,12 @@ async function walletFileMetadata(path) {
 
 // src/cli.ts
 var HELP = `
-LDGR CLI 0.1.1 — self-custody wallet
+LDGR CLI 0.2.1 — self-custody wallet
 
 Usage:
   ldgr wallet create [--testnet] [--wallet <path>]
-  ldgr wallet import [--testnet] [--wallet <path>]
+  ldgr wallet import [recovery-key-file] [--testnet] [--wallet <path>]
+  ldgr wallet export <recovery-key-file> [--wallet <path>]
   ldgr wallet list [--wallet <path>]
   ldgr wallet select <index> [--wallet <path>]
   ldgr address [--wallet <path>]
@@ -291,16 +377,17 @@ Usage:
   ldgr network show [--wallet <path>]
   ldgr network set <mainnet|testnet> [--wallet <path>]
 
-The default wallet store is ~/.config/ldgr/wallet.json. Each wallet inside it
-is independently encrypted with a passphrase you enter through the terminal;
-the CLI never accepts recovery keys or passphrases as arguments or environment
-variables. Use \`ldgr wallet select <index>\` to change the active wallet, or
-\`ldgr network set testnet\` to switch its network persistently. Testnet mode
-prints a warning on every wallet command.
+The default wallet store is ~/.ldgr/wallet.json. Existing wallets at
+~/.config/ldgr/wallet.json move there safely on first use. A wallet can be
+passphrase-protected or unprotected (local-file permissions only). The CLI
+never accepts recovery-key values or passphrases as arguments or environment
+variables. Use \`ldgr wallet export <path>\` for an extension-compatible
+recovery-key file. Testnet mode prints a warning on every wallet command.
 `;
 function parseArguments(argv) {
   const command = [];
   let walletPath = defaultWalletPath();
+  let walletPathExplicit = false;
   let walletOnTestnet = false;
   for (let index = 0;index < argv.length; index += 1) {
     const value = argv[index];
@@ -309,6 +396,7 @@ function parseArguments(argv) {
       if (!path || path.startsWith("-"))
         throw new TypeError("--wallet requires a file path");
       walletPath = path;
+      walletPathExplicit = true;
       index += 1;
     } else if (value === "--testnet") {
       walletOnTestnet = true;
@@ -321,7 +409,7 @@ function parseArguments(argv) {
   if (walletOnTestnet && !(command[0] === "wallet" && (command[1] === "create" || command[1] === "import"))) {
     throw new TypeError("--testnet is only used with wallet create or wallet import; use `ldgr network set testnet` to switch an existing wallet");
   }
-  return { command, walletPath, walletOnTestnet };
+  return { command, walletPath, walletPathExplicit, walletOnTestnet };
 }
 function networkLabel(file) {
   return file.ledgerId === 0 ? "testnet" : "mainnet";
@@ -342,6 +430,23 @@ async function askPassphrase(message) {
     throw new Error("Cancelled");
   return answer;
 }
+async function chooseWalletPassphrase() {
+  const protectedWallet = await p.confirm({ message: "Protect this wallet with a passphrase?", initialValue: true });
+  if (p.isCancel(protectedWallet))
+    throw new Error("Cancelled");
+  if (!protectedWallet) {
+    p.log.warn("This wallet will be unprotected. Anyone who can read its owner-only local file can spend its funds.");
+    return;
+  }
+  const passphrase = await askPassphrase("Choose a wallet passphrase");
+  const confirmation = await askPassphrase("Repeat the wallet passphrase");
+  if (passphrase !== confirmation)
+    throw new Error("Passphrases did not match");
+  return passphrase;
+}
+async function signingPassphrase(file, message) {
+  return file.protection === "none" ? undefined : askPassphrase(message);
+}
 async function confirm2(message) {
   const answer = await p.confirm({ message, initialValue: false });
   if (p.isCancel(answer) || !answer)
@@ -374,39 +479,34 @@ async function runCreate(path, testnet) {
   const ledgerId = testnet ? 0 : 1;
   if (ledgerId === 0)
     showNetworkWarning({ ledgerId });
-  const passphrase = await askPassphrase("Choose a wallet passphrase");
-  const confirmation = await askPassphrase("Repeat the wallet passphrase");
-  if (passphrase !== confirmation)
-    throw new Error("Passphrases did not match");
+  const passphrase = await chooseWalletPassphrase();
   const spinner2 = p.spinner();
-  spinner2.start("Generating and encrypting your wallet");
+  spinner2.start("Generating your wallet");
   const created = await createEncryptedWalletFile({ ledgerId, passphrase });
   const index = await addWalletFile(path, created.file);
-  spinner2.stop("Encrypted wallet added");
+  spinner2.stop(passphrase === undefined ? "Unprotected wallet added" : "Protected wallet added");
   p.note(`Address
 ${created.file.address}
 
 Recovery key — save this offline now; it will not be shown again
 ${created.recoveryKey}`, "Your self-custody backup");
-  p.log.warn("This recovery key alone can restore and control this wallet. Your passphrase protects only this local file; never share either secret.");
+  p.log.warn("This recovery key alone can restore and control this wallet. Export it as a file with `ldgr wallet export <path>` and keep it offline.");
   p.outro(`Wallet #${index + 1} selected in ${path}`);
 }
-async function runImport(path, testnet) {
+async function runImport(path, testnet, recoveryKeyPath) {
   const ledgerId = testnet ? 0 : 1;
   if (ledgerId === 0)
     showNetworkWarning({ ledgerId });
-  const recoveryKey = await p.password({
+  const enteredRecoveryKey = recoveryKeyPath === undefined ? await p.password({
     message: "Enter the recovery key to import",
     validate(value) {
       return value.trim() ? undefined : "Enter a recovery key";
     }
-  });
-  if (p.isCancel(recoveryKey))
+  }) : (await readFile2(recoveryKeyPath, "utf8")).trim();
+  if (p.isCancel(enteredRecoveryKey) || !enteredRecoveryKey)
     throw new Error("Cancelled");
-  const passphrase = await askPassphrase("Choose a passphrase for this imported wallet");
-  const confirmation = await askPassphrase("Repeat the wallet passphrase");
-  if (passphrase !== confirmation)
-    throw new Error("Passphrases did not match");
+  const recoveryKey = enteredRecoveryKey;
+  const passphrase = await chooseWalletPassphrase();
   const spinner2 = p.spinner();
   spinner2.start("Validating and encrypting imported wallet");
   const imported = await importEncryptedWalletFile({ path, recoveryKey, ledgerId, passphrase });
@@ -420,12 +520,20 @@ ${networkLabel(imported.file)}`, `Wallet #${imported.index + 1} selected`);
     showNetworkWarning(imported.file);
   p.outro(`Wallet #${imported.index + 1} added to ${path}`);
 }
+async function runExport(path, backupPath) {
+  const file = await walletFileMetadata(path);
+  showNetworkWarning(file);
+  const passphrase = await signingPassphrase(file, "Enter your wallet passphrase to export");
+  await exportRecoveryKeyFile({ walletPath: path, backupPath, passphrase });
+  p.log.warn("Anyone with this recovery-key file can control the wallet. Keep it offline and never share it.");
+  p.outro(`Recovery-key file saved at ${backupPath}`);
+}
 async function runWalletList(path) {
   const wallets = await listWalletFileMetadata(path);
   const selected = wallets.find((wallet) => wallet.selected);
   showNetworkWarning(selected);
   const rows = wallets.map((wallet) => [
-    `${wallet.selected ? "● Selected" : "○"}  #${wallet.index + 1} · ${networkLabel(wallet)}`,
+    `${wallet.selected ? "● Selected" : "○"}  #${wallet.index + 1} · ${networkLabel(wallet)} · ${wallet.protection === "none" ? "Unprotected" : "Protected"}`,
     wallet.address
   ].join(`
 `));
@@ -477,7 +585,7 @@ async function runSend(path, rawAsset, recipient, amount) {
   const client = await selectedClient(file);
   const asset = resolvePublicAssetCode(rawAsset, file.ledgerId);
   const definition = await definitionForAsset(client, asset, file.ledgerId);
-  const passphrase = await askPassphrase("Enter your wallet passphrase to sign");
+  const passphrase = await signingPassphrase(file, "Enter your wallet passphrase to sign");
   const wallet = await readEncryptedWalletFile(path, passphrase);
   const makeSubmission = async () => buildTransferSubmission({
     wallet,
@@ -535,7 +643,7 @@ ${file.address}`, "Selected network");
   if (ledgerId === 0)
     showNetworkWarning({ ledgerId });
   p.log.info("Switching networks derives a different address from the same self-custody key.");
-  const passphrase = await askPassphrase("Enter your wallet passphrase to switch networks");
+  const passphrase = await signingPassphrase(file, "Enter your wallet passphrase to switch networks");
   await confirm2(`Switch this wallet to ${target}?`);
   const spinner2 = p.spinner();
   spinner2.start("Re-encrypting wallet for the selected network");
@@ -561,26 +669,31 @@ async function main() {
   }
   p.intro("LDGR CLI");
   try {
+    const resolved = parsed.walletPathExplicit ? { path: parsed.walletPath, migrated: false } : await migrateDefaultWalletPath();
+    if (resolved.migrated)
+      p.log.info(`Moved legacy wallet store to ${resolved.path}`);
     if (first === "wallet" && second === "create" && third === undefined)
-      await runCreate(parsed.walletPath, parsed.walletOnTestnet);
-    else if (first === "wallet" && second === "import" && third === undefined)
-      await runImport(parsed.walletPath, parsed.walletOnTestnet);
+      await runCreate(resolved.path, parsed.walletOnTestnet);
+    else if (first === "wallet" && second === "import" && fourth === undefined)
+      await runImport(resolved.path, parsed.walletOnTestnet, third);
+    else if (first === "wallet" && second === "export" && third && fourth === undefined)
+      await runExport(resolved.path, third);
     else if (first === "wallet" && second === "list" && third === undefined)
-      await runWalletList(parsed.walletPath);
+      await runWalletList(resolved.path);
     else if (first === "wallet" && second === "select" && third && fourth === undefined)
-      await runWalletSelect(parsed.walletPath, third);
+      await runWalletSelect(resolved.path, third);
     else if (first === "address" && second === undefined)
-      await runAddress(parsed.walletPath);
+      await runAddress(resolved.path);
     else if (first === "balance" && second === undefined)
-      await runBalance(parsed.walletPath);
+      await runBalance(resolved.path);
     else if (first === "send" && second && third && fourth === undefined)
-      await runSend(parsed.walletPath, "dng", second, third);
+      await runSend(resolved.path, "dng", second, third);
     else if (first === "send-token" && second && third && fourth)
-      await runSend(parsed.walletPath, second, third, fourth);
+      await runSend(resolved.path, second, third, fourth);
     else if (first === "network" && second === "show" && third === undefined)
-      await runNetwork(parsed.walletPath);
+      await runNetwork(resolved.path);
     else if (first === "network" && second === "set" && third && fourth === undefined)
-      await runNetwork(parsed.walletPath, third);
+      await runNetwork(resolved.path, third);
     else
       throw new TypeError("Unknown command. Run `ldgr --help` for available commands.");
   } catch (error) {

package/dist/wallet-file.d.ts

@@ -1,13 +1,17 @@
 import { type LdgrSigner } from "@ldgr/client";
 import { type LedgerId } from "@ldgr/protocol";
 export type WalletNetwork = "mainnet" | "testnet";
-export type EncryptedWalletFile = {
+type WalletIdentity = {
     readonly format: "ldgr-cli-wallet";
     readonly version: 1;
     readonly network: WalletNetwork;
     readonly ledgerId: LedgerId;
     readonly address: string;
     readonly publicKey: string;
+};
+/** Passphrase protection is the legacy format when `protection` is omitted. */
+export type EncryptedWalletFile = WalletIdentity & {
+    readonly protection?: "passphrase";
     readonly ciphertext: string;
     readonly iv: string;
     readonly kdf: {
@@ -17,45 +21,72 @@ export type EncryptedWalletFile = {
         readonly salt: string;
     };
 };
+/** Matches the extension's explicit local-only, no-passphrase vault mode. */
+export type UnprotectedWalletFile = WalletIdentity & {
+    readonly protection: "none";
+    /** Local secret material; protected by the file's owner-only permissions only. */
+    readonly recoveryKey: string;
+};
+export type LocalWalletFile = EncryptedWalletFile | UnprotectedWalletFile;
 export type EncryptedWalletStore = {
     readonly format: "ldgr-cli-wallet-store";
     readonly version: 1;
     readonly activeWalletIndex: number;
-    readonly wallets: readonly EncryptedWalletFile[];
+    readonly wallets: readonly LocalWalletFile[];
 };
-export type WalletFileMetadata = EncryptedWalletFile & {
+export type WalletFileMetadata = LocalWalletFile & {
     readonly index: number;
     readonly selected: boolean;
 };
+export type DefaultWalletPathInput = {
+    readonly home?: string | undefined;
+    /** Test seam for the former XDG default; production reads XDG_CONFIG_HOME. */
+    readonly configHome?: string | undefined;
+};
 export type CreatedEncryptedWallet = {
-    readonly file: EncryptedWalletFile;
+    readonly file: LocalWalletFile;
     readonly serialized: string;
     /** Display once during creation; never persist or log this value. */
     readonly recoveryKey: string;
 };
-export declare function defaultWalletPath(input?: {
-    readonly home?: string | undefined;
-}): string;
+export declare function defaultWalletPath(input?: DefaultWalletPathInput): string;
+/** The v0.1 default location, used only to preserve existing local wallets. */
+export declare function legacyDefaultWalletPath(input?: DefaultWalletPathInput): string;
 export declare function createEncryptedWalletFile(input: {
     readonly ledgerId: LedgerId;
-    readonly passphrase: string;
+    readonly passphrase?: string | undefined;
 }): Promise<CreatedEncryptedWallet>;
-export declare function writeNewWalletFile(path: string, file: EncryptedWalletFile): Promise<void>;
-export declare function readEncryptedWalletFile(path: string, passphrase: string): Promise<LdgrSigner>;
+export declare function writeNewWalletFile(path: string, file: LocalWalletFile): Promise<void>;
+/**
+ * Moves the validated former XDG default into ~/.ldgr/ on first wallet use.
+ * Explicit --wallet paths are deliberately never considered here.
+ */
+export declare function migrateDefaultWalletPath(input?: DefaultWalletPathInput): Promise<{
+    readonly path: string;
+    readonly migrated: boolean;
+}>;
+export declare function readEncryptedWalletFile(path: string, passphrase?: string): Promise<LdgrSigner>;
+/** Writes the exact raw recovery-key text accepted by the extension importer. */
+export declare function exportRecoveryKeyFile(input: {
+    readonly walletPath: string;
+    readonly backupPath: string;
+    readonly passphrase?: string | undefined;
+}): Promise<void>;
 /** Adds a separately encrypted wallet and selects it. */
-export declare function addWalletFile(path: string, file: EncryptedWalletFile): Promise<number>;
-/** Encrypts canonical recovery material, adds it to the store, and selects it. */
+export declare function addWalletFile(path: string, file: LocalWalletFile): Promise<number>;
+/** Adds canonical recovery material with optional passphrase protection and selects it. */
 export declare function importEncryptedWalletFile(input: {
     readonly path: string;
     readonly recoveryKey: string;
     readonly ledgerId: LedgerId;
-    readonly passphrase: string;
+    readonly passphrase?: string | undefined;
 }): Promise<{
-    readonly file: EncryptedWalletFile;
+    readonly file: LocalWalletFile;
     readonly index: number;
 }>;
 export declare function listWalletFileMetadata(path: string): Promise<readonly WalletFileMetadata[]>;
-export declare function selectWalletFile(path: string, index: number): Promise<EncryptedWalletFile>;
+export declare function selectWalletFile(path: string, index: number): Promise<LocalWalletFile>;
 /** Re-encrypts the same self-custody key for a different LDGR ledger. */
-export declare function switchWalletNetwork(path: string, passphrase: string, ledgerId: LedgerId): Promise<EncryptedWalletFile>;
-export declare function walletFileMetadata(path: string): Promise<EncryptedWalletFile>;
+export declare function switchWalletNetwork(path: string, passphrase: string | undefined, ledgerId: LedgerId): Promise<LocalWalletFile>;
+export declare function walletFileMetadata(path: string): Promise<LocalWalletFile>;
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ldgr/cli",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "type": "module",
   "bin": {
     "ldgr": "dist/cli.js"