@centient/secrets 0.8.0 → 0.10.0

package/dist/platform/session-context.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Session-context detection (#188).
+ *
+ * ## Why this is not platform detection
+ *
+ * The keychain accessors in this package used to branch on nothing at all:
+ * one code path, which implicitly assumed an interactive GUI session. That
+ * assumption is wrong in exactly the contexts a credential store matters most
+ * — a launchd system-domain daemon and an SSH login both run **without a
+ * security session** attached to the user's login keychain:
+ *
+ *   - no consent UI can render, so an item whose ACL is not preauthorized at
+ *     write time is unreadable and there is nothing to click;
+ *   - the keychain **search list** cannot be trusted, because it leads with
+ *     the (locked) login keychain, whose copy of an item shadows a perfectly
+ *     readable System-keychain copy.
+ *
+ * `process.platform === "darwin"` answers neither question — a Mac is a Mac in
+ * all three contexts. So the branch that matters is *session vs sessionless*,
+ * and that is what this module reports.
+ *
+ * ## The signals, and their limits
+ *
+ * There is no supported API that says "you are in the launchd system domain",
+ * so this is a heuristic and is documented as one. It is deliberately
+ * conservative, and the read path is built so that a misclassification is
+ * harmless rather than fatal: a sessionless read consults the System keychain
+ * *first* and only then falls back to the search list, so classifying an
+ * interactive session as sessionless can never lose a credential that was
+ * previously readable (see `readKeychainCredential` in
+ * `../crypto/darwin-keychain.ts`).
+ *
+ * The override exists for the case the heuristic cannot see — a daemon whose
+ * environment is scrubbed, or a test rig — and it wins over every signal.
+ */
+/** Environment variable that forces the answer. `sessionless` | `interactive`. */
+export declare const SESSION_CONTEXT_OVERRIDE_ENV = "CENTIENT_SECRETS_SESSION_CONTEXT";
+/** Injectable seam. Both fields default to the live process. */
+export interface SessionContextDeps {
+    platform: NodeJS.Platform;
+    env: NodeJS.ProcessEnv;
+}
+/**
+ * Why a context was classified the way it was. Carried so a diagnostic can
+ * explain the read path it is about to take instead of asserting it.
+ */
+export type SessionContext = {
+    kind: "sessionless";
+    /**
+     * - `ssh` — an SSH login: `SSH_CONNECTION`/`SSH_TTY`/`SSH_CLIENT` set.
+     * - `launchd-daemon` — a launchd-managed job with no controlling
+     *   terminal (`XPC_SERVICE_NAME` set to a real job label, `TERM` unset).
+     * - `forced` — the override said so.
+     */
+    reason: "ssh" | "launchd-daemon" | "forced";
+} | {
+    kind: "interactive";
+    /**
+     * - `session` — no sessionless signal was present.
+     * - `not-darwin` — the distinction is macOS-specific; elsewhere there is
+     *   no keychain search list to mistrust.
+     * - `forced` — the override said so.
+     */
+    reason: "session" | "not-darwin" | "forced";
+};
+/**
+ * Classify the current execution context.
+ *
+ * Order of precedence: explicit override, then SSH, then launchd-without-a-tty,
+ * then interactive. Off darwin the answer is always `interactive` with reason
+ * `not-darwin` — the search-list shadowing problem is a macOS keychain problem,
+ * and other backends have no equivalent notion.
+ */
+export declare function detectSessionContext(deps?: Partial<SessionContextDeps>): SessionContext;
+/** Convenience predicate over {@link detectSessionContext}. */
+export declare function isSessionlessContext(deps?: Partial<SessionContextDeps>): boolean;
+//# sourceMappingURL=session-context.d.ts.map

package/dist/platform/session-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-context.d.ts","sourceRoot":"","sources":["../../src/platform/session-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,kFAAkF;AAClF,eAAO,MAAM,4BAA4B,qCAAqC,CAAC;AAE/E,gEAAgE;AAChE,MAAM,WAAW,kBAAkB;IACjC,QAAQ,EAAE,MAAM,CAAC,QAAQ,CAAC;IAC1B,GAAG,EAAE,MAAM,CAAC,UAAU,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,MAAM,cAAc,GACtB;IACE,IAAI,EAAE,aAAa,CAAC;IACpB;;;;;OAKG;IACH,MAAM,EAAE,KAAK,GAAG,gBAAgB,GAAG,QAAQ,CAAC;CAC7C,GACD;IACE,IAAI,EAAE,aAAa,CAAC;IACpB;;;;;OAKG;IACH,MAAM,EAAE,SAAS,GAAG,YAAY,GAAG,QAAQ,CAAC;CAC7C,CAAC;AAaN;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,GAAE,OAAO,CAAC,kBAAkB,CAAM,GACrC,cAAc,CAyBhB;AAED,+DAA+D;AAC/D,wBAAgB,oBAAoB,CAClC,IAAI,GAAE,OAAO,CAAC,kBAAkB,CAAM,GACrC,OAAO,CAET"}

package/dist/platform/session-context.js

@@ -0,0 +1,83 @@
+/**
+ * Session-context detection (#188).
+ *
+ * ## Why this is not platform detection
+ *
+ * The keychain accessors in this package used to branch on nothing at all:
+ * one code path, which implicitly assumed an interactive GUI session. That
+ * assumption is wrong in exactly the contexts a credential store matters most
+ * — a launchd system-domain daemon and an SSH login both run **without a
+ * security session** attached to the user's login keychain:
+ *
+ *   - no consent UI can render, so an item whose ACL is not preauthorized at
+ *     write time is unreadable and there is nothing to click;
+ *   - the keychain **search list** cannot be trusted, because it leads with
+ *     the (locked) login keychain, whose copy of an item shadows a perfectly
+ *     readable System-keychain copy.
+ *
+ * `process.platform === "darwin"` answers neither question — a Mac is a Mac in
+ * all three contexts. So the branch that matters is *session vs sessionless*,
+ * and that is what this module reports.
+ *
+ * ## The signals, and their limits
+ *
+ * There is no supported API that says "you are in the launchd system domain",
+ * so this is a heuristic and is documented as one. It is deliberately
+ * conservative, and the read path is built so that a misclassification is
+ * harmless rather than fatal: a sessionless read consults the System keychain
+ * *first* and only then falls back to the search list, so classifying an
+ * interactive session as sessionless can never lose a credential that was
+ * previously readable (see `readKeychainCredential` in
+ * `../crypto/darwin-keychain.ts`).
+ *
+ * The override exists for the case the heuristic cannot see — a daemon whose
+ * environment is scrubbed, or a test rig — and it wins over every signal.
+ */
+/** Environment variable that forces the answer. `sessionless` | `interactive`. */
+export const SESSION_CONTEXT_OVERRIDE_ENV = "CENTIENT_SECRETS_SESSION_CONTEXT";
+function resolve(deps) {
+    return {
+        platform: deps.platform ?? process.platform,
+        env: deps.env ?? process.env,
+    };
+}
+function isSet(value) {
+    return typeof value === "string" && value.trim().length > 0;
+}
+/**
+ * Classify the current execution context.
+ *
+ * Order of precedence: explicit override, then SSH, then launchd-without-a-tty,
+ * then interactive. Off darwin the answer is always `interactive` with reason
+ * `not-darwin` — the search-list shadowing problem is a macOS keychain problem,
+ * and other backends have no equivalent notion.
+ */
+export function detectSessionContext(deps = {}) {
+    const { platform, env } = resolve(deps);
+    const override = env[SESSION_CONTEXT_OVERRIDE_ENV]?.trim();
+    if (override === "sessionless")
+        return { kind: "sessionless", reason: "forced" };
+    if (override === "interactive")
+        return { kind: "interactive", reason: "forced" };
+    if (platform !== "darwin")
+        return { kind: "interactive", reason: "not-darwin" };
+    if (isSet(env["SSH_CONNECTION"]) || isSet(env["SSH_TTY"]) || isSet(env["SSH_CLIENT"])) {
+        return { kind: "sessionless", reason: "ssh" };
+    }
+    // launchd exports `XPC_SERVICE_NAME` as the job label for a managed job; a
+    // process started from a shell either has it unset or set to the literal
+    // `"0"`. A managed job that also has no `TERM` has no controlling terminal
+    // and therefore no way to render a consent prompt. Both halves are required:
+    // a GUI application is also a launchd job, and demoting one of those to
+    // "sessionless" would be a needless change of read path.
+    const xpc = env["XPC_SERVICE_NAME"];
+    if (isSet(xpc) && xpc?.trim() !== "0" && !isSet(env["TERM"])) {
+        return { kind: "sessionless", reason: "launchd-daemon" };
+    }
+    return { kind: "interactive", reason: "session" };
+}
+/** Convenience predicate over {@link detectSessionContext}. */
+export function isSessionlessContext(deps = {}) {
+    return detectSessionContext(deps).kind === "sessionless";
+}
+//# sourceMappingURL=session-context.js.map

package/dist/platform/session-context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-context.js","sourceRoot":"","sources":["../../src/platform/session-context.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,kFAAkF;AAClF,MAAM,CAAC,MAAM,4BAA4B,GAAG,kCAAkC,CAAC;AAkC/E,SAAS,OAAO,CAAC,IAAiC;IAChD,OAAO;QACL,QAAQ,EAAE,IAAI,CAAC,QAAQ,IAAI,OAAO,CAAC,QAAQ;QAC3C,GAAG,EAAE,IAAI,CAAC,GAAG,IAAI,OAAO,CAAC,GAAG;KAC7B,CAAC;AACJ,CAAC;AAED,SAAS,KAAK,CAAC,KAAyB;IACtC,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC,CAAC;AAC9D,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,oBAAoB,CAClC,OAAoC,EAAE;IAEtC,MAAM,EAAE,QAAQ,EAAE,GAAG,EAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExC,MAAM,QAAQ,GAAG,GAAG,CAAC,4BAA4B,CAAC,EAAE,IAAI,EAAE,CAAC;IAC3D,IAAI,QAAQ,KAAK,aAAa;QAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IACjF,IAAI,QAAQ,KAAK,aAAa;QAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC;IAEjF,IAAI,QAAQ,KAAK,QAAQ;QAAE,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,YAAY,EAAE,CAAC;IAEhF,IAAI,KAAK,CAAC,GAAG,CAAC,gBAAgB,CAAC,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC,IAAI,KAAK,CAAC,GAAG,CAAC,YAAY,CAAC,CAAC,EAAE,CAAC;QACtF,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC;IAChD,CAAC;IAED,2EAA2E;IAC3E,yEAAyE;IACzE,2EAA2E;IAC3E,6EAA6E;IAC7E,wEAAwE;IACxE,yDAAyD;IACzD,MAAM,GAAG,GAAG,GAAG,CAAC,kBAAkB,CAAC,CAAC;IACpC,IAAI,KAAK,CAAC,GAAG,CAAC,IAAI,GAAG,EAAE,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC,KAAK,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC,EAAE,CAAC;QAC7D,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,gBAAgB,EAAE,CAAC;IAC3D,CAAC;IAED,OAAO,EAAE,IAAI,EAAE,aAAa,EAAE,MAAM,EAAE,SAAS,EAAE,CAAC;AACpD,CAAC;AAED,+DAA+D;AAC/D,MAAM,UAAU,oBAAoB,CAClC,OAAoC,EAAE;IAEtC,OAAO,oBAAoB,CAAC,IAAI,CAAC,CAAC,IAAI,KAAK,aAAa,CAAC;AAC3D,CAAC"}

package/dist/secret-state.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The five-way credential state (#188).
+ *
+ * Every probe in this package answers with this shape, at both credential
+ * layers — the `KeyProvider` layer (the vault master key) and the
+ * `VaultBackend` cascade (credential values).
+ *
+ * ## Why five kinds and not a boolean
+ *
+ * The defect this type exists to kill is the collapse of "there is no such
+ * credential" into "I could not read the credential". They have opposite
+ * remedies — one says *store it*, the other says *unlock the store / fix the
+ * ACL / run me in a context that has a session* — and a caller handed a single
+ * `null` cannot tell them apart. A backend that reports `absent` for an item
+ * it simply could not open turns a context change into a silent outage: the
+ * reader logs "none configured" and everything downstream behaves as though
+ * the operator never set it up.
+ *
+ * So the kinds are deliberately irreducible:
+ *
+ * - `found` — the credential is there. **Value-free**: a probe never carries
+ *   secret material, so this variant has no `value` field. Reading the bytes
+ *   is a separate, explicit call.
+ * - `absent` — the store answered, and there is no such item.
+ * - `locked` — the item exists but this execution context cannot open it
+ *   (locked keychain, an ACL that does not preauthorize the reader, no
+ *   session in which a consent prompt could render).
+ * - `not-applicable` — this store cannot exist here at all (a macOS Keychain
+ *   probe on Linux). Distinct from `failed`: nothing went wrong.
+ * - `failed` — the store was contacted and did not give a usable answer.
+ *   Includes the corrupt case where a successful read yields zero bytes: an
+ *   empty credential is never reported as `found`.
+ *
+ * `not-applicable` and `failed` carry a value-free human-readable string for
+ * diagnostics. No variant ever carries a credential.
+ *
+ * See issue #188, ADR-005, and `docs/threat-model.md`.
+ */
+export type SecretState = {
+    kind: "found";
+} | {
+    kind: "absent";
+} | {
+    kind: "locked";
+} | {
+    kind: "not-applicable";
+    reason: string;
+} | {
+    kind: "failed";
+    detail: string;
+};
+/** The discriminant of {@link SecretState}, for exhaustive switches. */
+export type SecretStateKind = SecretState["kind"];
+//# sourceMappingURL=secret-state.d.ts.map

package/dist/secret-state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-state.d.ts","sourceRoot":"","sources":["../src/secret-state.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AACH,MAAM,MAAM,WAAW,GACnB;IAAE,IAAI,EAAE,OAAO,CAAA;CAAE,GACjB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,QAAQ,CAAA;CAAE,GAClB;IAAE,IAAI,EAAE,gBAAgB,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,GAC1C;IAAE,IAAI,EAAE,QAAQ,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvC,wEAAwE;AACxE,MAAM,MAAM,eAAe,GAAG,WAAW,CAAC,MAAM,CAAC,CAAC"}

package/dist/secret-state.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=secret-state.js.map

package/dist/secret-state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-state.js","sourceRoot":"","sources":["../src/secret-state.ts"],"names":[],"mappings":""}

package/dist/vault/policy.d.ts

@@ -8,8 +8,13 @@
  * stack described in ADR-002.
  *
  * Execution model:
- *   1. `before` hooks run top-to-bottom. If any throws, the operation
- *      is aborted and the error propagates to the caller.
+ *   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
+ *      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.
  *   2. The backend operation executes.
  *   3. `after` hooks run bottom-to-top with a structured event
  *      describing the outcome. Exceptions in `after` hooks are
@@ -17,7 +22,7 @@
  *      failures must never break credential operations.
  */
 import type { VaultType } from "./types.js";
-export type SecretsEventType = "credential_read" | "credential_read_missing" | "credential_read_failed" | "credential_written" | "credential_write_failed" | "credential_deleted" | "credential_delete_failed" | "credential_enumerated" | "credential_enumerate_failed";
+export type SecretsEventType = "credential_read" | "credential_read_missing" | "credential_read_failed" | "credential_read_rejected" | "credential_written" | "credential_write_failed" | "credential_write_rejected" | "credential_deleted" | "credential_delete_failed" | "credential_delete_rejected" | "credential_enumerated" | "credential_enumerate_failed" | "credential_enumerate_rejected";
 export interface SecretsEvent {
     type: SecretsEventType;
     timestamp: string;
@@ -33,14 +38,40 @@ export interface SecretsOperation {
     key?: string;
     prefix?: string;
 }
+/**
+ * The audit event type emitted when a `before` hook rejects an
+ * operation. Single source of truth for the operation→`*_rejected`
+ * mapping, shared by the cascade vault and the session vault.
+ */
+export declare function rejectedEventType(op: SecretsOperation): SecretsEventType;
 export interface SecretsPolicy {
     readonly name: string;
+    /** `before` hooks may be async; they are awaited before the operation runs. */
     before?(op: SecretsOperation): void | Promise<void>;
+    /**
+     * `after` hooks MUST be synchronous (return type is `void`, not
+     * `Promise<void>`). The runner invokes them synchronously and catches
+     * only synchronous throws — a `Promise` returned from an `after` hook
+     * is not awaited, so its rejection would escape as an unhandled
+     * rejection rather than being swallowed with the one-time warning. Do
+     * audit I/O via a fire-and-forget sink the hook itself owns, or buffer
+     * and flush outside the hook.
+     */
     after?(event: SecretsEvent): void;
 }
 export declare function setSecretsPolicies(policies: SecretsPolicy[]): void;
 export declare function getActivePolicies(): readonly SecretsPolicy[];
-export declare function runBeforeHooks(op: SecretsOperation): Promise<void>;
+/**
+ * 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 declare function runBeforeHooks(op: SecretsOperation, makeRejectionEvent: (error: string) => SecretsEvent): Promise<void>;
 export declare function runAfterHooks(event: SecretsEvent): void;
 export interface AuditTrailOptions {
     sink: (event: SecretsEvent) => void;

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

@@ -1 +1 @@
-{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/vault/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAM5C,MAAM,MAAM,gBAAgB,GACxB,iBAAiB,GACjB,yBAAyB,GACzB,wBAAwB,GACxB,oBAAoB,GACpB,yBAAyB,GACzB,oBAAoB,GACpB,0BAA0B,GAC1B,uBAAuB,GACvB,6BAA6B,CAAC;AAElC,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,gBAAgB,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,SAAS,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,CAAC;IAChD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAMD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,MAAM,CAAC,CAAC,EAAE,EAAE,gBAAgB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD,KAAK,CAAC,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;CACnC;AASD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,IAAI,CAGlE;AAED,wBAAgB,iBAAiB,IAAI,SAAS,aAAa,EAAE,CAE5D;AAED,wBAAsB,cAAc,CAAC,EAAE,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC,CAIxE;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAiBvD;AAMD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IACpC,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,aAAa,CAejE"}
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/vault/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAM5C,MAAM,MAAM,gBAAgB,GACxB,iBAAiB,GACjB,yBAAyB,GACzB,wBAAwB,GACxB,0BAA0B,GAC1B,oBAAoB,GACpB,yBAAyB,GACzB,2BAA2B,GAC3B,oBAAoB,GACpB,0BAA0B,GAC1B,4BAA4B,GAC5B,uBAAuB,GACvB,6BAA6B,GAC7B,+BAA+B,CAAC;AAEpC,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,gBAAgB,CAAC;IACvB,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,SAAS,CAAC;IACnB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;CACpB;AAMD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,WAAW,CAAC;IAChD,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,EAAE,EAAE,gBAAgB,GAAG,gBAAgB,CAiBxE;AAMD,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,+EAA+E;IAC/E,MAAM,CAAC,CAAC,EAAE,EAAE,gBAAgB,GAAG,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IACpD;;;;;;;;OAQG;IACH,KAAK,CAAC,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAAC;CACnC;AASD,wBAAgB,kBAAkB,CAAC,QAAQ,EAAE,aAAa,EAAE,GAAG,IAAI,CAGlE;AAED,wBAAgB,iBAAiB,IAAI,SAAS,aAAa,EAAE,CAE5D;AAED;;;;;;;;;GASG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,gBAAgB,EACpB,kBAAkB,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,YAAY,GAClD,OAAO,CAAC,IAAI,CAAC,CAYf;AAED,wBAAgB,aAAa,CAAC,KAAK,EAAE,YAAY,GAAG,IAAI,CAEvD;AAkCD,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,CAAC,KAAK,EAAE,YAAY,KAAK,IAAI,CAAC;IACpC,YAAY,CAAC,EAAE,OAAO,CAAC;CACxB;AAED,wBAAgB,UAAU,CAAC,IAAI,EAAE,iBAAiB,GAAG,aAAa,CAejE"}

package/dist/vault/policy.js

@@ -8,14 +8,42 @@
  * stack described in ADR-002.
  *
  * Execution model:
- *   1. `before` hooks run top-to-bottom. If any throws, the operation
- *      is aborted and the error propagates to the caller.
+ *   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
+ *      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.
  *   2. The backend operation executes.
  *   3. `after` hooks run bottom-to-top with a structured event
  *      describing the outcome. Exceptions in `after` hooks are
  *      swallowed with a one-time stderr warning — audit infrastructure
  *      failures must never break credential operations.
  */
+/**
+ * The audit event type emitted when a `before` hook rejects an
+ * operation. Single source of truth for the operation→`*_rejected`
+ * mapping, shared by the cascade vault and the session vault.
+ */
+export function rejectedEventType(op) {
+    switch (op.type) {
+        case "read":
+            return "credential_read_rejected";
+        case "write":
+            return "credential_write_rejected";
+        case "delete":
+            return "credential_delete_rejected";
+        case "enumerate":
+            return "credential_enumerate_rejected";
+        default: {
+            // Exhaustiveness guard: if a new SecretsOperation["type"] is added
+            // without a case here, this assignment fails to compile.
+            const unreachable = op.type;
+            throw new Error(`unhandled operation type: ${String(unreachable)}`);
+        }
+    }
+}
 // =============================================================================
 // Policy registry
 // =============================================================================
@@ -28,14 +56,45 @@ export function setSecretsPolicies(policies) {
 export function getActivePolicies() {
     return activePolicies;
 }
-export async function runBeforeHooks(op) {
-    for (const policy of activePolicies) {
-        if (policy.before)
+/**
+ * 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);
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            runAfterHooksForRange(makeRejectionEvent(msg), i - 1);
+            throw err;
+        }
     }
 }
 export function runAfterHooks(event) {
-    for (let i = activePolicies.length - 1; i >= 0; i--) {
+    runAfterHooksForRange(event, activePolicies.length - 1);
+}
+/**
+ * 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.
+ */
+function runAfterHooksForRange(event, fromIndex) {
+    for (let i = fromIndex; i >= 0; i--) {
         const policy = activePolicies[i];
         if (policy.after) {
             try {

package/dist/vault/policy.js.map

@@ -1 +1 @@
-{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/vault/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;GAiBG;AAkDH,gFAAgF;AAChF,kBAAkB;AAClB,gFAAgF;AAEhF,IAAI,cAAc,GAAoB,EAAE,CAAC;AACzC,IAAI,mBAAmB,GAAG,KAAK,CAAC;AAEhC,MAAM,UAAU,kBAAkB,CAAC,QAAyB;IAC1D,cAAc,GAAG,CAAC,GAAG,QAAQ,CAAC,CAAC;IAC/B,mBAAmB,GAAG,KAAK,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,iBAAiB;IAC/B,OAAO,cAAc,CAAC;AACxB,CAAC;AAED,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,EAAoB;IACvD,KAAK,MAAM,MAAM,IAAI,cAAc,EAAE,CAAC;QACpC,IAAI,MAAM,CAAC,MAAM;YAAE,MAAM,MAAM,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;IAC7C,CAAC;AACH,CAAC;AAED,MAAM,UAAU,aAAa,CAAC,KAAmB;IAC/C,KAAK,IAAI,CAAC,GAAG,cAAc,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC,IAAI,CAAC,EAAE,CAAC,EAAE,EAAE,CAAC;QACpD,MAAM,MAAM,GAAG,cAAc,CAAC,CAAC,CAAE,CAAC;QAClC,IAAI,MAAM,CAAC,KAAK,EAAE,CAAC;YACjB,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;AACH,CAAC;AAWD,MAAM,UAAU,UAAU,CAAC,IAAuB;IAChD,MAAM,YAAY,GAAG,IAAI,CAAC,YAAY,IAAI,IAAI,CAAC;IAC/C,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,KAAK,CAAC,KAAmB;YACvB,IACE,CAAC,YAAY;gBACb,CAAC,KAAK,CAAC,IAAI,KAAK,iBAAiB;oBAC/B,KAAK,CAAC,IAAI,KAAK,yBAAyB,CAAC,EAC3C,CAAC;gBACD,OAAO;YACT,CAAC;YACD,IAAI,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;QACnB,CAAC;KACF,CAAC;AACJ,CAAC"}
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/vault/policy.ts"],"names":[],"mappings":"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"}

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) {