@zerotal/orm 1.3.0 → 1.4.0

package/CHANGELOG.md

@@ -8,6 +8,54 @@ follows the Zerotal monorepo's unified versioning.
 
 ## [Unreleased]
 
+## [1.4.0] — 2026-08-10
+
+### Added
+
+- **Encrypted columns.** A column can now hold ciphertext at rest and plaintext on
+  the model, keyed by `APP_KEY` with AES-256-GCM. Declare it per-column or as a
+  list; the two mean the same thing and resolve to the same cast:
+
+  ```ts
+  @column("encrypted", { nullable: true }) idNumber?: string;
+  @column("encrypted:json") medical?: MedicalInfo;
+
+  // …the same, spelled out — `encrypted` is a cast, not a storage type:
+  @column({ type: "text", nullable: true, cast: "encrypted" }) passportNumber?: string;
+
+  static encryptable = ["idNumber", "passportNumber"];
+  ```
+
+  `encrypted` and `encrypted:json` join the `@column("…")` shorthands, resolving
+  to `{ type: "text", cast: "encrypted" }` — so the storage type is right without
+  having to know that ciphertext outgrows its plaintext.
+
+  Encryption happens on the way to the database rather than to the instance, so —
+  unlike `hashable` — it is non-destructive: after `save()` the property still
+  holds what you assigned. `$dirty` compares plaintext, so an unchanged column is
+  not rewritten with a fresh IV on every unrelated save.
+
+  A column listed in `encryptable` whose `@column({ type })` is `json` encrypts as
+  `encrypted:json`, so it round-trips as the structure it was instead of reaching
+  the cipher as `"[object Object]"`.
+
+  **`where()` on an encrypted column throws** rather than returning nothing. The
+  bind path runs a column's cast over the search value, which would encrypt it
+  under a fresh IV and compare it against ciphertext written with a different one:
+  zero rows, no error, and a screen reading "no such client" for a client who is
+  right there. `EncryptedColumnError` says so and points at a blind index.
+
+  **A value the key cannot open fails the read**, naming the model, the column and
+  the two causes (a rotated `APP_KEY`, or plaintext that predates the cast).
+  Returning the ciphertext instead would put an unreadable value where the
+  application expects a real one — displayed, reported on, or re-encrypted by the
+  next save, which destroys the original.
+
+  `migrate:generate` and `synchronize()` widen an encrypted column to TEXT
+  whatever it was declared as. A payload is ~1.4× the plaintext plus 28 bytes, and
+  MySQL outside strict mode truncates rather than failing — a truncated payload
+  never decrypts, so the row would be destroyed silently at write time.
+
 ## [1.3.0] — 2026-08-09
 
 ### Changed — BREAKING

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/orm",
-  "version": "1.3.0",
+  "version": "1.4.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -30,8 +30,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.3.0",
-    "@zerotal/validator": "1.3.0"
+    "@zerotal/core": "1.4.0",
+    "@zerotal/validator": "1.4.0"
   },
   "devDependencies": {
     "typescript": "^5.8.0"

package/src/casts/encrypted.ts

@@ -0,0 +1,168 @@
+/**
+ * Encrypted columns — ciphertext at rest, plaintext on the model.
+ *
+ * The column stores an opaque AES-256-GCM payload keyed by `APP_KEY`; the model
+ * property holds the value you assigned. Encryption happens on the way to the
+ * database and decryption on the way back, so nothing in between — your code,
+ * validation, `$dirty` — has to know the column is encrypted.
+ *
+ * Two ways to declare one, and they compile to the same thing:
+ *
+ * ```ts
+ * class Client extends BaseModel {
+ *   @column({ type: "text", nullable: true, cast: "encrypted" })
+ *   idNumber?: string;
+ *
+ *   // …or, for several columns at once:
+ *   static encryptable = ["idNumber", "passportNumber"];
+ * }
+ * ```
+ *
+ * **The column must be `text`, not `string`.** A payload is roughly a third
+ * larger than its plaintext plus 28 bytes of IV and auth tag, so a 13-character
+ * ID number lands around 60 characters and a paragraph overflows a `VARCHAR(255)`
+ * that comfortably held it before.
+ *
+ * **You cannot query an encrypted column.** Every write draws a fresh IV, so the
+ * same value encrypts to different ciphertext each time and an equality match can
+ * never hit. `where()` on one throws rather than returning zero rows — see
+ * {@link EncryptedColumnError}. If you need lookup, keep a separate hashed column
+ * (a blind index) beside it and query that.
+ *
+ * **Decryption failure is fatal to the read**, deliberately. Returning the
+ * ciphertext instead would put an unreadable value where the application expects
+ * a real one — displayed to a user, written into a report, or re-encrypted on the
+ * next save, which destroys the original for good.
+ *
+ * @packageDocumentation
+ */
+
+import { ZerotalError } from "@zerotal/core";
+import { Crypt } from "@zerotal/core/security";
+
+/** The cast names that mean "encrypt this column". */
+export type EncryptedCastName = "encrypted" | "encrypted:json";
+
+/** Raised for anything an encrypted column cannot do. */
+export class EncryptedColumnError extends ZerotalError {
+  constructor(message: string, code: string, context?: Record<string, unknown>) {
+    super(message, code, 500, context);
+  }
+}
+
+/** Whether a resolved cast option is one of the encrypted ones. */
+export function isEncryptedCast(cast: unknown): cast is EncryptedCastName {
+  return cast === "encrypted" || cast === "encrypted:json";
+}
+
+/**
+ * Model value → the ciphertext written to the column.
+ *
+ * @param label - `Model.column`, or just the column name, for error messages.
+ */
+export function encryptColumn(value: unknown, cast: EncryptedCastName, label: string): unknown {
+  if (value === null || value === undefined) return value;
+
+  if (cast === "encrypted:json") return Crypt.encryptString(JSON.stringify(value));
+
+  if (typeof value !== "string") {
+    // Not coerced with String(). `42` would store as "42" and read back as the
+    // string "42" — the value's type silently changing between write and read,
+    // which is worse than refusing it, because nothing fails until something
+    // downstream compares it.
+    throw new EncryptedColumnError(
+      `[Zerotal] ${label} is cast "encrypted", which stores strings, but a ` +
+        `${Array.isArray(value) ? "array" : typeof value} was assigned. Use ` +
+        `cast: "encrypted:json" to encrypt a structured value — it round-trips the type.`,
+      "E_ENCRYPTED_COLUMN_NOT_A_STRING",
+      { column: label, received: typeof value },
+    );
+  }
+
+  return Crypt.encryptString(value);
+}
+
+/**
+ * Stored ciphertext → the value the model exposes.
+ *
+ * @param label - `Model.column`, for error messages.
+ * @throws {@link EncryptedColumnError} When the stored value is not ciphertext
+ *   this `APP_KEY` can open.
+ */
+export function decryptColumn(value: unknown, cast: EncryptedCastName, label: string): unknown {
+  if (value === null || value === undefined) return value;
+
+  let plain: string;
+  try {
+    plain = Crypt.decryptString(String(value));
+  } catch (cause) {
+    throw new EncryptedColumnError(
+      `[Zerotal] Could not decrypt ${label}. The column is cast "${cast}", so what is ` +
+        `stored has to be ciphertext this APP_KEY can open. Two things cause this: ` +
+        `APP_KEY changed since the row was written (decrypt with the old key and ` +
+        `re-save), or the column already held plaintext when the cast was added ` +
+        `(back-fill the existing rows before switching it on). The row cannot be read ` +
+        `until one of those is resolved.`,
+      "E_ENCRYPTED_COLUMN_UNREADABLE",
+      { column: label, cause: cause instanceof Error ? cause.message : String(cause) },
+    );
+  }
+
+  if (cast !== "encrypted:json") return plain;
+  try {
+    return JSON.parse(plain);
+  } catch {
+    // Decrypted cleanly, so the key is right and the bytes are intact — the
+    // column simply was not written as JSON. Says so, rather than reporting a
+    // key problem it does not have.
+    throw new EncryptedColumnError(
+      `[Zerotal] ${label} decrypted, but its contents are not JSON. The column is cast ` +
+        `"encrypted:json"; a column written under plain "encrypted" reads back with that.`,
+      "E_ENCRYPTED_COLUMN_NOT_JSON",
+      { column: label },
+    );
+  }
+}
+
+/** The error thrown when someone tries to filter on an encrypted column. */
+export function encryptedQueryError(label: string): EncryptedColumnError {
+  return new EncryptedColumnError(
+    `[Zerotal] Cannot filter on ${label} — it is an encrypted column. Every write draws ` +
+      `a fresh IV, so the same value encrypts to different ciphertext each time and an ` +
+      `equality match can never hit. Keep a separate hashed lookup column (a blind index) ` +
+      `beside it and query that instead.`,
+    "E_ENCRYPTED_COLUMN_NOT_QUERYABLE",
+    { column: label },
+  );
+}
+
+/**
+ * Resolve `static encryptable = [...]` down a prototype chain into cast entries.
+ *
+ * Declaring it is exactly equivalent to putting `cast: "encrypted"` on each of
+ * those columns, which is why it resolves to casts here rather than being handled
+ * separately: read, write, `$dirty` and the query guard then all see one thing.
+ *
+ * A `json` column resolves to `encrypted:json` on its own — the alternative is
+ * `String(someObject)` reaching the cipher as `"[object Object]"`.
+ *
+ * Entries union down the chain, so a base model marking a column encrypted keeps
+ * it encrypted in a subclass that lists its own.
+ *
+ * @param chain - The constructor chain, base-most first.
+ * @param columnType - Declared `@column({ type })` for a property, if any.
+ */
+export function collectEncryptable(
+  chain: readonly object[],
+  columnType: (key: string) => string | undefined,
+): Record<string, EncryptedCastName> {
+  const out: Record<string, EncryptedCastName> = {};
+  for (const entry of chain) {
+    const keys = (entry as { encryptable?: string[] }).encryptable;
+    if (!keys) continue;
+    for (const key of keys) {
+      out[key] = columnType(key) === "json" ? "encrypted:json" : "encrypted";
+    }
+  }
+  return out;
+}

package/src/index.ts

@@ -244,6 +244,11 @@ export type { DatabaseConfigShape } from "./config.ts";
 // Casts
 export { Cast, JsonCast, ArrayCast, json, objectOf, arrayOf } from "./casts/Cast.ts";
 export type { CastContract, CastMapper, CastField } from "./casts/Cast.ts";
+// Encrypted columns — `cast: "encrypted"` / `static encryptable`. The error is
+// exported so an app can catch an unreadable row (a rotated APP_KEY) and say
+// something useful instead of 500ing.
+export { EncryptedColumnError, isEncryptedCast } from "./casts/encrypted.ts";
+export type { EncryptedCastName } from "./casts/encrypted.ts";
 
 // Framework events emitted by the ORM (subscribe via core's FrameworkEvents bus).
 export {

package/src/model/BaseModel.ts

@@ -36,6 +36,13 @@ import { installReactiveAccessors, type ColumnOptions } from "./decorators/colum
 import { _compose } from "./mixins.ts";
 import type { Compose } from "./mixins.ts";
 import { columnsFor, relationsFor } from "./decorators/_metadata.ts";
+import {
+  collectEncryptable,
+  decryptColumn,
+  encryptColumn,
+  isEncryptedCast,
+  type EncryptedCastName,
+} from "../casts/encrypted.ts";
 import { TransactionContext } from "../db/TransactionContext.ts";
 import type { InsertPayload, UpdatePayload, FillablePayload } from "./payload.ts";
 import type { WhereOperator, OrderDirection } from "../db/types.ts";
@@ -222,6 +229,7 @@ type StringCast =
   | "float"
   | "enum"
   | "immutable_datetime"
+  | EncryptedCastName
   | `decimal:${number}`;
 type CastOption = ColumnOptions["cast"];
 
@@ -234,6 +242,13 @@ function getCasts(ctor: Function): Record<string, CastOption> {
     current = Object.getPrototypeOf(current) as Function | null;
   }
   chain.reverse();
+  // `static encryptable` first, so an explicit cast on the same column still wins —
+  // spelling one out is the more specific statement of intent.
+  const colReg = columnsFor(ctor);
+  Object.assign(
+    merged,
+    collectEncryptable(chain, (key) => colReg?.get(key)?.type),
+  );
   for (const entry of chain) {
     const casts = (entry as { casts?: Record<string, CastOption> }).casts;
     if (casts) Object.assign(merged, casts);
@@ -241,8 +256,9 @@ function getCasts(ctor: Function): Record<string, CastOption> {
   return merged;
 }
 
-function applyCastGet(value: unknown, cast: StringCast): unknown {
+function applyCastGet(value: unknown, cast: StringCast, label: string): unknown {
   if (value === null || value === undefined) return value;
+  if (isEncryptedCast(cast)) return decryptColumn(value, cast, label);
   const cstr = cast as unknown as string;
   if (cstr.startsWith("decimal:")) {
     const n = parseInt(cstr.slice(8), 10) || 0;
@@ -294,8 +310,9 @@ function tryParseJson(s: string): unknown {
   }
 }
 
-function applyCastSet(value: unknown, cast: StringCast): unknown {
+function applyCastSet(value: unknown, cast: StringCast, label: string): unknown {
   if (value === null || value === undefined) return value;
+  if (isEncryptedCast(cast)) return encryptColumn(value, cast, label);
   const cstr = cast as unknown as string;
   if (cstr.startsWith("decimal:")) {
     const n = parseInt(cstr.slice(8), 10) || 0;
@@ -362,6 +379,7 @@ function _serializeForWrite(
   val: unknown,
   casts: Record<string, CastOption>,
   colReg: Map<string, ColumnOptions> | null,
+  model?: string,
 ): unknown {
   const colMeta = colReg?.get(key);
   const castOpt = casts[key] ?? colMeta?.cast;
@@ -370,7 +388,7 @@ function _serializeForWrite(
   if (castOpt && typeof castOpt === "object" && castOpt.set) {
     serializedVal = castOpt.set(val);
   } else if (typeof castOpt === "string") {
-    serializedVal = applyCastSet(val, castOpt);
+    serializedVal = applyCastSet(val, castOpt, model ? `${model}.${key}` : key);
   } else if (colType === "boolean" && val !== null && val !== undefined) {
     serializedVal = val ? 1 : 0;
   } else if (colType === "json" && val !== null) {
@@ -833,6 +851,42 @@ export class BaseModel {
    */
   static hashable?: string[];
 
+  /**
+   * Columns encrypted at rest with AES-256-GCM under `APP_KEY`, and decrypted
+   * transparently on read. Shorthand for putting `cast: "encrypted"` on each one.
+   *
+   * Unlike {@link hashable} this is reversible and non-destructive: the model
+   * property still holds the value you assigned after a `save()`, because the
+   * encryption happens on the way to the database rather than to the instance.
+   * `$dirty` therefore compares plaintext, and an unchanged column is not
+   * rewritten with a new IV on every save.
+   *
+   * A `json` column in this list encrypts as `encrypted:json`, so it round-trips
+   * as the structure it was rather than as `"[object Object]"`.
+   *
+   * @example
+   * ```ts
+   * class Client extends BaseModel {
+   *   static encryptable = ["idNumber", "passportNumber"];
+   *
+   *   // TEXT, not VARCHAR — a payload outgrows its plaintext.
+   *   @column({ type: "text", nullable: true }) idNumber?: string;
+   *   @column({ type: "text", nullable: true }) passportNumber?: string;
+   * }
+   * ```
+   *
+   * @remarks
+   * Encrypted columns cannot be filtered, grouped or usefully sorted — every
+   * write draws a fresh IV, so the ciphertext for a given value never repeats.
+   * `where()` on one throws rather than quietly matching nothing. For lookup,
+   * keep a hashed blind-index column beside it. Add these to {@link hidden} too
+   * if the model is serialized to a client: decryption puts the real value back
+   * on the instance, and `toJSON()` will happily include it.
+   *
+   * @category Persistence
+   */
+  static encryptable?: string[];
+
   /**
    * Register an observer class for this model.
    * The observer's lifecycle methods (creating, created, updating, …) are
@@ -1480,7 +1534,7 @@ export class BaseModel {
         const row: Record<string, unknown> = {};
         for (const [key, val] of Object.entries(rec as Record<string, unknown>)) {
           if (key.startsWith("_")) continue;
-          row[toSnake(key)] = _serializeForWrite(key, val, casts, colReg);
+          row[toSnake(key)] = _serializeForWrite(key, val, casts, colReg, ModelClass.name);
         }
         if (useTs) {
           row["created_at"] = now;
@@ -1562,7 +1616,7 @@ export class BaseModel {
     const row: Record<string, unknown> = _writeDialect.run(dialect, () => {
       const r: Record<string, unknown> = {};
       for (const [key, val] of Object.entries(data as Record<string, unknown>)) {
-        r[toSnake(key)] = _serializeForWrite(key, val, casts, colReg);
+        r[toSnake(key)] = _serializeForWrite(key, val, casts, colReg, this.name);
       }
       return r;
     });
@@ -1703,7 +1757,7 @@ export class BaseModel {
             // value is readable straight after save() without a reload.
             self[key] = effective;
           }
-          r[toSnake(key)] = _serializeForWrite(key, effective, casts, colReg);
+          r[toSnake(key)] = _serializeForWrite(key, effective, casts, colReg, ModelClass.name);
         }
         if (ModelClass.timestamps) {
           const now = _serializeDate(new Date());
@@ -1785,7 +1839,11 @@ export class BaseModel {
       if (Object.keys(dirty).length > 0) {
         const entries = _writeDialect.run(dialect, () =>
           Object.entries(dirty).map(
-            ([k, v]) => [toSnake(k), _serializeForWrite(k, v, casts, colReg)] as [string, unknown],
+            ([k, v]) =>
+              [toSnake(k), _serializeForWrite(k, v, casts, colReg, ModelClass.name)] as [
+                string,
+                unknown,
+              ],
           ),
         );
         const segs: Seg[] = [`UPDATE ${ModelClass.table} SET `];
@@ -2467,7 +2525,7 @@ function _applyRow(inst: BaseModel, row: Record<string, unknown>): void {
       finalVal = castObj.get(rawVal);
     } else if (typeof cast === "string") {
       // Explicit shorthand cast ('boolean', 'json', 'date', etc.)
-      finalVal = applyCastGet(rawVal, cast);
+      finalVal = applyCastGet(rawVal, cast, `${ModelClass.name}.${propKey}`);
     } else if (colType === "boolean" && rawVal !== null && rawVal !== undefined) {
       // Auto-cast based on @column({ type: 'boolean' }) — SQLite stores 0/1
       finalVal = rawVal === 1 || rawVal === "1" || rawVal === true;

package/src/model/ModelQueryBuilder.ts

@@ -6,6 +6,7 @@ import {
   toSnakeColumn as _toSnakeColumn,
   ctorChain,
 } from "../support/identifiers.ts";
+import { collectEncryptable, encryptedQueryError, isEncryptedCast } from "../casts/encrypted.ts";
 import type {
   PaginateResult,
   SimplePaginateResult,
@@ -27,6 +28,14 @@ type CastOption = ColumnOptions["cast"];
 
 function _getCasts(ctor: Function): Record<string, CastOption> {
   const merged: Record<string, CastOption> = {};
+  const colReg = columnsFor(ctor);
+  // Mirrors getCasts() in BaseModel: `static encryptable` resolves to casts, and an
+  // explicit cast on the same column wins. Without this the guard below cannot see
+  // a column declared encrypted through the list form.
+  Object.assign(
+    merged,
+    collectEncryptable(ctorChain(ctor), (key) => colReg?.get(key)?.type),
+  );
   for (const entry of ctorChain(ctor)) {
     const casts = (entry as { casts?: Record<string, CastOption> }).casts;
     if (casts) Object.assign(merged, casts);
@@ -1245,6 +1254,15 @@ export class ModelQueryBuilder<M extends BaseModel> extends QueryBuilder {
     const castOpt = casts[rawKey] ?? casts[camelKey] ?? colMeta?.cast;
     const colType = colMeta?.type;
 
+    // Before anything binds: an encrypted column cannot be compared. Running the
+    // cast's set() here would encrypt the search term under a fresh IV, producing
+    // ciphertext that cannot equal what is stored — a query that always returns
+    // nothing and never says why. Same failure the created_at note below describes,
+    // and permanent rather than occasional, so it is refused outright.
+    if (isEncryptedCast(castOpt)) {
+      throw encryptedQueryError(`${this._ModelClass.name}.${camelKey}`);
+    }
+
     if (operator === "in" || operator === "not in") {
       if (Array.isArray(value)) {
         return value.map((v) => this._coerceWhereValue(column, v));

package/src/model/decorators/column.ts

@@ -29,6 +29,8 @@ export { columnRegistry };
  * | `"date"`    | `{ type: "datetime", cast: "date" }`            |
  * | `"json"`    | `{ type: "json", cast: "json" }`                |
  * | `"array"`   | `{ type: "json", cast: "array" }`               |
+ * | `"encrypted"` | `{ type: "text", cast: "encrypted" }`         |
+ * | `"encrypted:json"` | `{ type: "text", cast: "encrypted:json" }` |
  */
 export type ColumnShorthand =
   | "string"
@@ -40,7 +42,9 @@ export type ColumnShorthand =
   | "datetime"
   | "date"
   | "json"
-  | "array";
+  | "array"
+  | "encrypted"
+  | "encrypted:json";
 
 /**
  * Full option object accepted by `@column({ ... })`.
@@ -105,6 +109,12 @@ export interface ColumnOptions {
    * - 'integer'        — parseInt on both read and write
    * - 'float'          — parseFloat on both read and write
    * - 'enum'           — pass-through; pairs with `enumValues` for TS enum columns
+   * - 'encrypted'      — AES-256-GCM at rest under `APP_KEY`, plaintext on the model
+   * - 'encrypted:json' — the same, for a structured value (stringified, then encrypted)
+   *
+   * Encrypted columns need `type: "text"` (a payload outgrows the plaintext) and
+   * cannot be filtered on — `where()` against one throws, because a fresh IV per
+   * write means the ciphertext never repeats. See `casts/encrypted.ts`.
    */
   cast?:
     | "datetime"
@@ -116,6 +126,8 @@ export interface ColumnOptions {
     | "float"
     | "enum"
     | "immutable_datetime"
+    | "encrypted"
+    | "encrypted:json"
     | `decimal:${number}`
     | {
         get?: (dbValue: unknown) => unknown;
@@ -140,6 +152,10 @@ const SHORTHAND_MAP: Record<ColumnShorthand, ColumnOptions> = {
   date: { type: "datetime", cast: "date" },
   json: { type: "json", cast: "json" },
   array: { type: "json", cast: "array" },
+  // TEXT, not string: the stored payload is ~1.4× the plaintext plus 28 bytes of
+  // IV and auth tag, so a VARCHAR that held the value will not hold its ciphertext.
+  encrypted: { type: "text", cast: "encrypted" },
+  "encrypted:json": { type: "text", cast: "encrypted:json" },
 };
 
 /**

package/src/schema/ModelInspector.ts

@@ -1,6 +1,8 @@
 import path from "node:path";
 import type { ColumnOptions } from "../model/decorators/column.ts";
 import { columnRegistry, columnsFor } from "../model/decorators/_metadata.ts";
+import { ctorChain } from "../support/identifiers.ts";
+import { isEncryptedCast } from "../casts/encrypted.ts";
 
 // ── Model schema descriptor ───────────────────────────────────────────────────
 
@@ -54,12 +56,22 @@ function collectColumns(ctor: Function): Map<string, ColumnOptions> | null {
   return columnsFor(ctor);
 }
 
-function toModelColumns(fields: Map<string, ColumnOptions>): ModelColumn[] {
+function toModelColumns(
+  fields: Map<string, ColumnOptions>,
+  encrypted: ReadonlySet<string>,
+): ModelColumn[] {
   const columns: ModelColumn[] = [];
   for (const [name, opts] of fields.entries()) {
     columns.push({
       name,
-      type: opts.type,
+      // An encrypted column is generated as TEXT whatever it was declared as. The
+      // stored payload is the plaintext plus 28 bytes of IV and auth tag, base64'd —
+      // about 1.4× longer — so a VARCHAR(255) that comfortably held the value no
+      // longer holds its ciphertext. MySQL outside strict mode truncates rather than
+      // failing, and a truncated payload will not decrypt: the row is lost, quietly,
+      // at write time. The generated migration says `table.text(...)`, so the
+      // widening is visible in review rather than only here.
+      type: encrypted.has(name) ? "text" : opts.type,
       nullable: opts.nullable ?? false,
       primary: opts.primary ?? false,
       default: opts.default,
@@ -70,6 +82,21 @@ function toModelColumns(fields: Map<string, ColumnOptions>): ModelColumn[] {
   return columns;
 }
 
+/** Columns encrypted by either route — `cast: "encrypted…"` or `static encryptable`. */
+function encryptedColumns(
+  chain: readonly object[],
+  fields: Map<string, ColumnOptions>,
+): Set<string> {
+  const names = new Set<string>();
+  for (const [name, opts] of fields.entries()) {
+    if (isEncryptedCast(opts.cast)) names.add(name);
+  }
+  for (const entry of chain) {
+    for (const key of (entry as { encryptable?: string[] }).encryptable ?? []) names.add(key);
+  }
+  return names;
+}
+
 // ── ModelInspector ────────────────────────────────────────────────────────────
 
 /**
@@ -133,7 +160,7 @@ export const ModelInspector = {
       primaryKey: (M["primaryKey"] as string | undefined) ?? "id",
       timestamps: (M["timestamps"] as boolean | undefined) ?? true,
       softDeletes: (M["softDeletes"] as boolean | undefined) ?? false,
-      columns: toModelColumns(fields),
+      columns: toModelColumns(fields, encryptedColumns(ctorChain(ctor), fields)),
     };
   },
 };