@centient/secrets 0.5.0 → 0.7.0

package/README.md

@@ -2,6 +2,8 @@
 
 Cross-platform secrets vault with AES-256-GCM encryption and platform-native key storage.
 
+> **Daemons / long-running processes:** see [Session-backed vault (`openVault`)](./docs/session-vault.md) for the recommended API — single master-key unlock per session, in-memory cached reads, mtime-check coherence with the CLI, rollback protection via monotonic version + sidecar.
+
 ## Installation
 
 ```bash
@@ -18,7 +20,7 @@ pnpm add @centient/secrets
 
 - AES-256-GCM authenticated encryption for secrets at rest
 - Platform-native key storage (macOS Keychain, Linux secret-service)
-- Pluggable key providers (Keychain, 1Password)
+- Pluggable key providers (Keychain, 1Password, passphrase)
 - Credential vault with session management
 - Environment detection (CI, Docker, SSH, headless, agent)
 - Built-in CLI for interactive secret management
@@ -64,6 +66,42 @@ if (isCIEnvironment()) {
 |----------|----------|-------------|
 | `KeychainProvider` | macOS/Linux | Uses OS keychain (Keychain Access / secret-service) |
 | `OnePasswordProvider` | Any | Uses 1Password CLI for team secret sharing |
+| `PassphraseProvider` | Any (interactive TTY) | Derives the vault key from a typed passphrase via scrypt — no OS keychain required |
+
+Provider auto-detection prefers OS-backed storage: 1Password, then Keychain,
+then passphrase as the last fallback. Set `secrets.provider: "passphrase"` in
+`~/.centient/config.json` to select it explicitly.
+
+### Passphrase provider
+
+For hosts without an OS keychain or 1Password CLI (e.g. a headless Linux box
+over SSH), the vault key is derived from a passphrase typed at an interactive
+terminal using scrypt (`N=2^17, r=8, p=1`, 32-byte key — ~128 MB memory cost
+per derivation, in line with current OWASP guidance). The passphrase and the
+derived key are never persisted. A sidecar file (`vault.passphrase.json`,
+mode `0600`, beside the vault) stores only the salt, the KDF parameters, and
+an HMAC-SHA256 verifier used to detect a wrong passphrase without revealing
+the key.
+
+Security tradeoffs vs OS-backed providers — choose deliberately:
+
+- **Passphrase strength is the security ceiling.** Keychain keys are random
+  256-bit values guarded by the OS; a passphrase-derived key is only as strong
+  as the passphrase. The scrypt cost is the sole brake on brute force.
+- **The sidecar enables offline guessing if exfiltrated.** An attacker holding
+  `vault.passphrase.json` (or the vault file) can test candidate passphrases
+  offline at ~one guess per 128 MB-scrypt derivation. Use a long, high-entropy
+  passphrase.
+- **No human-presence guarantee.** Unlike Keychain with Touch ID, typing a
+  passphrase proves knowledge, not presence; it cannot satisfy policies that
+  require fresh per-operation human auth.
+- **Interactive TTY required — fails closed otherwise.** In CI, agent, or
+  other non-interactive contexts the provider refuses to prompt and unlock
+  fails with an actionable error. Configure keychain/1Password for
+  non-interactive use.
+- **Unlock blocks the event loop.** Key derivation is synchronous (~hundreds
+  of ms); daemons should call `openVault()` once at startup, before entering
+  their hot loop.
 
 ## License
 

package/dist/cli/hidden-input.d.ts

@@ -0,0 +1,52 @@
+/**
+ * Hidden-Input State Machine
+ *
+ * Pure character-stream parser used by the secrets CLI's hidden-input prompt
+ * (password / secret entry). Extracted from `secrets-cli.ts` so the parsing
+ * rules can be exercised directly in tests without stubbing `process.stdin`.
+ *
+ * Regression: issue #37 — the previous prompt resolved on the first `\n`
+ * from a terminal paste and silently truncated multi-line secrets (PEM keys,
+ * multi-line config blobs) to their first line.
+ */
+/** VT100 bracketed-paste sentinels — wraps pasted content from the terminal. */
+export declare const PASTE_START = "\u001B[200~";
+export declare const PASTE_END = "\u001B[201~";
+/** Enable / disable bracketed paste mode on the current terminal. */
+export declare const ENABLE_BRACKETED_PASTE = "\u001B[?2004h";
+export declare const DISABLE_BRACKETED_PASTE = "\u001B[?2004l";
+/** Control characters recognized by the hidden-input state machine. */
+export declare const CTRL_C = "\u0003";
+export declare const CTRL_D = "\u0004";
+export declare const BACKSPACE = "";
+export declare const BS = "\b";
+/** Signal emitted by {@link advanceHiddenInput} to indicate why input stopped. */
+export type HiddenInputSignal = "submit" | "ctrl-c" | "continue";
+/**
+ * Mutable state for the hidden-input parser. Callers should construct a fresh
+ * instance per prompt and feed chunks via {@link advanceHiddenInput}.
+ */
+export interface HiddenInputState {
+    input: string;
+    inPaste: boolean;
+    escBuf: string;
+    /**
+     * True when the state machine has recognized an escape sequence that is not
+     * a paste-marker prefix and is swallowing characters until the sequence's
+     * terminator byte arrives. Prevents stray `~` / digits from unrelated CSI
+     * sequences (e.g. Delete `\x1b[3~`, arrow keys) from leaking into `input`.
+     */
+    swallowingCsi: boolean;
+}
+export declare function createHiddenInputState(): HiddenInputState;
+/**
+ * Advance the state machine with a single chunk from stdin. Returns `"submit"`
+ * when the caller should resolve the prompt with `state.input`, `"ctrl-c"`
+ * when the user interrupted, or `"continue"` when more input is expected.
+ *
+ * Character-by-character processing ensures escape-sequence state survives
+ * across chunk boundaries (a fast paste may arrive split across many chunks,
+ * and a single chunk may contain both paste markers and regular keystrokes).
+ */
+export declare function advanceHiddenInput(state: HiddenInputState, chunk: string): HiddenInputSignal;
+//# sourceMappingURL=hidden-input.d.ts.map

package/dist/cli/hidden-input.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hidden-input.d.ts","sourceRoot":"","sources":["../../src/cli/hidden-input.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,gFAAgF;AAChF,eAAO,MAAM,WAAW,gBAAc,CAAC;AACvC,eAAO,MAAM,SAAS,gBAAc,CAAC;AACrC,qEAAqE;AACrE,eAAO,MAAM,sBAAsB,kBAAgB,CAAC;AACpD,eAAO,MAAM,uBAAuB,kBAAgB,CAAC;AAErD,uEAAuE;AACvE,eAAO,MAAM,MAAM,WAAW,CAAC;AAC/B,eAAO,MAAM,MAAM,WAAW,CAAC;AAC/B,eAAO,MAAM,SAAS,MAAW,CAAC;AAClC,eAAO,MAAM,EAAE,OAAO,CAAC;AAEvB,kFAAkF;AAClF,MAAM,MAAM,iBAAiB,GAAG,QAAQ,GAAG,QAAQ,GAAG,UAAU,CAAC;AAEjE;;;GAGG;AACH,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf;;;;;OAKG;IACH,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,wBAAgB,sBAAsB,IAAI,gBAAgB,CAEzD;AAeD;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,KAAK,EAAE,gBAAgB,EACvB,KAAK,EAAE,MAAM,GACZ,iBAAiB,CAmEnB"}

package/dist/cli/hidden-input.js

@@ -0,0 +1,109 @@
+/**
+ * Hidden-Input State Machine
+ *
+ * Pure character-stream parser used by the secrets CLI's hidden-input prompt
+ * (password / secret entry). Extracted from `secrets-cli.ts` so the parsing
+ * rules can be exercised directly in tests without stubbing `process.stdin`.
+ *
+ * Regression: issue #37 — the previous prompt resolved on the first `\n`
+ * from a terminal paste and silently truncated multi-line secrets (PEM keys,
+ * multi-line config blobs) to their first line.
+ */
+/** VT100 bracketed-paste sentinels — wraps pasted content from the terminal. */
+export const PASTE_START = "\x1b[200~";
+export const PASTE_END = "\x1b[201~";
+/** Enable / disable bracketed paste mode on the current terminal. */
+export const ENABLE_BRACKETED_PASTE = "\x1b[?2004h";
+export const DISABLE_BRACKETED_PASTE = "\x1b[?2004l";
+/** Control characters recognized by the hidden-input state machine. */
+export const CTRL_C = "\u0003";
+export const CTRL_D = "\u0004";
+export const BACKSPACE = "\u007F";
+export const BS = "\b";
+export function createHiddenInputState() {
+    return { input: "", inPaste: false, escBuf: "", swallowingCsi: false };
+}
+/**
+ * CSI final-byte range per ECMA-48: `\x40`-`\x7E` (i.e. `@` through `~`). When
+ * we're swallowing a CSI we know isn't a paste marker, we stop at the first
+ * byte in this range that isn't a parameter byte (`0`-`9`, `;`, `:`, `<`-`?`).
+ */
+function isCsiTerminator(char) {
+    const code = char.charCodeAt(0);
+    // Parameter / intermediate bytes — not terminators.
+    if ((code >= 0x30 && code <= 0x3f) || (code >= 0x20 && code <= 0x2f))
+        return false;
+    // Final byte range.
+    return code >= 0x40 && code <= 0x7e;
+}
+/**
+ * Advance the state machine with a single chunk from stdin. Returns `"submit"`
+ * when the caller should resolve the prompt with `state.input`, `"ctrl-c"`
+ * when the user interrupted, or `"continue"` when more input is expected.
+ *
+ * Character-by-character processing ensures escape-sequence state survives
+ * across chunk boundaries (a fast paste may arrive split across many chunks,
+ * and a single chunk may contain both paste markers and regular keystrokes).
+ */
+export function advanceHiddenInput(state, chunk) {
+    for (let i = 0; i < chunk.length; i++) {
+        const char = chunk[i];
+        // Swallowing a non-paste CSI sequence: drop characters until the CSI
+        // terminator byte arrives, then resume normal processing.
+        if (state.swallowingCsi) {
+            if (isCsiTerminator(char))
+                state.swallowingCsi = false;
+            continue;
+        }
+        // Accumulate potential bracketed-paste marker.
+        if (state.escBuf || char === "\x1b") {
+            state.escBuf += char;
+            if (state.escBuf === PASTE_START) {
+                state.inPaste = true;
+                state.escBuf = "";
+                continue;
+            }
+            if (state.escBuf === PASTE_END) {
+                state.inPaste = false;
+                state.escBuf = "";
+                continue;
+            }
+            // If escBuf is no longer a prefix of either paste marker, it's a
+            // different escape sequence (arrow keys, Delete, F-keys, etc.). Switch
+            // to swallow-until-terminator mode so we don't leak the sequence's
+            // final byte (e.g. `~` from `\x1b[3~`) into the input buffer.
+            if (!PASTE_START.startsWith(state.escBuf) &&
+                !PASTE_END.startsWith(state.escBuf)) {
+                // If the current char is already a terminator, we've consumed the
+                // entire sequence; no need to swallow more.
+                state.swallowingCsi = !isCsiTerminator(char);
+                state.escBuf = "";
+            }
+            continue;
+        }
+        // Inside a bracketed paste, newlines are literal content.
+        if (state.inPaste) {
+            state.input += char;
+            continue;
+        }
+        if (char === CTRL_C)
+            return "ctrl-c";
+        if (char === CTRL_D) {
+            // Explicit end-of-input (multi-line escape hatch for terminals without
+            // bracketed-paste support).
+            return "submit";
+        }
+        if (char === "\n" || char === "\r") {
+            // Single-line submit — preserves the old single-password UX.
+            return "submit";
+        }
+        if (char === BACKSPACE || char === BS) {
+            if (state.input.length > 0)
+                state.input = state.input.slice(0, -1);
+            continue;
+        }
+        state.input += char;
+    }
+    return "continue";
+}
+//# sourceMappingURL=hidden-input.js.map

package/dist/cli/hidden-input.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hidden-input.js","sourceRoot":"","sources":["../../src/cli/hidden-input.ts"],"names":[],"mappings":"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"}

package/dist/cli/hidden-prompt.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Synchronous hidden TTY prompt.
+ *
+ * KeyProvider implementations are synchronous today, so passphrase unlock
+ * needs a sync wrapper around the hidden-input state machine. The parser stays
+ * in hidden-input.ts; this file only owns terminal raw-mode and fd reads.
+ */
+interface PromptInput {
+    readonly fd?: number;
+    readonly isRaw?: boolean;
+    readonly isTTY?: boolean;
+    pause?(): unknown;
+    resume?(): unknown;
+    setRawMode?(mode: boolean): unknown;
+}
+interface PromptOutput {
+    write(chunk: string): unknown;
+}
+export interface HiddenPromptOptions {
+    input?: PromptInput;
+    output?: PromptOutput;
+}
+export declare class HiddenPromptError extends Error {
+    constructor(message: string);
+}
+export declare const NON_INTERACTIVE_HIDDEN_PROMPT_MESSAGE = "Passphrase provider requires an interactive TTY. Run this command from a terminal so the passphrase can be typed, or configure keychain/1password for non-interactive use.";
+/**
+ * Upper bound on accumulated hidden input. Interactive passphrases and pasted
+ * multi-line secrets (PEM keys, config blobs — issue #37) fit comfortably;
+ * the cap exists so a hostile or broken input source feeding endless bytes
+ * without a submit cannot grow `state.input` without bound.
+ */
+export declare const MAX_HIDDEN_INPUT_LENGTH = 65536;
+export declare const HIDDEN_INPUT_TOO_LONG_MESSAGE = "Hidden input exceeded 65536 characters without a submit; aborting prompt.";
+/**
+ * Prompt for a hidden single-line value from a real TTY.
+ *
+ * Returns null when the user sends Ctrl-C. Throws HiddenPromptError when stdin
+ * is not an interactive TTY; callers should fail closed.
+ *
+ * Known limitation: the submitted value is returned as an immutable JS string,
+ * which cannot be zeroed and lingers in the heap until GC — same residue class
+ * as the session-vault key-in-RAM caveat. The transient read buffer IS zeroed
+ * before return.
+ */
+export declare function promptHiddenSync(message: string, options?: HiddenPromptOptions): string | null;
+export {};
+//# sourceMappingURL=hidden-prompt.d.ts.map

package/dist/cli/hidden-prompt.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hidden-prompt.d.ts","sourceRoot":"","sources":["../../src/cli/hidden-prompt.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAWH,UAAU,WAAW;IACnB,QAAQ,CAAC,EAAE,CAAC,EAAE,MAAM,CAAC;IACrB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,KAAK,CAAC,IAAI,OAAO,CAAC;IAClB,MAAM,CAAC,IAAI,OAAO,CAAC;IACnB,UAAU,CAAC,CAAC,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC;CACrC;AAED,UAAU,YAAY;IACpB,KAAK,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,mBAAmB;IAClC,KAAK,CAAC,EAAE,WAAW,CAAC;IACpB,MAAM,CAAC,EAAE,YAAY,CAAC;CACvB;AAED,qBAAa,iBAAkB,SAAQ,KAAK;gBAC9B,OAAO,EAAE,MAAM;CAI5B;AAED,eAAO,MAAM,qCAAqC,+KAC4H,CAAC;AAE/K;;;;;GAKG;AACH,eAAO,MAAM,uBAAuB,QAAS,CAAC;AAE9C,eAAO,MAAM,6BAA6B,8EAAmG,CAAC;AAQ9I;;;;;;;;;;GAUG;AACH,wBAAgB,gBAAgB,CAC9B,OAAO,EAAE,MAAM,EACf,OAAO,GAAE,mBAAwB,GAChC,MAAM,GAAG,IAAI,CAqFf"}

package/dist/cli/hidden-prompt.js

@@ -0,0 +1,127 @@
+/**
+ * Synchronous hidden TTY prompt.
+ *
+ * KeyProvider implementations are synchronous today, so passphrase unlock
+ * needs a sync wrapper around the hidden-input state machine. The parser stays
+ * in hidden-input.ts; this file only owns terminal raw-mode and fd reads.
+ */
+import { readSync } from "node:fs";
+import { StringDecoder } from "node:string_decoder";
+import { advanceHiddenInput, createHiddenInputState, DISABLE_BRACKETED_PASTE, ENABLE_BRACKETED_PASTE, } from "./hidden-input.js";
+export class HiddenPromptError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "HiddenPromptError";
+    }
+}
+export const NON_INTERACTIVE_HIDDEN_PROMPT_MESSAGE = "Passphrase provider requires an interactive TTY. Run this command from a terminal so the passphrase can be typed, or configure keychain/1password for non-interactive use.";
+/**
+ * Upper bound on accumulated hidden input. Interactive passphrases and pasted
+ * multi-line secrets (PEM keys, config blobs — issue #37) fit comfortably;
+ * the cap exists so a hostile or broken input source feeding endless bytes
+ * without a submit cannot grow `state.input` without bound.
+ */
+export const MAX_HIDDEN_INPUT_LENGTH = 65_536;
+export const HIDDEN_INPUT_TOO_LONG_MESSAGE = `Hidden input exceeded ${MAX_HIDDEN_INPUT_LENGTH} characters without a submit; aborting prompt.`;
+const PROMPT_SIGNALS = [
+    "SIGINT",
+    "SIGTERM",
+    "SIGHUP",
+];
+/**
+ * Prompt for a hidden single-line value from a real TTY.
+ *
+ * Returns null when the user sends Ctrl-C. Throws HiddenPromptError when stdin
+ * is not an interactive TTY; callers should fail closed.
+ *
+ * Known limitation: the submitted value is returned as an immutable JS string,
+ * which cannot be zeroed and lingers in the heap until GC — same residue class
+ * as the session-vault key-in-RAM caveat. The transient read buffer IS zeroed
+ * before return.
+ */
+export function promptHiddenSync(message, options = {}) {
+    const input = options.input ?? process.stdin;
+    const output = options.output ?? process.stdout;
+    if (input.isTTY !== true || typeof input.fd !== "number") {
+        throw new HiddenPromptError(NON_INTERACTIVE_HIDDEN_PROMPT_MESSAGE);
+    }
+    const state = createHiddenInputState();
+    const decoder = new StringDecoder("utf8");
+    const buffer = Buffer.allocUnsafe(256);
+    const wasRaw = input.isRaw === true;
+    let restored = false;
+    const restoreTerminal = () => {
+        if (restored)
+            return;
+        restored = true;
+        output.write(DISABLE_BRACKETED_PASTE);
+        input.setRawMode?.(wasRaw);
+        input.pause?.();
+        output.write("\n");
+    };
+    // A signal's default disposition terminates the process without unwinding
+    // the stack, so `finally` would never run and the terminal would be left in
+    // raw mode with echo disabled. The terminal's own Ctrl-C arrives in-band as
+    // \x03 under raw mode, so these handlers only matter for external signals
+    // (`kill`, hangup).
+    //
+    // Timing: this entire prompt is synchronous, so the event loop cannot
+    // dispatch a signal's JS callback while it runs — an external signal
+    // received here is queued by libuv and dispatched only after the prompt
+    // unwinds. Installing the listeners suppresses the immediate default kill
+    // (protecting raw mode); the deferred handler then re-raises so the default
+    // exit behavior is preserved. That is also why removal is deferred one tick
+    // in `finally` below: removing the listeners synchronously would drop the
+    // queued dispatch and the process would silently ignore a kill received
+    // during the prompt.
+    const onSignal = (signal) => {
+        // Remove ALL prompt listeners (not just this signal's spent `once`
+        // wrapper) before re-raising, so the re-raised signal hits the default
+        // disposition and sibling handlers cannot fire after the prompt is done.
+        removeSignalHandlers();
+        restoreTerminal();
+        process.kill(process.pid, signal);
+    };
+    const removeSignalHandlers = () => {
+        for (const signal of PROMPT_SIGNALS) {
+            process.removeListener(signal, onSignal);
+        }
+    };
+    for (const signal of PROMPT_SIGNALS)
+        process.once(signal, onSignal);
+    output.write(message);
+    input.setRawMode?.(true);
+    output.write(ENABLE_BRACKETED_PASTE);
+    input.resume?.();
+    try {
+        while (true) {
+            const bytesRead = readSync(input.fd, buffer, 0, buffer.length, null);
+            if (bytesRead === 0)
+                return null;
+            const chunk = decoder.write(buffer.subarray(0, bytesRead));
+            const signal = advanceHiddenInput(state, chunk);
+            if (signal === "ctrl-c")
+                return null;
+            if (signal === "submit")
+                return state.input;
+            if (state.input.length > MAX_HIDDEN_INPUT_LENGTH) {
+                // Drop the reference before throwing; the string itself is immutable
+                // and lingers until GC (same residue class as the documented caveat).
+                state.input = "";
+                throw new HiddenPromptError(HIDDEN_INPUT_TOO_LONG_MESSAGE);
+            }
+        }
+    }
+    finally {
+        // The read buffer held raw passphrase bytes — zero it before returning.
+        buffer.fill(0);
+        restoreTerminal();
+        // Deferred (see the comment on onSignal): a signal received while
+        // readSync blocked has not been dispatched yet — removing the listeners
+        // now would swallow it. One tick later either the queued handler has
+        // re-raised (process is exiting) or there was no signal and this is a
+        // plain cleanup.
+        setImmediate(removeSignalHandlers);
+    }
+}
+//# sourceMappingURL=hidden-prompt.js.map

package/dist/cli/hidden-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hidden-prompt.js","sourceRoot":"","sources":["../../src/cli/hidden-prompt.ts"],"names":[],"mappings":"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"}

package/dist/cli/secrets-cli.d.ts

@@ -25,8 +25,16 @@
  * Security:
  *   - All commands check for AI agent environment and refuse to run
  *   - Vault is encrypted with AES-256-GCM
- *   - Key stored via pluggable provider (macOS Keychain or 1Password)
+ *   - Key stored or derived via pluggable provider (macOS Keychain, 1Password,
+ *     or passphrase)
  *   - 4-hour session timeout
+ *
+ * Internals:
+ *   Vault mutations flow through `openVault` (session-vault.ts) so the CLI
+ *   and the library-facing API share one on-disk format (AAD-bound, schema 1).
+ *   Pre-`openVault` CLI-written vaults (AAD-less, legacy flat format) are
+ *   handled transparently by session-vault's legacy-read path and upgraded to
+ *   schema 1 on the next successful write.
  */
 export interface SecretsOptions {
     command: "init" | "unlock" | "lock" | "list" | "list-backend-keys" | "set" | "get" | "delete" | "status" | "migrate" | "env-list" | "env-switch" | "env-create" | "env-current";

package/dist/cli/secrets-cli.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"secrets-cli.d.ts","sourceRoot":"","sources":["../../src/cli/secrets-cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAWH,MAAM,WAAW,cAAc;IAC7B,OAAO,EACH,MAAM,GACN,QAAQ,GACR,MAAM,GACN,MAAM,GACN,mBAAmB,GACnB,KAAK,GACL,KAAK,GACL,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,UAAU,GACV,YAAY,GACZ,YAAY,GACZ,aAAa,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAirBD;;GAEG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAwDvE"}
+{"version":3,"file":"secrets-cli.d.ts","sourceRoot":"","sources":["../../src/cli/secrets-cli.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAkBH,MAAM,WAAW,cAAc;IAC7B,OAAO,EACH,MAAM,GACN,QAAQ,GACR,MAAM,GACN,MAAM,GACN,mBAAmB,GACnB,KAAK,GACL,KAAK,GACL,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,UAAU,GACV,YAAY,GACZ,YAAY,GACZ,aAAa,CAAC;IAClB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,+EAA+E;IAC/E,IAAI,CAAC,EAAE,OAAO,CAAC;CAChB;AAwwBD;;GAEG;AACH,wBAAsB,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,IAAI,CAAC,CAwDvE"}