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

src/errors.ts

@@ -46,6 +46,24 @@ 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". Only equality-based queries are supported',
+  'E_UNSUPPORTED_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,7 @@ import {
   type ModelKeysContract,
   type ModelAssignOptions,
   type ModelAdapterOptions,
+  type ModelEncryptionContract,
   type ModelRelationOptions,
   type ModelQueryBuilderContract,
   type ModelPaginatorContract,
@@ -112,6 +113,11 @@ class BaseModelImpl implements LucidRow {
    */
   static $adapter: AdapterContract
 
+  /**
+   * Encryption provider used by encrypted columns.
+   */
+  static $encryption?: ModelEncryptionContract
+
   /**
    * Define an adapter to use for interacting with
    * the database
@@ -120,6 +126,27 @@ class BaseModelImpl implements LucidRow {
     this.$adapter = adapter
   }
 
+  /**
+   * Define encryption provider to use for encrypted columns.
+   */
+  static useEncryption(encryption: ModelEncryptionContract) {
+    this.$encryption = encryption
+  }
+
+  /**
+   * Returns encryption provider and raises when missing.
+   */
+  static $getEncryption(attributeName?: string): ModelEncryptionContract {
+    this.boot()
+
+    if (this.$encryption) {
+      return this.$encryption
+    }
+
+    const dottedAttribute = attributeName ? `${this.name}.${attributeName}` : this.name
+    throw new errors.E_MISSING_MODEL_ENCRYPTION([dottedAttribute])
+  }
+
   /**
    * Naming strategy for model properties
    */
@@ -647,6 +674,11 @@ class BaseModelImpl implements LucidRow {
      */
     this.$defineProperty('selfAssignPrimaryKey', false, 'inherit')
 
+    /**
+     * Inherit encryption provider.
+     */
+    this.$defineProperty('$encryption', undefined, 'inherit')
+
     /**
      * Define the keys' property. This allows looking up variations
      * for model keys
@@ -1357,13 +1389,26 @@ class BaseModelImpl implements LucidRow {
 
     return Object.keys(attributes).reduce((result: any, key) => {
       const column = Model.$getColumn(key)!
+      const encryption = column.meta?.encryption
 
       const value =
         typeof column.prepare === 'function'
           ? column.prepare(attributes[key], key, this)
           : attributes[key]
 
       result[column.columnName] = value
+
+      if (encryption?.mode === 'blind') {
+        const blindColumnName = encryption.blindColumnName as string
+        const purpose = encryption.purpose as string
+        const encryptionProvider = Model.$getEncryption(key)
+
+        result[blindColumnName] =
+          attributes[key] === null || attributes[key] === undefined
+            ? attributes[key]
+            : encryptionProvider.blindIndex(attributes[key], { purpose })
+      }
+
       return result
     }, {})
   }

src/orm/decorators/encrypted.ts

@@ -0,0 +1,109 @@
+/*
+ * @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}`
+
+  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) {
+    if (!options.blind.columnName?.trim()) {
+      throw new errors.E_INVALID_ENCRYPTED_COLUMN_CONFIGURATION([
+        dottedAttribute,
+        'Missing "blind.columnName"',
+      ])
+    }
+
+    if (!options.blind.purpose?.trim()) {
+      throw new errors.E_INVALID_ENCRYPTED_COLUMN_CONFIGURATION([
+        dottedAttribute,
+        'Missing "blind.purpose"',
+      ])
+    }
+
+    return {
+      mode: 'blind',
+      blindColumnName: options.blind.columnName,
+      purpose: options.blind.purpose,
+    }
+  }
+
+  if (options?.deterministic) {
+    return {
+      mode: 'deterministic',
+    }
+  }
+
+  return {
+    mode: 'standard',
+  }
+}
+
+/**
+ * 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: droppedDeterministic,
+      blind: droppedBlind,
+      ...columnOptions
+    } = options || {}
+    void droppedDeterministic
+    void droppedBlind
+    const encryptionMeta = defineEncryptedMeta(Model, property, options)
+    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 encryption = (modelInstance.constructor as LucidModel).$getEncryption(attributeName)
+        if (encryptionMeta.mode === 'deterministic') {
+          return encryption.encrypt(value, { deterministic: true })
+        }
+
+        return encryption.encrypt(value)
+      },
+      consume(value: any, attributeName: string, modelInstance: LucidRow) {
+        if (value === null || value === undefined) {
+          return value
+        }
+
+        const encryption = (modelInstance.constructor as LucidModel).$getEncryption(attributeName)
+        return encryption.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'