@phnx-labs/agents-cli 1.22.83 → 1.22.85

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

@@ -0,0 +1,191 @@
+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. 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;