@phnx-labs/agents-cli 1.22.84 → 1.22.86

package/dist/lib/secrets/install-helper.d.ts

@@ -1,72 +0,0 @@
-/**
- * Stable install location for the signed macOS Keychain helper.
- *
- * Why a stable path: every npm publish re-signs `Agents CLI.app` with a fresh
- * timestamp, producing a new code signature. macOS Keychain trusted-app ACLs
- * are pinned to the exact signature, so the ACL invalidates on every release
- * when the helper lives inside the npm package directory. Copying the .app
- * once to `~/Library/Application Support/agents-cli/` gives it a path that
- * survives `npm i -g`, `scripts/install.sh`, version bumps, etc.
- *
- * This module is the SINGLE SOURCE OF TRUTH for the helper path. Other
- * modules in `src/lib/secrets/` must import `getKeychainHelperPath()` rather
- * than recomputing it.
- */
-/** Redirect the install root (test only). Returns the previous override so callers can restore. */
-export declare function setInstallRootForTest(dir: string | null): string | null;
-/**
- * Idempotent install. Copies the bundled `.app` to the stable user path. Skips
- * if the destination already exists, `codesign --verify` passes, AND the
- * installed executable matches the bundled one byte-for-byte — a valid
- * signature alone is not enough, because an outdated helper signs clean too.
- * `forceReinstall=true` skips all checks and always copies.
- *
- * Notarization is checked via `spctl --assess` after install — a failure is
- * logged as a warning but does NOT throw. Notarization checks require network
- * access (Gatekeeper ticket lookup) and are not load-bearing for the helper's
- * keychain ACL semantics.
- */
-export declare function ensureKeychainHelperInstalled(opts?: {
-    forceReinstall?: boolean;
-}): void;
-/**
- * ASYNC, download-capable install — the EXPLICIT onboarding/upgrade path
- * (`agents setup secrets`, the bootstrap upgrade self-heal). When a bundled or
- * locally-built `.app` ships (the common case, and always true this release
- * stage), it installs that copy with NO network. When the tarball lacks the
- * bundle (a fresh `npm i -g` whose tarball dropped it), it fetches the signed +
- * notarized release asset for the running CLI version — sha256 + codesign +
- * Team + notarization verified before install — and installs from the cached
- * copy. The sync `getKeychainHelperPath()` never routes here: it stays sync +
- * network-free and fails loud toward this command when no source exists.
- */
-export declare function ensureKeychainHelperInstalledAsync(opts?: {
-    forceReinstall?: boolean;
-}): Promise<void>;
-/**
- * Return the absolute path to the helper executable. If the installed bundle
- * is missing, or is stale relative to the bundled source helper, performs a
- * lazy (re)install first. The staleness check is what lets an upgraded CLI
- * replace a helper a previous version installed — the install never runs on
- * `npm i -g`, so this call site is the only one every machine is guaranteed to
- * pass through.
- *
- * SYNC and network-free by design: this is the secrets hot path, called by
- * every keychain op. It never downloads. When no bundled/local source exists
- * (a tarball that dropped the bundle), the reinstall's `sourceAppPath()` throws
- * loud, directing the user to `agents setup secrets` — the explicit, async,
- * download-capable path (`ensureKeychainHelperInstalledAsync`). Throws on
- * non-darwin.
- */
-export declare function getKeychainHelperPath(): string;
-/** Diagnostic snapshot of the installed Keychain helper. */
-export interface KeychainHelperStatus {
-    source: string | null;
-    destination: string;
-    installed: boolean;
-    codesignOk: boolean;
-    codesignOutput: string;
-    spctlOk: boolean;
-    spctlOutput: string;
-}
-export declare function getKeychainHelperStatus(): KeychainHelperStatus;

package/dist/lib/secrets/install-helper.js

@@ -1,245 +0,0 @@
-/**
- * Stable install location for the signed macOS Keychain helper.
- *
- * Why a stable path: every npm publish re-signs `Agents CLI.app` with a fresh
- * timestamp, producing a new code signature. macOS Keychain trusted-app ACLs
- * are pinned to the exact signature, so the ACL invalidates on every release
- * when the helper lives inside the npm package directory. Copying the .app
- * once to `~/Library/Application Support/agents-cli/` gives it a path that
- * survives `npm i -g`, `scripts/install.sh`, version bumps, etc.
- *
- * This module is the SINGLE SOURCE OF TRUTH for the helper path. Other
- * modules in `src/lib/secrets/` must import `getKeychainHelperPath()` rather
- * than recomputing it.
- */
-import { fileURLToPath } from 'url';
-import { spawnSync } from 'child_process';
-import { createHash } from 'crypto';
-import * as fs from 'fs';
-import * as os from 'os';
-import * as path from 'path';
-import { copyAppBundle, withInstallLock } from '../app-bundle-install.js';
-import { downloadKeychainHelperApp } from './download-keychain.js';
-import { helperFloor } from '../helper-versions.js';
-const APP_BUNDLE_NAME = 'Agents CLI.app';
-const INSTALL_DIR_NAME = 'agents-cli';
-let installRootOverride = null;
-/** Redirect the install root (test only). Returns the previous override so callers can restore. */
-export function setInstallRootForTest(dir) {
-    const prev = installRootOverride;
-    installRootOverride = dir;
-    return prev;
-}
-/** Absolute path to the installed `.app` bundle directory (not the executable). */
-function installedAppPath() {
-    const root = installRootOverride ?? os.homedir();
-    return path.join(root, 'Library', 'Application Support', INSTALL_DIR_NAME, APP_BUNDLE_NAME);
-}
-/** Absolute path to the executable inside the installed `.app` bundle. */
-function installedExecutablePath() {
-    return path.join(installedAppPath(), 'Contents', 'MacOS', 'Agents CLI');
-}
-/**
- * Locate the source `.app` bundle shipped alongside the compiled JS.
- *
- * Resolution order:
- *   1. dist/lib/secrets/Agents CLI.app — sibling of this compiled file (npm install layout)
- *   2. <repo>/bin/Agents CLI.app       — raw working tree (`bun run dev`, tsx from src/)
- *
- * Throws if neither exists.
- */
-function sourceAppPath() {
-    const candidates = [];
-    try {
-        const here = path.dirname(fileURLToPath(import.meta.url));
-        candidates.push(path.join(here, APP_BUNDLE_NAME));
-        // tsx/src case: src/lib/secrets/install-helper.ts -> ../../../bin/Agents CLI.app
-        candidates.push(path.resolve(here, '..', '..', '..', 'bin', APP_BUNDLE_NAME));
-    }
-    catch { /* import.meta.url unavailable */ }
-    for (const c of candidates) {
-        if (fs.existsSync(c))
-            return c;
-    }
-    throw new Error(`Source ${APP_BUNDLE_NAME} not found. Looked in:\n  ${candidates.join('\n  ')}\n` +
-        'The npm package shipped without the bundled keychain helper. Run `agents setup secrets` to ' +
-        'download the signed helper for this version, or reinstall agents-cli.');
-}
-/** The bundled/local source `.app`, or null when absent (no throw) — the async
- *  download path resolves the missing bundle instead of failing. */
-function bundledSourceAppPathOrNull() {
-    try {
-        return sourceAppPath();
-    }
-    catch {
-        return null;
-    }
-}
-function assertDarwin() {
-    if (process.platform !== 'darwin') {
-        throw new Error('Keychain helper is macOS only.');
-    }
-}
-function sha256File(filePath) {
-    return createHash('sha256').update(fs.readFileSync(filePath)).digest('hex');
-}
-/**
- * True when the installed helper executable differs byte-for-byte from the
- * bundled source helper. A stale-but-validly-signed helper is exactly how the
- * broken 1.20.4 build (signed, but missing the keychain-access-groups
- * entitlement) survived upgrades: codesign --verify passes on it, so the
- * "exists and verifies" early-return kept it installed forever. Returns false
- * when there is no bundled source to compare against (dev installs) or no
- * installed copy yet — both cases are decided by the existence checks in the
- * callers, not by staleness.
- */
-function installedHelperIsStale() {
-    let srcApp;
-    try {
-        srcApp = sourceAppPath();
-    }
-    catch {
-        return false;
-    }
-    const srcExec = path.join(srcApp, 'Contents', 'MacOS', 'Agents CLI');
-    const destExec = installedExecutablePath();
-    if (!fs.existsSync(srcExec) || !fs.existsSync(destExec))
-        return false;
-    return sha256File(srcExec) !== sha256File(destExec);
-}
-function codesignVerify(appPath) {
-    const r = spawnSync('codesign', ['--verify', '--deep', '--strict', appPath], {
-        stdio: ['ignore', 'pipe', 'pipe'],
-        encoding: 'utf-8',
-    });
-    return { ok: r.status === 0, output: (r.stderr || r.stdout || '').toString().trim() };
-}
-function spctlAssess(appPath) {
-    const r = spawnSync('spctl', ['--assess', '--type', 'execute', '--verbose=2', appPath], {
-        stdio: ['ignore', 'pipe', 'pipe'],
-        encoding: 'utf-8',
-    });
-    return { ok: r.status === 0, output: (r.stderr || r.stdout || '').toString().trim() };
-}
-/**
- * Idempotent install. Copies the bundled `.app` to the stable user path. Skips
- * if the destination already exists, `codesign --verify` passes, AND the
- * installed executable matches the bundled one byte-for-byte — a valid
- * signature alone is not enough, because an outdated helper signs clean too.
- * `forceReinstall=true` skips all checks and always copies.
- *
- * Notarization is checked via `spctl --assess` after install — a failure is
- * logged as a warning but does NOT throw. Notarization checks require network
- * access (Gatekeeper ticket lookup) and are not load-bearing for the helper's
- * keychain ACL semantics.
- */
-export function ensureKeychainHelperInstalled(opts = {}) {
-    assertDarwin();
-    installKeychainHelperFromSource(sourceAppPath(), opts);
-}
-/**
- * ASYNC, download-capable install — the EXPLICIT onboarding/upgrade path
- * (`agents setup secrets`, the bootstrap upgrade self-heal). When a bundled or
- * locally-built `.app` ships (the common case, and always true this release
- * stage), it installs that copy with NO network. When the tarball lacks the
- * bundle (a fresh `npm i -g` whose tarball dropped it), it fetches the signed +
- * notarized release asset for the running CLI version — sha256 + codesign +
- * Team + notarization verified before install — and installs from the cached
- * copy. The sync `getKeychainHelperPath()` never routes here: it stays sync +
- * network-free and fails loud toward this command when no source exists.
- */
-export async function ensureKeychainHelperInstalledAsync(opts = {}) {
-    assertDarwin();
-    const bundled = bundledSourceAppPathOrNull();
-    const src = bundled ?? (await downloadKeychainHelperApp(helperFloor('keychain')));
-    installKeychainHelperFromSource(src, opts);
-}
-/**
- * Copy `src` (a verified `.app` bundle) to the stable user path, then verify.
- * Shared by the sync (bundled-source) and async (download-capable) installers.
- */
-function installKeychainHelperFromSource(src, opts = {}) {
-    const dest = installedAppPath();
-    const upToDate = () => fs.existsSync(dest) && codesignVerify(dest).ok && !installedHelperIsStale();
-    // Fast path: already installed, valid, and current — no lock, no copy.
-    if (!opts.forceReinstall && upToDate())
-        return;
-    // Serialize the install so concurrent `agents` invocations don't race the
-    // atomic swap (and don't each run a redundant `cp`). The re-check inside the
-    // lock means a burst of callers copies once, not N times — the stampede that
-    // transiently corrupted the bundle and tripped the "damaged" dialog.
-    withInstallLock(dest, (heartbeat) => {
-        if (!opts.forceReinstall && upToDate())
-            return;
-        copyAppBundle(src, dest);
-        heartbeat(); // cp -R done; keep the lock fresh across the codesign/spctl spawns
-        const verify = codesignVerify(dest);
-        if (!verify.ok) {
-            throw new Error(`Installed helper failed codesign verification at ${dest}.\n${verify.output}\n` +
-                'The bundle may be corrupted. Reinstall agents-cli to restore it; the helper reinstalls automatically on the next secrets use.');
-        }
-        heartbeat(); // codesign done; spctl does a network Gatekeeper lookup — refresh again
-        const assess = spctlAssess(dest);
-        if (!assess.ok) {
-            // Warn, do not fail. Gatekeeper ticket lookup needs network; offline
-            // installs and CI runners commonly fail this check. The ACL semantics
-            // we care about depend on codesign, not spctl.
-            process.stderr.write(`agents-cli: notarization check (spctl) did not pass for ${dest}: ${assess.output}\n`);
-        }
-    });
-}
-/**
- * Return the absolute path to the helper executable. If the installed bundle
- * is missing, or is stale relative to the bundled source helper, performs a
- * lazy (re)install first. The staleness check is what lets an upgraded CLI
- * replace a helper a previous version installed — the install never runs on
- * `npm i -g`, so this call site is the only one every machine is guaranteed to
- * pass through.
- *
- * SYNC and network-free by design: this is the secrets hot path, called by
- * every keychain op. It never downloads. When no bundled/local source exists
- * (a tarball that dropped the bundle), the reinstall's `sourceAppPath()` throws
- * loud, directing the user to `agents setup secrets` — the explicit, async,
- * download-capable path (`ensureKeychainHelperInstalledAsync`). Throws on
- * non-darwin.
- */
-export function getKeychainHelperPath() {
-    assertDarwin();
-    const exec = installedExecutablePath();
-    if (!fs.existsSync(exec) || installedHelperIsStale()) {
-        ensureKeychainHelperInstalled();
-    }
-    return exec;
-}
-export function getKeychainHelperStatus() {
-    assertDarwin();
-    const destApp = installedAppPath();
-    let src = null;
-    try {
-        src = sourceAppPath();
-    }
-    catch { /* missing source is reported as null */ }
-    const installed = fs.existsSync(destApp);
-    if (!installed) {
-        return {
-            source: src,
-            destination: destApp,
-            installed: false,
-            codesignOk: false,
-            codesignOutput: 'not installed',
-            spctlOk: false,
-            spctlOutput: 'not installed',
-        };
-    }
-    const cs = codesignVerify(destApp);
-    const sp = spctlAssess(destApp);
-    return {
-        source: src,
-        destination: destApp,
-        installed: true,
-        codesignOk: cs.ok,
-        codesignOutput: cs.output || 'ok',
-        spctlOk: sp.ok,
-        spctlOutput: sp.output || 'ok',
-    };
-}

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

@@ -1,25 +0,0 @@
-export declare const MIN_LEASE_MS: number;
-export declare const MAX_LEASE_MS: number;
-export interface SecretLease {
-    id: string;
-    bundle: string;
-    keys: string[];
-    createdAt: number;
-    expiresAt: number;
-    harness: string;
-    sleepPersist: boolean;
-}
-export declare function clampLeaseTtlMs(ttlMs: number): number;
-export declare function normalizeLeaseKeys(keys: readonly string[], availableKeys: readonly string[]): string[];
-export declare function createSecretLease(input: {
-    bundle: string;
-    keys: readonly string[];
-    availableKeys: readonly string[];
-    ttlMs: number;
-    now?: number;
-    id?: string;
-    harness?: string;
-    sleepPersist?: boolean;
-}): SecretLease;
-export declare function leaseIsActive(lease: SecretLease, now?: number): boolean;
-export declare function selectLeasedEnv(lease: SecretLease, env: Record<string, string>, now?: number): Record<string, string>;

package/dist/lib/secrets/lease.js

@@ -1,44 +0,0 @@
-import { randomBytes } from 'crypto';
-import { GLOBAL_HARNESS } from './scope.js';
-export const MIN_LEASE_MS = 60 * 1000;
-export const MAX_LEASE_MS = 30 * 24 * 60 * 60 * 1000;
-export function clampLeaseTtlMs(ttlMs) {
-    if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
-        throw new Error('Lease duration must be a positive finite number.');
-    }
-    return Math.min(Math.max(Math.floor(ttlMs), MIN_LEASE_MS), MAX_LEASE_MS);
-}
-export function normalizeLeaseKeys(keys, availableKeys) {
-    const requested = [...new Set(keys.map((key) => key.trim()).filter(Boolean))].sort();
-    if (requested.length === 0)
-        throw new Error('A secret lease requires at least one key.');
-    const available = new Set(availableKeys);
-    const missing = requested.filter((key) => !available.has(key));
-    if (missing.length > 0)
-        throw new Error(`Unknown secret lease key(s): ${missing.join(', ')}`);
-    return requested;
-}
-export function createSecretLease(input) {
-    const createdAt = input.now ?? Date.now();
-    const ttlMs = clampLeaseTtlMs(input.ttlMs);
-    return {
-        id: input.id ?? randomBytes(12).toString('hex'),
-        bundle: input.bundle,
-        keys: normalizeLeaseKeys(input.keys, input.availableKeys),
-        createdAt,
-        expiresAt: createdAt + ttlMs,
-        harness: input.harness ?? GLOBAL_HARNESS,
-        sleepPersist: input.sleepPersist ?? false,
-    };
-}
-export function leaseIsActive(lease, now = Date.now()) {
-    return now < lease.expiresAt;
-}
-export function selectLeasedEnv(lease, env, now = Date.now()) {
-    if (!leaseIsActive(lease, now))
-        throw new Error(`Secret lease '${lease.id}' has expired.`);
-    const missing = lease.keys.filter((key) => typeof env[key] !== 'string');
-    if (missing.length > 0)
-        throw new Error(`Secret lease '${lease.id}' is missing value(s): ${missing.join(', ')}`);
-    return Object.fromEntries(lease.keys.map((key) => [key, env[key]]));
-}

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

@@ -1,77 +0,0 @@
-/**
- * Linux secret storage via libsecret (GNOME Keyring / Secret Service API).
- *
- * Primary backend: `secret-tool` CLI (libsecret-tools package).
- *
- * Headless fallback: when the default Secret Service collection is locked
- * (common on server-class Linux — no graphical login means the keyring
- * passphrase never enters the daemon, so `secret-tool store` fails with
- * "Cannot create an item in a locked collection"), we transparently switch
- * to the AES-256-GCM encrypted-file store in ./filestore.ts. The decision is
- * cached per process; one stderr line is emitted the first time the fallback
- * activates.
- *
- * Secrets stored via secret-tool use:
- *   service = "agents-cli"
- *   account = username
- *   item    = the secret identifier
- */
-import type { KeychainBackend } from './index.js';
-import { type NativeImportReport } from './fallback.js';
-export { encryptForFallback, decryptForFallback, fileBackend, type EncFile, } from './filestore.js';
-/**
- * True when secret operations currently route to the encrypted-file store
- * instead of the Secret Service (the headless / locked-collection fallback).
- *
- * Runs the same `preflight()` decision every read and write uses, so it can't
- * drift from where bytes actually land. `preflight()` throws only in the
- * interactive / no-secret-tool / no-passphrase case — where nothing is stored
- * — so treat that as "not on the file path".
- *
- * `listBundles()` needs this: under the fallback the keychain enumeration
- * (`linuxBackend.list`) and the file enumeration read the SAME store, so
- * without this signal every file-backed bundle would be listed twice.
- */
-export declare function usesFileFallback(): boolean;
-/** secret-tool lookup attributes:
- *   service=agents-cli account=<user> item=<itemName> */
-export declare function hasSecretToolToken(item: string): boolean;
-export declare function getSecretToolToken(item: string): string;
-export declare function setSecretToolToken(item: string, value: string): void;
-export declare function deleteSecretToolToken(item: string): boolean;
-/**
- * Parse the item names out of `secret-tool search --all` output, keeping only
- * those starting with `prefix`. Exported for tests.
- *
- * `output` must be the combined stdout+stderr of the search: libsecret splits
- * the dump across both streams — the value/label/schema lines go to stdout
- * while the `attribute.*` lines (which carry `attribute.item`, the only place
- * the item name is reliably machine-readable) go to stderr (observed on
- * libsecret 0.21.4). Which stream each line lands on has varied across
- * libsecret versions, so callers concatenate both rather than bet on one.
- */
-export declare function parseSecretToolItems(output: string, prefix: string): string[];
-/**
- * List secrets by prefix. secret-tool doesn't have a list command,
- * so we use secret-tool search which outputs in a specific format.
- */
-export declare function listSecretToolItems(prefix: string): string[];
-/**
- * Copy agents-cli items from the keyring into the file store (the `import-keyring`
- * backend for Linux). Requires an unlocked keyring; items already in the file
- * store are left untouched. With `commit=false` it reports what it *would* do.
- */
-export declare function importNativeSecretToolItems(prefix: string, commit: boolean): NativeImportReport;
-/** KeychainBackend implementation for Linux. Routes through secret-tool
- *  with a transparent encrypted-file fallback when the default Secret
- *  Service collection is locked (or libsecret-tools is not installed but
- *  AGENTS_SECRETS_PASSPHRASE is set). */
-export declare const linuxBackend: KeychainBackend;
-/** Test-only: reset module state so independent test cases don't bleed
- *  passphrase / fallback decisions across each other. File-store state (file
- *  dir + cached passphrase) lives in ./filestore.ts and is reset there. */
-export declare function _resetForTest(opts?: {
-    fileDir?: string | null;
-    forceFileFallback?: boolean;
-    passphrase?: string | null;
-}): void;