@ultimatelemon-eu/crypto 1.0.0 → 1.1.0

package/README.md

@@ -28,15 +28,27 @@ 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                    |
+| 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

@@ -1,5 +1,12 @@
-export declare function encrypt(plaintext: string): string;
-export declare function decrypt(sealed: string): string;
+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

@@ -20,11 +20,14 @@ function key() {
     cached = { raw, key };
     return key;
 }
-export function encrypt(plaintext) {
+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()
@@ -33,7 +36,7 @@ export function encrypt(plaintext) {
     return [VERSION, iv, tag, data].map(encode).join('.');
 }
 // Throws when the value was tampered with or sealed under another key.
-export function decrypt(sealed) {
+export function decrypt(sealed, options = {}) {
     if (!isEncrypted(sealed))
         throw new Error('Not an encrypted value');
     const [, iv, tag, data] = sealed.split('.').map(decode);
@@ -43,6 +46,9 @@ export function decrypt(sealed) {
     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');
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimatelemon-eu/crypto",
-  "version": "1.0.0",
+  "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": {