@ultimatelemon-eu/crypto 0.0.0-stage → 1.1.0

package/README.md

@@ -1,3 +1,54 @@
-# Temporary Holding Version
+# @ultimatelemon-eu/crypto
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Encrypt secrets before they go into the database: API keys, OAuth tokens,
+passwords for external systems. AES-256-GCM, Node only, no dependencies.
+
+```bash
+npm install @ultimatelemon-eu/crypto
+```
+
+```ts
+import { decrypt, encrypt } from '@ultimatelemon-eu/crypto';
+
+const sealed = encrypt(apiKey); // 'v1.<iv>.<tag>.<data>'
+const apiKey = decrypt(sealed);
+```
+
+## Key
+
+`ENCRYPTION_KEY`: 32 random bytes, base64.
+
+```bash
+node -e "console.log(require('crypto').randomBytes(32).toString('base64'))"
+```
+
+Read on first use, not at import, so a build without secrets works. Missing
+or not 32 bytes throws; there is no fallback key. Losing the key means losing
+every value sealed with it.
+
+## API
+
+| Function                           | Returns   | Notes                                                  |
+| ---------------------------------- | --------- | ------------------------------------------------------ |
+| `encrypt(plaintext, { context? })` | `string`  | `v1.<iv>.<tag>.<data>`, base64url, fresh IV every call |
+| `decrypt(sealed, { context? })`    | `string`  | Throws on tampering, a wrong key or a non-sealed value |
+| `isEncrypted(value)`               | `boolean` | Type guard for the `v1.` format                        |
+| `randomToken(bytes=32)`            | `string`  | base64url, for invite links, CSRF, state               |
+| `sha256Hex(value)`                 | `string`  | Store a token's hash, not the token                    |
+
+`decrypt` also reads the same format written with standard base64, which is
+what Cellar stored before this package.
+
+Store sealed values in a `text` column.
+
+## Context
+
+Pass the row a value belongs to as `context`, and it only decrypts with that
+same context. A sealed password copied into another user's row then fails
+instead of opening their mailbox. The context is not stored; supply it again
+when decrypting.
+
+```ts
+const sealed = encrypt(password, { context: `${userId}:${accountId}` });
+const password = decrypt(sealed, { context: `${userId}:${accountId}` });
+```

package/dist/index.d.ts

@@ -0,0 +1,12 @@
+export interface SealOptions {
+    /**
+     * Bound into the tag but not stored: decrypting needs the same value, so a
+     * sealed value copied to another row (another user's id) no longer opens.
+     */
+    context?: string;
+}
+export declare function encrypt(plaintext: string, options?: SealOptions): string;
+export declare function decrypt(sealed: string, options?: SealOptions): string;
+export declare function isEncrypted(value: unknown): value is string;
+export declare function randomToken(bytes?: number): string;
+export declare function sha256Hex(value: string): string;

package/dist/index.js

@@ -0,0 +1,71 @@
+import { createCipheriv, createDecipheriv, createHash, randomBytes } from 'node:crypto';
+const ALGORITHM = 'aes-256-gcm';
+const VERSION = 'v1';
+const KEY_BYTES = 32;
+const IV_BYTES = 12;
+const TAG_BYTES = 16;
+const SEALED = /^v1\.[\w+/=-]+\.[\w+/=-]+\.[\w+/=-]*$/;
+let cached = null;
+// Read on first use, not at import, so builds without secrets still work.
+function key() {
+    const raw = process.env.ENCRYPTION_KEY;
+    if (!raw)
+        throw new Error('ENCRYPTION_KEY is not set');
+    if (cached?.raw === raw)
+        return cached.key;
+    const key = Buffer.from(raw, 'base64');
+    if (key.length !== KEY_BYTES) {
+        throw new Error(`ENCRYPTION_KEY must be ${KEY_BYTES} bytes of base64, got ${key.length} bytes`);
+    }
+    cached = { raw, key };
+    return key;
+}
+export function encrypt(plaintext, options = {}) {
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv(ALGORITHM, key(), iv, {
+        authTagLength: TAG_BYTES
+    });
+    if (options.context !== undefined) {
+        cipher.setAAD(Buffer.from(options.context, 'utf8'));
+    }
+    const data = Buffer.concat([
+        cipher.update(plaintext, 'utf8'),
+        cipher.final()
+    ]);
+    const tag = cipher.getAuthTag();
+    return [VERSION, iv, tag, data].map(encode).join('.');
+}
+// Throws when the value was tampered with or sealed under another key.
+export function decrypt(sealed, options = {}) {
+    if (!isEncrypted(sealed))
+        throw new Error('Not an encrypted value');
+    const [, iv, tag, data] = sealed.split('.').map(decode);
+    if (iv.length !== IV_BYTES || tag.length !== TAG_BYTES) {
+        throw new Error('Not an encrypted value');
+    }
+    const decipher = createDecipheriv(ALGORITHM, key(), iv, {
+        authTagLength: TAG_BYTES
+    });
+    if (options.context !== undefined) {
+        decipher.setAAD(Buffer.from(options.context, 'utf8'));
+    }
+    decipher.setAuthTag(tag);
+    return Buffer.concat([decipher.update(data), decipher.final()]).toString('utf8');
+}
+export function isEncrypted(value) {
+    return typeof value === 'string' && SEALED.test(value);
+}
+export function randomToken(bytes = 32) {
+    return randomBytes(bytes).toString('base64url');
+}
+export function sha256Hex(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function encode(part) {
+    return typeof part === 'string' ? part : part.toString('base64url');
+}
+// Node's base64 decoder also reads base64url, so values written as either
+// decrypt the same.
+function decode(part) {
+    return Buffer.from(part, 'base64');
+}

package/package.json

@@ -1,6 +1,37 @@
 {
   "name": "@ultimatelemon-eu/crypto",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.1.0",
+  "description": "AES-256-GCM encryption for secrets at rest, keyed by ENCRYPTION_KEY, plus random tokens and SHA-256. Node only, no dependencies.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ultimatelemon/packages.git",
+    "directory": "packages/crypto"
+  },
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc --project tsconfig.json",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^26.5.0",
+    "typescript": "^5.9.3",
+    "vitest": "^5.0.1"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}