@phnx-labs/agents-cli 1.22.84 → 1.22.86

package/dist/lib/reserved-stores.js

@@ -0,0 +1,120 @@
+/**
+ * Reserved per-harness credential stores (PHNX-3940 / PHNX-3989).
+ *
+ * One store name per `ALL_AGENT_IDS` entry: `__<harness>__`. A user-created
+ * bundle can never collide (the standalone rejects `__`-prefixed names unless
+ * explicitly allowed). The legacy `auth` bundle remains a readable alias for
+ * `__claude__` — this module does not migrate data.
+ *
+ * Deliberately a LEAF module (no import of `claude-account-token.ts` or
+ * `secrets-policy.ts`): both of those need these constants, and
+ * `claude-account-token.ts` is itself a dependency of `secrets-policy.ts`'s
+ * fleet-sync helpers — importing this module's exports from `secrets-policy.js`
+ * instead would form a real circular import that throws
+ * `ReferenceError: Cannot access '...' before initialization` under real ESM
+ * evaluation order (reproduced running this suite outside vitest's
+ * mock-tolerant transform). Keep it a leaf; `secrets-policy.ts` re-exports it
+ * for the existing public surface.
+ */
+import { bundleExistsSync, bundleBackendSync, isSecretsClientError } from './secrets-client.js';
+import { AGENT_IDS } from './types.js';
+/** Legacy readable alias for `__claude__`. Not migrated in this track. */
+export const AUTH_STORE_ALIAS = 'auth';
+/** The one reserved bundle name most callers actually need. */
+export const AUTH_BUNDLE_NAME = AUTH_STORE_ALIAS;
+/**
+ * The reserved `auth` bundle holds per-account Claude setup-tokens for
+ * unattended usage/probe and MUST be file-backed (headless, fleet-shareable —
+ * credential-management.md invariant 7). The standalone enforces the same
+ * rule on its write path (`WRONG_BACKEND`); agents-cli asserts it on every
+ * read so a keychain/vault-backed `auth` left over from an older layout fails
+ * loud instead of silently being ignored by usage/probe (SEC-GAP-3).
+ */
+export const AUTH_BUNDLE_BACKEND = 'file';
+export const RESERVED_BUNDLE_NAMES = new Set([AUTH_BUNDLE_NAME]);
+export function isReservedBundleName(name) {
+    return RESERVED_BUNDLE_NAMES.has(name.trim().toLowerCase());
+}
+/** Thrown when the reserved `auth` bundle is found on the wrong backend. */
+export class ReservedBundleWrongBackendError extends Error {
+    bundle;
+    backend;
+    constructor(bundle, backend) {
+        super(`Bundle '${bundle}' is reserved for file-backed setup-tokens (headless, fleet-shareable). ` +
+            `A ${backend}-backed '${bundle}' bundle is ignored by usage/probe instead of authenticating. ` +
+            `Recreate it as file-backed: agents secrets delete ${bundle} --yes && agents secrets create ${bundle} --backend file`);
+        this.name = 'ReservedBundleWrongBackendError';
+        this.bundle = bundle;
+        this.backend = backend;
+    }
+}
+/** Fail loud when the reserved `auth` bundle is on any backend but `file`. */
+export function assertReservedAuthBackend(backend) {
+    if (backend !== AUTH_BUNDLE_BACKEND)
+        throw new ReservedBundleWrongBackendError(AUTH_STORE_ALIAS, backend);
+}
+/**
+ * True for the wrong-backend refusal in either shape: raised here from a
+ * read-side check, or returned by the standalone (`WRONG_BACKEND`) when its
+ * own write/resolve guard fired.
+ */
+export function isReservedBundleBackendError(error) {
+    return error instanceof ReservedBundleWrongBackendError || isSecretsClientError(error, 'WRONG_BACKEND');
+}
+export const RESERVED_STORES = Object.fromEntries(AGENT_IDS.map((id) => [id, `__${id}__`]));
+export function reservedStoreName(harness) {
+    const name = RESERVED_STORES[harness];
+    if (!name)
+        throw new Error(`No reserved store for '${harness}'.`);
+    return name;
+}
+export function isReservedStoreName(name) {
+    const n = name.trim().toLowerCase();
+    if (n === AUTH_STORE_ALIAS)
+        return true;
+    return AGENT_IDS.some((id) => RESERVED_STORES[id].toLowerCase() === n);
+}
+/**
+ * Fail loud at the write boundary: only a setup-token or an API key may enter
+ * a reserved store. Rotating OAuth/session credentials stay in their slot on
+ * the device that minted them.
+ */
+export function assertStorableCredentialKind(kind, harness) {
+    if (kind === 'setup-token' || kind === 'api-key')
+        return;
+    throw new Error(storableCredentialRefusal(kind, harness));
+}
+function storableCredentialRefusal(kind, harness) {
+    if (harness === 'codex')
+        return 'codex: auth.json is a rotating session; add an API key instead';
+    if (harness === 'droid')
+        return 'droid: refresh tokens are single-use and collapse the fleet when copied; add a FACTORY_API_KEY instead';
+    if (harness === 'claude')
+        return 'claude: native OAuth (.credentials.json) is a rotating session; mint a setup-token instead';
+    if (harness === 'grok')
+        return 'grok: auth.json is a rotating session; add an XAI_API_KEY instead';
+    if (harness === 'kimi' || harness === 'antigravity')
+        return `${harness}: no portable worker credential; log in per device`;
+    const who = harness ?? 'this harness';
+    return `${who}: reserved stores accept only a setup-token or an API key, not '${kind}'`;
+}
+/**
+ * Whether the local reserved `auth` bundle exists and is on the expected
+ * (file) backend. `ok: true` on a missing bundle — nothing to be wrong about.
+ * Read-only status probe (`agents doctor`, `agents fleet apply`); an
+ * unreachable standalone is treated the same as "bundle absent" so a
+ * diagnostic never crashes over one optional finding.
+ */
+export function inspectReservedAuthBundle() {
+    let exists;
+    try {
+        exists = bundleExistsSync(AUTH_BUNDLE_NAME);
+    }
+    catch {
+        return { exists: false, backend: null, ok: true };
+    }
+    if (!exists)
+        return { exists: false, backend: null, ok: true };
+    const backend = bundleBackendSync(AUTH_BUNDLE_NAME);
+    return { exists: true, backend, ok: backend === AUTH_BUNDLE_BACKEND };
+}

package/dist/lib/secrets-client.d.ts

@@ -0,0 +1,199 @@
+import type { SecretsBundle, SecretsBackend, ResolveBundleOptions, WriteBundleOptions, BundleEntryInfo, RenameOptions, RotateOptions, BundleValue, KeychainReadContext, SecretRef, AgentStatusEntry, PushBundleOptions, PushBundleResult, RemoteBundleSummary, PullOptions, RcSecretFinding } from './secrets-types.js';
+/**
+ * Wire contract, mirrored from `secrets-cli/src/protocol.ts`. Both sides MUST
+ * agree byte-for-byte; this is the shared schema of the seam, the one thing an
+ * independent client legitimately re-declares rather than imports.
+ */
+export declare const PROTOCOL_VERSION = 1;
+export interface SecretsContext {
+    /** Bundle allowlist; absent ⇒ full trust (the local agents client today). */
+    allowedBundles?: string[];
+    /** Opaque scope the standalone folds into resolution — the harness name. */
+    scope?: string;
+}
+/** Serialize `Map`s the way the server's `decodeWire` expects to receive them. */
+export declare function encodeWire(value: unknown): unknown;
+/** Reconstruct `Map`s from the server's `encodeWire`'d reply. */
+export declare function decodeWire(value: unknown): unknown;
+/** Carries the server's `{code, message}`, or a client-side transport code. */
+export declare class SecretsClientError extends Error {
+    readonly code: string;
+    constructor(code: string, message: string);
+    /**
+     * Serialize to a plain `{code, message}`. A consumer that folds a failure into
+     * a structure it later `JSON.stringify`s (a teammate's meta.json, a failure
+     * record, a spawn env) must never make the serializer chase this Error's
+     * internal references and throw `Converting circular structure to JSON`
+     * mid-launch — the value here is the two fields a caller actually needs.
+     */
+    toJSON(): {
+        code: string;
+        message: string;
+    };
+}
+/** True when `error` is a {@link SecretsClientError}, optionally with the given code. */
+export declare function isSecretsClientError(error: unknown, code?: string): error is SecretsClientError;
+/** True when `error` is a {@link SecretsClientError} from the transport itself (the
+ * standalone was unreachable/unusable), not a data error it answered with. */
+export declare function isSecretsTransportError(error: unknown): error is SecretsClientError;
+export declare const SECRETS_ITEM_PREFIX = "agents-cli.secrets.";
+/** The raw item holding one bundle key's value. */
+export declare function secretsKeychainItem(bundle: string, key: string): string;
+/** The raw item holding a profile provider's token (`agents-cli.<provider>.token`). */
+export declare function profileKeychainItem(provider: string): string;
+/** The bundle-var form that points a key at its own raw item. */
+export declare function keychainRef(key: string): string;
+export type { BundleValue, SecretRef };
+/**
+ * Parse a bundle value into either a literal string or a typed secret ref. A
+ * `{ value }` object is an escaped literal (a URL that happens to start with a
+ * ref prefix is never misread as a reference).
+ */
+export declare function parseBundleValue(raw: BundleValue): {
+    literal: string;
+} | {
+    ref: SecretRef;
+};
+/**
+ * Resolve the standalone `secrets` executable: `$SECRETS_BIN` if set, else the
+ * `secrets` command on PATH — resolved with `findInPath`, which skips agents-cli's
+ * own shims dir. That skip is load-bearing, not tidiness: before PHNX-3989 the
+ * shims dir carried a `secrets` command shim that `exec`s `agents secrets`, it
+ * sits FIRST on PATH, and it survives an in-place upgrade (its baked entrypoint
+ * still exists). A plain `which secrets` returned that shim, so `agents secrets`
+ * → shim → `agents secrets` → … spawned an unbounded process chain on every box
+ * upgraded from 1.22.84 (the whole fleet, via R5 auto-update). A `secrets` inside
+ * our shims dir can never be the standalone, so it is not a candidate at all.
+ * Cached for the process. A miss throws with install guidance — there is NO
+ * fallback to the embedded engine (DIST-1).
+ */
+export declare function resolveSecretsBin(): string;
+/**
+ * How to invoke the resolved binary. A `.js`/`.mjs`/`.cjs` entrypoint (a dev
+ * build, or `$SECRETS_BIN` pointing at `dist/index.js`) is run through this
+ * process's Node so it works without an executable bit and on Windows; an
+ * installed `secrets` shim/binary is spawned directly. Exported so a caller
+ * that needs to run an interactive standalone verb directly (e.g. `secrets
+ * migrate`, which isn't in this client's op table) can build the same argv.
+ */
+export declare function invocation(bin: string): {
+    command: string;
+    prefix: string[];
+};
+/**
+ * Spawn env for the child, applied to a base env (defaults to `process.env`):
+ *
+ *  - `SECRETS_HOME` defaults to the user agents dir so the standalone adopts the
+ *    existing stores in place (MIG-1); an explicit value in the base env wins.
+ *  - The standalone renamed every `AGENTS_SECRETS_*` knob to `SECRETS_*`, so a
+ *    caller env still carrying the old `AGENTS_SECRETS_PASSPHRASE` (the name
+ *    agents-cli's own engine reads — filestore/linux/windows) would be invisible
+ *    to `secrets`, which reads only `SECRETS_PASSPHRASE`. Forward it so the child
+ *    can decrypt the very file store agents-cli wrote, rather than silently
+ *    provisioning a fresh machine-local key. An explicit `SECRETS_PASSPHRASE`
+ *    wins — this only bridges the rename, it never overrides.
+ *
+ * Exported for the seam test (a pure env mapping, no spawn).
+ */
+export declare function buildServeEnv(base?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;
+/**
+ * Send one operation to the standalone secrets CLI and await its typed result.
+ * Verifies the executable speaks protocol v1 once per process (cached), then
+ * spawns `secrets __serve` for the operation. Throws a {@link SecretsClientError}
+ * carrying the server's `{code, message}` on failure.
+ */
+export declare function secretsRequest<T = unknown>(op: string, args?: unknown[], context?: SecretsContext): Promise<T>;
+/**
+ * Synchronous sibling of {@link secretsRequest} for the consumers that resolve
+ * secrets on a synchronous path (e.g. building a child env before spawn).
+ * Bounded by a spawn timeout. POSIX only.
+ */
+export declare function secretsRequestSync<T = unknown>(op: string, args?: unknown[], context?: SecretsContext): T;
+/** Test hook: forget the cached binary + handshake so a new env is re-resolved. */
+export declare function _resetSecretsClientForTest(): void;
+export declare function readAndResolveBundleEnv(name: string, opts?: ResolveBundleOptions, context?: SecretsContext): Promise<{
+    bundle: SecretsBundle;
+    env: Record<string, string>;
+}>;
+export declare function readAndResolveBundleEnvSync(name: string, opts?: ResolveBundleOptions, context?: SecretsContext): {
+    bundle: SecretsBundle;
+    env: Record<string, string>;
+};
+export declare function listBundles(context?: SecretsContext): Promise<SecretsBundle[]>;
+export declare function listBundlesSync(context?: SecretsContext): SecretsBundle[];
+/**
+ * Per-key kind breakdown (`literal`/`file`/`onepassword`/…) of an already-resolved
+ * bundle — the cosmetic `[secrets] Resolved <name>: N keys (…)` summary line. Pure
+ * over the bundle document server-side; the wrapper forwards the object the caller
+ * already holds from {@link readAndResolveBundleEnv} so the same shape is described.
+ */
+export declare function describeBundle(bundle: SecretsBundle, context?: SecretsContext): Promise<BundleEntryInfo[]>;
+export declare function readBundle(name: string, context?: SecretsContext): Promise<SecretsBundle>;
+export declare function readBundleSync(name: string, context?: SecretsContext): SecretsBundle;
+export declare function bundleExists(name: string, context?: SecretsContext): Promise<boolean>;
+export declare function bundleExistsSync(name: string, context?: SecretsContext): boolean;
+export declare function bundleBackend(name: string, context?: SecretsContext): Promise<SecretsBackend>;
+export declare function bundleBackendSync(name: string, context?: SecretsContext): SecretsBackend;
+export declare function writeBundle(bundle: SecretsBundle, opts?: WriteBundleOptions, context?: SecretsContext): Promise<void>;
+export declare function writeBundleWithItems(bundle: SecretsBundle, items: Map<string, string>, opts?: WriteBundleOptions, context?: SecretsContext): Promise<void>;
+export declare function writeBundleWithItemsSync(bundle: SecretsBundle, items: Map<string, string>, opts?: WriteBundleOptions, context?: SecretsContext): void;
+export declare function deleteBundle(name: string, context?: SecretsContext): Promise<boolean>;
+export declare function deleteBundleSync(name: string, context?: SecretsContext): boolean;
+/** Rename a bundle: metadata and raw items move together; the source is deleted last. */
+export declare function renameBundle(oldName: string, newName: string, opts?: RenameOptions, context?: SecretsContext): Promise<void>;
+export declare function renameBundleSync(oldName: string, newName: string, opts?: RenameOptions, context?: SecretsContext): void;
+/** Rotate one keychain-backed key's value in place, preserving or patching its meta. */
+export declare function rotateBundleSecret(bundle: SecretsBundle, key: string, opts: RotateOptions, context?: SecretsContext): Promise<void>;
+export declare function rotateBundleSecretSync(bundle: SecretsBundle, key: string, opts: RotateOptions, context?: SecretsContext): void;
+export declare function agentPing(): Promise<{
+    reachable: boolean;
+    cliVersion?: string;
+}>;
+export declare function agentPingSync(): {
+    reachable: boolean;
+    cliVersion?: string;
+};
+export declare function agentStatus(): Promise<AgentStatusEntry[]>;
+export declare function agentLock(name?: string): Promise<number>;
+export declare function ensureAgentRunning(timeoutMs?: number): Promise<boolean>;
+export declare function getKeychainToken(item: string, context?: KeychainReadContext): Promise<string>;
+export declare function getKeychainTokenSync(item: string, context?: KeychainReadContext): string;
+export declare function setKeychainToken(item: string, value: string, opts?: {
+    noAcl?: boolean;
+}): Promise<void>;
+export declare function setKeychainTokenSync(item: string, value: string, opts?: {
+    noAcl?: boolean;
+}): void;
+export declare function hasKeychainToken(item: string): Promise<boolean>;
+export declare function hasKeychainTokenSync(item: string): boolean;
+export declare function deleteKeychainToken(item: string): Promise<boolean>;
+export declare function deleteKeychainTokenSync(item: string): boolean;
+export declare function listKeychainItems(prefix: string): Promise<string[]>;
+/**
+ * True when `keychain`-backend items are being routed to the standalone's
+ * encrypted file store (headless Linux/Windows with no reachable keyring):
+ * on such a host no test or probe can reach a real OS keychain.
+ */
+export declare function keychainUsesFileFallback(): Promise<boolean>;
+export declare function storeGet(backend: SecretsBackend, item: string): Promise<string>;
+export declare function storeGetSync(backend: SecretsBackend, item: string): string;
+export declare function storeHas(backend: SecretsBackend, item: string): Promise<boolean>;
+export declare function storeHasSync(backend: SecretsBackend, item: string): boolean;
+export declare function storeSet(backend: SecretsBackend, item: string, value: string): Promise<void>;
+export declare function storeSetSync(backend: SecretsBackend, item: string, value: string): void;
+export declare function storeDelete(backend: SecretsBackend, item: string): Promise<boolean>;
+export declare function remoteResolveEnv(target: string, bundle: string, opts?: {
+    osLookupName?: string;
+}): Promise<Record<string, string>>;
+export declare function pushBundleToHost(bundle: string, host: string, opts: PushBundleOptions): Promise<PushBundleResult>;
+export declare function pushBundleToHostAsync(bundle: string, host: string, opts: PushBundleOptions): Promise<PushBundleResult>;
+export declare function listRemoteBundles(context?: SecretsContext): Promise<RemoteBundleSummary[]>;
+export declare function pullBundle(name: string, opts: PullOptions, context?: SecretsContext): Promise<SecretsBundle>;
+export declare function scanUserRcFiles(homeDir?: string, context?: SecretsContext): Promise<RcSecretFinding[]>;
+export declare function scanUserRcFilesSync(homeDir?: string, context?: SecretsContext): RcSecretFinding[];
+export declare function masterPassphraseInEnv(context?: SecretsContext): Promise<boolean>;
+export declare function masterPassphraseInEnvSync(context?: SecretsContext): boolean;
+/** True for a dynamic-loader or language-interpreter override env var. */
+export declare function isLoaderOrInterpreterEnv(name: string): boolean;
+/** Strip loader/interpreter overrides from an env before it reaches a spawned child. */
+export declare function sanitizeProcessEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;