feat(encryption): add blind index API across drivers

Author: RomainLanz

README.md

@@ -25,6 +25,7 @@ npm install @boringnode/encryption
 - **Deterministic Encryption**: AES-SIV driver for equality queries
 - **Purpose-Bound Encryption**: Ensure encrypted values are used for their intended purpose
 - **Expiration Support**: Set time-to-live on encrypted values
+- **Blind Indexes**: Deterministic indexes for equality queries
 - **Message Verification**: Sign data without encrypting (HMAC-based)
 - **Type-Safe**: Full TypeScript support with typed payloads
 
@@ -181,6 +182,32 @@ const token = encryption.encrypt({ userId: 1 }, '7d')
 encryption.decrypt(expiredToken) // => null
 ```
 
+## Blind Indexes
+
+Blind indexes are deterministic hashes used for equality queries:
+
+```typescript
+const index = encryption.blindIndex('foo@example.com', 'users.email')
+```
+
+When rotating keys, query using all blind indexes:
+
+```typescript
+const indexes = encryption.blindIndexes('foo@example.com', 'users.email')
+// Use SQL: WHERE email_index IN (...)
+```
+
+Rules:
+
+- `purpose` is required and should identify the field/context (`users.email`, `users.ssn`, ...).
+- Matching is exact-bytes (no implicit normalization).
+- Prefer normalized primitive values for blind indexes (`string`/`number`/`boolean`/ISO date).
+- For structured objects, normalize/canonicalize before indexing (for example, map object -> stable string yourself).
+
+```typescript
+const emailIndex = encryption.blindIndex(email.trim().toLowerCase(), 'users.email')
+```
+
 ## Message Verifier
 
 When you need to ensure data integrity without hiding the content, use the `MessageVerifier`. The payload is base64-encoded (not encrypted) and signed with HMAC.

src/drivers/base_driver.ts

@@ -5,9 +5,10 @@
  * @copyright Boring Node
  */
 
-import { createHash } from 'node:crypto'
+import { createHash, createHmac, hkdfSync } from 'node:crypto'
+import { MessageBuilder, type Secret } from '@poppinss/utils'
 import * as errors from '../exceptions.ts'
-import type { Secret } from '@poppinss/utils'
+import { base64UrlEncode } from '../base64.ts'
 import type { BaseConfig, CypherText, EncryptOptions } from '../types/main.ts'
 
 export abstract class BaseDriver {
@@ -16,6 +17,7 @@ export abstract class BaseDriver {
    * from the user provided secret.
    */
   cryptoKey: Buffer
+  #blindIndexKey: Buffer
 
   /**
    * Use `dot` as a separator for joining encrypted value, iv and the
@@ -26,6 +28,17 @@ export abstract class BaseDriver {
   protected constructor(config: BaseConfig) {
     const key = this.#validateAndGetSecret(config.key)
     this.cryptoKey = createHash('sha256').update(key).digest()
+
+    const rawBlindIndexKey = hkdfSync(
+      'sha256',
+      this.cryptoKey,
+      Buffer.alloc(0),
+      Buffer.from(`blind-index:${config.id || 'default'}`),
+      32
+    )
+    this.#blindIndexKey = Buffer.isBuffer(rawBlindIndexKey)
+      ? rawBlindIndexKey
+      : Buffer.from(rawBlindIndexKey)
   }
 
   /**
@@ -48,6 +61,26 @@ export abstract class BaseDriver {
     return values.join(this.separator) as CypherText
   }
 
+  blindIndex(payload: any, purpose: string): string {
+    if (typeof purpose !== 'string' || purpose.trim().length === 0) {
+      throw new errors.E_BLIND_INDEX_PURPOSE_REQUIRED()
+    }
+
+    const rawPayload = new MessageBuilder().build(payload)
+    const payloadBuffer = Buffer.isBuffer(rawPayload) ? rawPayload : Buffer.from(rawPayload)
+    const indexPayload = Buffer.concat([
+      Buffer.from(purpose),
+      Buffer.from(this.separator),
+      payloadBuffer,
+    ])
+
+    return base64UrlEncode(createHmac('sha256', this.#blindIndexKey).update(indexPayload).digest())
+  }
+
+  blindIndexes(payload: any, purpose: string): string[] {
+    return [this.blindIndex(payload, purpose)]
+  }
+
   /**
    * Encrypt a given piece of value using the app secret. A wide range of
    * data types are supported.

src/encryption.ts

@@ -63,6 +63,22 @@ export class Encryption {
     return null
   }
 
+  blindIndex(payload: any, purpose: string): string {
+    return this.#drivers[0].blindIndex(payload, purpose)
+  }
+
+  blindIndexes(payload: any, purpose: string): string[] {
+    const indexes = new Set<string>()
+
+    for (const driver of this.#drivers) {
+      for (const index of driver.blindIndexes(payload, purpose)) {
+        indexes.add(index)
+      }
+    }
+
+    return [...indexes]
+  }
+
   /**
    * Get the message verifier instance
    */

src/encryption_manager.ts

@@ -99,4 +99,12 @@ export class EncryptionManager<KnownEncrypters extends Record<string, Encryption
   decrypt<T extends any>(value: string, purpose?: string): T | null {
     return this.use().decrypt(value, purpose)
   }
+
+  blindIndex(payload: any, purpose: string): string {
+    return this.use().blindIndex(payload, purpose)
+  }
+
+  blindIndexes(payload: any, purpose: string): string[] {
+    return this.use().blindIndexes(payload, purpose)
+  }
 }

src/exceptions.ts

@@ -26,3 +26,8 @@ export const E_DETERMINISTIC_DRIVER_EXPIRES_IN_NOT_SUPPORTED = createError(
   'Deterministic encryption does not support expiresIn',
   'E_DETERMINISTIC_DRIVER_EXPIRES_IN_NOT_SUPPORTED'
 )
+
+export const E_BLIND_INDEX_PURPOSE_REQUIRED = createError(
+  'Blind index requires a non-empty purpose',
+  'E_BLIND_INDEX_PURPOSE_REQUIRED'
+)

src/types/main.ts

@@ -42,6 +42,16 @@ export interface EncryptionDriverContract {
    * Decrypt value and verify it against a purpose
    */
   decrypt<T extends any>(value: string, purpose?: string): T | null
+
+  /**
+   * Compute a deterministic blind index for equality lookups.
+   */
+  blindIndex(payload: any, purpose: string): string
+
+  /**
+   * Compute blind indexes for all keys used by the driver.
+   */
+  blindIndexes(payload: any, purpose: string): string[]
 }
 
 /**
@@ -53,6 +63,7 @@ export type ManagerDriverFactory = () => EncryptionDriverContract
 
 export interface BaseConfig {
   key: string | Secret<string>
+  id?: string
 }
 
 export interface LegacyConfig extends BaseConfig {}

tests/drivers/aes_256_cbc.spec.ts

@@ -169,4 +169,37 @@ test.group('AES-256-CBC', () => {
 
     assert.deepEqual(driver.decrypt(encrypted, 'register'), { username: 'lanz' })
   })
+
+  test('create deterministic blind index for the same value and purpose', ({ assert }) => {
+    const driver = new AES256CBC({ id: 'lanz', key: SECRET })
+    const one = driver.blindIndex('foo@example.com', 'users.email')
+    const two = driver.blindIndex('foo@example.com', 'users.email')
+
+    assert.equal(one, two)
+  })
+
+  test('return different blind index when purpose changes', ({ assert }) => {
+    const driver = new AES256CBC({ id: 'lanz', key: SECRET })
+    const one = driver.blindIndex('foo@example.com', 'users.email')
+    const two = driver.blindIndex('foo@example.com', 'users.login')
+
+    assert.notEqual(one, two)
+  })
+
+  test('return blind indexes list', ({ assert }) => {
+    const driver = new AES256CBC({ id: 'lanz', key: SECRET })
+    const indexes = driver.blindIndexes('foo@example.com', 'users.email')
+
+    assert.lengthOf(indexes, 1)
+    assert.equal(indexes[0], driver.blindIndex('foo@example.com', 'users.email'))
+  })
+
+  test('fail when blind index purpose is missing', ({ assert }) => {
+    const driver = new AES256CBC({ id: 'lanz', key: SECRET })
+
+    assert.throws(
+      () => driver.blindIndex('foo@example.com', ''),
+      'Blind index requires a non-empty purpose'
+    )
+  })
 })

tests/drivers/aes_256_gcm.spec.ts

@@ -176,4 +176,37 @@ test.group('AES-256-GCM', () => {
 
     assert.deepEqual(driver.decrypt(encrypted, 'register'), { username: 'lanz' })
   })
+
+  test('create deterministic blind index for the same value and purpose', ({ assert }) => {
+    const driver = new AES256GCM({ id: 'lanz', key: SECRET })
+    const one = driver.blindIndex('foo@example.com', 'users.email')
+    const two = driver.blindIndex('foo@example.com', 'users.email')
+
+    assert.equal(one, two)
+  })
+
+  test('return different blind index when purpose changes', ({ assert }) => {
+    const driver = new AES256GCM({ id: 'lanz', key: SECRET })
+    const one = driver.blindIndex('foo@example.com', 'users.email')
+    const two = driver.blindIndex('foo@example.com', 'users.login')
+
+    assert.notEqual(one, two)
+  })
+
+  test('return blind indexes list', ({ assert }) => {
+    const driver = new AES256GCM({ id: 'lanz', key: SECRET })
+    const indexes = driver.blindIndexes('foo@example.com', 'users.email')
+
+    assert.lengthOf(indexes, 1)
+    assert.equal(indexes[0], driver.blindIndex('foo@example.com', 'users.email'))
+  })
+
+  test('fail when blind index purpose is missing', ({ assert }) => {
+    const driver = new AES256GCM({ id: 'lanz', key: SECRET })
+
+    assert.throws(
+      () => driver.blindIndex('foo@example.com', ''),
+      'Blind index requires a non-empty purpose'
+    )
+  })
 })

tests/drivers/chacha20_poly1305.spec.ts

@@ -169,4 +169,37 @@ test.group('ChaCha20-Poly1305', () => {
 
     assert.deepEqual(driver.decrypt(encrypted, 'register'), { username: 'lanz' })
   })
+
+  test('create deterministic blind index for the same value and purpose', ({ assert }) => {
+    const driver = new ChaCha20Poly1305({ id: 'lanz', key: SECRET })
+    const one = driver.blindIndex('foo@example.com', 'users.email')
+    const two = driver.blindIndex('foo@example.com', 'users.email')
+
+    assert.equal(one, two)
+  })
+
+  test('return different blind index when purpose changes', ({ assert }) => {
+    const driver = new ChaCha20Poly1305({ id: 'lanz', key: SECRET })
+    const one = driver.blindIndex('foo@example.com', 'users.email')
+    const two = driver.blindIndex('foo@example.com', 'users.login')
+
+    assert.notEqual(one, two)
+  })
+
+  test('return blind indexes list', ({ assert }) => {
+    const driver = new ChaCha20Poly1305({ id: 'lanz', key: SECRET })
+    const indexes = driver.blindIndexes('foo@example.com', 'users.email')
+
+    assert.lengthOf(indexes, 1)
+    assert.equal(indexes[0], driver.blindIndex('foo@example.com', 'users.email'))
+  })
+
+  test('fail when blind index purpose is missing', ({ assert }) => {
+    const driver = new ChaCha20Poly1305({ id: 'lanz', key: SECRET })
+
+    assert.throws(
+      () => driver.blindIndex('foo@example.com', ''),
+      'Blind index requires a non-empty purpose'
+    )
+  })
 })

tests/encryption.spec.ts

@@ -155,4 +155,54 @@ test.group('Encryption', () => {
     const encrypted = encryption.encrypt({ username: 'virk' }, { expiresIn: '1h', purpose: 'test' })
     assert.deepEqual(encryption.decrypt(encrypted, 'test'), { username: 'virk' })
   })
+
+  test('compute blind index using first key', ({ assert }) => {
+    const encryption = new Encryption({
+      driver: (key) => new ChaCha20Poly1305({ id: 'test', key }),
+      keys: [SECRET, SECRET_2],
+    })
+
+    const blindIndex = encryption.blindIndex('foo@example.com', 'users.email')
+
+    const singleKeyEncryption = new Encryption({
+      driver: (key) => new ChaCha20Poly1305({ id: 'test', key }),
+      keys: [SECRET],
+    })
+
+    assert.equal(blindIndex, singleKeyEncryption.blindIndex('foo@example.com', 'users.email'))
+  })
+
+  test('compute blind indexes for all keys', ({ assert }) => {
+    const encryption = new Encryption({
+      driver: (key) => new ChaCha20Poly1305({ id: 'test', key }),
+      keys: [SECRET, SECRET_2],
+    })
+
+    const indexes = encryption.blindIndexes('foo@example.com', 'users.email')
+    assert.lengthOf(indexes, 2)
+
+    const singleKeyEncryption1 = new Encryption({
+      driver: (key) => new ChaCha20Poly1305({ id: 'test', key }),
+      keys: [SECRET],
+    })
+    const singleKeyEncryption2 = new Encryption({
+      driver: (key) => new ChaCha20Poly1305({ id: 'test', key }),
+      keys: [SECRET_2],
+    })
+
+    assert.include(indexes, singleKeyEncryption1.blindIndex('foo@example.com', 'users.email'))
+    assert.include(indexes, singleKeyEncryption2.blindIndex('foo@example.com', 'users.email'))
+  })
+
+  test('fail when blind index purpose is missing', ({ assert }) => {
+    const encryption = new Encryption({
+      driver: (key) => new ChaCha20Poly1305({ id: 'test', key }),
+      keys: [SECRET],
+    })
+
+    assert.throws(
+      () => encryption.blindIndex('foo@example.com', ''),
+      'Blind index requires a non-empty purpose'
+    )
+  })
 })