vaultkeeper 0.2.0 → 0.4.0

package/dist/index.d.cts

@@ -287,6 +287,59 @@ interface SecretAccessor {
      */
     read(callback: (buf: Buffer) => void): void;
 }
+/**
+ * Request for delegated signing.
+ *
+ * The `data` field is the payload to sign. Strings are UTF-8-encoded
+ * before signing.
+ */
+interface SignRequest {
+    /** The data to sign. Strings are treated as UTF-8. */
+    data: string | Buffer;
+    /**
+     * Override the hash algorithm (`'sha256'`, `'sha384'`, or `'sha512'`).
+     * Ignored for Ed25519/Ed448 keys where the algorithm is implicit.
+     * Non-Edwards keys (RSA, EC) default to `'sha256'` when omitted.
+     * Weak algorithms (e.g. `'md5'`, `'sha1'`) are rejected.
+     */
+    algorithm?: string | undefined;
+}
+/** Result from a delegated signing operation. */
+interface SignResult {
+    /** Base64-encoded signature. */
+    signature: string;
+    /**
+     * Algorithm label describing how the signature was produced.
+     * For Edwards keys this is the key type (e.g. `'ed25519'`).
+     * For other keys this matches the `algorithm` field from the request
+     * (or the default `'sha256'`).
+     */
+    algorithm: string;
+}
+/**
+ * Request for signature verification.
+ *
+ * This is a static operation that only requires public key material —
+ * no VaultKeeper instance or capability token is needed.
+ */
+interface VerifyRequest {
+    /** The original data that was signed. Strings are treated as UTF-8. */
+    data: string | Buffer;
+    /** Base64-encoded signature to verify. */
+    signature: string;
+    /**
+     * PEM-encoded public key (SPKI format) as a string.
+     *
+     * Other `KeyLike` formats supported by `crypto.createPublicKey()` are not
+     * accepted by this interface.
+     */
+    publicKey: string;
+    /**
+     * Override the hash algorithm. Ignored for Ed25519/Ed448 keys.
+     * Non-Edwards keys default to `'sha256'` when omitted.
+     */
+    algorithm?: string | undefined;
+}
 /** Vaultkeeper configuration file structure. */
 interface VaultConfig {
     /** Config schema version. Currently must be `1`. */
@@ -379,6 +432,22 @@ interface SecretBackend {
      */
     exists(id: string): Promise<boolean>;
 }
+/**
+ * Backend that can enumerate stored secret IDs.
+ * @public
+ */
+interface ListableBackend extends SecretBackend {
+    /**
+     * List IDs of all secrets managed by this backend.
+     * @returns Array of secret identifiers
+     */
+    list(): Promise<string[]>;
+}
+/**
+ * Type guard for backends that support listing.
+ * @public
+ */
+declare function isListableBackend(backend: SecretBackend): backend is ListableBackend;
 
 /**
  * Registry for secret backend implementations.
@@ -418,6 +487,19 @@ declare class BackendRegistry {
      * @returns Array of backend type identifiers
      */
     static getTypes(): string[];
+    /**
+     * 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 getAvailableTypes(): Promise<string[]>;
 }
 
 /**
@@ -549,6 +631,40 @@ declare class VaultKeeper {
      *   instance.
      */
     getSecret(token: CapabilityToken): SecretAccessor;
+    /**
+     * Sign data using the private key embedded in a capability token.
+     *
+     * The signing key is extracted from the token's encrypted claims, used
+     * for a single `crypto.sign()` call, and never exposed to the caller.
+     * The algorithm is auto-detected from the key type unless overridden
+     * in the request.
+     *
+     * @param token - A `CapabilityToken` obtained from `authorize()`.
+     * @param request - The data to sign and optional algorithm override.
+     * @returns The base64-encoded signature and algorithm label, together
+     *   with the vault metadata (`vaultResponse`).
+     * @throws {VaultError} If `token` is invalid or was not created by this
+     *   vault instance.
+     */
+    sign(token: CapabilityToken, request: SignRequest): Promise<{
+        result: SignResult;
+        vaultResponse: VaultResponse;
+    }>;
+    /**
+     * Verify a signature using a public key.
+     *
+     * This is a static method — no VaultKeeper instance, secrets, or
+     * capability tokens are required. It is safe to call from CI or any
+     * context that has access to public key material.
+     *
+     * Never throws. Returns `false` for invalid key material, malformed
+     * signatures, or any verification failure.
+     *
+     * @param request - The data, signature, public key, and optional
+     *   algorithm override.
+     * @returns `true` if the signature is valid, `false` otherwise.
+     */
+    static verify(request: VerifyRequest): boolean;
     /**
      * Rotate the current encryption key.
      *
@@ -584,4 +700,4 @@ declare class VaultKeeper {
     setDevelopmentMode(executablePath: string, enabled: boolean): Promise<void>;
 }
 
-export { AuthorizationDeniedError, type BackendConfig, type BackendFactory, BackendLockedError, BackendRegistry, BackendUnavailableError, CapabilityToken, DeviceNotPresentError, type ExecRequest, type ExecResult, type FetchRequest, FilesystemError, IdentityMismatchError, KeyRevokedError, KeyRotatedError, type KeyStatus, PluginNotFoundError, type PreflightCheck, type PreflightCheckStatus, type PreflightResult, RotationInProgressError, type SecretAccessor, type SecretBackend, SecretNotFoundError, SetupError, type SetupOptions, TokenExpiredError, TokenRevokedError, type TrustTier, UsageLimitExceededError, type VaultConfig, VaultError, VaultKeeper, type VaultKeeperOptions, type VaultResponse };
+export { AuthorizationDeniedError, type BackendConfig, type BackendFactory, BackendLockedError, BackendRegistry, BackendUnavailableError, CapabilityToken, DeviceNotPresentError, type ExecRequest, type ExecResult, type FetchRequest, FilesystemError, IdentityMismatchError, KeyRevokedError, KeyRotatedError, type KeyStatus, type ListableBackend, PluginNotFoundError, type PreflightCheck, type PreflightCheckStatus, type PreflightResult, RotationInProgressError, type SecretAccessor, type SecretBackend, SecretNotFoundError, SetupError, type SetupOptions, type SignRequest, type SignResult, TokenExpiredError, TokenRevokedError, type TrustTier, UsageLimitExceededError, type VaultConfig, VaultError, VaultKeeper, type VaultKeeperOptions, type VaultResponse, type VerifyRequest, isListableBackend };

package/dist/index.d.ts

@@ -287,6 +287,59 @@ interface SecretAccessor {
      */
     read(callback: (buf: Buffer) => void): void;
 }
+/**
+ * Request for delegated signing.
+ *
+ * The `data` field is the payload to sign. Strings are UTF-8-encoded
+ * before signing.
+ */
+interface SignRequest {
+    /** The data to sign. Strings are treated as UTF-8. */
+    data: string | Buffer;
+    /**
+     * Override the hash algorithm (`'sha256'`, `'sha384'`, or `'sha512'`).
+     * Ignored for Ed25519/Ed448 keys where the algorithm is implicit.
+     * Non-Edwards keys (RSA, EC) default to `'sha256'` when omitted.
+     * Weak algorithms (e.g. `'md5'`, `'sha1'`) are rejected.
+     */
+    algorithm?: string | undefined;
+}
+/** Result from a delegated signing operation. */
+interface SignResult {
+    /** Base64-encoded signature. */
+    signature: string;
+    /**
+     * Algorithm label describing how the signature was produced.
+     * For Edwards keys this is the key type (e.g. `'ed25519'`).
+     * For other keys this matches the `algorithm` field from the request
+     * (or the default `'sha256'`).
+     */
+    algorithm: string;
+}
+/**
+ * Request for signature verification.
+ *
+ * This is a static operation that only requires public key material —
+ * no VaultKeeper instance or capability token is needed.
+ */
+interface VerifyRequest {
+    /** The original data that was signed. Strings are treated as UTF-8. */
+    data: string | Buffer;
+    /** Base64-encoded signature to verify. */
+    signature: string;
+    /**
+     * PEM-encoded public key (SPKI format) as a string.
+     *
+     * Other `KeyLike` formats supported by `crypto.createPublicKey()` are not
+     * accepted by this interface.
+     */
+    publicKey: string;
+    /**
+     * Override the hash algorithm. Ignored for Ed25519/Ed448 keys.
+     * Non-Edwards keys default to `'sha256'` when omitted.
+     */
+    algorithm?: string | undefined;
+}
 /** Vaultkeeper configuration file structure. */
 interface VaultConfig {
     /** Config schema version. Currently must be `1`. */
@@ -379,6 +432,22 @@ interface SecretBackend {
      */
     exists(id: string): Promise<boolean>;
 }
+/**
+ * Backend that can enumerate stored secret IDs.
+ * @public
+ */
+interface ListableBackend extends SecretBackend {
+    /**
+     * List IDs of all secrets managed by this backend.
+     * @returns Array of secret identifiers
+     */
+    list(): Promise<string[]>;
+}
+/**
+ * Type guard for backends that support listing.
+ * @public
+ */
+declare function isListableBackend(backend: SecretBackend): backend is ListableBackend;
 
 /**
  * Registry for secret backend implementations.
@@ -418,6 +487,19 @@ declare class BackendRegistry {
      * @returns Array of backend type identifiers
      */
     static getTypes(): string[];
+    /**
+     * 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 getAvailableTypes(): Promise<string[]>;
 }
 
 /**
@@ -549,6 +631,40 @@ declare class VaultKeeper {
      *   instance.
      */
     getSecret(token: CapabilityToken): SecretAccessor;
+    /**
+     * Sign data using the private key embedded in a capability token.
+     *
+     * The signing key is extracted from the token's encrypted claims, used
+     * for a single `crypto.sign()` call, and never exposed to the caller.
+     * The algorithm is auto-detected from the key type unless overridden
+     * in the request.
+     *
+     * @param token - A `CapabilityToken` obtained from `authorize()`.
+     * @param request - The data to sign and optional algorithm override.
+     * @returns The base64-encoded signature and algorithm label, together
+     *   with the vault metadata (`vaultResponse`).
+     * @throws {VaultError} If `token` is invalid or was not created by this
+     *   vault instance.
+     */
+    sign(token: CapabilityToken, request: SignRequest): Promise<{
+        result: SignResult;
+        vaultResponse: VaultResponse;
+    }>;
+    /**
+     * Verify a signature using a public key.
+     *
+     * This is a static method — no VaultKeeper instance, secrets, or
+     * capability tokens are required. It is safe to call from CI or any
+     * context that has access to public key material.
+     *
+     * Never throws. Returns `false` for invalid key material, malformed
+     * signatures, or any verification failure.
+     *
+     * @param request - The data, signature, public key, and optional
+     *   algorithm override.
+     * @returns `true` if the signature is valid, `false` otherwise.
+     */
+    static verify(request: VerifyRequest): boolean;
     /**
      * Rotate the current encryption key.
      *
@@ -584,4 +700,4 @@ declare class VaultKeeper {
     setDevelopmentMode(executablePath: string, enabled: boolean): Promise<void>;
 }
 
-export { AuthorizationDeniedError, type BackendConfig, type BackendFactory, BackendLockedError, BackendRegistry, BackendUnavailableError, CapabilityToken, DeviceNotPresentError, type ExecRequest, type ExecResult, type FetchRequest, FilesystemError, IdentityMismatchError, KeyRevokedError, KeyRotatedError, type KeyStatus, PluginNotFoundError, type PreflightCheck, type PreflightCheckStatus, type PreflightResult, RotationInProgressError, type SecretAccessor, type SecretBackend, SecretNotFoundError, SetupError, type SetupOptions, TokenExpiredError, TokenRevokedError, type TrustTier, UsageLimitExceededError, type VaultConfig, VaultError, VaultKeeper, type VaultKeeperOptions, type VaultResponse };
+export { AuthorizationDeniedError, type BackendConfig, type BackendFactory, BackendLockedError, BackendRegistry, BackendUnavailableError, CapabilityToken, DeviceNotPresentError, type ExecRequest, type ExecResult, type FetchRequest, FilesystemError, IdentityMismatchError, KeyRevokedError, KeyRotatedError, type KeyStatus, type ListableBackend, PluginNotFoundError, type PreflightCheck, type PreflightCheckStatus, type PreflightResult, RotationInProgressError, type SecretAccessor, type SecretBackend, SecretNotFoundError, SetupError, type SetupOptions, type SignRequest, type SignResult, TokenExpiredError, TokenRevokedError, type TrustTier, UsageLimitExceededError, type VaultConfig, VaultError, VaultKeeper, type VaultKeeperOptions, type VaultResponse, type VerifyRequest, isListableBackend };

package/dist/index.js

@@ -2,7 +2,7 @@ import { spawn } from 'child_process';
 import * as fs5 from 'fs/promises';
 import * as path5 from 'path';
 import * as os4 from 'os';
-import * as crypto3 from 'crypto';
+import * as crypto4 from 'crypto';
 import * as fs4 from 'fs';
 import { CompactEncrypt, compactDecrypt } from 'jose';
 
@@ -171,6 +171,11 @@ var RotationInProgressError = class extends VaultError {
   }
 };
 
+// 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();
@@ -206,6 +211,33 @@ var BackendRegistry = class {
   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);
@@ -239,7 +271,7 @@ path5.join(".vaultkeeper", "file");
 path5.join(".vaultkeeper", "yubikey");
 function hashExecutable(filePath) {
   return new Promise((resolve, reject) => {
-    const hash = crypto3.createHash("sha256");
+    const hash = crypto4.createHash("sha256");
     const stream = fs4.createReadStream(filePath);
     stream.on("data", (chunk) => {
       hash.update(chunk);
@@ -539,10 +571,10 @@ var KeyManager = class {
   #rotating = false;
   /** Generate a new 32-byte key with a timestamp-based id. */
   generateKey() {
-    const randomSuffix = crypto3.randomBytes(4).toString("hex");
+    const randomSuffix = crypto4.randomBytes(4).toString("hex");
     return {
       id: `k-${String(Date.now())}-${randomSuffix}`,
-      key: new Uint8Array(crypto3.randomBytes(32)),
+      key: new Uint8Array(crypto4.randomBytes(32)),
       createdAt: /* @__PURE__ */ new Date()
     };
   }
@@ -958,6 +990,50 @@ function createSecretAccessor(secretValue) {
   return proxy;
 }
 
+// src/access/sign-util.ts
+var ALLOWED_ALGORITHMS = /* @__PURE__ */ new Set(["sha256", "sha384", "sha512"]);
+function resolveAlgorithmForKey(key, override) {
+  const keyType = key.asymmetricKeyType;
+  if (keyType === "ed25519" || keyType === "ed448") {
+    return { signAlg: null, label: keyType };
+  }
+  const alg = override ?? "sha256";
+  if (!ALLOWED_ALGORITHMS.has(alg)) {
+    throw new VaultError(
+      `Unsupported signing algorithm '${alg}'. Allowed: ${[...ALLOWED_ALGORITHMS].join(", ")}`
+    );
+  }
+  return { signAlg: alg, label: alg };
+}
+
+// src/access/delegated-sign.ts
+function delegatedSign(secretPem, request) {
+  const key = crypto4.createPrivateKey(secretPem);
+  const { signAlg, label } = resolveAlgorithmForKey(key, request.algorithm);
+  const data = Buffer.isBuffer(request.data) ? request.data : Buffer.from(request.data);
+  const signature = crypto4.sign(signAlg, data, key);
+  return {
+    signature: signature.toString("base64"),
+    algorithm: label
+  };
+}
+function delegatedVerify(request) {
+  let key;
+  try {
+    key = crypto4.createPublicKey(request.publicKey);
+  } catch {
+    return false;
+  }
+  const { signAlg } = resolveAlgorithmForKey(key, request.algorithm);
+  const sig = Buffer.from(request.signature, "base64");
+  try {
+    const data = Buffer.isBuffer(request.data) ? request.data : Buffer.from(request.data);
+    return crypto4.verify(signAlg, data, key, sig);
+  } catch {
+    return false;
+  }
+}
+
 // src/doctor/checks.ts
 function parseVersion(raw) {
   const match = /(\d+)\.(\d+)\.(\d+)/.exec(raw);
@@ -1210,7 +1286,7 @@ var VaultKeeper = class _VaultKeeper {
     }
     const now = Math.floor(Date.now() / 1e3);
     const claims = {
-      jti: crypto3.randomUUID(),
+      jti: crypto4.randomUUID(),
       exp: now + ttlMinutes * 60,
       iat: now,
       sub: secretName,
@@ -1315,6 +1391,47 @@ var VaultKeeper = class _VaultKeeper {
     const claims = validateCapabilityToken(token);
     return createSecretAccessor(claims.val);
   }
+  /**
+   * Sign data using the private key embedded in a capability token.
+   *
+   * The signing key is extracted from the token's encrypted claims, used
+   * for a single `crypto.sign()` call, and never exposed to the caller.
+   * The algorithm is auto-detected from the key type unless overridden
+   * in the request.
+   *
+   * @param token - A `CapabilityToken` obtained from `authorize()`.
+   * @param request - The data to sign and optional algorithm override.
+   * @returns The base64-encoded signature and algorithm label, together
+   *   with the vault metadata (`vaultResponse`).
+   * @throws {VaultError} If `token` is invalid or was not created by this
+   *   vault instance.
+   */
+  async sign(token, request) {
+    const claims = validateCapabilityToken(token);
+    const result = delegatedSign(claims.val, request);
+    await Promise.resolve();
+    return {
+      result,
+      vaultResponse: { keyStatus: "current" }
+    };
+  }
+  /**
+   * Verify a signature using a public key.
+   *
+   * This is a static method — no VaultKeeper instance, secrets, or
+   * capability tokens are required. It is safe to call from CI or any
+   * context that has access to public key material.
+   *
+   * Never throws. Returns `false` for invalid key material, malformed
+   * signatures, or any verification failure.
+   *
+   * @param request - The data, signature, public key, and optional
+   *   algorithm override.
+   * @returns `true` if the signature is valid, `false` otherwise.
+   */
+  static verify(request) {
+    return delegatedVerify(request);
+  }
   /**
    * Rotate the current encryption key.
    *
@@ -1431,6 +1548,6 @@ var VaultKeeper = class _VaultKeeper {
   }
 };
 
-export { AuthorizationDeniedError, BackendLockedError, BackendRegistry, BackendUnavailableError, CapabilityToken, DeviceNotPresentError, FilesystemError, IdentityMismatchError, KeyRevokedError, KeyRotatedError, PluginNotFoundError, RotationInProgressError, SecretNotFoundError, SetupError, TokenExpiredError, TokenRevokedError, UsageLimitExceededError, VaultError, VaultKeeper };
+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