@sebastienrousseau/crypto-server

v0.0.39

Published

15 days ago

Fastify REST API for cryptography as a service: post-quantum ML-KEM and ML-DSA, encryption, signing, hashing and KMS endpoints, with OpenAPI docs, API key or JWT auth, rate limiting and OpenTelemetry.

0High
0Medium
0Low

sebastienrousseau

fastify rest-api cryptography encryption post-quantum pqc ml-kem ml-dsa openapi microservice opentelemetry jwt kms openpgp

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

The Crypto Service ecosystem — full 18-package suite overview

Package reference

Reference & Usage — features, configuration, and capabilities
Examples — runnable sample code

Operational

Development — build, lint, format, and test targets
Security — vulnerability disclosure and cryptographic invariants
Documentation — TypeDoc API docs and ecosystem guides
Stability guarantees — SemVer axis and release policy
License

Install

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

Requirements

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)

Quick Start

Start the server:

npx crypto-server
# or, from a clone of this repo:
pnpm --filter @sebastienrousseau/crypto-server start

Hash some data:

curl -s -X POST http://localhost:3000/v2/hash \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-secret-api-key" \
  -d '{"algorithm":"sha256","data":"Hello, world!"}' | jq

{
  "data": "315f5bdb76d078c43b8ac0064e4a0164612b1fce77c869345bfc94c75894edd3"
}

The Crypto Service ecosystem

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

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

Overview

Crypto Server is built on Fastify 4.x with a layered middleware stack:

Request
  -> @fastify/helmet (security headers)
  -> @fastify/cors
  -> @fastify/rate-limit
  -> @fastify/compress
  -> Authentication (x-api-key / JWT Bearer)
  -> Route handler
  -> Response

Route versioning

| Prefix | Status | Notes | | :---------------------------- | :------------- | :---------------------------------------------------------------------------- | | /v1/* | Deprecated | Legacy PGP-based endpoints. Emit Deprecation, Sunset, and Link headers. | | /v2/* | Current | Modern endpoints using @noble/* primitives and post-quantum algorithms. | | /live, /ready, /metrics | Stable | Infrastructure probes (no auth required). |

API Routes

All v2 endpoints accept and return application/json. Authenticated requests must include an x-api-key header (or Authorization: Bearer <jwt>).

Errors

Every error response is an RFC 9457 problem, served as application/problem+json:

{
  "type": "urn:crypto-service:problem:forbidden",
  "title": "Forbidden",
  "status": 403,
  "detail": "Missing required scope: crypto:encrypt",
  "instance": "/v2/encrypt"
}

type is urn:crypto-service:problem:<slug>, one of validation-failed (400, with an errors array of { field, message }), invalid-input (400), request-error (other 4xx), unauthorized (401), forbidden (403), not-found (404), key-not-found (404), key-algorithm-mismatch (400), payload-too-large (413), rate-limited (429, with Retry-After), key-store-full (503) and internal-error (500). A crypto-lib CryptoError or key-store error adds its code. A 500 never carries the internal message or stack, and instance is the request path without its query string.

Work factors

/v2/kdf and /v2/password/hash enforce the OWASP Password Storage Cheat Sheet floors for new keys and hashes: scrypt N = 2^17 with r = 8 (crypto-lib caps N at 2^17), PBKDF2-HMAC-SHA256 with at least 600,000 iterations, and Argon2id with at least 19 MiB of memory and two passes. A lower value gets 400. /v2/password/verify still accepts the parameters of existing hashes. Scrypt, PBKDF2 and Argon2 (including /v2/password/encrypt and /decrypt) run on two worker threads, so a derivation does not block other requests or the health probes; further derivations queue.

Key custody

The API never takes a private key and never returns one, with one exception below. Key-generation routes (/v2/keys/generate, /v2/pq/keygen, /v2/pq/hybrid/keygen, /v2/pq/dsa/keygen, /v2/pq/slh-dsa/keygen) keep the private key on the server and return a keyId with the public key. Signing, sealed-box opening and decapsulation routes take that keyId. A key belongs to the principal (token sub) that generated it; for anyone else it does not exist (404).

Keys live in memory (at most 10,000 without persistence, and 1,000 per principal by default). Set CRYPTO_KEY_OUT_DIR to also write each key to <keyId>.json there (mode 0600, never overwritten) so keys survive a restart. With CRYPTO_KEY_STORAGE_KEY the private parts are encrypted and the whole record authenticated; without it they are written in plaintext, which a production server refuses unless CRYPTO_KEY_ALLOW_PLAINTEXT=1. POST /v2/keys/delete removes one of the caller's keys.

POST /v2/keys/export returns a key's private parts. It needs the crypto:keys:export scope, granted explicitly in a JWT: crypto:admin does not include it, so API-key and anonymous principals cannot export.

The v1 routes use the server's own OpenPGP key pair from CRYPTO_KEY_DIR: /v1/decrypt decrypts messages sent to it, and /v1/encrypt signs with it when sign is true.

Symmetric keys (/v2/encrypt, /v2/secretbox/*, /v2/hmac, the key-wrap KEK) are still supplied by the client.

Authentication

The server supports two authentication modes:

API Key -- set CRYPTO_API_KEY and pass it as the x-api-key header.
JWT Bearer -- set JWT_SECRET and pass Authorization: Bearer <token>.

If neither variable is set, every request except the probes and /docs gets 401, unless ALLOW_ANONYMOUS=1 is set for local development or behind an authenticating gateway.

# API key
curl -H "x-api-key: your-secret-api-key" ...

# JWT Bearer
curl -H "Authorization: Bearer eyJhbGciOi..." ...

A JWT must be HS256 and carry sub, exp and iat. Its sub must be a non-empty string other than api-key and anonymous (the built-in principals), because server-held keys belong to the subject. It is refused once it is older than JWT_MAX_AGE seconds (default 3600) or if it declares a longer lifetime (exp - iat). When JWT_ISSUER / JWT_AUDIENCE are set, its iss must equal the issuer and its aud must contain the audience. In production (NODE_ENV=production) both are required whenever JWT_SECRET is set, and the server refuses to start without them.

Scopes

Every route requires one scope, defined in one table (ROUTE_SCOPES in src/config/auth-policy.ts). A principal without it gets 403. The server refuses to start if a route has no entry. JWT principals carry their scopes in a scopes array claim; API-key and anonymous principals hold crypto:admin, which satisfies every scope except crypto:keys:export.

Anonymous access (ALLOW_ANONYMOUS=1) is single-tenant: every caller is the same principal, holds crypto:admin, and can use every key the server holds. Use it only for local development.

KMS keys

The /v2/kms/* routes use only the providers in KMS_PROVIDERS (default local); a request for any other provider is refused with 400 before a provider is contacted. A key created with /v2/kms/create-key belongs to the principal that created it: other principals get 404 for it, as for a key that does not exist. A key the API did not create (for example one made in the cloud console) has no owner and can be used by crypto:admin only. With CRYPTO_KEY_OUT_DIR set, owners are kept in kms-owners.json there (mode 0600), so they survive a restart.

| Scope | Routes | | :------------------- | :------------------------------------------------------------------------------------------------------------------- | | crypto:encrypt | /v1/encrypt, /v2/encrypt, secretbox/sealedbox seal, password and multi-recipient encrypt, PQ encapsulate | | crypto:decrypt | /v1/decrypt, /v2/decrypt, secretbox/sealedbox open, password decrypt, PQ decapsulate | | crypto:sign | /v2/sign, /v2/stream/sign, ML-DSA and SLH-DSA sign, /v2/hmac | | crypto:verify | /v1/verify, /v2/verify, /v2/stream/verify, /v2/stream/iso20022, ML-DSA and SLH-DSA verify, /v2/hmac/verify | | crypto:hash | /v2/hash | | crypto:kdf | /v2/kdf, /v2/password/hash, /v2/password/verify | | crypto:keys | /v1/generate, /v2/keys/*, PQ, ML-DSA and SLH-DSA keygen | | crypto:keys:export | /v2/keys/export; never implied by crypto:admin | | crypto:admin | /v1/revoke (revokes the server's own key pair); satisfies every other scope except crypto:keys:export |

GET /, GET /v2/algorithms and GET /v2/compliance/* need authentication but no scope.

Audit log

Every request that creates, exports, deletes or uses a server-held key, calls a KMS route, or registers an OPAQUE credential writes one log line with msg: "audit" after the response, refused requests included:

{
  "reqId": "…",
  "msg": "audit",
  "audit": {
    "action": "POST /v2/keys/export",
    "principal": "alice",
    "status": 404,
    "outcome": "failure",
    "keyId": "k_…"
  }
}

It names the key or KMS provider, never key material. Audit lines are written at info, so a LOG_LEVEL above info drops them.

Configuration

The server checks every setting at startup and refuses to start, listing each problem, when one is invalid. Numeric settings take digits only: PORT=3000abc or RATE_LIMIT_MAX=0 is an error, not a fallback to the default.

Examples

All examples are self-contained TypeScript files in the examples/ directory. Each uses fetch to call the server. Run any example with:

# Start the server in one terminal:
pnpm --filter @sebastienrousseau/crypto-server start

# Run an example in another:
npx ts-node examples/<name>.ts

Development

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

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

Security

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.

Documentation

Stability guarantees

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.

License

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