@phnx-labs/agents-cli 1.22.57 → 1.22.59

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

@@ -1,37 +1,14 @@
 /**
  * Remote secrets — read and use `agents secrets` bundles that live on another
- * host, over the same hardened SSH path that `agents secrets export --device`
- * (the write inverse) already uses.
+ * host over the same SSH path that `agents secrets export --device` uses.
  *
- * This is the READ / USE direction:
- *   - browse:  drive the remote `agents secrets list|view` and stream its
- *              stdout back verbatim (lossless, no parsing).
- *   - use:     resolve a remote bundle to an env map (JSON over ssh stdout) and
- *              inject it ephemerally — never written to this machine's keychain.
- *
- * Trust model: relies on the operator's existing SSH access to the host (same
- * boundary as `export --device` / `run --device`). Bundle names are shell-quoted
- * into the remote command; resolved VALUES return over ssh stdout. File-backend
- * import never forwards AGENTS_SECRETS_PASSPHRASE (PHNX-2371). Nothing is
- * persisted locally.
+ * Browse streams remote stdout verbatim; use resolves a bundle to an env map
+ * and injects it ephemerally without persisting it locally.
  */
 import { type SshExecResult } from '../ssh-exec.js';
 /**
- * SSH options for a SECRET-carrying transport (RUSH-2527). Every `agents secrets
- * --host` operation moves credential bytes — over ssh stdin (push) or ssh stdout
- * (resolve/read-back) — so it MUST NOT ride the shared `accept-new` baseline
- * against the user's own `~/.ssh/known_hosts` with a reusable control socket.
- * Two hardenings over that baseline, matching the posture the `--copy-creds`
- * dispatch already uses (`hosts/dispatch.ts` -> `hostKeyCheckingOpts`):
- *
- *   - **Managed pinned host keys.** Verify against the CLI-owned known_hosts
- *     store (`known-hosts.ts`), not `~/.ssh/known_hosts`. A CHANGED key on a
- *     known host is refused (`StrictHostKeyChecking` `yes` once pinned,
- *     `accept-new` before that). Callers that copy durable provider credentials
- *     must separately require an existing pin before invoking this transport.
- *   - **No multiplex reuse.** `multiplex: false` — a credential channel never
- *     leaves a persistent `ControlMaster` socket lingering (60s `ControlPersist`)
- *     that any other `agents` invocation to that host would silently reuse.
+ * SSH options for secret-carrying transport. Pins the managed host key and
+ * disables multiplex so no reusable control socket lingers for other invocations.
  */
 export declare function credentialTransportSshOpts(target: string): {
     hostKeyOpts: string[];
@@ -40,37 +17,21 @@ export declare function credentialTransportSshOpts(target: string): {
 /** Refuse durable credential transfer until the destination SSH key is pinned. */
 export declare function assertCredentialTransportHostPinned(target: string, pinned?: boolean): void;
 /**
- * Trust boundary for a remote-resolved env map. A peer's `secrets export` output
- * is untrusted input: a compromised or misconfigured host could return keys that
- * silently reshape THIS process's behavior once merged into the agent env
- * (bundles.ts:251 `sanitizeProcessEnv` only strips loader vars from process.env,
- * never the remote bundle). Block the dangerous-override classes here — at the
- * source — so every consumer (`run --secrets b@host`, `secrets exec --host`) is
- * protected, not just one call site:
- *   - LD_* / DYLD_* / NODE_OPTIONS and the other loader/interpreter injections
- *     (reuses the canonical bundles.ts predicate);
- *   - GIT_*        — GIT_SSH_COMMAND et al. hijack every git subprocess;
- *   - *_PROXY      — HTTP(S)_PROXY / ALL_PROXY reroute outbound traffic (MITM);
- *   - *_BASE_URL   — ANTHROPIC_BASE_URL / OPENAI_BASE_URL redirect the model API.
- * These keys are already rejected on the ADD side (validateEnvKey for loaders),
- * so a legitimate bundle never carries them — only a hostile peer would.
+ * Trust boundary for a remote-resolved env map. A peer's export output is
+ * untrusted input that could reshape this process once merged into the env, so
+ * block dangerous override classes here for every consumer:
+ * loader/interpreter vars, GIT_*, *_PROXY, and *_BASE_URL.
  */
 export declare function isDangerousRemoteEnvKey(name: string): boolean;
 /**
- * Resolve a `--device` value to an ssh target STRING for the remote-secrets path.
- * Delegates to the single host/device resolver (`resolveHost`, RUSH-1967) so a
- * name here dials the exact same box `run --device` does; on a miss, treats the
- * value as a raw ssh target and validates it against injection. Named distinctly
- * from `../devices/resolve-target.ts` (which returns richer shapes) so importing
- * the wrong one can't silently change which machine you dial.
+ * Resolve a `--device` value to an ssh target string for the remote-secrets
+ * path. Delegates to the same resolver `run --device` uses; on a miss, treats
+ * the value as a raw ssh target and validates it.
  */
 export declare function resolveHostSshTarget(nameOrAlias: string): Promise<string>;
 /**
- * Merge `--host <single>` / `--hosts <a,b,c>` (and their `--device` / `--devices`
- * aliases) into an ordered, de-duplicated list. All four flags compose; any alone
- * works. `--device`/`--devices` resolve identically to `--device`/`--hosts` so the
- * fleet-wide `--device` vocabulary (see `agents run --device`, `agents feed --host`)
- * works on the secrets remote commands too. Empty when none is set.
+ * Merge `--host` / `--hosts` (and their `--device` / `--devices` aliases) into
+ * an ordered, de-duplicated list. Empty when none is set.
  */
 export declare function parseHostsOption(opts: {
     host?: string;
@@ -79,11 +40,9 @@ export declare function parseHostsOption(opts: {
     devices?: string;
 }): string[];
 /**
- * Split a `bundle@host` reference. No `@` → a local bundle (host undefined).
- * Bundle names can't contain `@` (BUNDLE_NAME_PATTERN), so the FIRST `@`
- * separates the bundle from the ssh target — and the target itself may be a
- * `user@host` (e.g. `r2.backups@muqsit@box` → bundle `r2.backups`, host
- * `muqsit@box`).
+ * Split a `bundle@host` reference. No `@` → a local bundle. Bundle names can't
+ * contain `@`, so the FIRST `@` separates bundle from ssh target; the target
+ * itself may be `user@host` (e.g. `r2.backups@muqsit@box`).
  */
 export declare function splitBundleRef(ref: string): {
     bundle: string;
@@ -91,9 +50,8 @@ export declare function splitBundleRef(ref: string): {
 };
 /**
  * Run `agents secrets <args>` on a remote host over ssh and return the raw
- * result. Used by the browse commands — the remote's human-readable stdout is
- * streamed back unchanged. `tty` forces an interactive ssh session (`-tt`) so a
- * remote Touch-ID / passphrase prompt can surface (e.g. `view --reveal`).
+ * result. Used by browse commands; `tty` forces `-tt` so remote passphrase
+ * prompts can surface.
  */
 export declare function remoteSecretsRaw(target: string, args: string[], opts?: {
     tty?: boolean;
@@ -102,17 +60,9 @@ export declare function remoteSecretsRaw(target: string, args: string[], opts?:
     secret?: boolean;
 }): SshExecResult;
 /**
- * Run a remote `agents secrets <args>` FOREGROUND, with the local stdio wired
- * straight through (`stdio: 'inherit'` + `-tt`), and return its exit code.
- *
- * Unlike `remoteSecretsRaw` — which pipes stdin, so even with `-tt` the remote
- * process's `process.stdin.isTTY` is false and a passphrase prompt refuses to
- * appear (the macOS file-store guard then hard-errors "needs
- * AGENTS_SECRETS_PASSPHRASE") — this inherits the caller's real terminal, so the
- * remote sees a genuine TTY and its hidden passphrase prompt surfaces and reads
- * the keystrokes. This is the transport for `unlock --device`: you type the remote
- * bundle's passphrase at your own terminal. Output is NOT captured (it streams
- * to the terminal); only the exit code is returned.
+ * Run a remote `agents secrets <args>` foreground with local stdio inherited,
+ * so the remote sees a real TTY and its passphrase prompt surfaces and reads
+ * keystrokes. Output streams to the terminal; only the exit code is returned.
  */
 export declare function remoteSecretsStream(target: string, args: string[], opts?: {
     osLookupName?: string;
@@ -120,31 +70,20 @@ export declare function remoteSecretsStream(target: string, args: string[], opts
 /**
  * Resolve a remote bundle to a plaintext env map by driving the remote's
  * `agents secrets export <bundle> --plaintext --format json`. Values cross over
- * ssh stdout (encrypted in transit), parsed in memory, never persisted.
+ * ssh stdout, parsed in memory, never persisted.
  *
- * The remote unlocks the bundle with ITS OWN credentials — the owner host's
- * keychain/secrets-agent, or its own `AGENTS_SECRETS_PASSPHRASE` (in the login
- * env) for a file-backed bundle. We deliberately do NOT forward this machine's
- * passphrase: the remote bundle is encrypted with the remote's passphrase, so
- * overriding it would break the read. (A macOS remote under non-interactive
- * SSH will block on Touch-ID — use `view`/`exec` with a remote `file` bundle,
- * an already-unlocked remote secrets-agent, or an interactive `-tt` session.)
+ * The remote unlocks the bundle with its own credentials; this machine does NOT
+ * forward its passphrase because the remote bundle is encrypted with the
+ * remote's passphrase.
  */
 export declare function remoteResolveEnv(target: string, bundle: string, opts?: {
     osLookupName?: string;
 }): Promise<Record<string, string>>;
 /**
- * Outcome of a post-push read-back verification (see verifyRemoteKeychainPush).
- *   - `ok`               — the pushed keys materialized readably on the remote.
- *   - `locked-keychain`  — the read-back gave the SPECIFIC signal of a keychain
- *                          that didn't persist (the remote's headless "not unlocked
- *                          in the secrets agent" guard, or a "stored item … not
- *                          found" on read-back, or pushed keys simply absent). Only
- *                          this verdict earns the locked-login-keychain diagnosis +
- *                          `--remote-backend file` steer.
- *   - `error`            — a DIFFERENT failure (flaky SSH, timeout, unparseable
- *                          payload). The raw error is re-surfaced verbatim, never
- *                          mislabeled as a locked keychain.
+ * Outcome of a post-push read-back verification.
+ *   - `ok`              — the pushed keys materialized readably.
+ *   - `locked-keychain` — read-back gave the specific locked-keychain signal.
+ *   - `error`           — a different failure (SSH, timeout, etc.).
  */
 export type RemoteKeychainWriteVerification = {
     ok: true;
@@ -158,24 +97,10 @@ export type RemoteKeychainWriteVerification = {
     reason: string;
 };
 /**
- * Decide whether a keychain-backed push to a remote actually PERSISTED its secret
- * value items, given the read-back of that bundle from the remote's own store.
- *
- * The silent-failure this guards: pushing `--remote-backend keychain` (default) to
- * a macOS host over headless SSH lands the bundle METADATA but not readable value
- * items — the remote login keychain is locked in the non-interactive SSH context,
- * so Security accepts the item WRITE at the DB level but the biometry-ACL'd item is
- * unreadable, and the remote `import` still reports success (values written first,
- * metadata `noAcl` last — bundles.ts writeBundleWithItems). The metadata-only bundle
- * then fails every later read with the confusing `Bundle '<b>' key '<k>': stored
- * item '<item>' not found` (bundles.ts resolveBundleEnv). We catch it by reading
- * the bundle back the same way a later `secrets exec`/resolve will (the marker-gated
- * json transport, driven headlessly on the remote so its `agentOnly` guard FAILS FAST
- * before any keychain read — no Touch ID prompt) and confirming every pushed key
- * returned.
- *
- * Pure so both branches are unit-testable without a real locked keychain: inject the
- * "read-back failed / key absent" condition through `readBack`.
+ * Decide whether a keychain-backed push to a remote actually persisted its
+ * secret value items by reading the bundle back the same way a later resolve
+ * will. Catches the silent failure where headless SSH writes metadata but not
+ * readable value items to a locked macOS login keychain.
  */
 export declare function evaluateKeychainWriteVerification(pushedKeys: string[], readBack: {
     ok: true;
@@ -185,38 +110,26 @@ export declare function evaluateKeychainWriteVerification(pushedKeys: string[],
     stderr: string;
 }): RemoteKeychainWriteVerification;
 /**
- * The actionable error message for a failed keychain-over-SSH push verification.
- * Names the cause (locked remote login keychain) and steers to the two real fixes:
- * re-run with the headless-readable file backend, or unlock the remote keychain.
- * Pure + exported so the exact guidance is asserted in tests.
+ * Actionable error message for a failed keychain-over-SSH push. Names the cause
+ * (locked remote login keychain) and steers to the two real fixes.
  */
 export declare function keychainWriteFailureMessage(host: string, bundle: string, reason: string): string;
 /**
- * Read a bundle back from a remote over SSH (headlessly, so it fails fast rather
- * than prompting Touch ID) and confirm the pushed keys materialized. Drives the
- * remote's marker-gated json transport (`secrets export <bundle> --plaintext
- * --format json` under AGENTS_SECRETS_REMOTE_TRANSPORT) but keeps only the KEY
- * NAMES; the plaintext values are dropped immediately and never retained or
- * logged. Returns a verification verdict; the caller renders
- * `keychainWriteFailureMessage` on failure.
+ * Read a bundle back from a remote over SSH and confirm the pushed keys
+ * materialized. Drives the marker-gated json transport but keeps only KEY NAMES;
+ * plaintext values are discarded immediately. Returns a verification verdict.
  */
 export declare function verifyRemoteKeychainPush(target: string, bundle: string, pushedKeys: string[], opts?: {
     osLookupName?: string;
     secret?: boolean;
 }): RemoteKeychainWriteVerification;
 /**
- * The `bash -lc` command + stdin payload that drives a **file-backed** remote
- * import for `secrets export --device … --remote-backend file`.
+ * `bash -lc` command + stdin payload for a file-backed remote import.
  *
- * The file store is passphrase-free: the remote `agents secrets import --backend
- * file` auto-provisions the remote's own machine-local key (0600 under
- * `~/.agents/.secrets-key/`), so its reads are HEADLESS — no passphrase, no
- * Touch ID. AGENTS_SECRETS_PASSPHRASE is a deprecated override and MUST NOT be
+ * The file store is passphrase-free: the remote auto-provisions its own machine-
+ * local key, so reads are headless. AGENTS_SECRETS_PASSPHRASE must NOT be
  * forwarded (PHNX-2371): a remote keyed to a secret its daemon does not hold
  * reports "Imported N key(s)" then fails every later decrypt.
- *
- * Pure — no I/O — so the exact command string and stdin ordering are unit-testable
- * against the SSH boundary the same way `remoteSecretsRaw` is.
  */
 export declare function buildRemoteFileImportCommand(bundle: string, dotenv: string, opts?: {
     force?: boolean;