quilltap 4.9.0-dev.92 → 4.9.0-dev.93

package/lib/__tests__/dbkey-restore.test.js

@@ -0,0 +1,151 @@
+/**
+ * `quilltap instances restore-key` — the guards that stand between an operator
+ * with a pepper and a `.dbkey` that would brick an instance.
+ *
+ * The load-bearing one is the pepper proof: a key file holding the WRONG
+ * pepper is worse than none at all, because the server unwraps it happily and
+ * then reports an intact database as corrupt. So the proof runs against real
+ * SQLCipher files, not the suite's `better-sqlite3` mock — the mock would open
+ * anything.
+ *
+ * @jest-environment node
+ */
+
+'use strict';
+
+const fs = require('fs');
+const os = require('os');
+const path = require('path');
+const crypto = require('crypto');
+
+const PKG_ROOT = path.join(__dirname, '..', '..');
+
+// The root jest config maps both driver names onto __mocks__/better-sqlite3.ts,
+// which accepts any key. Point them back at the real binding by absolute path
+// so a wrong pepper actually fails to decrypt.
+jest.mock('better-sqlite3-multiple-ciphers', () =>
+  require(path.join(PKG_ROOT, 'node_modules', 'better-sqlite3-multiple-ciphers'))
+);
+
+const Database = require('better-sqlite3-multiple-ciphers');
+const { provePepper, databaseState } = require('../dbkey-restore');
+const {
+  INTERNAL_PASSPHRASE,
+  encryptDbKey,
+  decryptDbKey,
+  tryDecryptDbKey,
+  preserveExtraFields,
+  readDbKeyFile,
+  writeDbKeyFile,
+} = require('../dbkey');
+
+const PEPPER = crypto.randomBytes(32).toString('base64');
+const OTHER_PEPPER = crypto.randomBytes(32).toString('base64');
+
+let dataDir;
+
+function seedEncryptedDb(filename, pepper) {
+  const db = new Database(path.join(dataDir, filename));
+  db.pragma(`key = "x'${Buffer.from(pepper, 'base64').toString('hex')}'"`);
+  db.exec("CREATE TABLE t (a TEXT); INSERT INTO t VALUES ('hello');");
+  db.close();
+}
+
+function seedPlaintextDb(filename) {
+  const db = new Database(path.join(dataDir, filename));
+  db.exec('CREATE TABLE t (a TEXT);');
+  db.close();
+}
+
+beforeEach(() => {
+  dataDir = fs.mkdtempSync(path.join(os.tmpdir(), 'qtap-restore-'));
+});
+
+afterEach(() => {
+  fs.rmSync(dataDir, { recursive: true, force: true });
+});
+
+describe('databaseState', () => {
+  it('reads the SQLite magic to tell plaintext from SQLCipher', () => {
+    seedPlaintextDb('plain.db');
+    seedEncryptedDb('enc.db', PEPPER);
+
+    expect(databaseState(path.join(dataDir, 'plain.db'))).toBe('plaintext');
+    expect(databaseState(path.join(dataDir, 'enc.db'))).toBe('encrypted');
+    expect(databaseState(path.join(dataDir, 'nope.db'))).toBe('absent');
+  });
+});
+
+describe('provePepper', () => {
+  it('proves the right pepper against every encrypted database', () => {
+    seedEncryptedDb('quilltap.db', PEPPER);
+    seedEncryptedDb('quilltap-llm-logs.db', PEPPER);
+    seedEncryptedDb('quilltap-mount-index.db', PEPPER);
+
+    const { proved, results } = provePepper(dataDir, PEPPER);
+    expect(proved).toBe(true);
+    expect(results.every((r) => r.ok === true)).toBe(true);
+  });
+
+  it('refuses a pepper that does not open the databases', () => {
+    seedEncryptedDb('quilltap.db', PEPPER);
+
+    const { proved, results } = provePepper(dataDir, OTHER_PEPPER);
+    expect(proved).toBe(false);
+    expect(results.find((r) => r.filename === 'quilltap.db').ok).toBe(false);
+  });
+
+  it('reports one bad database among good ones rather than averaging it away', () => {
+    seedEncryptedDb('quilltap.db', PEPPER);
+    seedEncryptedDb('quilltap-llm-logs.db', OTHER_PEPPER);
+
+    const { proved, results } = provePepper(dataDir, PEPPER);
+    expect(proved).toBe(false);
+    expect(results.find((r) => r.filename === 'quilltap.db').ok).toBe(true);
+    expect(results.find((r) => r.filename === 'quilltap-llm-logs.db').ok).toBe(false);
+  });
+
+  it('cannot prove anything when the databases are absent or still plaintext', () => {
+    expect(provePepper(dataDir, PEPPER).proved).toBe(false);
+
+    seedPlaintextDb('quilltap.db');
+    const { proved, results } = provePepper(dataDir, PEPPER);
+    expect(proved).toBe(false);
+    expect(results.find((r) => r.filename === 'quilltap.db')).toMatchObject({
+      state: 'plaintext',
+      ok: null,
+    });
+  });
+});
+
+describe('rewrapping a key file', () => {
+  it('round-trips the pepper under a new passphrase', () => {
+    writeDbKeyFile(dataDir, encryptDbKey(PEPPER, INTERNAL_PASSPHRASE));
+    expect(decryptDbKey(readDbKeyFile(dataDir), INTERNAL_PASSPHRASE)).toBe(PEPPER);
+
+    writeDbKeyFile(dataDir, encryptDbKey(PEPPER, 'the lamplighter'));
+    const rewrapped = readDbKeyFile(dataDir);
+    expect(tryDecryptDbKey(rewrapped, INTERNAL_PASSPHRASE)).toBeNull();
+    expect(decryptDbKey(rewrapped, 'the lamplighter')).toBe(PEPPER);
+  });
+
+  it('carries fields the wrapping does not own across the rebuild', () => {
+    // `minServerVersion` is written by lib/startup/version-guard.ts for the
+    // Electron shell's pre-launch check. Dropping it on a rewrap would take
+    // the version floor with it.
+    const existing = encryptDbKey(PEPPER, INTERNAL_PASSPHRASE);
+    existing.minServerVersion = '4.9.0-dev.91';
+
+    const fresh = preserveExtraFields(existing, encryptDbKey(PEPPER, 'the lamplighter'));
+
+    expect(fresh.minServerVersion).toBe('4.9.0-dev.91');
+    expect(fresh.salt).not.toBe(existing.salt);
+    expect(decryptDbKey(fresh, 'the lamplighter')).toBe(PEPPER);
+  });
+
+  it('writes the key file owner-only', () => {
+    writeDbKeyFile(dataDir, encryptDbKey(PEPPER, INTERNAL_PASSPHRASE));
+    const mode = fs.statSync(path.join(dataDir, 'quilltap.dbkey')).mode & 0o777;
+    expect(mode).toBe(0o600);
+  });
+});

package/lib/completion/bash.template

@@ -263,8 +263,8 @@ _quilltap_complete() {
       fi
       ;;
     instances)
-      local inst_verbs="list ls show path where add create remove rm delete set-passphrase passphrase default rename"
-      local inst_flags="--names-only --json --clear --help"
+      local inst_verbs="list ls show path where add create remove rm delete set-passphrase passphrase default rename restore-key rebuild-key"
+      local inst_flags="--names-only --json --clear --passphrase --no-passphrase --data-dir --force --yes --help"
       if [[ -z "$subverb" ]]; then
         if [[ "$cur" == -* ]]; then
           COMPREPLY=($(compgen -W "$inst_flags" -- "$cur"))
@@ -274,7 +274,7 @@ _quilltap_complete() {
       else
         # Most instances verbs take a name as positional; offer registered names
         case "$subverb" in
-          show|remove|rm|delete|set-passphrase|passphrase|default|rename)
+          show|remove|rm|delete|set-passphrase|passphrase|default|rename|restore-key|rebuild-key)
             local instances=$(command quilltap instances list --names-only 2>/dev/null)
             if [[ "$cur" == -* ]]; then
               COMPREPLY=($(compgen -W "$inst_flags" -- "$cur"))

package/lib/completion/fish.template

@@ -225,14 +225,23 @@ complete -c quilltap -n '__quilltap_using_subcommand instances' -f -a 'set-passp
 complete -c quilltap -n '__quilltap_using_subcommand instances' -f -a 'passphrase' -d 'Set passphrase'
 complete -c quilltap -n '__quilltap_using_subcommand instances' -f -a 'default' -d 'Set/show/clear default instance'
 complete -c quilltap -n '__quilltap_using_subcommand instances' -f -a 'rename' -d 'Rename instance'
+complete -c quilltap -n '__quilltap_using_subcommand instances' -f -a 'restore-key' -d 'Rebuild .dbkey from the pepper'
+complete -c quilltap -n '__quilltap_using_subcommand instances' -f -a 'rebuild-key' -d 'Rebuild .dbkey from the pepper'
 
 # Instance names as positional for verbs that target one
-for verb in show remove rm delete set-passphrase passphrase default rename
+for verb in show remove rm delete set-passphrase passphrase default rename restore-key rebuild-key
   complete -c quilltap -n "__quilltap_using_subverb instances $verb" -f -a '(__quilltap_instance_names)'
 end
 
 complete -c quilltap -n '__quilltap_using_subcommand instances' -l 'names-only' -d 'Print one name per line'
 complete -c quilltap -n '__quilltap_using_subverb instances default' -l 'clear' -d 'Clear default instance'
+for verb in restore-key rebuild-key
+  complete -c quilltap -n "__quilltap_using_subverb instances $verb" -l 'passphrase' -d 'Passphrase for the rebuilt .dbkey'
+  complete -c quilltap -n "__quilltap_using_subverb instances $verb" -l 'no-passphrase' -d 'Rebuild with no passphrase'
+  complete -c quilltap -n "__quilltap_using_subverb instances $verb" -s 'd' -l 'data-dir' -r -d 'Instance root to rebuild in'
+  complete -c quilltap -n "__quilltap_using_subverb instances $verb" -l 'force' -d 'Write with no database to prove against'
+  complete -c quilltap -n "__quilltap_using_subverb instances $verb" -s 'y' -l 'yes' -d 'Skip confirmation prompts'
+end
 
 # ---------- memories verbs ----------
 complete -c quilltap -n '__quilltap_using_subcommand memories' -f -a 'ls' -d 'List memories'

package/lib/completion/zsh.template

@@ -450,12 +450,19 @@ _quilltap_instances() {
     'passphrase:Set instance passphrase'
     'default:Set/show/clear the default instance'
     'rename:Rename an instance (preserves passphrase)'
+    'restore-key:Rebuild the .dbkey from the pepper'
+    'rebuild-key:Rebuild the .dbkey from the pepper'
   )
 
   inst_opts=(
     '--names-only[Print one name per line (for completion)]'
     '--json[JSON output]'
     '--clear[Clear value (for default)]'
+    '--passphrase[Passphrase for the rebuilt .dbkey]:passphrase:'
+    '--no-passphrase[Rebuild the .dbkey with no passphrase]'
+    '(-d --data-dir)'{-d,--data-dir}'[Instance root to rebuild in]:directory:_files -/'
+    '--force[Write even with no encrypted database to prove the pepper against]'
+    '(-y --yes)'{-y,--yes}'[Skip confirmation prompts]'
     '(-h --help)'{-h,--help}'[Show help]'
   )
 
@@ -470,7 +477,7 @@ _quilltap_instances() {
       ;;
     name)
       case "$line[1]" in
-        show|remove|rm|delete|set-passphrase|passphrase|default|rename)
+        show|remove|rm|delete|set-passphrase|passphrase|default|rename|restore-key|rebuild-key)
           _quilltap_instance_names
           ;;
       esac

package/lib/db-helpers.js

@@ -148,42 +148,19 @@ function promptPassphrase(prompt) {
 }
 
 async function loadDbKey(dataDir, passphrase) {
-  const crypto = require('crypto');
-  const dbkeyPath = path.join(dataDir, 'quilltap.dbkey');
-  if (!fs.existsSync(dbkeyPath)) {
-    return null;
-  }
-
-  const data = JSON.parse(fs.readFileSync(dbkeyPath, 'utf8'));
-  const INTERNAL_PASSPHRASE = '__quilltap_no_passphrase__';
-
-  if ('hasPassphrase' in data) {
-    delete data.hasPassphrase;
-    fs.writeFileSync(dbkeyPath, JSON.stringify(data, null, 2), { mode: 0o600 });
-  }
+  const { INTERNAL_PASSPHRASE, readDbKeyFile, decryptDbKey, tryDecryptDbKey } = require('./dbkey');
 
-  function tryDecrypt(pass) {
-    const salt = Buffer.from(data.salt, 'hex');
-    const key = crypto.pbkdf2Sync(pass, new Uint8Array(salt), data.kdfIterations, 32, data.kdfDigest);
-    const iv = Buffer.from(data.iv, 'hex');
-    const decipher = crypto.createDecipheriv(data.algorithm, new Uint8Array(key), new Uint8Array(iv));
-    decipher.setAuthTag(new Uint8Array(Buffer.from(data.authTag, 'hex')));
-    let plaintext = decipher.update(data.ciphertext, 'hex', 'utf8');
-    plaintext += decipher.final('utf8');
-
-    const hash = crypto.createHash('sha256').update(plaintext).digest('hex');
-    if (hash !== data.pepperHash) {
-      throw new Error('Pepper hash mismatch');
-    }
-    return plaintext;
+  const data = readDbKeyFile(dataDir);
+  if (!data) {
+    return null;
   }
 
-  try {
-    return tryDecrypt(INTERNAL_PASSPHRASE);
-  } catch {
-    // Internal passphrase failed — need user passphrase
+  const internal = tryDecryptDbKey(data, INTERNAL_PASSPHRASE);
+  if (internal !== null) {
+    return internal;
   }
 
+  // Internal passphrase failed — need a user passphrase.
   if (!passphrase && process.env.QUILLTAP_DB_PASSPHRASE) {
     passphrase = process.env.QUILLTAP_DB_PASSPHRASE;
   }
@@ -195,7 +172,7 @@ async function loadDbKey(dataDir, passphrase) {
     }
   }
 
-  return tryDecrypt(passphrase);
+  return decryptDbKey(data, passphrase);
 }
 
 function openEncryptedDb(dbPath, pepper, { readonly = true, friendlyName = 'database' } = {}) {

package/lib/dbkey-restore.js

@@ -0,0 +1,347 @@
+'use strict';
+
+/**
+ * `quilltap instances restore-key` — rebuild a lost `.dbkey`, or re-wrap an
+ * existing one under a different passphrase, from the pepper itself.
+ *
+ * The pepper IS the database key; the `.dbkey` file is only a wrapper around
+ * it. So an operator who kept the pepper printed at first-run setup (or who
+ * runs with `ENCRYPTION_MASTER_PEPPER` in the environment) can always rebuild
+ * the wrapper — including under a new passphrase, when the old one is gone.
+ * The server can already do this for the *lost-file* half through
+ * `/api/v1/system/unlock?action=store`, but only while it is running and only
+ * from the env var; a forgotten passphrase leaves it stuck in locked mode with
+ * no way in. This is the offline twin, and it also covers the re-wrap.
+ *
+ * The load-bearing safety property: a `.dbkey` holding the WRONG pepper is
+ * worse than no `.dbkey` at all — the server unwraps it, hands SQLCipher a key
+ * that decrypts nothing, and reports what looks like a corrupt database (or,
+ * with the env var also set, exits fatally on the hash mismatch). So the
+ * candidate pepper is proved against the encrypted databases on disk BEFORE
+ * anything is written, and that proof cannot be waived while an encrypted
+ * database exists to check.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const readline = require('readline');
+
+const {
+  INTERNAL_PASSPHRASE,
+  getDbKeyPath,
+  hashPepper,
+  readDbKeyFile,
+  tryDecryptDbKey,
+  encryptDbKey,
+  preserveExtraFields,
+  writeDbKeyFile,
+} = require('./dbkey');
+const { promptPassphrase, openEncryptedDb } = require('./db-helpers');
+const { acquireWriteLock, releaseWriteLock } = require('./lock-helpers');
+const { resolveInstance, expandPath, setInstancePassphrase, readInstances } = require('./instances');
+
+/** Mirror of lib/startup/db-encryption-state.ts. */
+const SQLITE_MAGIC = 'SQLite format 3\0';
+
+/** The three databases the one pepper opens, main first — it is the authority. */
+const DATABASES = [
+  { filename: 'quilltap.db', label: 'main database' },
+  { filename: 'quilltap-llm-logs.db', label: 'LLM logs database' },
+  { filename: 'quilltap-mount-index.db', label: 'mount index database' },
+];
+
+function promptLine(prompt) {
+  return new Promise((resolve) => {
+    const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+    let answered = false;
+    // A closed stdin (piped, /dev/null, CI) never fires `question` — treat the
+    // EOF as an empty answer so the caller's default (no) still applies.
+    rl.on('close', () => {
+      if (!answered) {
+        answered = true;
+        resolve('');
+      }
+    });
+    rl.question(prompt, (answer) => {
+      answered = true;
+      rl.close();
+      resolve(answer);
+    });
+  });
+}
+
+async function confirm(question, assumeYes) {
+  if (assumeYes) return true;
+  const answer = (await promptLine(`${question} [y/N] `)).trim().toLowerCase();
+  return answer === 'y' || answer === 'yes';
+}
+
+/**
+ * 'encrypted' | 'plaintext' | 'absent' — by file header, exactly as the server
+ * decides whether a database still needs converting.
+ */
+function databaseState(dbPath) {
+  if (!fs.existsSync(dbPath)) return 'absent';
+  const fd = fs.openSync(dbPath, 'r');
+  try {
+    const header = Buffer.alloc(16);
+    // Read into the Buffer itself — `new Uint8Array(buf)` would COPY it and
+    // the read would land in the copy, leaving `header` all zeroes (which
+    // reads as "encrypted" for every file on disk).
+    const read = fs.readSync(fd, header, 0, 16, 0);
+    if (read < 16) return 'plaintext';
+    return header.toString('utf8') === SQLITE_MAGIC ? 'plaintext' : 'encrypted';
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+/**
+ * Prove the candidate pepper against every encrypted database in `dataDir`.
+ *
+ * Returns `{ proved, results }` — `proved` is true only when at least one
+ * encrypted database opened AND none that was encrypted failed. Opening is
+ * read-only and reads the schema page, which is what actually exercises the
+ * key.
+ */
+function provePepper(dataDir, pepper) {
+  const results = [];
+  for (const { filename, label } of DATABASES) {
+    const dbPath = path.join(dataDir, filename);
+    const state = databaseState(dbPath);
+    if (state !== 'encrypted') {
+      results.push({ label, filename, state, ok: null });
+      continue;
+    }
+    let db;
+    try {
+      db = openEncryptedDb(dbPath, pepper, { readonly: true, friendlyName: label });
+      db.prepare('SELECT count(*) AS n FROM sqlite_master').get();
+      results.push({ label, filename, state, ok: true });
+    } catch (err) {
+      results.push({ label, filename, state, ok: false, error: err.message });
+    } finally {
+      if (db) {
+        try { db.close(); } catch { /* best effort */ }
+      }
+    }
+  }
+  const checked = results.filter((r) => r.ok !== null);
+  const proved = checked.length > 0 && checked.every((r) => r.ok === true);
+  return { proved, results };
+}
+
+/** Back an existing key file up beside itself, returning the backup path. */
+function backupDbKey(dataDir) {
+  const dbkeyPath = getDbKeyPath(dataDir);
+  const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+  const backupPath = `${dbkeyPath}.bak-${stamp}`;
+  fs.copyFileSync(dbkeyPath, backupPath);
+  try { fs.chmodSync(backupPath, 0o600); } catch { /* best effort */ }
+  return backupPath;
+}
+
+/**
+ * Resolve the target data directory from either a registered instance name or
+ * an explicit instance root, returning the registry name when there is one so
+ * a stored passphrase can be kept honest afterwards.
+ */
+function resolveTarget(name, dataDirFlag) {
+  if (name && dataDirFlag) {
+    throw new Error('Specify either an instance name or --data-dir, not both.');
+  }
+  if (name) {
+    const inst = resolveInstance(name);
+    return { dataDir: path.join(inst.path, 'data'), instanceName: inst.name, root: inst.path };
+  }
+  if (!dataDirFlag) {
+    throw new Error('Usage: quilltap instances restore-key <name> | --data-dir <instance-root>');
+  }
+  const root = expandPath(dataDirFlag);
+  // Accept either the instance root or the data directory itself.
+  const dataDir = path.basename(root) === 'data' ? root : path.join(root, 'data');
+  const registry = readInstances();
+  const match = Object.entries(registry.instances || {}).find(
+    ([, entry]) => expandPath(entry.path) === expandPath(path.dirname(dataDir)),
+  );
+  return { dataDir, instanceName: match ? match[0] : null, root: path.dirname(dataDir) };
+}
+
+/**
+ * Rebuild `<dataDir>/quilltap.dbkey` from the pepper.
+ *
+ * @param {object} opts
+ * @param {string} opts.name            Registered instance name (optional)
+ * @param {string} opts.dataDir         Instance root or data dir (optional)
+ * @param {string} opts.passphrase      Passphrase for the new file (non-interactive)
+ * @param {boolean} opts.noPassphrase   Write with no user passphrase, don't prompt
+ * @param {boolean} opts.force          Proceed when no encrypted database exists to prove against
+ * @param {boolean} opts.yes            Skip confirmation prompts
+ */
+async function restoreKey(opts) {
+  const target = resolveTarget(opts.name, opts.dataDir);
+  const { dataDir } = target;
+
+  if (!fs.existsSync(dataDir)) {
+    throw new Error(`Data directory does not exist: ${dataDir}`);
+  }
+
+  console.log(`Instance:    ${target.instanceName || '(unregistered)'}`);
+  console.log(`Data dir:    ${dataDir}`);
+
+  // The server keeps the pepper and the effective passphrase in memory; a file
+  // rewritten underneath it would leave both stale (archive encryption reads
+  // the cached passphrase). Recovery happens with the instance down.
+  acquireWriteLock(dataDir);
+
+  try {
+    // ---- 1. The pepper. Never a flag: a command line lands in shell history
+    // and in `ps`. Environment or hidden prompt only.
+    let pepper = (process.env.ENCRYPTION_MASTER_PEPPER || '').trim();
+    if (pepper) {
+      console.log('Pepper:      from ENCRYPTION_MASTER_PEPPER');
+    } else {
+      pepper = (await promptPassphrase('Encryption master pepper (hidden): ')).trim();
+      if (!pepper) {
+        throw new Error('No pepper provided. Set ENCRYPTION_MASTER_PEPPER or paste it at the prompt.');
+      }
+    }
+    if (Buffer.from(pepper, 'base64').length !== 32) {
+      console.log('Warning:     that does not look like a Quilltap pepper (44-char base64 of 32 bytes).');
+    }
+
+    // ---- 2. Prove it against the databases before writing anything.
+    const { proved, results } = provePepper(dataDir, pepper);
+    console.log('');
+    for (const r of results) {
+      if (r.state === 'absent') {
+        console.log(`  ${r.filename.padEnd(28)} absent`);
+      } else if (r.state === 'plaintext') {
+        console.log(`  ${r.filename.padEnd(28)} unencrypted (nothing to check against)`);
+      } else if (r.ok) {
+        console.log(`  ${r.filename.padEnd(28)} opens with this pepper ✓`);
+      } else {
+        console.log(`  ${r.filename.padEnd(28)} DOES NOT OPEN — ${r.error.split('\n')[0]}`);
+      }
+    }
+    console.log('');
+
+    const failures = results.filter((r) => r.ok === false);
+    if (failures.length > 0) {
+      throw new Error(
+        'This pepper does not open the databases on disk. Refusing to write a .dbkey that\n' +
+        'would make an intact instance look corrupt. If the files are cloud-evicted rather\n' +
+        'than wrongly keyed, run `quilltap file-verify` first and try again.',
+      );
+    }
+    if (!proved) {
+      console.log('No encrypted database exists here, so the pepper cannot be proved.');
+      if (results.some((r) => r.state === 'plaintext')) {
+        console.log('The databases are still unencrypted — the server will encrypt them with');
+        console.log('this pepper on its next start, whether or not it is the original one.');
+      }
+      if (!opts.force && !(await confirm('Write the .dbkey anyway?', opts.yes))) {
+        throw new Error('Aborted.');
+      }
+    }
+
+    // ---- 3. What is already on disk.
+    const existing = readDbKeyFile(dataDir);
+    let replacingDifferentPepper = false;
+    if (existing) {
+      if (existing.pepperHash === hashPepper(pepper)) {
+        console.log('An existing .dbkey already holds this pepper — rewrapping it.');
+      } else {
+        replacingDifferentPepper = true;
+        console.log('WARNING: the existing .dbkey holds a DIFFERENT pepper than the one given.');
+        if (proved) {
+          console.log('The databases opened with the new one, so the file on disk is the stale part.');
+        }
+        if (!(await confirm('Replace it? (a timestamped backup is kept)', opts.yes))) {
+          throw new Error('Aborted.');
+        }
+      }
+    }
+
+    // ---- 4. The passphrase for the rebuilt file.
+    let newPassphrase;
+    if (opts.noPassphrase) {
+      newPassphrase = '';
+    } else if (opts.passphrase !== undefined && opts.passphrase !== '') {
+      newPassphrase = opts.passphrase;
+    } else if (opts.yes) {
+      newPassphrase = '';
+    } else {
+      newPassphrase = await promptPassphrase('Passphrase for the rebuilt .dbkey (blank for none): ');
+      if (newPassphrase) {
+        const again = await promptPassphrase('Confirm passphrase: ');
+        if (again !== newPassphrase) {
+          throw new Error('Passphrases did not match.');
+        }
+      }
+    }
+
+    const hadUserPassphrase = existing
+      ? tryDecryptDbKey(existing, INTERNAL_PASSPHRASE) === null
+      : false;
+    const effective = newPassphrase.length > 0 ? newPassphrase : INTERNAL_PASSPHRASE;
+
+    // ---- 5. Write, then read back and prove the round trip.
+    let backupPath = null;
+    if (existing) {
+      backupPath = backupDbKey(dataDir);
+    }
+
+    // `minServerVersion` (the Electron shell's version floor) rides along in
+    // the same file without belonging to the wrapping — carry it, and anything
+    // like it, across the rebuild.
+    writeDbKeyFile(dataDir, preserveExtraFields(existing, encryptDbKey(pepper, effective)));
+
+    const written = readDbKeyFile(dataDir);
+    const roundTrip = written && tryDecryptDbKey(written, effective);
+    if (roundTrip !== pepper) {
+      if (backupPath) {
+        fs.copyFileSync(backupPath, getDbKeyPath(dataDir));
+      }
+      throw new Error('Wrote the .dbkey but could not read the pepper back — restored the previous file.');
+    }
+
+    console.log('');
+    console.log(`Wrote ${getDbKeyPath(dataDir)} (mode 0600).`);
+    if (backupPath) {
+      console.log(`Previous file kept at ${path.basename(backupPath)}.`);
+    }
+    console.log(
+      newPassphrase
+        ? 'The instance now unlocks with the passphrase you just set.'
+        : 'The instance now opens with no passphrase.',
+    );
+
+    // ---- 6. Keep the registry's stored passphrase honest.
+    if (target.instanceName) {
+      setInstancePassphrase(target.instanceName, newPassphrase);
+      console.log(
+        newPassphrase
+          ? `Updated the stored passphrase for "${target.instanceName}".`
+          : `Cleared the stored passphrase for "${target.instanceName}".`,
+      );
+    }
+
+    // ---- 7. The one thing a re-wrap does NOT carry with it.
+    const passphraseChanged =
+      replacingDifferentPepper ||
+      hadUserPassphrase !== (newPassphrase.length > 0) ||
+      (hadUserPassphrase && newPassphrase.length > 0);
+    if (existing && passphraseChanged) {
+      console.log('');
+      console.log('Note: character ARCHIVE bundles in files/ are encrypted with the passphrase,');
+      console.log('not the pepper. This command does not rewrite them — bundles made under the');
+      console.log('old passphrase still want the old one. The server\'s Change Passphrase card');
+      console.log('re-encrypts them; this offline path cannot.');
+    }
+  } finally {
+    releaseWriteLock(dataDir);
+  }
+}
+
+module.exports = { restoreKey, provePepper, databaseState };

package/lib/dbkey.js

@@ -0,0 +1,188 @@
+'use strict';
+
+/**
+ * `.dbkey` file primitives for the CLI.
+ *
+ * The instance's one and only `quilltap.dbkey` wraps the pepper — the actual
+ * SQLCipher key for all three databases — in AES-256-GCM under a PBKDF2 key
+ * derived from the operator's passphrase (or an internal sentinel when no
+ * passphrase is set). The CLI is plain Node and cannot import the TypeScript
+ * source of truth at `lib/startup/dbkey.ts` + `lib/startup/pepper-crypto.ts`,
+ * so the format and constants below MIRROR it. Keep them in sync.
+ *
+ * Three call sites needed this unwrap — `db-helpers.loadDbKey`,
+ * `instances.verifyPassphrase`, and the `instances restore-key` rebuild — so it
+ * lives here once rather than three times.
+ *
+ * Reading params off the file (rather than the constants) is deliberate: it is
+ * what keeps older `.dbkey` files decryptable after a parameter upgrade. The
+ * constants are used only when writing a fresh file.
+ */
+
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+
+/** The instance's single key file. One pepper per instance. */
+const DBKEY_FILENAME = 'quilltap.dbkey';
+
+/** Sentinel used to wrap the pepper when the operator sets no passphrase. */
+const INTERNAL_PASSPHRASE = '__quilltap_no_passphrase__';
+
+// Mirror of the write-side constants in lib/startup/dbkey.ts.
+const ALGORITHM = 'aes-256-gcm';
+const KEY_LENGTH = 32;
+const IV_LENGTH = 16;
+const SALT_LENGTH = 32;
+const PBKDF2_ITERATIONS = 600000;
+const PBKDF2_DIGEST = 'sha256';
+
+function getDbKeyPath(dataDir) {
+  return path.join(dataDir, DBKEY_FILENAME);
+}
+
+/** SHA-256 of the plaintext pepper, hex — the file's `pepperHash` field. */
+function hashPepper(pepper) {
+  return crypto.createHash('sha256').update(pepper).digest('hex');
+}
+
+/**
+ * Read and parse `<dataDir>/quilltap.dbkey`, returning null when absent.
+ *
+ * Strips the legacy `hasPassphrase` flag in passing (it leaked whether a user
+ * passphrase was set), rewriting the file the same way the server does.
+ */
+function readDbKeyFile(dataDir) {
+  const dbkeyPath = getDbKeyPath(dataDir);
+  if (!fs.existsSync(dbkeyPath)) return null;
+  const data = JSON.parse(fs.readFileSync(dbkeyPath, 'utf8'));
+  if ('hasPassphrase' in data) {
+    delete data.hasPassphrase;
+    fs.writeFileSync(dbkeyPath, JSON.stringify(data, null, 2), { mode: 0o600 });
+  }
+  return data;
+}
+
+/**
+ * Unwrap the pepper from parsed `.dbkey` contents.
+ *
+ * Throws on a wrong passphrase, a tampered file, or a pepper whose hash does
+ * not match the one recorded alongside it.
+ */
+function decryptDbKey(data, passphrase) {
+  const salt = Buffer.from(data.salt, 'hex');
+  const key = crypto.pbkdf2Sync(
+    passphrase,
+    new Uint8Array(salt),
+    data.kdfIterations,
+    KEY_LENGTH,
+    data.kdfDigest,
+  );
+  const iv = Buffer.from(data.iv, 'hex');
+  const decipher = crypto.createDecipheriv(data.algorithm, new Uint8Array(key), new Uint8Array(iv));
+  decipher.setAuthTag(new Uint8Array(Buffer.from(data.authTag, 'hex')));
+  let plaintext = decipher.update(data.ciphertext, 'hex', 'utf8');
+  plaintext += decipher.final('utf8');
+  if (hashPepper(plaintext) !== data.pepperHash) {
+    throw new Error('Pepper hash mismatch');
+  }
+  return plaintext;
+}
+
+/** Unwrap, returning null instead of throwing. */
+function tryDecryptDbKey(data, passphrase) {
+  try {
+    return decryptDbKey(data, passphrase);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Wrap a pepper for storage, generating a fresh salt and IV. Mirrors
+ * `encryptPepper` in lib/startup/dbkey.ts, field for field.
+ */
+function encryptDbKey(pepper, passphrase) {
+  const salt = crypto.randomBytes(SALT_LENGTH);
+  const key = crypto.pbkdf2Sync(
+    passphrase,
+    new Uint8Array(salt),
+    PBKDF2_ITERATIONS,
+    KEY_LENGTH,
+    PBKDF2_DIGEST,
+  );
+  const iv = crypto.randomBytes(IV_LENGTH);
+  const cipher = crypto.createCipheriv(ALGORITHM, new Uint8Array(key), new Uint8Array(iv));
+  let ciphertext = cipher.update(pepper, 'utf8', 'hex');
+  ciphertext += cipher.final('hex');
+  return {
+    version: 1,
+    algorithm: ALGORITHM,
+    kdf: 'pbkdf2',
+    kdfIterations: PBKDF2_ITERATIONS,
+    kdfDigest: PBKDF2_DIGEST,
+    salt: salt.toString('hex'),
+    iv: iv.toString('hex'),
+    ciphertext,
+    authTag: cipher.getAuthTag().toString('hex'),
+    pepperHash: hashPepper(pepper),
+  };
+}
+
+/**
+ * The fields that make up the wrapped key itself. Anything else in the file
+ * was put there by another subsystem — `minServerVersion`, written by
+ * `lib/startup/version-guard.ts` for the Electron shell's pre-launch check —
+ * and belongs to the instance rather than to this wrapping, so a rewrap must
+ * carry it across.
+ */
+const KEY_WRAPPER_FIELDS = new Set([
+  'version',
+  'algorithm',
+  'kdf',
+  'kdfIterations',
+  'kdfDigest',
+  'salt',
+  'iv',
+  'ciphertext',
+  'authTag',
+  'pepperHash',
+]);
+
+/**
+ * Copy every field the wrapping does not own from an old key file onto a
+ * freshly wrapped one, so rebuilding a `.dbkey` never quietly drops a field
+ * some other part of Quilltap depends on.
+ */
+function preserveExtraFields(existing, fresh) {
+  if (!existing) return fresh;
+  for (const [key, value] of Object.entries(existing)) {
+    if (!KEY_WRAPPER_FIELDS.has(key)) {
+      fresh[key] = value;
+    }
+  }
+  return fresh;
+}
+
+/** Write the key file at mode 0600, creating the data directory if needed. */
+function writeDbKeyFile(dataDir, data) {
+  if (!fs.existsSync(dataDir)) {
+    fs.mkdirSync(dataDir, { recursive: true });
+  }
+  fs.writeFileSync(getDbKeyPath(dataDir), JSON.stringify(data, null, 2), { mode: 0o600 });
+}
+
+module.exports = {
+  DBKEY_FILENAME,
+  INTERNAL_PASSPHRASE,
+  KEY_WRAPPER_FIELDS,
+  preserveExtraFields,
+  PBKDF2_ITERATIONS,
+  getDbKeyPath,
+  hashPepper,
+  readDbKeyFile,
+  decryptDbKey,
+  tryDecryptDbKey,
+  encryptDbKey,
+  writeDbKeyFile,
+};

package/lib/instances-commands.js

@@ -38,6 +38,7 @@ Verbs:
   set-passphrase <name>         Change or clear the stored passphrase
   default [<name>]              Set/show/clear default instance
   rename <old> <new>            Rename an instance (preserves passphrase)
+  restore-key <name>            Rebuild a lost/locked .dbkey from the pepper
   -h, --help                    This help
 
 Storage: ~/Library/Application Support/Quilltap/instances.json on macOS,
@@ -61,6 +62,22 @@ Default Instance:
   quilltap instances default --clear         # clear the default
   quilltap instances default                 # show the current default
 
+Rebuilding a .dbkey:
+  The .dbkey file only WRAPS the pepper — the pepper itself is the database
+  key. So if the file is lost, or its passphrase is forgotten, an operator who
+  still has the pepper can rebuild it:
+
+  quilltap instances restore-key Friday          # pepper from the environment,
+                                                 #   or a hidden prompt
+  quilltap instances restore-key Friday --no-passphrase --yes
+
+  The pepper is read from ENCRYPTION_MASTER_PEPPER or prompted for, never
+  passed as a flag (a command line lands in shell history and in ps output). It is
+  proved against the encrypted databases on disk before anything is written,
+  and the command refuses while the instance lock is held, so run it with the
+  server down. Flags: --passphrase <pass>, --no-passphrase, --data-dir <path>,
+  --force (no encrypted database to prove against), --yes.
+
 Examples:
   quilltap instances add Friday ~/iCloud/Quilltap/Friday
   quilltap instances add Ignite ~/iCloud/Quilltap/Ignite     # prompts for passphrase
@@ -280,6 +297,33 @@ function cmdRename(args) {
   console.log(`Renamed instance "${oldKey}" → "${newKey}".`);
 }
 
+// Rebuild the instance's .dbkey from the pepper — see lib/dbkey-restore.js
+// for why the pepper never arrives as a flag and why the write is proved first.
+async function cmdRestoreKey(args) {
+  const opts = { name: '', dataDir: '', passphrase: undefined, noPassphrase: false, force: false, yes: false };
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    switch (a) {
+      case '-d': case '--data-dir': opts.dataDir = args[++i]; break;
+      case '--passphrase': opts.passphrase = args[++i]; break;
+      case '--no-passphrase': opts.noPassphrase = true; break;
+      case '--force': opts.force = true; break;
+      case '-y': case '--yes': opts.yes = true; break;
+      default:
+        if (a.startsWith('-')) throw new Error(`Unknown flag: ${a}`);
+        if (opts.name) throw new Error('Specify one instance.');
+        opts.name = a;
+        break;
+    }
+  }
+  if (!opts.name && !opts.dataDir) {
+    console.error('Usage: quilltap instances restore-key <name> | --data-dir <instance-root>');
+    process.exit(1);
+  }
+  const { restoreKey } = require('./dbkey-restore');
+  await restoreKey(opts);
+}
+
 async function instancesCommand(args) {
   if (args.length === 0) {
     cmdList();
@@ -328,6 +372,10 @@ async function instancesCommand(args) {
       case 'rename':
         cmdRename(rest);
         return;
+      case 'restore-key':
+      case 'rebuild-key':
+        await cmdRestoreKey(rest);
+        return;
       default:
         console.error(`Unknown instances verb: ${verb}`);
         console.error('Run "quilltap instances --help" for usage.');

package/lib/instances.js

@@ -277,41 +277,17 @@ function renameInstance(oldName, newName) {
 //   'no-dbkey'     — no .dbkey on disk yet (first-run instance)
 //   'no-encryption'— dbkey is unlocked by the internal passphrase, no user one needed
 async function verifyPassphrase(instanceRoot, passphrase) {
-  const crypto = require('crypto');
+  const { INTERNAL_PASSPHRASE, readDbKeyFile, tryDecryptDbKey } = require('./dbkey');
   const dataDir = path.join(expandPath(instanceRoot), 'data');
-  const dbkeyPath = path.join(dataDir, 'quilltap.dbkey');
-  if (!fs.existsSync(dbkeyPath)) {
-    return 'no-dbkey';
-  }
-  const data = JSON.parse(fs.readFileSync(dbkeyPath, 'utf8'));
-  const INTERNAL = '__quilltap_no_passphrase__';
 
-  function tryDecrypt(pass) {
-    const salt = Buffer.from(data.salt, 'hex');
-    const key = crypto.pbkdf2Sync(pass, new Uint8Array(salt), data.kdfIterations, 32, data.kdfDigest);
-    const iv = Buffer.from(data.iv, 'hex');
-    const decipher = crypto.createDecipheriv(data.algorithm, new Uint8Array(key), new Uint8Array(iv));
-    decipher.setAuthTag(new Uint8Array(Buffer.from(data.authTag, 'hex')));
-    let plaintext = decipher.update(data.ciphertext, 'hex', 'utf8');
-    plaintext += decipher.final('utf8');
-    const hash = crypto.createHash('sha256').update(plaintext).digest('hex');
-    if (hash !== data.pepperHash) throw new Error('pepperHash mismatch');
-    return plaintext;
+  const data = readDbKeyFile(dataDir);
+  if (!data) {
+    return 'no-dbkey';
   }
-
-  try {
-    tryDecrypt(INTERNAL);
+  if (tryDecryptDbKey(data, INTERNAL_PASSPHRASE) !== null) {
     return 'no-encryption';
-  } catch {
-    // Falls through — dbkey needs a user passphrase.
-  }
-
-  try {
-    tryDecrypt(passphrase);
-    return 'valid';
-  } catch {
-    return 'wrong';
   }
+  return tryDecryptDbKey(data, passphrase) !== null ? 'valid' : 'wrong';
 }
 
 module.exports = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "quilltap",
-  "version": "4.9.0-dev.92",
+  "version": "4.9.0-dev.93",
   "description": "Self-hosted AI workspace for writers, worldbuilders, and roleplayers. Run with npx quilltap.",
   "author": {
     "name": "Charles Sebold",