@phnx-labs/agents-cli 1.22.57 → 1.22.59

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

@@ -1,27 +1,11 @@
 /**
- * The secrets-agent: a local broker that holds resolved bundle env in memory
- * after a single Touch ID unlock, so concurrent agent processes don't each pop
- * their own prompt.
+ * The secrets-agent: an in-memory broker that holds resolved bundle env after one
+ * Touch ID unlock, so concurrent agents don't each prompt.
  *
- * Why this exists: every secret item carries a biometry access control, and
- * macOS refuses to cache that across processes — N concurrent `agents run`
- * spawns = N Touch ID prompts (see src/lib/secrets/bundles.ts). The Swift
- * helper's LAContext only deduplicates reads *within one process*. This broker
- * is the ssh-agent answer: `agents secrets unlock <bundle>` decrypts the bundle
- * once (one prompt), ships the resolved env here, and every later read returns
- * from memory over a user-only Unix socket — no prompt.
- *
- * Security model (deliberate): while a bundle is unlocked, any same-user
- * process that can reach the socket reads it silently. That's strictly the same
- * trust boundary the keychain already concedes (docs/secrets.md: the ACL is
- * user-presence, not code-identity — any same-user process can pop the prompt
- * and read), minus the visible prompt. We bound it with: explicit per-bundle
- * opt-in (nothing is held unless you `unlock` it), an absolute TTL (~7d), an
- * auto-wipe on sleep / logout, and `agents secrets lock`. A bare screen-lock is
- * NOT a wipe (the login password already gates it). Nothing ever touches disk.
- *
- * macOS only: Linux libsecret has no biometry prompt, so there's nothing to
- * deduplicate — every entry point here no-ops off darwin.
+ * Security model: while unlocked, any same-user process reaching the socket can
+ * read it silently — the same trust boundary the keychain already concedes. We
+ * bound it with per-bundle opt-in, a TTL (~7d), auto-wipe on sleep/logout, and
+ * explicit lock. Nothing touches disk. Off-darwin the broker is unused.
  */
 import * as net from 'net';
 import type { SecretsBundle } from './bundles.js';
@@ -31,63 +15,33 @@ export { GLOBAL_HARNESS, bundleScopeChain };
 /** Default lifetime of an unlocked bundle when `--ttl` is not given. */
 export declare const DEFAULT_TTL_MS: number;
 /**
- * Whether the secrets broker service is enabled in the daemon service config.
- * Off-darwin this is irrelevant (the broker is never used), but the helper is
- * kept synchronous and safe everywhere so callers can fail loud without a prompt.
+ * Whether the secrets broker service is enabled in daemon service config.
  */
 export declare function isSecretsBrokerEnabled(): boolean;
 /**
  * Reserved store-key prefix for the `secrets list` metadata snapshot cache.
- * The broker holds the resolved bundle-metadata array (names/policy/timestamps,
- * NO resolved secret values beyond the literals already in metadata) keyed by a
- * hash of the current keychain bundle name-set, so the second and later
- * `secrets list` within the hold window read metadata without a Touch ID
- * prompt. Keyed by the name-set hash so adding/removing/renaming a bundle
- * changes the key and misses the cache automatically — no active invalidation.
- * The '!' sentinel can never collide with a real bundle name
- * (BUNDLE_NAME_PATTERN requires an alphanumeric first char) and is safe as
- * spawnSync argv (unlike a NUL byte); `status` hides these entries.
+ * Keyed by a hash of the keychain name-set; adding/removing/renaming a bundle
+ * changes the key and invalidates passively. The '!' sentinel cannot collide
+ * with a real bundle name and is safe as argv.
  */
 export declare const META_CACHE_PREFIX = "!meta:";
 export { SYNC_GET_CMD, SYNC_PING_CMD, SYNC_LOCK_CMD } from './sync-commands.js';
 /**
- * Decide whether a persistent broker should self-heal onto freshly-installed
- * code (exit so launchd relaunches it). Only when the store is EMPTY: exiting
- * with bundles still unlocked wipes them from memory, so the next reader falls
- * back to a direct keychain read and re-prompts for Touch ID. Deferring the
- * restart until the cache is idle (TTL-expired / slept) means an
- * in-place `npm i -g` never wipes a hot cache — the new code is adopted at the
- * next quiet moment instead. See #435: rapid repeated upgrades wiped a hot
- * cache on every bump and produced a recurring Touch ID storm.
+ * Decide whether a persistent broker should exit so launchd relaunches it on
+ * freshly-installed code. Only when the store is empty: exiting with held
+ * bundles would force a re-prompt. Deferring protects against rapid upgrades
+ * wiping the hot cache (#435).
  */
 export declare function shouldSelfHealForUpgrade(persistent: boolean, storeSize: number, runningVersion: string, onDiskVersion: string): boolean;
 /**
- * Client-side twin of shouldSelfHealForUpgrade: whether ensureAgentRunning may
- * tear down a reachable broker whose running version differs from the client's
- * on-disk version. Only while it holds NO real unlocks — tearing down a hot
- * broker wipes every held bundle, so the next read of each one re-prompts for
- * Touch ID. On a machine where installed versions churn (dev builds stamp a
- * fresh 0.0.0-dev.<sha> on every install; an npm copy and a dev copy invoke in
- * turn), an unguarded teardown produced a rolling Touch ID storm — the exact
- * failure #435 fixed on the server side. A hot, protocol-compatible broker
- * keeps serving; its own sweep adopts the new code at the next quiet moment.
+ * Client-side twin: may only tear down a version-skewed broker when it holds
+ * no real unlocks, otherwise every held bundle re-prompts (#435).
  */
 export declare function shouldTeardownVersionSkewedBroker(realHeldBundles: number): boolean;
 /**
- * Whether a version-skewed client may evict the reachable broker at all. The
- * held-bundle gate above is necessary but not sufficient: a broker the always-on
- * daemon is hosting must NEVER be client-evicted, even when it holds zero
- * unlocks. teardownStaleBroker() recognizes only the standalone broker's
- * pidPath() O_EXCL claim (the daemon writes ownerPath(), never pidPath()), so
- * evicting a daemon-hosted broker unlinks its socket WITHOUT stopping the daemon;
- * the daemon then keeps hostedBroker != null and shouldTakeOverBroker() refuses
- * to re-host, orphaning its broker until the daemon restarts while every reader
- * falls onto cold one-off brokers that re-prompt Touch ID — the storm. Deferring
- * is safe: daemon code-version upgrades are handled by postinstall.js restarting
- * it, and agentPing() already gated on PROTOCOL_VERSION, so a code-skewed daemon
- * broker is still wire-compatible. Only when NO daemon owns the broker (churning
- * dev installs with a dead/absent daemon — the case #435's client twin was built
- * for) does the zero-held-bundles teardown apply, exactly as before.
+ * Whether a client may evict a version-skewed broker. A daemon-hosted broker
+ * must never be client-evicted: the daemon owns the socket via ownerPath(), so
+ * unlinking it would orphan the broker until daemon restart (#435).
  */
 export declare function shouldClientEvictSkewedBroker(daemonRunning: boolean, realHeldBundles: number): boolean;
 export interface StoredBundle {
@@ -110,28 +64,21 @@ export interface AgentStatusEntry {
 /** Public accessor for the broker's socket path — `agents daemon status`/`services` reads it for display. */
 export declare function secretsBrokerSocketPath(): string;
 /**
- * Read the current broker capability token, or null if none is present. Clients
- * read it fresh per request and attach it to every non-ping command; a broker
- * restart mints a new token, so a stale read simply fails authorization and the
- * caller falls back to a direct keychain read (soft, never a hard error).
+ * Read the current broker capability token. A restart mints a new token, so a
+ * stale read fails soft and the caller falls back to a direct keychain read.
  */
 export declare function readAgentToken(): string | null;
 /** True if a legacy standalone-broker launchd plist is still installed. */
 export declare function secretsAgentServiceInstalled(): boolean;
 /**
- * Retire the legacy standalone secrets-agent launchd service: bootout the job
- * (falling back to the legacy `unload`) and remove its plist so the always-on
- * daemon owns the broker socket. Idempotent and best-effort — a no-op when no
- * legacy plist is present. Does NOT wipe held bundles: the booted-out process's
- * memory is gone anyway, and the daemon-hosted broker starts fresh.
+ * Retire the legacy standalone launchd service so the daemon owns the socket.
+ * Idempotent; does not wipe held bundles.
  */
 export declare function retireLegacySecretsAgentService(): void;
 /**
- * Stop the persistent broker for `agents secrets stop`: wipe whatever the broker
- * holds (forces Touch ID again on the next read), then retire any legacy
- * standalone service. The daemon-hosted broker itself is left running — it is
- * the always-on backbone, and stopping it would take down unrelated background
- * work (routines, browser IPC, session-sync).
+ * Stop the persistent broker for `agents secrets stop`: wipe held bundles, then
+ * retire any legacy standalone service. The daemon-hosted broker itself is left
+ * running because it backs unrelated background work.
  */
 export declare function uninstallSecretsAgentService(): Promise<void>;
 export type Request = {
@@ -199,73 +146,47 @@ export type Response = {
     error: string;
 };
 /**
- * Pure request handler over the in-memory store. Extracted so the store
- * semantics (lazy expiry on get/status, lock-one vs lock-all, load TTL) are
- * unit-testable with a controlled `now`, without a socket or a spawned process.
- * Mutates `store` in place; returns the wire response.
- */
-/**
- * Count of real unlocked bundles in the store, excluding the internal
- * `secrets list` metadata cache. Used to decide broker "warmth" for self-heal
- * and idle-exit: a metadata-only store must read as empty so a disposable list
- * cache never blocks an upgrade restart (#435) or an idle one-off broker from
- * exiting. Pure + exported for unit testing.
+ * Count of real unlocked bundles, excluding the internal `secrets list` metadata
+ * cache. A metadata-only store must read as empty so it doesn't block upgrade
+ * self-heal or idle-exit (#435). Exported for tests.
  */
 export declare function realBundleCount(store: Map<string, StoredBundle>): number;
 export declare function scopedBundleKey(name: string, harness: string): string;
+/** Pure request handler over the in-memory store. Exported for tests. */
 export declare function handleAgentRequest(store: Map<string, StoredBundle>, req: Request, now?: number, evictedAt?: Map<string, number>): Response;
 /**
- * Decide whether a `watch-lock` helper line should wipe the in-memory store.
- * The helper emits `LOCK` on screen-lock / screensaver and `SLEEP` on system
- * sleep. We wipe on SLEEP only: a bare screen-lock is already gated by the login
- * password, and with the ~7d hold, re-authing after every lock would defeat the
- * point. Logout needs no line — it tears down the launchd session and kills the
- * broker outright. Pure + exported so the LOCK-survives / SLEEP-wipes contract
- * has direct regression coverage (the inline stdout handler isn't unit-testable).
+ * Wipe the in-memory store only on SLEEP, not screen-lock (already gated by the
+ * login password). Exported for regression coverage of the LOCK-survives /
+ * SLEEP-wipes contract.
  */
 export declare function shouldWipeOnWatchEvent(chunk: string): boolean;
 /**
- * Authorization gate applied to every request BEFORE handleAgentRequest touches
- * the store (RUSH-1760). A bare same-UID socket connection is no longer trusted
- * to load/get arbitrary bundle env: each command except the liveness `ping` must
- * carry the per-broker capability token, which lives in a 0600 file inside the
- * 0700 agent dir and so is readable only by the UID that owns the broker.
- *
- * Fail closed: a missing/empty expected token (no token file) rejects every
- * command but ping. `ping` stays unauthenticated — it exposes only the protocol
- * and cli version, and clients need it to detect a reachable broker before they
- * have any reason to read the token. Pure + exported for direct unit testing.
+ * Authorization gate: every request except `ping` must carry the per-broker
+ * capability token from the 0600 token file. `ping` stays unauthenticated so
+ * clients can probe reachability before reading the token. Fail closed. Exported
+ * for tests.
  */
 export declare function isRequestAuthorized(req: Request, expectedToken: string | null): boolean;
 type BrokerConnectionHandler = (conn: net.Socket) => void;
 /**
- * Build the socket `connection` handler shared by both brokers (standalone and
- * daemon-hosted): newline-framed JSON in, one response line out, with the
- * authorization gate (isRequestAuthorized) applied before `handle`. `token`
- * resolves the currently-expected capability token per request so a token
- * rotation on broker restart is picked up without rebuilding the handler.
+ * Build the socket `connection` handler shared by standalone and daemon-hosted
+ * brokers. Newline-framed JSON in, one response line out, with per-request token
+ * lookup so rotation on restart is picked up.
  */
 export declare function makeConnectionHandler(handle: (req: Request) => Response, token: () => string | null): BrokerConnectionHandler;
 /**
- * Whether a live process still owns the broker pid file.
- *
- * A single missed `agentPing` is NOT proof the owner is dead — the broker is
- * single-threaded, so a big `get` or the rehydrate at startup can blow the
- * 700ms ping budget while the process is perfectly healthy. Treating that as
- * death let a starting broker unlink a live socket and rebind, leaving the old
- * process alive holding every unlocked bundle in RAM that no client could reach
- * any more (observed live: two brokers, one socket path, two kernel sockets).
- * The pid file is the second, independent liveness signal that makes the reclaim
+ * Whether a live process still owns the broker pid file. A single missed ping
+ * isn't proof of death: the single-threaded broker can blow the ping budget
+ * while healthy. The pid file is the second liveness signal that makes reclaim
  * safe.
  */
-/** Drop our ownership record, but only if it is still ours — never clobber a
- *  successor that already claimed the socket. */
+/** Drop our ownership record only if it is still ours. */
 export declare function releaseBrokerPid(): void;
 export declare function brokerPidAlive(): boolean;
 /**
- * Run the broker in the foreground. Spawned detached by ensureAgentRunning via
- * `agents secrets _agent-run`. Holds the store in memory, serves the socket,
- * sweeps expired entries, wipes on sleep, and self-exits when idle.
+ * Run the standalone broker in the foreground. Spawned by ensureAgentRunning via
+ * `agents secrets _agent-run`. Serves the socket, sweeps expired entries, wipes
+ * on sleep, and self-exits when idle.
  */
 export declare function runSecretsAgent(opts?: {
     service?: boolean;
@@ -273,72 +194,35 @@ export declare function runSecretsAgent(opts?: {
     close(): void | Promise<void>;
 } | null>;
 /**
- * Host the secrets broker inside the always-on daemon (#416).
- *
- * Serves the SAME socket and wire protocol as the standalone `runSecretsAgent`
- * — so every existing client (`agentGetSync`, `agentPing`, `agentAutoLoadSync`)
- * keeps working through the versioned protocol — but it is daemon-safe:
- *
- *   - no pid-file single-instance guard (the daemon owns the instance);
- *   - no `process.exit`, no SIGTERM/SIGINT handlers, no self-heal/idle-exit
- *     (those would kill the daemon — the daemon is the always-on backbone and
- *     manages its own version/lifecycle). The sweep only TTL-evicts.
- *
- * The caller (`runDaemon`) normally invokes this only when no broker answers
- * its initial ping. Binding still arbitrates ownership through the same shared
- * path as the standalone service: a live owner wins, while only an unreachable
- * stale socket is reclaimed. Returns a handle the daemon closes on shutdown,
- * or null off-darwin (nothing to broker without biometry).
+ * Host the secrets broker inside the always-on daemon (#416). Serves the same
+ * socket/protocol as the standalone broker, but daemon-safe: no pid-file guard,
+ * no process.exit/SIG handlers, no self-heal/idle-exit (the daemon owns the
+ * lifecycle). Returns null off-darwin.
  */
 export declare function startHostedBroker(): Promise<{
     close(): void | Promise<void>;
 } | null>;
 /**
- * Call Node's net.Server.close() and wait for the 'close' event (or a bounded
- * timeout). Without this, close() returned while the listen socket could still
- * be held — a successor bind could race EADDRINUSE against a half-closed server
- * (RUSH-2421). Pure side-effect helper; never throws.
+ * Wait for net.Server.close()'s 'close' event (or a bounded timeout) so a
+ * successor bind doesn't race a half-closed socket (RUSH-2421).
  */
 export declare function closeServerBounded(server: net.Server, timeoutMs?: number): Promise<void>;
-/** True if a broker socket exists at all. Cheap; gates the sync read so the
- * never-unlocked path stays a single stat. */
+/** Cheap socket-existence check so the never-unlocked path stays a single stat. */
 export declare function agentSocketExists(): boolean;
 /**
- * Spawn one of the `__secrets-*` sync clients and return its result.
- *
- * These three call sites used to hand-roll `spawnSync(process.execPath, ['-e',
- * <inline node program>, …])`. That is correct only for a JS install, where
- * `process.execPath` is `node`. Since 1.20.53 the shipped macOS `agents` is a
- * **bun-compiled Mach-O**, where `process.execPath` is the CLI binary itself —
- * so the spawn became `agents -e <program> …`, which commander rejects with
- * `error: unknown option '-e'` and a non-zero exit. Every sync client then took
- * its own failure path (`agentGetSync` → null, `agentReachableSync` → false,
- * `agentEvictSync` → no-op), which reads as "broker down" and falls through to
- * a real keychain read. Net effect on the standalone binary: the broker cache
- * was never hit, so the `daily` policy's one-prompt-per-7d never applied and
- * every bundle read re-popped Touch ID.
- *
- * Same defect class as the broker-launch bug fixed in 1.20.56 (see cliSpawn's
- * doc comment); these three sites were simply never converted. Routing them
- * through `getCliLaunch` fixes both install shapes at once and keeps a single
- * code path.
- *
- * The subcommands are top-level `__secrets-*` tokens intercepted in index.ts
- * BEFORE commander and before the CLI's startup work, exactly like
- * `__daemon-run` and `__vault-age-helper`. That is load-bearing, not cosmetic:
- * a normal command path runs `checkForUpdates()` and `spawnDetachedSync()` on
- * every invocation (index.ts), so registering these as ordinary hidden
- * subcommands would fire an update check and spawn a detached background sync
- * on every cache hit — turning the hot read path into a process fork storm.
+ * Spawn one of the `__secrets-*` sync clients via `getCliLaunch`. The old
+ * `process.execPath -e` pattern broke on the bun-compiled Mach-O binary
+ * (1.20.53); routing through getCliLaunch fixes both install shapes. The
+ * subcommands are intercepted in index.ts before commander/startup so a cache
+ * hit doesn't fork detached syncs or run update checks.
  */
 export declare function syncClientLaunch(sub: string[], agentsBin?: string): {
     command: string;
     args: string[];
 };
 /**
- * Synchronous read for the hot path. Returns the cached resolved bundle, or
- * null if the agent isn't running / doesn't hold this bundle / anything fails
- * (soft — caller falls through to the real keychain). macOS only.
+ * Synchronous read for the hot path. Returns null on any failure so the caller
+ * falls through to the real keychain. macOS only.
  */
 export declare function agentGetSync(name: string, harness?: string): {
     bundle: SecretsBundle;
@@ -346,70 +230,41 @@ export declare function agentGetSync(name: string, harness?: string): {
     lease?: SecretLease;
 } | null;
 /**
- * Last non-empty line of a child's stdout — the payload line.
- *
- * The inline `node -e` client this replaced was a bare node process that could
- * only ever emit its own JSON. The replacement boots the real CLI, so anything
- * the CLI prints on the way up shares that stream. Today the known chatter (the
- * `~/.agents/ is N commits behind` notice) correctly goes to stderr, but a
- * single future stdout write anywhere in startup would make `JSON.parse` throw
- * and turn every cache hit back into a silent miss — i.e. quietly reintroduce
- * the Touch-ID-on-every-read bug this fix closes, with no failing test to catch
- * it. Anchoring on the last line makes the payload the terminator of the
- * stream rather than the whole of it, so preceding chatter is inert.
+ * Last non-empty line of a child's stdout — the payload line. Anchors on the
+ * terminator so any future CLI startup chatter on stdout doesn't break JSON.parse
+ * and silently turn cache hits into misses.
  */
 export declare function lastLine(stdout: string): string;
 /**
- * Synchronous liveness check: is a broker actually LISTENING and answering (not
- * just a lingering socket file)? Used to decide whether the auto-cache may take
- * the synchronous warm path — a dead broker whose socket outlived it (crash,
- * OOM, version-skew teardown) must NOT drag a foreground read through the
- * worker's 20s cold-start budget. A stale socket refuses instantly, so this is
- * fast in both the alive and dead cases. macOS only.
+ * Synchronous liveness check: is a broker actually listening? Gates the
+ * synchronous warm path so a stale socket doesn't drag a foreground read
+ * through a cold-start. macOS only.
  */
 export declare function agentReachableSync(): boolean;
 /**
- * Synchronously evict one bundle from the broker. Called after a mutating
- * keychain write (add / rotate / remove / rename / delete) so the broker never
- * keeps serving the pre-write snapshot for up to the ~7d hold — the next read
- * re-resolves from the keychain (one prompt) and re-caches fresh values.
- * Best-effort: no broker, no socket, or any failure is a silent no-op.
- * macOS only.
+ * Synchronously evict one bundle after a mutating write so the broker doesn't
+ * serve a stale snapshot for the hold window. Best-effort silent no-op. macOS only.
  */
 export declare function agentEvictSync(name: string): void;
-/** Body of `__secrets-get <name>`. Prints `{bundle, env}` as JSON on a
- * cache hit. Exit 0 = hit, 3 = miss or broker down. */
+/** Body of `__secrets-get <name>`. Exit 0 = hit, 3 = miss/down. */
 export declare function runAgentGetSync(name: string, harness?: string): Promise<number>;
-/** Body of `__secrets-ping`. Exit 0 = a broker is listening and speaking
- * our protocol, 3 = nothing there. Deliberately does NOT gate on
- * PROTOCOL_VERSION: this only decides whether the auto-cache may take the
- * synchronous warm path, and a version-skewed broker still answers reads. That
- * matches the inline program this replaced. */
+/** Body of `__secrets-ping`. Exit 0 = listening broker, 3 = nothing there.
+ * Does not gate on PROTOCOL_VERSION so version-skewed brokers still answer reads. */
 export declare function runAgentPingSync(): Promise<number>;
 /** Body of `__secrets-lock <name>`. Best-effort evict; exit 0 even when no
- * broker answers, so a missing broker never fails the mutating write that
- * triggered it (agentEvictSync discards this either way).
- *
- * An empty name is refused rather than forwarded: the broker treats a nameless
- * lock as lock-ALL (handleAgentRequest), so a bare `__secrets-lock` would wipe
- * every held bundle and re-prompt Touch ID for each. That was unreachable while
- * this was an inline `node -e` string; as a top-level argv token it is one typo
- * away, and agentEvictSync only ever locks by name. */
+ * broker answers. An empty name is refused to avoid accidentally locking ALL
+ * bundles. */
 export declare function runAgentLockSync(name: string): Promise<number>;
 /**
- * Read the cached `secrets list` metadata snapshot for the given keychain
- * name-set hash, or null on miss / no broker / off-darwin. Reuses the value
- * fast-path socket read (agentGetSync) — no prompt, no wire change. The hash is
- * the cache key: a changed name-set (bundle added/removed/renamed) yields a
- * different key and therefore a clean miss, so the stale set is never served.
+ * Read the cached `secrets list` metadata snapshot for a keychain name-set hash.
+ * Reuses agentGetSync. The name-set hash is the cache key, so add/remove/rename
+ * yields a clean miss.
  */
 export declare function agentGetMetaSync(nameSetHash: string): SecretsBundle[] | null;
 /**
- * Fire-and-forget: populate the broker with a freshly-read metadata snapshot so
- * the next `secrets list` within the hold window renders without a prompt.
- * Stored as an ordinary entry (placeholder bundle, snapshot in env) under the
- * reserved META_CACHE_PREFIX key; the snapshot travels over stdin to the
- * detached worker (never argv/disk), same as value caching. macOS only.
+ * Fire-and-forget: populate the broker with a metadata snapshot so the next
+ * `secrets list` within the hold window is prompt-free. Stored under a reserved
+ * META_CACHE_PREFIX key; snapshot travels over stdin. macOS only.
  */
 export declare function agentAutoLoadMetaSync(nameSetHash: string, bundles: SecretsBundle[], ttlMs: number): void;
 /** True unless `secrets.agent.auto` is explicitly disabled in agents.yaml. The