@centient/secrets 0.9.0 → 0.11.0

package/dist/vault/vault-env.js

@@ -1,90 +1,169 @@
 /**
  * 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)
+ * Last-resort, read-only backend for CI and headless environments where no
+ * secure credential store is available. Every valid logical key has exactly
+ * one shell-safe environment-variable name; no credential values are written
+ * to disk.
  */
 import { AUTH_MESSAGES } from "../cli/messages.js";
-// =============================================================================
-// EnvVault implementation
-// =============================================================================
+import { assertValidKey, assertValidKeyPrefix, isValidKey, } from "./vault-utils.js";
+const AUTH_TOKEN_KEY = "auth-token";
+const AUTH_TOKEN_ENV_NAME = "ENGRAM_API_KEY";
+/** Prefix reserved for non-auth-token credential values in {@link EnvVault}. */
+export const ENV_VAULT_PREFIX = "CENTIENT_SECRET_";
+/**
+ * Encode a validated key into an uppercase, shell-safe, reversible suffix.
+ *
+ * `_` is forbidden by the credential-key grammar, so the ASCII escapes are
+ * unambiguous even when separators are adjacent: `-` becomes `_2D` and `.`
+ * becomes `_2E`.
+ */
+function encodeCredentialKey(key) {
+    let encoded = "";
+    for (const character of key) {
+        if (character === "-")
+            encoded += "_2D";
+        else if (character === ".")
+            encoded += "_2E";
+        else
+            encoded += character.toUpperCase();
+    }
+    return encoded;
+}
+/**
+ * Return the one environment-variable name assigned to a credential key.
+ *
+ * The historical `auth-token` mapping remains `ENGRAM_API_KEY`. Every other
+ * valid key uses {@link ENV_VAULT_PREFIX} plus the reversible encoding above.
+ *
+ * @throws {InvalidCredentialKeyError} when `key` violates the package-wide
+ * credential-key grammar.
+ */
+export function credentialKeyToEnvName(key) {
+    assertValidKey(key, "read");
+    if (key === AUTH_TOKEN_KEY)
+        return AUTH_TOKEN_ENV_NAME;
+    return `${ENV_VAULT_PREFIX}${encodeCredentialKey(key)}`;
+}
+/** Decode only canonical generic names. Malformed or aliased names are ignored. */
+function envNameToCredentialKey(envName) {
+    if (!envName.startsWith(ENV_VAULT_PREFIX))
+        return null;
+    const encoded = envName.slice(ENV_VAULT_PREFIX.length);
+    let key = "";
+    for (let index = 0; index < encoded.length; index += 1) {
+        const character = encoded[index];
+        if (/^[A-Z0-9]$/.test(character)) {
+            key += character.toLowerCase();
+            continue;
+        }
+        if (character !== "_")
+            return null;
+        const escape = encoded.slice(index + 1, index + 3);
+        if (escape === "2D")
+            key += "-";
+        else if (escape === "2E")
+            key += ".";
+        else
+            return null;
+        index += 2;
+    }
+    if (!isValidKey(key))
+        return null;
+    // This also excludes a generic alias for the legacy auth-token mapping.
+    return credentialKeyToEnvName(key) === envName ? key : null;
+}
 /**
  * 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.
+ * available. It is intentionally read-only and offers no encryption or
+ * process-isolation boundary.
  */
 export class EnvVault {
-    /**
-     * Detection probe — always returns true so that EnvVault is always
-     * available as a last-resort fallback.
-     */
+    name = "env";
+    env;
+    platform;
+    constructor(options = {}) {
+        this.env = options.env ?? process.env;
+        this.platform = options.platform ?? process.platform;
+    }
+    /** Always available as the cascade's terminal 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) {
+    /** Validate and look up one credential without trimming or copying it. */
+    lookup(key, operation) {
+        assertValidKey(key, operation);
+        const envName = credentialKeyToEnvName(key);
+        const value = this.env[envName];
+        if (value === undefined)
+            return { kind: "absent", envName };
+        if (value.length === 0)
+            return { kind: "empty", envName };
+        return { kind: "found", envName, value };
+    }
+    /** Environment variables cannot be mutated persistently from this process. */
+    store(key, _value) {
+        assertValidKey(key, "write");
         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
-     */
+    /** Return the configured value, or `null` when its canonical slot is absent/empty. */
     retrieve(key) {
-        if (key === "auth-token") {
-            return process.env["ENGRAM_API_KEY"] ?? null;
-        }
-        return null;
+        const lookup = this.lookup(key, "read");
+        return lookup.kind === "found" ? lookup.value : null;
     }
     /**
-     * Delete a credential.
-     *
-     * No-op: there is nothing stored in this backend to delete.
+     * Probe one credential without returning its value.
      *
-     * @returns true — always succeeds (nothing to remove)
+     * An unset canonical variable is confirmed absent. A defined-but-empty
+     * variable is a visible configuration failure, never a found credential.
      */
-    delete(_key) {
+    probe(key) {
+        const lookup = this.lookup(key, "read");
+        if (lookup.kind === "found")
+            return { kind: "found" };
+        if (lookup.kind === "absent")
+            return { kind: "absent" };
+        return {
+            kind: "failed",
+            detail: `environment variable "${lookup.envName}" is set but empty`,
+        };
+    }
+    /** No-op deletion for the read-only fallback, after contract validation. */
+    delete(key) {
+        assertValidKey(key, "delete");
         return true;
     }
-    /**
-     * Enumerate logical keys served by this backend.
-     *
-     * EnvVault only surfaces a single hardcoded mapping (`auth-token` ->
-     * `ENGRAM_API_KEY`), so enumeration returns `["auth-token"]` when the
-     * underlying env var is set, otherwise `[]`.
-     *
-     * There is no user-defined naming convention over `process.env`, so
-     * arbitrary prefixes that don't match `auth-token` always produce `[]`.
-     */
+    /** Enumerate defined canonical variable names without reading unrelated values. */
     async listKeys(prefix) {
-        if (process.env["ENGRAM_API_KEY"] === undefined)
-            return [];
-        if (prefix !== undefined && !"auth-token".startsWith(prefix))
-            return [];
-        return ["auth-token"];
+        if (prefix !== undefined)
+            assertValidKeyPrefix(prefix, "enumerate");
+        const keys = new Set();
+        for (const observedEnvName of Object.keys(this.env)) {
+            // Native Windows environment lookup is case-insensitive but preserves an
+            // existing variable's spelling during enumeration. Normalize only the
+            // comparison name so retrieve() and listKeys() answer for the same store;
+            // POSIX retains exact-case canonical-name enforcement.
+            const envName = this.platform === "win32" ? observedEnvName.toUpperCase() : observedEnvName;
+            if (envName === AUTH_TOKEN_ENV_NAME) {
+                if (this.env[observedEnvName] !== undefined)
+                    keys.add(AUTH_TOKEN_KEY);
+                continue;
+            }
+            if (!envName.startsWith(ENV_VAULT_PREFIX))
+                continue;
+            if (this.env[observedEnvName] === undefined)
+                continue;
+            const key = envNameToCredentialKey(envName);
+            if (key !== null)
+                keys.add(key);
+        }
+        return [...keys]
+            .filter((key) => prefix === undefined || key.startsWith(prefix))
+            .sort();
     }
 }
 //# sourceMappingURL=vault-env.js.map

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

@@ -1 +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;IAED;;;;;;;;;OASG;IACH,KAAK,CAAC,QAAQ,CAAC,MAAe;QAC5B,IAAI,OAAO,CAAC,GAAG,CAAC,gBAAgB,CAAC,KAAK,SAAS;YAAE,OAAO,EAAE,CAAC;QAC3D,IAAI,MAAM,KAAK,SAAS,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,MAAM,CAAC;YAAE,OAAO,EAAE,CAAC;QACxE,OAAO,CAAC,YAAY,CAAC,CAAC;IACxB,CAAC;CACF"}
+{"version":3,"file":"vault-env.js","sourceRoot":"","sources":["../../src/vault/vault-env.ts"],"names":[],"mappings":"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"}

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

@@ -5,7 +5,11 @@
  * ~/.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.
+ * Error handling: a storage failure returns false/null — this backend never
+ * throws for that. A credential key that violates the shared key grammar is
+ * NOT a storage failure and throws `InvalidCredentialKeyError` (#168): such a
+ * key is unaddressable here, and reporting it as a failed write or an absent
+ * credential would be indistinguishable from the ordinary miss.
  */
 import type { VaultBackend } from "./types.js";
 /**
@@ -14,6 +18,7 @@ import type { VaultBackend } from "./types.js";
  * Use `GpgVault.detect()` before instantiating to verify availability.
  */
 export declare class GpgVault implements VaultBackend {
+    readonly name = "gpg";
     /**
      * Returns true if GPG is installed and at least one public key is available.
      */

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

@@ -1 +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;IAmB5B;;;;;;;OAOG;IACG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CA0BnD"}
+{"version":3,"file":"vault-gpg.d.ts","sourceRoot":"","sources":["../../src/vault/vault-gpg.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAOH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AA4D/C;;;;GAIG;AACH,qBAAa,QAAS,YAAW,YAAY;IAC3C,QAAQ,CAAC,IAAI,SAAS;IAEtB;;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;IAmB5B;;;;;;;OAOG;IACG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;CA0BnD"}

package/dist/vault/vault-gpg.js

@@ -5,13 +5,17 @@
  * ~/.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.
+ * Error handling: a storage failure returns false/null — this backend never
+ * throws for that. A credential key that violates the shared key grammar is
+ * NOT a storage failure and throws `InvalidCredentialKeyError` (#168): such a
+ * key is unaddressable here, and reporting it as a failed write or an absent
+ * credential would be indistinguishable from the ordinary miss.
  */
 import { execFileSync } from "child_process";
 import { mkdirSync, readdirSync, unlinkSync } from "fs";
 import { homedir } from "os";
 import { join } from "path";
-import { isValidKey } from "./vault-utils.js";
+import { assertValidKey } from "./vault-utils.js";
 // =============================================================================
 // Constants
 // =============================================================================
@@ -66,6 +70,7 @@ function getFirstGpgKeyId() {
  * Use `GpgVault.detect()` before instantiating to verify availability.
  */
 export class GpgVault {
+    name = "gpg";
     /**
      * Returns true if GPG is installed and at least one public key is available.
      */
@@ -84,8 +89,7 @@ export class GpgVault {
      * @returns true on success, false if GPG is unavailable or encryption fails
      */
     store(key, value) {
-        if (!isValidKey(key))
-            return false;
+        assertValidKey(key, "write");
         try {
             const keyId = getFirstGpgKeyId();
             if (keyId === null)
@@ -108,8 +112,7 @@ export class GpgVault {
      * @returns the plaintext credential, or null if not found / decryption fails
      */
     retrieve(key) {
-        if (!isValidKey(key))
-            return null;
+        assertValidKey(key, "read");
         try {
             const filePath = credentialPath(key);
             const result = execFileSync("gpg", ["--batch", "--quiet", "-d", filePath], {
@@ -128,8 +131,7 @@ export class GpgVault {
      * @returns true if the file was deleted or did not exist, false on unexpected error
      */
     delete(key) {
-        if (!isValidKey(key))
-            return false;
+        assertValidKey(key, "delete");
         try {
             unlinkSync(credentialPath(key));
             return true;

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

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

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

@@ -6,7 +6,11 @@
  * stored under a fixed service attribute (`centient`) and a per-key
  * attribute (`key`).
  *
- * Error handling: all functions return null/false on failure — never throw.
+ * Error handling: a storage failure returns false/null — this backend never
+ * throws for that. A credential key that violates the shared key grammar is
+ * NOT a storage failure and throws `InvalidCredentialKeyError` (#168): such a
+ * key is unaddressable here, and reporting it as a failed write or an absent
+ * credential would be indistinguishable from the ordinary miss.
  */
 import type { VaultBackend } from "./types.js";
 /**
@@ -20,6 +24,7 @@ import type { VaultBackend } from "./types.js";
  *   }
  */
 export declare class LibsecretVault implements VaultBackend {
+    readonly name = "libsecret";
     /**
      * Returns true if `secret-tool` is available on this system.
      * Uses `which secret-tool` — returns false if not found or command fails.

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

@@ -1 +1 @@
-{"version":3,"file":"vault-libsecret.d.ts","sourceRoot":"","sources":["../../src/vault/vault-libsecret.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAsB/C;;;;;;;;;GASG;AACH,qBAAa,cAAe,YAAW,YAAY;IACjD;;;OAGG;IACH,MAAM,CAAC,MAAM,IAAI,OAAO;IAYxB;;;;;;OAMG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAiB1C;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAiBpC;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAmB5B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAelD;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,qBAAqB;IAa7B;;;;OAIG;YACW,eAAe;IAyD7B;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;CA2B9B"}
+{"version":3,"file":"vault-libsecret.d.ts","sourceRoot":"","sources":["../../src/vault/vault-libsecret.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAsB/C;;;;;;;;;GASG;AACH,qBAAa,cAAe,YAAW,YAAY;IACjD,QAAQ,CAAC,IAAI,eAAe;IAE5B;;;OAGG;IACH,MAAM,CAAC,MAAM,IAAI,OAAO;IAYxB;;;;;;OAMG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAkB1C;;;;;OAKG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAkBpC;;;;;OAKG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAoB5B;;;;;;;;;;;;;;;;;;;;;;;OAuBG;IACG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAelD;;;;;;;;;;;;OAYG;IACH,OAAO,CAAC,qBAAqB;IAa7B;;;;OAIG;YACW,eAAe;IAyD7B;;;;;OAKG;IACH,OAAO,CAAC,qBAAqB;CA4B9B"}

package/dist/vault/vault-libsecret.js

@@ -6,10 +6,14 @@
  * stored under a fixed service attribute (`centient`) and a per-key
  * attribute (`key`).
  *
- * Error handling: all functions return null/false on failure — never throw.
+ * Error handling: a storage failure returns false/null — this backend never
+ * throws for that. A credential key that violates the shared key grammar is
+ * NOT a storage failure and throws `InvalidCredentialKeyError` (#168): such a
+ * key is unaddressable here, and reporting it as a failed write or an absent
+ * credential would be indistinguishable from the ordinary miss.
  */
-import { execSync } from "child_process";
-import { isValidKey } from "./vault-utils.js";
+import { execFileSync } from "child_process";
+import { assertValidKey } from "./vault-utils.js";
 // =============================================================================
 // Constants
 // =============================================================================
@@ -36,13 +40,14 @@ let dbusFallbackWarned = false;
  *   }
  */
 export class LibsecretVault {
+    name = "libsecret";
     /**
      * Returns true if `secret-tool` is available on this system.
      * Uses `which secret-tool` — returns false if not found or command fails.
      */
     static detect() {
         try {
-            execSync("which secret-tool", {
+            execFileSync("which", ["secret-tool"], {
                 encoding: "utf8",
                 stdio: ["pipe", "pipe", "pipe"],
             });
@@ -60,10 +65,9 @@ export class LibsecretVault {
      * @returns true on success, false if the write fails
      */
     store(key, value) {
-        if (!isValidKey(key))
-            return false;
+        assertValidKey(key, "write");
         try {
-            execSync(`secret-tool store --label "${LABEL}" service ${SERVICE_ATTR} key "${key}"`, {
+            execFileSync("secret-tool", ["store", "--label", LABEL, "service", SERVICE_ATTR, "key", key], {
                 encoding: "utf8",
                 stdio: ["pipe", "pipe", "pipe"],
                 input: value,
@@ -81,10 +85,9 @@ export class LibsecretVault {
      * @returns The stored value, or null if not found / lookup fails
      */
     retrieve(key) {
-        if (!isValidKey(key))
-            return null;
+        assertValidKey(key, "read");
         try {
-            const result = execSync(`secret-tool lookup service ${SERVICE_ATTR} key "${key}"`, {
+            const result = execFileSync("secret-tool", ["lookup", "service", SERVICE_ATTR, "key", key], {
                 encoding: "utf8",
                 stdio: ["pipe", "pipe", "pipe"],
             });
@@ -102,10 +105,9 @@ export class LibsecretVault {
      * @returns true on success (including "already deleted"), false on unexpected error
      */
     delete(key) {
-        if (!isValidKey(key))
-            return false;
+        assertValidKey(key, "delete");
         try {
-            execSync(`secret-tool clear service ${SERVICE_ATTR} key "${key}"`, {
+            execFileSync("secret-tool", ["clear", "service", SERVICE_ATTR, "key", key], {
                 encoding: "utf8",
                 stdio: ["pipe", "pipe", "pipe"],
             });
@@ -238,7 +240,7 @@ export class LibsecretVault {
     listKeysViaSecretTool(prefix) {
         let output;
         try {
-            output = execSync(`secret-tool search --all service ${SERVICE_ATTR}`, {
+            output = execFileSync("secret-tool", ["search", "--all", "service", SERVICE_ATTR], {
                 encoding: "utf8",
                 stdio: ["pipe", "pipe", "pipe"],
             });

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

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

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

@@ -0,0 +1,119 @@
+/**
+ * Vault backend — 1Password credential storage (ADR-004).
+ *
+ * Stores credential **values** in a dedicated 1Password vault via the `op` CLI.
+ * This is a different layer from ADR-001's `OnePasswordProvider`, which stores
+ * the vault *encryption key*: an operator may keep the key in the Keychain and
+ * the credentials in 1Password, or the reverse. The two carry separate config
+ * blocks for exactly that reason (ADR-004 §1).
+ *
+ * ## Two properties this backend exists to hold
+ *
+ * 1. **Never auto-selected.** `op` being installed must not silently route
+ *    credentials into someone's personal vault — surprising secret placement is
+ *    a security defect (P15/P2). Selection is explicit opt-in, and
+ *    {@link OnePasswordVault.detect} refuses without it.
+ * 2. **Secret values never touch argv.** Writes build the item JSON in-process
+ *    and pipe it to `op item create -`, so nothing readable in `ps` ever carries
+ *    a secret. This is the pattern issue #102 retrofitted to the key provider,
+ *    which now writes through the same `op item create -` stdin seam. Its
+ *    replace ordering differs — create first, delete the superseded item last —
+ *    because losing the vault *master key* between two calls would be
+ *    unrecoverable, where a credential value can be re-fetched from its source.
+ */
+import type { VaultBackend } from "./types.js";
+import type { OnePasswordBackendConfig } from "../key-providers/types.js";
+/** Default tag applied to every item this backend writes. */
+export declare const DEFAULT_OP_TAG = "centient";
+/**
+ * List-cache TTL, mirroring `KEYCHAIN_LIST_CACHE_TTL_MS` (ADR-004 §8).
+ *
+ * Only key **names** are cached, never values: a cached value would both extend
+ * how long plaintext sits in the heap and serve a rotated or revoked credential
+ * until expiry. 1Password stays the source of truth for values.
+ */
+export declare const OP_LIST_CACHE_TTL_MS = 5000;
+/** Options for {@link OnePasswordVault}. */
+export interface OnePasswordVaultOptions extends OnePasswordBackendConfig {
+    /**
+     * Injectable clock for the list cache, so tests can drive expiry without
+     * sleeping. Defaults to `Date.now`.
+     */
+    now?: () => number;
+}
+export declare class OnePasswordVault implements VaultBackend {
+    readonly name = "1password";
+    private readonly vault;
+    private readonly tag;
+    private readonly now;
+    private listCache;
+    private warned;
+    /**
+     * @param config - must carry a `vault`; there is deliberately no default
+     *   (ADR-004 §1 — guessing a vault name risks writing credentials somewhere
+     *   the operator did not intend).
+     * @throws {Error} when `vault` is missing or blank.
+     */
+    constructor(config: OnePasswordVaultOptions);
+    /**
+     * Whether this backend may be used.
+     *
+     * Requires **both** an explicit opt-in and a usable `op`. The opt-in half is
+     * what keeps 1Password out of the auto-cascade: without it this returns false
+     * even on a machine where `op` is installed and signed in.
+     *
+     * @param optedIn - true when config or env explicitly selected this backend.
+     */
+    static detect(optedIn: boolean): boolean;
+    /**
+     * Write a credential. The value travels on stdin and never appears in argv.
+     *
+     * Update is modeled as replace (delete-then-create) so create and update share
+     * one argv-safe path rather than needing a separate `op item edit` form.
+     */
+    store(key: string, value: string): boolean;
+    /**
+     * Read a credential value. Returns null when absent or on failure.
+     *
+     * @throws {InvalidCredentialKeyError} for a key this backend could never
+     *   have written — building an `op://` reference from it is exactly the
+     *   misparse the key grammar exists to prevent, and `null` would report the
+     *   impossible key as a merely absent one.
+     */
+    retrieve(key: string): string | null;
+    /**
+     * Delete a credential. Idempotent — a missing item is success.
+     *
+     * @throws {InvalidCredentialKeyError} — deliberately NOT folded into the
+     *   idempotent-success path. "Missing" and "impossible" are different
+     *   answers: such a key was never storable here, so reporting success would
+     *   assert something about a key this backend does not accept.
+     */
+    delete(key: string): boolean;
+    /**
+     * Enumerate credential keys, optionally prefix-filtered.
+     *
+     * Per the {@link VaultBackend} contract this returns `[]` for a genuinely
+     * empty vault but **throws** on a transient failure, so a caller can tell
+     * "nothing stored" from "1Password did not answer" and retry the latter.
+     * The `--tags` filter keeps unrelated items in a shared vault out of the
+     * result; no secret values appear in `op item list` output.
+     */
+    listKeys(prefix?: string): Promise<string[]>;
+    private fetchKeys;
+    private deleteItem;
+    private readListCache;
+    private invalidateListCache;
+    /**
+     * Surface an unexpected `op` failure once per instance (ADR-004 §7, the
+     * libsecret lesson from #121).
+     *
+     * A not-found is normal and stays quiet. Anything else means we are
+     * authenticated but the call still failed — a misconfiguration the operator
+     * needs to see, since the non-throwing backend contract would otherwise
+     * swallow it entirely. Once per instance keeps a hot loop from flooding
+     * stderr while still making the first occurrence visible.
+     */
+    private warnOnce;
+}
+//# sourceMappingURL=vault-onepassword.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"vault-onepassword.d.ts","sourceRoot":"","sources":["../../src/vault/vault-onepassword.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,OAAO,KAAK,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAa1E,6DAA6D;AAC7D,eAAO,MAAM,cAAc,aAAa,CAAC;AAKzC;;;;;;GAMG;AACH,eAAO,MAAM,oBAAoB,OAAQ,CAAC;AAM1C,4CAA4C;AAC5C,MAAM,WAAW,uBAAwB,SAAQ,wBAAwB;IACvE;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB;AAMD,qBAAa,gBAAiB,YAAW,YAAY;IACnD,QAAQ,CAAC,IAAI,eAAe;IAE5B,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAS;IAC/B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAS;IAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAe;IAEnC,OAAO,CAAC,SAAS,CAAsD;IACvE,OAAO,CAAC,MAAM,CAAS;IAEvB;;;;;OAKG;gBACS,MAAM,EAAE,uBAAuB;IAa3C;;;;;;;;OAQG;IACH,MAAM,CAAC,MAAM,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO;IAKxC;;;;;OAKG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IA2B1C;;;;;;;OAOG;IACH,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAepC;;;;;;;OAOG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAa5B;;;;;;;;OAQG;IACG,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAgBlD,OAAO,CAAC,SAAS;IAsDjB,OAAO,CAAC,UAAU;IAYlB,OAAO,CAAC,aAAa;IASrB,OAAO,CAAC,mBAAmB;IAI3B;;;;;;;;;OASG;IACH,OAAO,CAAC,QAAQ;CAWjB"}