feat(orm): add encrypted column decorator with deterministic and blind indexes

src/errors.ts

@@ -46,6 +46,30 @@ export const E_MODEL_DELETED = createError(
   500
 )
 
+export const E_MISSING_MODEL_ENCRYPTION = createError<[string]>(
+  'Cannot use encrypted column "%s" without a configured encryption provider. Call "BaseModel.useEncryption()" before querying or persisting encrypted columns',
+  'E_MISSING_MODEL_ENCRYPTION',
+  500
+)
+
+export const E_INVALID_ENCRYPTED_COLUMN_CONFIGURATION = createError<[string, string]>(
+  'Invalid encrypted column configuration for "%s". %s',
+  'E_INVALID_ENCRYPTED_COLUMN_CONFIGURATION',
+  500
+)
+
+export const E_UNSUPPORTED_ENCRYPTED_COLUMN_QUERY = createError<[string, string]>(
+  'Cannot use "%s" on encrypted column "%s". Encrypted columns can only be used with equality-based WHERE clauses',
+  'E_UNSUPPORTED_ENCRYPTED_COLUMN_QUERY',
+  500
+)
+
+export const E_UNSUPPORTED_STANDARD_ENCRYPTED_COLUMN_QUERY = createError<[string, string]>(
+  'Cannot use "%s" on standard encrypted column "%s". Equality queries require deterministic or blind encryption',
+  'E_UNSUPPORTED_STANDARD_ENCRYPTED_COLUMN_QUERY',
+  500
+)
+
 /**
  * The "E_ROW_NOT_FOUND" exception is raised when
  * no row is found in a database single query

src/orm/base_model/index.ts

@@ -35,6 +35,9 @@ import {
   type ModelKeysContract,
   type ModelAssignOptions,
   type ModelAdapterOptions,
+  type EncryptedColumnMode,
+  type ModelEncryptionConfig,
+  type ModelEncryptionContract,
   type ModelRelationOptions,
   type ModelQueryBuilderContract,
   type ModelPaginatorContract,
@@ -112,6 +115,11 @@ class BaseModelImpl implements LucidRow {
    */
   static $adapter: AdapterContract
 
+  /**
+   * Encryption provider used by encrypted columns.
+   */
+  static $encryption?: ModelEncryptionConfig
+
   /**
    * Define an adapter to use for interacting with
    * the database
@@ -120,6 +128,53 @@ class BaseModelImpl implements LucidRow {
     this.$adapter = adapter
   }
 
+  /**
+   * Define encryption provider to use for encrypted columns.
+   */
+  static useEncryption(config: ModelEncryptionConfig) {
+    this.$encryption = config
+  }
+
+  /**
+   * Returns encryption provider and raises when missing.
+   */
+  static $getEncryption(attributeName?: string): ModelEncryptionContract {
+    this.boot()
+
+    if (this.$encryption?.provider) {
+      return this.$encryption.provider
+    }
+
+    const dottedAttribute = attributeName ? `${this.name}.${attributeName}` : this.name
+    throw new errors.E_MISSING_MODEL_ENCRYPTION([dottedAttribute])
+  }
+
+  /**
+   * Returns encryption provider and driver for a given encrypted column mode.
+   */
+  static $resolveEncryption(
+    attributeName: string | undefined,
+    mode: EncryptedColumnMode,
+    columnDriver?: string
+  ): {
+    provider: ModelEncryptionContract
+    driver?: string
+  } {
+    const provider = this.$getEncryption(attributeName)
+    const defaults = this.$encryption?.defaults
+    const defaultDriver =
+      mode === 'deterministic'
+        ? defaults?.deterministicDriver
+        : mode === 'blind'
+          ? defaults?.blindDriver
+          : defaults?.standardDriver
+
+    return {
+      provider,
+      driver: columnDriver ?? defaultDriver,
+    }
+  }
+
   /**
    * Naming strategy for model properties
    */
@@ -1354,18 +1409,72 @@ class BaseModelImpl implements LucidRow {
    */
   protected prepareForAdapter(attributes: ModelObject) {
     const Model = this.constructor as typeof BaseModel
-
-    return Object.keys(attributes).reduce((result: any, key) => {
+    const blindWrites: Array<{
+      key: string
+      value: any
+      purpose: string
+      blindColumnName: string
+      driver?: string
+    }> = []
+    const result = Object.keys(attributes).reduce((acc: any, key) => {
       const column = Model.$getColumn(key)!
+      const attributeValue = attributes[key]
 
-      const value =
+      acc[column.columnName] =
         typeof column.prepare === 'function'
-          ? column.prepare(attributes[key], key, this)
-          : attributes[key]
+          ? column.prepare(attributeValue, key, this)
+          : attributeValue
 
-      result[column.columnName] = value
-      return result
+      const encryption = column.meta?.encryption
+      if (encryption?.mode !== 'blind') {
+        return acc
+      }
+
+      const dottedAttribute = `${Model.name}.${key}`
+      const blindColumnName = encryption.blindColumnName?.trim()
+      if (!blindColumnName) {
+        throw new errors.E_INVALID_ENCRYPTED_COLUMN_CONFIGURATION([
+          dottedAttribute,
+          'Missing "blind.columnName"',
+        ])
+      }
+
+      const purpose = encryption.purpose?.trim()
+      if (!purpose) {
+        throw new errors.E_INVALID_ENCRYPTED_COLUMN_CONFIGURATION([
+          dottedAttribute,
+          'Missing "blind.purpose"',
+        ])
+      }
+
+      blindWrites.push({
+        key,
+        value: attributeValue,
+        purpose,
+        blindColumnName,
+        driver: encryption.driver,
+      })
+
+      return acc
     }, {})
+
+    /**
+     * Apply blind writes after preparing base columns so computed blind indexes
+     * always win over any manually assigned blind column value.
+     */
+    blindWrites.forEach(({ key, value, purpose, blindColumnName, driver }) => {
+      const encryption = Model.$resolveEncryption(key, 'blind', driver)
+
+      result[blindColumnName] =
+        value === null || value === undefined
+          ? value
+          : encryption.provider.blindIndex(value, {
+              purpose,
+              driver: encryption.driver,
+            })
+    })
+
+    return result
   }
 
   /**

src/orm/decorators/encrypted.ts

@@ -0,0 +1,143 @@
+/*
+ * @adonisjs/lucid
+ *
+ * (c) AdonisJS
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+import * as errors from '../../errors.js'
+import {
+  type LucidRow,
+  type LucidModel,
+  type EncryptedColumnMeta,
+  type EncryptedColumnOptions,
+  type EncryptedColumnDecorator,
+} from '../../types/model.js'
+
+function defineEncryptedMeta(
+  model: LucidModel,
+  property: string,
+  options?: EncryptedColumnOptions
+): EncryptedColumnMeta {
+  const dottedAttribute = `${model.name}.${property}`
+  const driver = options?.driver
+
+  if (options?.deterministic && options?.blind) {
+    throw new errors.E_INVALID_ENCRYPTED_COLUMN_CONFIGURATION([
+      dottedAttribute,
+      'The "deterministic" and "blind" options cannot be used together',
+    ])
+  }
+
+  if (options?.blind) {
+    const blindColumnName = options.blind.columnName?.trim()
+    const purpose = options.blind.purpose?.trim()
+
+    if (!blindColumnName) {
+      throw new errors.E_INVALID_ENCRYPTED_COLUMN_CONFIGURATION([
+        dottedAttribute,
+        'Missing "blind.columnName"',
+      ])
+    }
+
+    if (!purpose) {
+      throw new errors.E_INVALID_ENCRYPTED_COLUMN_CONFIGURATION([
+        dottedAttribute,
+        'Missing "blind.purpose"',
+      ])
+    }
+
+    return {
+      mode: 'blind',
+      driver,
+      blindColumnName,
+      purpose,
+    }
+  }
+
+  if (options?.deterministic) {
+    return {
+      mode: 'deterministic',
+      driver,
+    }
+  }
+
+  return {
+    mode: 'standard',
+    driver,
+  }
+}
+
+/**
+ * Decorator to define an encrypted column
+ */
+export const encryptedColumn: EncryptedColumnDecorator = (options?) => {
+  return function decorateAsEncryptedColumn(target, property) {
+    const Model = target.constructor as LucidModel
+    Model.boot()
+
+    const { deterministic, blind, driver, ...columnOptions } = options || {}
+
+    const encryptionMeta = defineEncryptedMeta(Model, property, {
+      deterministic,
+      blind,
+      driver,
+    })
+    const meta = Object.assign({}, columnOptions.meta, { encryption: encryptionMeta })
+
+    Model.$addColumn(property, {
+      ...columnOptions,
+      meta,
+      prepare(value: any, attributeName: string, modelInstance: LucidRow) {
+        if (value === null || value === undefined) {
+          return value
+        }
+
+        const model = modelInstance.constructor as LucidModel
+        if (encryptionMeta.mode === 'deterministic') {
+          const encryption = model.$resolveEncryption(
+            attributeName,
+            'deterministic',
+            encryptionMeta.driver
+          )
+
+          return encryption.driver
+            ? encryption.provider.encrypt(value, {
+                deterministic: true,
+                driver: encryption.driver,
+              })
+            : encryption.provider.encrypt(value, {
+                deterministic: true,
+              })
+        }
+
+        const encryption = model.$resolveEncryption(
+          attributeName,
+          encryptionMeta.mode,
+          encryptionMeta.driver
+        )
+
+        return encryption.driver
+          ? encryption.provider.encrypt(value, { driver: encryption.driver })
+          : encryption.provider.encrypt(value)
+      },
+      consume(value: any, attributeName: string, modelInstance: LucidRow) {
+        if (value === null || value === undefined) {
+          return value
+        }
+
+        const encryption = (modelInstance.constructor as LucidModel).$resolveEncryption(
+          attributeName,
+          encryptionMeta.mode,
+          encryptionMeta.driver
+        )
+
+        return encryption.driver
+          ? encryption.provider.decrypt(value, { driver: encryption.driver })
+          : encryption.provider.decrypt(value)
+      },
+    })
+  }
+}

src/orm/decorators/index.ts

@@ -11,6 +11,7 @@ import {
   type LucidModel,
   type HooksDecorator,
   type ColumnDecorator,
+  type EncryptedColumnDecorator,
   type ComputedDecorator,
   type DateColumnDecorator,
   type DateTimeColumnDecorator,
@@ -26,6 +27,7 @@ import {
 
 import { dateColumn } from './date.js'
 import { dateTimeColumn } from './date_time.js'
+import { encryptedColumn } from './encrypted.js'
 
 /**
  * Define property on a model as a column. The decorator needs a
@@ -34,6 +36,7 @@ import { dateTimeColumn } from './date_time.js'
 export const column: ColumnDecorator & {
   date: DateColumnDecorator
   dateTime: DateTimeColumnDecorator
+  encrypted: EncryptedColumnDecorator
 } = (options?) => {
   return function decorateAsColumn(target, property) {
     const Model = target.constructor as LucidModel
@@ -44,6 +47,7 @@ export const column: ColumnDecorator & {
 
 column.date = dateColumn
 column.dateTime = dateTimeColumn
+column.encrypted = encryptedColumn
 
 /**
  * Define computed property on a model. The decorator needs a

src/orm/main.ts

@@ -10,6 +10,7 @@
 export * from './decorators/index.js'
 export * from './decorators/date.js'
 export * from './decorators/date_time.js'
+export * from './decorators/encrypted.js'
 export { BaseModel, scope } from './base_model/index.js'
 export { ModelQueryBuilder } from './query_builder/index.js'
 export { ModelPaginator } from './paginator/index.js'