@phnx-labs/agents-cli 1.19.2 → 1.20.3

package/dist/lib/secrets/bundles.js

@@ -1,21 +1,21 @@
 /**
- * Secret bundles -- named sets of keychain-backed environment variables.
+ * Secret bundles — named sets of keychain-backed environment variables.
  *
  * Bundle metadata (name, description, vars map) is stored in the macOS
- * Keychain as a JSON blob under `agents-cli.bundles.<name>`. Bundles created
- * with `--icloud-sync` write the metadata to the iCloud-synced keychain so
- * the full bundle definition (not just secret values) propagates across
- * the user's Macs. Nothing about secrets ever lives in plaintext on disk.
+ * 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.
  *
- * Secret values keep their old layout: one keychain item per key under
- * `agents-cli.secrets.<bundle>.<key>`, sync-state matching the bundle's
- * `icloud_sync` flag.
+ * Cross-machine sync is handled by src/lib/secrets/sync.ts via an explicit
+ * encrypted export/import flow; the bundle layer is sync-agnostic.
  */
 import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { deleteKeychainToken, getKeychainToken, getKeychainTokensBatch, hasKeychainToken, listKeychainItems, parseBundleValue, resolveRef, secretsKeychainItem, setKeychainToken, } from './index.js';
+import { deleteKeychainToken, getKeychainToken, getKeychainTokens, hasKeychainToken, listKeychainItems, parseBundleValue, resolveRef, secretsKeychainItem, setKeychainToken, } from './index.js';
 import { emit } from '../events.js';
 /** Allowed values for a secret's `type` metadata field. */
 export const SECRET_TYPES = [
@@ -34,6 +34,7 @@ const LAST_USED_THROTTLE_MS = 60_000;
 const BUNDLE_NAME_PATTERN = /^[a-z0-9][a-z0-9\-_.]{0,48}$/i;
 const ENV_KEY_PATTERN = /^[A-Za-z_][A-Za-z0-9_]*$/;
 const BUNDLE_META_PREFIX = 'agents-cli.bundles.';
+const SECRETS_ITEM_PREFIX = 'agents-cli.secrets.';
 export const RESERVED_ENV_NAMES = new Set([
     'PATH', 'HOME', 'USER', 'USERNAME', 'SHELL', 'PWD', 'OLDPWD',
     'TERM', 'LANG', 'LC_ALL', 'DISPLAY', 'EDITOR', 'VISUAL',
@@ -62,6 +63,17 @@ export function isLoaderOrInterpreterEnv(name) {
             'CDPATH',
         ].includes(upper);
 }
+export function sanitizeProcessEnv(env = process.env) {
+    const out = {};
+    for (const [k, v] of Object.entries(env)) {
+        if (v === undefined)
+            continue;
+        if (isLoaderOrInterpreterEnv(k))
+            continue;
+        out[k] = v;
+    }
+    return out;
+}
 /** Validate a bundle name against the allowed pattern. Throws on invalid input. */
 export function validateBundleName(name) {
     if (!BUNDLE_NAME_PATTERN.test(name)) {
@@ -124,11 +136,12 @@ export function readBundle(name) {
     if (!parsed || typeof parsed !== 'object') {
         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.
     const bundle = {
         name,
         description: parsed.description,
         allow_exec: Boolean(parsed.allow_exec),
-        icloud_sync: Boolean(parsed.icloud_sync),
         vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
     };
     if (typeof parsed.created_at === 'string')
@@ -178,7 +191,6 @@ export function writeBundle(bundle) {
     const payload = {
         description: bundle.description,
         allow_exec: bundle.allow_exec ? true : undefined,
-        icloud_sync: bundle.icloud_sync ? true : undefined,
         created_at: bundle.created_at,
         updated_at: bundle.updated_at,
         last_used: bundle.last_used,
@@ -186,7 +198,7 @@ export function writeBundle(bundle) {
         meta,
     };
     const json = JSON.stringify(payload);
-    setKeychainToken(bundleMetaItem(bundle.name), json, Boolean(bundle.icloud_sync));
+    setKeychainToken(bundleMetaItem(bundle.name), json);
     emit('secrets.set', { bundle: bundle.name });
 }
 export function deleteBundle(name) {
@@ -208,14 +220,57 @@ export function listBundles() {
     const names = services
         .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;
         try {
-            out.push(readBundle(name));
+            parsed = JSON.parse(json);
         }
         catch {
             // Skip malformed bundles; surfaced via `agents secrets view <name>`.
+            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);
     }
     return out.sort((a, b) => a.name.localeCompare(b.name));
 }
@@ -253,31 +308,27 @@ function stampLastUsed(bundle) {
         // Swallow — telemetry must never block secret resolution.
     }
 }
-export function resolveBundleEnv(bundle, opts = {}) {
+// 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
+// (the helper's auth context survives across separate invocations only via
+// the per-process LAContext, so we still get one prompt for the batch even
+// if metadata triggered an earlier one). Literals/env/file/exec refs are
+// resolved inline and never reach the keychain.
+export function resolveBundleEnv(bundle, _opts = {}) {
     stampLastUsed(bundle);
     const parsedByKey = new Map();
     const keychainItemsToFetch = [];
-    const keychainItemToKey = new Map();
     for (const [key, raw] of Object.entries(bundle.vars)) {
         const parsed = parseBundleValue(raw);
         parsedByKey.set(key, parsed);
         if ('ref' in parsed && parsed.ref.provider === 'keychain') {
-            const item = secretsKeychainItem(bundle.name, parsed.ref.value);
-            keychainItemsToFetch.push(item);
-            keychainItemToKey.set(item, key);
+            keychainItemsToFetch.push(secretsKeychainItem(bundle.name, parsed.ref.value));
         }
     }
-    // Build the localizedReason shown under the Touch ID prompt. Lowercase verb
-    // phrase per Apple HIG — the system prepends "<App> is required to ".
-    const reason = opts.caller
-        ? `read ${bundle.name} secrets (for ${opts.caller})`
-        : `read ${bundle.name} secrets`;
-    // Single helper invocation, one biometric prompt.
     const fetched = keychainItemsToFetch.length > 0
-        ? getKeychainTokensBatch(keychainItemsToFetch, bundle.icloud_sync, reason)
+        ? getKeychainTokens(keychainItemsToFetch)
         : new Map();
-    // Second pass: assemble env. Keychain values come from the batch; everything
-    // else is resolved inline (literals and env/file/exec refs don't prompt).
     const env = {};
     for (const [key, raw] of Object.entries(bundle.vars)) {
         const parsed = parsedByKey.get(key);
@@ -298,7 +349,6 @@ export function resolveBundleEnv(bundle, opts = {}) {
         try {
             env[key] = resolveRef(parsed.ref, {
                 allowExec: bundle.allow_exec,
-                iCloudSync: bundle.icloud_sync,
                 keychainItemFor: (shortId) => secretsKeychainItem(bundle.name, shortId),
             });
         }
@@ -306,8 +356,133 @@ export function resolveBundleEnv(bundle, opts = {}) {
             throw new Error(`Bundle '${bundle.name}' key '${key}': ${err.message}`);
         }
     }
+    // `caller` is intentionally unused; see ResolveBundleOptions.
+    void _opts.caller;
     return env;
 }
+/**
+ * Read a bundle's metadata AND resolve its env in a single Touch ID prompt.
+ *
+ * `readBundle` + `resolveBundleEnv` issued two separate `LAContext` calls
+ * (metadata read via `get-auth`, then secret values via `get-batch`) which
+ * surfaced as two consecutive Touch ID prompts. macOS does not honor
+ * "Always Allow" for items protected with `kSecAttrAccessControl`+biometry,
+ * so caching at the OS level was never an option. This collapses both reads
+ * into one `get-batch` call: we enumerate the bundle's secret items first
+ * (silent — `list` returns attrs only and does not trigger biometry) and
+ * include the metadata item in the same batch. One prompt, correctly scoped
+ * to the bundle name and caller.
+ */
+export function readAndResolveBundleEnv(name, opts = {}) {
+    validateBundleName(name);
+    const metaItem = bundleMetaItem(name);
+    const bundleSecretPrefix = `${SECRETS_ITEM_PREFIX}${name}.`;
+    let secretItems;
+    try {
+        secretItems = listKeychainItems(bundleSecretPrefix);
+    }
+    catch {
+        secretItems = [];
+    }
+    const reason = opts.caller
+        ? `read ${name} secrets (for ${opts.caller})`
+        : `read ${name} secrets`;
+    void reason;
+    const fetched = getKeychainTokens([metaItem, ...secretItems]);
+    const json = fetched.get(metaItem);
+    if (json === undefined) {
+        throw new Error(`Secrets bundle '${name}' not found.`);
+    }
+    let parsed;
+    try {
+        parsed = JSON.parse(json);
+    }
+    catch {
+        throw new Error(`Bundle '${name}' is malformed.`);
+    }
+    if (!parsed || typeof parsed !== 'object') {
+        throw new Error(`Bundle '${name}' is malformed.`);
+    }
+    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;
+    for (const key of Object.keys(bundle.vars)) {
+        validateEnvKey(key);
+    }
+    stampLastUsed(bundle);
+    const parsedByKey = new Map();
+    const keychainKeys = [];
+    const kindCounts = {};
+    for (const [key, raw] of Object.entries(bundle.vars)) {
+        const p = parseBundleValue(raw);
+        parsedByKey.set(key, p);
+        const kind = 'literal' in p ? 'literal' : p.ref.provider;
+        kindCounts[kind] = (kindCounts[kind] ?? 0) + 1;
+        if ('ref' in p && p.ref.provider === 'keychain') {
+            keychainKeys.push(key);
+        }
+    }
+    const keys = Object.keys(bundle.vars).sort();
+    keychainKeys.sort();
+    const emitReadAudit = (status, err) => {
+        emit('secrets.get', {
+            bundle: bundle.name,
+            caller: opts.caller,
+            status,
+            keyCount: keys.length,
+            keys,
+            keychainKeys,
+            kindCounts,
+            error: err instanceof Error ? err.message : (err ? String(err) : undefined),
+        });
+    };
+    try {
+        const env = {};
+        for (const [key] of Object.entries(bundle.vars)) {
+            const p = parsedByKey.get(key);
+            if ('literal' in p) {
+                env[key] = p.literal;
+                continue;
+            }
+            if (p.ref.provider === 'keychain') {
+                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. ` +
+                        `Run: agents secrets add ${bundle.name} ${key}`);
+                }
+                env[key] = value;
+                continue;
+            }
+            try {
+                env[key] = resolveRef(p.ref, {
+                    allowExec: bundle.allow_exec,
+                    keychainItemFor: (shortId) => secretsKeychainItem(bundle.name, shortId),
+                });
+            }
+            catch (err) {
+                throw new Error(`Bundle '${bundle.name}' key '${key}': ${err.message}`);
+            }
+        }
+        emitReadAudit('success');
+        return { bundle, env };
+    }
+    catch (err) {
+        emitReadAudit('error', err);
+        throw err;
+    }
+}
 // Build a keychain ref expression from a bundle+key pair, for storage in the bundle metadata.
 export function keychainRef(key) {
     return `keychain:${key}`;
@@ -331,7 +506,7 @@ export function rotateBundleSecret(bundle, key, opts) {
     }
     const shortId = raw.slice('keychain:'.length);
     const item = secretsKeychainItem(bundle.name, shortId);
-    setKeychainToken(item, opts.newValue, bundle.icloud_sync);
+    setKeychainToken(item, opts.newValue);
     if (opts.clearMeta) {
         if (bundle.meta)
             delete bundle.meta[key];
@@ -362,8 +537,8 @@ export function rotateBundleSecret(bundle, key, opts) {
  *   4) write new bundle metadata
  *   5) delete the old per-key keychain items + old metadata
  *
- * Steps 1-4 are reversible. If 5 partially fails (e.g. iCloud Keychain
- * hiccup), running `rename` again is a safe no-op for the source items.
+ * Steps 1-4 are reversible. If 5 partially fails, running `rename` again is
+ * a safe no-op for the source items.
  */
 export function renameBundle(oldName, newName, opts = {}) {
     validateBundleName(oldName);
@@ -381,7 +556,7 @@ export function renameBundle(oldName, newName, opts = {}) {
         }
         const dest = readBundle(newName);
         for (const { item } of keychainItemsForBundle(dest)) {
-            deleteKeychainToken(item, dest.icloud_sync);
+            deleteKeychainToken(item);
         }
         deleteBundle(newName);
     }
@@ -394,15 +569,15 @@ export function renameBundle(oldName, newName, opts = {}) {
             continue;
         const shortId = raw.slice('keychain:'.length);
         const newItem = secretsKeychainItem(newName, shortId);
-        const value = getKeychainToken(oldItem, source.icloud_sync);
-        setKeychainToken(newItem, value, source.icloud_sync);
+        const value = getKeychainToken(oldItem);
+        setKeychainToken(newItem, value);
     }
     // writeBundle preserves source.created_at and refreshes updated_at.
     const renamed = { ...source, name: newName };
     writeBundle(renamed);
     // Cleanup: delete the old per-key keychain items, then the old metadata.
     for (const { item: oldItem } of sourceItems) {
-        deleteKeychainToken(oldItem, source.icloud_sync);
+        deleteKeychainToken(oldItem);
     }
     deleteBundle(oldName);
     emit('secrets.rename', { from: oldName, to: newName });
@@ -476,7 +651,6 @@ export async function migrateLegacyBundles(confirmBundle) {
                 name,
                 description: parsed.description,
                 allow_exec: Boolean(parsed.allow_exec),
-                icloud_sync: Boolean(parsed.icloud_sync),
                 vars: parsed.vars && typeof parsed.vars === 'object' ? parsed.vars : {},
             };
             const keys = Object.keys(bundle.vars);

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

@@ -1,14 +1,23 @@
 /**
  * Cross-platform secure credential storage.
  *
- * macOS: Uses Keychain via signed Swift helper (Agents CLI.app) or `security` CLI.
- * Linux: Uses libsecret (GNOME Keyring) via `secret-tool` CLI.
- * Windows: Not yet supported.
+ * macOS: every keychain operation goes through the signed `Agents CLI.app`
+ * helper. The helper attaches a biometry-or-passcode access control to every
+ * item it writes, so the OS itself gates decryption with Touch ID. A single
+ * LAContext lives for the helper's process lifetime, so a batch read pops
+ * Touch ID once and reuses the assertion for every item in the same batch.
+ * No /usr/bin/security fast path: that path bypasses the helper's ACL,
+ * exposes items to the legacy password sheet, and would defeat the model.
  *
- * The .app embeds a provisioning profile that grants the application-identifier
- * + keychain-access-groups entitlement macOS requires for kSecAttrSynchronizable
- * writes (iCloud Keychain). For device-local writes the helper is invoked with
- * the `nosync` arg.
+ * Linux: libsecret (GNOME Keyring) via the `secret-tool` CLI. No biometry —
+ * items are unlocked when the keyring is open.
+ *
+ * Windows: not supported.
+ *
+ * Items are device-local: the biometry access control requires the OS to
+ * treat them as bound to this device, so cross-machine propagation goes
+ * through the explicit export/import flow in src/lib/secrets/sync.ts
+ * rather than the system's cloud-keychain path.
  */
 /** Supported secret resolution backends. */
 export type SecretProvider = 'keychain' | 'env' | 'file' | 'exec';
@@ -44,38 +53,50 @@ export declare function secretsKeychainItem(bundle: string, key: string): string
  * tests) is destructive and would require an interactive Keychain unlock.
  */
 export interface KeychainBackend {
-    has(item: string, sync: boolean): boolean;
-    get(item: string, sync: boolean): string;
-    set(item: string, value: string, sync: boolean): void;
-    delete(item: string, sync: boolean): boolean;
+    has(item: string): boolean;
+    get(item: string): string;
+    set(item: string, value: string): void;
+    delete(item: string): boolean;
     list(prefix: string): string[];
 }
 /** Install a custom keychain backend (test only). Returns the previous backend so callers can restore. */
 export declare function setKeychainBackendForTest(b: KeychainBackend | null): KeychainBackend | null;
-/** Check if a keychain/keyring item exists. */
-export declare function hasKeychainToken(item: string, sync?: boolean): boolean;
-/** Retrieve a secret value from the keychain/keyring. Throws if not found. */
-export declare function getKeychainToken(item: string, sync?: boolean): string;
+/** Check if a keychain/keyring item exists. Never prompts for biometry. */
+export declare function hasKeychainToken(item: string): boolean;
 /**
- * Batch-read multiple keychain items behind a single LocalAuthentication
- * prompt. macOS shows ONE Touch ID prompt and every requested item is
- * unlocked in the same process. Returns a Map keyed by item name. Missing
- * items are absent from the map (caller decides whether that's an error).
+ * Retrieve a secret value from the keychain/keyring. Throws if not found.
  *
- * `reason` is shown to the user under the Touch ID prompt — e.g.
- * "read 'hetzner.com' secrets for agent 'claude'". Apple's HIG recommends
- * a lowercase verb phrase that completes the sentence "X is required to ___".
+ * On macOS this triggers Touch ID (or reuses an assertion held by an earlier
+ * call in the same process). For bundles, prefer getKeychainTokens() so a
+ * single biometric prompt covers every key in the batch.
+ */
+export declare function getKeychainToken(item: string): string;
+/**
+ * Batch-read multiple keychain items behind a single Touch ID prompt. The
+ * macOS helper holds one LAContext for its whole process: the first protected
+ * item triggers Touch ID, every later item in the same invocation reuses the
+ * assertion. Missing items are absent from the returned map (caller decides
+ * whether that's an error).
  *
  * On Linux or when a test backend is installed, falls back to individual
- * `get` calls — no biometric prompt path on those platforms.
+ * lookups — no biometric prompt path on those platforms.
  */
-export declare function getKeychainTokensBatch(items: string[], _sync?: boolean, reason?: string): Map<string, string>;
-/** Store or update a secret value in the keychain/keyring. iCloud-synced when sync=true (macOS only). */
-export declare function setKeychainToken(item: string, value: string, sync?: boolean): void;
-/** Delete a keychain/keyring item. Returns true if it existed. */
-export declare function deleteKeychainToken(item: string, sync?: boolean): boolean;
+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;
+/** Delete a keychain/keyring item. Returns true if it existed. Never prompts for biometry. */
+export declare function deleteKeychainToken(item: string): boolean;
 /** Enumerate keychain/keyring item names starting with the given prefix. */
 export declare function listKeychainItems(prefix: string): string[];
+/**
+ * One-time upgrade for a keychain item that was written by a previous helper
+ * generation with a trusted-app ACL. The helper reads the legacy item
+ * (which may pop the password sheet once), then deletes and re-adds it with
+ * the biometry access control. Returns true if the item was rewritten, false
+ * if no item by that name exists. macOS only — Linux backends have no ACL
+ * concept, so the call is a no-op there.
+ */
+export declare function migrateKeychainItem(item: string): boolean;
 /** Options controlling how secret refs are resolved. */
 export interface ResolveOptions {
     /** Translate a short keychain ID to a fully namespaced item name. */
@@ -84,8 +105,6 @@ export interface ResolveOptions {
     allowExec?: boolean;
     /** Restrict env: refs to this allowlist. When undefined, any env var may be read. */
     envAllowlist?: string[];
-    /** Read keychain refs from the iCloud-synced keychain backend. */
-    iCloudSync?: boolean;
 }
 /** Resolve a secret ref to its plaintext value using the appropriate provider. */
 export declare function resolveRef(ref: SecretRef, opts?: ResolveOptions): string;