@phnx-labs/agents-cli 1.20.35 → 1.20.37

package/dist/lib/secrets/bundles.js

@@ -257,6 +257,8 @@ function parsePolicy(raw) {
         return 'daily';
     if (raw === 'always' || raw === 'biometry')
         return 'always';
+    if (raw === 'never' || raw === 'none')
+        return 'never';
     return undefined;
 }
 /** The default prompt policy applied to bundles without an explicit per-bundle
@@ -314,9 +316,14 @@ export function writeBundle(bundle) {
         backend: backend === 'file' ? 'file' : undefined,
         // Wire format: persist the policy under the legacy `tier` token so older CLI
         // versions on other synced machines keep reading it — `daily`⇒`session`,
-        // explicit `always`⇒`biometry`. An absent policy omits the token entirely
-        // and resolves to the configured default (`daily`) on read.
-        tier: bundle.policy === 'daily' ? 'session' : bundle.policy === 'always' ? 'biometry' : undefined,
+        // explicit `always`⇒`biometry`, `never`⇒`none`. An absent policy omits the
+        // token entirely and resolves to the configured default (`daily`) on read.
+        // An older CLI that doesn't know `none` reads it as undefined and falls back
+        // to its own default — safe, since it also lacks the no-ACL write path.
+        tier: bundle.policy === 'daily' ? 'session'
+            : bundle.policy === 'always' ? 'biometry'
+                : bundle.policy === 'never' ? 'none'
+                    : undefined,
         created_at: bundle.created_at,
         updated_at: bundle.updated_at,
         last_used: bundle.last_used,
@@ -324,7 +331,11 @@ export function writeBundle(bundle) {
         meta,
     };
     const json = JSON.stringify(payload);
-    itemStore(backend).set(bundleMetaItem(bundle.name), json);
+    // A `never` bundle's metadata is stored without the biometry ACL too, so
+    // `view` and the metadata half of a read resolve silently — the whole point
+    // of the tier. On an un-updated pinned helper this write fails loudly (the
+    // no-ACL command is missing) rather than silently landing an ACL'd item.
+    itemStore(backend).set(bundleMetaItem(bundle.name), json, { noAcl: bundle.policy === 'never' });
     emit('secrets.set', { bundle: bundle.name });
 }
 export function deleteBundle(name) {
@@ -504,6 +515,87 @@ function stampLastUsed(bundle) {
         // Swallow — telemetry must never block secret resolution.
     }
 }
+/**
+ * Abort if any of the selected keys has an `expires` date in the past.
+ * Bundle-level expiry is not a concept today (expiry is per-key via `meta`),
+ * so we iterate only the per-key meta entries.
+ */
+function assertNotExpired(bundle, selectedKeys, allowExpired) {
+    if (allowExpired)
+        return;
+    if (!bundle.meta)
+        return;
+    const now = Date.now();
+    for (const key of selectedKeys) {
+        const meta = bundle.meta[key];
+        if (!meta?.expires)
+            continue;
+        // expires is 'YYYY-MM-DD'; treat as end-of-day UTC.
+        const expiry = new Date(meta.expires + 'T23:59:59Z').getTime();
+        if (expiry < now) {
+            throw new Error(`Bundle '${bundle.name}' key '${key}' expired on ${meta.expires}. ` +
+                `Rotate it with: agents secrets rotate ${bundle.name} ${key}` +
+                ` (or pass --allow-expired to skip this check).`);
+        }
+    }
+}
+/**
+ * Resolve the requested key subset against a bundle's `vars` map. Throws a
+ * fail-loud error listing available keys if any requested key is absent. When
+ * `requested` is undefined or empty, every key in the bundle is selected.
+ */
+function selectRequestedKeys(bundle, requested) {
+    const req = requested?.length ? requested : undefined;
+    if (req) {
+        const missing = req.filter((k) => !(k in bundle.vars));
+        if (missing.length > 0) {
+            const available = Object.keys(bundle.vars).join(', ') || '(none)';
+            throw new Error(`Bundle '${bundle.name}' does not contain key(s): ${missing.join(', ')}. Available: ${available}.`);
+        }
+    }
+    return new Set(req ?? Object.keys(bundle.vars));
+}
+/**
+ * Apply the --keys subset + expiry gate to an already-resolved snapshot from
+ * the secrets-agent fast-path. The agent stores the FULL bundle env, so a
+ * naive fast-path return would silently defeat --keys and inject expired
+ * values. Mirrors the slow-path pre-checks in `resolveBundleEnv` /
+ * `readAndResolveBundleEnv` and returns a new env whose keys match the subset.
+ *
+ * Exported for tests; production callers reach it via the fast-path branch in
+ * `readAndResolveBundleEnv`.
+ */
+export function filterAgentHitBySubsetAndExpiry(hit, opts) {
+    const selectedKeys = selectRequestedKeys(hit.bundle, opts.keys);
+    assertNotExpired(hit.bundle, [...selectedKeys], opts.allowExpired ?? false);
+    // When no subset was requested, return the cached env untouched — same
+    // reference the agent handed back, so no per-call allocation on the hot path.
+    if (!opts.keys?.length)
+        return hit;
+    const env = {};
+    for (const key of selectedKeys) {
+        if (key in hit.env)
+            env[key] = hit.env[key];
+    }
+    return { bundle: hit.bundle, env };
+}
+/**
+ * Guard for remote-bundle callers (`bundle@host` / `--host`) — the SSH
+ * resolver in `remoteResolveEnv` does not thread --keys or --allow-expired
+ * yet. Silently applying them would inject the full remote env or an expired
+ * value, defeating the least-privilege intent, so we fail loud.
+ *
+ * Exported so `agents run --secrets bundle@host` and `agents secrets exec
+ * --host` share the exact same error text; the tests exercise this helper
+ * directly instead of driving the whole CLI.
+ */
+export function assertRemoteBundleFlagsUnsupported(bundleName, host, opts, flagLabels) {
+    const hasKeys = Array.isArray(opts.keys) && opts.keys.length > 0;
+    if (!hasKeys && !opts.allowExpired)
+        return;
+    throw new Error(`Bundle '${bundleName}@${host}': ${flagLabels.keysFlag} and ${flagLabels.allowExpiredFlag} are not supported for remote (bundle@host) bundles yet. ` +
+        `Drop the flag or resolve the bundle locally.`);
+}
 // Walk the bundle and produce a flat env map. Every keychain: ref is gathered
 // into a single batch read so macOS shows ONE Touch ID prompt for the whole
 // bundle — including the metadata fetch that already happened in readBundle
@@ -513,9 +605,14 @@ function stampLastUsed(bundle) {
 // resolved inline and never reach the keychain.
 export function resolveBundleEnv(bundle, _opts = {}) {
     stampLastUsed(bundle);
+    // Key-subset validation and expiry pre-check.
+    const selectedKeys = selectRequestedKeys(bundle, _opts.keys);
+    assertNotExpired(bundle, [...selectedKeys], _opts.allowExpired ?? false);
     const parsedByKey = new Map();
     const keychainItemsToFetch = [];
     for (const [key, raw] of Object.entries(bundle.vars)) {
+        if (!selectedKeys.has(key))
+            continue;
         const parsed = parseBundleValue(raw);
         parsedByKey.set(key, parsed);
         if ('ref' in parsed && parsed.ref.provider === 'keychain') {
@@ -528,6 +625,8 @@ export function resolveBundleEnv(bundle, _opts = {}) {
         : new Map();
     const env = {};
     for (const [key, raw] of Object.entries(bundle.vars)) {
+        if (!selectedKeys.has(key))
+            continue;
         const parsed = parsedByKey.get(key);
         if ('literal' in parsed) {
             env[key] = parsed.literal;
@@ -582,15 +681,20 @@ export function readAndResolveBundleEnv(name, opts = {}) {
     if (backend === 'keychain' && !opts.noAgent && process.env.AGENTS_SECRETS_NO_AGENT !== '1') {
         const hit = agentGetSync(name);
         if (hit) {
-            stampLastUsed(hit.bundle);
+            // The agent stores the FULL bundle env. Apply the same subset filter and
+            // expiry gate as the slow path — without this, `--secrets-keys X` would
+            // silently inject every key and an expired key would flow through after
+            // the first cache-populating run.
+            const filtered = filterAgentHitBySubsetAndExpiry(hit, opts);
+            stampLastUsed(filtered.bundle);
             emit('secrets.get', {
                 bundle: name,
                 caller: opts.caller,
                 status: 'success',
                 source: 'agent',
-                keyCount: Object.keys(hit.env).length,
+                keyCount: Object.keys(filtered.env).length,
             });
-            return hit;
+            return filtered;
         }
     }
     if (backend === 'file')
@@ -651,11 +755,16 @@ export function readAndResolveBundleEnv(name, opts = {}) {
     for (const key of Object.keys(bundle.vars)) {
         validateEnvKey(key);
     }
+    // Key-subset validation and expiry pre-check (mirrors resolveBundleEnv logic).
+    const selectedKeys = selectRequestedKeys(bundle, opts.keys);
+    assertNotExpired(bundle, [...selectedKeys], opts.allowExpired ?? false);
     stampLastUsed(bundle);
     const parsedByKey = new Map();
     const keychainKeys = [];
     const kindCounts = {};
     for (const [key, raw] of Object.entries(bundle.vars)) {
+        if (!selectedKeys.has(key))
+            continue;
         const p = parseBundleValue(raw);
         parsedByKey.set(key, p);
         const kind = 'literal' in p ? 'literal' : p.ref.provider;
@@ -664,7 +773,7 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             keychainKeys.push(key);
         }
     }
-    const keys = Object.keys(bundle.vars).sort();
+    const keys = [...selectedKeys].sort();
     keychainKeys.sort();
     const emitReadAudit = (status, err) => {
         emit('secrets.get', {
@@ -681,6 +790,8 @@ export function readAndResolveBundleEnv(name, opts = {}) {
     try {
         const env = {};
         for (const [key] of Object.entries(bundle.vars)) {
+            if (!selectedKeys.has(key))
+                continue;
             const p = parsedByKey.get(key);
             if ('literal' in p) {
                 env[key] = p.literal;
@@ -749,7 +860,7 @@ export function rotateBundleSecret(bundle, key, opts) {
     }
     const shortId = raw.slice('keychain:'.length);
     const item = secretsKeychainItem(bundle.name, shortId);
-    itemStore(bundle.backend ?? 'keychain').set(item, opts.newValue);
+    itemStore(bundle.backend ?? 'keychain').set(item, opts.newValue, { noAcl: bundlePolicy(bundle) === 'never' });
     if (opts.clearMeta) {
         if (bundle.meta)
             delete bundle.meta[key];
@@ -817,7 +928,7 @@ export function renameBundle(oldName, newName, opts = {}) {
         const shortId = raw.slice('keychain:'.length);
         const newItem = secretsKeychainItem(newName, shortId);
         const value = store.get(oldItem);
-        store.set(newItem, value);
+        store.set(newItem, value, { noAcl: bundlePolicy(source) === 'never' });
     }
     // writeBundle preserves source.created_at, refreshes updated_at, and keeps
     // the source backend (spread carries source.backend).
@@ -837,8 +948,16 @@ export function renameBundle(oldName, newName, opts = {}) {
  * `import` / `remove` / `delete`. Pass the bundle's resolved backend
  * (`bundle.backend ?? 'keychain'`).
  */
-export function bundleItemStore(backend) {
-    return itemStore(backend ?? 'keychain');
+export function bundleItemStore(backend, opts) {
+    const store = itemStore(backend ?? 'keychain');
+    // `never`-policy bundles write their per-key values without the biometry ACL
+    // (same rationale as the metadata write in writeBundle). Wrap `set` so every
+    // value the add/import paths write inherits the no-ACL flag; reads, deletes,
+    // and existence checks are ACL-independent and pass through untouched.
+    if (opts?.noAcl) {
+        return { ...store, set: (item, value) => store.set(item, value, { noAcl: true }) };
+    }
+    return store;
 }
 // Iterate all keychain-backed keys in a bundle for cleanup on rm/unset.
 export function keychainItemsForBundle(bundle) {

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

@@ -74,9 +74,12 @@ export declare const fileStore: {
 /** File-only KeychainBackend (exported for tests; the Linux backend uses these
  *  ops with auto-provision allowed). */
 export declare const fileBackend: KeychainBackend;
+/** Resolved passphrase directory (exported for integration tests). */
+export declare function resolvePassphraseDir(): string;
 /** Test-only: reset module state (file dir + cached passphrase). */
 export declare function _resetFileStoreForTest(opts?: {
     fileDir?: string | null;
+    passphraseDir?: string | null;
     passphrase?: string | null;
 }): void;
 export {};

package/dist/lib/secrets/filestore.js

@@ -28,6 +28,7 @@ import * as path from 'path';
 import { encodePwshBase64 } from '../pwsh.js';
 // ---------- file store location ----------
 let fileDirOverride = null;
+let passphraseDirOverride = null;
 let cachedPassphrase = null;
 let warnedAutoPassphrase = false;
 export function fileDir() {
@@ -106,29 +107,40 @@ function readPassphraseFromTty() {
         fs.closeSync(fd);
     }
 }
-/** Path of the auto-provisioned machine-local passphrase. Lives alongside the
- *  encrypted items but is never itself an item (no `.enc` suffix, so it's
- *  excluded from list/has/get and from fileFallbackPreviouslyActivated). */
+/**
+ * Directory for the auto-provisioned machine-local passphrase. Kept outside
+ * `fileDir()` so a scan of the encrypted store never co-locates key + ciphertext.
+ */
+function passphraseDir() {
+    return passphraseDirOverride ?? path.join(os.homedir(), '.agents', '.secrets-key');
+}
+function ensurePassphraseDir() {
+    fs.mkdirSync(passphraseDir(), { recursive: true, mode: 0o700 });
+}
+/** Path of the auto-provisioned machine-local passphrase (not an `.enc` item). */
 function passphraseFilePath() {
+    return path.join(passphraseDir(), 'passphrase');
+}
+/** Legacy co-located path — read-only for machines provisioned before #479. */
+function legacyPassphraseFilePath() {
     return path.join(fileDir(), '.passphrase');
 }
 /** True if a machine-local passphrase has already been provisioned. */
 export function machinePassphraseExists() {
-    try {
-        return fs.readFileSync(passphraseFilePath(), 'utf8').trim().length > 0;
-    }
-    catch {
-        return false;
-    }
+    return readMachinePassphrase() !== null;
 }
 function readMachinePassphrase() {
-    try {
-        const p = fs.readFileSync(passphraseFilePath(), 'utf8').trim();
-        return p.length > 0 ? p : null;
-    }
-    catch {
-        return null;
+    for (const fp of [passphraseFilePath(), legacyPassphraseFilePath()]) {
+        try {
+            const p = fs.readFileSync(fp, 'utf8').trim();
+            if (p.length > 0)
+                return p;
+        }
+        catch {
+            // try next location
+        }
     }
+    return null;
 }
 /**
  * Provision (or read back) a stable machine-local passphrase for the encrypted
@@ -146,7 +158,7 @@ function provisionMachinePassphrase() {
     const existing = readMachinePassphrase();
     if (existing)
         return existing;
-    ensureFileDir();
+    ensurePassphraseDir();
     const generated = randomBytes(32).toString('base64');
     const fp = passphraseFilePath();
     try {
@@ -317,9 +329,23 @@ export const fileBackend = {
     delete: fileDelete,
     list: fileList,
 };
+/** Resolved passphrase directory (exported for integration tests). */
+export function resolvePassphraseDir() {
+    return passphraseDir();
+}
 /** Test-only: reset module state (file dir + cached passphrase). */
 export function _resetFileStoreForTest(opts = {}) {
     fileDirOverride = opts.fileDir ?? null;
+    if (opts.passphraseDir !== undefined) {
+        passphraseDirOverride = opts.passphraseDir;
+    }
+    else if (opts.fileDir) {
+        // Hermetic sibling when only the store dir is overridden (linux.test.ts).
+        passphraseDirOverride = path.resolve(opts.fileDir, '..', `${path.basename(opts.fileDir)}-key`);
+    }
+    else {
+        passphraseDirOverride = null;
+    }
     cachedPassphrase = opts.passphrase ?? null;
     warnedAutoPassphrase = false;
 }

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

@@ -103,8 +103,16 @@ export declare function getKeychainToken(item: string): string;
  * lookups — no biometric prompt path on those platforms.
  */
 export declare function getKeychainTokens(items: string[]): Map<string, string>;
-/** Store or update a secret value in the keychain/keyring. Device-local; biometry-gated on macOS. */
-export declare function setKeychainToken(item: string, value: string): void;
+/** Store or update a secret value in the keychain/keyring. Device-local;
+ * biometry-gated on macOS. `opts.noAcl` (the `never` prompt-policy) writes our
+ * item WITHOUT the biometry access control so later reads are fully silent — it
+ * routes through the signed helper's `set-no-acl` path. A pinned helper that
+ * predates that path rejects the unknown command (exit 2) and this throws,
+ * rather than silently falling back to an ACL'd `set` (which would behave like
+ * `always`). Ignored by the Linux/Windows/test backends, which have no ACL. */
+export declare function setKeychainToken(item: string, value: string, opts?: {
+    noAcl?: boolean;
+}): void;
 /** Delete a keychain/keyring item. Returns true if it existed. Never prompts for biometry. */
 export declare function deleteKeychainToken(item: string): boolean;
 /**
@@ -140,6 +148,39 @@ export declare function listLegacyKeychainItems(prefix: string): string[];
  * concept, so the call is a no-op there.
  */
 export declare function migrateKeychainItem(item: string): boolean;
+/**
+ * Enumerate data-protection items whose service starts with `prefix` that live
+ * under a NON-concrete access group — pre-#279 "orphans" filed under the implicit
+ * default group (the literal `2HTP252L87.*`) that the pinned-group queries can't
+ * see. Attributes only: never decrypts, never prompts. macOS only — Linux/Windows
+ * and the test backend have no access-group concept, so this returns [].
+ */
+export declare function listOrphanedKeychainItems(prefix: string): string[];
+/** Outcome of re-homing one orphaned keychain item. */
+export interface OrphanMigrationResult {
+    item: string;
+    status: 'ok' | 'warn' | 'fail';
+    detail?: string;
+}
+/**
+ * Parse the `migrate-orphans` helper summary (one record per line):
+ *   OK <service>               re-homed
+ *   WARN <service> <detail>    pinned copy written but orphan not removed
+ *   FAIL <service> <detail>    could not re-home (orphan left intact)
+ * Unknown lines are ignored. Exported for unit testing without a keychain.
+ */
+export declare function parseOrphanMigrationOutput(stdout: string): OrphanMigrationResult[];
+/**
+ * Re-home every pre-#279 orphaned data-protection item under `prefix` into the
+ * concrete access group, behind a SINGLE Touch ID prompt for the whole batch.
+ * The helper reads each orphan by its exact persistent ref, adds the pinned copy
+ * (add-before-delete: a failed add leaves the orphan intact), then deletes the
+ * orphan by ref. Returns one result per item. macOS only — no-op elsewhere.
+ *
+ * Throws on Touch ID cancellation (exit 4) so callers can distinguish "user
+ * aborted" from "nothing to do" (empty array).
+ */
+export declare function migrateOrphanedKeychainItems(prefix: string): OrphanMigrationResult[];
 /** Options controlling how secret refs are resolved. */
 export interface ResolveOptions {
     /** Translate a short keychain ID to a fully namespaced item name. */

package/dist/lib/secrets/index.js

@@ -264,8 +264,14 @@ export function getKeychainTokens(items) {
     }
     return result;
 }
-/** Store or update a secret value in the keychain/keyring. Device-local; biometry-gated on macOS. */
-export function setKeychainToken(item, value) {
+/** Store or update a secret value in the keychain/keyring. Device-local;
+ * biometry-gated on macOS. `opts.noAcl` (the `never` prompt-policy) writes our
+ * item WITHOUT the biometry access control so later reads are fully silent — it
+ * routes through the signed helper's `set-no-acl` path. A pinned helper that
+ * predates that path rejects the unknown command (exit 2) and this throws,
+ * rather than silently falling back to an ACL'd `set` (which would behave like
+ * `always`). Ignored by the Linux/Windows/test backends, which have no ACL. */
+export function setKeychainToken(item, value, opts) {
     if (backend) {
         backend.set(item, value);
         return;
@@ -303,12 +309,22 @@ export function setKeychainToken(item, value) {
         return;
     }
     const bin = getKeychainHelperPath();
-    const result = spawnSync(bin, ['set', item, os.userInfo().username], {
+    // `never` policy → no-ACL write. The `set-no-acl` subcommand exists only in a
+    // re-notarized helper; an older pinned helper dies with "Unknown command:
+    // set-no-acl" (exit 2), surfaced below — never a silent ACL'd downgrade.
+    const helperCmd = opts?.noAcl ? 'set-no-acl' : 'set';
+    const result = spawnSync(bin, [helperCmd, item, os.userInfo().username], {
         input: value,
         stdio: ['pipe', 'pipe', 'pipe'],
     });
     if (result.status !== 0) {
         const msg = result.stderr?.toString().trim();
+        if (opts?.noAcl && /unknown command/i.test(msg ?? '')) {
+            throw new Error(`The 'never' prompt-policy needs a Keychain helper with the no-ACL write path, ` +
+                `but the installed helper does not support it. Rebuild + re-notarize the signed ` +
+                `helper (scripts/build-keychain-helper.sh) and re-pin its sha, then retry. ` +
+                `(helper said: ${msg})`);
+        }
         throw new Error(msg || `Failed to write keychain item '${item}'.`);
     }
 }
@@ -419,6 +435,89 @@ export function migrateKeychainItem(item) {
     const msg = result.stderr?.toString().trim();
     throw new Error(msg || `Failed to migrate keychain item '${item}'.`);
 }
+/**
+ * Enumerate data-protection items whose service starts with `prefix` that live
+ * under a NON-concrete access group — pre-#279 "orphans" filed under the implicit
+ * default group (the literal `2HTP252L87.*`) that the pinned-group queries can't
+ * see. Attributes only: never decrypts, never prompts. macOS only — Linux/Windows
+ * and the test backend have no access-group concept, so this returns [].
+ */
+export function listOrphanedKeychainItems(prefix) {
+    if (backend)
+        return [];
+    assertSupportedPlatform();
+    if (isLinux() || isWindows())
+        return [];
+    const bin = getKeychainHelperPath();
+    const result = spawnSync(bin, ['list-orphans', prefix, os.userInfo().username], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (result.status !== 0) {
+        const msg = result.stderr?.toString().trim();
+        throw new Error(msg || `Failed to enumerate orphaned keychain items with prefix '${prefix}'.`);
+    }
+    const out = result.stdout?.toString() || '';
+    return out.split('\n').map((s) => s.trim()).filter(Boolean);
+}
+/**
+ * Parse the `migrate-orphans` helper summary (one record per line):
+ *   OK <service>               re-homed
+ *   WARN <service> <detail>    pinned copy written but orphan not removed
+ *   FAIL <service> <detail>    could not re-home (orphan left intact)
+ * Unknown lines are ignored. Exported for unit testing without a keychain.
+ */
+export function parseOrphanMigrationOutput(stdout) {
+    const results = [];
+    for (const line of stdout.split('\n')) {
+        const trimmed = line.trim();
+        if (!trimmed)
+            continue;
+        const sep = trimmed.indexOf(' ');
+        const tag = sep === -1 ? trimmed : trimmed.slice(0, sep);
+        const rest = sep === -1 ? '' : trimmed.slice(sep + 1);
+        if (tag === 'OK') {
+            // OK carries only the service name (no trailing detail).
+            results.push({ item: rest, status: 'ok' });
+        }
+        else if (tag === 'WARN' || tag === 'FAIL') {
+            // WARN/FAIL are 'TAG <service> <detail>'. Service names are space-free
+            // (validateBundleName / validateEnvKey), so the first token IS the exact
+            // service — this stays consistent with listOrphanedKeychainItems for the
+            // healed-set reconciliation in migrate-acl.
+            const item = rest.split(' ')[0] ?? rest;
+            results.push({ item, status: tag === 'WARN' ? 'warn' : 'fail', detail: rest });
+        }
+    }
+    return results;
+}
+/**
+ * Re-home every pre-#279 orphaned data-protection item under `prefix` into the
+ * concrete access group, behind a SINGLE Touch ID prompt for the whole batch.
+ * The helper reads each orphan by its exact persistent ref, adds the pinned copy
+ * (add-before-delete: a failed add leaves the orphan intact), then deletes the
+ * orphan by ref. Returns one result per item. macOS only — no-op elsewhere.
+ *
+ * Throws on Touch ID cancellation (exit 4) so callers can distinguish "user
+ * aborted" from "nothing to do" (empty array).
+ */
+export function migrateOrphanedKeychainItems(prefix) {
+    if (backend)
+        return [];
+    assertSupportedPlatform();
+    if (isLinux() || isWindows())
+        return [];
+    const bin = getKeychainHelperPath();
+    const result = spawnSync(bin, ['migrate-orphans', prefix, os.userInfo().username], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (result.status === 4)
+        throw new Error('Touch ID cancelled during orphan migration.');
+    if (result.status !== 0) {
+        const msg = result.stderr?.toString().trim();
+        throw new Error(msg || `Failed to migrate orphaned keychain items with prefix '${prefix}'.`);
+    }
+    return parseOrphanMigrationOutput(result.stdout?.toString() || '');
+}
 function expandHome(p) {
     if (p.startsWith('~/') || p === '~') {
         return path.join(os.homedir(), p.slice(1));

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

@@ -0,0 +1,93 @@
+/**
+ * Zero-knowledge / JIT secret delivery over MCP (issue #333).
+ *
+ * A stdio MCP server exposing a single `get_secret(bundle, key)` tool. Unlike
+ * `agents secrets exec`, which spawns the child process with EVERY resolved
+ * value baked into `process.env` (any subprocess can `printenv` the lot — see
+ * buildSecretsExecEnv in src/commands/secrets.ts), this server hands an
+ * MCP-speaking agent framework ONE credential at a time, by name, at call
+ * time. The raw value is returned only inside the tool result: it never enters
+ * the child's environment, is never logged, and never appears in `tools/list`
+ * metadata (names only).
+ *
+ * Resolution reuses the canonical bundle read path
+ * (readAndResolveBundleEnv -> getKeychainToken); no keychain access is
+ * re-implemented here. On Linux the libsecret backend (or its encrypted-file
+ * fallback for locked/headless collections) applies transparently through that
+ * abstraction, so the server stays backend-agnostic and works unchanged on
+ * macOS.
+ *
+ * Transport: the MCP stdio transport is newline-delimited JSON-RPC 2.0 (one
+ * message per line, UTF-8, no embedded newlines). That framing is trivial, so
+ * we implement it directly rather than pull in the @modelcontextprotocol/sdk
+ * server dependency — keeping the tree dependency-free and the handler pure and
+ * unit-testable in-process.
+ */
+/** MCP protocol revision this server negotiates. */
+export declare const MCP_PROTOCOL_VERSION = "2024-11-05";
+/** The single tool this server exposes. */
+export declare const GET_SECRET_TOOL = "get_secret";
+/** serverInfo.name reported at `initialize`. */
+export declare const MCP_SERVER_NAME = "agents-secrets";
+export interface JsonRpcRequest {
+    jsonrpc?: string;
+    id?: string | number | null;
+    method?: string;
+    params?: unknown;
+}
+interface JsonRpcSuccess {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    result: unknown;
+}
+interface JsonRpcErrorResponse {
+    jsonrpc: '2.0';
+    id: string | number | null;
+    error: {
+        code: number;
+        message: string;
+    };
+}
+export type JsonRpcResponse = JsonRpcSuccess | JsonRpcErrorResponse;
+/** Per-bundle metadata for `tools/list` — names only, NEVER values. */
+export interface BundleKeyMetadata {
+    bundle: string;
+    description?: string;
+    keys: string[];
+}
+/**
+ * Enumerate every bundle and its key names WITHOUT resolving or reading any
+ * value. Mirrors how `agents secrets list` surfaces bundle metadata: names are
+ * safe to expose, values are not. `listBundles()` reads only the bundle
+ * metadata items (var definitions), never the secret items behind them.
+ */
+export declare function listSecretMetadata(): BundleKeyMetadata[];
+/**
+ * Resolve a single secret value by bundle + key through the canonical read
+ * path. Throws a clear error when the bundle or the key is absent.
+ *
+ * The bundle metadata is read first (readBundle) so a missing key is reported
+ * without triggering resolution — and, on macOS, without prompting Touch ID —
+ * for the other keys in the bundle.
+ */
+export declare function resolveSecret(bundle: string, key: string): string;
+/**
+ * Handle one parsed JSON-RPC request. Returns the response object, or `null`
+ * for notifications (which take no reply). Pure — no I/O, no logging — so tests
+ * drive it directly.
+ */
+export declare function handleMcpRequest(req: JsonRpcRequest, ctx?: {
+    version?: string;
+}): JsonRpcResponse | null;
+/**
+ * Run the stdio MCP server: read newline-delimited JSON-RPC requests from
+ * `input`, write responses to `output`. Resolves when the input stream ends.
+ * Streams are injectable so tests can drive a full request/response loop
+ * without spawning a process.
+ */
+export declare function runSecretsMcpServer(opts?: {
+    input?: NodeJS.ReadableStream;
+    output?: NodeJS.WritableStream;
+    version?: string;
+}): Promise<void>;
+export {};