vaultkeeper 0.0.0 → 0.3.0

package/dist/index.js

@@ -0,0 +1,1468 @@
+import { spawn } from 'child_process';
+import * as fs5 from 'fs/promises';
+import * as path5 from 'path';
+import * as os4 from 'os';
+import * as crypto4 from 'crypto';
+import * as fs4 from 'fs';
+import { CompactEncrypt, compactDecrypt } from 'jose';
+
+// src/errors.ts
+var VaultError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "VaultError";
+  }
+};
+var BackendLockedError = class extends VaultError {
+  /**
+   * Whether the lock can be resolved through an interactive user prompt.
+   * When `true`, callers may retry after prompting the user.
+   */
+  interactive;
+  constructor(message, interactive) {
+    super(message);
+    this.name = "BackendLockedError";
+    this.interactive = interactive;
+  }
+};
+var DeviceNotPresentError = class extends VaultError {
+  /**
+   * How long (in milliseconds) the operation waited for the device before
+   * giving up.
+   */
+  timeoutMs;
+  constructor(message, timeoutMs) {
+    super(message);
+    this.name = "DeviceNotPresentError";
+    this.timeoutMs = timeoutMs;
+  }
+};
+var AuthorizationDeniedError = class extends VaultError {
+  constructor(message) {
+    super(message);
+    this.name = "AuthorizationDeniedError";
+  }
+};
+var BackendUnavailableError = class extends VaultError {
+  /**
+   * Machine-readable reason code describing why the backend is unavailable
+   * (e.g. `'none-enabled'`, `'all-failed'`).
+   */
+  reason;
+  /**
+   * The backend type identifiers that were attempted before this error was
+   * thrown.
+   */
+  attempted;
+  constructor(message, reason, attempted) {
+    super(message);
+    this.name = "BackendUnavailableError";
+    this.reason = reason;
+    this.attempted = attempted;
+  }
+};
+var PluginNotFoundError = class extends VaultError {
+  /**
+   * The plugin package or binary name that was not found.
+   */
+  plugin;
+  /**
+   * A URL pointing to installation instructions for the missing plugin.
+   */
+  installUrl;
+  constructor(message, plugin, installUrl) {
+    super(message);
+    this.name = "PluginNotFoundError";
+    this.plugin = plugin;
+    this.installUrl = installUrl;
+  }
+};
+var SecretNotFoundError = class extends VaultError {
+  constructor(message) {
+    super(message);
+    this.name = "SecretNotFoundError";
+  }
+};
+var TokenExpiredError = class extends VaultError {
+  /**
+   * Whether the token can be refreshed by calling `setup()` again.
+   * When `true`, the secret still exists in the backend and a new token can be
+   * issued.
+   */
+  canRefresh;
+  constructor(message, canRefresh) {
+    super(message);
+    this.name = "TokenExpiredError";
+    this.canRefresh = canRefresh;
+  }
+};
+var KeyRotatedError = class extends VaultError {
+  constructor(message) {
+    super(message);
+    this.name = "KeyRotatedError";
+  }
+};
+var KeyRevokedError = class extends VaultError {
+  constructor(message) {
+    super(message);
+    this.name = "KeyRevokedError";
+  }
+};
+var TokenRevokedError = class extends VaultError {
+  constructor(message) {
+    super(message);
+    this.name = "TokenRevokedError";
+  }
+};
+var UsageLimitExceededError = class extends VaultError {
+  constructor(message) {
+    super(message);
+    this.name = "UsageLimitExceededError";
+  }
+};
+var IdentityMismatchError = class extends VaultError {
+  /**
+   * The hash that was recorded in the trust manifest at approval time.
+   */
+  previousHash;
+  /**
+   * The hash computed from the executable at the current moment.
+   */
+  currentHash;
+  constructor(message, previousHash, currentHash) {
+    super(message);
+    this.name = "IdentityMismatchError";
+    this.previousHash = previousHash;
+    this.currentHash = currentHash;
+  }
+};
+var SetupError = class extends VaultError {
+  /**
+   * The name of the dependency that caused the setup failure.
+   */
+  dependency;
+  constructor(message, dependency) {
+    super(message);
+    this.name = "SetupError";
+    this.dependency = dependency;
+  }
+};
+var FilesystemError = class extends VaultError {
+  /**
+   * The absolute path of the file or directory that caused the error.
+   */
+  path;
+  /**
+   * The permission level that was required but not available
+   * (e.g. `'read'`, `'write'`, `'execute'`).
+   */
+  permission;
+  constructor(message, filePath, permission) {
+    super(message);
+    this.name = "FilesystemError";
+    this.path = filePath;
+    this.permission = permission;
+  }
+};
+var RotationInProgressError = class extends VaultError {
+  constructor(message) {
+    super(message);
+    this.name = "RotationInProgressError";
+  }
+};
+
+// src/backend/types.ts
+function isListableBackend(backend) {
+  return "list" in backend && typeof backend.list === "function";
+}
+
+// src/backend/registry.ts
+var BackendRegistry = class {
+  static backends = /* @__PURE__ */ new Map();
+  /**
+   * Register a backend factory.
+   * @param type - Backend type identifier
+   * @param factory - Factory function to create backend instances
+   */
+  static register(type, factory) {
+    this.backends.set(type, factory);
+  }
+  /**
+   * Create a backend instance by type.
+   * @param type - Backend type identifier
+   * @returns A SecretBackend instance
+   * @throws Error if the backend type is not registered
+   */
+  static create(type) {
+    const factory = this.backends.get(type);
+    if (factory === void 0) {
+      throw new BackendUnavailableError(
+        `Unknown backend type: ${type}. Available types: ${Array.from(this.backends.keys()).join(", ")}`,
+        "unknown-type",
+        Array.from(this.backends.keys())
+      );
+    }
+    return factory();
+  }
+  /**
+   * Get all registered backend type identifiers.
+   * @returns Array of backend type identifiers
+   */
+  static getTypes() {
+    return Array.from(this.backends.keys());
+  }
+  /**
+   * Returns backend types that are available on the current system.
+   *
+   * @remarks
+   * Creates each registered backend via its factory, calls `isAvailable()`,
+   * and returns only the type identifiers whose backend reports availability.
+   * If a backend's `isAvailable()` call throws, that backend is excluded from
+   * the result rather than propagating the error.
+   *
+   * @returns Promise resolving to an array of available backend type identifiers
+   * @public
+   */
+  static async getAvailableTypes() {
+    const entries = Array.from(this.backends.entries());
+    const results = await Promise.all(
+      entries.map(async ([type, factory]) => {
+        try {
+          const backend = factory();
+          const available = await backend.isAvailable();
+          return available ? type : null;
+        } catch {
+          return null;
+        }
+      })
+    );
+    return results.filter((type) => type !== null);
+  }
+};
+async function execCommand(command, args, options) {
+  const result = await execCommandFull(command, args);
+  if (result.exitCode !== 0) {
+    throw new Error(`Command failed with exit code ${String(result.exitCode)}: ${result.stderr}`);
+  }
+  return result.stdout.trim();
+}
+function execCommandFull(command, args, options) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn(command, args, {
+      stdio: ["ignore", "pipe", "pipe"]
+    });
+    let stdout = "";
+    let stderr = "";
+    proc.stdout?.on("data", (data) => {
+      stdout += data.toString();
+    });
+    proc.stderr?.on("data", (data) => {
+      stderr += data.toString();
+    });
+    proc.on("close", (code) => {
+      resolve({ stdout, stderr, exitCode: code ?? 1 });
+    });
+    proc.on("error", (error) => {
+      reject(error);
+    });
+  });
+}
+path5.join(".vaultkeeper", "file");
+path5.join(".vaultkeeper", "yubikey");
+function hashExecutable(filePath) {
+  return new Promise((resolve, reject) => {
+    const hash = crypto4.createHash("sha256");
+    const stream = fs4.createReadStream(filePath);
+    stream.on("data", (chunk) => {
+      hash.update(chunk);
+    });
+    stream.on("end", () => {
+      resolve(hash.digest("hex"));
+    });
+    stream.on("error", (err) => {
+      reject(err);
+    });
+  });
+}
+var MANIFEST_FILENAME = "trust-manifest.json";
+function isRawManifest(value) {
+  if (typeof value !== "object" || value === null) return false;
+  if (!("version" in value) || typeof value.version !== "number") return false;
+  if (!("entries" in value) || typeof value.entries !== "object" || value.entries === null) return false;
+  return true;
+}
+function isTrustManifestEntry(value) {
+  if (typeof value !== "object" || value === null) return false;
+  if (!("hashes" in value) || !Array.isArray(value.hashes)) return false;
+  if (!("trustTier" in value)) return false;
+  const { trustTier } = value;
+  if (trustTier !== 1 && trustTier !== 2 && trustTier !== 3) return false;
+  return true;
+}
+async function loadManifest(configDir) {
+  const manifestPath = path5.join(configDir, MANIFEST_FILENAME);
+  let rawText;
+  try {
+    rawText = await fs5.readFile(manifestPath, "utf8");
+  } catch (err) {
+    if (typeof err === "object" && err !== null && "code" in err && err.code === "ENOENT") {
+      return /* @__PURE__ */ new Map();
+    }
+    throw err;
+  }
+  const parsed = JSON.parse(rawText);
+  if (!isRawManifest(parsed)) {
+    return /* @__PURE__ */ new Map();
+  }
+  const manifest = /* @__PURE__ */ new Map();
+  for (const [namespace, entry] of Object.entries(parsed.entries)) {
+    if (isTrustManifestEntry(entry)) {
+      manifest.set(namespace, { hashes: [...entry.hashes], trustTier: entry.trustTier });
+    }
+  }
+  return manifest;
+}
+async function saveManifest(configDir, manifest) {
+  await fs5.mkdir(configDir, { recursive: true });
+  const entries = {};
+  for (const [namespace, entry] of manifest) {
+    entries[namespace] = entry;
+  }
+  const raw = { version: 1, entries };
+  const manifestPath = path5.join(configDir, MANIFEST_FILENAME);
+  await fs5.writeFile(manifestPath, JSON.stringify(raw, null, 2), "utf8");
+}
+function addTrustedHash(manifest, namespace, hash) {
+  const next = new Map(manifest);
+  const existing = next.get(namespace);
+  if (existing === void 0) {
+    next.set(namespace, { hashes: [hash], trustTier: 3 });
+  } else if (!existing.hashes.includes(hash)) {
+    next.set(namespace, { hashes: [...existing.hashes, hash], trustTier: existing.trustTier });
+  }
+  return next;
+}
+function isTrusted(manifest, namespace, hash) {
+  const entry = manifest.get(namespace);
+  if (entry === void 0) return false;
+  return entry.hashes.includes(hash);
+}
+
+// src/identity/trust.ts
+async function trySigstore(execPath) {
+  try {
+    const sigstore = await import('sigstore');
+    if (typeof sigstore !== "object" || sigstore === null) {
+      return false;
+    }
+    if (!("verify" in sigstore) || typeof sigstore.verify !== "function") {
+      return false;
+    }
+    void execPath;
+    return false;
+  } catch {
+    return false;
+  }
+}
+async function verifyTrust(execPath, options) {
+  if (execPath === "dev") {
+    return {
+      identity: { hash: "dev", trustTier: 3, verified: false },
+      tofuConflict: false,
+      reason: "Dev mode \u2014 hash verification skipped"
+    };
+  }
+  const configDir = options?.configDir ?? ".vaultkeeper";
+  const namespace = options?.namespace ?? execPath;
+  const currentHash = await hashExecutable(execPath);
+  const manifest = await loadManifest(configDir);
+  if (options?.skipSigstore !== true) {
+    const sigstoreVerified = await trySigstore(execPath);
+    if (sigstoreVerified) {
+      const updated2 = addTrustedHash(manifest, namespace, currentHash);
+      await saveManifest(configDir, updated2);
+      return {
+        identity: { hash: currentHash, trustTier: 1, verified: true },
+        tofuConflict: false,
+        reason: "Sigstore bundle verified"
+      };
+    }
+  }
+  if (isTrusted(manifest, namespace, currentHash)) {
+    return {
+      identity: { hash: currentHash, trustTier: 2, verified: true },
+      tofuConflict: false,
+      reason: "Hash found in trust manifest"
+    };
+  }
+  const existing = manifest.get(namespace);
+  if (existing !== void 0 && existing.hashes.length > 0) {
+    return {
+      identity: { hash: currentHash, trustTier: 3, verified: false },
+      tofuConflict: true,
+      reason: `Hash changed from a previously approved value \u2014 re-approval required`
+    };
+  }
+  const updated = addTrustedHash(manifest, namespace, currentHash);
+  await saveManifest(configDir, updated);
+  return {
+    identity: { hash: currentHash, trustTier: 3, verified: false },
+    tofuConflict: false,
+    reason: "First encounter \u2014 hash recorded via TOFU"
+  };
+}
+
+// src/identity/session.ts
+var CapabilityToken = class {
+  // Private field ensures no public surface leaks claims.
+  #brand;
+  constructor() {
+    this.#brand = /* @__PURE__ */ Symbol("CapabilityToken");
+  }
+  /**
+   * Return a non-enumerable identifier for debugging purposes only.
+   * Does NOT expose claims.
+   */
+  toString() {
+    return `[CapabilityToken ${this.#brand.toString()}]`;
+  }
+};
+var claimsStore = /* @__PURE__ */ new WeakMap();
+function createCapabilityToken(claims) {
+  const token = new CapabilityToken();
+  claimsStore.set(token, claims);
+  return token;
+}
+function validateCapabilityToken(token) {
+  const claims = claimsStore.get(token);
+  if (claims === void 0) {
+    throw new AuthorizationDeniedError("Invalid or unrecognized capability token");
+  }
+  return claims;
+}
+function getDefaultConfigDir() {
+  if (process.platform === "win32") {
+    const appData = process.env.APPDATA;
+    if (appData !== void 0) {
+      return path5.join(appData, "vaultkeeper");
+    }
+    return path5.join(os4.homedir(), "AppData", "Roaming", "vaultkeeper");
+  }
+  return path5.join(os4.homedir(), ".config", "vaultkeeper");
+}
+function defaultConfig() {
+  return {
+    version: 1,
+    backends: [{ type: "file", enabled: true }],
+    keyRotation: { gracePeriodDays: 7 },
+    defaults: { ttlMinutes: 60, trustTier: 3 }
+  };
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function validateBackendEntry(entry, index) {
+  if (!isObject(entry)) {
+    throw new Error(`backends[${String(index)}] must be an object`);
+  }
+  if (typeof entry.type !== "string" || entry.type.trim() === "") {
+    throw new Error(`backends[${String(index)}].type must be a non-empty string`);
+  }
+  if (typeof entry.enabled !== "boolean") {
+    throw new Error(`backends[${String(index)}].enabled must be a boolean`);
+  }
+  const result = {
+    type: entry.type,
+    enabled: entry.enabled
+  };
+  if (entry.plugin !== void 0) {
+    if (typeof entry.plugin !== "boolean") {
+      throw new Error(`backends[${String(index)}].plugin must be a boolean`);
+    }
+    result.plugin = entry.plugin;
+  }
+  if (entry.path !== void 0) {
+    if (typeof entry.path !== "string") {
+      throw new Error(`backends[${String(index)}].path must be a string`);
+    }
+    result.path = entry.path;
+  }
+  return result;
+}
+function validateConfig(config) {
+  if (!isObject(config)) {
+    throw new Error("Config must be an object");
+  }
+  if (typeof config.version !== "number" || config.version !== 1) {
+    throw new Error("Config version must be 1");
+  }
+  if (!Array.isArray(config.backends) || config.backends.length === 0) {
+    throw new Error("Config must have at least one backend");
+  }
+  const backends = config.backends.map(
+    (entry, i) => validateBackendEntry(entry, i)
+  );
+  if (!isObject(config.keyRotation)) {
+    throw new Error("Config keyRotation must be an object");
+  }
+  if (typeof config.keyRotation.gracePeriodDays !== "number" || config.keyRotation.gracePeriodDays <= 0) {
+    throw new Error("Config keyRotation.gracePeriodDays must be a positive number");
+  }
+  if (!isObject(config.defaults)) {
+    throw new Error("Config defaults must be an object");
+  }
+  if (typeof config.defaults.ttlMinutes !== "number" || config.defaults.ttlMinutes <= 0) {
+    throw new Error("Config defaults.ttlMinutes must be a positive number");
+  }
+  const tier = config.defaults.trustTier;
+  if (tier !== 1 && tier !== 2 && tier !== 3) {
+    throw new Error("Config defaults.trustTier must be 1, 2, or 3");
+  }
+  const result = {
+    version: 1,
+    backends,
+    keyRotation: {
+      gracePeriodDays: config.keyRotation.gracePeriodDays
+    },
+    defaults: {
+      ttlMinutes: config.defaults.ttlMinutes,
+      trustTier: tier
+    }
+  };
+  if (config.developmentMode !== void 0) {
+    if (!isObject(config.developmentMode)) {
+      throw new Error("Config developmentMode must be an object");
+    }
+    if (!Array.isArray(config.developmentMode.executables)) {
+      throw new Error("Config developmentMode.executables must be an array");
+    }
+    const executables = [];
+    for (const [i, exe] of Array.from(config.developmentMode.executables).entries()) {
+      if (typeof exe !== "string") {
+        throw new Error(`Config developmentMode.executables[${String(i)}] must be a string`);
+      }
+      executables.push(exe);
+    }
+    result.developmentMode = { executables };
+  }
+  return result;
+}
+async function loadConfig(configDir) {
+  const dir = configDir ?? getDefaultConfigDir();
+  const configPath = path5.join(dir, "config.json");
+  let raw;
+  try {
+    raw = await fs5.readFile(configPath, "utf-8");
+  } catch {
+    return defaultConfig();
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    throw new Error(`Failed to parse config file at ${configPath}`);
+  }
+  return validateConfig(parsed);
+}
+var KeyManager = class {
+  #state = void 0;
+  #gracePeriodTimer = void 0;
+  #gracePeriodExpiresAt = void 0;
+  #rotating = false;
+  /** Generate a new 32-byte key with a timestamp-based id. */
+  generateKey() {
+    const randomSuffix = crypto4.randomBytes(4).toString("hex");
+    return {
+      id: `k-${String(Date.now())}-${randomSuffix}`,
+      key: new Uint8Array(crypto4.randomBytes(32)),
+      createdAt: /* @__PURE__ */ new Date()
+    };
+  }
+  /**
+   * Initialize the manager with a freshly generated key.
+   * Safe to call multiple times; subsequent calls are no-ops.
+   */
+  init() {
+    if (this.#state === void 0) {
+      this.#state = { current: this.generateKey() };
+    }
+    return Promise.resolve();
+  }
+  /** Return the current (encryption) key. Throws if not initialized. */
+  getCurrentKey() {
+    const state = this.#requireState();
+    return state.current;
+  }
+  /**
+   * Return the previous key if we are still inside a grace period,
+   * otherwise `undefined`.
+   */
+  getPreviousKey() {
+    const state = this.#requireState();
+    return state.previous;
+  }
+  /**
+   * Find a key by its id, searching current then previous.
+   * Returns `undefined` if the key is not found (or the previous key's
+   * grace period has expired).
+   */
+  findKeyById(kid) {
+    const state = this.#requireState();
+    if (state.current.id === kid) {
+      return state.current;
+    }
+    const { previous } = state;
+    if (previous?.id === kid) {
+      return previous;
+    }
+    return void 0;
+  }
+  /**
+   * Rotate the current key: the current key becomes previous, a new key
+   * becomes current. A grace-period timer is started; when it fires the
+   * previous key is cleared automatically.
+   *
+   * @throws {RotationInProgressError} if a rotation is already underway.
+   */
+  rotateKey(gracePeriodMs) {
+    if (this.#rotating) {
+      throw new RotationInProgressError("A key rotation is already in progress");
+    }
+    const state = this.#requireState();
+    this.#rotating = true;
+    this.#clearGracePeriodTimer();
+    const newKey = this.generateKey();
+    this.#state = { current: newKey, previous: state.current };
+    this.#gracePeriodExpiresAt = Date.now() + gracePeriodMs;
+    this.#gracePeriodTimer = setTimeout(() => {
+      if (this.#state !== void 0) {
+        this.#state = { current: this.#state.current };
+      }
+      this.#gracePeriodExpiresAt = void 0;
+      this.#gracePeriodTimer = void 0;
+      this.#rotating = false;
+    }, gracePeriodMs);
+    if (typeof this.#gracePeriodTimer.unref === "function") {
+      this.#gracePeriodTimer.unref();
+    }
+  }
+  /**
+   * Emergency revocation: immediately clear the previous key and generate
+   * a brand-new current key. Any in-flight grace period is cancelled.
+   */
+  revokeKey() {
+    this.#clearGracePeriodTimer();
+    this.#rotating = false;
+    this.#gracePeriodExpiresAt = void 0;
+    const newKey = this.generateKey();
+    this.#state = { current: newKey };
+  }
+  /**
+   * Return `true` while a rotation grace period is active (i.e. the previous
+   * key is still accessible).
+   */
+  isInGracePeriod() {
+    if (this.#gracePeriodExpiresAt === void 0) {
+      return false;
+    }
+    return Date.now() < this.#gracePeriodExpiresAt;
+  }
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+  #requireState() {
+    if (this.#state === void 0) {
+      throw new SetupError(
+        "KeyManager has not been initialized \u2014 call init() first",
+        "KeyManager"
+      );
+    }
+    return this.#state;
+  }
+  #clearGracePeriodTimer() {
+    if (this.#gracePeriodTimer !== void 0) {
+      clearTimeout(this.#gracePeriodTimer);
+      this.#gracePeriodTimer = void 0;
+    }
+  }
+};
+var ALGORITHM = "dir";
+var ENCRYPTION = "A256GCM";
+async function createToken(key, claims, options) {
+  const plaintext = new TextEncoder().encode(JSON.stringify(claims));
+  const header = {
+    alg: ALGORITHM,
+    enc: ENCRYPTION
+  };
+  if (options?.kid !== void 0) {
+    header.kid = options.kid;
+  }
+  return new CompactEncrypt(plaintext).setProtectedHeader(header).encrypt(key);
+}
+function isObject2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function parseVaultClaims(raw) {
+  if (!isObject2(raw)) {
+    return void 0;
+  }
+  const { jti, exp, iat, sub, exe, use, tid, bkd, val, ref } = raw;
+  if (typeof jti !== "string") return void 0;
+  if (typeof exp !== "number") return void 0;
+  if (typeof iat !== "number") return void 0;
+  if (typeof sub !== "string") return void 0;
+  if (typeof exe !== "string") return void 0;
+  if (use !== null && typeof use !== "number") return void 0;
+  if (tid !== 1 && tid !== 2 && tid !== 3) return void 0;
+  if (typeof bkd !== "string") return void 0;
+  if (typeof val !== "string") return void 0;
+  if (typeof ref !== "string") return void 0;
+  return { jti, exp, iat, sub, exe, use: use ?? null, tid, bkd, val, ref };
+}
+async function decryptToken(key, jwe) {
+  let plaintext;
+  try {
+    const result = await compactDecrypt(jwe, key);
+    plaintext = result.plaintext;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    throw new VaultError(`JWE decryption failed: ${message}`);
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(new TextDecoder().decode(plaintext));
+  } catch {
+    throw new VaultError("JWE payload is not valid JSON");
+  }
+  const claims = parseVaultClaims(parsed);
+  if (claims === void 0) {
+    throw new VaultError("JWE payload does not match VaultClaims schema");
+  }
+  return claims;
+}
+function extractKid(jwe) {
+  const parts = jwe.split(".");
+  if (parts.length !== 5) {
+    throw new VaultError("Invalid JWE compact serialization: expected 5 parts");
+  }
+  const headerSegment = parts[0];
+  if (headerSegment === void 0 || headerSegment === "") {
+    throw new VaultError("Invalid JWE compact serialization: missing header segment");
+  }
+  let headerJson;
+  try {
+    headerJson = Buffer.from(headerSegment, "base64url").toString("utf-8");
+  } catch {
+    throw new VaultError("Invalid JWE compact serialization: header is not valid Base64URL");
+  }
+  let header;
+  try {
+    header = JSON.parse(headerJson);
+  } catch {
+    throw new VaultError("Invalid JWE compact serialization: header is not valid JSON");
+  }
+  if (!isObject2(header)) {
+    return void 0;
+  }
+  const kid = header.kid;
+  if (typeof kid !== "string") {
+    return void 0;
+  }
+  return kid;
+}
+
+// src/jwe/claims.ts
+var BLOCKLIST_MAX_SIZE = 1e4;
+var blocklist = /* @__PURE__ */ new Map();
+function blockToken(jti) {
+  if (blocklist.has(jti)) {
+    blocklist.delete(jti);
+  } else if (blocklist.size >= BLOCKLIST_MAX_SIZE) {
+    const oldestKey = blocklist.keys().next().value;
+    if (oldestKey !== void 0) {
+      blocklist.delete(oldestKey);
+    }
+  }
+  blocklist.set(jti, true);
+}
+function isBlocked(jti) {
+  return blocklist.has(jti);
+}
+function validateClaims(claims, usedCount = 0) {
+  if (claims.jti.trim() === "") {
+    throw new VaultError("Invalid token: jti must not be empty");
+  }
+  if (claims.sub.trim() === "") {
+    throw new VaultError("Invalid token: sub must not be empty");
+  }
+  if (claims.exe.trim() === "") {
+    throw new VaultError("Invalid token: exe must not be empty");
+  }
+  if (claims.bkd.trim() === "") {
+    throw new VaultError("Invalid token: bkd must not be empty");
+  }
+  if (claims.val.trim() === "") {
+    throw new VaultError("Invalid token: val must not be empty");
+  }
+  if (claims.ref.trim() === "") {
+    throw new VaultError("Invalid token: ref must not be empty");
+  }
+  if (claims.iat > claims.exp) {
+    throw new VaultError("Invalid token: iat must not be after exp");
+  }
+  const nowSec = Math.floor(Date.now() / 1e3);
+  if (nowSec >= claims.exp) {
+    throw new TokenExpiredError(
+      `Token expired at ${String(claims.exp)} (now: ${String(nowSec)})`,
+      false
+    );
+  }
+  if (isBlocked(claims.jti)) {
+    throw new TokenRevokedError(`Token ${claims.jti} has been revoked`);
+  }
+  if (claims.use !== null) {
+    if (claims.use <= 0) {
+      throw new UsageLimitExceededError(
+        `Token ${claims.jti} has a non-positive usage limit: ${String(claims.use)}`
+      );
+    }
+    if (usedCount >= claims.use) {
+      throw new UsageLimitExceededError(
+        `Token ${claims.jti} usage limit of ${String(claims.use)} exceeded (used: ${String(usedCount)})`
+      );
+    }
+  }
+}
+
+// src/access/delegated-fetch.ts
+var PLACEHOLDER = "{{secret}}";
+function replacePlaceholder(value, secret) {
+  return value.replaceAll(PLACEHOLDER, secret);
+}
+function replaceInRecord(record, secret) {
+  const result = {};
+  for (const [key, value] of Object.entries(record)) {
+    result[key] = replacePlaceholder(value, secret);
+  }
+  return result;
+}
+async function delegatedFetch(secret, request) {
+  const url = replacePlaceholder(request.url, secret);
+  const headers = request.headers !== void 0 ? replaceInRecord(request.headers, secret) : void 0;
+  const body = request.body !== void 0 ? replacePlaceholder(request.body, secret) : void 0;
+  const init = {};
+  if (request.method !== void 0) {
+    init.method = request.method;
+  }
+  if (headers !== void 0) {
+    init.headers = headers;
+  }
+  if (body !== void 0) {
+    init.body = body;
+  }
+  return fetch(url, init);
+}
+var PLACEHOLDER2 = "{{secret}}";
+function replacePlaceholder2(value, secret) {
+  return value.replaceAll(PLACEHOLDER2, secret);
+}
+function replaceInRecord2(record, secret) {
+  const result = {};
+  for (const [key, value] of Object.entries(record)) {
+    result[key] = replacePlaceholder2(value, secret);
+  }
+  return result;
+}
+function delegatedExec(secret, request) {
+  const args = (request.args ?? []).map((arg) => replacePlaceholder2(arg, secret));
+  const env = request.env !== void 0 ? replaceInRecord2(request.env, secret) : void 0;
+  return new Promise((resolve, reject) => {
+    const spawnOptions = {
+      stdio: ["ignore", "pipe", "pipe"]
+    };
+    if (env !== void 0) {
+      spawnOptions.env = { ...process.env, ...env };
+    }
+    if (request.cwd !== void 0) {
+      spawnOptions.cwd = request.cwd;
+    }
+    const proc = spawn(request.command, args, spawnOptions);
+    let stdout = "";
+    let stderr = "";
+    proc.stdout?.on("data", (data) => {
+      stdout += data.toString();
+    });
+    proc.stderr?.on("data", (data) => {
+      stderr += data.toString();
+    });
+    proc.on("close", (code) => {
+      resolve({ stdout, stderr, exitCode: code ?? 1 });
+    });
+    proc.on("error", (error) => {
+      reject(error);
+    });
+  });
+}
+
+// src/access/controlled-direct.ts
+var INSPECT_CUSTOM = /* @__PURE__ */ Symbol.for("nodejs.util.inspect.custom");
+var SecretAccessorTarget = class {
+  read;
+  [INSPECT_CUSTOM];
+  constructor(readImpl, inspectImpl) {
+    this.read = readImpl;
+    this[INSPECT_CUSTOM] = inspectImpl;
+  }
+};
+function createSecretAccessor(secretValue) {
+  let consumed = false;
+  const revokeHolder = { fn: void 0 };
+  function readImpl(callback) {
+    if (consumed) {
+      throw new Error("SecretAccessor has already been consumed \u2014 call getSecret() again to obtain a new accessor");
+    }
+    consumed = true;
+    const buf = Buffer.from(secretValue, "utf8");
+    try {
+      callback(buf);
+    } finally {
+      buf.fill(0);
+      revokeHolder.fn?.();
+    }
+  }
+  function inspectImpl() {
+    return "[SecretAccessor]";
+  }
+  const target = new SecretAccessorTarget(readImpl, inspectImpl);
+  Object.setPrototypeOf(target, null);
+  Object.preventExtensions(target);
+  const handler = {
+    get(_t, prop, _receiver) {
+      if (prop === "read") return readImpl;
+      if (prop === INSPECT_CUSTOM) return inspectImpl;
+      return void 0;
+    },
+    set(_t, _prop, _value, _receiver) {
+      return false;
+    },
+    has(_t, prop) {
+      return prop === "read" || prop === INSPECT_CUSTOM;
+    },
+    deleteProperty(_t, _prop) {
+      return false;
+    },
+    apply(_t, _thisArg, _args) {
+      throw new TypeError("SecretAccessor is not a function");
+    },
+    construct(_t, _args, _newTarget) {
+      throw new TypeError("SecretAccessor is not a constructor");
+    },
+    defineProperty(_t, _prop, _descriptor) {
+      return false;
+    },
+    getOwnPropertyDescriptor(_t, prop) {
+      if (prop === "read") {
+        return { configurable: true, enumerable: true, writable: false, value: readImpl };
+      }
+      if (prop === INSPECT_CUSTOM) {
+        return { configurable: true, enumerable: false, writable: false, value: inspectImpl };
+      }
+      return void 0;
+    },
+    getPrototypeOf(_t) {
+      return null;
+    },
+    setPrototypeOf(_t, _proto) {
+      return false;
+    },
+    isExtensible(_t) {
+      return false;
+    },
+    preventExtensions(_t) {
+      return true;
+    },
+    ownKeys(_t) {
+      return ["read", INSPECT_CUSTOM];
+    }
+  };
+  const { proxy, revoke } = Proxy.revocable(target, handler);
+  revokeHolder.fn = revoke;
+  return proxy;
+}
+
+// src/doctor/checks.ts
+function parseVersion(raw) {
+  const match = /(\d+)\.(\d+)\.(\d+)/.exec(raw);
+  if (!match) return null;
+  const major = parseInt(match[1] ?? "0", 10);
+  const minor = parseInt(match[2] ?? "0", 10);
+  const patch = parseInt(match[3] ?? "0", 10);
+  return [major, minor, patch];
+}
+function versionGte(a, b) {
+  if (a[0] !== b[0]) return a[0] > b[0];
+  if (a[1] !== b[1]) return a[1] > b[1];
+  return a[2] >= b[2];
+}
+async function checkOpenssl() {
+  const name = "openssl";
+  try {
+    const output = await execCommand("openssl", ["version"]);
+    const parsed = parseVersion(output);
+    if (!parsed) {
+      return {
+        name,
+        status: "version-unsupported",
+        version: output,
+        reason: "Could not parse openssl version"
+      };
+    }
+    if (!versionGte(parsed, [1, 1, 1])) {
+      return {
+        name,
+        status: "version-unsupported",
+        version: output,
+        reason: "openssl >= 1.1.1 is required"
+      };
+    }
+    return { name, status: "ok", version: output };
+  } catch {
+    return { name, status: "missing", reason: "openssl not found in PATH" };
+  }
+}
+async function checkBash() {
+  const name = "bash";
+  try {
+    const output = await execCommand("bash", ["--version"]);
+    const firstLine = output.split("\n")[0] ?? output;
+    return { name, status: "ok", version: firstLine };
+  } catch {
+    return { name, status: "missing", reason: "bash not found in PATH" };
+  }
+}
+async function checkPowershell() {
+  const name = "powershell";
+  try {
+    const output = await execCommand("powershell", [
+      "-Command",
+      "$PSVersionTable.PSVersion"
+    ]);
+    const version = output.trim();
+    return { name, status: "ok", version };
+  } catch {
+    return { name, status: "missing", reason: "powershell not found in PATH" };
+  }
+}
+async function checkSecurity() {
+  const name = "security";
+  try {
+    await execCommand("security", ["help"]);
+    return { name, status: "ok" };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.includes("security")) {
+      return { name, status: "ok" };
+    }
+    return {
+      name,
+      status: "missing",
+      reason: "security command not found in PATH"
+    };
+  }
+}
+async function checkSecretTool() {
+  const name = "secret-tool";
+  try {
+    const output = await execCommand("secret-tool", ["--version"]);
+    return { name, status: "ok", version: output.trim() };
+  } catch {
+    return {
+      name,
+      status: "missing",
+      reason: "secret-tool not found in PATH (install libsecret-tools)"
+    };
+  }
+}
+async function checkOp() {
+  const name = "op";
+  try {
+    const output = await execCommand("op", ["--version"]);
+    return { name, status: "ok", version: output.trim() };
+  } catch {
+    return {
+      name,
+      status: "missing",
+      reason: "op (1Password CLI) not found in PATH"
+    };
+  }
+}
+async function checkYkman() {
+  const name = "ykman";
+  try {
+    const output = await execCommand("ykman", ["--version"]);
+    return { name, status: "ok", version: output.trim() };
+  } catch {
+    return {
+      name,
+      status: "missing",
+      reason: "ykman (YubiKey Manager) not found in PATH"
+    };
+  }
+}
+
+// src/util/platform.ts
+function currentPlatform() {
+  const p = process.platform;
+  if (p === "darwin" || p === "win32" || p === "linux") {
+    return p;
+  }
+  throw new Error(`Unsupported platform: ${p}`);
+}
+
+// src/doctor/runner.ts
+async function runDoctor(options) {
+  const platform = currentPlatform();
+  const entries = buildCheckList(platform);
+  const resolved = await Promise.all(
+    entries.map(async ({ check, required }) => {
+      const result = await check();
+      return { required, result };
+    })
+  );
+  const ready = resolved.every(({ required, result }) => {
+    if (!required) return true;
+    return result.status === "ok";
+  });
+  const warnings = [];
+  const nextSteps = [];
+  for (const { required, result } of resolved) {
+    if (result.status === "missing") {
+      if (required) {
+        nextSteps.push(`Install missing required dependency: ${result.name}`);
+      } else {
+        warnings.push(
+          `Optional dependency not found: ${result.name}${result.reason !== void 0 ? ` \u2014 ${result.reason}` : ""}`
+        );
+      }
+    } else if (result.status === "version-unsupported") {
+      const msg = `${result.name} version is unsupported${result.reason !== void 0 ? `: ${result.reason}` : ""}`;
+      if (required) {
+        nextSteps.push(`Upgrade required dependency: ${msg}`);
+      } else {
+        warnings.push(`Optional dependency version unsupported: ${msg}`);
+      }
+    }
+  }
+  const checks = resolved.map(({ result }) => result);
+  return { checks, ready, warnings, nextSteps };
+}
+function buildCheckList(platform) {
+  const entries = [{ check: checkOpenssl, required: true }];
+  if (platform === "darwin") {
+    entries.push({ check: checkSecurity, required: true });
+    entries.push({ check: checkBash, required: false });
+  } else if (platform === "win32") {
+    entries.push({ check: checkPowershell, required: true });
+  } else {
+    entries.push({ check: checkBash, required: true });
+    entries.push({ check: checkSecretTool, required: true });
+  }
+  entries.push({ check: checkOp, required: false });
+  entries.push({ check: checkYkman, required: false });
+  return entries;
+}
+
+// src/vault.ts
+var usageCounts = /* @__PURE__ */ new Map();
+var VaultKeeper = class _VaultKeeper {
+  #config;
+  #keyManager;
+  #configDir;
+  #backend;
+  constructor(config, keyManager, configDir) {
+    this.#config = config;
+    this.#keyManager = keyManager;
+    this.#configDir = configDir;
+  }
+  /**
+   * Initialize a new VaultKeeper instance.
+   * Runs doctor checks (unless skipped), loads config, and sets up the key manager.
+   */
+  static async init(options) {
+    if (options?.skipDoctor !== true) {
+      const doctorResult = await runDoctor();
+      if (!doctorResult.ready) {
+        throw new VaultError(
+          `System not ready: ${doctorResult.nextSteps.join("; ")}`
+        );
+      }
+    }
+    const configDir = options?.configDir ?? getDefaultConfigDir();
+    const config = options?.config ?? await loadConfig(configDir);
+    const keyManager = new KeyManager();
+    await keyManager.init();
+    const vault = new _VaultKeeper(config, keyManager, configDir);
+    vault.#backend = vault.#resolveBackend();
+    return vault;
+  }
+  /** Run doctor checks without full initialization. */
+  static async doctor() {
+    return runDoctor();
+  }
+  /**
+   * Store a secret and return a JWE token that encapsulates it.
+   *
+   * @param secretName - Identifier for the secret
+   * @param options - Setup options
+   * @returns Compact JWE string
+   */
+  async setup(secretName, options) {
+    const backend = this.#requireBackend();
+    const backendType = options?.backendType ?? backend.type;
+    const ttlMinutes = options?.ttlMinutes ?? this.#config.defaults.ttlMinutes;
+    const trustTier = options?.trustTier ?? this.#config.defaults.trustTier;
+    const useLimit = options?.useLimit ?? null;
+    const executablePath = options?.executablePath ?? "dev";
+    const secretValue = await backend.retrieve(secretName);
+    let exeIdentity;
+    if (executablePath === "dev" || this.#isDevModeExecutable(executablePath)) {
+      exeIdentity = "dev";
+    } else {
+      const trustResult = await verifyTrust(executablePath, {
+        configDir: this.#configDir
+      });
+      if (trustResult.tofuConflict) {
+        throw new IdentityMismatchError(
+          "Executable hash changed \u2014 re-approval required",
+          "previously-approved",
+          trustResult.identity.hash
+        );
+      }
+      exeIdentity = trustResult.identity.hash;
+    }
+    const now = Math.floor(Date.now() / 1e3);
+    const claims = {
+      jti: crypto4.randomUUID(),
+      exp: now + ttlMinutes * 60,
+      iat: now,
+      sub: secretName,
+      exe: exeIdentity,
+      use: useLimit,
+      tid: trustTier,
+      bkd: backendType,
+      val: secretValue,
+      ref: secretName
+    };
+    const currentKey = this.#keyManager.getCurrentKey();
+    return createToken(currentKey.key, claims, { kid: currentKey.id });
+  }
+  /**
+   * Decrypt a JWE, validate claims, verify executable identity, and return
+   * an opaque CapabilityToken.
+   *
+   * @param jwe - Compact JWE string from setup()
+   * @returns Opaque capability token for use with fetch/exec/getSecret
+   */
+  async authorize(jwe) {
+    const kid = extractKid(jwe);
+    const { claims, keyStatus } = await this.#decryptWithKeyResolution(jwe, kid);
+    const jti = claims.jti;
+    const currentCount = usageCounts.get(jti) ?? 0;
+    validateClaims(claims, currentCount);
+    const newCount = currentCount + 1;
+    if (claims.use !== null && newCount >= claims.use) {
+      usageCounts.delete(jti);
+      blockToken(jti);
+    } else {
+      usageCounts.set(jti, newCount);
+    }
+    const token = createCapabilityToken(claims);
+    const response = { keyStatus };
+    if (keyStatus === "previous") {
+      const currentKey = this.#keyManager.getCurrentKey();
+      const rotatedJwt = await createToken(currentKey.key, claims, { kid: currentKey.id });
+      response.rotatedJwt = rotatedJwt;
+    }
+    return { token, response };
+  }
+  /**
+   * Execute a delegated HTTP fetch, injecting the secret from the token.
+   *
+   * The secret value is substituted for every `{{secret}}` placeholder found
+   * in `request.url`, `request.headers`, and `request.body` before the fetch
+   * is executed. The raw secret is never exposed in the return value.
+   *
+   * @param token - A `CapabilityToken` obtained from `authorize()`.
+   * @param request - The fetch request template. Use `{{secret}}` as a
+   *   placeholder wherever the secret value should be injected.
+   * @returns The `Response` from the underlying `fetch()` call, together with
+   *   the vault metadata (`vaultResponse`).
+   * @throws {Error} If `token` is invalid or was not created by this vault
+   *   instance.
+   */
+  async fetch(token, request) {
+    const claims = validateCapabilityToken(token);
+    const response = await delegatedFetch(claims.val, request);
+    return {
+      response,
+      vaultResponse: { keyStatus: "current" }
+    };
+  }
+  /**
+   * Execute a delegated command, injecting the secret from the token.
+   *
+   * The secret value is substituted for every `{{secret}}` placeholder found
+   * in `request.args` and `request.env` values before the process is spawned.
+   * The raw secret is never exposed in the return value.
+   *
+   * @param token - A `CapabilityToken` obtained from `authorize()`.
+   * @param request - The exec request template. Use `{{secret}}` as a
+   *   placeholder wherever the secret value should be injected.
+   * @returns The command result (`stdout`, `stderr`, `exitCode`) together with
+   *   the vault metadata (`vaultResponse`).
+   * @throws {Error} If `token` is invalid or was not created by this vault
+   *   instance.
+   */
+  async exec(token, request) {
+    const claims = validateCapabilityToken(token);
+    const result = await delegatedExec(claims.val, request);
+    return {
+      result,
+      vaultResponse: { keyStatus: "current" }
+    };
+  }
+  /**
+   * Create a controlled-direct `SecretAccessor` from a capability token.
+   *
+   * The accessor wraps the secret in a single-use, auto-zeroing `Buffer`. The
+   * secret is accessible only through the `read()` callback and is zeroed
+   * immediately after the callback returns.
+   *
+   * @param token - A `CapabilityToken` obtained from `authorize()`.
+   * @returns A `SecretAccessor` that can be read exactly once.
+   * @throws {Error} If `token` is invalid or was not created by this vault
+   *   instance.
+   */
+  getSecret(token) {
+    const claims = validateCapabilityToken(token);
+    return createSecretAccessor(claims.val);
+  }
+  /**
+   * Rotate the current encryption key.
+   *
+   * The previous key remains valid for decryption during the grace period
+   * configured in `keyRotation.gracePeriodDays`. JWEs presented during the
+   * grace period return a `rotatedJwt` in the `VaultResponse` so callers can
+   * persist the updated token.
+   *
+   * @throws {RotationInProgressError} If a rotation is already in progress
+   *   (i.e. a previous key is still within its grace period).
+   */
+  async rotateKey() {
+    const gracePeriodMs = this.#config.keyRotation.gracePeriodDays * 24 * 60 * 60 * 1e3;
+    this.#keyManager.rotateKey(gracePeriodMs);
+    await Promise.resolve();
+  }
+  /**
+   * Emergency key revocation — invalidates the previous key immediately.
+   *
+   * After revocation, any JWE that was encrypted with the revoked key will
+   * be permanently unreadable. A new encryption key is generated automatically
+   * so that `setup()` can be called immediately after revocation.
+   */
+  async revokeKey() {
+    this.#keyManager.revokeKey();
+    await Promise.resolve();
+  }
+  /**
+   * Add or remove an executable from the development-mode whitelist.
+   *
+   * When an executable is in the development-mode list, identity verification
+   * (TOFU hash checking) is skipped for that executable during `setup()`. This
+   * is intended for local development workflows where the binary changes
+   * frequently.
+   *
+   * @param executablePath - Absolute path to the executable to add or remove.
+   * @param enabled - Pass `true` to add the executable to the list, `false`
+   *   to remove it.
+   */
+  async setDevelopmentMode(executablePath, enabled) {
+    if (this.#config.developmentMode === void 0) {
+      if (enabled) {
+        this.#config.developmentMode = { executables: [executablePath] };
+      }
+      return;
+    }
+    const exes = this.#config.developmentMode.executables;
+    const idx = exes.indexOf(executablePath);
+    if (enabled && idx === -1) {
+      exes.push(executablePath);
+    } else if (!enabled && idx !== -1) {
+      exes.splice(idx, 1);
+    }
+    await Promise.resolve();
+  }
+  // ---------------------------------------------------------------------------
+  // Private helpers
+  // ---------------------------------------------------------------------------
+  #resolveBackend() {
+    const enabledBackends = this.#config.backends.filter((b) => b.enabled);
+    if (enabledBackends.length === 0) {
+      throw new BackendUnavailableError(
+        "No enabled backends configured",
+        "none-enabled",
+        this.#config.backends.map((b) => b.type)
+      );
+    }
+    const firstEnabled = enabledBackends[0];
+    if (firstEnabled === void 0) {
+      throw new BackendUnavailableError(
+        "No enabled backends configured",
+        "none-enabled",
+        []
+      );
+    }
+    return BackendRegistry.create(firstEnabled.type);
+  }
+  #requireBackend() {
+    if (this.#backend === void 0) {
+      throw new VaultError("VaultKeeper backend not initialized");
+    }
+    return this.#backend;
+  }
+  #isDevModeExecutable(executablePath) {
+    if (this.#config.developmentMode === void 0) {
+      return false;
+    }
+    return this.#config.developmentMode.executables.includes(executablePath);
+  }
+  async #decryptWithKeyResolution(jwe, kid) {
+    if (kid !== void 0) {
+      const key = this.#keyManager.findKeyById(kid);
+      if (key !== void 0) {
+        const claims = await decryptToken(key.key, jwe);
+        const isCurrent = key.id === this.#keyManager.getCurrentKey().id;
+        return {
+          claims,
+          keyStatus: isCurrent ? "current" : "previous"
+        };
+      }
+      throw new KeyRevokedError(`Key ${kid} not found \u2014 may have been revoked`);
+    }
+    try {
+      const claims = await decryptToken(this.#keyManager.getCurrentKey().key, jwe);
+      return { claims, keyStatus: "current" };
+    } catch {
+      const previousKey = this.#keyManager.getPreviousKey();
+      if (previousKey !== void 0) {
+        const claims = await decryptToken(previousKey.key, jwe);
+        return { claims, keyStatus: "previous" };
+      }
+      throw new VaultError("Failed to decrypt JWE with any available key");
+    }
+  }
+};
+
+export { AuthorizationDeniedError, BackendLockedError, BackendRegistry, BackendUnavailableError, CapabilityToken, DeviceNotPresentError, FilesystemError, IdentityMismatchError, KeyRevokedError, KeyRotatedError, PluginNotFoundError, RotationInProgressError, SecretNotFoundError, SetupError, TokenExpiredError, TokenRevokedError, UsageLimitExceededError, VaultError, VaultKeeper, isListableBackend };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map