Crypto SDK
    Preparing search index...

    Crypto SDK

    crypto-sdk logo

    @sebastienrousseau/crypto-sdk

    A zero-dependency, typed HTTP client for the Crypto Service REST API, with full post-quantum support.

    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-sdk
    # or
    npm install @sebastienrousseau/crypto-sdk
    # or
    yarn add @sebastienrousseau/crypto-sdk

    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 { CryptoClient } from "@sebastienrousseau/crypto-sdk";

    const client = new CryptoClient({
    baseUrl: "http://localhost:3000",
    apiKey: "<the server's CRYPTO_API_KEY>",
    });

    const { data } = await client.hash({ algorithm: "sha256", data: "hello" });
    console.log(data.digest);

    CryptoClient accepts two authentication mechanisms. The server refuses unauthenticated requests unless it runs with ALLOW_ANONYMOUS=1, and each route needs a scope (crypto:sign, crypto:keys, ...); an API key holds crypto:admin, which covers every scope except crypto:keys:export.

    Option Header sent Description
    apiKey x-api-key: <value> Static API key
    token Authorization: Bearer <value> JWT bearer token

    Private keys never cross the API. Key-generation methods return a keyId with the public key, and the server keeps the private key; methods that need it take the keyId. A key is usable only by the principal that generated it.

    const { data: key } = await client.generateKeyPair({ algorithm: "ed25519" });
    const { data: sig } = await client.sign({ keyId: key.keyId, message: "hi" });
    const { data: check } = await client.verify({
    publicKey: key.publicKey,
    message: "hi",
    signature: sig.signature,
    });
    console.log(check.valid); // true

    exportKey({ keyId }) returns the private parts, and only to a principal whose token grants crypto:keys:export explicitly.

    Failed requests throw a CryptoApiError whose body is the server's RFC 9457 problem (application/problem+json):

    import { CryptoClient, CryptoApiError } from "@sebastienrousseau/crypto-sdk";

    try {
    await client.sign({ keyId: "k_AAAAAAAAAAAAAAAAAAAAAA", message: "x" });
    } catch (err) {
    if (err instanceof CryptoApiError) {
    console.error(err.status); // 404
    console.error(err.body.type); // "urn:crypto-service:problem:key-not-found"
    console.error(err.body.detail); // "Key not found"
    console.error(err.body.code); // "KEY_NOT_FOUND"
    }
    }

    body has type, title, status, detail and instance, plus code for crypto-lib and key-store errors and errors ({ field, message } per failed check) for validation failures. A response without a problem body (for example from a proxy) becomes an about:blank problem for its status code.

    A request that got no response (connection failure, timeout) throws a CryptoTransportError: timedOut says which, and cause holds the underlying error.

    timeout (milliseconds) applies to each attempt. Retries are off unless retry.maxRetries is set; then 429, 503 and 504 responses and lost connections are retried with jittered exponential backoff, or after the server's Retry-After when it gives one. A Retry-After longer than retry.maxDelayMs (default 2000) ends the retries, so the client does not keep calling a server that asked it to wait.

    Requests that create or delete server state (key generation, KMS key creation, OPAQUE registration, key deletion) are retried only after 429 or 503, which mean the server did not process them: after a lost connection or a 504 the work may already be done, and a retry could create a second key. The client never follows redirects, so an API key or token is never sent to another origin.

    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 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 (this package) 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-sdk is a typed HTTP client that wraps the Crypto Service REST API. It uses the global fetch API (no runtime dependencies) and provides strongly-typed methods for every v2 endpoint -- hashing, encryption, signing, key derivation, password hashing, key management, sealed boxes, secretboxes, and post-quantum KEM and signature operations.

    Back to Top

    Methods return Promise<ApiResponse<T>> where ApiResponse<T> is { data: T }, except getCbom() (the CycloneDX document itself) and health(). Methods marked keyId use a server-held key; key-generation methods return its keyId and public key, never the private key.

    Method Endpoint Description
    hash(body) POST /v2/hash Compute a cryptographic hash
    encrypt(body) POST /v2/encrypt Encrypt with XChaCha20-Poly1305
    decrypt(body) POST /v2/decrypt Decrypt ciphertext
    generateKeyPair(body?) POST /v2/keys/generate Generate a server-held key pair
    exportKey(body) POST /v2/keys/export Export a key's private parts (keyId)
    sign(body) POST /v2/sign Sign with Ed25519 (keyId)
    verify(body) POST /v2/verify Verify an Ed25519 signature
    kdf(body) POST /v2/kdf Derive a key
    mac(body) POST /v2/hmac Compute an HMAC
    macVerify(body) POST /v2/hmac/verify Verify an HMAC
    passwordHash(body) POST /v2/password/hash Hash a password with Argon2id
    passwordVerify(body) POST /v2/password/verify Verify a password hash
    passwordEncrypt(body) POST /v2/password/encrypt Encrypt data with a password
    passwordDecrypt(body) POST /v2/password/decrypt Decrypt password-encrypted data
    keyWrap(body) POST /v2/keys/wrap Wrap a key
    keyUnwrap(body) POST /v2/keys/unwrap Unwrap a wrapped key
    secretboxSeal(body) POST /v2/secretbox/seal Seal plaintext with a symmetric key
    secretboxOpen(body) POST /v2/secretbox/open Open a sealed secretbox
    sealedboxSeal(body) POST /v2/sealedbox/seal Seal plaintext for an X25519 public key
    sealedboxOpen(body) POST /v2/sealedbox/open Open a sealed box (keyId)
    sealedboxSealPq(body) POST /v2/sealedbox/seal-pq Seal plaintext for a hybrid public key pair
    sealedboxOpenPq(body) POST /v2/sealedbox/open-pq Open a hybrid sealed box (keyId)
    mlKemGenerateKeyPair() POST /v2/pq/keygen Generate a server-held ML-KEM-768 key pair
    mlKemEncapsulate(body) POST /v2/pq/encapsulate Encapsulate to an ML-KEM-768 public key
    mlKemDecapsulate(body) POST /v2/pq/decapsulate Decapsulate (keyId)
    pqGenerateKeyPair() POST /v2/pq/hybrid/keygen Generate a server-held hybrid key pair
    pqEncapsulate(body) POST /v2/pq/hybrid/encapsulate Encapsulate a hybrid shared secret
    pqDecapsulate(body) POST /v2/pq/hybrid/decapsulate Decapsulate a hybrid shared secret (keyId)
    pqSignKeygen(body) POST /v2/pq/dsa/keygen Generate a server-held ML-DSA key pair
    pqSign(body) POST /v2/pq/dsa/sign Sign with ML-DSA (keyId; level from the key)
    pqVerify(body) POST /v2/pq/dsa/verify Verify an ML-DSA signature
    pqHashSignKeygen(body) POST /v2/pq/slh-dsa/keygen Generate a server-held SLH-DSA key pair
    pqHashSign(body) POST /v2/pq/slh-dsa/sign Sign with SLH-DSA (keyId; variant from key)
    pqHashVerify(body) POST /v2/pq/slh-dsa/verify Verify an SLH-DSA signature
    getDoraCompliance() GET /v2/compliance/dora DORA self-assessment
    getCbom() GET /v2/compliance/cbom CycloneDX 1.6 CBOM
    algorithms() GET /v2/algorithms List all supported algorithms
    health() GET /health Server health check

    The stream (/v2/stream/*), multi-recipient (/v2/multi-recipient/encrypt) and v1 OpenPGP routes have no SDK methods yet.

    Back to Top

    All examples are self-contained TypeScript files in the examples/ directory. Each requires the crypto-server running on http://localhost:3000 (override via CRYPTO_SERVER_URL) and sends CRYPTO_API_KEY (or the JWT in CRYPTO_TOKEN) when set. pnpm run examples:check type-checks them against the SDK.

    CRYPTO_API_KEY=<key> npx ts-node examples/<name>.ts
    
    Category Example Purpose
    Algorithms algorithms.ts List all supported algorithms
    Encryption encrypt.ts XChaCha20-Poly1305 encrypt and decrypt
    Hashing hash.ts Compute SHA-256, SHA-512 and BLAKE2b digests
    KDF kdf.ts Key derivation with HKDF-SHA256
    Key Gen keygen.ts Generate server-held key pairs
    Key Wrap keywrap.ts AES key wrapping and unwrapping
    MAC mac.ts HMAC-SHA256 compute and verify
    Passwords password.ts Argon2 hashing and password encryption
    PQ KEM pqkem.ts Hybrid X25519 + ML-KEM key exchange by keyId
    PQ Sign pqsign.ts ML-DSA post-quantum signing by keyId
    PQ Hash Sign pqhashsign.ts SLH-DSA post-quantum signing by keyId
    Sealed Box sealedbox.ts Anonymous public-key encryption, open by keyId
    Secretbox secretbox.ts Symmetric authenticated encryption
    Signing sign.ts Ed25519 signing by keyId and verification

    __tests__/contract.test.ts runs the SDK against the real crypto-server in process (its fetch forwards to Fastify's inject), so a drift between a method and its route fails the test suite.

    Back to Top

    Back to Top


    pnpm --filter @sebastienrousseau/crypto-sdk run build
    pnpm --filter @sebastienrousseau/crypto-sdk run test
    pnpm --filter @sebastienrousseau/crypto-sdk run lint
    pnpm --filter @sebastienrousseau/crypto-sdk 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.

    Cryptographic operations use the @noble/* libraries, Node.js crypto and OpenPGP.js. @noble/post-quantum has not been independently audited and does not guarantee constant-time execution, and no module in this suite is FIPS 140-3 validated. Key zeroization is limited: JavaScript strings and garbage-collected buffers cannot be reliably wiped. See SECURITY.md.

    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