@phnx-labs/agents-cli 1.20.33 → 1.20.35

package/dist/lib/secrets/index.js

@@ -12,7 +12,10 @@
  * Linux: libsecret (GNOME Keyring) via the `secret-tool` CLI. No biometry —
  * items are unlocked when the keyring is open.
  *
- * Windows: not supported.
+ * Windows: Windows Credential Manager (CRED_TYPE_GENERIC,
+ * CRED_PERSIST_LOCAL_MACHINE) via a PowerShell P/Invoke shim, with the same
+ * AES-256-GCM encrypted-file fallback used on Linux when the credential store
+ * is unreachable (no logon session / no powershell.exe). No biometry.
  *
  * Items are device-local: the biometry access control requires the OS to
  * treat them as bound to this device, so cross-machine propagation goes
@@ -24,6 +27,7 @@ import * as fs from 'fs';
 import * as os from 'os';
 import * as path from 'path';
 import { linuxBackend, usesFileFallback as linuxUsesFileFallback } from './linux.js';
+import { windowsBackend, usesFileFallback as windowsUsesFileFallback } from './windows.js';
 import { getKeychainHelperPath } from './install-helper.js';
 const SERVICE_PREFIX = 'agents-cli';
 const SECRETS_ITEM_PREFIX = `${SERVICE_PREFIX}.secrets.`;
@@ -47,15 +51,36 @@ export function serializeRef(ref) {
     return `${ref.provider}:${ref.value}`;
 }
 function assertSupportedPlatform() {
-    if (process.platform !== 'darwin' && process.platform !== 'linux') {
-        throw new Error('agents secrets requires macOS Keychain or Linux libsecret.\n' +
-            'Windows is not supported — use environment variables or a .env file instead.\n' +
-            'WSL2 is supported (libsecret via gnome-keyring).');
+    if (process.platform !== 'darwin' && process.platform !== 'linux' && process.platform !== 'win32') {
+        throw new Error('agents secrets requires macOS Keychain, Linux libsecret, or Windows Credential Manager.\n' +
+            'Use environment variables or a .env file on unsupported platforms.');
     }
 }
 function isLinux() {
     return process.platform === 'linux';
 }
+function isWindows() {
+    return process.platform === 'win32';
+}
+/**
+ * Guard a secret value before it is written to the current platform's primary
+ * backend.
+ *
+ * A value is empty on every platform → always rejected. Embedded newlines are
+ * rejected ONLY on darwin: the macOS batch read path (`get-batch`, see
+ * getKeychainTokens) is newline-delimited, so a value with a newline would
+ * corrupt record framing on read. Linux (secret-tool), Windows (Credential
+ * Manager stores the raw UTF-8 blob and emits base64), and the encrypted-file
+ * fallback all store raw bytes and round-trip multiline values (PEM / SSH keys)
+ * faithfully, so they accept newlines. `platform` is injectable for tests.
+ */
+export function assertValueStorable(value, platform = process.platform) {
+    if (!value || !value.trim())
+        throw new Error('Secret value is empty.');
+    if (platform === 'darwin' && /[\r\n]/.test(value)) {
+        throw new Error('Secret value contains newlines, which are not supported.');
+    }
+}
 /** Build the keychain item name for a profile provider token. */
 export function profileKeychainItem(provider) {
     return `${SERVICE_PREFIX}.${provider}.token`;
@@ -74,6 +99,13 @@ export function setKeychainBackendForTest(b) {
     backend = b;
     return prev;
 }
+/** True when a test backend is installed (real keychain / biometry bypassed).
+ * Callers that gate on the live secrets-agent broker use this to stay hermetic —
+ * with an in-memory backend there is no real keychain to dedup, so the broker
+ * fast-path must not engage. Always false in production (`backend` is null). */
+export function isKeychainBackendOverridden() {
+    return backend !== null;
+}
 /**
  * Items whose name does NOT start with `agents-cli.` belong to another
  * application (e.g. Anthropic's `Claude Code-credentials-*`). Their ACL
@@ -93,6 +125,8 @@ export function hasKeychainToken(item) {
     assertSupportedPlatform();
     if (isLinux())
         return linuxBackend.has(item);
+    if (isWindows())
+        return windowsBackend.has(item);
     if (!isOurItem(item)) {
         return spawnSync('/usr/bin/security', ['find-generic-password', '-a', os.userInfo().username, '-s', item], {
             stdio: ['ignore', 'ignore', 'ignore'],
@@ -116,6 +150,8 @@ export function getKeychainToken(item) {
     assertSupportedPlatform();
     if (isLinux())
         return linuxBackend.get(item);
+    if (isWindows())
+        return windowsBackend.get(item);
     if (!isOurItem(item)) {
         const sec = spawnSync('/usr/bin/security', ['find-generic-password', '-a', os.userInfo().username, '-s', item, '-w'], {
             stdio: ['ignore', 'pipe', 'pipe'],
@@ -177,6 +213,15 @@ export function getKeychainTokens(items) {
         }
         return result;
     }
+    if (isWindows()) {
+        for (const item of items) {
+            try {
+                result.set(item, windowsBackend.get(item));
+            }
+            catch { /* missing — skip */ }
+        }
+        return result;
+    }
     const bin = getKeychainHelperPath();
     const child = spawnSync(bin, ['get-batch', os.userInfo().username, ...items], {
         stdio: ['ignore', 'pipe', 'pipe'],
@@ -226,16 +271,17 @@ export function setKeychainToken(item, value) {
         return;
     }
     assertSupportedPlatform();
-    if (!value || !value.trim())
-        throw new Error('Secret value is empty.');
-    if (/[\r\n]/.test(value))
-        throw new Error('Secret value contains newlines, which are not supported.');
+    assertValueStorable(value);
     if (/[\x00=\r\n]/.test(item))
         throw new Error('Secret item name contains invalid characters.');
     if (isLinux()) {
         linuxBackend.set(item, value);
         return;
     }
+    if (isWindows()) {
+        windowsBackend.set(item, value);
+        return;
+    }
     // Bare (non-`agents-cli.`) items are written WITHOUT the biometry ACL so
     // they round-trip with the no-prompt read path in getKeychainToken (which
     // also uses /usr/bin/security for non-our items). This is what lets a
@@ -273,6 +319,8 @@ export function deleteKeychainToken(item) {
     assertSupportedPlatform();
     if (isLinux())
         return linuxBackend.delete(item);
+    if (isWindows())
+        return windowsBackend.delete(item);
     const bin = getKeychainHelperPath();
     return spawnSync(bin, ['delete', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],
@@ -293,6 +341,8 @@ export function keychainUsesFileFallback() {
         return false;
     if (isLinux())
         return linuxUsesFileFallback();
+    if (isWindows())
+        return windowsUsesFileFallback();
     return false;
 }
 /** Enumerate keychain/keyring item names starting with the given prefix. */
@@ -302,6 +352,8 @@ export function listKeychainItems(prefix) {
     assertSupportedPlatform();
     if (isLinux())
         return linuxBackend.list(prefix);
+    if (isWindows())
+        return windowsBackend.list(prefix);
     const bin = getKeychainHelperPath();
     const result = spawnSync(bin, ['list', prefix], {
         stdio: ['ignore', 'pipe', 'pipe'],
@@ -313,6 +365,33 @@ export function listKeychainItems(prefix) {
     const out = result.stdout?.toString() || '';
     return out.split('\n').map((s) => s.trim()).filter(Boolean);
 }
+/**
+ * Enumerate ONLY legacy file-based-keychain item names with the given prefix —
+ * the items that still carry a pre-migration (trusted-app) ACL and pop a
+ * separate auth sheet on read. Items already in the data-protection keychain are
+ * excluded (they need no migration). Silent (attributes only, never decrypts).
+ *
+ * macOS only: on Linux / the test backend there is no separate legacy keychain,
+ * so this returns []. Used by `agents secrets migrate-acl` to rewrite only the
+ * stragglers instead of every item (which would be a Touch ID storm).
+ */
+export function listLegacyKeychainItems(prefix) {
+    if (backend)
+        return [];
+    assertSupportedPlatform();
+    if (isLinux())
+        return [];
+    const bin = getKeychainHelperPath();
+    const result = spawnSync(bin, ['list-legacy', prefix], {
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    if (result.status !== 0) {
+        const msg = result.stderr?.toString().trim();
+        throw new Error(msg || `Failed to enumerate legacy keychain items with prefix '${prefix}'.`);
+    }
+    const out = result.stdout?.toString() || '';
+    return out.split('\n').map((s) => s.trim()).filter(Boolean);
+}
 /**
  * One-time upgrade for a keychain item that was written by a previous helper
  * generation with a trusted-app ACL. The helper reads the legacy item
@@ -327,6 +406,8 @@ export function migrateKeychainItem(item) {
     assertSupportedPlatform();
     if (isLinux())
         return linuxBackend.has(item);
+    if (isWindows())
+        return windowsBackend.has(item);
     const bin = getKeychainHelperPath();
     const result = spawnSync(bin, ['migrate-acl', item, os.userInfo().username], {
         stdio: ['ignore', 'pipe', 'pipe'],

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

@@ -0,0 +1,74 @@
+/**
+ * Windows secret storage via Windows Credential Manager (wincred).
+ *
+ * Primary backend: the Credential Manager `advapi32` API (CredReadW /
+ * CredWriteW / CredDeleteW / CredEnumerateW), reached through a static
+ * PowerShell script that P/Invokes the C# shim below. PowerShell (Windows
+ * PowerShell 5.1) ships with every supported Windows, so there is no separate
+ * install step. Items are stored as CRED_TYPE_GENERIC with
+ * CRED_PERSIST_LOCAL_MACHINE — device-local, matching the biometry-bound model
+ * on macOS (src/lib/secrets/index.ts).
+ *
+ * Zero injection surface: the PS script is a single STATIC constant. All
+ * dynamic data rides in the child ENV (target name, list prefix) or STDIN (the
+ * secret value) — nothing is string-interpolated into the script. The child is
+ * spawned with a spawnSync ARGV ARRAY (`-EncodedCommand <base64>`), never a
+ * shell string.
+ *
+ * Headless fallback: when Credential Manager is unreachable (no logon session —
+ * ERROR_NO_SUCH_LOGON_SESSION 1312 — or powershell.exe missing from PATH), we
+ * transparently switch to the AES-256-GCM encrypted-file store in
+ * ./filestore.ts, exactly like the Linux locked-collection fallback. The
+ * decision is cached per process; one stderr line is emitted the first time.
+ *
+ * Item names are stored VERBATIM as the credential TargetName
+ * (`agents-cli.bundles.<name>` / `agents-cli.secrets.<bundle>.<key>` — the
+ * scheme shared with the file store, see ./filestore.ts) so `list` returns item
+ * names directly.
+ */
+import type { KeychainBackend } from './index.js';
+export { encryptForFallback, decryptForFallback, fileBackend, type EncFile, } from './filestore.js';
+/**
+ * CRED_MAX_CREDENTIAL_BLOB_SIZE — Credential Manager rejects a generic
+ * credential blob larger than 2560 bytes with an opaque CredWrite failure. We
+ * guard against it in `set` with a clear message. Only pathologically large
+ * bundle metadata could hit this; such an item should live in a file-backed
+ * bundle (AGENTS_SECRETS_PASSPHRASE) instead.
+ */
+export declare const CRED_MAX_CREDENTIAL_BLOB_SIZE = 2560;
+/**
+ * True when secret operations currently route to the encrypted-file store
+ * instead of Windows Credential Manager. Mirrors linux.ts:usesFileFallback so
+ * `listBundles()` doesn't double-count file-backed bundles under the fallback.
+ */
+export declare function usesFileFallback(): boolean;
+export declare function hasCredManToken(item: string): boolean;
+export declare function getCredManToken(item: string): string;
+export declare function setCredManToken(item: string, value: string): void;
+export declare function deleteCredManToken(item: string): boolean;
+export declare function listCredManItems(prefix: string): string[];
+/**
+ * Parse the target names printed by the `list` op (one per line), keeping only
+ * those starting with `prefix` and deduping. Same contract as
+ * parseSecretToolItems (linux.ts). Exported for tests.
+ */
+export declare function parseWindowsCredList(output: string, prefix: string): string[];
+/**
+ * KeychainBackend implementation for Windows. Routes through Windows Credential
+ * Manager (via PowerShell P/Invoke) with a transparent encrypted-file fallback
+ * when the credential store is unreachable.
+ */
+export declare const windowsBackend: KeychainBackend;
+/**
+ * Test-only: reset module state so independent test cases don't bleed
+ * availability / fallback decisions across each other. Pass `forceAvailable` to
+ * pin the powershell-availability probe (skips the real spawn); pass `fileDir`
+ * to redirect the encrypted-file store to a temp dir. File-store state lives in
+ * ./filestore.ts and is reset there.
+ */
+export declare function _resetForTest(opts?: {
+    fileDir?: string | null;
+    forceFileFallback?: boolean;
+    passphrase?: string | null;
+    forceAvailable?: boolean | null;
+}): void;