@maestro-js/crypt 1.0.0-alpha.0

package/README.md

@@ -0,0 +1,248 @@
+# Maestro Crypt
+
+## Overview
+
+The `@maestro-js/crypt` package provides AES-256-GCM encryption and decryption with automatic key rotation. Encrypted strings use a dot-delimited format (`keyId.iv.ciphertext.authTag`) that embeds a short key identifier, allowing the correct key to be selected during decryption even after key rotation.
+
+## Quick Setup
+
+```ts
+import { Crypt } from '@maestro-js/crypt'
+import crypto from 'node:crypto'
+
+// Create a service with a 32-byte base64-encoded key
+const service = Crypt.Provider.create({
+  key: process.env.ENCRYPTION_KEY!,   // base64-encoded, 32 bytes decoded
+  previousKeys: []                     // no rotated keys yet
+})
+
+// Register as the default provider
+Crypt.Provider.register('default', service)
+
+// Encrypt and decrypt
+const encrypted = Crypt.encryptString('sensitive data')
+const plaintext = Crypt.decryptString(encrypted)  // 'sensitive data'
+```
+
+Generate a valid key: `crypto.randomBytes(32).toString('base64')`
+
+## API Reference
+
+### `Crypt.Provider.create(config)`
+
+Create a new Crypt service instance from a keyset.
+
+```ts
+function create(config: {
+  key: string            // current primary key, base64-encoded (32 bytes decoded)
+  previousKeys: string[] // previously-used keys for decryption, base64-encoded
+}): Crypt.CryptService
+```
+
+Each key is assigned a short ID (first 4 characters of its base64 SHA-256 hash). Keys must be exactly 32 bytes when decoded from base64.
+
+```ts
+const service = Crypt.Provider.create({
+  key: 'aGVsbG93b3JsZGhlbGxvd29ybGRoZWxsb3dvcmxkMTI=',
+  previousKeys: []
+})
+```
+
+### `Crypt.Provider.register(name, service)`
+
+Register a service instance in the named registry.
+
+```ts
+Crypt.Provider.register('default', service)
+```
+
+### `Crypt.provider(key)`
+
+Resolve a named provider instance. The default facade (`Crypt.encryptString`, etc.) delegates to `Crypt.provider('default')`.
+
+```ts
+const fieldCrypt = Crypt.provider('field-level')
+const encrypted = fieldCrypt.encryptString('SSN: 123-45-6789')
+```
+
+### `encryptString(plaintext)`
+
+Encrypt a plaintext string using AES-256-GCM with the current primary key. Generates a random 12-byte IV per call, so encrypting the same string twice produces different ciphertext.
+
+```ts
+encryptString(plaintext: string): string
+```
+
+Returns a dot-delimited string: `{keyId}.{iv}.{ciphertext}.{authTag}`.
+
+```ts
+const token1 = Crypt.encryptString('user-session-abc')
+const token2 = Crypt.encryptString('user-session-abc')
+// token1 !== token2 (different IVs)
+```
+
+### `decryptString(encryptedText)`
+
+Decrypt a dot-delimited cipher string. Parses the embedded key ID and tries all keys in the keyset with a matching ID. Throws if no key can decrypt the text.
+
+```ts
+decryptString(encryptedText: string): string
+```
+
+```ts
+const plaintext = Crypt.decryptString(encrypted)  // 'user-session-abc'
+```
+
+### `getEncryptingKeyId(encryptedText)`
+
+Extract the key ID from an encrypted string without decrypting it. Useful for checking whether data needs re-encryption after a key rotation.
+
+```ts
+getEncryptingKeyId(encryptedText: string): string | undefined
+```
+
+```ts
+const keyId = Crypt.getEncryptingKeyId(encrypted)  // e.g. 'aB3d'
+```
+
+### `getCurrentKeyId()`
+
+Return the ID of the current primary encryption key.
+
+```ts
+getCurrentKeyId(): string
+```
+
+```ts
+const currentId = Crypt.getCurrentKeyId()  // e.g. 'aB3d'
+
+// Check if data needs re-encryption
+if (Crypt.getEncryptingKeyId(encrypted) !== Crypt.getCurrentKeyId()) {
+  const refreshed = Crypt.encryptString(Crypt.decryptString(encrypted))
+}
+```
+
+## Key Rotation
+
+Key rotation allows transitioning to a new encryption key without breaking decryption of existing data. Move the old key into `previousKeys` and set the new key as `key`.
+
+```ts
+// Before rotation: key1 is the primary key
+const service = Crypt.Provider.create({
+  key: key1,
+  previousKeys: []
+})
+
+// After rotation: key2 is primary, key1 still decrypts old data
+const rotatedService = Crypt.Provider.create({
+  key: key2,
+  previousKeys: [key1]
+})
+
+// New encryptions use key2
+const newEncrypted = rotatedService.encryptString('new data')
+
+// Old data encrypted with key1 still decrypts
+const oldPlaintext = rotatedService.decryptString(oldEncryptedWithKey1)
+```
+
+### Re-encrypting Existing Data
+
+After rotation, identify and re-encrypt data that uses old keys:
+
+```ts
+function reEncryptIfNeeded(encryptedValue: string): string {
+  if (Crypt.getEncryptingKeyId(encryptedValue) !== Crypt.getCurrentKeyId()) {
+    return Crypt.encryptString(Crypt.decryptString(encryptedValue))
+  }
+  return encryptedValue
+}
+```
+
+## Common Patterns
+
+### Field-Level Encryption in Database Records
+
+```ts
+// Encrypt before storing
+const encryptedSsn = Crypt.encryptString('123-45-6789')
+await Db.query('INSERT INTO users (name, ssn_encrypted) VALUES (?, ?)', ['Alice', encryptedSsn])
+
+// Decrypt after reading
+const [row] = await Db.query('SELECT ssn_encrypted FROM users WHERE id = ?', [userId])
+const ssn = Crypt.decryptString(row.ssn_encrypted)  // '123-45-6789'
+```
+
+### Multiple Named Providers
+
+```ts
+// Separate keysets for different sensitivity levels
+Crypt.Provider.register('default', Crypt.Provider.create({
+  key: process.env.GENERAL_ENCRYPTION_KEY!,
+  previousKeys: []
+}))
+
+Crypt.Provider.register('pii', Crypt.Provider.create({
+  key: process.env.PII_ENCRYPTION_KEY!,
+  previousKeys: [process.env.PII_OLD_KEY!]
+}))
+
+// Use the PII provider for sensitive fields
+const piiCrypt = Crypt.provider('pii')
+const encryptedSsn = piiCrypt.encryptString(ssn)
+```
+
+### Encrypted String Format
+
+The dot-delimited format is: `{keyId}.{iv}.{ciphertext}.{authTag}`
+
+- **keyId** -- first 4 chars of the key's base64 SHA-256 hash
+- **iv** -- random 12-byte initialization vector, base64-encoded
+- **ciphertext** -- AES-256-GCM encrypted data, base64-encoded
+- **authTag** -- GCM authentication tag, base64-encoded
+
+## Testing
+
+Use `Crypt.Provider.create` directly in tests with generated keys. No mock driver is needed since encryption is CPU-only with no external dependencies.
+
+```ts
+import crypto from 'node:crypto'
+import { Crypt } from '@maestro-js/crypt'
+import { test } from 'beartest-js'
+import { expect } from 'expect'
+
+test('encrypt and decrypt a value', () => {
+  const key = crypto.randomBytes(32).toString('base64')
+  const service = Crypt.Provider.create({ key, previousKeys: [] })
+
+  const encrypted = service.encryptString('sensitive-token')
+  const decrypted = service.decryptString(encrypted)
+
+  expect(decrypted).toBe('sensitive-token')
+})
+
+test('key rotation decrypts old and new data', () => {
+  const key1 = crypto.randomBytes(32).toString('base64')
+  const key2 = crypto.randomBytes(32).toString('base64')
+
+  const oldService = Crypt.Provider.create({ key: key1, previousKeys: [] })
+  const oldEncrypted = oldService.encryptString('original-secret')
+
+  const newService = Crypt.Provider.create({ key: key2, previousKeys: [key1] })
+  const newEncrypted = newService.encryptString('new-secret')
+
+  expect(newService.decryptString(oldEncrypted)).toBe('original-secret')
+  expect(newService.decryptString(newEncrypted)).toBe('new-secret')
+  expect(newService.getEncryptingKeyId(newEncrypted)).not.toBe(
+    newService.getEncryptingKeyId(oldEncrypted)
+  )
+})
+```
+
+Run tests: `pnpm --filter @maestro-js/crypt test`
+
+## Cross-Package Integration
+
+- **Depends on**: `@maestro-js/service-registry` for the Provider pattern (registry, deferred proxy resolution)
+- **Architectural sibling**: `@maestro-js/hash` follows the same single-driver Provider pattern
+- **Standalone**: No downstream maestro packages depend on Crypt directly; it is used at the application layer for field-level encryption

package/dist/index.d.ts

@@ -0,0 +1,108 @@
+type KeysWithFallback = keyof Crypt.Provider.Keys extends never ? {
+    default: unknown;
+} : Crypt.Provider.Keys;
+/**
+ * Creates a new Crypt service instance from the given keyset.
+ *
+ * Each key is assigned a short id (first 4 chars of its SHA-256 hash, base64-encoded)
+ * which is embedded in encrypted output so the correct key can be identified during decryption.
+ *
+ * @param keysetInput - The primary key and any previous keys for decryption.
+ * @returns A CryptService with encrypt/decrypt operations bound to the provided keyset.
+ */
+declare function create(keysetInput: Crypt.Provider.CryptServiceConfig): {
+    encryptString: (plaintext: string) => string;
+    decryptString: (encryptedText: string) => string;
+    getEncryptingKeyId: (encryptedText: string) => string | undefined;
+    getCurrentKeyId: () => string;
+};
+declare function provider(key: Crypt.Provider.Key): {
+    encryptString: (plaintext: string) => string;
+    decryptString: (encryptedText: string) => string;
+    getEncryptingKeyId: (encryptedText: string) => string | undefined;
+    getCurrentKeyId: () => string;
+};
+/**
+ * AES-256-GCM encryption and decryption with automatic key rotation.
+ *
+ * Encrypted strings use a dot-delimited format (`keyId.iv.ciphertext.authTag`)
+ * that embeds a short key identifier, allowing the correct key to be selected
+ * during decryption. New data is always encrypted with the current key, while
+ * older data can still be decrypted using any previously registered key.
+ *
+ * @example
+ * ```ts
+ * Crypt.Provider.register('default', Crypt.Provider.create({
+ *   key: 'base64-encoded-32-byte-key',
+ *   previousKeys: ['old-base64-key'],
+ * }))
+ *
+ * const encrypted = Crypt.encryptString('sensitive data')
+ * Crypt.decryptString(encrypted)          // 'sensitive data'
+ * Crypt.getCurrentKeyId()                  // 'aB3d'
+ * Crypt.getEncryptingKeyId(encrypted)      // 'aB3d'
+ * ```
+ */
+declare namespace Crypt {
+    namespace Provider {
+        interface Keyset {
+            /** The current (primary) encryption key, base64-encoded. Must be 32 bytes decoded (for AES-256). */
+            key: string;
+            /** Previously-used keys that can still decrypt existing data, base64-encoded. */
+            previousKeys: string[];
+        }
+        interface CryptServiceConfig extends Keyset {
+        }
+        type Key = keyof KeysWithFallback;
+        interface Keys {
+        }
+    }
+    /**
+     * AES-256-GCM encryption service bound to a specific keyset.
+     *
+     * The service maintains an ordered list of keys:
+     *
+     * - **Current key** – used by {@link encryptString} for all new encryptions.
+     * - **Previous keys** – tried by {@link decryptString} when the embedded key
+     *   id matches, enabling zero-downtime key rotation.
+     *
+     * Each key is identified by a short id (first 4 characters of its base64
+     * SHA-256 hash) embedded in every encrypted string.
+     *
+     * @example
+     * ```ts
+     * const encrypted = Crypt.encryptString('secret')
+     * Crypt.decryptString(encrypted) // 'secret'
+     * Crypt.getEncryptingKeyId(encrypted) === Crypt.getCurrentKeyId() // true
+     * ```
+     */
+    interface CryptService {
+        /** Encrypts a plaintext string using the current key and returns a dot-delimited cipher string */
+        encryptString: (plaintext: string) => string;
+        /** Decrypts a dot-delimited cipher string, trying all keys whose id matches the embedded key id */
+        decryptString: (encryptedText: string) => string;
+        /** Extracts the key id from an encrypted string without decrypting it */
+        getEncryptingKeyId: (encryptedText: string) => string | undefined;
+        /** Returns the id of the current encryption key */
+        getCurrentKeyId: () => string;
+    }
+}
+/**
+ * AES-256-GCM encryption with automatic key rotation.
+ * Call `Crypt.Provider.create()` with a keyset and register it before use.
+ */
+declare const Crypt: {
+    provider: typeof provider;
+    encryptString: (plaintext: string) => string;
+    decryptString: (encryptedText: string) => string;
+    getEncryptingKeyId: (encryptedText: string) => string | undefined;
+    getCurrentKeyId: () => string;
+    Provider: {
+        /** Creates a new Crypt service instance from a keyset. */
+        create: typeof create;
+        /** Registers a Crypt service instance by name. Use `'default'` for the primary instance. */
+        register: (name: Crypt.Provider.Key, item: Crypt.CryptService) => void;
+    };
+};
+
+export { Crypt };

package/dist/index.js

@@ -0,0 +1,88 @@
+// src/index.ts
+import assert from "assert";
+import crypto from "crypto";
+import { ServiceRegistry } from "@maestro-js/service-registry";
+function create(keysetInput) {
+  const keyset = [keysetInput.key, ...keysetInput.previousKeys].map((key) => ({
+    key,
+    id: crypto.createHash("sha256").update(key).digest("base64").substr(0, 4)
+  }));
+  for (const k of keyset) {
+    const decoded = Buffer.from(k.key, "base64");
+    assert.ok(decoded.length === 32, `Crypt key must be 32 bytes (got ${decoded.length})`);
+  }
+  assert.ok(keyset[0], "Keyset has not been set for Crypt");
+  const primaryKey = keyset[0];
+  function encrypt(key, iv, plaintext) {
+    const cipher = crypto.createCipheriv("aes-256-gcm", Buffer.from(key.key, "base64"), iv);
+    const encrypted = Buffer.concat([cipher.update(plaintext), cipher.final()]).toString("base64");
+    const tag = cipher.getAuthTag().toString("base64");
+    return [key.id, iv, encrypted, tag].join(".");
+  }
+  function encryptString(plaintext) {
+    const iv = crypto.randomBytes(12).toString("base64");
+    return encrypt(primaryKey, iv, plaintext);
+  }
+  function decryptString(encryptedText) {
+    const [key, iv, encrypted, tag] = encryptedText.split(".");
+    assert.ok(key, "no key identified for encryptedText");
+    assert.ok(iv, "no iv identified for encryptedText");
+    assert.ok(encrypted, "no body identified for encryptedText");
+    assert.ok(tag, "no tag identified for encryptedText");
+    const matchingKeys = keyset.filter((k) => k.id === key);
+    if (matchingKeys.length === 0) {
+      throw new Error(`No key found matching id "${key}"`);
+    }
+    let err;
+    for (let decipherKey of matchingKeys) {
+      try {
+        const decipher = crypto.createDecipheriv("aes-256-gcm", Buffer.from(decipherKey.key, "base64"), iv);
+        decipher.setAuthTag(Buffer.from(tag, "base64"));
+        let plaintext = decipher.update(encrypted, "base64", "utf8");
+        plaintext += decipher.final("utf8");
+        return plaintext;
+      } catch (e) {
+        err = e;
+      }
+    }
+    throw err;
+  }
+  function getEncryptingKeyId(encryptedText) {
+    const [key] = encryptedText.split(".");
+    return key;
+  }
+  function getCurrentKeyId() {
+    return primaryKey.id;
+  }
+  return {
+    encryptString,
+    decryptString,
+    getEncryptingKeyId,
+    getCurrentKeyId
+  };
+}
+var registry = ServiceRegistry.createRegistry(ServiceRegistry.proxyFunctionsForObject);
+var Provider = {
+  /** Creates a new Crypt service instance from a keyset. */
+  create,
+  /** Registers a Crypt service instance by name. Use `'default'` for the primary instance. */
+  register: registry.register
+};
+function provider(key) {
+  const service = registry.resolve(key);
+  return {
+    encryptString: service.encryptString,
+    decryptString: service.decryptString,
+    getEncryptingKeyId: service.getEncryptingKeyId,
+    getCurrentKeyId: service.getCurrentKeyId
+  };
+}
+var facade = provider("default");
+var Crypt = {
+  Provider,
+  ...facade,
+  provider
+};
+export {
+  Crypt
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@maestro-js/crypt",
+  "description": "AES-256-GCM encryption and decryption with automatic key rotation for the maestro-js framework. Use when working with @maestro-js/crypt, encrypting or decrypting strings, rotating encryption keys, checking key IDs on encrypted data, or setting up field-level encryption. Key capabilities include AES-256-GCM authenticated encryption, dot-delimited cipher format with embedded key IDs, zero-downtime key rotation via previousKeys, per-call random IV generation, Provider pattern with deferred resolution, and key identification without decryption.",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "@maestro-js/service-registry": "1.0.0-alpha.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.9.0"
+  },
+  "version": "1.0.0-alpha.0",
+  "publishConfig": {
+    "access": "restricted"
+  },
+  "files": [
+    "dist"
+  ],
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=22.18.0"
+  },
+  "repository": "https://github.com/Marcato-Partners/maestro-js",
+  "scripts": {
+    "build": "tsup --config ../../tsup.config.ts",
+    "typecheck": "tsc --noEmit",
+    "test": "beartest ./tests/**/*",
+    "format": "prettier --write src/ tests/",
+    "lint": "prettier --check src/ tests/"
+  }
+}