enable encryption for model columns

Author: ElectronSz

README.md

@@ -34,6 +34,8 @@ _A Modern, Type-Safe, and Expressive ORM for Bun_
 - **Connection Pooling**: Efficient connection management for PostgreSQL and MySQL.
 - **Transactional Integrity**: Built-in support for atomic transactions with automatic rollback on failure.
 - **Advanced Query Builder**: Fluent, chainable API for building complex queries, including joins, filters, ordering, and pagination.
+- **Pagination Helper**: Easily paginate any query with `.paginate(page, pageSize)` and get `{ data, total, page, pageSize }`.
+- **Advanced Model Validation**: Enforce rules like `required`, `minLength`, `maxLength`, `pattern`, and custom validators—errors are thrown on invalid input.
 - **Model Relationships**: Define `OneToOne`, `ManyToOne`, `OneToMany`, and `ManyToMany` relationships in the model configuration.
 - **Soft Deletes**: Enable soft deletes in the model configuration for transparent "deleted" flags and safe row removal.
 - **Lifecycle Hooks**: Define hooks in the model configuration or as class methods for lifecycle events like `beforeCreate`, `afterUpdate`, etc.
@@ -145,59 +147,55 @@ const User = defineModel({
   },
 });
 
-// Add a hook as a class method
-User.prototype.afterCreate = async function () {
-  console.log(`Created user with ID: ${this.id}`);
-};
-
 export { User };
 ```
 
-```typescript
-// models/Role.ts
-import { defineModel, DataTypes } from "stabilize-orm";
+---
 
-const Role = defineModel({
-  tableName: "roles",
-  columns: {
-    id: { type: DataTypes.Integer, required: true },
-    name: { type: DataTypes.String, length: 50, required: true, unique: true },
-  },
-});
+## 🔍 Pagination
+
+The built-in pagination helper makes it easy to retrieve paged results and total counts in a single call.
 
-export { Role };
+```typescript
+const page = await userRepository.paginate(2, 10);
+// page = { data: [...], total: N, page: 2, pageSize: 10 }
 ```
 
+Or, use the query builder:
+
 ```typescript
-// models/UserRole.ts
-import { defineModel, DataTypes, RelationType } from "stabilize-orm";
-import { User } from "./User";
-import { Role } from "./Role";
+const page = await userRepository.find().where('isActive = ?', true).paginate(1, 20).execute();
+```
+
+---
 
-const UserRole = defineModel({
-  tableName: "user_roles",
+## 🛡️ Advanced Validation
+
+Models can define advanced validation rules for columns, including:
+
+- `required`
+- `minLength` / `maxLength`
+- `pattern` (RegExp)
+- `customValidator` (function)
+
+Validation errors are thrown on create/update if data is invalid.
+
+```typescript
+const User = defineModel({
+  tableName: "users",
   columns: {
     id: { type: DataTypes.Integer, required: true },
-    userId: { type: DataTypes.Integer, required: true, index: "idx_user_id" },
-    roleId: { type: DataTypes.Integer, required: true, index: "idx_role_id" },
-  },
-  relations: [
-    {
-      type: RelationType.ManyToOne,
-      target: () => User,
-      property: "user",
-      foreignKey: "userId",
-    },
-    {
-      type: RelationType.ManyToOne,
-      target: () => Role,
-      property: "role",
-      foreignKey: "roleId",
+    email: {
+      type: DataTypes.String,
+      required: true,
+      unique: true,
+      minLength: 6,
+      pattern: /^[^@]+@[^@]+\.[^@]+$/,
+      customValidator: (val) => val.endsWith("@offbytesecure.com") || "Must use an @offbytesecure.com email"
     },
-  ],
+    password: { type: DataTypes.String, minLength: 8 },
+  },
 });
-
-export { UserRole };
 ```
 
 ---

model.ts

@@ -23,6 +23,7 @@ export interface ColumnConfig {
     maxLength?: number;
     pattern?: RegExp;
     customValidator?: (val: any) => boolean | string;
+    encrypted?: boolean;
 
 }
 

repository.ts

@@ -17,6 +17,7 @@ import {
 } from "./types";
 import { MetadataStorage } from "./model";
 import { getHooks, type HookType } from "./hooks";
+import { decrypt, encrypt } from "./utils/encryption";
 
 type VersionOperation = "insert" | "update" | "delete";
 
@@ -132,18 +133,18 @@ export class Repository<T> {
     for (const [key, rules] of Object.entries(this.validators)) {
       const value = (entity as any)[key];
 
-      // 🔹 Required validation
+      //  Required validation
       if (rules.includes("required") && (value === undefined || value === null)) {
         throw new StabilizeError(`Field ${key} is required`, "VALIDATION_ERROR");
       }
 
-      // 🔹 Skip further checks if field is empty and not required
+      // Skip further checks if field is empty and not required
       if (value === undefined || value === null) continue;
 
       const column = this.columns?.[key];
       if (!column) continue;
 
-      // 🔹 Length validation
+      //  Length validation
       if (column.minLength && typeof value === "string" && value.length < column.minLength) {
         throw new StabilizeError(`Field ${key} too short`, "VALIDATION_ERROR");
       }
@@ -152,12 +153,12 @@ export class Repository<T> {
         throw new StabilizeError(`Field ${key} too long`, "VALIDATION_ERROR");
       }
 
-      // 🔹 Pattern validation
+      // Pattern validation
       if (column.pattern && typeof value === "string" && !column.pattern.test(value)) {
         throw new StabilizeError(`Field ${key} does not match pattern`, "VALIDATION_ERROR");
       }
 
-      // 🔹 Custom validator
+      // Custom validator
       if (typeof column.customValidator === "function") {
         const result = column.customValidator(value);
         if (result !== true) {
@@ -238,10 +239,11 @@ export class Repository<T> {
     }
     const cacheKey = `findOne:${this.table}:${id}:${options.relations?.join(",")}`;
     const results = await queryBuilder.execute(client, this.cache!, cacheKey);
+    const result = this.processForLoad(results);
     this.logger.logDebug(
       `Found ${this.table} with ID ${id} in ${(performance.now() - start).toFixed(2)}ms`,
     );
-    return results[0] || null;
+    return result[0] || null;
   }
 
   /**
@@ -423,9 +425,10 @@ export class Repository<T> {
       `Creating ${this.table} with data: ${JSON.stringify(entity)}`,
     );
     this.validate(entity);
+    const entityToSave = this.processForSave(entity);
 
     const timestamps = MetadataStorage.getTimestamps((this as any).model || Object);
-    const entityWithTimestamps = { ...entity } as Record<string, any>;
+    const entityWithTimestamps = { ...entityToSave } as Record<string, any>;
     if (timestamps.createdAt && !entityWithTimestamps[timestamps.createdAt]) {
       entityWithTimestamps[timestamps.createdAt] = new Date();
     }
@@ -443,6 +446,7 @@ export class Repository<T> {
     let id: number | string | undefined;
     const dbType = this.getDBType(client);
 
+    
     if (dbType === DBType.Postgres) {
       query += " RETURNING *";
       insertedResult = await client.query<T>(query, params);
@@ -1174,4 +1178,31 @@ export class Repository<T> {
   }
 
 
+  // Encrypt fields before save
+  private processForSave(entity: any): any {
+    const processed = { ...entity };
+    for (const [key, col] of Object.entries(this.columns)) {
+      if ((col as any).encrypted && processed[key]) {
+        processed[key] = encrypt(processed[key]);
+      }
+    }
+    return processed;
+  }
+
+  // Decrypt fields after load
+  private processForLoad(row: any): any {
+    const processed = { ...row };
+    for (const [key, col] of Object.entries(this.columns)) {
+      if ((col as any).encrypted && processed[key]) {
+        try {
+          processed[key] = decrypt(processed[key]);
+        } catch {
+          // Optionally, log or throw for corrupted/corrupt data
+          processed[key] = null;
+        }
+      }
+    }
+    return processed;
+  }
+
 }

utils/encryption.ts

@@ -0,0 +1,56 @@
+import crypto from "crypto";
+
+const ENCRYPTION_KEY =
+    process.env.ORM_ENCRYPTION_KEY || "f71a3c8e9b12d5a49c0a3f98b1f2e46d"; // 32 bytes for AES-256
+const IV_LENGTH = 16; // AES block size in bytes
+
+/**
+ * Encrypts a UTF-8 string using AES-256-CBC.
+ * @param text - The plain text to encrypt.
+ * @returns {string} Base64-encoded string in the format "iv:encrypted".
+ */
+export function encrypt(text: string): string {
+    // Convert the encryption key properly (handle hex vs utf8)
+    const keyBuffer = Buffer.from(ENCRYPTION_KEY, "utf8");
+    if (keyBuffer.length !== 32) {
+        throw new Error("ENCRYPTION_KEY must be 32 bytes (256 bits) long for AES-256");
+    }
+
+    const iv = crypto.randomBytes(IV_LENGTH);
+    const cipher = crypto.createCipheriv("aes-256-cbc", keyBuffer, iv);
+
+    const encrypted = Buffer.concat([
+        cipher.update(text, "utf8"),
+        cipher.final(),
+    ]);
+
+    return `${iv.toString("base64")}:${encrypted.toString("base64")}`;
+}
+
+/**
+ * Decrypts a string encrypted with `encrypt()`.
+ * @param text - The Base64-encoded "iv:encrypted" string.
+ * @returns {string} The decrypted plain text.
+ */
+export function decrypt(text: string): string {
+    const [ivPart, encryptedPart] = text.split(":");
+    if (!ivPart || !encryptedPart) {
+        throw new Error("Invalid encrypted text format. Expected 'iv:encrypted'.");
+    }
+
+    const iv = Buffer.from(ivPart, "base64");
+    const encrypted = Buffer.from(encryptedPart, "base64");
+
+    const keyBuffer = Buffer.from(ENCRYPTION_KEY, "utf8");
+    if (keyBuffer.length !== 32) {
+        throw new Error("ENCRYPTION_KEY must be 32 bytes (256 bits) long for AES-256");
+    }
+
+    const decipher = crypto.createDecipheriv("aes-256-cbc", keyBuffer, iv);
+    const decrypted = Buffer.concat([
+        decipher.update(encrypted),
+        decipher.final(),
+    ]);
+
+    return decrypted.toString("utf8");
+}