@centient/secrets 0.9.0 → 0.11.0

package/dist/vault/vault.d.ts

@@ -8,32 +8,92 @@
  *   4. GpgVault       — GPG-encrypted files (Linux / WSL)
  *   5. EnvVault       — Environment variable fallback (always available)
  *
- * The active backend is selected once at module load by calling each backend's
+ * The default backend is selected lazily on first use by calling each backend's
  * static `detect()` method in order and choosing the first one that returns true.
+ * A successful selection is then reused for the lifetime of this module.
+ *
+ * **Explicit selection (ADR-004) sits in front of that cascade.** `secrets.backend`
+ * (or `CENTIENT_SECRETS_BACKEND`) names a backend directly and fails closed if it
+ * is unusable — it is never silently substituted. `OnePasswordVault` is reachable
+ * *only* this way: having `op` installed is not consent to route credentials into
+ * someone's 1Password vault.
  *
  * Session TTL: 4 hours from the last successful read/write.
  *
- * Error handling: all functions return null/false on failure — never throw.
+ * Error handling: a *storage* failure is reported as `null`/`false` — the
+ * backend contract is non-throwing. Three things do throw, because they are
+ * not storage outcomes: a policy `before` hook rejecting the operation
+ * (ADR-002 §1.0.0), a backend surfacing an unexpected transport failure from
+ * `retrieve`/`listKeys`, and a malformed credential key
+ * (`InvalidCredentialKeyError`, see the key-validation section below).
  */
-import type { VaultType } from "./types.js";
+import type { KeychainDeps } from "../crypto/darwin-keychain.js";
+import type { SecretState } from "../secret-state.js";
+import type { VaultBackend, VaultType } from "./types.js";
 /**
- * Returns true if the in-process session is still within the TTL window.
- * This does NOT validate the token itself — use validateToken() for that.
+ * The keychain service every credential VALUE lives under. Exported because
+ * the migration helper (`migrateLoginCredentialToSystem`) and operator
+ * tooling have to name the same service — a second literal somewhere else is
+ * how a migration silently moves nothing.
  */
-export declare function isSessionValid(): boolean;
+export declare const AUTH_KEYCHAIN_SERVICE = "centient-auth";
+/**
+ * Wraps the macOS Keychain helper functions as a VaultBackend.
+ *
+ * Every method routes through `crypto/darwin-keychain.ts` (#188), so credential
+ * values inherit explicit System-keychain reads in a sessionless context,
+ * `-U` replace-in-place writes and `-T /usr/bin/security` reader
+ * preauthorization — the same posture the KeyProvider layer gets for the vault
+ * master key.
+ *
+ * Only available on macOS (darwin).
+ */
+export declare class KeychainVault implements VaultBackend {
+    private readonly deps;
+    readonly name = "keychain";
+    /**
+     * @param deps - Injection seam for the `security` CLI and the
+     *   platform/environment that decide the read path. Omitted in production;
+     *   supplied by tests so the exact argv is assertable.
+     */
+    constructor(deps?: Partial<KeychainDeps>);
+    static detect(): boolean;
+    store(key: string, value: string): boolean;
+    retrieve(key: string): string | null;
+    delete(key: string): boolean;
+    listKeys(prefix?: string): Promise<string[]>;
+    /**
+     * The credential state probe: runs the SAME read {@link retrieve} would run
+     * in this context — same path, same explicit target — then discards the
+     * value and returns only the value-free {@link SecretState}.
+     *
+     * A metadata-only lookup would be cheaper and would leave the secret on
+     * disk, but it can only report presence: an item whose ACL does not
+     * preauthorize the reader, or that sits in a locked keychain, is present and
+     * unreadable, and calling that `found` hands a caller trusted state that is
+     * wrong in exactly the direction #188 exists to fix. `found` here means the
+     * reader will get bytes.
+     */
+    probe(key: string): SecretState;
+}
 /**
  * Returns the type identifier for the active vault backend.
  *
  * Useful for diagnostics and health checks to know which backend was selected
- * at startup (e.g. "keychain", "libsecret", "gpg", "env").
+ * on first use (e.g. "keychain", "libsecret", "gpg", "env").
  */
 export declare function getActiveVaultType(): VaultType;
+/** Legacy module-level shim over the default client. */
+export declare function isSessionValid(): boolean;
 /**
  * Store a credential in the active vault backend.
  *
- * @param key     - Logical key name (e.g. 'auth-token', 'refresh-token')
+ * @param key     - Logical key name (e.g. 'auth-token', 'refresh-token').
+ *                  Must match the key grammar — see "Key validation" above.
  * @param value   - The credential value to store
  * @returns true on success, false if the backend write fails
+ * @throws {InvalidCredentialKeyError} if `key` does not match the grammar.
+ *   Nothing is written and no backend is contacted.
  */
 export declare function storeCredential(key: string, value: string): Promise<boolean>;
 /**
@@ -41,6 +101,10 @@ export declare function storeCredential(key: string, value: string): Promise<boo
  *
  * @param key - Logical key name (e.g. 'auth-token')
  * @returns The stored value, or null if not found / backend unavailable
+ * @throws {InvalidCredentialKeyError} if `key` does not match the grammar.
+ *   Deliberately not `null`: "malformed" and "not stored" are different
+ *   answers, and returning the not-found shape for the first is the silent
+ *   degradation this path used to have.
  */
 export declare function getCredential(key: string): Promise<string | null>;
 /**
@@ -48,6 +112,9 @@ export declare function getCredential(key: string): Promise<string | null>;
  *
  * @param key - Logical key name (e.g. 'auth-token')
  * @returns true on success (including "already deleted"), false on unexpected error
+ * @throws {InvalidCredentialKeyError} if `key` does not match the grammar.
+ *   Not reported as an idempotent success: such a key was never storable, so
+ *   "already deleted" would be a claim the vault cannot make.
  */
 export declare function deleteCredential(key: string): Promise<boolean>;
 /**
@@ -64,7 +131,15 @@ export declare function deleteCredential(key: string): Promise<boolean>;
  * Note: credential keys must match `isValidKey` — lowercase alphanumeric
  * plus hyphen and dot, first and last character alphanumeric, <=64 chars.
  * Both `-` and `.` work as namespace separators; pick whichever convention
- * reads best.
+ * reads best. **This is enforced, not merely documented** (#168): every
+ * function on this path rejects a non-conforming key before dispatching.
+ *
+ * A `prefix` is checked against `isValidKeyPrefix` rather than `isValidKey`,
+ * so it may end on a separator — `"soma.anthropic."` is the intended way to
+ * scope an enumeration to a namespace, and is not itself a valid key.
+ *
+ * @throws {InvalidCredentialKeyError} if `prefix` could not be the leading
+ *   substring of any valid key.
  *
  * @example
  *   // Enumerate all soma-owned Anthropic credentials
@@ -75,4 +150,40 @@ export declare function deleteCredential(key: string): Promise<boolean>;
  *   }
  */
 export declare function listCredentials(prefix?: string): Promise<string[]>;
+/** A value-free answer about one credential in one backend. */
+export interface BackendStateProbe {
+    /** Always `"value"` — distinguishes this from the key-layer probe. */
+    layer: "value";
+    /** Which backend answered. */
+    backend: VaultType;
+    state: SecretState;
+}
+/**
+ * Probe one credential's state in a specific backend.
+ *
+ * Backends that implement `probe()` answer directly. For the rest this falls
+ * back to a `retrieve()`-based mapping — the value is discarded immediately
+ * and never returned — which yields `found`/`absent` honestly and `failed`
+ * when the backend threw. It never invents `locked`, because a backend that
+ * did not report one cannot be assumed to have one, and it never converts a
+ * throw into `absent`.
+ *
+ * Both paths answer readability, not mere presence: the fallback runs the real
+ * `retrieve()`, and an implementing backend is required to exercise the same
+ * access path it would for a read (see `VaultBackend.probe`). `found`
+ * therefore means the reader will get bytes.
+ *
+ * @throws {InvalidCredentialKeyError} if `key` does not match the grammar —
+ *   the same rule every other vault entry point enforces (#168). Policy hooks
+ *   are deliberately NOT run: a probe reads no value, so there is nothing for
+ *   an access-control hook to allow or deny.
+ */
+export declare function probeVaultBackendState(backend: VaultBackend, type: VaultType, key: string): Promise<BackendStateProbe>;
+/**
+ * Probe one credential's state in the backend this process actually uses.
+ *
+ * The value-layer half of the two-layer probe; see `probeKeyProviderState()`
+ * for the vault master key.
+ */
+export declare function probeBackendState(key: string): Promise<BackendStateProbe>;
 //# sourceMappingURL=vault.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../../src/vault/vault.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAYH,OAAO,KAAK,EAAgB,SAAS,EAAE,MAAM,YAAY,CAAC;AAiE1D;;;GAGG;AACH,wBAAgB,cAAc,IAAI,OAAO,CAGxC;AAiBD;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,SAAS,CAE9C;AAED;;;;;;GAMG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAoBlB;AAED;;;;;GAKG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAiCvE;AAED;;;;;GAKG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAmBpE;AAED;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAkCxE"}
+{"version":3,"file":"vault.d.ts","sourceRoot":"","sources":["../../src/vault/vault.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AASH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,oBAAoB,CAAC;AAMtD,OAAO,KAAK,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAe1D;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,kBAAkB,CAAC;AAMrD;;;;;;;;;;GAUG;AACH,qBAAa,aAAc,YAAW,YAAY;IAQpC,OAAO,CAAC,QAAQ,CAAC,IAAI;IAPjC,QAAQ,CAAC,IAAI,cAAc;IAE3B;;;;OAIG;gBAC0B,IAAI,GAAE,OAAO,CAAC,YAAY,CAAM;IAE7D,MAAM,CAAC,MAAM,IAAI,OAAO;IAIxB,KAAK,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO;IAI1C,QAAQ,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI;IAIpC,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAItB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC;IAIlD;;;;;;;;;;;OAWG;IACH,KAAK,CAAC,GAAG,EAAE,MAAM,GAAG,WAAW;CAGhC;AA6GD;;;;;GAKG;AACH,wBAAgB,kBAAkB,IAAI,SAAS,CAE9C;AAED,wDAAwD;AACxD,wBAAgB,cAAc,IAAI,OAAO,CAExC;AAED;;;;;;;;;GASG;AACH,wBAAsB,eAAe,CACnC,GAAG,EAAE,MAAM,EACX,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAElB;AAED;;;;;;;;;GASG;AACH,wBAAsB,aAAa,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAEvE;AAED;;;;;;;;GAQG;AACH,wBAAsB,gBAAgB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEpE;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAsB,eAAe,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAExE;AAuBD,+DAA+D;AAC/D,MAAM,WAAW,iBAAiB;IAChC,sEAAsE;IACtE,KAAK,EAAE,OAAO,CAAC;IACf,8BAA8B;IAC9B,OAAO,EAAE,SAAS,CAAC;IACnB,KAAK,EAAE,WAAW,CAAC;CACpB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAsB,sBAAsB,CAC1C,OAAO,EAAE,YAAY,EACrB,IAAI,EAAE,SAAS,EACf,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,iBAAiB,CAAC,CAiC5B;AAED;;;;;GAKG;AACH,wBAAsB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC,CAG/E"}

package/dist/vault/vault.js

@@ -8,56 +8,156 @@
  *   4. GpgVault       — GPG-encrypted files (Linux / WSL)
  *   5. EnvVault       — Environment variable fallback (always available)
  *
- * The active backend is selected once at module load by calling each backend's
+ * The default backend is selected lazily on first use by calling each backend's
  * static `detect()` method in order and choosing the first one that returns true.
+ * A successful selection is then reused for the lifetime of this module.
+ *
+ * **Explicit selection (ADR-004) sits in front of that cascade.** `secrets.backend`
+ * (or `CENTIENT_SECRETS_BACKEND`) names a backend directly and fails closed if it
+ * is unusable — it is never silently substituted. `OnePasswordVault` is reachable
+ * *only* this way: having `op` installed is not consent to route credentials into
+ * someone's 1Password vault.
  *
  * Session TTL: 4 hours from the last successful read/write.
  *
- * Error handling: all functions return null/false on failure — never throw.
+ * Error handling: a *storage* failure is reported as `null`/`false` — the
+ * backend contract is non-throwing. Three things do throw, because they are
+ * not storage outcomes: a policy `before` hook rejecting the operation
+ * (ADR-002 §1.0.0), a backend surfacing an unexpected transport failure from
+ * `retrieve`/`listKeys`, and a malformed credential key
+ * (`InvalidCredentialKeyError`, see the key-validation section below).
  */
 import { storeStringInKeychain, getStringFromKeychain, deleteFromKeychain, listAccountsInKeychain, } from "../crypto/vault-common.js";
+import { probeKeychainCredentialState } from "../crypto/darwin-keychain.js";
 import { WindowsVault } from "./vault-windows.js";
 import { LibsecretVault } from "./vault-libsecret.js";
 import { GpgVault } from "./vault-gpg.js";
 import { EnvVault } from "./vault-env.js";
-import { runBeforeHooks, runAfterHooks } from "./policy.js";
+import { OnePasswordVault } from "./vault-onepassword.js";
+import { loadConfig } from "../key-providers/resolve.js";
+import { defaultPolicyRunner } from "./policy.js";
+import { assertValidKey } from "./vault-utils.js";
+import { createSecretsClientWithPolicyRunner } from "../client.js";
 // =============================================================================
 // Constants
 // =============================================================================
-const AUTH_KEYCHAIN_SERVICE = "centient-auth";
-const SESSION_TTL_MS = 4 * 60 * 60 * 1000; // 4 hours
+/**
+ * The keychain service every credential VALUE lives under. Exported because
+ * the migration helper (`migrateLoginCredentialToSystem`) and operator
+ * tooling have to name the same service — a second literal somewhere else is
+ * how a migration silently moves nothing.
+ */
+export const AUTH_KEYCHAIN_SERVICE = "centient-auth";
 // =============================================================================
 // KeychainVault wrapper
 // =============================================================================
 /**
- * Wraps the existing macOS Keychain helper functions as a VaultBackend.
+ * Wraps the macOS Keychain helper functions as a VaultBackend.
+ *
+ * Every method routes through `crypto/darwin-keychain.ts` (#188), so credential
+ * values inherit explicit System-keychain reads in a sessionless context,
+ * `-U` replace-in-place writes and `-T /usr/bin/security` reader
+ * preauthorization — the same posture the KeyProvider layer gets for the vault
+ * master key.
+ *
  * Only available on macOS (darwin).
  */
-class KeychainVault {
+export class KeychainVault {
+    deps;
+    name = "keychain";
+    /**
+     * @param deps - Injection seam for the `security` CLI and the
+     *   platform/environment that decide the read path. Omitted in production;
+     *   supplied by tests so the exact argv is assertable.
+     */
+    constructor(deps = {}) {
+        this.deps = deps;
+    }
     static detect() {
         return process.platform === "darwin";
     }
     store(key, value) {
-        return storeStringInKeychain(AUTH_KEYCHAIN_SERVICE, key, value);
+        return storeStringInKeychain(AUTH_KEYCHAIN_SERVICE, key, value, this.deps);
     }
     retrieve(key) {
-        return getStringFromKeychain(AUTH_KEYCHAIN_SERVICE, key);
+        return getStringFromKeychain(AUTH_KEYCHAIN_SERVICE, key, this.deps);
     }
     delete(key) {
-        return deleteFromKeychain(AUTH_KEYCHAIN_SERVICE, key);
+        return deleteFromKeychain(AUTH_KEYCHAIN_SERVICE, key, this.deps);
     }
     async listKeys(prefix) {
-        return listAccountsInKeychain(AUTH_KEYCHAIN_SERVICE, prefix);
+        return listAccountsInKeychain(AUTH_KEYCHAIN_SERVICE, prefix, this.deps);
+    }
+    /**
+     * The credential state probe: runs the SAME read {@link retrieve} would run
+     * in this context — same path, same explicit target — then discards the
+     * value and returns only the value-free {@link SecretState}.
+     *
+     * A metadata-only lookup would be cheaper and would leave the secret on
+     * disk, but it can only report presence: an item whose ACL does not
+     * preauthorize the reader, or that sits in a locked keychain, is present and
+     * unreadable, and calling that `found` hands a caller trusted state that is
+     * wrong in exactly the direction #188 exists to fix. `found` here means the
+     * reader will get bytes.
+     */
+    probe(key) {
+        return probeKeychainCredentialState(AUTH_KEYCHAIN_SERVICE, key, this.deps);
     }
 }
 // =============================================================================
 // Cascade initialization
 // =============================================================================
 /**
- * Selects the first available vault backend in priority order:
+ * Read the explicitly-selected backend, env taking precedence over config —
+ * the same env > config order the key layer uses (ADR-001).
+ *
+ * Returns null when nothing is explicitly selected, which is the signal to run
+ * the auto-cascade unchanged.
+ */
+function resolveExplicitBackend() {
+    const envBackend = process.env.CENTIENT_SECRETS_BACKEND?.trim();
+    const config = loadConfig().secrets ?? {};
+    const selected = envBackend || config.backend;
+    if (!selected)
+        return null;
+    if (selected !== "1password") {
+        throw new Error(`Unknown secrets backend "${selected}". Supported explicit backends: 1password.`);
+    }
+    const envVault = process.env.CENTIENT_OP_VAULT?.trim();
+    const onePasswordBackend = {
+        ...config.onePasswordBackend,
+        ...(envVault ? { vault: envVault } : {}),
+    };
+    return { type: selected, onePasswordBackend };
+}
+/**
+ * Selects the credential-storage backend.
+ *
+ * **Explicit selection wins and fails closed** (ADR-004 §1): if config or env
+ * names a backend that then turns out to be unusable — no vault configured, `op`
+ * missing or unauthenticated — this throws rather than quietly continuing down
+ * the auto-cascade. Falling through would silently store credentials somewhere
+ * other than where the operator said, which is the whole class of surprise the
+ * opt-in model exists to prevent (P2).
+ *
+ * With no explicit selection, the historical auto-cascade runs unchanged:
  *   Keychain -> Windows -> Libsecret -> GPG -> Env
+ * 1Password is **never** auto-selected — `op` being installed is not consent to
+ * route credentials into it.
  */
 function initVaultBackend() {
+    const explicit = resolveExplicitBackend();
+    if (explicit !== null) {
+        // Constructor throws on a missing vault name — the fail-closed half of §1.
+        const backend = new OnePasswordVault(explicit.onePasswordBackend);
+        if (!OnePasswordVault.detect(true)) {
+            throw new Error('secrets backend "1password" was explicitly selected, but the 1Password CLI ' +
+                "(`op`) is unavailable or not authenticated. Install `op` and sign in, or set " +
+                "OP_SERVICE_ACCOUNT_TOKEN. Refusing to fall back to another backend — an " +
+                "explicit backend choice is never silently substituted.");
+        }
+        return { backend, type: "1password" };
+    }
     if (KeychainVault.detect())
         return { backend: new KeychainVault(), type: "keychain" };
     if (WindowsVault.detect())
@@ -68,31 +168,29 @@ function initVaultBackend() {
         return { backend: new GpgVault(), type: "gpg" };
     return { backend: new EnvVault(), type: "env" };
 }
-const { backend: activeBackend, type: activeVaultType } = initVaultBackend();
-// =============================================================================
-// Session State
-// =============================================================================
-/** Last successful vault access timestamp (epoch ms). */
-let lastAccessAt = null;
-/**
- * Returns true if the in-process session is still within the TTL window.
- * This does NOT validate the token itself — use validateToken() for that.
- */
-export function isSessionValid() {
-    if (lastAccessAt === null)
-        return false;
-    return Date.now() - lastAccessAt < SESSION_TTL_MS;
-}
-/** Update session timestamp on successful access. */
-function touchSession() {
-    lastAccessAt = Date.now();
+let defaultVault;
+function getDefaultVault() {
+    if (defaultVault !== undefined)
+        return defaultVault;
+    const { backend, type } = initVaultBackend();
+    const initialized = {
+        backend,
+        type,
+        client: createSecretsClientWithPolicyRunner({
+            provider: backend,
+            providerName: type,
+            policyRunner: defaultPolicyRunner,
+        }),
+    };
+    defaultVault = initialized;
+    return initialized;
 }
 // =============================================================================
 // Public API
 //
 // Policy-rejected operations are audited: when a `before` hook throws,
-// the rejection propagates to the caller AND the `after` hooks of the
-// already-entered policies fire with a `*_rejected` event (see
+// the rejection propagates to the caller AND the rejecting policy plus the
+// already-entered policies fire `after` with a `*_rejected` event (see
 // `runBeforeHooks` in policy.ts), so a denied operation is never
 // invisible to the audit trail. ADR-002 §1.0.0.
 // =============================================================================
@@ -100,107 +198,52 @@ function touchSession() {
  * Returns the type identifier for the active vault backend.
  *
  * Useful for diagnostics and health checks to know which backend was selected
- * at startup (e.g. "keychain", "libsecret", "gpg", "env").
+ * on first use (e.g. "keychain", "libsecret", "gpg", "env").
  */
 export function getActiveVaultType() {
-    return activeVaultType;
+    return getDefaultVault().type;
+}
+/** Legacy module-level shim over the default client. */
+export function isSessionValid() {
+    return getDefaultVault().client.isSessionValid();
 }
 /**
  * Store a credential in the active vault backend.
  *
- * @param key     - Logical key name (e.g. 'auth-token', 'refresh-token')
+ * @param key     - Logical key name (e.g. 'auth-token', 'refresh-token').
+ *                  Must match the key grammar — see "Key validation" above.
  * @param value   - The credential value to store
  * @returns true on success, false if the backend write fails
+ * @throws {InvalidCredentialKeyError} if `key` does not match the grammar.
+ *   Nothing is written and no backend is contacted.
  */
 export async function storeCredential(key, value) {
-    const start = performance.now();
-    await runBeforeHooks({ type: "write", key }, (error) => ({
-        type: "credential_write_rejected",
-        timestamp: new Date().toISOString(),
-        backend: activeVaultType,
-        key,
-        error,
-        durationMs: performance.now() - start,
-    }));
-    const success = activeBackend.store(key, value);
-    if (success)
-        touchSession();
-    runAfterHooks({
-        type: success ? "credential_written" : "credential_write_failed",
-        timestamp: new Date().toISOString(),
-        backend: activeVaultType,
-        key,
-        durationMs: performance.now() - start,
-    });
-    return success;
+    return getDefaultVault().client.storeCredential(key, value);
 }
 /**
  * Retrieve a credential from the active vault backend.
  *
  * @param key - Logical key name (e.g. 'auth-token')
  * @returns The stored value, or null if not found / backend unavailable
+ * @throws {InvalidCredentialKeyError} if `key` does not match the grammar.
+ *   Deliberately not `null`: "malformed" and "not stored" are different
+ *   answers, and returning the not-found shape for the first is the silent
+ *   degradation this path used to have.
  */
 export async function getCredential(key) {
-    const start = performance.now();
-    await runBeforeHooks({ type: "read", key }, (error) => ({
-        type: "credential_read_rejected",
-        timestamp: new Date().toISOString(),
-        backend: activeVaultType,
-        key,
-        error,
-        durationMs: performance.now() - start,
-    }));
-    let value;
-    try {
-        value = activeBackend.retrieve(key);
-    }
-    catch (err) {
-        runAfterHooks({
-            type: "credential_read_failed",
-            timestamp: new Date().toISOString(),
-            backend: activeVaultType,
-            key,
-            error: err instanceof Error ? err.message : String(err),
-            durationMs: performance.now() - start,
-        });
-        throw err;
-    }
-    if (value !== null)
-        touchSession();
-    runAfterHooks({
-        type: value !== null ? "credential_read" : "credential_read_missing",
-        timestamp: new Date().toISOString(),
-        backend: activeVaultType,
-        key,
-        durationMs: performance.now() - start,
-    });
-    return value;
+    return getDefaultVault().client.getCredential(key);
 }
 /**
  * Delete a credential from the active vault backend.
  *
  * @param key - Logical key name (e.g. 'auth-token')
  * @returns true on success (including "already deleted"), false on unexpected error
+ * @throws {InvalidCredentialKeyError} if `key` does not match the grammar.
+ *   Not reported as an idempotent success: such a key was never storable, so
+ *   "already deleted" would be a claim the vault cannot make.
  */
 export async function deleteCredential(key) {
-    const start = performance.now();
-    await runBeforeHooks({ type: "delete", key }, (error) => ({
-        type: "credential_delete_rejected",
-        timestamp: new Date().toISOString(),
-        backend: activeVaultType,
-        key,
-        error,
-        durationMs: performance.now() - start,
-    }));
-    const success = activeBackend.delete(key);
-    runAfterHooks({
-        type: success ? "credential_deleted" : "credential_delete_failed",
-        timestamp: new Date().toISOString(),
-        backend: activeVaultType,
-        key,
-        durationMs: performance.now() - start,
-    });
-    return success;
+    return getDefaultVault().client.deleteCredential(key);
 }
 /**
  * Enumerate credential keys in the active vault backend, optionally
@@ -216,7 +259,15 @@ export async function deleteCredential(key) {
  * Note: credential keys must match `isValidKey` — lowercase alphanumeric
  * plus hyphen and dot, first and last character alphanumeric, <=64 chars.
  * Both `-` and `.` work as namespace separators; pick whichever convention
- * reads best.
+ * reads best. **This is enforced, not merely documented** (#168): every
+ * function on this path rejects a non-conforming key before dispatching.
+ *
+ * A `prefix` is checked against `isValidKeyPrefix` rather than `isValidKey`,
+ * so it may end on a separator — `"soma.anthropic."` is the intended way to
+ * scope an enumeration to a namespace, and is not itself a valid key.
+ *
+ * @throws {InvalidCredentialKeyError} if `prefix` could not be the leading
+ *   substring of any valid key.
  *
  * @example
  *   // Enumerate all soma-owned Anthropic credentials
@@ -227,40 +278,72 @@ export async function deleteCredential(key) {
  *   }
  */
 export async function listCredentials(prefix) {
-    const start = performance.now();
-    await runBeforeHooks({ type: "enumerate", prefix }, (error) => ({
-        type: "credential_enumerate_rejected",
-        timestamp: new Date().toISOString(),
-        backend: activeVaultType,
-        prefix,
-        error,
-        durationMs: performance.now() - start,
-    }));
-    let keys;
+    return getDefaultVault().client.listCredentials(prefix);
+}
+/**
+ * Probe one credential's state in a specific backend.
+ *
+ * Backends that implement `probe()` answer directly. For the rest this falls
+ * back to a `retrieve()`-based mapping — the value is discarded immediately
+ * and never returned — which yields `found`/`absent` honestly and `failed`
+ * when the backend threw. It never invents `locked`, because a backend that
+ * did not report one cannot be assumed to have one, and it never converts a
+ * throw into `absent`.
+ *
+ * Both paths answer readability, not mere presence: the fallback runs the real
+ * `retrieve()`, and an implementing backend is required to exercise the same
+ * access path it would for a read (see `VaultBackend.probe`). `found`
+ * therefore means the reader will get bytes.
+ *
+ * @throws {InvalidCredentialKeyError} if `key` does not match the grammar —
+ *   the same rule every other vault entry point enforces (#168). Policy hooks
+ *   are deliberately NOT run: a probe reads no value, so there is nothing for
+ *   an access-control hook to allow or deny.
+ */
+export async function probeVaultBackendState(backend, type, key) {
+    assertValidKey(key, "read");
+    if (typeof backend.probe === "function") {
+        try {
+            return { layer: "value", backend: type, state: await backend.probe(key) };
+        }
+        catch (err) {
+            return {
+                layer: "value",
+                backend: type,
+                state: {
+                    kind: "failed",
+                    detail: err instanceof Error ? err.message : String(err),
+                },
+            };
+        }
+    }
     try {
-        keys = await activeBackend.listKeys(prefix);
+        const value = await backend.retrieve(key);
+        return {
+            layer: "value",
+            backend: type,
+            state: value !== null ? { kind: "found" } : { kind: "absent" },
+        };
     }
     catch (err) {
-        runAfterHooks({
-            type: "credential_enumerate_failed",
-            timestamp: new Date().toISOString(),
-            backend: activeVaultType,
-            prefix,
-            error: err instanceof Error ? err.message : String(err),
-            durationMs: performance.now() - start,
-        });
-        throw err;
+        return {
+            layer: "value",
+            backend: type,
+            state: {
+                kind: "failed",
+                detail: err instanceof Error ? err.message : String(err),
+            },
+        };
     }
-    if (keys.length > 0)
-        touchSession();
-    runAfterHooks({
-        type: "credential_enumerated",
-        timestamp: new Date().toISOString(),
-        backend: activeVaultType,
-        prefix,
-        keyCount: keys.length,
-        durationMs: performance.now() - start,
-    });
-    return keys;
+}
+/**
+ * Probe one credential's state in the backend this process actually uses.
+ *
+ * The value-layer half of the two-layer probe; see `probeKeyProviderState()`
+ * for the vault master key.
+ */
+export async function probeBackendState(key) {
+    const { backend, type } = getDefaultVault();
+    return probeVaultBackendState(backend, type, key);
 }
 //# sourceMappingURL=vault.js.map