@centient/secrets 0.4.0 → 0.6.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (64) hide show
  1. package/README.md +2 -0
  2. package/dist/cli/hidden-input.d.ts +52 -0
  3. package/dist/cli/hidden-input.d.ts.map +1 -0
  4. package/dist/cli/hidden-input.js +109 -0
  5. package/dist/cli/hidden-input.js.map +1 -0
  6. package/dist/cli/secrets-cli.d.ts +9 -0
  7. package/dist/cli/secrets-cli.d.ts.map +1 -1
  8. package/dist/cli/secrets-cli.js +251 -169
  9. package/dist/cli/secrets-cli.js.map +1 -1
  10. package/dist/crypto/vault-common.d.ts +23 -4
  11. package/dist/crypto/vault-common.d.ts.map +1 -1
  12. package/dist/crypto/vault-common.js +47 -6
  13. package/dist/crypto/vault-common.js.map +1 -1
  14. package/dist/index.d.ts +5 -0
  15. package/dist/index.d.ts.map +1 -1
  16. package/dist/index.js +8 -0
  17. package/dist/index.js.map +1 -1
  18. package/dist/vault/file-lock.d.ts +33 -0
  19. package/dist/vault/file-lock.d.ts.map +1 -0
  20. package/dist/vault/file-lock.js +143 -0
  21. package/dist/vault/file-lock.js.map +1 -0
  22. package/dist/vault/policy.d.ts +50 -0
  23. package/dist/vault/policy.d.ts.map +1 -0
  24. package/dist/vault/policy.js +68 -0
  25. package/dist/vault/policy.js.map +1 -0
  26. package/dist/vault/session-vault-errors.d.ts +38 -0
  27. package/dist/vault/session-vault-errors.d.ts.map +1 -0
  28. package/dist/vault/session-vault-errors.js +67 -0
  29. package/dist/vault/session-vault-errors.js.map +1 -0
  30. package/dist/vault/session-vault.d.ts +147 -0
  31. package/dist/vault/session-vault.d.ts.map +1 -0
  32. package/dist/vault/session-vault.js +667 -0
  33. package/dist/vault/session-vault.js.map +1 -0
  34. package/dist/vault/sidecar.d.ts +37 -0
  35. package/dist/vault/sidecar.d.ts.map +1 -0
  36. package/dist/vault/sidecar.js +84 -0
  37. package/dist/vault/sidecar.js.map +1 -0
  38. package/dist/vault/types.d.ts +7 -4
  39. package/dist/vault/types.d.ts.map +1 -1
  40. package/dist/vault/vault-env.d.ts +1 -1
  41. package/dist/vault/vault-env.d.ts.map +1 -1
  42. package/dist/vault/vault-env.js +1 -1
  43. package/dist/vault/vault-env.js.map +1 -1
  44. package/dist/vault/vault-gpg.d.ts +1 -1
  45. package/dist/vault/vault-gpg.d.ts.map +1 -1
  46. package/dist/vault/vault-gpg.js +1 -1
  47. package/dist/vault/vault-gpg.js.map +1 -1
  48. package/dist/vault/vault-libsecret.d.ts +28 -14
  49. package/dist/vault/vault-libsecret.d.ts.map +1 -1
  50. package/dist/vault/vault-libsecret.js +76 -15
  51. package/dist/vault/vault-libsecret.js.map +1 -1
  52. package/dist/vault/vault-utils.d.ts +12 -2
  53. package/dist/vault/vault-utils.d.ts.map +1 -1
  54. package/dist/vault/vault-utils.js +21 -4
  55. package/dist/vault/vault-utils.js.map +1 -1
  56. package/dist/vault/vault-windows.d.ts +1 -1
  57. package/dist/vault/vault-windows.d.ts.map +1 -1
  58. package/dist/vault/vault-windows.js +1 -1
  59. package/dist/vault/vault-windows.js.map +1 -1
  60. package/dist/vault/vault.d.ts +5 -4
  61. package/dist/vault/vault.d.ts.map +1 -1
  62. package/dist/vault/vault.js +83 -8
  63. package/dist/vault/vault.js.map +1 -1
  64. package/package.json +4 -1
@@ -0,0 +1,68 @@
1
+ /**
2
+ * SecretsPolicy — Middleware layer for credential operations.
3
+ *
4
+ * Policies are cross-cutting concerns (audit, rate limiting, access
5
+ * control, attestation) applied to every credential operation via
6
+ * `setSecretsPolicies([...])`. In 0.5.0 only the audit policy is
7
+ * shipped; the API shape is designed to grow into the full policy
8
+ * stack described in ADR-002.
9
+ *
10
+ * Execution model:
11
+ * 1. `before` hooks run top-to-bottom. If any throws, the operation
12
+ * is aborted and the error propagates to the caller.
13
+ * 2. The backend operation executes.
14
+ * 3. `after` hooks run bottom-to-top with a structured event
15
+ * describing the outcome. Exceptions in `after` hooks are
16
+ * swallowed with a one-time stderr warning — audit infrastructure
17
+ * failures must never break credential operations.
18
+ */
19
+ // =============================================================================
20
+ // Policy registry
21
+ // =============================================================================
22
+ let activePolicies = [];
23
+ let afterWarningEmitted = false;
24
+ export function setSecretsPolicies(policies) {
25
+ activePolicies = [...policies];
26
+ afterWarningEmitted = false;
27
+ }
28
+ export function getActivePolicies() {
29
+ return activePolicies;
30
+ }
31
+ export async function runBeforeHooks(op) {
32
+ for (const policy of activePolicies) {
33
+ if (policy.before)
34
+ await policy.before(op);
35
+ }
36
+ }
37
+ export function runAfterHooks(event) {
38
+ for (let i = activePolicies.length - 1; i >= 0; i--) {
39
+ const policy = activePolicies[i];
40
+ if (policy.after) {
41
+ try {
42
+ policy.after(event);
43
+ }
44
+ catch (err) {
45
+ if (!afterWarningEmitted) {
46
+ afterWarningEmitted = true;
47
+ const msg = err instanceof Error ? err.message : String(err);
48
+ process.stderr.write(`[secrets] policy "${policy.name}" after-hook threw (swallowed): ${msg}\n`);
49
+ }
50
+ }
51
+ }
52
+ }
53
+ }
54
+ export function auditTrail(opts) {
55
+ const includeReads = opts.includeReads ?? true;
56
+ return {
57
+ name: "auditTrail",
58
+ after(event) {
59
+ if (!includeReads &&
60
+ (event.type === "credential_read" ||
61
+ event.type === "credential_read_missing")) {
62
+ return;
63
+ }
64
+ opts.sink(event);
65
+ },
66
+ };
67
+ }
68
+ //# sourceMappingURL=policy.js.map
@@ -0,0 +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"}
@@ -0,0 +1,38 @@
1
+ /**
2
+ * SessionVault error classes — extracted so helper modules (file-lock,
3
+ * sidecar) can throw them without creating an import cycle back into
4
+ * session-vault.ts.
5
+ *
6
+ * Each subclass restores the prototype chain with `Object.setPrototypeOf`
7
+ * so `instanceof VaultError` etc. remains robust when the class is consumed
8
+ * across an ES transpile boundary (L2 — matches the EngramError pattern in
9
+ * `packages/sdk/src/errors.ts`).
10
+ */
11
+ /** Base class for SessionVault errors. */
12
+ export declare class VaultError extends Error {
13
+ readonly code: string;
14
+ constructor(code: string, message: string);
15
+ }
16
+ /** Thrown when the master key can't be retrieved from the configured provider. */
17
+ export declare class VaultUnlockError extends VaultError {
18
+ constructor(message: string);
19
+ }
20
+ /** Thrown when decryption fails — wrong key, corrupted file, or AAD mismatch. */
21
+ export declare class VaultDecryptError extends VaultError {
22
+ constructor(message: string);
23
+ }
24
+ /** Thrown when rollback is detected and not explicitly accepted. */
25
+ export declare class VaultRollbackError extends VaultError {
26
+ readonly expected: number;
27
+ readonly actual: number;
28
+ constructor(expected: number, actual: number);
29
+ }
30
+ /** Thrown when operations are attempted on a closed vault. */
31
+ export declare class VaultClosedError extends VaultError {
32
+ constructor();
33
+ }
34
+ /** Thrown when the write-path file lock can't be acquired within the timeout. */
35
+ export declare class VaultLockError extends VaultError {
36
+ constructor(message: string);
37
+ }
38
+ //# sourceMappingURL=session-vault-errors.d.ts.map
@@ -0,0 +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"}
@@ -0,0 +1,67 @@
1
+ /**
2
+ * SessionVault error classes — extracted so helper modules (file-lock,
3
+ * sidecar) can throw them without creating an import cycle back into
4
+ * session-vault.ts.
5
+ *
6
+ * Each subclass restores the prototype chain with `Object.setPrototypeOf`
7
+ * so `instanceof VaultError` etc. remains robust when the class is consumed
8
+ * across an ES transpile boundary (L2 — matches the EngramError pattern in
9
+ * `packages/sdk/src/errors.ts`).
10
+ */
11
+ /** Base class for SessionVault errors. */
12
+ export class VaultError extends Error {
13
+ code;
14
+ constructor(code, message) {
15
+ super(message);
16
+ this.code = code;
17
+ this.name = "VaultError";
18
+ Object.setPrototypeOf(this, new.target.prototype);
19
+ }
20
+ }
21
+ /** Thrown when the master key can't be retrieved from the configured provider. */
22
+ export class VaultUnlockError extends VaultError {
23
+ constructor(message) {
24
+ super("VAULT_UNLOCK_FAILED", message);
25
+ this.name = "VaultUnlockError";
26
+ Object.setPrototypeOf(this, new.target.prototype);
27
+ }
28
+ }
29
+ /** Thrown when decryption fails — wrong key, corrupted file, or AAD mismatch. */
30
+ export class VaultDecryptError extends VaultError {
31
+ constructor(message) {
32
+ super("VAULT_DECRYPT_FAILED", message);
33
+ this.name = "VaultDecryptError";
34
+ Object.setPrototypeOf(this, new.target.prototype);
35
+ }
36
+ }
37
+ /** Thrown when rollback is detected and not explicitly accepted. */
38
+ export class VaultRollbackError extends VaultError {
39
+ expected;
40
+ actual;
41
+ constructor(expected, actual) {
42
+ super("VAULT_VERSION_ROLLBACK_DETECTED", `Vault version rollback detected: sidecar expects version >= ${expected}, ` +
43
+ `but vault file reports version ${actual}. If this is an intentional ` +
44
+ `restore, pass { acceptRollback: true } to openVault().`);
45
+ this.expected = expected;
46
+ this.actual = actual;
47
+ this.name = "VaultRollbackError";
48
+ Object.setPrototypeOf(this, new.target.prototype);
49
+ }
50
+ }
51
+ /** Thrown when operations are attempted on a closed vault. */
52
+ export class VaultClosedError extends VaultError {
53
+ constructor() {
54
+ super("VAULT_CLOSED", "Vault has been closed; reopen with openVault() to continue.");
55
+ this.name = "VaultClosedError";
56
+ Object.setPrototypeOf(this, new.target.prototype);
57
+ }
58
+ }
59
+ /** Thrown when the write-path file lock can't be acquired within the timeout. */
60
+ export class VaultLockError extends VaultError {
61
+ constructor(message) {
62
+ super("VAULT_LOCK_FAILED", message);
63
+ this.name = "VaultLockError";
64
+ Object.setPrototypeOf(this, new.target.prototype);
65
+ }
66
+ }
67
+ //# sourceMappingURL=session-vault-errors.js.map
@@ -0,0 +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"}
@@ -0,0 +1,147 @@
1
+ /**
2
+ * SessionVault — public session-backed envelope vault API.
3
+ *
4
+ * Opens the CLI's encrypted vault file once per session (one KeyProvider
5
+ * prompt), caches the decrypted contents in RAM, and serves reads without
6
+ * further prompts. External writes (e.g. the CLI in another shell) become
7
+ * visible via mtime-check coherence on every read.
8
+ *
9
+ * Addresses the per-item Keychain-prompt problem flagged in issue #40:
10
+ * long-running daemons (centient-labs/maintainer) holding N credentials
11
+ * across a long lifetime should not reach into the OS keychain on every
12
+ * access. Envelope encryption with a single master-key unlock matches
13
+ * industry standard (KMS, HashiCorp Vault, 1Password, Bitwarden).
14
+ *
15
+ * ## Threat model (what this protects and doesn't)
16
+ *
17
+ * - Protects against filesystem-read-only adversaries (ciphertext is AEAD
18
+ * encrypted; forging plaintext requires the master key).
19
+ * - Protects against live-session and cold-start vault-file rollback by a
20
+ * filesystem-write-only adversary via the combined in-payload
21
+ * `vaultVersion` + sidecar-file `highestSeenVersion` scheme.
22
+ * - Does NOT protect against an adversary with **both** master-key access
23
+ * and filesystem write — game over for any local envelope vault.
24
+ * - Does NOT protect against an adversary with write access to the vault
25
+ * directory who chooses to downgrade both vault and sidecar in lockstep
26
+ * — the sidecar lives next to the vault. If your threat model includes
27
+ * adversarial writes to `~/.centient/secrets/`, use a secrets service
28
+ * with remote attestation (HashiCorp Vault, AWS Secrets Manager,
29
+ * 1Password Connect) instead.
30
+ * - Session key is in process RAM for the full session lifetime. Any code
31
+ * with execution in the process has access to all secrets in the vault.
32
+ * Operators running daemons with this API SHOULD disable core dumps
33
+ * (`ulimit -c 0` / `prlimit --core=0`) and disable the Node.js inspector
34
+ * (`NODE_OPTIONS=--inspect` grants heap read to anyone on the inspector
35
+ * socket — a full master-key compromise vector).
36
+ * - On macOS, a newly-started process will still prompt the user for
37
+ * Keychain access even if another process holds the vault open.
38
+ * Keychain ACLs are per-process, not per-vault-file.
39
+ */
40
+ import type { KeyProviderType } from "../key-providers/types.js";
41
+ import { VaultError, VaultUnlockError, VaultDecryptError, VaultRollbackError, VaultClosedError, VaultLockError } from "./session-vault-errors.js";
42
+ export { VaultError, VaultUnlockError, VaultDecryptError, VaultRollbackError, VaultClosedError, VaultLockError, };
43
+ /** Current payload schema version — bump requires a compat migration. */
44
+ export declare const VAULT_SCHEMA_VERSION = 1;
45
+ /** Default vault file location — same path the CLI uses, so they share state. */
46
+ export declare const DEFAULT_VAULT_PATH: string;
47
+ /** Default sidecar location — stores highest-ever-seen vault version. */
48
+ export declare const DEFAULT_SIDECAR_PATH: string;
49
+ /**
50
+ * AAD prefix — static byte header mixed into the vault ciphertext's
51
+ * Additional Authenticated Data. Binding this prefix into AAD means a
52
+ * ciphertext from some other AES-GCM user with the same key cannot be
53
+ * substituted into the vault. Exported so test fixtures can produce AAD
54
+ * consistent with the real implementation without duplicating the constant.
55
+ */
56
+ export declare const VAULT_AAD_PREFIX = "centient-secrets-vault";
57
+ /**
58
+ * Coherence strategy governs how the open vault reconciles in-memory state
59
+ * with concurrent external writes to the vault file.
60
+ */
61
+ export type CoherenceStrategy = "mtime-check" | "strict" | "best-effort";
62
+ /** Options for {@link openVault}. All fields are optional. */
63
+ export interface OpenVaultOptions {
64
+ /** Alternate vault file path. Defaults to the same path the CLI uses. */
65
+ path?: string;
66
+ /** Alternate sidecar path. Defaults to vault directory + `vault.seen-version`. */
67
+ sidecarPath?: string;
68
+ /**
69
+ * Coherence strategy for concurrent external writes. Default `mtime-check`:
70
+ * stat on every read; re-decrypt if mtime advanced. `strict` throws on stale
71
+ * snapshot. `best-effort` keeps the in-memory snapshot until `reload()`.
72
+ */
73
+ coherence?: CoherenceStrategy;
74
+ /**
75
+ * Opt-in acceptance of a detected rollback (sidecar version > vault version).
76
+ * Emits a scary warning on stderr. Use only when the operator explicitly
77
+ * intends to restore an older vault (backup restore, etc.).
78
+ */
79
+ acceptRollback?: boolean;
80
+ /**
81
+ * Opt-in acceptance of a missing sidecar. Default behaviour (`false`) is to
82
+ * **refuse** to open the vault when the sidecar is absent — this enforces
83
+ * the security invariant that rollback protection is always in effect.
84
+ * Pass `true` for legitimate first-use contexts (fresh install, test
85
+ * fixtures, post-migration) to auto-initialize `seenVersion = vaultVersion`
86
+ * with a stderr warning. See docs/session-vault.md §Missing sidecar.
87
+ */
88
+ acceptMissingSidecar?: boolean;
89
+ /**
90
+ * Optional auto-close TTL in milliseconds. Not set by default — daemons run
91
+ * forever; forced re-auth undoes the point of a session vault. Useful for
92
+ * short-lived script consumers that want defense-in-depth.
93
+ */
94
+ ttlMs?: number;
95
+ }
96
+ /**
97
+ * A long-lived handle to an unlocked vault. Construct with {@link openVault};
98
+ * close with {@link SessionVault.close}. Operations are async so policy
99
+ * `before` hooks can await (e.g. remote attestation).
100
+ */
101
+ export interface SessionVault {
102
+ /** Read a secret by name. Returns null if the name isn't in the vault. */
103
+ get(name: string): Promise<string | null>;
104
+ /** List all secret names, optionally prefix-filtered. Sorted ascending. */
105
+ list(prefix?: string): Promise<string[]>;
106
+ /** Write a secret. Re-encrypts and saves the vault file atomically. */
107
+ set(name: string, value: string): Promise<void>;
108
+ /** Delete a secret. Returns true if the name existed and was removed. */
109
+ delete(name: string): Promise<boolean>;
110
+ /** Force an immediate reload from disk regardless of coherence strategy. */
111
+ reload(): Promise<void>;
112
+ /** Release the session key and in-memory state. No-op if already closed. */
113
+ close(): void;
114
+ /** Diagnostic — the KeyProvider that unlocked this session. */
115
+ readonly provider: KeyProviderType;
116
+ /** Diagnostic — absolute path of the vault file. */
117
+ readonly path: string;
118
+ /** Diagnostic — the current in-memory vault version. */
119
+ readonly vaultVersion: number;
120
+ }
121
+ /**
122
+ * Open an encrypted session vault.
123
+ *
124
+ * Resolves the configured {@link KeyProvider} to obtain the master key,
125
+ * decrypts the vault file bound to its resolved real path (symlink-aware),
126
+ * checks rollback detection via the sidecar, and returns a long-lived
127
+ * {@link SessionVault} handle that serves reads from memory.
128
+ *
129
+ * @param opts - {@link OpenVaultOptions}. All fields are optional; defaults
130
+ * use the same paths the `centient secrets` CLI uses.
131
+ * @returns An open {@link SessionVault}. Call `close()` when done.
132
+ * @throws {@link VaultError} `VAULT_NOT_FOUND` when the vault file is absent.
133
+ * @throws {@link VaultUnlockError} when the KeyProvider cannot return a key.
134
+ * @throws {@link VaultDecryptError} when decryption fails (wrong key, AAD
135
+ * mismatch, corrupted payload).
136
+ * @throws {@link VaultRollbackError} when the sidecar indicates a rollback
137
+ * and `acceptRollback` is not set.
138
+ *
139
+ * @example
140
+ * ```ts
141
+ * const vault = await openVault({ ttlMs: 60_000 });
142
+ * const apiKey = await vault.get("openai-api-key");
143
+ * vault.close();
144
+ * ```
145
+ */
146
+ export declare function openVault(opts?: OpenVaultOptions): Promise<SessionVault>;
147
+ //# sourceMappingURL=session-vault.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"session-vault.d.ts","sourceRoot":"","sources":["../../src/vault/session-vault.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAiBH,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAejE,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,EACf,MAAM,2BAA2B,CAAC;AAGnC,OAAO,EACL,UAAU,EACV,gBAAgB,EAChB,iBAAiB,EACjB,kBAAkB,EAClB,gBAAgB,EAChB,cAAc,GACf,CAAC;AAMF,yEAAyE;AACzE,eAAO,MAAM,oBAAoB,IAAI,CAAC;AAEtC,iFAAiF;AACjF,eAAO,MAAM,kBAAkB,QAAuD,CAAC;AAEvF,yEAAyE;AACzE,eAAO,MAAM,oBAAoB,QAKhC,CAAC;AAKF;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB,2BAA2B,CAAC;AA2BzD;;;GAGG;AACH,MAAM,MAAM,iBAAiB,GAAG,aAAa,GAAG,QAAQ,GAAG,aAAa,CAAC;AAEzE,8DAA8D;AAC9D,MAAM,WAAW,gBAAgB;IAC/B,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,kFAAkF;IAClF,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,SAAS,CAAC,EAAE,iBAAiB,CAAC;IAC9B;;;;OAIG;IACH,cAAc,CAAC,EAAE,OAAO,CAAC;IACzB;;;;;;;OAOG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,0EAA0E;IAC1E,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAAC;IAC1C,2EAA2E;IAC3E,IAAI,CAAC,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,EAAE,CAAC,CAAC;IACzC,uEAAuE;IACvE,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAChD,yEAAyE;IACzE,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;IACvC,4EAA4E;IAC5E,MAAM,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;IACxB,4EAA4E;IAC5E,KAAK,IAAI,IAAI,CAAC;IACd,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,eAAe,CAAC;IACnC,oDAAoD;IACpD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,wDAAwD;IACxD,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AA2ED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAsB,SAAS,CAAC,IAAI,GAAE,gBAAqB,GAAG,OAAO,CAAC,YAAY,CAAC,CAoJlF"}