@centient/secrets 0.9.0 → 0.11.0

package/dist/platform/agent-detect.js

@@ -2,21 +2,67 @@
  * Agent Environment Detection
  *
  * Detects whether the process is running inside an AI agent session
- * (Claude Code, MCP context, etc.). Auth commands that require human
- * interaction are blocked in these environments.
+ * (Claude Code, MCP subprocess, etc.) by testing the environment markers such
+ * a session sets.
  *
- * Shared by: vault.ts, cli, secrets-cli.ts
+ * **What this gates (the whole list).** This is the single implementation; the
+ * only call sites are:
+ *
+ * - `cli/secrets-cli.ts` — `runSecrets()` refuses every `centient secrets`
+ *   subcommand when it returns true, and
+ * - `environment/EnvironmentManager.ts` — the environment mutation commands
+ *   (create / switch / delete-style auth operations).
+ *
+ * It does **not** gate the programmatic API: `openVault()`, `getCredential()`,
+ * `storeCredential()`, and `SessionVault.get()` contain no agent check, and
+ * `vault.ts` does not call this function. (An earlier version of this comment
+ * claimed it was "shared by vault.ts" — it never was.)
+ *
+ * **This is a UX guardrail, not a security boundary.** It reads environment
+ * variables the calling process itself controls, so any agent can clear them
+ * (`env -u CLAUDECODE …`) and walk straight through. Its job is to stop an
+ * agent from *accidentally* driving the operator CLI, nothing more. See
+ * `docs/threat-model.md` §4.4 and ADR-005 §3, which demotes this check
+ * explicitly; repairing the marker names (#189) does not re-promote it.
+ *
+ * **Marker accuracy matters** precisely because the check is cheap: before
+ * #189 it tested `CLAUDE_CODE_ENTRY_POINT` (a misspelling of the real
+ * `CLAUDE_CODE_ENTRYPOINT`) and leaned on `CLAUDE_PROJECT_DIR`, which
+ * hook-spawned subprocesses get but live interactive sessions do not — so the
+ * gate never fired for the sessions it was written for. `tests/agent-detect.test.ts`
+ * pins each marker individually so a rename cannot silently disable it again.
  */
+/**
+ * Environment variables whose presence marks an AI agent session.
+ *
+ * Package-internal (not re-exported from `index.ts`) — exported so tests and
+ * the CLI test harnesses clear exactly this set rather than a hand-copied one
+ * that can drift.
+ */
+export const AGENT_ENV_MARKERS = [
+    /** Set by every live Claude Code session (interactive and headless). */
+    "CLAUDECODE",
+    /** Set by Claude Code to name how the session was launched (cli, vscode, …). */
+    "CLAUDE_CODE_ENTRYPOINT",
+    /** Set in Claude Code hook-spawned subprocesses; absent in live sessions. */
+    "CLAUDE_PROJECT_DIR",
+    /** Session identifier exposed by some Claude Code integrations. */
+    "CLAUDE_CODE_SESSION",
+    /** Set by MCP hosts for servers running under a model context. */
+    "MCP_CONTEXT",
+    /** Set by MCP hosts to name the server being run. */
+    "MCP_SERVER_NAME",
+    /** Legacy marker retained from the pre-#189 set; harmless if unset. */
+    "ANTHROPIC_API_KEY_SOURCE",
+];
 /**
  * Returns true if the current process appears to be running inside an
  * AI agent environment (Claude Code, MCP subprocess, etc.).
+ *
+ * Advisory only — see the module docstring. A false result does not mean "a
+ * human is at the keyboard", it means "no marker was found".
  */
 export function isAgentEnvironment() {
-    return !!(process.env["CLAUDE_PROJECT_DIR"] ||
-        process.env["MCP_CONTEXT"] ||
-        process.env["CLAUDE_CODE_SESSION"] ||
-        process.env["CLAUDE_CODE_ENTRY_POINT"] ||
-        process.env["ANTHROPIC_API_KEY_SOURCE"] ||
-        process.env["MCP_SERVER_NAME"]);
+    return AGENT_ENV_MARKERS.some((name) => !!process.env[name]);
 }
 //# sourceMappingURL=agent-detect.js.map

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

@@ -1 +1 @@
-{"version":3,"file":"agent-detect.js","sourceRoot":"","sources":["../../src/platform/agent-detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH;;;GAGG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,CAAC,CAAC,CACP,OAAO,CAAC,GAAG,CAAC,oBAAoB,CAAC;QACjC,OAAO,CAAC,GAAG,CAAC,aAAa,CAAC;QAC1B,OAAO,CAAC,GAAG,CAAC,qBAAqB,CAAC;QAClC,OAAO,CAAC,GAAG,CAAC,yBAAyB,CAAC;QACtC,OAAO,CAAC,GAAG,CAAC,0BAA0B,CAAC;QACvC,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAC/B,CAAC;AACJ,CAAC"}
+{"version":3,"file":"agent-detect.js","sourceRoot":"","sources":["../../src/platform/agent-detect.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AAEH;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,iBAAiB,GAAG;IAC/B,wEAAwE;IACxE,YAAY;IACZ,gFAAgF;IAChF,wBAAwB;IACxB,6EAA6E;IAC7E,oBAAoB;IACpB,mEAAmE;IACnE,qBAAqB;IACrB,kEAAkE;IAClE,aAAa;IACb,qDAAqD;IACrD,iBAAiB;IACjB,uEAAuE;IACvE,0BAA0B;CAClB,CAAC;AAEX;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB;IAChC,OAAO,iBAAiB,CAAC,IAAI,CAAC,CAAC,IAAI,EAAE,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC;AAC/D,CAAC"}

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/policies/audit-trail.d.ts

@@ -0,0 +1,25 @@
+import type { CredentialAuditEvent } from "../audit/ocsf.js";
+import type { AuditSink } from "../sinks/types.js";
+import type { SecretsPolicy } from "../vault/policy.js";
+/** Structural seam implemented by `createHmacAuditChain()`. */
+export interface AuditEventChain {
+    append(event: CredentialAuditEvent): CredentialAuditEvent;
+}
+export interface AuditTrailOptions {
+    /** Defaults to the application-owned global OpenTelemetry tracer. */
+    readonly sink?: AuditSink;
+    /** Successful and missing reads are included unless explicitly disabled. */
+    readonly includeReads?: boolean;
+    /** Optional synchronous integrity chain applied before the record reaches a sink. */
+    readonly chain?: AuditEventChain;
+    /** Actor used when the operation did not carry an explicit caller. */
+    readonly defaultActor?: string;
+    /** Injectable record UID seam. */
+    readonly uid?: () => string;
+}
+/**
+ * Map value-free policy outcomes to OCSF, optionally chain them, then emit to
+ * one synchronous sink boundary. Rejected and failed reads are never filtered.
+ */
+export declare function auditTrail(options?: AuditTrailOptions): SecretsPolicy;
+//# sourceMappingURL=audit-trail.d.ts.map

package/dist/policies/audit-trail.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-trail.d.ts","sourceRoot":"","sources":["../../src/policies/audit-trail.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAG7D,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,mBAAmB,CAAC;AACnD,OAAO,KAAK,EAAgB,aAAa,EAAE,MAAM,oBAAoB,CAAC;AAEtE,+DAA+D;AAC/D,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,KAAK,EAAE,oBAAoB,GAAG,oBAAoB,CAAC;CAC3D;AAED,MAAM,WAAW,iBAAiB;IAChC,qEAAqE;IACrE,QAAQ,CAAC,IAAI,CAAC,EAAE,SAAS,CAAC;IAC1B,4EAA4E;IAC5E,QAAQ,CAAC,YAAY,CAAC,EAAE,OAAO,CAAC;IAChC,qFAAqF;IACrF,QAAQ,CAAC,KAAK,CAAC,EAAE,eAAe,CAAC;IACjC,sEAAsE;IACtE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,kCAAkC;IAClC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,aAAa,CA2BzE"}

package/dist/policies/audit-trail.js

@@ -0,0 +1,31 @@
+import { toCredentialAuditEvent } from "../audit/ocsf.js";
+import { otelAuditSink } from "../sinks/otel.js";
+/**
+ * Map value-free policy outcomes to OCSF, optionally chain them, then emit to
+ * one synchronous sink boundary. Rejected and failed reads are never filtered.
+ */
+export function auditTrail(options = {}) {
+    const includeReads = options.includeReads ?? true;
+    const sink = options.sink ?? otelAuditSink();
+    const chain = options.chain;
+    const appendToChain = chain?.append.bind(chain);
+    const defaultActor = options.defaultActor;
+    const uid = options.uid;
+    return {
+        name: "auditTrail",
+        observesPolicyRejections: true,
+        after(event) {
+            if (!includeReads &&
+                (event.type === "credential_read" ||
+                    event.type === "credential_read_missing")) {
+                return;
+            }
+            const projected = toCredentialAuditEvent(event, {
+                ...(defaultActor !== undefined ? { defaultActor } : {}),
+                ...(uid !== undefined ? { uid } : {}),
+            });
+            sink(appendToChain?.(projected) ?? projected);
+        },
+    };
+}
+//# sourceMappingURL=audit-trail.js.map

package/dist/policies/audit-trail.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"audit-trail.js","sourceRoot":"","sources":["../../src/policies/audit-trail.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,sBAAsB,EAAE,MAAM,kBAAkB,CAAC;AAC1D,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAsBjD;;;GAGG;AACH,MAAM,UAAU,UAAU,CAAC,UAA6B,EAAE;IACxD,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,IAAI,IAAI,CAAC;IAClD,MAAM,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,aAAa,EAAE,CAAC;IAC7C,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;IAC5B,MAAM,aAAa,GAAG,KAAK,EAAE,MAAM,CAAC,IAAI,CAAC,KAAK,CAAC,CAAC;IAChD,MAAM,YAAY,GAAG,OAAO,CAAC,YAAY,CAAC;IAC1C,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC;IAExB,OAAO;QACL,IAAI,EAAE,YAAY;QAClB,wBAAwB,EAAE,IAAI;QAC9B,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;YAED,MAAM,SAAS,GAAG,sBAAsB,CAAC,KAAK,EAAE;gBAC9C,GAAG,CAAC,YAAY,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,YAAY,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;gBACvD,GAAG,CAAC,GAAG,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,GAAG,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;aACtC,CAAC,CAAC;YACH,IAAI,CAAC,aAAa,EAAE,CAAC,SAAS,CAAC,IAAI,SAAS,CAAC,CAAC;QAChD,CAAC;KACF,CAAC;AACJ,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/sinks/index.d.ts

@@ -0,0 +1,9 @@
+export { jsonlAuditSink } from "./jsonl.js";
+export type { JsonlAuditSinkOptions } from "./jsonl.js";
+export { credentialAuditSpanAttributes, otelAuditSink, OtelAuditSinkDegradedError, } from "./otel.js";
+export type { OtelAuditSinkOptions } from "./otel.js";
+export { syslogAuditSink } from "./syslog.js";
+export type { SyslogAuditSender, SyslogAuditSinkOptions, } from "./syslog.js";
+export { AuditSinkOverflowError } from "./types.js";
+export type { AuditSink, AuditSinkErrorHandler, AuditSinkHealth, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/sinks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/sinks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAC5C,YAAY,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AACxD,OAAO,EACL,6BAA6B,EAC7B,aAAa,EACb,0BAA0B,GAC3B,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACtD,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EACV,iBAAiB,EACjB,sBAAsB,GACvB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC;AACpD,YAAY,EACV,SAAS,EACT,qBAAqB,EACrB,eAAe,GAChB,MAAM,YAAY,CAAC"}

package/dist/sinks/index.js

@@ -0,0 +1,5 @@
+export { jsonlAuditSink } from "./jsonl.js";
+export { credentialAuditSpanAttributes, otelAuditSink, OtelAuditSinkDegradedError, } from "./otel.js";
+export { syslogAuditSink } from "./syslog.js";
+export { AuditSinkOverflowError } from "./types.js";
+//# sourceMappingURL=index.js.map

package/dist/sinks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sinks/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAE5C,OAAO,EACL,6BAA6B,EAC7B,aAAa,EACb,0BAA0B,GAC3B,MAAM,WAAW,CAAC;AAEnB,OAAO,EAAE,eAAe,EAAE,MAAM,aAAa,CAAC;AAK9C,OAAO,EAAE,sBAAsB,EAAE,MAAM,YAAY,CAAC"}

package/dist/sinks/jsonl.d.ts

@@ -0,0 +1,16 @@
+import type { AuditSink, AuditSinkErrorHandler } from "./types.js";
+export interface JsonlAuditSinkOptions {
+    readonly filePath: string;
+    /** Creation mode for a new log file. Defaults to owner-only `0o600`. */
+    readonly fileMode?: number;
+    /** Creation mode for missing directories. Defaults to owner-only `0o700`. */
+    readonly directoryMode?: number;
+    readonly maxPending?: number;
+    readonly onError?: AuditSinkErrorHandler;
+}
+/**
+ * Append bare OCSF records as newline-delimited JSON. Writes are serialized in
+ * emission order; `flush()` rejects if any queued append failed.
+ */
+export declare function jsonlAuditSink(options: JsonlAuditSinkOptions): AuditSink;
+//# sourceMappingURL=jsonl.d.ts.map

package/dist/sinks/jsonl.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl.d.ts","sourceRoot":"","sources":["../../src/sinks/jsonl.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAGnE,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,6EAA6E;IAC7E,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC;CAC1C;AAQD;;;GAGG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,SAAS,CAuCxE"}

package/dist/sinks/jsonl.js

@@ -0,0 +1,51 @@
+import { appendFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+import { createQueuedAuditSink } from "./queue.js";
+function assertMode(mode, field) {
+    if (!Number.isInteger(mode) || mode < 0 || mode > 0o777) {
+        throw new RangeError(`${field} must be an integer permission mode from 0o000 to 0o777`);
+    }
+}
+/**
+ * Append bare OCSF records as newline-delimited JSON. Writes are serialized in
+ * emission order; `flush()` rejects if any queued append failed.
+ */
+export function jsonlAuditSink(options) {
+    if (options.filePath.length === 0) {
+        throw new TypeError("filePath must not be empty");
+    }
+    const fileMode = options.fileMode ?? 0o600;
+    const directoryMode = options.directoryMode ?? 0o700;
+    assertMode(fileMode, "fileMode");
+    assertMode(directoryMode, "directoryMode");
+    let directoryReady = false;
+    return createQueuedAuditSink({
+        name: "jsonl",
+        ...(options.maxPending !== undefined ? { maxPending: options.maxPending } : {}),
+        ...(options.onError !== undefined ? { onError: options.onError } : {}),
+        async write(event) {
+            if (!directoryReady) {
+                await mkdir(dirname(options.filePath), {
+                    recursive: true,
+                    mode: directoryMode,
+                });
+                directoryReady = true;
+            }
+            try {
+                await appendFile(options.filePath, `${JSON.stringify(event)}\n`, {
+                    encoding: "utf8",
+                    mode: fileMode,
+                });
+            }
+            catch (error) {
+                if (error instanceof Error &&
+                    "code" in error &&
+                    error.code === "ENOENT") {
+                    directoryReady = false;
+                }
+                throw error;
+            }
+        },
+    });
+}
+//# sourceMappingURL=jsonl.js.map

package/dist/sinks/jsonl.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"jsonl.js","sourceRoot":"","sources":["../../src/sinks/jsonl.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AACrD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAGpC,OAAO,EAAE,qBAAqB,EAAE,MAAM,YAAY,CAAC;AAYnD,SAAS,UAAU,CAAC,IAAY,EAAE,KAAa;IAC7C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,GAAG,CAAC,IAAI,IAAI,GAAG,KAAK,EAAE,CAAC;QACxD,MAAM,IAAI,UAAU,CAAC,GAAG,KAAK,yDAAyD,CAAC,CAAC;IAC1F,CAAC;AACH,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,OAA8B;IAC3D,IAAI,OAAO,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,SAAS,CAAC,4BAA4B,CAAC,CAAC;IACpD,CAAC;IACD,MAAM,QAAQ,GAAG,OAAO,CAAC,QAAQ,IAAI,KAAK,CAAC;IAC3C,MAAM,aAAa,GAAG,OAAO,CAAC,aAAa,IAAI,KAAK,CAAC;IACrD,UAAU,CAAC,QAAQ,EAAE,UAAU,CAAC,CAAC;IACjC,UAAU,CAAC,aAAa,EAAE,eAAe,CAAC,CAAC;IAE3C,IAAI,cAAc,GAAG,KAAK,CAAC;IAC3B,OAAO,qBAAqB,CAAC;QAC3B,IAAI,EAAE,OAAO;QACb,GAAG,CAAC,OAAO,CAAC,UAAU,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,UAAU,EAAE,OAAO,CAAC,UAAU,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC/E,GAAG,CAAC,OAAO,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,OAAO,CAAC,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACtE,KAAK,CAAC,KAAK,CAAC,KAAK;YACf,IAAI,CAAC,cAAc,EAAE,CAAC;gBACpB,MAAM,KAAK,CAAC,OAAO,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE;oBACrC,SAAS,EAAE,IAAI;oBACf,IAAI,EAAE,aAAa;iBACpB,CAAC,CAAC;gBACH,cAAc,GAAG,IAAI,CAAC;YACxB,CAAC;YACD,IAAI,CAAC;gBACH,MAAM,UAAU,CAAC,OAAO,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,IAAI,EAAE;oBAC/D,QAAQ,EAAE,MAAM;oBAChB,IAAI,EAAE,QAAQ;iBACf,CAAC,CAAC;YACL,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACf,IACE,KAAK,YAAY,KAAK;oBACtB,MAAM,IAAI,KAAK;oBACd,KAA+B,CAAC,IAAI,KAAK,QAAQ,EAClD,CAAC;oBACD,cAAc,GAAG,KAAK,CAAC;gBACzB,CAAC;gBACD,MAAM,KAAK,CAAC;YACd,CAAC;QACH,CAAC;KACF,CAAC,CAAC;AACL,CAAC"}

package/dist/sinks/otel.d.ts

@@ -0,0 +1,22 @@
+import { type Attributes, type Tracer } from "@opentelemetry/api";
+import type { CredentialAuditEvent } from "../audit/ocsf.js";
+import { type AuditSink, type AuditSinkErrorHandler } from "./types.js";
+export declare class OtelAuditSinkDegradedError extends Error {
+    readonly code: "OTEL_AUDIT_SINK_DEGRADED";
+    constructor(reason: "not-recording" | "not-sampled");
+}
+export interface OtelAuditSinkOptions {
+    /** Application-owned tracer; defaults to the global OTel API tracer. */
+    readonly tracer?: Tracer;
+    /** Called once when spans are not recording/sampled, and on synchronous errors. */
+    readonly onError?: AuditSinkErrorHandler;
+}
+/** Flatten one OCSF JSON record into primitive span attributes. */
+export declare function credentialAuditSpanAttributes(event: CredentialAuditEvent): Attributes;
+/**
+ * Emit one completed credential operation as a retroactive OTel span. The
+ * application owns SDK/exporter configuration; this package depends only on
+ * the OTel API, as required for reusable instrumentation libraries.
+ */
+export declare function otelAuditSink(options?: OtelAuditSinkOptions): AuditSink;
+//# sourceMappingURL=otel.d.ts.map

package/dist/sinks/otel.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"otel.d.ts","sourceRoot":"","sources":["../../src/sinks/otel.ts"],"names":[],"mappings":"AAAA,OAAO,EAKL,KAAK,UAAU,EACf,KAAK,MAAM,EACZ,MAAM,oBAAoB,CAAC;AAE5B,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAC7D,OAAO,EAGL,KAAK,SAAS,EACd,KAAK,qBAAqB,EAE3B,MAAM,YAAY,CAAC;AAKpB,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,QAAQ,CAAC,IAAI,EAAG,0BAA0B,CAAU;gBAExC,MAAM,EAAE,eAAe,GAAG,aAAa;CAQpD;AAED,MAAM,WAAW,oBAAoB;IACnC,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,mFAAmF;IACnF,QAAQ,CAAC,OAAO,CAAC,EAAE,qBAAqB,CAAC;CAC1C;AAED,mEAAmE;AACnE,wBAAgB,6BAA6B,CAC3C,KAAK,EAAE,oBAAoB,GAC1B,UAAU,CA6DZ;AAED;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,OAAO,GAAE,oBAAyB,GAAG,SAAS,CA0E3E"}