@zerotal/orm 1.1.0 → 1.4.0

package/CHANGELOG.md

@@ -8,11 +8,106 @@ 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
+
+- **`BaseModelWith(...)` is replaced by the `Model.using(...)` static.** Mixin composition is now
+  a property of the base class rather than a helper shipped alongside it, so there is one idiom to
+  learn and nothing extra to import.
+
+  ```ts
+  // before
+  import { BaseModelWith } from "@zerotal/orm";
+  class User extends BaseModelWith(Authenticatable, Permissions, Roles) {}
+
+  // after
+  import { Model } from "@zerotal/orm";
+  class User extends Model.using(Authenticatable, Permissions, Roles) {}
+  ```
+
+  Run `bun run scripts/codemod-mixin-composition.ts` to rewrite call sites and imports.
+
+  How mixins are **authored** is unchanged — `<T extends Constructor>(Base: T) => class extends Base`
+  still works exactly as before, and every shipped mixin (`SoftDeletes`, `State`, `Authenticatable`,
+  `Roles`, `Permissions`, `Notifiable`, `Tenantable`, `Auditable`, …) keeps its signature. The
+  `Constructor` and `Mixin` types are still exported; `Compose` (the type of `Model.using`) joins
+  them. Mixin authors declaring columns still call `registerColumn` imperatively.
+
+  `with` was deliberately **not** used for this. It is reserved for the eager-load static
+  (`User.with("posts")`), the one conspicuous gap in the model's existing query-forwarder family
+  (`where`, `whereIn`, `orderBy`, `latest`, `first`, `paginate`, `find`, `all`, `count`, …).
+
+### Changed
+
+- **`Model` is now the canonical name for the base class; `BaseModel` is the alias.** They are the
+  same class object and both remain exported, so no code breaks — but `class User extends Model {}`
+  is the documented form from here, mirroring Flow's `class PostsPage extends Component {}`.
+  `BaseModel` was previously the canonical name and `Model` an unused compat alias added in 1.0.2.
+
+### Added
+
+- **`using` composes onto any class in the chain, not just the root.** An app-level base model can
+  now carry mixins without being flattened out of the prototype chain — `AppModel.using(SoftDeletes)`
+  keeps `AppModel` and its statics in the lineage. `BaseModelWith` hardcoded `BaseModel`, so this
+  previously required hand-nesting.
+- **Composition chains.** The composed class carries `using` itself, so
+  `Model.using(a, b).using(c, d)` works past the 8-mixin overload set — which is why the overload
+  set shrank from 20 hand-written arities to 8 without losing any capability.
+
 ## [1.1.0] — 2026-08-08
 
 ### Fixed
 
-- **A `json` column returns the type it was given.** Writing skipped `JSON.stringify` for values that were already strings, so a string went into the column as bare characters — `62812345678`, not `"62812345678"` — and the read side's `JSON.parse` turned it back into a number. A `json`-cast setting holding an account number came back as a number, and only for *some* values, since a string that fails to parse fell through unchanged. Encoding is now symmetric in both directions, and `where()` against a `json` column encodes the same way, so a query finds what a write stores. **Upgrade note:** rows written by an older version hold bare scalars, so a string column may still read back as a number, and a `where()` on a string will not match those older rows — they are stored unquoted. Only affects bare scalars in `json`/`array` columns; objects and arrays were always encoded and are untouched.
+- **A `json` column returns the type it was given.** Writing skipped `JSON.stringify` for values that were already strings, so a string went into the column as bare characters — `62812345678`, not `"62812345678"` — and the read side's `JSON.parse` turned it back into a number. A `json`-cast setting holding an account number came back as a number, and only for _some_ values, since a string that fails to parse fell through unchanged. Encoding is now symmetric in both directions, and `where()` against a `json` column encodes the same way, so a query finds what a write stores. **Upgrade note:** rows written by an older version hold bare scalars, so a string column may still read back as a number, and a `where()` on a string will not match those older rows — they are stored unquoted. Only affects bare scalars in `json`/`array` columns; objects and arrays were always encoded and are untouched.
 - **`bun zt make:model` generates a file that parses.** The stub emitted `@table('posts').withTimestamps()`, which is not valid decorator syntax — the grammar allows a call at the end of the chain, not in the middle — so every generated model failed with `Expected "class" but found "."`. The stub now emits plain `@table('posts')`; timestamps are on by default and the chained form needs outer parentheses, `@(table("x").withoutTimestamps())`. The same broken form is corrected in the `BaseModel` docblocks, and every generated stub is now parsed by a test rather than checked for substrings.
 - **A column `default` is applied on insert.** A declared field that was never assigned was written as an explicit `NULL`, so the INSERT named the column, the database never applied its own default, and a `NOT NULL` column failed outright — on a model and migration that both declared `default: 0`. `undefined` now means "I didn't say": the declared default is used, or the column is omitted so the database decides. An explicit `null` still stores `NULL`.
 - **A `Date` compared against a timestamp column matches again.** Bound values are serialised through the column's cast metadata, but the framework-managed `created_at` / `updated_at` / `deleted_at` carry no `@column` registration — so a `Date` was bound raw and matched nothing. `where("created_at", ">=", monthStart)` is the commonest reporting query there is, and it silently returned zero rows: a dashboard reading "0 this month" looks like a quiet month, not a broken query.

package/README.md

@@ -43,11 +43,11 @@ export default DatabaseConfig({
 ### Define a model
 
 ```ts
-import { BaseModel, column, table, belongsTo, hasMany } from "@zerotal/orm";
+import { Model, column, table, belongsTo, hasMany } from "@zerotal/orm";
 import type { Columns } from "@zerotal/orm";
 
 @(table("posts").withTimestamps().withSoftDeletes())
-export class Post extends BaseModel {
+export class Post extends Model {
   static fillable: Columns<Post>[] = ["title", "body", "status", "userId"];
 
   @column("string") title!: string;
@@ -144,7 +144,7 @@ This package exposes two subpath entry points:
 
 Main exports from the default entry point:
 
-- **Models** — `BaseModel` / `Model`, `ModelQueryBuilder`, `DB`, `QueryBuilder`
+- **Models** — `Model` (aka `BaseModel`), `ModelQueryBuilder`, `DB`, `QueryBuilder`
 - **Decorators** — `column`, `table`, `belongsTo`, `hasMany`, `hasOne`, `manyToMany`, `morphTo`, `morphMany`, `morphOne`, `hasManyThrough`, `hasOneThrough`, `morphToMany`, `morphedByMany`
 - **Schema / migrations** — `Schema`, `Blueprint`, `Migration`, `MigrationRunner`, `SchemaInspector`, `ModelInspector`, `SchemaDiffer`, `synchronizeSchema`
 - **Seeding** — `Seeder`

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zerotal/orm",
-  "version": "1.1.0",
+  "version": "1.4.0",
   "license": "MIT",
   "maturity": "stable",
   "private": false,
@@ -30,8 +30,8 @@
     "typecheck": "tsc --noEmit"
   },
   "dependencies": {
-    "@zerotal/core": "1.1.0",
-    "@zerotal/validator": "1.1.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

@@ -1,7 +1,7 @@
 /**
  * A Bun-native Active Record ORM built on `Bun.sql`.
  *
- * Models extend {@link BaseModel}: you declare columns with {@link column | `@column`},
+ * Models extend {@link Model}: you declare columns with {@link column | `@column`},
  * relationships with decorators like {@link hasMany | `@hasMany`} and
  * {@link belongsTo | `@belongsTo`}, and then query and persist through the model's
  * static and instance methods. Under the hood a {@link QueryBuilder} routes every
@@ -11,17 +11,17 @@
  * using the {@link Schema} facade and the {@link Blueprint} table builder.
  *
  * Mass assignment is **guarded by default** — a model with neither `fillable` nor
- * `guarded` declared rejects all attributes in {@link BaseModel.fill | `fill()`}.
+ * `guarded` declared rejects all attributes in {@link Model.fill | `fill()`}.
  * Soft deletes and state machines are opt-in mixins composed via
- * {@link BaseModelWith}. The ORM's CLI commands (`migrate`, `make:model`, …) live
+ * `Model.using(...)`. The ORM's CLI commands (`migrate`, `make:model`, …) live
  * under the `@zerotal/orm/commands` subpath.
  *
  * @example Define a model
  * ```ts
- * import { BaseModel, column, hasMany, type HasMany } from "@zerotal/orm";
+ * import { Model, column, hasMany, type HasMany } from "@zerotal/orm";
  * import { Post } from "./Post.ts";
  *
- * export class User extends BaseModel {
+ * export class User extends Model {
  *   @column({ primary: true }) id!: number;
  *   @column() email!: string;
  *   @column() name!: string;
@@ -70,12 +70,14 @@
 
 // @zerotal/orm — public API barrel
 
-export { BaseModel, Model } from "./model/BaseModel.ts";
-export { BaseModelWith } from "./model/mixins.ts";
-export type { Constructor, Mixin } from "./model/mixins.ts";
-// State-machine behaviour is an opt-in mixin — compose with `BaseModelWith(State)`.
+// `Model` is the canonical base class; `BaseModel` is the same class under its original name.
+export { Model, BaseModel } from "./model/BaseModel.ts";
+// Mixin authoring types. Compose them onto a model with the `Model.using(...)` static —
+// `class User extends Model.using(Authenticatable, Roles)`.
+export type { Constructor, Mixin, Compose } from "./model/mixins.ts";
+// State-machine behaviour is an opt-in mixin — compose with `Model.using(State)`.
 export { State } from "./model/State.ts";
-// Soft deletes are opt-in — compose with `BaseModelWith(SoftDeletes)`.
+// Soft deletes are opt-in — compose with `Model.using(SoftDeletes)`.
 export { SoftDeletes } from "./model/SoftDeletes.ts";
 export type {
   StateDefinition,
@@ -143,7 +145,7 @@ export { column, columnRegistry } from "./model/decorators/column.ts";
 export type { ColumnOptions, ColumnShorthand } from "./model/decorators/column.ts";
 export { registerModel, modelByName, modelsByName } from "./model/decorators/_metadata.ts";
 // Imperative column registration — for mixin authors composing model behaviour with
-// BaseModelWith (the @column decorator can't run inside a returned class expression).
+// Model.using (the @column decorator can't run inside a returned class expression).
 export { registerColumn, columnsFor } from "./model/decorators/_metadata.ts";
 export { table } from "./model/decorators/table.ts";
 export type { TableDecoratorBuilder, TableOptions } from "./model/decorators/table.ts";
@@ -242,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

@@ -33,7 +33,16 @@ import {
 } from "../errors/index.ts";
 import { type ManyToMany } from "./relations/RelationRegistry.ts";
 import { installReactiveAccessors, type ColumnOptions } from "./decorators/column.ts";
+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";
@@ -220,6 +229,7 @@ type StringCast =
   | "float"
   | "enum"
   | "immutable_datetime"
+  | EncryptedCastName
   | `decimal:${number}`;
 type CastOption = ColumnOptions["cast"];
 
@@ -232,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);
@@ -239,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;
@@ -292,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;
@@ -360,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;
@@ -368,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) {
@@ -567,6 +587,37 @@ export class BaseModel {
    */
   declare readonly __isZerotalModel: true;
 
+  /**
+   * Compose one or more model mixins onto this class, folding them left-to-right, so reusable
+   * model behaviour (auth contract, roles, permissions, soft deletes, tenancy, …) stacks flat
+   * instead of nesting.
+   *
+   * @remarks
+   * Each mixin receives the accumulated base and returns an extended class, so this class's full
+   * static surface (`query()`, `find()`, `create()`, scopes, …) and every mixin's instance and
+   * static members flow through to the composed class — fully type-checked. Prefer this over
+   * hand-nesting mixins (`Roles(Permissions(AuthUser))`), which reads inside-out and repeats the
+   * base.
+   *
+   * `using` composes onto whatever class it is called on, so it also works on an intermediate
+   * model base, and the composed class carries `using` itself, so `Model.using(a, b).using(c)`
+   * chains past the 8-mixin overload set.
+   *
+   * Mixin authors declaring columns must call {@link registerColumn} imperatively — the `@column`
+   * decorator cannot run inside a returned class expression.
+   *
+   * @param mixins - Mixin factories applied in order; each receives the class the previous one produced.
+   * @returns A model class extending this one with every mixin applied.
+   *
+   * @example
+   * ```ts
+   * class User extends Model.using(Authenticatable, Permissions, Roles) {}
+   * ```
+   *
+   * @category Composition
+   */
+  static using: Compose = _compose;
+
   /**
    * Database table this model maps to. Usually set for you by the `@table("…")`
    * decorator; assign directly to override.
@@ -800,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
@@ -1447,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;
@@ -1529,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;
     });
@@ -1670,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());
@@ -1752,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 `];
@@ -2434,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;
@@ -2530,5 +2621,7 @@ function _applyRow(inst: BaseModel, row: Record<string, unknown>): void {
   (inst as unknown as { _original: Record<string, unknown> })._original = orig;
 }
 
-// Backward-compat alias (index.ts exports `Model`)
+// `Model` is the canonical name at the declaration site — `class User extends Model.using(…)`
+// mirrors Flow's `class PostsPage extends Component.using(…)`. `BaseModel` remains exported as
+// an alias (same class object) for code that references the base class by that name.
 export { BaseModel as Model };

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/SoftDeletes.ts

@@ -4,10 +4,10 @@
 // `deletedAt`, `forceDelete()`, `restore()`, `trashed()`, and the `withTrashed()` /
 // `onlyTrashed()` query scopes. A hard-delete model has none of these.
 //
-//   import { BaseModelWith, SoftDeletes } from "@zerotal/orm";
+//   import { Model, SoftDeletes } from "@zerotal/orm";
 //
 //   @table("posts")
-//   class Post extends BaseModelWith(SoftDeletes) {
+//   class Post extends Model.using(SoftDeletes) {
 //     @column() title!: string;
 //   }
 //
@@ -47,7 +47,7 @@ interface SoftDeleteModelClass<T extends BaseModel> {
  * @example
  * ```ts
  * @table("posts")
- * class Post extends BaseModelWith(SoftDeletes) {
+ * class Post extends Model.using(SoftDeletes) {
  *   @column() title!: string;
  * }
  *