@centient/secrets 0.9.0 → 0.11.0

package/dist/vault/policy.js

@@ -1,20 +1,19 @@
 /**
  * SecretsPolicy — Middleware layer for credential operations.
  *
- * Policies are cross-cutting concerns (audit, rate limiting, access
- * control, attestation) applied to every credential operation via
- * `setSecretsPolicies([...])`. In 0.5.0 only the audit policy is
- * shipped; the API shape is designed to grow into the full policy
- * stack described in ADR-002.
+ * Policies are cross-cutting concerns (audit, rate limiting, access control,
+ * attestation) applied to every credential operation. Explicit clients own an
+ * isolated stack supplied to `createSecretsClient`; `setSecretsPolicies`
+ * remains as the deprecated configuration path for the module-level shims and
+ * SessionVault. The API shape is designed for the full stack in ADR-002.
  *
  * Execution model:
  *   1. `before` hooks run top-to-bottom. If one throws, the operation
  *      is aborted and the error propagates to the caller — but the
- *      `after` hooks of already-entered policies (those whose `before`
- *      hook already completed) still fire with a `*_rejected` event, so
+ *      rejecting policy and already-entered policies still fire their
+ *      `after` hooks with a `*_rejected` event, so
  *      a policy-denied operation is audited rather than vanishing
- *      (ADR-002 §1.0.0). The rejecting policy's own `after` hook does
- *      not fire — its `before` hook did not complete.
+ *      (issue #98). Policies not yet reached do not fire.
  *   2. The backend operation executes.
  *   3. `after` hooks run bottom-to-top with a structured event
  *      describing the outcome. Exceptions in `after` hooks are
@@ -44,59 +43,57 @@ export function rejectedEventType(op) {
         }
     }
 }
-// =============================================================================
-// Policy registry
-// =============================================================================
-let activePolicies = [];
-let afterWarningEmitted = false;
-export function setSecretsPolicies(policies) {
-    activePolicies = [...policies];
-    afterWarningEmitted = false;
-}
-export function getActivePolicies() {
-    return activePolicies;
-}
-/**
- * Run `before` hooks top-to-bottom. If a hook throws, the operation is
- * rejected: the `after` hooks of the already-entered policies (indices
- * `0..i-1`, bottom-to-top) fire with the event built by
- * `makeRejectionEvent` so the denied operation is still audited, then the
- * original error is re-thrown to abort the operation. The rejecting
- * policy's own `after` hook is intentionally skipped — its `before` hook
- * did not complete, so the policy was not fully entered. See ADR-002
- * §1.0.0.
- */
-export async function runBeforeHooks(op, makeRejectionEvent) {
-    for (let i = 0; i < activePolicies.length; i++) {
-        const policy = activePolicies[i];
-        if (!policy.before)
-            continue;
-        try {
-            await policy.before(op);
+function snapshotPolicies(configured) {
+    const snapshot = configured.map((policy) => {
+        // Capture the complete callable shape, not just the containing array.
+        // Otherwise a caller could add or replace a before hook after ordering
+        // validation and make a rejection observer silently miss denials.
+        const name = policy.name;
+        const observesPolicyRejections = policy.observesPolicyRejections;
+        const configuredBefore = policy.before;
+        const configuredAfter = policy.after;
+        // ADR-002 permits a policy object to retain mutable internal state. Bind
+        // the captured hooks to that original receiver while freezing only the
+        // validated public wrapper and its hook identities.
+        const before = configuredBefore?.bind(policy);
+        const after = configuredAfter?.bind(policy);
+        return Object.freeze({
+            name,
+            ...(observesPolicyRejections === true
+                ? { observesPolicyRejections: true }
+                : {}),
+            ...(before !== undefined ? { before } : {}),
+            ...(after !== undefined ? { after } : {}),
+        });
+    });
+    let precedingBeforePolicy;
+    for (const policy of snapshot) {
+        if (policy.observesPolicyRejections === true &&
+            precedingBeforePolicy !== undefined) {
+            throw new TypeError(`policy "${policy.name}" observes policy rejections and must precede ` +
+                `policy "${precedingBeforePolicy.name}" (and every other policy with a before hook)`);
         }
-        catch (err) {
-            const msg = err instanceof Error ? err.message : String(err);
-            runAfterHooksForRange(makeRejectionEvent(msg), i - 1);
-            throw err;
+        if (policy.before !== undefined && precedingBeforePolicy === undefined) {
+            precedingBeforePolicy = policy;
         }
     }
-}
-export function runAfterHooks(event) {
-    runAfterHooksForRange(event, activePolicies.length - 1);
+    // The registry's public inspection API returns this same value. Freeze the
+    // array so a cast to a mutable type cannot bypass replacement validation.
+    return Object.freeze(snapshot);
 }
 /**
- * Run `after` hooks for policies `fromIndex..0` (bottom-to-top). A
- * negative `fromIndex` is a no-op (no policy was entered). Synchronous
- * hook exceptions are swallowed best-effort with a one-time stderr
- * warning — audit-infrastructure failures must never break credential
- * operations. `after` hooks are synchronous by contract (see
- * `SecretsPolicy.after`); a hook that returns a rejected `Promise` is
- * not awaited here, so it would surface as an unhandled rejection.
+ * Build an isolated policy runner. Its input is snapshotted immediately, and
+ * every operation captures the current immutable frame so replacement cannot
+ * splice two different stacks across an await boundary.
  */
-function runAfterHooksForRange(event, fromIndex) {
-    for (let i = fromIndex; i >= 0; i--) {
-        const policy = activePolicies[i];
-        if (policy.after) {
+export function createPolicyRunner(initialPolicies = []) {
+    let policies = snapshotPolicies(initialPolicies);
+    let afterWarningEmitted = false;
+    const runAfterForFrame = (event, frame) => {
+        for (let i = frame.length - 1; i >= 0; i--) {
+            const policy = frame[i];
+            if (!policy.after)
+                continue;
             try {
                 policy.after(event);
             }
@@ -108,20 +105,65 @@ function runAfterHooksForRange(event, fromIndex) {
                 }
             }
         }
-    }
-}
-export function auditTrail(opts) {
-    const includeReads = opts.includeReads ?? true;
+    };
     return {
-        name: "auditTrail",
-        after(event) {
-            if (!includeReads &&
-                (event.type === "credential_read" ||
-                    event.type === "credential_read_missing")) {
-                return;
+        async runBefore(op, makeRejectionEvent) {
+            const frame = policies;
+            for (let i = 0; i < frame.length; i++) {
+                const policy = frame[i];
+                try {
+                    await policy.before?.(op);
+                }
+                catch (err) {
+                    const msg = err instanceof Error ? err.message : String(err);
+                    // Issue #98 is authoritative: the rejecting policy is part of the
+                    // unwind, followed by already-entered outer policies.
+                    runAfterForFrame(makeRejectionEvent(msg), frame.slice(0, i + 1));
+                    throw err;
+                }
             }
-            opts.sink(event);
+            return frame;
+        },
+        runAfter(event, frame = policies) {
+            runAfterForFrame(event, frame);
+        },
+        getPolicies() {
+            return policies;
+        },
+        replacePolicies(nextPolicies) {
+            policies = snapshotPolicies(nextPolicies);
+            afterWarningEmitted = false;
         },
     };
 }
+/** Global runner retained only for legacy module APIs and SessionVault. */
+export const defaultPolicyRunner = createPolicyRunner();
+/**
+ * @deprecated Configure policies on an isolated client created with
+ * `createSecretsClient`. This setter remains for module-level shims and
+ * SessionVault compatibility through the 1.x deprecation window.
+ */
+export function setSecretsPolicies(policies) {
+    defaultPolicyRunner.replacePolicies(policies);
+}
+/** @deprecated Inspect the policy list owned by the legacy default client. */
+export function getActivePolicies() {
+    return defaultPolicyRunner.getPolicies();
+}
+/**
+ * Run `before` hooks top-to-bottom. If a hook throws, the operation is
+ * rejected: the rejecting policy and already-entered policies (indices
+ * `0..i`, bottom-to-top) fire `after` with the event built by
+ * `makeRejectionEvent` so the denied operation is still audited, then the
+ * original error is re-thrown to abort the operation. This follows issue
+ * #98's acceptance contract; policies after the rejector are never entered.
+ */
+export async function runBeforeHooks(op, makeRejectionEvent) {
+    return defaultPolicyRunner.runBefore(op, makeRejectionEvent);
+}
+export function runAfterHooks(event, frame) {
+    defaultPolicyRunner.runAfter(event, frame);
+}
+// Compatibility re-export: the built-in now lives with the other policies.
+export { auditTrail } from "../policies/audit-trail.js";
 //# sourceMappingURL=policy.js.map

package/dist/vault/policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/vault/policy.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/vault/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;GAqBG;AAsDH;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,EAAoB;IACpD,QAAQ,EAAE,CAAC,IAAI,EAAE,CAAC;QAChB,KAAK,MAAM;YACT,OAAO,0BAA0B,CAAC;QACpC,KAAK,OAAO;YACV,OAAO,2BAA2B,CAAC;QACrC,KAAK,QAAQ;YACX,OAAO,4BAA4B,CAAC;QACtC,KAAK,WAAW;YACd,OAAO,+BAA+B,CAAC;QACzC,OAAO,CAAC,CAAC,CAAC;YACR,mEAAmE;YACnE,yDAAyD;YACzD,MAAM,WAAW,GAAU,EAAE,CAAC,IAAI,CAAC;YACnC,MAAM,IAAI,KAAK,CAAC,6BAA6B,MAAM,CAAC,WAAW,CAAC,EAAE,CAAC,CAAC;QACtE,CAAC;IACH,CAAC;AACH,CAAC;AA4CD,SAAS,gBAAgB,CACvB,UAAoC;IAEpC,MAAM,QAAQ,GAAG,UAAU,CAAC,GAAG,CAAC,CAAC,MAAM,EAAiB,EAAE;QACxD,sEAAsE;QACtE,uEAAuE;QACvE,kEAAkE;QAClE,MAAM,IAAI,GAAG,MAAM,CAAC,IAAI,CAAC;QACzB,MAAM,wBAAwB,GAAG,MAAM,CAAC,wBAAwB,CAAC;QACjE,MAAM,gBAAgB,GAAG,MAAM,CAAC,MAAM,CAAC;QACvC,MAAM,eAAe,GAAG,MAAM,CAAC,KAAK,CAAC;QACrC,yEAAyE;QACzE,uEAAuE;QACvE,oDAAoD;QACpD,MAAM,MAAM,GAAG,gBAAgB,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAC9C,MAAM,KAAK,GAAG,eAAe,EAAE,IAAI,CAAC,MAAM,CAAC,CAAC;QAE5C,OAAO,MAAM,CAAC,MAAM,CAAC;YACnB,IAAI;YACJ,GAAG,CAAC,wBAAwB,KAAK,IAAI;gBACnC,CAAC,CAAC,EAAE,wBAAwB,EAAE,IAAa,EAAE;gBAC7C,CAAC,CAAC,EAAE,CAAC;YACP,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;YAC3C,GAAG,CAAC,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;SAC1C,CAAC,CAAC;IACL,CAAC,CAAC,CAAC;IACH,IAAI,qBAAgD,CAAC;IAErD,KAAK,MAAM,MAAM,IAAI,QAAQ,EAAE,CAAC;QAC9B,IACE,MAAM,CAAC,wBAAwB,KAAK,IAAI;YACxC,qBAAqB,KAAK,SAAS,EACnC,CAAC;YACD,MAAM,IAAI,SAAS,CACjB,WAAW,MAAM,CAAC,IAAI,gDAAgD;gBACpE,WAAW,qBAAqB,CAAC,IAAI,+CAA+C,CACvF,CAAC;QACJ,CAAC;QACD,IAAI,MAAM,CAAC,MAAM,KAAK,SAAS,IAAI,qBAAqB,KAAK,SAAS,EAAE,CAAC;YACvE,qBAAqB,GAAG,MAAM,CAAC;QACjC,CAAC;IACH,CAAC;IAED,2EAA2E;IAC3E,0EAA0E;IAC1E,OAAO,MAAM,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC;AACjC,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAChC,kBAA4C,EAAE;IAE9C,IAAI,QAAQ,GAA6B,gBAAgB,CAAC,eAAe,CAAC,CAAC;IAC3E,IAAI,mBAAmB,GAAG,KAAK,CAAC;IAEhC,MAAM,gBAAgB,GAAG,CAAC,KAAmB,EAAE,KAAuB,EAAQ,EAAE;QAC9E,KAAK,IAAI,CAAC,GAAG,KAAK,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;YAC3C,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;YACzB,IAAI,CAAC,MAAM,CAAC,KAAK;gBAAE,SAAS;YAC5B,IAAI,CAAC;gBACH,MAAM,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;YACtB,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,IAAI,CAAC,mBAAmB,EAAE,CAAC;oBACzB,mBAAmB,GAAG,IAAI,CAAC;oBAC3B,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;oBAC7D,OAAO,CAAC,MAAM,CAAC,KAAK,CAClB,qBAAqB,MAAM,CAAC,IAAI,mCAAmC,GAAG,IAAI,CAC3E,CAAC;gBACJ,CAAC;YACH,CAAC;QACH,CAAC;IACH,CAAC,CAAC;IAEF,OAAO;QACL,KAAK,CAAC,SAAS,CAAC,EAAE,EAAE,kBAAkB;YACpC,MAAM,KAAK,GAAG,QAAQ,CAAC;YACvB,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;gBACtC,MAAM,MAAM,GAAG,KAAK,CAAC,CAAC,CAAE,CAAC;gBACzB,IAAI,CAAC;oBACH,MAAM,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,CAAC,CAAC;gBAC5B,CAAC;gBAAC,OAAO,GAAG,EAAE,CAAC;oBACb,MAAM,GAAG,GAAG,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;oBAC7D,kEAAkE;oBAClE,sDAAsD;oBACtD,gBAAgB,CAAC,kBAAkB,CAAC,GAAG,CAAC,EAAE,KAAK,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC;oBACjE,MAAM,GAAG,CAAC;gBACZ,CAAC;YACH,CAAC;YACD,OAAO,KAAK,CAAC;QACf,CAAC;QACD,QAAQ,CAAC,KAAK,EAAE,KAAK,GAAG,QAAQ;YAC9B,gBAAgB,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;QACjC,CAAC;QACD,WAAW;YACT,OAAO,QAAQ,CAAC;QAClB,CAAC;QACD,eAAe,CAAC,YAAY;YAC1B,QAAQ,GAAG,gBAAgB,CAAC,YAAY,CAAC,CAAC;YAC1C,mBAAmB,GAAG,KAAK,CAAC;QAC9B,CAAC;KACF,CAAC;AACJ,CAAC;AAED,2EAA2E;AAC3E,MAAM,CAAC,MAAM,mBAAmB,GAAG,kBAAkB,EAAE,CAAC;AAExD;;;;GAIG;AACH,MAAM,UAAU,kBAAkB,CAAC,QAAyB;IAC1D,mBAAmB,CAAC,eAAe,CAAC,QAAQ,CAAC,CAAC;AAChD,CAAC;AAED,8EAA8E;AAC9E,MAAM,UAAU,iBAAiB;IAC/B,OAAO,mBAAmB,CAAC,WAAW,EAAE,CAAC;AAC3C,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,EAAoB,EACpB,kBAAmD;IAEnD,OAAO,mBAAmB,CAAC,SAAS,CAAC,EAAE,EAAE,kBAAkB,CAAC,CAAC;AAC/D,CAAC;AAED,MAAM,UAAU,aAAa,CAC3B,KAAmB,EACnB,KAAwB;IAExB,mBAAmB,CAAC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC,CAAC;AAC7C,CAAC;AAED,2EAA2E;AAC3E,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC"}

package/dist/vault/session-vault-errors.d.ts

@@ -1,14 +1,23 @@
 /**
- * SessionVault error classes — extracted so helper modules (file-lock,
- * sidecar) can throw them without creating an import cycle back into
- * session-vault.ts.
+ * Vault error taxonomy — the package's one `VaultError` hierarchy, extracted
+ * so helper modules (file-lock, sidecar, vault-utils) can throw these without
+ * creating an import cycle back into session-vault.ts.
+ *
+ * Most members are SessionVault-specific; `InvalidCredentialKeyError` is
+ * raised by the credential cascade (`vault.ts`) and its backends. They share a
+ * base class deliberately — a caller wrapping vault work in
+ * `catch (e) { if (e instanceof VaultError) … }` should not have to know which
+ * storage path produced the failure.
+ *
+ * This module has no imports on purpose; keep it that way so any vault module
+ * can depend on it.
  *
  * Each subclass restores the prototype chain with `Object.setPrototypeOf`
  * so `instanceof VaultError` etc. remains robust when the class is consumed
  * across an ES transpile boundary (L2 — matches the EngramError pattern in
  * `packages/sdk/src/errors.ts`).
  */
-/** Base class for SessionVault errors. */
+/** Base class for vault errors. */
 export declare class VaultError extends Error {
     readonly code: string;
     constructor(code: string, message: string);
@@ -31,6 +40,65 @@ export declare class VaultRollbackError extends VaultError {
 export declare class VaultClosedError extends VaultError {
     constructor();
 }
+/**
+ * Thrown when a rekey's external commit failed AND restoring the prior
+ * ciphertext then failed too.
+ *
+ * This is the one indeterminate state the rekey path can reach: the vault file
+ * may still hold the ciphertext written under the NEW key, so neither key can
+ * be assumed to be the right one — and, critically, **no key material for
+ * either may be discarded**. Callers that clean up on failure (e.g. deleting
+ * freshly written passphrase metadata) must special-case this error; deleting
+ * the new key's material here can leave the vault permanently unopenable.
+ */
+export declare class VaultRestoreError extends VaultError {
+    /** Absolute path of the vault whose state is indeterminate. */
+    readonly path: string;
+    /** Version the new ciphertext carries, if it is the one on disk. */
+    readonly attemptedVersion: number;
+    /** The `commit` failure that triggered the rollback attempt. */
+    readonly commitCause: unknown;
+    /** The failure of the rollback write itself. */
+    readonly restoreCause: unknown;
+    constructor(
+    /** Absolute path of the vault whose state is indeterminate. */
+    path: string, 
+    /** Version the new ciphertext carries, if it is the one on disk. */
+    attemptedVersion: number, 
+    /** The `commit` failure that triggered the rollback attempt. */
+    commitCause: unknown, 
+    /** The failure of the rollback write itself. */
+    restoreCause: unknown);
+}
+/**
+ * Thrown when a credential key (or a `listCredentials` prefix) does not match
+ * the key grammar every vault backend is required to accept.
+ *
+ * **Why this throws rather than returning a falsy value (#168).** The backends
+ * disagree about non-conforming keys: macOS Keychain and the env fallback
+ * store anything, while the 1Password, GPG, libsecret and Windows backends
+ * cannot address such a key at all. A key that violates the grammar therefore
+ * writes successfully on a Mac and is unreadable everywhere else — a silent
+ * write/read asymmetry (P2). Returning `false`/`null` would express that as
+ * "the write failed" or, worse on the read path, as "no such credential",
+ * which is indistinguishable from a genuine miss. The key is malformed, not
+ * missing, and only a distinguishable failure says so.
+ */
+export declare class InvalidCredentialKeyError extends VaultError {
+    /** The offending key or prefix. A key name, never credential material. */
+    readonly key: string;
+    /** The operation that was refused — "read", "write", "delete", "enumerate". */
+    readonly operation: string;
+    /** Whether `key` was supplied as a full key or as a `listCredentials` prefix. */
+    readonly kind: "key" | "prefix";
+    constructor(
+    /** The offending key or prefix. A key name, never credential material. */
+    key: string, 
+    /** The operation that was refused — "read", "write", "delete", "enumerate". */
+    operation: string, 
+    /** Whether `key` was supplied as a full key or as a `listCredentials` prefix. */
+    kind?: "key" | "prefix");
+}
 /** Thrown when the write-path file lock can't be acquired within the timeout. */
 export declare class VaultLockError extends VaultError {
     constructor(message: string);

package/dist/vault/session-vault-errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"session-vault-errors.d.ts","sourceRoot":"","sources":["../../src/vault/session-vault-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,0CAA0C;AAC1C,qBAAa,UAAW,SAAQ,KAAK;aACP,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1D;AAED,kFAAkF;AAClF,qBAAa,gBAAiB,SAAQ,UAAU;gBAClC,OAAO,EAAE,MAAM;CAK5B;AAED,iFAAiF;AACjF,qBAAa,iBAAkB,SAAQ,UAAU;gBACnC,OAAO,EAAE,MAAM;CAK5B;AAED,oEAAoE;AACpE,qBAAa,kBAAmB,SAAQ,UAAU;aAE9B,QAAQ,EAAE,MAAM;aAChB,MAAM,EAAE,MAAM;gBADd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;CAWjC;AAED,8DAA8D;AAC9D,qBAAa,gBAAiB,SAAQ,UAAU;;CAM/C;AAED,iFAAiF;AACjF,qBAAa,cAAe,SAAQ,UAAU;gBAChC,OAAO,EAAE,MAAM;CAK5B"}
+{"version":3,"file":"session-vault-errors.d.ts","sourceRoot":"","sources":["../../src/vault/session-vault-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,mCAAmC;AACnC,qBAAa,UAAW,SAAQ,KAAK;aACP,IAAI,EAAE,MAAM;gBAAZ,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM;CAK1D;AAED,kFAAkF;AAClF,qBAAa,gBAAiB,SAAQ,UAAU;gBAClC,OAAO,EAAE,MAAM;CAK5B;AAED,iFAAiF;AACjF,qBAAa,iBAAkB,SAAQ,UAAU;gBACnC,OAAO,EAAE,MAAM;CAK5B;AAED,oEAAoE;AACpE,qBAAa,kBAAmB,SAAQ,UAAU;aAE9B,QAAQ,EAAE,MAAM;aAChB,MAAM,EAAE,MAAM;gBADd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM;CAWjC;AAED,8DAA8D;AAC9D,qBAAa,gBAAiB,SAAQ,UAAU;;CAM/C;AAED;;;;;;;;;;GAUG;AACH,qBAAa,iBAAkB,SAAQ,UAAU;IAE7C,+DAA+D;aAC/C,IAAI,EAAE,MAAM;IAC5B,oEAAoE;aACpD,gBAAgB,EAAE,MAAM;IACxC,gEAAgE;aAChD,WAAW,EAAE,OAAO;IACpC,gDAAgD;aAChC,YAAY,EAAE,OAAO;;IAPrC,+DAA+D;IAC/C,IAAI,EAAE,MAAM;IAC5B,oEAAoE;IACpD,gBAAgB,EAAE,MAAM;IACxC,gEAAgE;IAChD,WAAW,EAAE,OAAO;IACpC,gDAAgD;IAChC,YAAY,EAAE,OAAO;CAexC;AAMD;;;;;;;;;;;;;GAaG;AACH,qBAAa,yBAA0B,SAAQ,UAAU;IAErD,0EAA0E;aAC1D,GAAG,EAAE,MAAM;IAC3B,+EAA+E;aAC/D,SAAS,EAAE,MAAM;IACjC,iFAAiF;aACjE,IAAI,EAAE,KAAK,GAAG,QAAQ;;IALtC,0EAA0E;IAC1D,GAAG,EAAE,MAAM;IAC3B,+EAA+E;IAC/D,SAAS,EAAE,MAAM;IACjC,iFAAiF;IACjE,IAAI,GAAE,KAAK,GAAG,QAAgB;CAejD;AAED,iFAAiF;AACjF,qBAAa,cAAe,SAAQ,UAAU;gBAChC,OAAO,EAAE,MAAM;CAK5B"}

package/dist/vault/session-vault-errors.js

@@ -1,14 +1,23 @@
 /**
- * SessionVault error classes — extracted so helper modules (file-lock,
- * sidecar) can throw them without creating an import cycle back into
- * session-vault.ts.
+ * Vault error taxonomy — the package's one `VaultError` hierarchy, extracted
+ * so helper modules (file-lock, sidecar, vault-utils) can throw these without
+ * creating an import cycle back into session-vault.ts.
+ *
+ * Most members are SessionVault-specific; `InvalidCredentialKeyError` is
+ * raised by the credential cascade (`vault.ts`) and its backends. They share a
+ * base class deliberately — a caller wrapping vault work in
+ * `catch (e) { if (e instanceof VaultError) … }` should not have to know which
+ * storage path produced the failure.
+ *
+ * This module has no imports on purpose; keep it that way so any vault module
+ * can depend on it.
  *
  * Each subclass restores the prototype chain with `Object.setPrototypeOf`
  * so `instanceof VaultError` etc. remains robust when the class is consumed
  * across an ES transpile boundary (L2 — matches the EngramError pattern in
  * `packages/sdk/src/errors.ts`).
  */
-/** Base class for SessionVault errors. */
+/** Base class for vault errors. */
 export class VaultError extends Error {
     code;
     constructor(code, message) {
@@ -56,6 +65,88 @@ export class VaultClosedError extends VaultError {
         Object.setPrototypeOf(this, new.target.prototype);
     }
 }
+/**
+ * Thrown when a rekey's external commit failed AND restoring the prior
+ * ciphertext then failed too.
+ *
+ * This is the one indeterminate state the rekey path can reach: the vault file
+ * may still hold the ciphertext written under the NEW key, so neither key can
+ * be assumed to be the right one — and, critically, **no key material for
+ * either may be discarded**. Callers that clean up on failure (e.g. deleting
+ * freshly written passphrase metadata) must special-case this error; deleting
+ * the new key's material here can leave the vault permanently unopenable.
+ */
+export class VaultRestoreError extends VaultError {
+    path;
+    attemptedVersion;
+    commitCause;
+    restoreCause;
+    constructor(
+    /** Absolute path of the vault whose state is indeterminate. */
+    path, 
+    /** Version the new ciphertext carries, if it is the one on disk. */
+    attemptedVersion, 
+    /** The `commit` failure that triggered the rollback attempt. */
+    commitCause, 
+    /** The failure of the rollback write itself. */
+    restoreCause) {
+        super("VAULT_RESTORE_FAILED", `Rekey of ${path} could not be completed OR undone. The caller's commit ` +
+            `failed (${describeCause(commitCause)}) and restoring the prior ` +
+            `ciphertext then failed (${describeCause(restoreCause)}). The vault ` +
+            `file may still hold the ciphertext written under the NEW key at ` +
+            `version ${attemptedVersion}. Do NOT discard either key: try the new ` +
+            `key first, then the old one. If neither opens it, restore a backup of ` +
+            `the vault file and its sidecar.`);
+        this.path = path;
+        this.attemptedVersion = attemptedVersion;
+        this.commitCause = commitCause;
+        this.restoreCause = restoreCause;
+        this.name = "VaultRestoreError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+function describeCause(cause) {
+    return cause instanceof Error ? cause.message : String(cause);
+}
+/**
+ * Thrown when a credential key (or a `listCredentials` prefix) does not match
+ * the key grammar every vault backend is required to accept.
+ *
+ * **Why this throws rather than returning a falsy value (#168).** The backends
+ * disagree about non-conforming keys: macOS Keychain and the env fallback
+ * store anything, while the 1Password, GPG, libsecret and Windows backends
+ * cannot address such a key at all. A key that violates the grammar therefore
+ * writes successfully on a Mac and is unreadable everywhere else — a silent
+ * write/read asymmetry (P2). Returning `false`/`null` would express that as
+ * "the write failed" or, worse on the read path, as "no such credential",
+ * which is indistinguishable from a genuine miss. The key is malformed, not
+ * missing, and only a distinguishable failure says so.
+ */
+export class InvalidCredentialKeyError extends VaultError {
+    key;
+    operation;
+    kind;
+    constructor(
+    /** The offending key or prefix. A key name, never credential material. */
+    key, 
+    /** The operation that was refused — "read", "write", "delete", "enumerate". */
+    operation, 
+    /** Whether `key` was supplied as a full key or as a `listCredentials` prefix. */
+    kind = "key") {
+        super("VAULT_INVALID_CREDENTIAL_KEY", `Vault ${operation} refused: credential ${kind} ${JSON.stringify(key)} ` +
+            `does not match the required key grammar. Keys must be 2-64 characters ` +
+            `of lowercase alphanumerics with '-' or '.' as separators, beginning ` +
+            `and ending with an alphanumeric` +
+            (kind === "prefix" ? " (a prefix may end with a separator)" : "") +
+            `. Non-conforming keys store on some backends and are unaddressable on ` +
+            `others, so the value would be written and never read back.`);
+        this.key = key;
+        this.operation = operation;
+        this.kind = kind;
+        this.name = "InvalidCredentialKeyError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
 /** Thrown when the write-path file lock can't be acquired within the timeout. */
 export class VaultLockError extends VaultError {
     constructor(message) {

package/dist/vault/session-vault-errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"session-vault-errors.js","sourceRoot":"","sources":["../../src/vault/session-vault-errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,0CAA0C;AAC1C,MAAM,OAAO,UAAW,SAAQ,KAAK;IACP;IAA5B,YAA4B,IAAY,EAAE,OAAe;QACvD,KAAK,CAAC,OAAO,CAAC,CAAC;QADW,SAAI,GAAJ,IAAI,CAAQ;QAEtC,IAAI,CAAC,IAAI,GAAG,YAAY,CAAC;QACzB,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,kFAAkF;AAClF,MAAM,OAAO,gBAAiB,SAAQ,UAAU;IAC9C,YAAY,OAAe;QACzB,KAAK,CAAC,qBAAqB,EAAE,OAAO,CAAC,CAAC;QACtC,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,iFAAiF;AACjF,MAAM,OAAO,iBAAkB,SAAQ,UAAU;IAC/C,YAAY,OAAe;QACzB,KAAK,CAAC,sBAAsB,EAAE,OAAO,CAAC,CAAC;QACvC,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,oEAAoE;AACpE,MAAM,OAAO,kBAAmB,SAAQ,UAAU;IAE9B;IACA;IAFlB,YACkB,QAAgB,EAChB,MAAc;QAE9B,KAAK,CACH,iCAAiC,EACjC,+DAA+D,QAAQ,IAAI;YACzE,kCAAkC,MAAM,8BAA8B;YACtE,wDAAwD,CAC3D,CAAC;QARc,aAAQ,GAAR,QAAQ,CAAQ;QAChB,WAAM,GAAN,MAAM,CAAQ;QAQ9B,IAAI,CAAC,IAAI,GAAG,oBAAoB,CAAC;QACjC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,8DAA8D;AAC9D,MAAM,OAAO,gBAAiB,SAAQ,UAAU;IAC9C;QACE,KAAK,CAAC,cAAc,EAAE,6DAA6D,CAAC,CAAC;QACrF,IAAI,CAAC,IAAI,GAAG,kBAAkB,CAAC;QAC/B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,iFAAiF;AACjF,MAAM,OAAO,cAAe,SAAQ,UAAU;IAC5C,YAAY,OAAe;QACzB,KAAK,CAAC,mBAAmB,EAAE,OAAO,CAAC,CAAC;QACpC,IAAI,CAAC,IAAI,GAAG,gBAAgB,CAAC;QAC7B,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF"}
+{"version":3,"file":"session-vault-errors.js","sourceRoot":"","sources":["../../src/vault/session-vault-errors.ts"],"names":[],"mappings":"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"}

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

@@ -39,8 +39,8 @@
  */
 import type { KeychainProviderOptions } from "../key-providers/keychain-provider.js";
 import type { KeyProvider, KeyProviderType } from "../key-providers/types.js";
-import { VaultError, VaultUnlockError, VaultDecryptError, VaultRollbackError, VaultClosedError, VaultLockError } from "./session-vault-errors.js";
-export { VaultError, VaultUnlockError, VaultDecryptError, VaultRollbackError, VaultClosedError, VaultLockError, };
+import { VaultError, VaultUnlockError, VaultDecryptError, VaultRollbackError, VaultClosedError, VaultLockError, VaultRestoreError, InvalidCredentialKeyError } from "./session-vault-errors.js";
+export { VaultError, VaultUnlockError, VaultDecryptError, VaultRollbackError, VaultClosedError, VaultLockError, VaultRestoreError, InvalidCredentialKeyError, };
 /** Current payload schema version — bump requires a compat migration. */
 export declare const VAULT_SCHEMA_VERSION = 1;
 /** Default vault file location — same path the CLI uses, so they share state. */
@@ -123,6 +123,29 @@ export interface OpenVaultOptions {
      */
     keychain?: KeychainProviderOptions;
 }
+/** Options for {@link createVault}. */
+export interface CreateVaultOptions {
+    /** Alternate vault file path. Defaults to the same path the CLI uses. */
+    path?: string;
+    /** Alternate sidecar path. Defaults to vault directory + `vault.seen-version`. */
+    sidecarPath?: string;
+    /**
+     * Caller-owned AES-256 key used to encrypt the empty vault.
+     *
+     * This function neither stores nor zeroes the key. Key-provider setup is a
+     * separate, potentially irreversible transaction; keeping it outside this
+     * filesystem primitive prevents a failed create from deleting or replacing
+     * a key that another vault may share.
+     */
+    key: Buffer;
+}
+/** Result of an idempotent {@link createVault} call. */
+export interface CreateVaultResult {
+    /** True when this call created the vault/sidecar pair; false when both existed. */
+    created: boolean;
+    /** Canonical absolute vault path used for AAD binding. */
+    path: string;
+}
 /**
  * A long-lived handle to an unlocked vault. Construct with {@link openVault};
  * close with {@link SessionVault.close}. Operations are async so policy
@@ -148,6 +171,26 @@ export interface SessionVault {
     /** Diagnostic — the current in-memory vault version. */
     readonly vaultVersion: number;
 }
+/**
+ * Create an empty, AAD-bound session vault and its rollback sidecar.
+ *
+ * Creation is idempotent only for a complete pair: if both files already
+ * exist they are left byte-for-byte untouched and `created` is false. A
+ * vault-only or sidecar-only state is refused rather than "repaired" because
+ * replacing either half could erase rollback evidence or make existing
+ * ciphertext permanently unreadable.
+ *
+ * Both destinations use no-clobber publication: the completed vault temp is
+ * linked into place first, then the sidecar is the logical commit point. A
+ * successful return therefore means both public paths exist, and a competing
+ * destination is never replaced. This is temp-file/link crash safety, not an
+ * fsync or power-loss durability guarantee.
+ *
+ * The caller retains ownership of `opts.key`; this function snapshots it for
+ * the duration of the call, zeroes that private copy, and never mutates,
+ * zeroes, or stores the caller's buffer.
+ */
+export declare function createVault(opts: CreateVaultOptions): Promise<CreateVaultResult>;
 /**
  * Open an encrypted session vault.
  *
@@ -174,4 +217,104 @@ export interface SessionVault {
  * ```
  */
 export declare function openVault(opts?: OpenVaultOptions): Promise<SessionVault>;
+/** Options for {@link rekeyVault}. */
+export interface RekeyVaultOptions {
+    /** Vault file path. Defaults to the same path the CLI uses. */
+    path?: string;
+    /** Sidecar path. Defaults to vault directory + `vault.seen-version`. */
+    sidecarPath?: string;
+    /** The key the vault is currently encrypted under. */
+    currentKey: Buffer;
+    /** The key the vault should be re-encrypted under. */
+    nextKey: Buffer;
+    /**
+     * Opt-in acceptance of a detected rollback (sidecar version > vault
+     * version), mirroring {@link OpenVaultOptions.acceptRollback}. Unlike
+     * `openVault`, the sidecar is never lowered to match — the rekeyed vault
+     * lands above the recorded high-water mark either way, so accepting a
+     * rollback here does not also discard the mark.
+     */
+    acceptRollback?: boolean;
+    /**
+     * Opt-in acceptance of a missing sidecar, mirroring
+     * {@link OpenVaultOptions.acceptMissingSidecar}. Legacy (pre-`openVault`,
+     * AAD-less) vaults never had a sidecar by construction and are exempt.
+     */
+    acceptMissingSidecar?: boolean;
+    /**
+     * Invoked once the re-encrypted vault has landed on disk, while the write
+     * lock is still held and before the sidecar high-water mark is published.
+     *
+     * This is the seam that makes an *external* commitment part of the same
+     * all-or-nothing step. `migrate --to passphrase` uses it to write
+     * `secrets.provider` — a config that names a provider which cannot open the
+     * vault (or a vault no configured provider can open) is exactly the
+     * half-migrated state this exists to prevent. Throwing restores the prior
+     * ciphertext byte-for-byte and rethrows; the sidecar is never advanced on
+     * that path, so the restored vault opens cleanly.
+     */
+    commit?: () => void | Promise<void>;
+}
+/** Outcome of a successful {@link rekeyVault}. */
+export interface RekeyVaultResult {
+    /** Number of secrets carried across to the new ciphertext. */
+    secretCount: number;
+    /** The vault version after the rekey. */
+    vaultVersion: number;
+    /** True when the source vault was in the pre-`openVault` AAD-less shape. */
+    upgradedFromLegacy: boolean;
+    /**
+     * False when the rekey committed but the sidecar version bump could not be
+     * written (warned on stderr). The rekey still succeeded — see the note on
+     * the sidecar write in {@link rekeyVault} — but rollback protection is
+     * degraded until the next successful vault write catches the sidecar up.
+     */
+    sidecarPublished: boolean;
+}
+/**
+ * Re-encrypt a vault in place under a different master key.
+ *
+ * Needed whenever the new key cannot be *chosen* — a `PassphraseProvider`
+ * derives its key from what the operator types and cannot store a
+ * caller-supplied one, so moving a vault to it means rewriting the ciphertext
+ * rather than copying the key to a new home. Provider-to-provider moves that
+ * only relocate the same key do not need this.
+ *
+ * The AAD binds the vault's resolved real path and schema, not the key, so the
+ * rekeyed ciphertext stays bound to the same file identity. Legacy AAD-less
+ * vaults are upgraded to schema 1 in the same step. The new version is one
+ * above both the payload's version and the sidecar's high-water mark, so a
+ * rekeyed vault can never land below a version already seen.
+ *
+ * Any process holding this vault open under the old key will fail its next
+ * decrypt with {@link VaultDecryptError} — an honest failure, by design: the
+ * old key genuinely no longer opens this vault.
+ *
+ * **Post-commit guarantee.** With one named exception, a throw means `commit`
+ * did not succeed and the prior ciphertext is back in place — nothing after a
+ * successful `commit` can throw, because the only step that follows it (the
+ * sidecar bump) is reported via {@link RekeyVaultResult.sidecarPublished}
+ * rather than thrown. Callers may therefore treat a throw as "nothing was
+ * committed" and clean up accordingly; that is what makes it safe for the CLI
+ * to delete freshly written passphrase metadata on failure.
+ *
+ * **The exception: {@link VaultRestoreError}.** If `commit` throws *and* the
+ * rollback write then fails, the file on disk may still be the new ciphertext.
+ * That state is neither committed nor undone, so it gets its own error type —
+ * callers MUST special-case it and must NOT discard key material for either
+ * key. Every other throw keeps the plain guarantee.
+ *
+ * @param opts - {@link RekeyVaultOptions}. `currentKey`/`nextKey` are required;
+ *   both remain owned by the caller and are never zeroed here.
+ * @returns {@link RekeyVaultResult}.
+ * @throws {@link VaultError} `VAULT_NOT_FOUND` when the vault file is absent.
+ * @throws {@link VaultDecryptError} when `currentKey` does not open the vault.
+ * @throws {@link VaultError} `VAULT_SIDECAR_MISSING` when the sidecar is absent
+ *   and neither `acceptMissingSidecar` nor the legacy exemption applies.
+ * @throws {@link VaultRollbackError} when the vault version trails the sidecar
+ *   and `acceptRollback` is not set.
+ * @throws {@link VaultError} `VAULT_ENCRYPT_FAILED` when re-encryption fails.
+ * @throws Whatever `commit` throws, after restoring the prior ciphertext.
+ */
+export declare function rekeyVault(opts: RekeyVaultOptions): Promise<RekeyVaultResult>;
 //# sourceMappingURL=session-vault.d.ts.map