@phnx-labs/agents-cli 1.20.51 → 1.20.53

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

@@ -24,6 +24,7 @@
  */
 import type { NativeImportReport } from './fallback.js';
 export type { NativeImportReport, NativeImportResult, NativeImportStatus } from './fallback.js';
+export declare const SECRETS_ITEM_PREFIX = "agents-cli.secrets.";
 /** Supported secret resolution backends. */
 export type SecretProvider = 'keychain' | 'env' | 'file' | 'exec';
 /** A typed reference to a secret, consisting of a provider and a provider-specific value. */
@@ -73,7 +74,11 @@ export declare function secretsKeychainItem(bundle: string, key: string): string
 export interface KeychainBackend {
     has(item: string): boolean;
     get(item: string): string;
-    set(item: string, value: string): void;
+    /** `opts.noAcl` mirrors setKeychainToken's no-ACL write path so tests can
+     * assert which path a write took; in-memory backends may ignore it. */
+    set(item: string, value: string, opts?: {
+        noAcl?: boolean;
+    }): void;
     delete(item: string): boolean;
     list(prefix: string): string[];
 }
@@ -84,6 +89,103 @@ export declare function setKeychainBackendForTest(b: KeychainBackend | null): Ke
  * 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 declare function isKeychainBackendOverridden(): boolean;
+export declare const HMAC_KEY_ITEM = "agents-cli.hmackey";
+/** Force hashed service names on with a fixed key (test only). Pass null to
+ * restore lazy production resolution. Composes with setKeychainBackendForTest
+ * so unit tests exercise the exact transform production uses. */
+export declare function setKeychainServiceHashingForTest(key: Buffer | null): void;
+/**
+ * Run `fn` with service-name hashing suspended: every primitive uses the
+ * literal names it is given. For migration flows ONLY — they enumerate raw
+ * names from the helper (which may be pre-re-key cleartext leftovers) and must
+ * read/delete those exact items, not their hashed transforms.
+ */
+export declare function withRawKeychainServiceNames<T>(fn: () => T): T;
+/** The hashed (storage) service name for a cleartext item name. Exported for
+ * the re-key migration and tests; runtime callers go through the primitives,
+ * which apply this transparently. */
+export declare function hashedServiceName(item: string, key: Buffer): string;
+/**
+ * The storage-layer service name for `item`: hashed when hashing is active,
+ * the item itself otherwise. For callers that mix helper-enumerated
+ * (already-hashed) names with computed cleartext names in one lookup map —
+ * see readAndResolveBundleEnv.
+ */
+export declare function keychainServiceAlias(item: string): string;
+/** One re-keyed (or failed) item, by its old cleartext service name. */
+export interface RekeyPlanItem {
+    oldService: string;
+    newService: string;
+    /** Preserve the no-ACL write path for `never`-policy bundle items. */
+    noAcl: boolean;
+    /** Replacement payload (bundle metadata gets `name` injected); absent = copy verbatim. */
+    payload?: string;
+}
+/**
+ * Build the old→new mapping for a set of cleartext services. Bundle metadata
+ * is parsed first to (a) recover each bundle's prompt policy — the persisted
+ * `tier` token, where `none`/`never` means the item must be re-written through
+ * the no-ACL path — and (b) inject the cleartext `name` into the JSON, because
+ * after hashing the service name can no longer carry it (listBundles reads it
+ * back from the payload). A value item's tier is resolved from its bundle's
+ * metadata PAYLOAD in `values` — under the cleartext metadata name or its
+ * hashed transform — never from the metadata item being part of the same
+ * `services` batch: a --prefix run can scope a bundle's value items alone, and
+ * rekeyServiceNames supplies the out-of-scope metadata reads (see the
+ * supplemental batch there). Exported for unit tests.
+ */
+export declare function computeRekeyPlan(services: string[], values: Map<string, string>, key: Buffer): {
+    items: RekeyPlanItem[];
+    unreadable: string[];
+};
+/** Outcome of one rekeyServiceNames run. */
+export interface RekeyReport {
+    /** Old cleartext services whose items now live under hashed names. */
+    migrated: string[];
+    failed: Array<{
+        item: string;
+        detail: string;
+    }>;
+    /** True when hashed naming is on after this run. */
+    activated: boolean;
+    nothingToDo: boolean;
+}
+/**
+ * The one-time re-key: move every cleartext-named `agents-cli.*` item to its
+ * hashed service name. Composed entirely from the existing helper primitives —
+ * no new Swift command:
+ *
+ *   1. Enumerate cleartext services (silent) and batch-read every value behind
+ *      ONE Touch ID (`get-batch`; readItem also sweeps legacy/orphaned copies).
+ *   2. Write each hashed copy (`set`/`set-no-acl` never prompt), preserving
+ *      the no-ACL tier for `never`-policy bundles.
+ *   3. Batch-verify every copy round-trips (second Touch ID).
+ *   4. Only then activate hashing (sentinel + pendingDeletes) and delete the
+ *      old items (silent).
+ *
+ * Add-before-delete throughout: a cancel/crash/failure anywhere before step 4
+ * leaves every old item intact and hashing OFF — same rationale as the
+ * helper's migrate-orphans, which is also why no pre-write backup is taken.
+ * On ANY per-item failure nothing is deleted and the sentinel stays off
+ * (all-or-nothing activation); the report names every failed item. A crash
+ * between the sentinel write and the deletes is resumed silently by the next
+ * process (pendingDeletes). Idempotent: re-running converges.
+ */
+export declare function rekeyServiceNames(opts?: {
+    prefixes?: string[];
+    announce?: boolean;
+    log?: (line: string) => void;
+}): RekeyReport;
+/** Re-key state snapshot for `agents secrets rekey --status`. */
+export declare function rekeyStatus(): {
+    migrated: boolean;
+    hasKey: boolean;
+    pendingDeletes: number;
+    cleartext: string[];
+    /** False when the enumeration probe fails (locked keybag) — the cleartext
+     * count is then meaningless. Only probeable once the key record exists. */
+    enumerationOk: boolean;
+};
 /** Check if a keychain/keyring item exists. Never prompts for biometry. */
 export declare function hasKeychainToken(item: string): boolean;
 /**
@@ -128,7 +230,10 @@ export declare function deleteKeychainToken(item: string): boolean;
  * and the direct file enumeration return the same items.
  */
 export declare function keychainUsesFileFallback(): boolean;
-/** Enumerate keychain/keyring item names starting with the given prefix. */
+/** Enumerate keychain/keyring item names starting with the given prefix.
+ * With hashed service names active, the two sub-namespace prefixes callers
+ * use (bundle metadata; one bundle's value items) are mapped to their hashed
+ * shapes — the returned names are then storage (opaque) names. */
 export declare function listKeychainItems(prefix: string): string[];
 /**
  * Enumerate ONLY legacy file-based-keychain item names with the given prefix —
@@ -141,6 +246,41 @@ export declare function listKeychainItems(prefix: string): string[];
  * stragglers instead of every item (which would be a Touch ID storm).
  */
 export declare function listLegacyKeychainItems(prefix: string): string[];
+/**
+ * Test seam for the LEGACY SYNCHRONIZABLE (iCloud Keychain) recovery path.
+ * The main `KeychainBackend` seam models the live device-local store; this one
+ * models the orphaned iCloud items that `secrets import --from icloud` reads.
+ * Kept separate so a test can populate both sides independently.
+ */
+export interface SyncedKeychainBackend {
+    list(prefix: string): string[];
+    getBatch(items: string[]): Map<string, string>;
+    delete(item: string): boolean;
+}
+export declare function setSyncedKeychainBackendForTest(b: SyncedKeychainBackend | null): SyncedKeychainBackend | null;
+/**
+ * Enumerate LEGACY SYNCHRONIZABLE (iCloud Keychain) item names with the given
+ * prefix — bundles written by the pre-biometry helper era, which defaulted
+ * secrets to iCloud Keychain sync. The device-local cutover orphaned them:
+ * every modern query pins synchronizable=false, so only the helper's
+ * `list-synced` verb can see them. Silent (attributes only, never decrypts).
+ * macOS only — Linux/Windows never had iCloud Keychain sync, so this returns [].
+ */
+export declare function listSyncedKeychainItems(prefix: string): string[];
+/**
+ * Batch-read LEGACY SYNCHRONIZABLE (iCloud Keychain) items. Returns a map of
+ * item name → value; missing items are simply absent. Pre-biometry items carry
+ * no biometry ACL, so this does not normally prompt. macOS only — returns an
+ * empty map on Linux/Windows.
+ */
+export declare function getSyncedKeychainTokens(items: string[]): Map<string, string>;
+/**
+ * Delete a LEGACY SYNCHRONIZABLE (iCloud Keychain) item after a successful
+ * import (`--purge`). Matches synchronizable items only — the device-local
+ * copy the import wrote is untouched. iCloud propagates the deletion to the
+ * user's other devices. Returns true if a copy was removed.
+ */
+export declare function deleteSyncedKeychainItem(item: string): 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