vaultkeeper 0.3.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`. */
@@ -578,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.
      *
@@ -613,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, type ListableBackend, 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, isListableBackend };
+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`. */
@@ -578,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.
      *
@@ -613,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, type ListableBackend, 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, isListableBackend };
+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

@@ -990,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);
@@ -1347,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.
    *