@ultimatelemon-eu/crypto 0.0.0-stage → 1.0.0

package/README.md

@@ -1,3 +1,42 @@
-# 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)`    | `string`  | `v1.<iv>.<tag>.<data>`, base64url, fresh IV every call |
+| `decrypt(sealed)`       | `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.

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export declare function encrypt(plaintext: string): string;
+export declare function decrypt(sealed: string): 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,65 @@
+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) {
+    const iv = randomBytes(IV_BYTES);
+    const cipher = createCipheriv(ALGORITHM, key(), iv, {
+        authTagLength: TAG_BYTES
+    });
+    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) {
+    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
+    });
+    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.0.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"
+  }
+}