@centient/secrets 0.2.0

package/dist/platform/agent-detect.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Agent Environment Detection
+ *
+ * Detects whether the process is running inside an AI agent session
+ * (Claude Code, MCP context, etc.). Auth commands that require human
+ * interaction are blocked in these environments.
+ *
+ * Shared by: vault.ts, cli, secrets-cli.ts
+ */
+/**
+ * Returns true if the current process appears to be running inside an
+ * AI agent environment (Claude Code, MCP subprocess, etc.).
+ */
+export declare function isAgentEnvironment(): boolean;
+//# sourceMappingURL=agent-detect.d.ts.map

package/dist/platform/agent-detect.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-detect.d.ts","sourceRoot":"","sources":["../../src/platform/agent-detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;GAGG;AACH,wBAAgB,kBAAkB,IAAI,OAAO,CAS5C"}

package/dist/platform/agent-detect.js

@@ -0,0 +1,22 @@
+/**
+ * Agent Environment Detection
+ *
+ * Detects whether the process is running inside an AI agent session
+ * (Claude Code, MCP context, etc.). Auth commands that require human
+ * interaction are blocked in these environments.
+ *
+ * Shared by: vault.ts, cli, secrets-cli.ts
+ */
+/**
+ * Returns true if the current process appears to be running inside an
+ * AI agent environment (Claude Code, MCP subprocess, etc.).
+ */
+export function isAgentEnvironment() {
+    return !!(process.env["CLAUDE_PROJECT_DIR"] ||
+        process.env["MCP_CONTEXT"] ||
+        process.env["CLAUDE_CODE_SESSION"] ||
+        process.env["CLAUDE_CODE_ENTRY_POINT"] ||
+        process.env["ANTHROPIC_API_KEY_SOURCE"] ||
+        process.env["MCP_SERVER_NAME"]);
+}
+//# sourceMappingURL=agent-detect.js.map

package/dist/platform/agent-detect.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent-detect.js","sourceRoot":"","sources":["../../src/platform/agent-detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;GAGG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,CAAC,CAAC,CACP,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;QACjC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;QAC1B,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC;QAClC,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC;QACtC,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC;QACvC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAC/B,CAAC;AACJ,CAAC"}

package/dist/platform/platform.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Auth Platform — Capability Detection
+ *
+ * Detects terminal/platform capabilities for rendering decisions.
+ * All functions are pure (no side effects beyond reading process.env / process.stdout).
+ */
+/**
+ * Returns true if stdout is a TTY (interactive terminal).
+ * Spinner, colour, and unicode output should only be used when this is true.
+ */
+export declare function isTTY(): boolean;
+/**
+ * Returns true if the terminal likely supports Unicode characters.
+ * Detection is based on LANG or LC_ALL containing "UTF-8" (case-insensitive).
+ * Falls back to false when environment variables are absent.
+ */
+export declare function canUnicode(): boolean;
+/**
+ * Returns true if running in a headless environment (no display server).
+ *
+ * On Linux: checks for absence of DISPLAY and WAYLAND_DISPLAY and
+ * XDG_CURRENT_DESKTOP env vars.
+ * On macOS: always returns false (macOS always has a window server available
+ * even in SSH sessions with X11 forwarding disabled).
+ * In CI environments: treats CI=true as headless.
+ */
+export declare function isHeadless(): boolean;
+/**
+ * Returns true if the system has a browser launcher available.
+ *
+ * macOS: checks for `open` (always present).
+ * Linux: checks for `xdg-open` via `which`.
+ * Other: returns false.
+ */
+export declare function canLaunchBrowser(): boolean;
+/**
+ * Returns true if the process is running in a known CI environment.
+ * Checks standard CI environment variables used by common CI platforms.
+ */
+export declare function isCIEnvironment(): boolean;
+/**
+ * Returns true if the process is running inside a Docker or containerd container.
+ * Checks /proc/1/cgroup for container markers and /.dockerenv existence.
+ */
+export declare function isDockerContainer(): boolean;
+/**
+ * Returns true if the process is running inside an SSH session.
+ * Checks SSH_CONNECTION and SSH_CLIENT environment variables.
+ */
+export declare function isSSHSession(): boolean;
+//# sourceMappingURL=platform.d.ts.map

package/dist/platform/platform.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"platform.d.ts","sourceRoot":"","sources":["../../src/platform/platform.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AASH;;;GAGG;AACH,wBAAgB,KAAK,IAAI,OAAO,CAE/B;AAMD;;;;GAIG;AACH,wBAAgB,UAAU,IAAI,OAAO,CASpC;AAMD;;;;;;;;GAQG;AACH,wBAAgB,UAAU,IAAI,OAAO,CAiBpC;AAMD;;;;;;GAMG;AACH,wBAAgB,gBAAgB,IAAI,OAAO,CAkB1C;AAMD;;;GAGG;AACH,wBAAgB,eAAe,IAAI,OAAO,CASzC;AAMD;;;GAGG;AACH,wBAAgB,iBAAiB,IAAI,OAAO,CAe3C;AAMD;;;GAGG;AACH,wBAAgB,YAAY,IAAI,OAAO,CAEtC"}

package/dist/platform/platform.js

@@ -0,0 +1,141 @@
+/**
+ * Auth Platform — Capability Detection
+ *
+ * Detects terminal/platform capabilities for rendering decisions.
+ * All functions are pure (no side effects beyond reading process.env / process.stdout).
+ */
+import { existsSync, readFileSync } from "fs";
+import { execSync } from "child_process";
+// =============================================================================
+// TTY detection
+// =============================================================================
+/**
+ * Returns true if stdout is a TTY (interactive terminal).
+ * Spinner, colour, and unicode output should only be used when this is true.
+ */
+export function isTTY() {
+    return process.stdout.isTTY === true;
+}
+// =============================================================================
+// Unicode detection
+// =============================================================================
+/**
+ * Returns true if the terminal likely supports Unicode characters.
+ * Detection is based on LANG or LC_ALL containing "UTF-8" (case-insensitive).
+ * Falls back to false when environment variables are absent.
+ */
+export function canUnicode() {
+    const lang = process.env["LANG"] ?? "";
+    const lcAll = process.env["LC_ALL"] ?? "";
+    const lcCtype = process.env["LC_CTYPE"] ?? "";
+    return (/utf-?8/i.test(lang) ||
+        /utf-?8/i.test(lcAll) ||
+        /utf-?8/i.test(lcCtype));
+}
+// =============================================================================
+// Headless detection
+// =============================================================================
+/**
+ * Returns true if running in a headless environment (no display server).
+ *
+ * On Linux: checks for absence of DISPLAY and WAYLAND_DISPLAY and
+ * XDG_CURRENT_DESKTOP env vars.
+ * On macOS: always returns false (macOS always has a window server available
+ * even in SSH sessions with X11 forwarding disabled).
+ * In CI environments: treats CI=true as headless.
+ */
+export function isHeadless() {
+    // Explicit CI flag
+    if (process.env["CI"] === "true" || process.env["CI"] === "1")
+        return true;
+    // macOS has a window server; treat as non-headless unless CI
+    if (process.platform === "darwin")
+        return false;
+    // Linux: headless if no display server variables are set
+    if (process.platform === "linux") {
+        const hasDisplay = Boolean(process.env["DISPLAY"]);
+        const hasWayland = Boolean(process.env["WAYLAND_DISPLAY"]);
+        const hasDesktop = Boolean(process.env["XDG_CURRENT_DESKTOP"]);
+        return !hasDisplay && !hasWayland && !hasDesktop;
+    }
+    // Unknown platform — assume headless for safety
+    return true;
+}
+// =============================================================================
+// Browser launch detection
+// =============================================================================
+/**
+ * Returns true if the system has a browser launcher available.
+ *
+ * macOS: checks for `open` (always present).
+ * Linux: checks for `xdg-open` via `which`.
+ * Other: returns false.
+ */
+export function canLaunchBrowser() {
+    if (isHeadless())
+        return false;
+    try {
+        if (process.platform === "darwin") {
+            execSync("which open", { stdio: "pipe" });
+            return true;
+        }
+        if (process.platform === "linux") {
+            execSync("which xdg-open", { stdio: "pipe" });
+            return true;
+        }
+    }
+    catch {
+        // `which` returned non-zero — tool not found
+    }
+    return false;
+}
+// =============================================================================
+// CI environment detection
+// =============================================================================
+/**
+ * Returns true if the process is running in a known CI environment.
+ * Checks standard CI environment variables used by common CI platforms.
+ */
+export function isCIEnvironment() {
+    return !!(process.env["CI"] ||
+        process.env["GITHUB_ACTIONS"] ||
+        process.env["GITLAB_CI"] ||
+        process.env["CIRCLECI"] ||
+        process.env["TRAVIS"] ||
+        process.env["BUILDKITE"]);
+}
+// =============================================================================
+// Docker/container detection
+// =============================================================================
+/**
+ * Returns true if the process is running inside a Docker or containerd container.
+ * Checks /proc/1/cgroup for container markers and /.dockerenv existence.
+ */
+export function isDockerContainer() {
+    // Check for /.dockerenv (Docker-specific file)
+    if (existsSync("/.dockerenv"))
+        return true;
+    // Check /proc/1/cgroup for docker or containerd markers (Linux only)
+    if (process.platform === "linux") {
+        try {
+            const cgroup = readFileSync("/proc/1/cgroup", "utf8");
+            if (/docker|containerd/.test(cgroup))
+                return true;
+        }
+        catch {
+            // /proc/1/cgroup not readable — not a concern on non-Linux
+        }
+    }
+    return false;
+}
+// =============================================================================
+// SSH session detection
+// =============================================================================
+/**
+ * Returns true if the process is running inside an SSH session.
+ * Checks SSH_CONNECTION and SSH_CLIENT environment variables.
+ */
+export function isSSHSession() {
+    return !!(process.env["SSH_CONNECTION"] || process.env["SSH_CLIENT"]);
+}
+//# sourceMappingURL=platform.js.map

package/dist/platform/platform.js.map

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

package/dist/vault/types.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Auth Module — Shared Type Definitions
+ */
+export interface TokenValidationResult {
+    valid: boolean;
+    status: "valid" | "expiring_soon" | "expired";
+    expiresAt: Date | null;
+    remainingMs: number;
+    formattedRemaining: string;
+}
+export interface DeviceFlowConfig {
+    /** Base URL for the auth API (e.g. https://api.engram.ai) */
+    baseUrl: string;
+    /** OAuth client ID */
+    clientId?: string;
+    /** Poll timeout in seconds (default: 300) */
+    timeoutSeconds?: number;
+}
+export interface DeviceFlowResult {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: Date;
+}
+export type DeviceFlowErrorCode = "access_denied" | "expired_token" | "network_error" | "timeout" | "unknown";
+export declare class DeviceFlowError extends Error {
+    readonly code: DeviceFlowErrorCode;
+    constructor(code: DeviceFlowErrorCode, message: string);
+}
+export interface SpinnerHandle {
+    /** Update the spinner message */
+    update(message: string): void;
+    /** Stop the spinner and optionally print a final line */
+    stop(finalMessage?: string): void;
+}
+export interface CountdownHandle {
+    /** Cancel the countdown early */
+    cancel(): void;
+}
+export type VaultType = "keychain" | "windows" | "libsecret" | "gpg" | "env" | "unknown";
+export interface StoredCredentialMeta {
+    source: "device-flow" | "api-key" | "env";
+    storedAt: string;
+    refreshToken?: string;
+}
+/**
+ * Common interface implemented by all vault backends.
+ * Backends must implement store/retrieve/delete plus a static detect() method.
+ */
+export interface VaultBackend {
+    store(key: string, value: string): boolean;
+    retrieve(key: string): string | null;
+    delete(key: string): boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/vault/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/vault/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAMH,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,OAAO,GAAG,eAAe,GAAG,SAAS,CAAC;IAC9C,SAAS,EAAE,IAAI,GAAG,IAAI,CAAC;IACvB,WAAW,EAAE,MAAM,CAAC;IACpB,kBAAkB,EAAE,MAAM,CAAC;CAC5B;AAMD,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,OAAO,EAAE,MAAM,CAAC;IAChB,sBAAsB;IACtB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,6CAA6C;IAC7C,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,gBAAgB;IAC/B,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,IAAI,CAAC;CACjB;AAED,MAAM,MAAM,mBAAmB,GAC3B,eAAe,GACf,eAAe,GACf,eAAe,GACf,SAAS,GACT,SAAS,CAAC;AAEd,qBAAa,eAAgB,SAAQ,KAAK;aAEtB,IAAI,EAAE,mBAAmB;gBAAzB,IAAI,EAAE,mBAAmB,EACzC,OAAO,EAAE,MAAM;CAKlB;AAMD,MAAM,WAAW,aAAa;IAC5B,iCAAiC;IACjC,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,yDAAyD;IACzD,IAAI,CAAC,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACnC;AAED,MAAM,WAAW,eAAe;IAC9B,iCAAiC;IACjC,MAAM,IAAI,IAAI,CAAC;CAChB;AAMD,MAAM,MAAM,SAAS,GAAG,UAAU,GAAG,SAAS,GAAG,WAAW,GAAG,KAAK,GAAG,KAAK,GAAG,SAAS,CAAC;AAEzF,MAAM,WAAW,oBAAoB;IACnC,MAAM,EAAE,aAAa,GAAG,SAAS,GAAG,KAAK,CAAC;IAC1C,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3C,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IACrC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CAC9B"}

package/dist/vault/types.js

@@ -0,0 +1,12 @@
+/**
+ * Auth Module — Shared Type Definitions
+ */
+export class DeviceFlowError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.code = code;
+        this.name = "DeviceFlowError";
+    }
+}
+//# sourceMappingURL=types.js.map

package/dist/vault/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/vault/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAwCH,MAAM,OAAO,eAAgB,SAAQ,KAAK;IAEtB;IADlB,YACkB,IAAyB,EACzC,OAAe;QAEf,KAAK,CAAC,OAAO,CAAC,CAAC;QAHC,SAAI,GAAJ,IAAI,CAAqB;QAIzC,IAAI,CAAC,IAAI,GAAG,iBAAiB,CAAC;IAChC,CAAC;CACF"}

package/dist/vault/vault-env.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Auth Vault — Environment Variable Fallback Backend
+ *
+ * Last-resort vault backend that reads credentials from environment variables.
+ * Reads/writes nothing to disk. Suitable for CI/headless environments where no
+ * secure credential store (libsecret, GPG, macOS Keychain) is available.
+ *
+ * Implements the VaultBackend interface:
+ *   store(key, value): boolean  — always returns false (env vars are read-only)
+ *   retrieve(key): string|null  — returns ENGRAM_API_KEY for 'auth-token', null otherwise
+ *   delete(key): boolean        — always returns true (no-op; nothing to delete)
+ *   static detect(): boolean    — always returns true (last-resort fallback)
+ */
+import type { VaultBackend } from "./types.js";
+/**
+ * Environment-variable-only vault backend.
+ *
+ * This is the last-resort fallback when no OS-level secure credential store is
+ * available. It surfaces `ENGRAM_API_KEY` as the `auth-token` credential and
+ * rejects all write attempts with a warning on stderr.
+ */
+export declare class EnvVault implements VaultBackend {
+    /**
+     * Detection probe — always returns true so that EnvVault is always
+     * available as a last-resort fallback.
+     */
+    static detect(): boolean;
+    /**
+     * Attempt to store a credential.
+     *
+     * Environment variables cannot be written from within a process, so this
+     * always fails. A warning is emitted to stderr explaining how to configure
+     * persistent storage.
+     *
+     * @returns false — storage is never performed
+     */
+    store(_key: string, _value: string): boolean;
+    /**
+     * Retrieve a credential from the environment.
+     *
+     * - `'auth-token'`    -> `process.env["ENGRAM_API_KEY"] ?? null`
+     * - `'refresh-token'` -> `null` (refresh tokens are not available in env mode)
+     * - any other key     -> `null`
+     *
+     * @param key - Logical credential key
+     * @returns The credential value, or null if unavailable
+     */
+    retrieve(key: string): string | null;
+    /**
+     * Delete a credential.
+     *
+     * No-op: there is nothing stored in this backend to delete.
+     *
+     * @returns true — always succeeds (nothing to remove)
+     */
+    delete(_key: string): boolean;
+}
+//# sourceMappingURL=vault-env.d.ts.map

package/dist/vault/vault-env.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault-env.d.ts","sourceRoot":"","sources":["../../src/vault/vault-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAM/C;;;;;;GAMG;AACH,qBAAa,QAAS,YAAW,YAAY;IAC3C;;;OAGG;IACH,MAAM,CAAC,MAAM,IAAI,OAAO;IAIxB;;;;;;;;OAQG;IACH,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO;IAK5C;;;;;;;;;OASG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAOpC;;;;;;OAMG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;CAG9B"}

package/dist/vault/vault-env.js

@@ -0,0 +1,73 @@
+/**
+ * Auth Vault — Environment Variable Fallback Backend
+ *
+ * Last-resort vault backend that reads credentials from environment variables.
+ * Reads/writes nothing to disk. Suitable for CI/headless environments where no
+ * secure credential store (libsecret, GPG, macOS Keychain) is available.
+ *
+ * Implements the VaultBackend interface:
+ *   store(key, value): boolean  — always returns false (env vars are read-only)
+ *   retrieve(key): string|null  — returns ENGRAM_API_KEY for 'auth-token', null otherwise
+ *   delete(key): boolean        — always returns true (no-op; nothing to delete)
+ *   static detect(): boolean    — always returns true (last-resort fallback)
+ */
+import { AUTH_MESSAGES } from "../cli/messages.js";
+// =============================================================================
+// EnvVault implementation
+// =============================================================================
+/**
+ * Environment-variable-only vault backend.
+ *
+ * This is the last-resort fallback when no OS-level secure credential store is
+ * available. It surfaces `ENGRAM_API_KEY` as the `auth-token` credential and
+ * rejects all write attempts with a warning on stderr.
+ */
+export class EnvVault {
+    /**
+     * Detection probe — always returns true so that EnvVault is always
+     * available as a last-resort fallback.
+     */
+    static detect() {
+        return true;
+    }
+    /**
+     * Attempt to store a credential.
+     *
+     * Environment variables cannot be written from within a process, so this
+     * always fails. A warning is emitted to stderr explaining how to configure
+     * persistent storage.
+     *
+     * @returns false — storage is never performed
+     */
+    store(_key, _value) {
+        process.stderr.write(AUTH_MESSAGES.warning.envVaultNoStorage + "\n");
+        return false;
+    }
+    /**
+     * Retrieve a credential from the environment.
+     *
+     * - `'auth-token'`    -> `process.env["ENGRAM_API_KEY"] ?? null`
+     * - `'refresh-token'` -> `null` (refresh tokens are not available in env mode)
+     * - any other key     -> `null`
+     *
+     * @param key - Logical credential key
+     * @returns The credential value, or null if unavailable
+     */
+    retrieve(key) {
+        if (key === "auth-token") {
+            return process.env["ENGRAM_API_KEY"] ?? null;
+        }
+        return null;
+    }
+    /**
+     * Delete a credential.
+     *
+     * No-op: there is nothing stored in this backend to delete.
+     *
+     * @returns true — always succeeds (nothing to remove)
+     */
+    delete(_key) {
+        return true;
+    }
+}
+//# sourceMappingURL=vault-env.js.map

package/dist/vault/vault-env.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault-env.js","sourceRoot":"","sources":["../../src/vault/vault-env.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAGnD,gFAAgF;AAChF,0BAA0B;AAC1B,gFAAgF;AAEhF;;;;;;GAMG;AACH,MAAM,OAAO,QAAQ;IACnB;;;OAGG;IACH,MAAM,CAAC,MAAM;QACX,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;;;OAQG;IACH,KAAK,CAAC,IAAY,EAAE,MAAc;QAChC,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,aAAa,CAAC,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;QACrE,OAAO,KAAK,CAAC;IACf,CAAC;IAED;;;;;;;;;OASG;IACH,QAAQ,CAAC,GAAW;QAClB,IAAI,GAAG,KAAK,YAAY,EAAE,CAAC;YACzB,OAAO,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,IAAI,IAAI,CAAC;QAC/C,CAAC;QACD,OAAO,IAAI,CAAC;IACd,CAAC;IAED;;;;;;OAMG;IACH,MAAM,CAAC,IAAY;QACjB,OAAO,IAAI,CAAC;IACd,CAAC;CACF"}

package/dist/vault/vault-gpg.d.ts

@@ -0,0 +1,40 @@
+/**
+ * Auth Vault — GPG Backend
+ *
+ * Implements the VaultBackend interface using GPG-encrypted files stored at
+ * ~/.centient/auth/credentials-<key>.gpg. Falls back gracefully when GPG is
+ * not installed or no keys are configured.
+ *
+ * Error handling: all methods return false/null on failure — never throw.
+ */
+import type { VaultBackend } from "./types.js";
+/**
+ * Vault backend that stores credentials as GPG-encrypted files.
+ *
+ * Use `GpgVault.detect()` before instantiating to verify availability.
+ */
+export declare class GpgVault implements VaultBackend {
+    /**
+     * Returns true if GPG is installed and at least one public key is available.
+     */
+    static detect(): boolean;
+    /**
+     * Encrypts and stores `value` under `key` using the first available GPG key.
+     *
+     * @returns true on success, false if GPG is unavailable or encryption fails
+     */
+    store(key: string, value: string): boolean;
+    /**
+     * Decrypts and returns the stored credential for `key`.
+     *
+     * @returns the plaintext credential, or null if not found / decryption fails
+     */
+    retrieve(key: string): string | null;
+    /**
+     * Deletes the GPG-encrypted credential file for `key`.
+     *
+     * @returns true if the file was deleted or did not exist, false on unexpected error
+     */
+    delete(key: string): boolean;
+}
+//# sourceMappingURL=vault-gpg.d.ts.map

package/dist/vault/vault-gpg.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vault-gpg.d.ts","sourceRoot":"","sources":["../../src/vault/vault-gpg.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AA4D/C;;;;GAIG;AACH,qBAAa,QAAS,YAAW,YAAY;IAC3C;;OAEG;IACH,MAAM,CAAC,MAAM,IAAI,OAAO;IASxB;;;;OAIG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAuB1C;;;;OAIG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAkBpC;;;;OAIG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;CAkB7B"}

package/dist/vault/vault-gpg.js

@@ -0,0 +1,149 @@
+/**
+ * Auth Vault — GPG Backend
+ *
+ * Implements the VaultBackend interface using GPG-encrypted files stored at
+ * ~/.centient/auth/credentials-<key>.gpg. Falls back gracefully when GPG is
+ * not installed or no keys are configured.
+ *
+ * Error handling: all methods return false/null on failure — never throw.
+ */
+import { execFileSync } from "child_process";
+import { mkdirSync, unlinkSync } from "fs";
+import { homedir } from "os";
+import { join } from "path";
+import { isValidKey } from "./vault-utils.js";
+// =============================================================================
+// Constants
+// =============================================================================
+const AUTH_DIR = join(homedir(), ".centient", "auth");
+// =============================================================================
+// Helpers
+// =============================================================================
+/**
+ * Returns the path to the GPG-encrypted credential file for the given key.
+ */
+function credentialPath(key) {
+    return join(AUTH_DIR, `credentials-${key}.gpg`);
+}
+/**
+ * Ensures ~/.centient/auth/ exists.
+ */
+function ensureAuthDir() {
+    mkdirSync(AUTH_DIR, { recursive: true });
+}
+/**
+ * Parses `gpg --list-keys --with-colons` output and returns the fingerprint
+ * of the first available public key, or null if none found.
+ */
+function getFirstGpgKeyId() {
+    try {
+        const output = execFileSync("gpg", ["--list-keys", "--with-colons"], { encoding: "utf8", stdio: ["pipe", "pipe", "pipe"] });
+        const lines = output.split("\n");
+        for (const line of lines) {
+            if (line.startsWith("fpr:")) {
+                // fpr lines have the fingerprint in the 10th colon-delimited field (index 9)
+                const parts = line.split(":");
+                const fingerprint = parts[9];
+                if (!fingerprint || !/^[0-9A-Fa-f]{40}$/.test(fingerprint.trim()))
+                    continue;
+                if (fingerprint && fingerprint.trim().length > 0) {
+                    return fingerprint.trim();
+                }
+            }
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+// =============================================================================
+// GpgVault
+// =============================================================================
+/**
+ * Vault backend that stores credentials as GPG-encrypted files.
+ *
+ * Use `GpgVault.detect()` before instantiating to verify availability.
+ */
+export class GpgVault {
+    /**
+     * Returns true if GPG is installed and at least one public key is available.
+     */
+    static detect() {
+        try {
+            execFileSync("which", ["gpg"], { stdio: ["pipe", "pipe", "pipe"] });
+        }
+        catch {
+            return false;
+        }
+        return getFirstGpgKeyId() !== null;
+    }
+    /**
+     * Encrypts and stores `value` under `key` using the first available GPG key.
+     *
+     * @returns true on success, false if GPG is unavailable or encryption fails
+     */
+    store(key, value) {
+        if (!isValidKey(key))
+            return false;
+        try {
+            const keyId = getFirstGpgKeyId();
+            if (keyId === null)
+                return false;
+            ensureAuthDir();
+            const outPath = credentialPath(key);
+            execFileSync("gpg", ["--batch", "--yes", "-e", "-r", keyId, "-o", outPath], {
+                input: value,
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Decrypts and returns the stored credential for `key`.
+     *
+     * @returns the plaintext credential, or null if not found / decryption fails
+     */
+    retrieve(key) {
+        if (!isValidKey(key))
+            return null;
+        try {
+            const filePath = credentialPath(key);
+            const result = execFileSync("gpg", ["--batch", "--quiet", "-d", filePath], {
+                encoding: "utf8",
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+            return result ?? null;
+        }
+        catch {
+            return null;
+        }
+    }
+    /**
+     * Deletes the GPG-encrypted credential file for `key`.
+     *
+     * @returns true if the file was deleted or did not exist, false on unexpected error
+     */
+    delete(key) {
+        if (!isValidKey(key))
+            return false;
+        try {
+            unlinkSync(credentialPath(key));
+            return true;
+        }
+        catch (err) {
+            // ENOENT means file did not exist — treat as success
+            if (err !== null &&
+                typeof err === "object" &&
+                "code" in err &&
+                err.code === "ENOENT") {
+                return true;
+            }
+            return false;
+        }
+    }
+}
+//# sourceMappingURL=vault-gpg.js.map