@phnx-labs/agents-cli 1.20.17 → 1.20.19

package/dist/lib/secrets/bundles.js

@@ -1,12 +1,18 @@
 /**
- * Secret bundles — named sets of keychain-backed environment variables.
+ * Secret bundles — named sets of environment variables backed by a secret store.
  *
- * Bundle metadata (name, description, vars map) is stored in the macOS
- * Keychain as a JSON blob under `agents-cli.bundles.<name>`. Secret values
- * live one per keychain item under `agents-cli.secrets.<bundle>.<key>`.
- * Every item is device-local and gated by Touch ID / device passcode — see
- * src/lib/secrets/index.ts for the access-control story. Nothing about
- * secrets ever lives in plaintext on disk.
+ * Bundle metadata (name, description, vars map) is stored as a JSON blob under
+ * `agents-cli.bundles.<name>`; secret values live one per item under
+ * `agents-cli.secrets.<bundle>.<key>`. Two backends carry those items:
+ *
+ *  - `keychain` (default): the macOS Keychain (device-local, Touch ID / device
+ *    passcode gated) or Linux libsecret — see src/lib/secrets/index.ts.
+ *  - `file`: an AES-256-GCM encrypted-file store keyed by a passphrase
+ *    (src/lib/secrets/filestore.ts). Opt-in, for headless / remote runs where
+ *    no biometry prompt can be satisfied (e.g. a release on a remote Mac over
+ *    SSH). The item-name scheme is identical, so the only difference is where
+ *    bytes land. A file-backed bundle is discovered by the presence of its
+ *    metadata item in the file store.
  *
  * Cross-machine sync is handled by src/lib/secrets/sync.ts via an explicit
  * encrypted export/import flow; the bundle layer is sync-agnostic.
@@ -16,7 +22,73 @@ import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'yaml';
 import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainToken, listKeychainItems, parseBundleValue, resolveRef, secretsKeychainItem, setKeychainToken, } from './index.js';
+import { fileStore } from './filestore.js';
 import { emit } from '../events.js';
+import { agentGetSync, agentAutoLoadSync, secretsAgentAutoEnabled, DEFAULT_TTL_MS } from './agent.js';
+const keychainStore = {
+    has: hasKeychainToken,
+    get: getKeychainToken,
+    getBatch: getKeychainTokens,
+    set: setKeychainToken,
+    delete: deleteKeychainToken,
+    list: listKeychainItems,
+};
+// The file store auto-provisions a machine-local passphrase on Linux (the
+// existing headless-libsecret fallback) but NEVER on macOS: a file-backed
+// bundle on a Mac must be unlocked with an explicit AGENTS_SECRETS_PASSPHRASE
+// supplied per run, so the box holds ciphertext only. assertFileBackendUsable()
+// enforces that the passphrase is present before we touch the store.
+const FILE_ALLOW_AUTO_PROVISION = process.platform !== 'darwin';
+const fileItemStore = {
+    has: (item) => fileStore.has(item),
+    get: (item) => fileStore.get(item, { allowAutoProvision: FILE_ALLOW_AUTO_PROVISION }),
+    getBatch: (items) => {
+        const out = new Map();
+        for (const item of items) {
+            try {
+                out.set(item, fileStore.get(item, { allowAutoProvision: FILE_ALLOW_AUTO_PROVISION }));
+            }
+            catch {
+                // Missing/undecryptable item — absent from the map, mirroring
+                // getKeychainTokens (caller decides whether that's an error).
+            }
+        }
+        return out;
+    },
+    set: (item, value) => fileStore.set(item, value, { allowAutoProvision: FILE_ALLOW_AUTO_PROVISION }),
+    delete: (item) => fileStore.delete(item),
+    list: (prefix) => fileStore.list(prefix),
+};
+function itemStore(backend) {
+    return backend === 'file' ? fileItemStore : keychainStore;
+}
+/**
+ * Discover a bundle's backend by location: a file-backed bundle's metadata
+ * item exists in the encrypted-file store. This is a plain file-existence
+ * check — no passphrase, no Touch ID — so it sidesteps the chicken-and-egg of
+ * "read metadata to learn where metadata lives." Absent ⇒ keychain.
+ */
+export function bundleBackend(name) {
+    return fileStore.has(BUNDLE_META_PREFIX + name) ? 'file' : 'keychain';
+}
+/**
+ * Guard a file-backed bundle operation. On macOS the file store must be
+ * unlocked with an explicit passphrase (env or interactive prompt) — we refuse
+ * to silently auto-provision a machine-local key there, so a remote/headless
+ * Mac cannot decrypt on its own. Linux keeps the existing auto-provision
+ * behavior, so this is a no-op there.
+ */
+function assertFileBackendUsable(name) {
+    if (process.platform !== 'darwin')
+        return;
+    if (process.env.AGENTS_SECRETS_PASSPHRASE && process.env.AGENTS_SECRETS_PASSPHRASE.length > 0)
+        return;
+    if (process.stdin.isTTY)
+        return;
+    throw new Error(`File-backed bundle '${name}' needs AGENTS_SECRETS_PASSPHRASE to be set on macOS ` +
+        `(no biometry prompt is available headlessly). Set it for this run, e.g.\n` +
+        `  AGENTS_SECRETS_PASSPHRASE=… agents secrets exec ${name} -- <command>`);
+}
 /** Allowed values for a secret's `type` metadata field. */
 export const SECRET_TYPES = [
     'api-key',
@@ -115,15 +187,23 @@ function bundleMetaItem(name) {
 }
 export function bundleExists(name) {
     validateBundleName(name);
-    return hasKeychainToken(bundleMetaItem(name));
+    return itemStore(bundleBackend(name)).has(bundleMetaItem(name));
 }
 export function readBundle(name) {
     validateBundleName(name);
+    const backend = bundleBackend(name);
+    if (backend === 'file')
+        assertFileBackendUsable(name);
     let json;
     try {
-        json = getKeychainToken(bundleMetaItem(name));
+        json = itemStore(backend).get(bundleMetaItem(name));
     }
-    catch {
+    catch (err) {
+        // A file-backed bundle whose metadata is on disk but fails to decrypt is a
+        // wrong-passphrase error, not a missing bundle — surface that clearly.
+        if (backend === 'file' && fileStore.has(bundleMetaItem(name))) {
+            throw new Error(`Bundle '${name}': failed to decrypt — wrong AGENTS_SECRETS_PASSPHRASE or tampered file store. (${err.message})`);
+        }
         throw new Error(`Secrets bundle '${name}' not found.`);
     }
     let parsed;
@@ -137,11 +217,16 @@ export function readBundle(name) {
         throw new Error(`Bundle '${name}' is malformed.`);
     }
     // Unknown fields on the JSON (e.g. legacy sync flags) are silently dropped
-    // here; the SecretsBundle shape is the only source of truth.
+    // here; the SecretsBundle shape is the only source of truth. `backend` is
+    // authoritative from location discovery, not the persisted field.
     const bundle = {
         name,
         description: parsed.description,
         allow_exec: Boolean(parsed.allow_exec),
+        // Absent ⇒ keychain (mirrors `tier`); only set when file-backed so a
+        // keychain bundle round-trips byte-for-byte.
+        backend: backend === 'file' ? 'file' : undefined,
+        tier: parseTier(parsed.tier),
         vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
     };
     if (typeof parsed.created_at === 'string')
@@ -158,8 +243,19 @@ export function readBundle(name) {
     }
     return bundle;
 }
+/** Normalize a persisted `tier` value; anything but `session` ⇒ default tier. */
+function parseTier(raw) {
+    return raw === 'session' ? 'session' : undefined;
+}
+/** The effective tier of a bundle (absent ⇒ `biometry`). */
+export function bundleTier(bundle) {
+    return bundle.tier ?? 'biometry';
+}
 export function writeBundle(bundle) {
     validateBundleName(bundle.name);
+    const backend = bundle.backend ?? 'keychain';
+    if (backend === 'file')
+        assertFileBackendUsable(bundle.name);
     for (const key of Object.keys(bundle.vars)) {
         validateEnvKey(key);
     }
@@ -191,6 +287,8 @@ export function writeBundle(bundle) {
     const payload = {
         description: bundle.description,
         allow_exec: bundle.allow_exec ? true : undefined,
+        backend: backend === 'file' ? 'file' : undefined,
+        tier: bundle.tier === 'session' ? 'session' : undefined,
         created_at: bundle.created_at,
         updated_at: bundle.updated_at,
         last_used: bundle.last_used,
@@ -198,79 +296,109 @@ export function writeBundle(bundle) {
         meta,
     };
     const json = JSON.stringify(payload);
-    setKeychainToken(bundleMetaItem(bundle.name), json);
+    itemStore(backend).set(bundleMetaItem(bundle.name), json);
     emit('secrets.set', { bundle: bundle.name });
 }
 export function deleteBundle(name) {
     validateBundleName(name);
-    const deleted = deleteKeychainToken(bundleMetaItem(name));
+    const deleted = itemStore(bundleBackend(name)).delete(bundleMetaItem(name));
     if (deleted) {
         emit('secrets.delete', { bundle: name });
     }
     return deleted;
 }
+/**
+ * Parse a stored metadata JSON blob into a SecretsBundle, applying the lenient
+ * posture listBundles wants (skip malformed / invalid-key bundles rather than
+ * throw). `backend` is authoritative from where the item was found. Returns
+ * null to skip.
+ */
+function parseBundleMeta(name, json, backend) {
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        return null;
+    }
+    if (!parsed || typeof parsed !== 'object')
+        return null;
+    const bundle = {
+        name,
+        description: parsed.description,
+        allow_exec: Boolean(parsed.allow_exec),
+        backend: backend === 'file' ? 'file' : undefined,
+        tier: parseTier(parsed.tier),
+        vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
+    };
+    if (typeof parsed.created_at === 'string')
+        bundle.created_at = parsed.created_at;
+    if (typeof parsed.updated_at === 'string')
+        bundle.updated_at = parsed.updated_at;
+    if (typeof parsed.last_used === 'string')
+        bundle.last_used = parsed.last_used;
+    if (parsed.meta && typeof parsed.meta === 'object')
+        bundle.meta = parsed.meta;
+    for (const key of Object.keys(bundle.vars)) {
+        if (!ENV_KEY_PATTERN.test(key))
+            return null;
+    }
+    return bundle;
+}
 export function listBundles() {
-    let services;
+    const out = [];
+    // Keychain-backed bundles: batch all metadata reads behind ONE Touch ID
+    // prompt instead of N. Bundle metadata items carry user-presence ACLs (same
+    // as secret values), so a naive loop over readBundle() spawns a fresh
+    // LAContext per item — meaning N biometric prompts for `secrets list`.
+    let keychainServices = [];
     try {
-        services = listKeychainItems(BUNDLE_META_PREFIX);
+        keychainServices = listKeychainItems(BUNDLE_META_PREFIX);
     }
     catch {
-        return [];
+        keychainServices = [];
     }
-    const names = services
+    const keychainNames = keychainServices
         .map((s) => s.slice(BUNDLE_META_PREFIX.length))
         .filter((n) => BUNDLE_NAME_PATTERN.test(n));
-    if (names.length === 0)
-        return [];
-    // Batch all metadata reads behind ONE Touch ID prompt instead of N. Bundle
-    // metadata items carry user-presence ACLs (same as secret values), so a naive
-    // loop over readBundle() spawns a fresh LAContext per item — meaning N
-    // biometric prompts for `secrets list`. Sharing a single context across all
-    // SecItemCopyMatching calls collapses the prompt to one. Mirrors the pattern
-    // already used by resolveBundleEnv for runtime secret injection.
-    const itemsToFetch = names.map(bundleMetaItem);
-    const fetched = getKeychainTokens(itemsToFetch);
-    const out = [];
-    for (const name of names) {
-        const json = fetched.get(bundleMetaItem(name));
-        if (json === undefined)
-            continue;
-        let parsed;
+    if (keychainNames.length > 0) {
+        const fetched = getKeychainTokens(keychainNames.map(bundleMetaItem));
+        for (const name of keychainNames) {
+            const json = fetched.get(bundleMetaItem(name));
+            if (json === undefined)
+                continue;
+            const bundle = parseBundleMeta(name, json, 'keychain');
+            if (bundle)
+                out.push(bundle);
+        }
+    }
+    // File-backed bundles live in the encrypted-file store. Enumeration is a
+    // silent directory listing; only decryption needs the passphrase, so a
+    // `secrets list` without one still shows the names (values stay sealed).
+    let fileServices = [];
+    try {
+        fileServices = fileStore.list(BUNDLE_META_PREFIX);
+    }
+    catch {
+        fileServices = [];
+    }
+    const fileNames = fileServices
+        .map((s) => s.slice(BUNDLE_META_PREFIX.length))
+        .filter((n) => BUNDLE_NAME_PATTERN.test(n));
+    for (const name of fileNames) {
+        let json;
         try {
-            parsed = JSON.parse(json);
+            json = fileItemStore.get(bundleMetaItem(name));
         }
         catch {
-            // Skip malformed bundles; surfaced via `agents secrets view <name>`.
+            // No passphrase (or wrong one): surface the bundle by name so it isn't
+            // invisible, with empty vars. `agents secrets view` reports the error.
+            out.push({ name, backend: 'file', vars: {} });
             continue;
         }
-        if (!parsed || typeof parsed !== 'object')
-            continue;
-        const bundle = {
-            name,
-            description: parsed.description,
-            allow_exec: Boolean(parsed.allow_exec),
-            vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
-        };
-        if (typeof parsed.created_at === 'string')
-            bundle.created_at = parsed.created_at;
-        if (typeof parsed.updated_at === 'string')
-            bundle.updated_at = parsed.updated_at;
-        if (typeof parsed.last_used === 'string')
-            bundle.last_used = parsed.last_used;
-        if (parsed.meta && typeof parsed.meta === 'object')
-            bundle.meta = parsed.meta;
-        // Skip bundles with invalid env keys rather than throwing — same lenient
-        // posture readBundle had via the outer catch.
-        let valid = true;
-        for (const key of Object.keys(bundle.vars)) {
-            if (!ENV_KEY_PATTERN.test(key)) {
-                valid = false;
-                break;
-            }
-        }
-        if (!valid)
-            continue;
-        out.push(bundle);
+        const bundle = parseBundleMeta(name, json, 'file');
+        if (bundle)
+            out.push(bundle);
     }
     return out.sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -326,8 +454,9 @@ export function resolveBundleEnv(bundle, _opts = {}) {
             keychainItemsToFetch.push(secretsKeychainItem(bundle.name, parsed.ref.value));
         }
     }
+    const store = itemStore(bundle.backend ?? 'keychain');
     const fetched = keychainItemsToFetch.length > 0
-        ? getKeychainTokens(keychainItemsToFetch)
+        ? store.getBatch(keychainItemsToFetch)
         : new Map();
     const env = {};
     for (const [key, raw] of Object.entries(bundle.vars)) {
@@ -340,7 +469,7 @@ export function resolveBundleEnv(bundle, _opts = {}) {
             const item = secretsKeychainItem(bundle.name, parsed.ref.value);
             const value = fetched.get(item);
             if (value === undefined) {
-                throw new Error(`Bundle '${bundle.name}' key '${key}': keychain item '${item}' not found. ` +
+                throw new Error(`Bundle '${bundle.name}' key '${key}': stored item '${item}' not found. ` +
                     `Run: agents secrets add ${bundle.name} ${key}`);
             }
             env[key] = value;
@@ -375,11 +504,35 @@ export function resolveBundleEnv(bundle, _opts = {}) {
  */
 export function readAndResolveBundleEnv(name, opts = {}) {
     validateBundleName(name);
+    const backend = bundleBackend(name);
+    // Fast-path: if the secrets-agent holds this bundle (user ran
+    // `agents secrets unlock <name>`), return the cached snapshot with no Touch
+    // ID. Soft — any failure falls through to the real keychain read below. macOS
+    // / keychain only — the agent exists to dedup Touch ID prompts, and a
+    // file-backed bundle has none to dedup. The never-unlocked path is a single
+    // stat (agentSocketExists) so it costs nothing when the agent isn't running.
+    if (backend === 'keychain' && !opts.noAgent && process.env.AGENTS_SECRETS_NO_AGENT !== '1') {
+        const hit = agentGetSync(name);
+        if (hit) {
+            stampLastUsed(hit.bundle);
+            emit('secrets.get', {
+                bundle: name,
+                caller: opts.caller,
+                status: 'success',
+                source: 'agent',
+                keyCount: Object.keys(hit.env).length,
+            });
+            return hit;
+        }
+    }
+    if (backend === 'file')
+        assertFileBackendUsable(name);
+    const store = itemStore(backend);
     const metaItem = bundleMetaItem(name);
     const bundleSecretPrefix = `${SECRETS_ITEM_PREFIX}${name}.`;
     let secretItems;
     try {
-        secretItems = listKeychainItems(bundleSecretPrefix);
+        secretItems = store.list(bundleSecretPrefix);
     }
     catch {
         secretItems = [];
@@ -388,9 +541,16 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         ? `read ${name} secrets (for ${opts.caller})`
         : `read ${name} secrets`;
     void reason;
-    const fetched = getKeychainTokens([metaItem, ...secretItems]);
+    const fetched = store.getBatch([metaItem, ...secretItems]);
     const json = fetched.get(metaItem);
     if (json === undefined) {
+        // For a file-backed bundle the metadata item is on disk (that's how
+        // bundleBackend resolved to 'file'); a missing decrypt means the wrong
+        // passphrase, not a missing bundle. getBatch swallowed the decrypt error,
+        // so distinguish here rather than report a misleading "not found".
+        if (backend === 'file' && fileStore.has(metaItem)) {
+            throw new Error(`Bundle '${name}': failed to decrypt — wrong AGENTS_SECRETS_PASSPHRASE or tampered file store.`);
+        }
         throw new Error(`Secrets bundle '${name}' not found.`);
     }
     let parsed;
@@ -407,6 +567,8 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         name,
         description: parsed.description,
         allow_exec: Boolean(parsed.allow_exec),
+        backend: backend === 'file' ? 'file' : undefined,
+        tier: parseTier(parsed.tier),
         vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
     };
     if (typeof parsed.created_at === 'string')
@@ -459,7 +621,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
                 const item = secretsKeychainItem(bundle.name, p.ref.value);
                 const value = fetched.get(item);
                 if (value === undefined) {
-                    throw new Error(`Bundle '${bundle.name}' key '${key}': keychain item '${item}' not found. ` +
+                    throw new Error(`Bundle '${bundle.name}' key '${key}': stored item '${item}' not found. ` +
                         `Run: agents secrets add ${bundle.name} ${key}`);
                 }
                 env[key] = value;
@@ -476,6 +638,18 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             }
         }
         emitReadAudit('success');
+        // Auto-cache: this was a real keychain read (the agent fast-path returned
+        // earlier on a hit). If the bundle opts into the session tier and the user
+        // enabled `secrets.agent.auto`, populate the broker in the background so the
+        // next concurrent run reads silently. Skipped when noAgent (e.g. `unlock`,
+        // which loads the agent itself). Fire-and-forget — never blocks this read.
+        if (backend === 'keychain' &&
+            !opts.noAgent &&
+            process.env.AGENTS_SECRETS_NO_AGENT !== '1' &&
+            bundleTier(bundle) === 'session' &&
+            secretsAgentAutoEnabled()) {
+            agentAutoLoadSync(name, bundle, env, DEFAULT_TTL_MS);
+        }
         return { bundle, env };
     }
     catch (err) {
@@ -506,7 +680,7 @@ export function rotateBundleSecret(bundle, key, opts) {
     }
     const shortId = raw.slice('keychain:'.length);
     const item = secretsKeychainItem(bundle.name, shortId);
-    setKeychainToken(item, opts.newValue);
+    itemStore(bundle.backend ?? 'keychain').set(item, opts.newValue);
     if (opts.clearMeta) {
         if (bundle.meta)
             delete bundle.meta[key];
@@ -550,13 +724,17 @@ export function renameBundle(oldName, newName, opts = {}) {
         throw new Error(`Bundle '${oldName}' not found.`);
     }
     const source = readBundle(oldName);
+    // Rename stays within the source's backend. The store carries both the
+    // per-key secret items and (via writeBundle/deleteBundle) the metadata.
+    const store = itemStore(source.backend ?? 'keychain');
     if (bundleExists(newName)) {
         if (!opts.force) {
             throw new Error(`Bundle '${newName}' already exists. Use --force to overwrite.`);
         }
         const dest = readBundle(newName);
+        const destStore = itemStore(dest.backend ?? 'keychain');
         for (const { item } of keychainItemsForBundle(dest)) {
-            deleteKeychainToken(item);
+            destStore.delete(item);
         }
         deleteBundle(newName);
     }
@@ -569,19 +747,30 @@ export function renameBundle(oldName, newName, opts = {}) {
             continue;
         const shortId = raw.slice('keychain:'.length);
         const newItem = secretsKeychainItem(newName, shortId);
-        const value = getKeychainToken(oldItem);
-        setKeychainToken(newItem, value);
+        const value = store.get(oldItem);
+        store.set(newItem, value);
     }
-    // writeBundle preserves source.created_at and refreshes updated_at.
+    // writeBundle preserves source.created_at, refreshes updated_at, and keeps
+    // the source backend (spread carries source.backend).
     const renamed = { ...source, name: newName };
     writeBundle(renamed);
-    // Cleanup: delete the old per-key keychain items, then the old metadata.
+    // Cleanup: delete the old per-key items, then the old metadata.
     for (const { item: oldItem } of sourceItems) {
-        deleteKeychainToken(oldItem);
+        store.delete(oldItem);
     }
     deleteBundle(oldName);
     emit('secrets.rename', { from: oldName, to: newName });
 }
+/**
+ * The store (keychain or encrypted file) that carries a bundle's items. The
+ * CLI uses this to read/write/delete per-key items (built with
+ * secretsKeychainItem) in the same store as the bundle's metadata, for `add` /
+ * `import` / `remove` / `delete`. Pass the bundle's resolved backend
+ * (`bundle.backend ?? 'keychain'`).
+ */
+export function bundleItemStore(backend) {
+    return itemStore(backend ?? 'keychain');
+}
 // Iterate all keychain-backed keys in a bundle for cleanup on rm/unset.
 export function keychainItemsForBundle(bundle) {
     const items = [];

package/dist/lib/secrets/filestore.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Passphrase-encrypted file store for secrets — platform-neutral.
+ *
+ * An AES-256-GCM encrypted-file store under `~/.agents/.cache/secrets/`. The
+ * encryption key is scrypt-derived from a passphrase read from
+ * `AGENTS_SECRETS_PASSPHRASE` (preferred), a machine-local provisioned key, or
+ * a TTY prompt. One `<item>.enc` JSON file per item, mode 0600.
+ *
+ * Two callers:
+ *  - Linux (src/lib/secrets/linux.ts): the headless fallback when the default
+ *    Secret Service collection is locked. Auto-provisions a machine-local
+ *    passphrase so `agents secrets` works out of the box on a server.
+ *  - macOS file-backed bundles (src/lib/secrets/bundles.ts): an explicit,
+ *    opt-in non-biometry backend for headless/remote release runs. The bundle
+ *    layer guards this path so it only activates with an explicit
+ *    AGENTS_SECRETS_PASSPHRASE (or TTY) — never the silent machine-local
+ *    auto-provision — so a remote box holds ciphertext only.
+ *
+ * The item-name scheme is shared with the keychain backend so a file-backed
+ * item and its keychain twin carry identical names:
+ *   `agents-cli.bundles.<name>` and `agents-cli.secrets.<bundle>.<key>`.
+ */
+import type { KeychainBackend } from './index.js';
+export declare function fileDir(): string;
+/** True if a machine-local passphrase has already been provisioned. */
+export declare function machinePassphraseExists(): boolean;
+/**
+ * Resolve the passphrase for the encrypted file store.
+ *
+ * Order: AGENTS_SECRETS_PASSPHRASE > previously-provisioned machine-local key >
+ * (interactive) TTY prompt > (headless) auto-provisioned machine-local key.
+ *
+ * `allowAutoProvision` (default true, used by the Linux fallback) controls the
+ * last two steps. macOS file-backed bundles pass `false` so a missing
+ * passphrase is a hard, explicit error instead of a silently provisioned
+ * on-disk key — the caller (bundles.ts) guards this before we get here.
+ */
+export declare function getPassphrase(opts?: {
+    allowAutoProvision?: boolean;
+}): string;
+/** Encrypted-file on-disk shape. Exported for tests. */
+export interface EncFile {
+    salt: string;
+    iv: string;
+    authTag: string;
+    ciphertext: string;
+}
+/** Encrypt plaintext under a passphrase using AES-256-GCM with a random
+ *  scrypt salt and a random 96-bit IV. Exported for tests. */
+export declare function encryptForFallback(plaintext: string, passphrase: string): EncFile;
+/** Decrypt an EncFile under a passphrase. Throws on wrong key or tampered
+ *  ciphertext (auth-tag mismatch). Exported for tests. */
+export declare function decryptForFallback(enc: EncFile, passphrase: string): string;
+declare function fileHas(item: string): boolean;
+declare function fileGet(item: string, opts?: {
+    allowAutoProvision?: boolean;
+}): string;
+declare function fileSet(item: string, value: string, opts?: {
+    allowAutoProvision?: boolean;
+}): void;
+declare function fileDelete(item: string): boolean;
+declare function fileList(prefix: string): string[];
+/** True if the fallback dir has any committed encrypted items. */
+export declare function fileStoreHasItems(): boolean;
+/** Low-level file-store ops, exported so callers (linux fallback, macOS
+ *  file-backed bundles) can opt into or out of passphrase auto-provision. */
+export declare const fileStore: {
+    has: typeof fileHas;
+    get: typeof fileGet;
+    set: typeof fileSet;
+    delete: typeof fileDelete;
+    list: typeof fileList;
+};
+/** File-only KeychainBackend (exported for tests; the Linux backend uses these
+ *  ops with auto-provision allowed). */
+export declare const fileBackend: KeychainBackend;
+/** Test-only: reset module state (file dir + cached passphrase). */
+export declare function _resetFileStoreForTest(opts?: {
+    fileDir?: string | null;
+    passphrase?: string | null;
+}): void;
+export {};