Crypto KMS
    Preparing search index...

    Crypto KMS

    crypto-kms logo

    @sebastienrousseau/crypto-kms

    Unified Key Management Service interface with AWS KMS, Google Cloud KMS, HashiCorp Vault Transit and in-memory local providers. Azure is a stub.

    Build Coverage Registry Docs OpenSSF Scorecard License: Apache-2.0 OR MIT Node.js 22 or newer


    Getting started

    • Install — installation via pnpm, npm, or yarn
    • Requirements — runtime floor and environment prerequisites
    • Quick Start — minimal working usage sample

    The Crypto Service ecosystem

    Package reference

    Operational


    pnpm add @sebastienrousseau/crypto-kms
    # or
    npm install @sebastienrousseau/crypto-kms
    # or
    yarn add @sebastienrousseau/crypto-kms

    Back to Top


    • Node.js: ^22.0.0 or >=24.0.0 (active and maintenance LTS releases)
    • Package Manager: pnpm >=9 (recommended) or npm >=10
    • TypeScript: >=5.0 (when compiling with TypeScript)

    Back to Top


    import { LocalKmsProvider } from "@sebastienrousseau/crypto-kms";

    const kms = new LocalKmsProvider();
    const key = await kms.createKey("aes-256-gcm", "encrypt");
    const encrypted = await kms.encrypt(
    key.keyId,
    new TextEncoder().encode("secret"),
    );
    const decrypted = await kms.decrypt(key.keyId, encrypted.ciphertext);
    console.log(new TextDecoder().decode(decrypted.plaintext)); // "secret"

    Back to Top


    Crypto Service provides a complete cryptography stack across 14 specialized packages:

    Package Role Description
    @sebastienrousseau/crypto-api API docs Postman collection types and a Postman-to-Markdown converter; the server's API contract is its OpenAPI document.
    @sebastienrousseau/crypto-benchmarks Benchmarks Benchmarks comparing classical and post-quantum cryptography: ops/sec, latency and throughput.
    @sebastienrousseau/crypto-cbom CBOM Cryptographic Bill of Materials generator and auditor (CycloneDX 1.6, SPDX 3.0).
    @sebastienrousseau/crypto-cli Terminal CLI Command-line interface: hashing, key generation, encryption, signing, HPKE, Argon2id and CBOM scans, with an interactive menu.
    @sebastienrousseau/crypto-edge Edge Runtime Edge-runtime cryptographic operations using the Web Crypto API, optimized for Cloudflare Workers, Vercel Edge, and Deno.
    @sebastienrousseau/crypto-kms (this package) Cloud KMS Unified KMS interface: AWS KMS, Google Cloud KMS, Vault Transit and local providers; Azure is a stub.
    @sebastienrousseau/crypto-lib Core Library Core library: post-quantum ML-KEM, ML-DSA and SLH-DSA, plus classical, modern and OpenPGP cryptography for TypeScript.
    @sebastienrousseau/crypto-lsp IDE Analysis Language server that flags weak and quantum-vulnerable cryptography in the editor, with quick fixes.
    @sebastienrousseau/crypto-mcp AI Agents Model Context Protocol server exposing cryptography tools to AI assistants and agents.
    @sebastienrousseau/crypto-middleware Middleware Cryptographic middleware for Express and Fastify: decrypt requests, encrypt responses, verify HMAC signatures and JWTs.
    @sebastienrousseau/crypto-prisma ORM Adapter Transparent field-level encryption extension for Prisma Client, using XChaCha20-Poly1305.
    @sebastienrousseau/crypto-react React Hooks React hooks and context provider for client-side cryptographic operations with zero boilerplate.
    @sebastienrousseau/crypto-sdk Client SDK A zero-dependency, typed HTTP client for the Crypto Service REST API, with full post-quantum support.
    @sebastienrousseau/crypto-server HTTP API A hardened Fastify REST API for cryptographic operations, with rate limiting, OpenAPI schemas, and post-quantum endpoints.
    @sebastienrousseau/crypto-testing Test Support Deterministic keys, fast mocks, and test fixtures for crypto-lib
    @sebastienrousseau/crypto-typeorm ORM Adapter TypeORM column-level encryption with a single decorator, powered by crypto-lib.
    @sebastienrousseau/crypto-vue Vue Composables Vue 3 composables for client-side cryptography
    @sebastienrousseau/crypto-wasm Acceleration Placeholder for a WebAssembly accelerator; no WebAssembly module ships yet.

    Back to Top


    crypto-kms defines a unified KmsProvider interface for key creation, encryption, decryption, signing, verification, rotation and data-key generation. Four providers talk to a real key store: AWS KMS (through the AWS SDK), Google Cloud KMS and HashiCorp Vault Transit (through their REST APIs, with fetch), and an in-memory local provider. The Azure Key Vault provider is a stub: every method rejects with NOT_IMPLEMENTED. The PKCS#11 provider is an in-memory software simulation for tests (see below); it does not talk to an HSM.

    createKey creates exactly the algorithm you ask for or rejects with INVALID_ARGUMENT; it never substitutes another. Each provider accepts the names below, and its backend's own names (such as ML_DSA_65 on AWS or EC_SIGN_P384_SHA384 on Google Cloud).

    Back to Top

    Provider Class Backend Encryption and wrap Signing Dependency
    AWS AwsKmsProvider AWS Key Management Service aes-256-gcm (SYMMETRIC_DEFAULT), rsa-* ed25519, p256, p384, p521, secp256k1, rsa-*, ml-dsa-44/65/87 @aws-sdk/client-kms
    GCP GcpKmsProvider Google Cloud KMS (REST v1) aes-256-gcm (GOOGLE_SYMMETRIC_ENCRYPTION) ed25519, p256, p384, rsa-2048/3072/4096 (PSS or PKCS#1) None
    Vault VaultKmsProvider HashiCorp Vault Transit aes-256-gcm, aes-128-gcm, chacha20-poly1305, rsa-* ed25519, p256, p384, p521, rsa-* None
    Local LocalKmsProvider In-memory (crypto-lib) aes-256-gcm ed25519 None
    Azure AzureKmsProvider Azure Key Vault Stub: rejects NOT_IMPLEMENTED Stub None
    PKCS#11 Pkcs11HsmProvider None (in-memory) Software simulation of aes-256-gcm; simulate: true Software simulation of ed25519 None

    Backend behaviour worth knowing:

    • AWS: without an explicit algorithm, sign and verify use the one matching the key spec (for example ECDSA_SHA_256 for P-256, ML_DSA_SHAKE_256 for ML-DSA). rotateKey rotates on demand, which AWS supports for symmetric keys only.
    • Google Cloud: signing uses the newest enabled key version, and verification is done locally against the public key of each enabled version, since Cloud KMS has no remote asymmetric verify; signatures made before a rotation keep verifying until their version is disabled. Post-quantum signing keys are refused for now. enableKey, disableKey and scheduleKeyDeletion act on every version; deletion uses the key's own destroy-scheduled duration.
    • Vault: the encryption context is bound as Transit associated_data. Ciphertext written by crypto-kms 0.0.35 or earlier is not bound to its context; set acceptUnboundContext to read it, then re-encrypt. Transit cannot disable a key, so enableKey/disableKey reject with NOT_IMPLEMENTED; deletion is immediate, so scheduleKeyDeletion requires pendingWindowDays: 0 to confirm. Vault creates a key on the first encrypt to an unknown name unless the token's policy denies create on transit/encrypt; grant update only.

    Pkcs11HsmProvider has no PKCS#11 binding: it never loads a module, accepts any PIN, keeps keys in process memory and reports fipsLevel: "none (software simulation)". Its constructor throws unless you pass { simulate: true }. Use it only in tests.

    Back to Top

    Every provider exposes the KmsProvider interface:

    Method Description
    listKeys(filters?) List all managed keys, with optional filters
    getKey(keyId) Retrieve metadata for a specific key
    createKey(algorithm, usage, metadata?) Create a new managed key
    enableKey(keyId) Enable a disabled key
    disableKey(keyId) Disable a key (soft delete)
    scheduleKeyDeletion(keyId, days?) Schedule a key for deletion
    encrypt(keyId, plaintext, context?) Encrypt plaintext with a managed key
    decrypt(keyId, ciphertext, context?) Decrypt ciphertext with a managed key
    sign(keyId, data, algorithm?) Sign data with a managed signing key
    verify(keyId, data, signature, algorithm?) Verify a signature
    rotateKey(keyId) Add a new current key version
    destroyKeyVersion?(keyId, version) Destroy a retired version (optional method)
    generateDataKey(keyId, keySpec?) Generate a wrapped data encryption key

    LocalKmsProvider and Pkcs11HsmProvider keep every version of a key. rotateKey adds a new current version; it does not replace the old material. New ciphertext and signatures use the current version, and each ciphertext records the version that produced it, so data encrypted before a rotation still decrypts and signatures made before it still verify. getKey reports currentVersion; encrypt and decrypt report keyVersion.

    A version stays usable until you destroy it with destroyKeyVersion(keyId, version). After that, ciphertext from that version rejects with VERSION_DESTROYED and its signatures no longer verify. The current version cannot be destroyed; rotate first. disableKey and scheduleKeyDeletion still block every operation on the key, all versions included.

    const key = await kms.createKey("aes-256-gcm", "encrypt");
    const old = await kms.encrypt(key.keyId, data); // old.keyVersion === 1
    await kms.rotateKey(key.keyId); // currentVersion === 2
    await kms.decrypt(key.keyId, old.ciphertext); // still decrypts with version 1
    await kms.destroyKeyVersion(key.keyId, 1); // version 1 is gone for good

    The ciphertext of these two providers is the base64 of: a format byte (0x01), the key version (4 bytes, big-endian), the AES-GCM IV (12 bytes), the tag (16 bytes) and the AES-256-GCM ciphertext. Ciphertext produced by 0.0.6 and earlier is not accepted; neither provider persists keys, so none can outlive the process that made it.

    The encryption context is bound to the ciphertext as AES-GCM additional authenticated data. It is canonicalised first (entries sorted by key), so { a: "1", b: "2" } and { b: "2", a: "1" } are the same context. Values must be strings; anything else rejects with INVALID_ARGUMENT. An empty context is the same as no context.

    Providers reject with KmsError, which extends Error and carries a code (and the keyId when there is one). Branch on the code, not the message:

    Code Meaning
    NOT_FOUND Unknown key, or a ciphertext names a version the key never had
    DISABLED The key is disabled or scheduled for deletion
    INVALID_USAGE The key's usage does not allow the operation
    INVALID_ARGUMENT Malformed argument, or destroying the current version
    INVALID_CIPHERTEXT Truncated ciphertext or an unknown format
    DECRYPTION_FAILED Wrong context, wrong key, or tampered ciphertext
    VERSION_DESTROYED The ciphertext's key version has been destroyed
    NOT_IMPLEMENTED Stub provider (Azure), or an operation the backend lacks
    DEPENDENCY_MISSING The AWS SDK peer dependency is not installed

    Errors raised by the AWS SDK itself are passed through unchanged. No provider method takes a timeout or an AbortSignal yet.

    Back to Top

    Provider Credentials
    AWS Pass credentials in AwsKmsOptions, or rely on the default AWS credential chain
    GCP An OAuth2 access token in token; the provider does not refresh it
    Azure Not applicable (stub provider)
    Vault A Vault token in token, and namespace for Vault Enterprise namespaces
    Local No authentication required

    Back to Top

    All examples are self-contained TypeScript files in the examples/ directory. Run any example with:

    npx ts-node examples/<name>.ts
    
    Category Example Purpose
    Local local.ts Create keys, encrypt/decrypt with the in-memory provider
    AWS aws.ts AWS KMS setup and usage pattern
    Envelope envelope.ts Envelope encryption with generateDataKey
    Rotation rotation.ts Rotate, decrypt old data, destroy a retired version
    Multi multi.ts Provider-agnostic code across multiple backends

    Back to Top

    Back to Top


    pnpm --filter @sebastienrousseau/crypto-kms run build
    pnpm --filter @sebastienrousseau/crypto-kms run test
    pnpm --filter @sebastienrousseau/crypto-kms run lint
    pnpm --filter @sebastienrousseau/crypto-kms run format

    All 18 packages in the Crypto Service workspace maintain a 100% coverage floor across statements, branches, functions, and lines.

    Back to Top


    Report vulnerabilities privately via GitHub Security Advisories or according to SECURITY.md. Never report security issues publicly.

    The local and simulated PKCS#11 providers run AES-256-GCM through Node.js crypto and Ed25519 through crypto-lib (@noble/curves). Neither is a validated cryptographic module, and neither zeroes key material held in memory.

    Back to Top


    Back to Top


    Versions advance strictly one step at a time on the 0.0.x line (v0.0.1 → v0.0.2 → v0.0.3 ... → v0.0.999 → v0.1.0). Work for every release iteration begins on a dedicated feat/v<version> branch.

    All 18 packages in the workspace move in lockstep. Public API signatures, cipher output formats, and serialization schemas are strictly versioned. Breaking changes to serialized formats or algorithm defaults are considered major breaking changes. Minimum toolchain upgrades (e.g. Node.js LTS floor) are governed by POLICIES.md.

    Back to Top


    Dual-licensed under Apache 2.0 or MIT, at your option.

    Copyright (c) 2022-2026 Sebastien Rousseau and The Crypto Service Suite contributors.

    Back to Top