@phnx-labs/agents-cli 1.14.2 → 1.14.4

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

@@ -1,23 +1,53 @@
 /**
  * Secret bundles -- named sets of keychain-backed environment variables.
  *
- * Each bundle is a YAML file in ~/.agents/secrets/ declaring key names.
- * Values live in the macOS Keychain and are injected into the agent's
- * environment at spawn time via `agents run --secrets <bundle>`.
+ * 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.
+ *
+ * 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.
  */
 import { type BundleValue, type SecretRef } from './index.js';
+/** Allowed values for a secret's `type` metadata field. */
+export declare const SECRET_TYPES: readonly ["api-key", "token", "password", "url", "database-url", "ssh-key", "certificate", "webhook", "note"];
+export type SecretType = typeof SECRET_TYPES[number];
+/** Per-secret metadata. All fields optional; absent ones omitted at write time. */
+export interface VarMeta {
+    type?: SecretType;
+    /** ISO date 'YYYY-MM-DD'. Always future-dated at write time. */
+    expires?: string;
+    /** Singular freeform note. */
+    note?: string;
+}
 /** A named set of environment variable definitions backed by various secret providers. */
 export interface SecretsBundle {
     name: string;
     description?: string;
     allow_exec?: boolean;
-    /** When true, keychain-backed values are stored in iCloud Keychain so they sync across the user's Macs. */
+    /** When true, keychain-backed values and bundle metadata sync via iCloud Keychain. */
     icloud_sync?: boolean;
     vars: Record<string, BundleValue>;
+    /** Optional per-var metadata, keyed by var name (parallel to `vars`). */
+    meta?: Record<string, VarMeta>;
 }
+export declare const RESERVED_ENV_NAMES: Set<string>;
+export declare function bundleToEnvPrefix(name: string): string;
+export declare function isReservedEnvName(key: string): boolean;
 /** Validate a bundle name against the allowed pattern. Throws on invalid input. */
 export declare function validateBundleName(name: string): void;
 export declare function validateEnvKey(key: string): void;
+/** Assert that `t` is one of the known SECRET_TYPES. Throws with the allowed list otherwise. */
+export declare function validateSecretType(t: string): asserts t is SecretType;
+/**
+ * Validate an `expires` value. Accepts strict 'YYYY-MM-DD' only and rejects
+ * any date <= now. We compare against end-of-day UTC for the chosen date so
+ * "today" is treated as past (per spec).
+ */
+export declare function validateExpiresFutureDated(iso: string): void;
 export declare function bundleExists(name: string): boolean;
 export declare function readBundle(name: string): SecretsBundle;
 export declare function writeBundle(bundle: SecretsBundle): void;
@@ -31,9 +61,36 @@ export interface BundleEntryInfo {
 export declare function describeBundle(bundle: SecretsBundle): BundleEntryInfo[];
 export declare function resolveBundleEnv(bundle: SecretsBundle): Record<string, string>;
 export declare function keychainRef(key: string): string;
+/** Options for rotateBundleSecret. */
+export interface RotateOptions {
+    /** New plaintext value to write into keychain (replaces the old one). */
+    newValue: string;
+    /** When true, drop existing meta for this key. Mutually exclusive with `meta`. */
+    clearMeta?: boolean;
+    /** Patch to merge into existing meta. Undefined fields preserve current values. */
+    meta?: Partial<VarMeta>;
+}
+/**
+ * Rotate a keychain-backed secret in `bundle`. Errors if `key` is not present
+ * in the bundle (use `add` to introduce a new key). Preserves existing meta
+ * unless `clearMeta` or a `meta` patch is supplied.
+ */
+export declare function rotateBundleSecret(bundle: SecretsBundle, key: string, opts: RotateOptions): void;
 export declare function keychainItemsForBundle(bundle: SecretsBundle): Array<{
     key: string;
     item: string;
 }>;
 export declare function parseDotenv(content: string): Record<string, string>;
+/**
+ * One-shot migration: move legacy YAML bundles into the keychain. Scans both
+ * `~/.agents/secrets/` and `~/.agents-system/secrets/` — past versions of the
+ * CLI sometimes wrote bundles into the system repo even though that's never
+ * been a legitimate location. After migration the directories are removed so
+ * the system repo never carries a `secrets/` subdir again.
+ *
+ * Idempotent: re-runs after the dirs are gone are no-ops. Called eagerly at
+ * the top of every `agents secrets` subcommand. Skipped on the latency-
+ * sensitive `agents run` path.
+ */
+export declare function migrateLegacyBundles(): void;
 export type { SecretRef };

package/dist/lib/secrets/bundles.js

@@ -1,21 +1,51 @@
 /**
  * Secret bundles -- named sets of keychain-backed environment variables.
  *
- * Each bundle is a YAML file in ~/.agents/secrets/ declaring key names.
- * Values live in the macOS Keychain and are injected into the agent's
- * environment at spawn time via `agents run --secrets <bundle>`.
+ * 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.
+ *
+ * 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.
  */
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import * as yaml from 'yaml';
-import { getSecretsDir, getUserSecretsDir } from '../state.js';
-import { parseBundleValue, resolveRef, secretsKeychainItem, } from './index.js';
-const BUNDLE_NAME_PATTERN = /^[a-z0-9][a-z0-9-_]{0,48}$/i;
+import { deleteKeychainToken, getKeychainToken, hasKeychainToken, listKeychainItems, parseBundleValue, resolveRef, secretsKeychainItem, setKeychainToken, } from './index.js';
+/** Allowed values for a secret's `type` metadata field. */
+export const SECRET_TYPES = [
+    'api-key',
+    'token',
+    'password',
+    'url',
+    'database-url',
+    'ssh-key',
+    'certificate',
+    'webhook',
+    'note',
+];
+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.';
+export const RESERVED_ENV_NAMES = new Set([
+    'PATH', 'HOME', 'USER', 'USERNAME', 'SHELL', 'PWD', 'OLDPWD',
+    'TERM', 'LANG', 'LC_ALL', 'DISPLAY', 'EDITOR', 'VISUAL',
+    'TMPDIR', 'TMP', 'TEMP', 'LOGNAME', 'UID', 'EUID', 'HOSTNAME',
+]);
+export function bundleToEnvPrefix(name) {
+    return name.replace(/[-\.]/g, '_').toUpperCase();
+}
+export function isReservedEnvName(key) {
+    return RESERVED_ENV_NAMES.has(key);
+}
 /** Validate a bundle name against the allowed pattern. Throws on invalid input. */
 export function validateBundleName(name) {
     if (!BUNDLE_NAME_PATTERN.test(name)) {
-        throw new Error(`Invalid bundle name '${name}'. Use letters, digits, dash, underscore (max 48 chars).`);
+        throw new Error(`Invalid bundle name '${name}'. Use letters, digits, dash, underscore, dot (max 48 chars).`);
     }
 }
 export function validateEnvKey(key) {
@@ -23,37 +53,64 @@ export function validateEnvKey(key) {
         throw new Error(`Invalid environment variable name '${key}'. Must match [A-Za-z_][A-Za-z0-9_]*.`);
     }
 }
-function bundlePath(name) {
-    // Check user dir first (for reads), write to user dir
-    const userPath = path.join(getUserSecretsDir(), `${name}.yml`);
-    if (fs.existsSync(userPath))
-        return userPath;
-    const systemPath = path.join(getSecretsDir(), `${name}.yml`);
-    if (fs.existsSync(systemPath))
-        return systemPath;
-    return userPath; // default write location
+/** Assert that `t` is one of the known SECRET_TYPES. Throws with the allowed list otherwise. */
+export function validateSecretType(t) {
+    if (!SECRET_TYPES.includes(t)) {
+        throw new Error(`Invalid type '${t}'. One of: ${SECRET_TYPES.join(', ')}.`);
+    }
+}
+/**
+ * Validate an `expires` value. Accepts strict 'YYYY-MM-DD' only and rejects
+ * any date <= now. We compare against end-of-day UTC for the chosen date so
+ * "today" is treated as past (per spec).
+ */
+export function validateExpiresFutureDated(iso) {
+    if (!/^\d{4}-\d{2}-\d{2}$/.test(iso)) {
+        throw new Error(`Invalid --expires '${iso}'. Use YYYY-MM-DD.`);
+    }
+    const target = new Date(iso + 'T23:59:59Z');
+    if (Number.isNaN(target.getTime()))
+        throw new Error(`Invalid --expires date '${iso}'.`);
+    if (target.getTime() <= Date.now()) {
+        throw new Error(`--expires must be future-dated. Got '${iso}'.`);
+    }
+}
+function bundleMetaItem(name) {
+    return BUNDLE_META_PREFIX + name;
 }
 export function bundleExists(name) {
-    return fs.existsSync(bundlePath(name));
+    validateBundleName(name);
+    return hasKeychainToken(bundleMetaItem(name));
 }
 export function readBundle(name) {
     validateBundleName(name);
-    const file = bundlePath(name);
-    if (!fs.existsSync(file)) {
+    let json;
+    try {
+        json = getKeychainToken(bundleMetaItem(name));
+    }
+    catch {
         throw new Error(`Secrets bundle '${name}' not found.`);
     }
-    const raw = fs.readFileSync(file, 'utf-8');
-    const parsed = yaml.parse(raw);
+    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: parsed.name || name,
+        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 (parsed.meta && typeof parsed.meta === 'object') {
+        bundle.meta = parsed.meta;
+    }
     for (const key of Object.keys(bundle.vars)) {
         validateEnvKey(key);
     }
@@ -64,48 +121,59 @@ export function writeBundle(bundle) {
     for (const key of Object.keys(bundle.vars)) {
         validateEnvKey(key);
     }
-    const dir = getUserSecretsDir();
-    fs.mkdirSync(dir, { recursive: true });
-    const body = yaml.stringify({
-        name: bundle.name,
+    // Strip empty/all-undefined meta entries so the JSON stays tidy.
+    let meta;
+    if (bundle.meta) {
+        for (const [key, m] of Object.entries(bundle.meta)) {
+            const cleaned = {};
+            if (m.type)
+                cleaned.type = m.type;
+            if (m.expires)
+                cleaned.expires = m.expires;
+            if (m.note)
+                cleaned.note = m.note;
+            if (Object.keys(cleaned).length > 0) {
+                if (!meta)
+                    meta = {};
+                meta[key] = cleaned;
+            }
+        }
+    }
+    const payload = {
         description: bundle.description,
         allow_exec: bundle.allow_exec ? true : undefined,
         icloud_sync: bundle.icloud_sync ? true : undefined,
         vars: bundle.vars,
-    });
-    const file = bundlePath(bundle.name);
-    const tmp = `${file}.tmp-${process.pid}`;
-    fs.writeFileSync(tmp, body, 'utf-8');
-    fs.renameSync(tmp, file);
+        meta,
+    };
+    const json = JSON.stringify(payload);
+    setKeychainToken(bundleMetaItem(bundle.name), json, Boolean(bundle.icloud_sync));
 }
 export function deleteBundle(name) {
     validateBundleName(name);
-    const file = bundlePath(name);
-    if (!fs.existsSync(file))
-        return false;
-    fs.unlinkSync(file);
-    return true;
+    return deleteKeychainToken(bundleMetaItem(name));
 }
 export function listBundles() {
-    const seen = new Set();
-    const bundles = [];
-    for (const dir of [getUserSecretsDir(), getSecretsDir()]) {
-        if (!fs.existsSync(dir))
-            continue;
-        for (const entry of fs.readdirSync(dir).filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'))) {
-            const name = entry.replace(/\.(yml|yaml)$/, '');
-            if (seen.has(name))
-                continue;
-            seen.add(name);
-            try {
-                bundles.push(readBundle(name));
-            }
-            catch {
-                // Skip malformed bundles; surfaced via `agents secrets view <name>`.
-            }
+    let services;
+    try {
+        services = listKeychainItems(BUNDLE_META_PREFIX);
+    }
+    catch {
+        return [];
+    }
+    const names = services
+        .map((s) => s.slice(BUNDLE_META_PREFIX.length))
+        .filter((n) => BUNDLE_NAME_PATTERN.test(n));
+    const out = [];
+    for (const name of names) {
+        try {
+            out.push(readBundle(name));
+        }
+        catch {
+            // Skip malformed bundles; surfaced via `agents secrets view <name>`.
         }
     }
-    return bundles.sort((a, b) => a.name.localeCompare(b.name));
+    return out.sort((a, b) => a.name.localeCompare(b.name));
 }
 export function describeBundle(bundle) {
     const out = [];
@@ -149,10 +217,49 @@ export function resolveBundleEnv(bundle) {
     }
     return env;
 }
-// Build a keychain ref expression from a bundle+key pair, for storage in YAML.
+// Build a keychain ref expression from a bundle+key pair, for storage in the bundle metadata.
 export function keychainRef(key) {
     return `keychain:${key}`;
 }
+/**
+ * Rotate a keychain-backed secret in `bundle`. Errors if `key` is not present
+ * in the bundle (use `add` to introduce a new key). Preserves existing meta
+ * unless `clearMeta` or a `meta` patch is supplied.
+ */
+export function rotateBundleSecret(bundle, key, opts) {
+    validateBundleName(bundle.name);
+    validateEnvKey(key);
+    if (!(key in bundle.vars)) {
+        throw new Error(`Key '${key}' not in bundle '${bundle.name}'. Use 'agents secrets add' to add a new key.`);
+    }
+    const raw = bundle.vars[key];
+    // We only rotate keychain-backed values. Literals/refs aren't "secrets" in
+    // the same sense — pivot the user back to add/remove.
+    if (typeof raw !== 'string' || !raw.startsWith('keychain:')) {
+        throw new Error(`Key '${key}' in bundle '${bundle.name}' is not keychain-backed; cannot rotate.`);
+    }
+    const shortId = raw.slice('keychain:'.length);
+    const item = secretsKeychainItem(bundle.name, shortId);
+    setKeychainToken(item, opts.newValue, bundle.icloud_sync);
+    if (opts.clearMeta) {
+        if (bundle.meta)
+            delete bundle.meta[key];
+    }
+    else if (opts.meta && Object.keys(opts.meta).length > 0) {
+        if (!bundle.meta)
+            bundle.meta = {};
+        const current = bundle.meta[key] ?? {};
+        const patched = { ...current };
+        if (opts.meta.type !== undefined)
+            patched.type = opts.meta.type;
+        if (opts.meta.expires !== undefined)
+            patched.expires = opts.meta.expires;
+        if (opts.meta.note !== undefined)
+            patched.note = opts.meta.note;
+        bundle.meta[key] = patched;
+    }
+    writeBundle(bundle);
+}
 // Iterate all keychain-backed keys in a bundle for cleanup on rm/unset.
 export function keychainItemsForBundle(bundle) {
     const items = [];
@@ -187,3 +294,64 @@ export function parseDotenv(content) {
     }
     return out;
 }
+/**
+ * One-shot migration: move legacy YAML bundles into the keychain. Scans both
+ * `~/.agents/secrets/` and `~/.agents-system/secrets/` — past versions of the
+ * CLI sometimes wrote bundles into the system repo even though that's never
+ * been a legitimate location. After migration the directories are removed so
+ * the system repo never carries a `secrets/` subdir again.
+ *
+ * Idempotent: re-runs after the dirs are gone are no-ops. Called eagerly at
+ * the top of every `agents secrets` subcommand. Skipped on the latency-
+ * sensitive `agents run` path.
+ */
+export function migrateLegacyBundles() {
+    const home = os.homedir();
+    const dirs = [
+        path.join(home, '.agents', 'secrets'),
+        path.join(home, '.agents-system', 'secrets'),
+    ];
+    let migrated = 0;
+    for (const dir of dirs) {
+        let entries;
+        try {
+            entries = fs.readdirSync(dir);
+        }
+        catch {
+            continue;
+        }
+        const ymls = entries.filter((f) => f.endsWith('.yml') || f.endsWith('.yaml'));
+        for (const entry of ymls) {
+            const file = path.join(dir, entry);
+            const name = entry.replace(/\.(yml|yaml)$/, '');
+            try {
+                validateBundleName(name);
+                const raw = fs.readFileSync(file, 'utf-8');
+                const parsed = yaml.parse(raw);
+                if (!parsed || typeof parsed !== 'object')
+                    continue;
+                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 : {},
+                };
+                writeBundle(bundle);
+                fs.unlinkSync(file);
+                migrated++;
+            }
+            catch {
+                // Leave malformed YAMLs in place so the user can inspect them.
+            }
+        }
+        try {
+            if (fs.readdirSync(dir).length === 0)
+                fs.rmdirSync(dir);
+        }
+        catch { /* not empty or already gone */ }
+    }
+    if (migrated > 0) {
+        console.log(`Migrated ${migrated} legacy bundle${migrated === 1 ? '' : 's'} into keychain.`);
+    }
+}

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

@@ -1,9 +1,11 @@
 /**
  * macOS Keychain integration for secure credential storage.
  *
- * Calls a compiled Swift helper (keychain-helper.swift) to store and retrieve
- * API keys and tokens via the Security framework, with kSecAttrSynchronizable
- * set so iCloud Keychain syncs them across the user's Macs.
+ * All reads/writes go through a signed Swift helper (keychain-helper.swift)
+ * compiled into AgentsKeychain.app. 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.
  */
 /** Supported secret resolution backends. */
 export type SecretProvider = 'keychain' | 'env' | 'file' | 'exec';
@@ -13,14 +15,14 @@ export interface SecretRef {
     value: string;
 }
 /**
- * A bundle YAML value: either a string (literal or provider-prefixed ref) or
+ * A bundle value: either a string (literal or provider-prefixed ref) or
  * an object `{value: string}` used to escape a literal that would otherwise
  * be parsed as a ref (e.g. a URL that happens to start with 'env:').
  */
 export type BundleValue = string | {
     value: string;
 };
-/** Parse a bundle YAML value into either a literal string or a typed secret ref. */
+/** Parse a bundle value into either a literal string or a typed secret ref. */
 export declare function parseBundleValue(raw: BundleValue): {
     literal: string;
 } | {
@@ -32,6 +34,21 @@ export declare function serializeRef(ref: SecretRef): string;
 export declare function profileKeychainItem(provider: string): string;
 /** Build the keychain item name for a secrets-bundle key. */
 export declare function secretsKeychainItem(bundle: string, key: string): string;
+/**
+ * Test seam: lets bundle storage tests swap the keychain backend for an
+ * in-memory map without touching the user's real keychain. Mocking is
+ * justified here because the alternative (touching real keychain in unit
+ * 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;
+    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 item exists (macOS only). */
 export declare function hasKeychainToken(item: string, sync?: boolean): boolean;
 /** Retrieve a secret value from the macOS Keychain. Throws if not found. */
@@ -40,6 +57,8 @@ export declare function getKeychainToken(item: string, sync?: boolean): string;
 export declare function setKeychainToken(item: string, value: string, sync?: boolean): void;
 /** Delete a keychain item. Returns true if it existed. */
 export declare function deleteKeychainToken(item: string, sync?: boolean): boolean;
+/** Enumerate keychain item service names whose name starts with the given prefix. */
+export declare function listKeychainItems(prefix: string): string[];
 /** Options controlling how secret refs are resolved. */
 export interface ResolveOptions {
     /** Translate a short keychain ID to a fully namespaced item name. */