moflo 4.9.18 → 4.9.20

package/dist/src/cli/commands/spell-credentials.js

@@ -0,0 +1,248 @@
+/**
+ * Spell Credentials CLI
+ *
+ * `moflo spell credentials list/set/unset/clear/passphrase` — manage the
+ * encrypted credential store the spell runner uses for unattended casts.
+ *
+ * Story #925 (epic #880).
+ */
+import { existsSync } from 'node:fs';
+import { output } from '../output.js';
+import { confirm, input } from '../prompt.js';
+import { CredentialStore, CredentialStoreError, MIN_PASSPHRASE_LENGTH, resolveCredentialFilePath, resolvePassphrase, } from '../spells/credentials/index.js';
+/**
+ * Build a CredentialStore using the runner's passphrase resolution.
+ * Returns null when no passphrase is available — caller surfaces the actionable error.
+ */
+function openStore() {
+    const filePath = resolveCredentialFilePath();
+    const passphrase = resolvePassphrase();
+    if (!passphrase)
+        return null;
+    try {
+        return new CredentialStore({ filePath, passphrase });
+    }
+    catch (err) {
+        output.printError(`Could not open credential store: ${err.message}`);
+        return null;
+    }
+}
+function noStoreError() {
+    output.printError('Credential store is locked.');
+    output.writeln('');
+    output.writeln('  Set MOFLO_CREDENTIALS_PASSPHRASE in your environment, or run:');
+    output.writeln('    flo spell credentials passphrase');
+    output.writeln('');
+    output.writeln('  to initialise a per-machine encryption key.');
+    return { success: false, exitCode: 1 };
+}
+const listCommand = {
+    name: 'list',
+    aliases: ['ls'],
+    description: 'List stored credential names (never values)',
+    action: async (ctx) => {
+        const store = openStore();
+        if (!store)
+            return noStoreError();
+        const meta = await store.list();
+        if (ctx.flags.format === 'json') {
+            output.printJson(meta);
+            return { success: true, data: meta };
+        }
+        if (meta.length === 0) {
+            output.printInfo('No credentials stored. Use `flo spell credentials set <name>` to add one.');
+            return { success: true };
+        }
+        output.writeln();
+        output.writeln(output.bold('Stored credentials'));
+        output.writeln();
+        output.printTable({
+            columns: [
+                { key: 'name', header: 'Name', width: 28 },
+                { key: 'description', header: 'Description', width: 35, format: (v) => v ? String(v) : '-' },
+                { key: 'updatedAt', header: 'Updated', width: 22, format: (v) => v ? new Date(String(v)).toLocaleString() : '-' },
+            ],
+            data: meta,
+        });
+        output.writeln();
+        output.printInfo(`${meta.length} credential${meta.length === 1 ? '' : 's'}`);
+        return { success: true, data: meta };
+    },
+};
+const setCommand = {
+    name: 'set',
+    description: 'Store a credential (prompts for the value with hidden input)',
+    options: [
+        { name: 'description', short: 'd', description: 'Optional description', type: 'string' },
+    ],
+    examples: [
+        { command: 'moflo spell credentials set GRAPH_ACCESS_TOKEN', description: 'Store the Graph token' },
+        { command: 'moflo spell credentials set SLACK_WEBHOOK_URL --description "OAP target"', description: 'With a description' },
+    ],
+    action: async (ctx) => {
+        const name = ctx.args[0];
+        if (!name) {
+            output.printError('Credential name is required (e.g. `flo spell credentials set TOKEN`)');
+            return { success: false, exitCode: 1 };
+        }
+        const store = openStore();
+        if (!store)
+            return noStoreError();
+        if (!ctx.interactive) {
+            output.printError('`set` requires an interactive TTY (the value is entered with hidden input).');
+            return { success: false, exitCode: 1 };
+        }
+        const value = await input({ message: `Value for ${name}:`, mask: true });
+        if (!value) {
+            output.printError('No value entered — credential not stored.');
+            return { success: false, exitCode: 1 };
+        }
+        const description = ctx.flags.description;
+        await store.store(name, value, description);
+        output.printSuccess(`Stored credential ${output.highlight(name)}.`);
+        return { success: true };
+    },
+};
+const unsetCommand = {
+    name: 'unset',
+    aliases: ['delete', 'rm'],
+    description: 'Remove a single credential',
+    action: async (ctx) => {
+        const name = ctx.args[0];
+        if (!name) {
+            output.printError('Credential name is required (e.g. `flo spell credentials unset TOKEN`)');
+            return { success: false, exitCode: 1 };
+        }
+        const store = openStore();
+        if (!store)
+            return noStoreError();
+        const removed = await store.delete(name);
+        if (!removed) {
+            output.printError(`Credential ${output.highlight(name)} not found.`);
+            return { success: false, exitCode: 1 };
+        }
+        output.printSuccess(`Removed credential ${output.highlight(name)}.`);
+        return { success: true };
+    },
+};
+const clearCommand = {
+    name: 'clear',
+    description: 'Remove all stored credentials',
+    options: [
+        { name: 'force', short: 'f', description: 'Skip confirmation', type: 'boolean', default: false },
+    ],
+    action: async (ctx) => {
+        const store = openStore();
+        if (!store)
+            return noStoreError();
+        const meta = await store.list();
+        if (meta.length === 0) {
+            output.printInfo('No credentials to clear.');
+            return { success: true };
+        }
+        if (!ctx.flags.force) {
+            if (!ctx.interactive) {
+                output.printError('Refusing to clear without --force in non-interactive mode.');
+                return { success: false, exitCode: 1 };
+            }
+            const ok = await confirm({
+                message: `Delete all ${meta.length} stored credential${meta.length === 1 ? '' : 's'}?`,
+                default: false,
+            });
+            if (!ok) {
+                output.printInfo('Cancelled.');
+                return { success: true };
+            }
+        }
+        const removed = await store.clear();
+        output.printSuccess(`Removed ${removed} credential${removed === 1 ? '' : 's'}.`);
+        return { success: true };
+    },
+};
+const passphraseCommand = {
+    name: 'passphrase',
+    aliases: ['init', 'rotate'],
+    description: 'Initialise the credential store passphrase, or rotate an existing one',
+    action: async (ctx) => {
+        if (!ctx.interactive) {
+            output.printError('`passphrase` requires an interactive TTY.');
+            return { success: false, exitCode: 1 };
+        }
+        const filePath = resolveCredentialFilePath();
+        const exists = existsSync(filePath);
+        const minHint = `(min ${MIN_PASSPHRASE_LENGTH} chars)`;
+        if (!exists) {
+            const newPass = await input({ message: `Choose a passphrase ${minHint}:`, mask: true });
+            const confirmed = await input({ message: 'Confirm passphrase:', mask: true });
+            if (newPass !== confirmed) {
+                output.printError('Passphrases do not match.');
+                return { success: false, exitCode: 1 };
+            }
+            try {
+                const store = new CredentialStore({ filePath, passphrase: newPass });
+                // Force a salted file write so the chosen passphrase locks the store.
+                await store.store('__init__', 'init');
+                await store.delete('__init__');
+            }
+            catch (err) {
+                if (err instanceof CredentialStoreError && err.code === 'WEAK_PASSPHRASE') {
+                    output.printError(err.message);
+                    return { success: false, exitCode: 1 };
+                }
+                throw err;
+            }
+            output.printSuccess(`Initialised credential store at ${filePath}`);
+            output.printInfo('Set MOFLO_CREDENTIALS_PASSPHRASE in your environment to keep schedules running unattended.');
+            return { success: true };
+        }
+        const oldPass = await input({ message: 'Current passphrase:', mask: true });
+        const newPass = await input({ message: `New passphrase ${minHint}:`, mask: true });
+        const confirmed = await input({ message: 'Confirm new passphrase:', mask: true });
+        if (newPass !== confirmed) {
+            output.printError('Passphrases do not match.');
+            return { success: false, exitCode: 1 };
+        }
+        try {
+            const store = new CredentialStore({ filePath, passphrase: oldPass });
+            await store.rotate(oldPass, newPass);
+        }
+        catch (err) {
+            if (err instanceof CredentialStoreError) {
+                output.printError(err.message);
+                return { success: false, exitCode: 1 };
+            }
+            throw err;
+        }
+        output.printSuccess('Passphrase rotated. Update MOFLO_CREDENTIALS_PASSPHRASE if you set it in your environment.');
+        return { success: true };
+    },
+};
+export const spellCredentialsCommand = {
+    name: 'credentials',
+    aliases: ['creds'],
+    description: 'Manage the encrypted credential store used for unattended spell casts',
+    subcommands: [listCommand, setCommand, unsetCommand, clearCommand, passphraseCommand],
+    options: [],
+    examples: [
+        { command: 'moflo spell credentials list', description: 'Show stored credential names' },
+        { command: 'moflo spell credentials set GRAPH_TOKEN', description: 'Store a credential' },
+        { command: 'moflo spell credentials unset GRAPH_TOKEN', description: 'Remove a credential' },
+        { command: 'moflo spell credentials clear --force', description: 'Wipe all credentials' },
+    ],
+    action: async () => {
+        output.writeln();
+        output.writeln(output.bold('Spell Credentials'));
+        output.writeln();
+        output.writeln('Usage: moflo spell credentials <subcommand>');
+        output.writeln();
+        output.printList([
+            `${output.highlight('list')}        - List stored credential names`,
+            `${output.highlight('set')}         - Store a credential (hidden input)`,
+            `${output.highlight('unset')}       - Remove a single credential`,
+            `${output.highlight('clear')}       - Remove all stored credentials`,
+            `${output.highlight('passphrase')}  - Initialise or rotate the passphrase`,
+        ]);
+        return { success: true };
+    },
+};
+//# sourceMappingURL=spell-credentials.js.map

package/dist/src/cli/commands/spell.js

@@ -13,6 +13,7 @@ import { callMCPTool } from '../mcp-client.js';
 import { TOOL_SPELL_CAST, TOOL_SPELL_LIST, TOOL_SPELL_STATUS, TOOL_SPELL_CANCEL, TOOL_SPELL_TEMPLATE, } from '../mcp-tools/tool-names.js';
 import { formatStatus, handleMCPError } from '../services/cli-formatters.js';
 import { scheduleCommand } from './spell-schedule.js';
+import { spellCredentialsCommand } from './spell-credentials.js';
 import { loadSpellEngine } from '../services/engine-loader.js';
 // Re-export formatStatus as formatStageStatus for table column references
 const formatStageStatus = formatStatus;
@@ -587,7 +588,7 @@ export const spellCommand = {
     name: 'spell',
     aliases: ['workflow'],
     description: 'Spell casting and management',
-    subcommands: [castCommand, validateCommand, listCommand, statusCommand, stopCommand, templateCommand, scheduleCommand],
+    subcommands: [castCommand, validateCommand, listCommand, statusCommand, stopCommand, templateCommand, scheduleCommand, spellCredentialsCommand],
     options: [],
     examples: [
         { command: 'moflo spell cast -n development', description: 'Cast spell by name' },
@@ -609,8 +610,9 @@ export const spellCommand = {
             `${output.highlight('list')}      - List spells (grimoire + casts)`,
             `${output.highlight('status')}    - Show spell status`,
             `${output.highlight('stop')}      - Dispel a running spell`,
-            `${output.highlight('template')}  - Browse grimoire templates`,
-            `${output.highlight('schedule')}  - Manage scheduled spells`,
+            `${output.highlight('template')}    - Browse grimoire templates`,
+            `${output.highlight('schedule')}    - Manage scheduled spells`,
+            `${output.highlight('credentials')} - Manage stored secrets for unattended casts`,
         ]);
         output.writeln();
         output.writeln('Run "moflo spell <subcommand> --help" for more info');

package/dist/src/cli/services/moflo-paths.js

@@ -19,6 +19,7 @@
  * `cli/services/cherry-pick-learnings.ts` and is dynamically imported from
  * the compiled `dist/` by the launcher.
  */
+import { homedir } from 'node:os';
 import { join } from 'node:path';
 export const MOFLO_DIR = '.moflo';
 /** Canonical memory DB filename (post-#727). Lives at `<root>/.moflo/moflo.db`. */
@@ -39,6 +40,10 @@ export const LEGACY_MEMORY_DB_BAK_SUFFIX = '.bak';
 export function mofloDir(projectRoot) {
     return join(projectRoot, MOFLO_DIR);
 }
+/** User-scope MoFlo state dir: `~/.moflo`. Holds credentials and other per-machine state. */
+export function mofloHomeDir() {
+    return join(homedir(), MOFLO_DIR);
+}
 export function legacyClaudeFlowDir(projectRoot) {
     return join(projectRoot, LEGACY_CLAUDE_FLOW_DIR);
 }

package/dist/src/cli/spells/commands/prompt-command.js

@@ -46,6 +46,10 @@ export const promptCommand = {
                 type: 'number',
                 description: 'Used when default resolves to empty/null — produces ISO timestamp N days ago',
             },
+            saveAs: {
+                type: 'string',
+                description: 'Persist the response under this name in the credential store; later casts read it back without prompting',
+            },
         },
         required: ['message'],
     },
@@ -65,11 +69,41 @@ export const promptCommand = {
         if (config.fallbackDaysAgo !== undefined && typeof config.fallbackDaysAgo !== 'number') {
             errors.push({ path: 'fallbackDaysAgo', message: 'fallbackDaysAgo must be a number' });
         }
+        if (config.saveAs !== undefined && typeof config.saveAs !== 'string') {
+            errors.push({ path: 'saveAs', message: 'saveAs must be a string' });
+        }
+        if (typeof config.saveAs === 'string' && config.saveAs.trim().length === 0) {
+            errors.push({ path: 'saveAs', message: 'saveAs cannot be empty' });
+        }
         return { valid: errors.length === 0, errors };
     },
     async execute(config, context) {
         const start = Date.now();
         const message = interpolateString(config.message, context);
+        const saveAs = config.saveAs?.trim();
+        if (saveAs) {
+            try {
+                const stored = await context.credentials.get(saveAs);
+                if (typeof stored === 'string' && stored.length > 0) {
+                    return {
+                        success: true,
+                        data: {
+                            message,
+                            options: config.options ?? null,
+                            outputVar: config.outputVar ?? 'response',
+                            response: stored,
+                            default: '',
+                            interactive: false,
+                            fromStore: true,
+                        },
+                        duration: Date.now() - start,
+                    };
+                }
+            }
+            catch {
+                // Store unavailable — fall through to normal prompt path.
+            }
+        }
         // Interpolate default — pure-ref interpolation may yield null; tolerate it.
         let interpolatedDefault = null;
         if (typeof config.default === 'string') {
@@ -96,6 +130,15 @@ export const promptCommand = {
                 lock.release();
             }
         }
+        // Best-effort persist — a failed save shouldn't fail a cast that already has a working answer.
+        if (saveAs && interactive && response) {
+            try {
+                await context.credentials.store(saveAs, response);
+            }
+            catch (err) {
+                console.warn(`[moflo:credentials] could not persist "${saveAs}": ${err.message}`);
+            }
+        }
         return {
             success: true,
             data: {
@@ -105,6 +148,7 @@ export const promptCommand = {
                 response,
                 default: effectiveDefault,
                 interactive,
+                fromStore: false,
             },
             duration: Date.now() - start,
         };
@@ -116,6 +160,7 @@ export const promptCommand = {
             { name: 'outputVar', type: 'string' },
             { name: 'default', type: 'string', description: 'Effective default after fallback chain' },
             { name: 'interactive', type: 'boolean', description: 'Whether the user was actually prompted' },
+            { name: 'fromStore', type: 'boolean', description: 'True when the response was returned from the credential store' },
         ];
     },
 };

package/dist/src/cli/spells/core/prerequisite-checker.js

@@ -151,17 +151,25 @@ export function formatPrerequisiteErrors(results) {
         return '';
     const lines = ['Missing prerequisites:'];
     for (const f of failed) {
-        lines.push(`  - ${f.name}: ${f.installHint}`);
-        if (f.url)
-            lines.push(`    ${f.url}`);
+        appendPrereqLine(lines, f.name, f.installHint, f.url);
     }
     return lines.join('\n');
 }
+function appendPrereqLine(lines, name, hint, url) {
+    const hintSuffix = hint ? `: ${hint}` : '';
+    lines.push(`  - ${name}${hintSuffix}`);
+    if (url)
+        lines.push(`    ${url}`);
+}
 /**
- * Evaluate all prereqs. On a TTY, prompts the user for unmet env-type prereqs
- * whose spec opted into `promptOnMissing`, writes answers into process.env,
- * then re-checks. Non-TTY calls and non-promptable unmet prereqs short-circuit
- * to a single formatted failure report.
+ * Evaluate all prereqs. Resolution chain for env-type prereqs:
+ *   1. process.env[key] already set → satisfied.
+ *   2. credentials.get(key) returns a value → write to process.env, satisfied.
+ *   3. TTY interactive → prompt → write to process.env AND credentials.store.
+ *   4. Non-TTY or no credentials → fail fast with `errorCode: 'MISSING_CREDENTIAL'`.
+ *
+ * Non-env prereqs (`command`, `file`) bypass the credential chain and surface
+ * through the standard "Missing prerequisites" path.
  */
 export async function resolveUnmetPrerequisites(prerequisites, options = {}) {
     if (prerequisites.length === 0) {
@@ -170,22 +178,58 @@ export async function resolveUnmetPrerequisites(prerequisites, options = {}) {
     const interactive = options.interactive
         ?? Boolean(process.stdin.isTTY && process.stdout.isTTY);
     const log = options.log ?? ((line) => console.log(line));
+    const credentials = options.credentials;
     const initial = await checkPrerequisites(prerequisites);
-    const unmet = prerequisites.filter((_, i) => !initial[i].satisfied);
-    if (unmet.length === 0) {
+    const unmetIndices = initial.flatMap((r, i) => r.satisfied ? [] : [i]);
+    if (unmetIndices.length === 0) {
         return { ok: true, resolvedNames: [] };
     }
-    const promptable = unmet.filter(p => interactive && p.promptOnMissing === true && typeof p.envKey === 'string');
+    // Pull env-type prereqs from the store in parallel — each resolved index
+    // lets us skip a re-check of the cheap env detector.
+    const resolvedFromStoreNames = [];
+    const storeResolved = new Set();
+    if (credentials) {
+        await Promise.all(unmetIndices.map(async (i) => {
+            const prereq = prerequisites[i];
+            if (!prereq.envKey)
+                return;
+            const stored = await credentials.get(prereq.envKey);
+            if (typeof stored === 'string' && stored.length > 0) {
+                process.env[prereq.envKey] = stored;
+                storeResolved.add(i);
+                resolvedFromStoreNames.push(prereq.name);
+            }
+        }));
+    }
+    const stillUnmetIdx = unmetIndices.filter(i => !storeResolved.has(i));
+    if (stillUnmetIdx.length === 0) {
+        return { ok: true, resolvedNames: resolvedFromStoreNames };
+    }
+    const stillUnmet = stillUnmetIdx.map(i => prerequisites[i]);
+    const promptable = stillUnmet.filter(p => interactive && p.promptOnMissing === true && typeof p.envKey === 'string');
     if (!interactive || promptable.length === 0) {
+        const promptableEnvKeys = stillUnmet
+            .filter(p => p.promptOnMissing === true && typeof p.envKey === 'string')
+            .map(p => p.envKey);
+        if (promptableEnvKeys.length > 0) {
+            return {
+                ok: false,
+                message: formatMissingCredentialMessage(promptableEnvKeys, stillUnmet),
+                resolvedNames: resolvedFromStoreNames,
+                errorCode: 'MISSING_CREDENTIAL',
+                missingCredentials: promptableEnvKeys,
+            };
+        }
         return {
             ok: false,
-            message: formatPrerequisiteErrors(initial),
-            resolvedNames: [],
+            message: formatPrerequisiteErrors(stillUnmetIdx.map(i => initial[i])),
+            resolvedNames: resolvedFromStoreNames,
         };
     }
-    printPreflightBanner(log, unmet.length);
+    printPreflightBanner(log, stillUnmet.length);
     const promptLine = options.promptLine ?? readLineFromStdin;
-    const resolvedNames = [];
+    const promptedNames = [];
+    const promptableSet = new Set(promptable);
     const lock = acquireTTYLock();
     try {
         for (const prereq of promptable) {
@@ -193,7 +237,7 @@ export async function resolveUnmetPrerequisites(prerequisites, options = {}) {
                 return {
                     ok: false,
                     message: 'Prerequisite resolution aborted',
-                    resolvedNames,
+                    resolvedNames: [...resolvedFromStoreNames, ...promptedNames],
                 };
             }
             if (prereq.description)
@@ -209,37 +253,56 @@ export async function resolveUnmetPrerequisites(prerequisites, options = {}) {
                 return {
                     ok: false,
                     message: `Prerequisite "${prereq.name}" prompt failed: ${err.message}`,
-                    resolvedNames,
+                    resolvedNames: [...resolvedFromStoreNames, ...promptedNames],
                 };
             }
             if (!answer || answer.length === 0) {
                 return {
                     ok: false,
                     message: `Prerequisite "${prereq.name}" was not provided`,
-                    resolvedNames,
+                    resolvedNames: [...resolvedFromStoreNames, ...promptedNames],
                 };
             }
             if (prereq.envKey) {
                 process.env[prereq.envKey] = answer;
+                if (credentials) {
+                    try {
+                        await credentials.store(prereq.envKey, answer);
+                    }
+                    catch (err) {
+                        log(`  (could not persist credential "${prereq.envKey}": ${err.message})`);
+                    }
+                }
             }
-            resolvedNames.push(prereq.name);
+            promptedNames.push(prereq.name);
         }
     }
     finally {
         lock.release();
     }
-    // Re-check everything — any still unmet (e.g. command/file prereqs that
-    // couldn't be resolved via prompt) fail now with the up-to-date report.
-    const rerun = await checkPrerequisites(prerequisites);
-    const stillUnmet = rerun.filter(r => !r.satisfied);
-    if (stillUnmet.length > 0) {
+    // Anything in stillUnmet that wasn't promptable (typically command/file
+    // prereqs) is still broken — carry forward the initial detector result.
+    const unfixableIdx = stillUnmetIdx.filter(i => !promptableSet.has(prerequisites[i]));
+    if (unfixableIdx.length > 0) {
         return {
             ok: false,
-            message: formatPrerequisiteErrors(rerun),
-            resolvedNames,
+            message: formatPrerequisiteErrors(unfixableIdx.map(i => initial[i])),
+            resolvedNames: [...resolvedFromStoreNames, ...promptedNames],
         };
     }
-    return { ok: true, resolvedNames };
+    return { ok: true, resolvedNames: [...resolvedFromStoreNames, ...promptedNames] };
+}
+function formatMissingCredentialMessage(envKeys, prereqs) {
+    const lines = ['Missing credentials (cannot prompt — non-interactive run):'];
+    for (const key of envKeys) {
+        const prereq = prereqs.find(p => p.envKey === key);
+        const label = `${prereq?.name ?? key} (${key})`;
+        appendPrereqLine(lines, label, prereq?.installHint, prereq?.url);
+    }
+    lines.push('');
+    lines.push('Prime these by casting the spell once interactively, or run:');
+    lines.push('  flo spell credentials set <name>');
+    return lines.join('\n');
 }
 function printPreflightBanner(log, unmetCount) {
     log('');

package/dist/src/cli/spells/core/runner.js

@@ -99,17 +99,18 @@ export class SpellCaster {
                 }
             }
         }
-        // Pre-flight prerequisite checks — walks YAML + step-command sources,
-        // prompts on a TTY for unmet env-type prereqs (issue #460).
+        // Pre-flight prerequisite checks (issue #460) — walks YAML + step-command
+        // sources, pulls from credential store, prompts on TTY, persists answers.
         if (!options.dryRun) {
             const prerequisites = collectPrerequisites(definition, this.registry);
             if (prerequisites.length > 0) {
                 const resolution = await resolveUnmetPrerequisites(prerequisites, {
                     abortSignal: options.signal,
+                    credentials: this.credentials,
                 });
                 if (!resolution.ok) {
                     return this.failureResult(spellId, startTime, [{
-                            code: 'PREREQUISITES_FAILED',
+                            code: resolution.errorCode ?? 'PREREQUISITES_FAILED',
                             message: resolution.message ?? 'Prerequisites failed',
                         }], definition.name);
                 }

package/dist/src/cli/spells/credentials/credential-store.js

@@ -20,6 +20,8 @@ const SALT_BYTES = 32;
 const KEY_BYTES = 32;
 const PBKDF2_ITERATIONS = 100_000;
 const PBKDF2_DIGEST = 'sha512';
+/** User-typeable floor for any passphrase that protects the store. */
+export const MIN_PASSPHRASE_LENGTH = 8;
 // ============================================================================
 // Encryption Helpers
 // ============================================================================
@@ -64,8 +66,8 @@ export class CredentialStore {
      * Derives the encryption key and loads existing data.
      */
     unlock(passphrase) {
-        if (passphrase.length < 8) {
-            throw new CredentialStoreError('Passphrase must be at least 8 characters', 'WEAK_PASSPHRASE');
+        if (passphrase.length < MIN_PASSPHRASE_LENGTH) {
+            throw new CredentialStoreError(`Passphrase must be at least ${MIN_PASSPHRASE_LENGTH} characters`, 'WEAK_PASSPHRASE');
         }
         this.data = this.readFile();
         const salt = Buffer.from(this.data.salt, 'hex');
@@ -132,6 +134,20 @@ export class CredentialStore {
         this.writeFile(this.data);
         return true;
     }
+    /**
+     * Remove every credential in a single write — preferred over a delete loop
+     * because each `delete()` rewrites the entire encrypted file.
+     * Returns the number of credentials removed.
+     */
+    async clear() {
+        this.ensureUnlocked();
+        const count = Object.keys(this.data.credentials).length;
+        if (count === 0)
+            return 0;
+        this.data.credentials = {};
+        this.writeFile(this.data);
+        return count;
+    }
     /**
      * List credential metadata (names + descriptions, never values).
      */
@@ -168,8 +184,8 @@ export class CredentialStore {
      * and derived key, re-encrypts everything, and writes atomically.
      */
     async rotate(oldPassphrase, newPassphrase) {
-        if (newPassphrase.length < 8) {
-            throw new CredentialStoreError('Passphrase must be at least 8 characters', 'WEAK_PASSPHRASE');
+        if (newPassphrase.length < MIN_PASSPHRASE_LENGTH) {
+            throw new CredentialStoreError(`Passphrase must be at least ${MIN_PASSPHRASE_LENGTH} characters`, 'WEAK_PASSPHRASE');
         }
         // Verify old passphrase by unlocking with it
         const fileData = this.readFile();