@phnx-labs/agents-cli 1.20.0 → 1.20.4

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 = [
@@ -63,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)) {
@@ -125,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')
@@ -146,7 +158,7 @@ export function readBundle(name) {
     }
     return bundle;
 }
-export function writeBundle(bundle, opts = {}) {
+export function writeBundle(bundle) {
     validateBundleName(bundle.name);
     for (const key of Object.keys(bundle.vars)) {
         validateEnvKey(key);
@@ -179,7 +191,6 @@ export function writeBundle(bundle, opts = {}) {
     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,
@@ -187,10 +198,8 @@ export function writeBundle(bundle, opts = {}) {
         meta,
     };
     const json = JSON.stringify(payload);
-    setKeychainToken(bundleMetaItem(bundle.name), json, Boolean(bundle.icloud_sync));
-    if (opts.emitEvent !== false) {
-        emit('secrets.set', { bundle: bundle.name });
-    }
+    setKeychainToken(bundleMetaItem(bundle.name), json);
+    emit('secrets.set', { bundle: bundle.name });
 }
 export function deleteBundle(name) {
     validateBundleName(name);
@@ -220,7 +229,7 @@ export function listBundles() {
     // 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 = getKeychainTokensBatch(itemsToFetch, false, 'list secrets bundles');
+    const fetched = getKeychainTokens(itemsToFetch);
     const out = [];
     for (const name of names) {
         const json = fetched.get(bundleMetaItem(name));
@@ -240,7 +249,6 @@ export function listBundles() {
             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')
@@ -294,90 +302,63 @@ function stampLastUsed(bundle) {
     }
     try {
         bundle.last_used = new Date(nowMs).toISOString();
-        writeBundle(bundle, { emitEvent: false });
+        writeBundle(bundle);
     }
     catch {
         // 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 keychainKeys = [];
-    const kindCounts = {};
     for (const [key, raw] of Object.entries(bundle.vars)) {
         const parsed = parseBundleValue(raw);
         parsedByKey.set(key, parsed);
-        const kind = 'literal' in parsed ? 'literal' : parsed.ref.provider;
-        kindCounts[kind] = (kindCounts[kind] ?? 0) + 1;
         if ('ref' in parsed && parsed.ref.provider === 'keychain') {
-            const item = secretsKeychainItem(bundle.name, parsed.ref.value);
-            keychainItemsToFetch.push(item);
-            keychainKeys.push(key);
+            keychainItemsToFetch.push(secretsKeychainItem(bundle.name, parsed.ref.value));
         }
     }
-    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),
-        });
-    };
-    // 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`;
-    try {
-        // Single helper invocation, one biometric prompt.
-        const fetched = keychainItemsToFetch.length > 0
-            ? getKeychainTokensBatch(keychainItemsToFetch, bundle.icloud_sync, reason)
-            : 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] of Object.entries(bundle.vars)) {
-            const parsed = parsedByKey.get(key);
-            if ('literal' in parsed) {
-                env[key] = parsed.literal;
-                continue;
-            }
-            if (parsed.ref.provider === 'keychain') {
-                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. ` +
-                        `Run: agents secrets add ${bundle.name} ${key}`);
-                }
-                env[key] = value;
-                continue;
-            }
-            try {
-                env[key] = resolveRef(parsed.ref, {
-                    allowExec: bundle.allow_exec,
-                    iCloudSync: bundle.icloud_sync,
-                    keychainItemFor: (shortId) => secretsKeychainItem(bundle.name, shortId),
-                });
-            }
-            catch (err) {
-                throw new Error(`Bundle '${bundle.name}' key '${key}': ${err.message}`);
+    const fetched = keychainItemsToFetch.length > 0
+        ? getKeychainTokens(keychainItemsToFetch)
+        : new Map();
+    const env = {};
+    for (const [key, raw] of Object.entries(bundle.vars)) {
+        const parsed = parsedByKey.get(key);
+        if ('literal' in parsed) {
+            env[key] = parsed.literal;
+            continue;
+        }
+        if (parsed.ref.provider === 'keychain') {
+            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. ` +
+                    `Run: agents secrets add ${bundle.name} ${key}`);
             }
+            env[key] = value;
+            continue;
+        }
+        try {
+            env[key] = resolveRef(parsed.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 env;
-    }
-    catch (err) {
-        emitReadAudit('error', err);
-        throw err;
     }
+    // `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.
@@ -406,10 +387,8 @@ export function readAndResolveBundleEnv(name, opts = {}) {
     const reason = opts.caller
         ? `read ${name} secrets (for ${opts.caller})`
         : `read ${name} secrets`;
-    // icloud_sync flag is unknown until we parse metadata, but the helper's
-    // get-batch uses kSecAttrSynchronizableAny so it finds both synced and
-    // device-local items in one shot.
-    const fetched = getKeychainTokensBatch([metaItem, ...secretItems], false, reason);
+    void reason;
+    const fetched = getKeychainTokens([metaItem, ...secretItems]);
     const json = fetched.get(metaItem);
     if (json === undefined) {
         throw new Error(`Secrets bundle '${name}' not found.`);
@@ -428,7 +407,6 @@ export function readAndResolveBundleEnv(name, opts = {}) {
         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')
@@ -490,7 +468,6 @@ export function readAndResolveBundleEnv(name, opts = {}) {
             try {
                 env[key] = resolveRef(p.ref, {
                     allowExec: bundle.allow_exec,
-                    iCloudSync: bundle.icloud_sync,
                     keychainItemFor: (shortId) => secretsKeychainItem(bundle.name, shortId),
                 });
             }
@@ -529,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];
@@ -560,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);
@@ -579,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);
     }
@@ -592,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 });
@@ -674,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,33 +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;
 /**
- * Read multiple keychain items, returning a Map keyed by item name. Missing or
- * unreadable items are simply absent from the map (the caller decides whether a
- * given key was required).
+ * Retrieve a secret value from the keychain/keyring. Throws if not found.
  *
- * On macOS this uses the signed helper's `get-batch` command so one LAContext
- * can satisfy all protected item reads for the bundle.
+ * 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 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 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
+ * 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;
+/** 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. */
@@ -79,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;