{
  "schema": "leumas.docs.page/1",
  "id": "adapter:domain/crypto",
  "slug": "adapters/domain/crypto",
  "kind": "capabilities",
  "bucket": "package",
  "title": "crypto — applied cryptography adapter pack",
  "name": "crypto",
  "eyebrow": "applied cryptography adapter pack",
  "chip": null,
  "summary": "Applied cryptography toolkit built on Node's native node:crypto (zero npm deps). Symmetric encryption: AES-256-GCM authenticated encrypt/decrypt of text with a password-derived key (scrypt KDF...",
  "keywords": [
    "crypto",
    "cryptography",
    "encrypt",
    "decrypt",
    "scrypt",
    "crypto api",
    "leumas crypto",
    "salt"
  ],
  "audience": "both",
  "funnel": {
    "product": null,
    "cta": null
  },
  "body": "# crypto — applied cryptography adapter pack\n\nReal, modern cryptography for the Leumas ecosystem, built entirely on Node's native\n`node:crypto`. **Zero npm dependencies** — pure Node built-ins, so it loads everywhere with no\ninstall step.\n\nThis is the \"do actual crypto\" pack: encrypt sensitive data, generate keypairs, sign & verify\npayloads, mint and validate JSON Web Tokens, derive keys from passwords, and generate secure\nsecrets.\n\n## Tools\n\n| Tool | What it does |\n|---|---|\n| `encrypt` | AES-256-GCM authenticated encryption of text with a password. Derives a 32-byte key via scrypt from the password + a random salt, encrypts under a random IV. Returns `{ salt, iv, authTag, ciphertext }` (all base64). |\n| `decrypt` | Reverses `encrypt`. Needs the password + the `salt/iv/authTag/ciphertext`. Throws on wrong password or tampered data (GCM is authenticated). |\n| `generateKeyPair` | Generate an `rsa` (default 2048-bit), `ec` (default P-256), `ed25519`, or `ed448` keypair. Returns PEM `publicKey` + `privateKey`. |\n| `publicKeyFromPrivate` | Derive/export the PEM public key from a private key. |\n| `sign` | Digital signature of `data` with a PEM private key (RSA/EC use a hash, default sha256; Ed keys sign raw). |\n| `verify` | Verify a signature against `data` with the matching public key → `{ valid }`. |\n| `jwtSign` | Sign a JWT. HS* use a shared `secret`; RS*/PS*/ES* use a PEM `privateKey`. Auto-adds `iat`/`exp` (`expiresIn` accepts `3600`, `\"15m\"`, `\"2h\"`, `\"7d\"`). |\n| `jwtVerify` | Verify a JWT signature + `exp`/`nbf`. Throws `status:401` on invalid/expired. Supports an `algorithms` allow-list. |\n| `jwtDecode` | Decode header + payload **without** verifying (inspection only — never trust for auth). |\n| `hmac` | Keyed MAC of arbitrary data (raw or encoded key, choose hash + output encoding). |\n| `hash` | One-shot cryptographic hash of arbitrary data/bytes (sha256 default). |\n| `pbkdf2` | PBKDF2 key derivation (iterations + salt). Auto-generates + returns a salt if none given. |\n| `scrypt` | scrypt memory-hard key derivation (`N`/`r`/`p`). Auto-generates + returns a salt if none given. |\n| `randomBytes` | CSPRNG bytes in the chosen encoding (base64 default). |\n| `randomToken` | URL-safe random token (base64url) for API keys, nonces, reset tokens. |\n| `uuid` | An RFC-4122 v4 UUID from the CSPRNG. |\n| `timingSafeEqual` | Constant-time comparison of two secrets (resists timing attacks). |\n| `listHashAlgorithms` | Hash algorithms available on this Node build. |\n\n## Usage\n\nEvery tool takes ONE args object (an HTTP POST body maps 1:1). Through the registry:\n`registry.run('crypto', '<tool>', args)`.\n\n```js\nimport crypto from './index.js';\nconst { adapters } = crypto;\n\n// Encrypt then decrypt\nconst box = adapters.encrypt({ text: 'top secret', password: 'hunter2' });\nconst { text } = adapters.decrypt({ password: 'hunter2', ...box });\n// text === 'top secret'\n\n// Keypair + sign + verify\nconst { publicKey, privateKey } = adapters.generateKeyPair({ type: 'ec' });\nconst { signature } = adapters.sign({ data: 'invoice#42', privateKey });\nconst { valid } = adapters.verify({ data: 'invoice#42', signature, publicKey }); // valid === true\n\n// JWT (HS256)\nconst { token } = adapters.jwtSign({ payload: { sub: 'u_1', role: 'admin' }, secret: 's3cr3t', expiresIn: '2h' });\nconst { payload } = adapters.jwtVerify({ token, secret: 's3cr3t' });\n\n// Key derivation + secure token\nconst kdf = adapters.pbkdf2({ password: 'hunter2' }); // returns salt + key\nconst { token: apiKey } = adapters.randomToken({ length: 32 });\n```\n\n## DRY boundary — what does NOT live here\n\nThis pack is deliberately scoped so it does not overlap its neighbours:\n\n- **`a-text`** owns string→string primitives on **text**: `MD5Hash`, `SHA256Hash`, `SHA512Hash`,\n  a hex-digest `HMAC`, `Base64Encode`/`Base64Decode`, and classical ciphers (`CaesarCipher`,\n  `Rot13`, `VigenereEncode`/`Decode`). Those are deterministic display/obfuscation helpers with no\n  key management. Reach for a-text when you just want the hex hash of a string.\n- **`a-file-actions`** owns AES encryption of **files** on disk.\n- **`crypto` (this pack)** owns **real applied cryptography on data and keys**: password-based\n  AES-256-GCM of arbitrary text (authenticated, salted, random-IV), RSA/EC/Ed keypairs, digital\n  signatures, JWTs, KDFs (PBKDF2/scrypt), and CSPRNG token/byte/compare primitives.\n\nThe small overlaps are intentional and distinct: `crypto.hmac`/`crypto.hash` are the general\ndata/bytes primitives (any key encoding, any output encoding) used to build signing flows, whereas\na-text's `HMAC`/`*Hash` are hex-only convenience wrappers for text. Use a-text for quick text\ndigests; use this pack when you're actually securing data, keys, or tokens.\n\n## Notes\n\n- Binary outputs default to base64 (base64url for `randomToken` and JWT segments). All results are\n  plain JSON-serializable objects.\n- `encrypt` uses scrypt (`N=16384, r=8, p=1`) → AES-256-GCM; the returned `salt`/`iv`/`authTag`\n  make each ciphertext self-describing for `decrypt`.\n- JWT algorithms: `HS256/384/512`, `RS256/384/512`, `PS256/384/512`, `ES256/384/512`. ES* use\n  IEEE-P1363 (r‖s) signatures per the JWT spec.\n",
  "source": {
    "path": "shared/engines/adapters/domain/crypto/README.md",
    "blobSha": "",
    "commit": "",
    "committedAt": "",
    "provenance": "no-git",
    "bytes": 5420,
    "hash": "bd2c3b2f5e00013a437fe4b85b77b7dc4ad533b1"
  },
  "urls": {
    "html": "/p/adapters/domain/crypto",
    "json": "/docs/adapters/domain/crypto.json",
    "md": "/docs/adapters/domain/crypto.md"
  },
  "links": {
    "composes": [],
    "usedBy": [],
    "product": [],
    "howTo": [],
    "skills": []
  }
}