@shaferllc/keel 0.80.0 → 0.81.1

package/llms-full.txt

@@ -4437,6 +4437,227 @@ router.get("/reports", handler).use(guards);
 
 
 
+---
+
+<!-- source: docs/accounts.md -->
+
+# Accounts
+
+Password reset, email verification, and two-factor authentication — the flows every
+app with a login needs, built on primitives already in core (`hash`, `encryption`,
+`mail`, `rate-limit`).
+
+They live in the framework, tested once, rather than being copy-pasted into each new
+app. A password-reset flow written five times is four copies that quietly rot.
+
+```bash
+npm install @shaferllc/keel
+```
+
+```ts
+// bootstrap/providers.ts
+import { AccountsServiceProvider } from "@shaferllc/keel/accounts";
+
+app.register(AccountsServiceProvider);
+```
+
+That merges config, adds four columns to your `users` table via a migration, and
+mounts the JSON endpoints. **Views stay yours** — these are functions and JSON
+endpoints; your controllers render the forms.
+
+## Login
+
+`attempt()` checks a password. What comes back depends on whether the user has 2FA.
+
+```ts
+const result = await attempt(email, password);
+
+if (result.status === "failed") {
+  return { error: "Those credentials don't match." };
+}
+
+if (result.status === "two-factor") {
+  // Nothing is logged in yet. Hold the challenge, ask for a code.
+  return { twoFactor: true, challenge: result.challenge };
+}
+
+auth().login(result.user.id);
+```
+
+A wrong email and a wrong password give the same answer, and take the same time —
+`attempt()` hashes against `hash.dummy` when no user is found, because a fast "no
+such user" tells an attacker which addresses are registered.
+
+## Two-factor
+
+### The challenge is not a session
+
+When 2FA is on, a correct password yields a **challenge**, not a login. Nothing is
+authenticated until the code verifies.
+
+This matters more than it looks. The usual implementation logs the user in and sets a
+`needs_2fa` flag for middleware to check — which means they are holding a real
+authenticated session *before* the second factor. Every route that forgets the
+middleware, and every `auth()` call that only asks "is anyone logged in?", is then
+bypassable with just a password. The second factor becomes advisory.
+
+Here there is no half-authenticated state to forget about, because there is no
+session. The challenge is a short-lived token bound to a single purpose, so it cannot
+be swapped for a session cookie or spent as a password-reset link.
+
+```ts
+const user = await completeTwoFactor(challenge, code);
+if (!user) return { error: "That code isn't valid." };
+
+auth().login(user.id);
+```
+
+`completeTwoFactor()` accepts an authenticator code **or** a recovery code.
+
+### Turning it on takes two steps
+
+```ts
+// Step one: a secret and recovery codes. 2FA is NOT on yet.
+const setup = await enableTwoFactor(user, { issuer: "Acme" });
+```
+
+`setup.uri` is an `otpauth://` URI to render as a QR code. `setup.secret` is for
+manual entry. `setup.recoveryCodes` are shown **once**.
+
+> Render the QR **locally**. The URI contains the shared secret, so posting it to a
+> QR-image service hands your users' second factor to a third party.
+
+```ts
+// Step two: a working code turns it on.
+const ok = await confirmTwoFactor(user, code);
+```
+
+The two-step dance is deliberate. A one-step "enable" locks out every user who scans
+the QR wrong or whose phone clock is off — and what's broken is the very thing they'd
+need to get back in. Until `confirmTwoFactor()` succeeds, `hasTwoFactor()` is false
+and login works as before.
+
+### Recovery codes
+
+Eight by default, hashed at rest, single-use — redeeming one burns it, so a code read
+over your shoulder is one you have already spent.
+
+```ts
+await recoveryCodesRemaining(user);       // worth surfacing when it gets low
+await regenerateRecoveryCodes(user);      // invalidates the old set
+await disableTwoFactor(user);             // destroys the secret and the codes
+```
+
+### What's stored
+
+The TOTP secret is **encrypted** at rest and the recovery codes are **hashed**, so a
+leaked database hands over neither the second factor nor the backdoor.
+
+TOTP itself is RFC 6238, verified against the RFC's published test vectors, and built
+on WebCrypto with no dependencies — so it runs unchanged on the edge.
+
+## Password reset
+
+```ts
+await requestPasswordReset(email);   // emails a link, or quietly does nothing
+```
+
+The answer is the same whether or not that address has an account. "No account with
+that address" is a free enumeration oracle on an unauthenticated endpoint that anyone
+can ask about anyone.
+
+```ts
+const ok = await resetPassword(token, password);
+```
+
+**A reset link works exactly once**, and there is no `password_resets` table. The
+token carries its own purpose and expiry inside the ciphertext, and it is bound to a
+fingerprint of the current password hash — so the moment the password changes, every
+token minted against the old one is dead. Nothing to store, nothing to clean up, and
+no window where a stale row is still redeemable because a cron job didn't run.
+
+## Email verification
+
+```ts
+await sendVerificationEmail(user);
+const user = await verifyEmail(token);   // idempotent
+```
+
+The token is bound to the address it was sent to. A link mailed to an old address
+cannot verify a new one — otherwise changing your email to someone else's and clicking
+an older link would mark *their* address as proven.
+
+## The endpoints
+
+Mounted at `auth` unless you turn them off (`routes.enabled: false`) and call the
+functions from your own controllers instead.
+
+| Method | Path | Notes |
+| --- | --- | --- |
+| POST | `/auth/login` | `{ email, password }` → a user, or `{ twoFactor, challenge }` |
+| POST | `/auth/two-factor` | `{ challenge, code }` — code or recovery code |
+| POST | `/auth/password/forgot` | Always `202`. Never says who exists. |
+| POST | `/auth/password/reset` | `{ token, password }` |
+| POST | `/auth/email/verify` | `{ token }` |
+| POST | `/auth/email/resend` | Always `202` |
+
+Every one is unauthenticated and touches credentials, so the group is rate-limited
+(5 per minute by default). Without a throttle, a six-digit code inside a 30-second
+window is guessable, and forgot-password is an email cannon pointed at whoever the
+caller names.
+
+## Configuration
+
+```bash
+keel vendor:publish --tag accounts-config
+```
+
+```ts
+export default {
+  userTable: "users",
+  routes: { enabled: true, prefix: "auth" },
+  passwordReset: { expiresIn: "60m", url: "/reset-password?token=:token" },
+  verification: { expiresIn: "24h", url: "/verify-email?token=:token" },
+  twoFactor: {
+    issuer: env("APP_NAME", "Keel"),
+    window: 1,               // ±30s of clock drift
+    challengeExpiresIn: "5m",
+    recoveryCodes: 8,
+  },
+  rateLimit: { max: 5, window: 60 },
+};
+```
+
+`twoFactor.challengeExpiresIn` is the window in which a stolen password alone is
+enough. Keep it short.
+
+## A different users table
+
+Accounts talks to a table through the query builder rather than assuming a `Model`.
+If your users live somewhere else — an auth service, a legacy schema — replace the
+store:
+
+```ts
+setAccountStore({
+  async findById(id) { /* … */ },
+  async findByEmail(email) { /* … */ },
+  async update(id, values) { /* … */ },
+});
+```
+
+## The schema
+
+Four columns on your users table, and no tokens table:
+
+| Column | |
+| --- | --- |
+| `email_verified_at` | null until proven |
+| `two_factor_secret` | encrypted at rest |
+| `two_factor_recovery_codes` | hashed, then encrypted |
+| `two_factor_confirmed_at` | null until a working code proves it |
+
+
+
 ---
 
 <!-- source: docs/ai.md -->
@@ -7573,6 +7794,23 @@ await db("posts").latest().get();          // ORDER BY created_at DESC
 await db("posts").oldest("published_at").get();
 ```
 
+Joins, grouping, and conditional/raw clauses:
+
+```ts
+await db("posts")
+  .join("users", "posts.user_id", "users.id")   // also leftJoin(...)
+  .select("posts.title", "users.name")
+  .get();
+
+await db("posts").select("user_id").groupBy("user_id").having("COUNT(*)", ">", 5).get();
+await db("users").distinct().select("country").pluck("country");
+
+await db("events").whereColumn("updated_at", ">", "created_at").get();
+await db("users").whereRaw("score >= ?", [10]).orderByRaw("LENGTH(name) DESC").get();
+
+await db("users").when(search, (q, term) => q.whereLike("name", `%${term}%`)).get();
+```
+
 ## Aggregates, single values, and pagination
 
 ```ts
@@ -7602,6 +7840,22 @@ Everything is parameterized — values become bindings, never string-interpolate
 SQL — so it's injection-safe by construction. Writes return a `WriteResult`;
 `insertGetId` unwraps it to just the new id.
 
+Counters, bulk upserts, and paged iteration:
+
+```ts
+await db("posts").where("id", id).increment("views");        // += 1
+await db("posts").where("id", id).decrement("stock", 3, { updated_at: now });
+
+// Insert, updating the listed columns on a unique-key conflict (dialect-aware).
+await db("users").upsert([{ id: 1, name: "Ada" }], ["id"], ["name"]);
+await db("logs").insertOrIgnore({ key, value });             // skip duplicates
+
+// Process a large table a page at a time (return false to stop early).
+await db("users").orderBy("id").chunk(500, async (rows) => {
+  for (const row of rows) await process(row);
+});
+```
+
 > **Guard your writes.** `update()` and `delete()` apply to every row that
 > matches the current `where` clause — with no `where`, that's the whole table.
 > Always scope a write with `where` unless you truly mean to touch every row.
@@ -8004,6 +8258,53 @@ await db("sessions").where("expires_at", "<", now).delete();
 **Notes:** with no `where`, empties the table. There's no soft-delete here — pair
 with a `deleted_at` column and `whereNull` if you want one.
 
+#### `whereColumn(first, operator?, second)` · `whereRaw(sql, bindings?)`
+
+Compare two columns (no binding) or add a raw WHERE fragment with its own
+bindings. `whereColumn("updated_at", ">", "created_at")`; `whereRaw("score >= ?", [10])`.
+
+#### `join(table, first, operator?, second)` · `leftJoin(...)`
+
+Add an `INNER JOIN` / `LEFT JOIN` on an equality (or the given operator).
+Included in `get`, `count`, and aggregates. Qualify ambiguous columns
+(`"posts.user_id"`).
+
+#### `groupBy(...columns)` · `having(column, operator?, value)` · `distinct()`
+
+`GROUP BY`, a bound `HAVING` predicate, and `SELECT DISTINCT`.
+
+#### `orderByRaw(sql)` · `when(condition, then, otherwise?)`
+
+A raw `ORDER BY` fragment; and conditional building — `then(query, value)` runs
+only when `condition` is truthy, else `otherwise`.
+
+#### `increment(column, amount?, extra?)` · `decrement(column, amount?, extra?)`
+
+`increment(column: string, amount = 1, extra: Row = {}): Promise<WriteResult>`
+
+Atomically `column = column ± amount` on matching rows, optionally setting other
+columns in the same statement. Scope with `where`.
+
+#### `upsert(rows, uniqueBy, update?)`
+
+`upsert(rows: Row | Row[], uniqueBy: string[], update?: string[]): Promise<WriteResult>`
+
+Insert rows, updating `update` columns (default: all non-unique) on a conflict
+against `uniqueBy`. Dialect-aware: `ON CONFLICT … DO UPDATE` (sqlite/postgres) or
+`ON DUPLICATE KEY UPDATE` (mysql).
+
+#### `insertOrIgnore(rows)`
+
+Insert one or more rows, skipping any that violate a unique constraint
+(`INSERT OR IGNORE` / `INSERT IGNORE` / `ON CONFLICT DO NOTHING`).
+
+#### `chunk(size, callback)`
+
+`chunk(size: number, callback: (rows: T[]) => void | boolean | Promise<void | boolean>): Promise<void>`
+
+Process results a page at a time so a large table never loads at once. Return
+`false` from the callback to stop early. Pair with `orderBy` for a stable order.
+
 ### Interfaces & types
 
 #### `Connection`
@@ -12745,12 +13046,41 @@ t.boolean("active").default(true);     // sqlite: DEFAULT 1, else DEFAULT true
 t.integer("retries").default(0);       // ... DEFAULT 0
 ```
 
-For anything the builder doesn't cover — indexes, foreign keys, an `ALTER
-TABLE` — `schema.raw(sql, bindings?)` runs arbitrary SQL:
+### Indexes and foreign keys
+
+`createTable` builds indexes and foreign keys alongside the columns:
+
+```ts
+schema.createTable("members", (t) => {
+  t.id();
+  t.integer("team_id");
+  t.string("email");
+  t.uniqueIndex("email");                       // or t.index(["a", "b"]) for composite
+  t.foreign("team_id").references("id").on("teams").onDelete("cascade");
+});
+```
+
+### Altering a table
+
+`schema.alterTable(name, build)` adds, renames, and drops columns and indexes on
+an existing table (dialect-aware SQL). Drop an index before the column it covers:
 
 ```ts
 up: (schema) =>
-  schema.raw("CREATE INDEX idx_posts_user ON posts (user_id)"),
+  schema.alterTable("users", (t) => {
+    t.string("phone").nullable();     // ADD COLUMN
+    t.renameColumn("name", "full_name");
+    t.index("phone");
+    t.dropIndex("users_legacy_index");
+    t.dropColumn("legacy");
+  }),
+```
+
+For anything the builder still doesn't cover, `schema.raw(sql, bindings?)` runs
+arbitrary SQL:
+
+```ts
+up: (schema) => schema.raw("CREATE INDEX idx_posts_user ON posts (user_id)"),
 ```
 
 > `raw()` writes through the connection **without** placeholder conversion, so
@@ -12928,11 +13258,10 @@ already gone — the typical `down()` for a `createTable`.
 
 `raw(sql: string, bindings?: unknown[]): Promise<void>`
 
-Runs arbitrary SQL through the connection — the escape hatch for indexes, foreign
-keys, and `ALTER TABLE`.
+Runs arbitrary SQL through the connection — the escape hatch for anything the
+builders don't cover.
 
 ```ts
-await schema.raw("CREATE INDEX idx_posts_user ON posts (user_id)");
 await schema.raw("UPDATE users SET active = ? WHERE active IS NULL", [true]);
 ```
 
@@ -12940,6 +13269,22 @@ await schema.raw("UPDATE users SET active = ? WHERE active IS NULL", [true]);
 `raw()` does **not** rewrite `?` to `$n`, so pass `$1, $2, …` yourself on the
 `postgres` dialect.
 
+#### `alterTable(name, build)`
+
+`alterTable(name: string, build: (table: AlterTableBuilder) => void): Promise<void>`
+
+Alter an existing table — the callback gets an [`AlterTableBuilder`](#altertablebuilder)
+for adding, renaming, and dropping columns and indexes. Emits one dialect-aware
+statement per operation, ordered so a dropped index precedes its column.
+
+```ts
+await schema.alterTable("users", (t) => {
+  t.string("phone").nullable();
+  t.renameColumn("name", "full_name");
+  t.dropColumn("legacy");
+});
+```
+
 ### `TableBuilder`
 
 Describes a table's columns. **You get one from the `createTable` callback** — it
@@ -13056,6 +13401,27 @@ t.toCreateSql("users", "postgres");
 // CREATE TABLE users (id SERIAL PRIMARY KEY, email VARCHAR(255) NOT NULL)
 ```
 
+#### `index(columns, name?)` / `uniqueIndex(columns, name?)`
+
+Add a (possibly composite) index or unique index; `columns` is a name or array.
+Emitted as `CREATE [UNIQUE] INDEX` after the table. Auto-named unless `name` is
+given.
+
+```ts
+t.index("email");
+t.uniqueIndex(["team_id", "slug"]);
+```
+
+#### `foreign(column)`
+
+`foreign(column: string): ForeignKeyBuilder`
+
+Add a foreign key, built fluently and emitted inline in the `CREATE TABLE`.
+
+```ts
+t.foreign("team_id").references("id").on("teams").onDelete("cascade");
+```
+
 #### `columns`
 
 `readonly columns: Column[]`
@@ -13063,6 +13429,21 @@ t.toCreateSql("users", "postgres");
 The `Column` instances added so far, in declaration order. Read-only inspection
 seam; you rarely touch it.
 
+### `AlterTableBuilder`
+
+From the `alterTable` callback. Column methods (`string`, `integer`, …) **add**
+columns; plus:
+
+- `dropColumn(name)` — drop a column.
+- `renameColumn(from, to)` — rename a column.
+- `index(columns, name?)` / `uniqueIndex(columns, name?)` — add an index.
+- `dropIndex(name)` — drop an index (runs before column drops).
+
+### `ForeignKeyBuilder`
+
+From `TableBuilder.foreign(column)`. Chainable: `references(column)`, `on(table)`,
+`onDelete(action)`, `onUpdate(action)`.
+
 ### `Column`
 
 A single column definition. **You get one from a `TableBuilder` method** (`t.string(...)` etc.) — you don't construct it in migrations. Modifier methods
@@ -13328,6 +13709,110 @@ return json(user);       // works directly — json() serializes it
 user.fill({ name: "X" }); // merge mass-assignable attributes without saving
 ```
 
+Control what `toJSON()` exposes with three statics. `hidden` strips columns;
+`visible` is an allowlist that wins over everything; `appends` adds computed
+attributes — a getter or a zero-arg method on the model:
+
+```ts
+class User extends Model {
+  static table = "users";
+  static hidden = ["password"];       // never serialized
+  static appends = ["fullName"];      // added to the output
+  get fullName() { return `${this.first} ${this.last}`; }
+}
+```
+
+## Lifecycle events
+
+A model fires events as it is retrieved, saved, and deleted. Hook onto them to
+slug a title, bust a cache, or cascade — without touching every call site. The
+`*ing` events are **cancelable**: a hook returning `false` aborts the write.
+
+```ts
+User.creating((user) => { user.uuid = crypto.randomUUID(); });
+User.saved((user) => cache().forget(`user:${user.id}`));
+User.deleting((user) => (user.isRoot ? false : undefined)); // veto
+
+// Or group them in an observer:
+User.observe({
+  creating: (u) => { u.uuid = crypto.randomUUID(); },
+  deleted:  (u) => audit(`deleted ${u.id}`),
+});
+```
+
+Events: `retrieved`, `creating`/`created`, `updating`/`updated`,
+`saving`/`saved`, `deleting`/`deleted`, `restoring`/`restored`. They're keyed by
+the exact class (subclasses don't inherit a parent's hooks).
+
+## Query scopes
+
+A **global scope** constrains every query a model builds — the base for
+multi-tenancy, published-only reads, and soft deletes:
+
+```ts
+Post.addGlobalScope("published", (q) => q.where("published", true));
+await Post.all();        // only published
+await Post.query().where("author_id", 1).get();  // still only published
+```
+
+Scopes **inherit**. A scope declared on a base class constrains every model that
+extends it — which is what makes a single tenant-scoped base class possible:
+
+```ts
+class TenantModel extends Model {}
+TenantModel.addGlobalScope("tenant", (q) => q.where("teamId", currentTeamId()));
+
+class Post extends TenantModel {}   // scoped, without repeating yourself
+```
+
+Scopes from several levels all apply, and a subclass overrides an ancestor's scope
+by reusing its name — the nearest declaration wins.
+
+### Escaping a scope
+
+```ts
+await Post.withoutGlobalScope("tenant").get();   // one named scope
+await Post.withoutGlobalScopes().get();          // all of them
+```
+
+Escaping is deliberately explicit, and worth keeping that way. A query that steps
+outside a tenancy scope is exactly the thing you want to be able to *find* — so it
+should be typed out and greppable, never something you arrive at by forgetting a
+`where`.
+
+A **local scope** is just a static method returning a query — no framework
+feature needed:
+
+```ts
+class Post extends Model {
+  static popular() { return this.query().where("views", ">", 1000); }
+}
+await Post.popular().orderBy("views", "desc").get();
+```
+
+## Soft deletes
+
+Opt in with `static softDeletes = true` and a `deleted_at` column. `delete()`
+then sets the timestamp instead of removing the row, and a global scope hides
+soft-deleted rows from every query.
+
+```ts
+class User extends Model {
+  static table = "users";
+  static softDeletes = true;
+  static casts = { deleted_at: "date" };
+}
+
+await user.delete();          // sets deleted_at; row stays in the table
+user.trashed();               // true
+await User.find(user.id);     // null — hidden by the scope
+
+await User.withTrashed().get();   // include soft-deleted
+await User.onlyTrashed().get();   // only soft-deleted
+await user.restore();             // clear deleted_at
+await user.forceDelete();         // remove the row for good
+```
+
 ## Relationships
 
 Define a relationship as a method that returns one of `hasMany` / `hasOne` /
@@ -13377,6 +13862,29 @@ users[0].toJSON();             // includes `posts` and `roles`
 Loaded relations are stored off the model, so they never leak into `save()`,
 and `toJSON()` serializes them (nested models included).
 
+### Querying relationships (`with`, `withCount`, `whereHas`)
+
+`Model.query()` returns a model-aware builder with the relationship operations a
+raw query can't express. `with()` eager-loads (dotted paths nest), `withCount()`
+adds a `<relation>_count`, and `has`/`whereHas`/`doesntHave` filter by whether a
+related row exists:
+
+```ts
+const users = await User.query()
+  .where("active", true)
+  .with("posts.comments")                       // nested eager load
+  .withCount("posts")                            // users[i].posts_count
+  .whereHas("posts", (q) => q.where("published", true))
+  .get();
+
+await User.has("posts").get();        // users with at least one post
+await User.doesntHave("posts").get(); // users with none
+```
+
+`with`/`withCount`/`whereHas`/`has`/`doesntHave` are also static shortcuts
+(`User.with(...)`, `User.whereHas(...)`). Existence filters use the same
+driver-agnostic two-query strategy as the relations themselves — no JOIN.
+
 ### Many-to-many
 
 `belongsToMany` reads through a pivot table (default name: the two table names
@@ -13397,11 +13905,39 @@ this.belongsTo(User, "owner_id", "id");
 this.belongsToMany(Role, "user_roles", "user_id", "role_id");
 ```
 
+### Polymorphic
+
+A polymorphic relation lets one model belong to more than one type. The related
+rows carry `<name>_id` + `<name>_type`; register each owner type so `morphTo`
+can resolve it:
+
+```ts
+class Post extends Model {
+  comments() { return this.morphMany(Comment, "commentable"); }
+}
+class Video extends Model {
+  comments() { return this.morphMany(Comment, "commentable"); }
+}
+class Comment extends Model {
+  commentable() { return this.morphTo("commentable"); } // resolves back to Post or Video
+}
+
+registerMorphType("Post", Post);
+registerMorphType("Video", Video);
+
+await post.comments().create({ body: "nice" }); // sets commentable_id/_type
+const owner = await comment.commentable();       // Post | Video | null
+```
+
+`morphOne` is the one-to-one variant. Eager loading (`Model.load` / `with`) works
+across mixed types.
+
 ## What this is (and isn't)
 
-This is a deliberately small active-record — enough for CRUD, relationships,
-casts, and simple queries without an ORM dependency. Nested eager loading
-(`posts.comments`) and query-time `with()` aren't here yet. For complex schemas
+This is a compact active-record — CRUD, lifecycle events, scopes, soft deletes,
+serialization control, eager loading (including nested `with("posts.comments")`),
+relationship queries (`whereHas`/`withCount`), and polymorphic relations — all on
+a driver-agnostic query builder, no ORM dependency. For complex one-off queries
 you can always drop to `db()` or your driver directly.
 
 ---
@@ -13557,6 +14093,55 @@ Rarely called directly — `create`/`save` use it internally.
 const storable = Post.toDatabase({ published: true }); // { published: 1 }
 ```
 
+#### `Model.with(...names)` · `Model.withCount(...names)`
+
+Start a [`ModelQuery`](#modelquery) that eager-loads the named relations (dotted
+paths nest: `"posts.comments"`) or counts them into `<relation>_count`.
+
+#### `Model.has(name)` · `Model.whereHas(name, constrain?)` · `Model.doesntHave(name, constrain?)`
+
+Start a `ModelQuery` filtered by relationship existence — has at least one
+related row, has one matching `constrain(query)`, or has none. `constrain`
+receives the related-table query builder.
+
+#### `Model.newQuery()`
+
+`static newQuery(): ModelQuery<T>`
+
+The model-aware query behind the sugar above — hydrates rows to models and adds
+`with`/`withCount`/`whereHas`.
+
+#### `Model.addGlobalScope(name, scope)`
+
+`static addGlobalScope(name: string, scope: (query: QueryBuilder) => void): void`
+
+Register a constraint applied to every query the model builds. Inherited by
+subclasses; a subclass re-using a name overrides it.
+
+#### `Model.withTrashed()` · `Model.onlyTrashed()` · `Model.withoutGlobalScope(...names)` · `Model.withoutGlobalScopes()`
+
+Escape hatches returning a `QueryBuilder`: include (or only) soft-deleted rows,
+or drop named / all global scopes. Deliberately explicit so an unscoped query is
+greppable at audit time.
+
+### `Model` — lifecycle events
+
+Register per-class hooks (keyed by the exact class). The `*ing` events are
+cancelable — a hook returning `false` aborts the operation.
+
+#### `Model.creating` · `created` · `updating` · `updated` · `saving` · `saved` · `deleting` · `deleted` · `restoring` · `restored` · `retrieved`
+
+`static <event>(hook: (model: T) => void | boolean | Promise<void | boolean>): void`
+
+Add a hook for that lifecycle event. `create()` fires `saving`→`creating`→write→
+`created`→`saved`; a save that updates fires the `updating`/`updated` pair.
+
+#### `Model.observe(observer)`
+
+`static observe(observer: Partial<Record<ModelEvent, ModelHook<T>>>): void`
+
+Attach an observer object — each method named after an event becomes a hook.
+
 ### `Model` — configuration statics
 
 Set these on the subclass to configure it. All have defaults.
@@ -13617,6 +14202,21 @@ class Post extends Model {
 }
 ```
 
+#### `static hidden` / `static visible` / `static appends`
+
+`static hidden: string[]` · `static visible: string[]` · `static appends: string[]`
+
+Shape `toJSON()`: `hidden` strips columns, `visible` is an allowlist that wins,
+`appends` adds computed attributes (a getter or zero-arg method). All default `[]`.
+
+#### `static softDeletes` / `static deletedAtColumn`
+
+`static softDeletes: boolean` (default `false`) · `static deletedAtColumn: string`
+(default `"deleted_at"`)
+
+Turn on soft deletes: `delete()` sets the timestamp and a global scope hides
+trashed rows.
+
 ### `Model` — instance methods
 
 #### `new Model(attributes?)`
@@ -13655,14 +14255,22 @@ still issues the query.
 
 `delete(): Promise<void>`
 
-Deletes the row matching this model's primary key.
+Deletes the row matching this model's primary key — or, with `static softDeletes`
+on, sets `deleted_at` instead. Fires `deleting`/`deleted`.
 
 ```ts
 await user.delete();
 ```
 
-**Notes:** keys off the current `primaryKey` value; on a model without one, the
-`where` binds `undefined`. Hard delete only — there's no soft-delete built in.
+**Notes:** keys off the current `primaryKey` value. See `forceDelete`/`restore`
+for the soft-delete variants.
+
+#### `forceDelete()` · `restore()` · `trashed()`
+
+`forceDelete(): Promise<void>` · `restore(): Promise<this>` · `trashed(): boolean`
+
+For soft-deletable models: permanently remove the row, clear `deleted_at`
+(fires `restoring`/`restored`), or test whether it's currently trashed.
 
 #### `fill(attributes)`
 
@@ -13792,6 +14400,52 @@ joined with `_` (User + Role → `role_user`). The pivot keys default to
 `<model>_<primaryKey>`. Reads as two `whereIn` queries (no JOIN), so it stays
 edge-safe.
 
+#### `morphMany(related, name, localKey?)` · `morphOne(related, name, localKey?)`
+
+`morphMany<T>(related: ModelClass<T>, name: string, localKey?: string): MorphMany<T>`
+
+The parent side of a polymorphic relation. Related rows carry `<name>_id` +
+`<name>_type` (the type stored is this model's class name). `MorphMany` also has
+`.create(attributes)`, which fills the morph keys.
+
+```ts
+comments() { return this.morphMany(Comment, "commentable"); }
+```
+
+#### `morphTo(name, idColumn?, typeColumn?)`
+
+`morphTo(name: string, idColumn?: string, typeColumn?: string): MorphTo`
+
+The owning side — resolves the parent from the stored `<name>_type` (via
+[`registerMorphType`](#registermorphtypetype-model)) and `<name>_id`. Awaitable;
+returns the parent model or `null`.
+
+```ts
+commentable() { return this.morphTo("commentable"); }
+```
+
+#### `registerMorphType(type, model)`
+
+`registerMorphType(type: string, related: ModelClass<Model>): void`
+
+Register a model under a morph-type string (usually its class name) so `morphTo`
+can resolve it. Call once at boot for each owner type.
+
+### `ModelQuery`
+
+The model-aware builder returned by `Model.query()`, `Model.newQuery()`, and the
+`with`/`whereHas`/`withCount` shortcuts. It proxies the query-builder constraint
+methods (`where`, `orderBy`, `limit`, …) and hydrates results to models, adding:
+
+- `with(...names)` — eager-load relations; dotted paths nest (`"posts.comments"`).
+- `withCount(...names)` — add `<relation>_count` to each result.
+- `has(name)` / `whereHas(name, constrain?)` / `doesntHave(name, constrain?)` —
+  filter by relationship existence.
+- Terminals `get()`, `first()`, `count()`, `exists()`, `paginate(page?, perPage?)`.
+
+Existence filters and counts use the same driver-agnostic two-query strategy as
+the relations (no JOIN). `toBase()` returns the underlying `QueryBuilder`.
+
 ### Relations
 
 You never `new` these — a relationship method (`user.posts()`) returns one. Each
@@ -17377,6 +18031,189 @@ Optional capabilities: `metadata` / `copy` / `move` / `signedUrl` /
 
 
 
+---
+
+<!-- source: docs/teams.md -->
+
+# Teams
+
+Multi-tenancy, membership, roles, and invitations — where a row belongs to a team,
+and one team can never see another's.
+
+```ts
+// bootstrap/providers.ts
+import { TeamsServiceProvider } from "@shaferllc/keel/teams";
+
+app.register(TeamsServiceProvider);
+```
+
+```ts
+// app/Http/Kernel.ts
+import { teamContext } from "@shaferllc/keel/teams";
+
+protected middleware = [sessionMiddleware(), teamContext()];
+```
+
+Then a tenant-owned model is one word:
+
+```ts
+import { TenantModel } from "@shaferllc/keel/teams";
+
+class Post extends TenantModel {
+  static table = "posts";
+}
+
+await Post.all();                     // only the current team's posts
+await Post.create({ title: "Hi" });   // stamped with the current team
+```
+
+## Isolation is the default, not a habit
+
+Two halves, and both matter.
+
+**Reads** are constrained by a global scope on `TenantModel`, so every query the
+model builds carries the team — including `find()`. Naming another team's row by its
+id returns `null`, not that row. This is the difference between tenancy and a list
+filter: a filter you forget on one endpoint is a leak; a scope you never write can't
+be forgotten.
+
+**Writes** are stamped by a `creating` hook, so a row cannot be born ownerless and
+end up visible to everyone (or to no one).
+
+## No team means an error, not "everything"
+
+A queued job, a console command, a webhook, a seeder — none of them run inside a
+request, so none of them have a team. **A tenant query there throws.**
+
+```ts
+await Post.all();
+// Error: No team in context, so a tenant-scoped query can't be built safely.
+//   Inside a request, add teamContext() to your middleware.
+//   In a job, command, or seeder, wrap the work: runForTeam(team, () => …).
+//   If it genuinely spans every team, say so: withoutTenant(() => …).
+```
+
+This is the security model, and the alternatives are worse:
+
+| If no team meant… | Then |
+| --- | --- |
+| *unscoped* | every background job sees every tenant's rows — this is how customer A's invoice reaches customer B |
+| `teamId = NULL` | jobs match nothing, "work" fine, and quietly do nothing for a month |
+| **an error** | a job that forgot **crashes in development** instead of leaking in production |
+
+So a job says which team it's for:
+
+```ts
+await runForTeam(team, () => sendInvoices());
+```
+
+...or says, out loud, that it isn't for one:
+
+```ts
+await withoutTenant(() => Post.withoutGlobalScope(TENANT_SCOPE).get());
+```
+
+Both are named calls you can **grep for at audit time**. That's the point: crossing a
+tenant boundary should be something you typed, never something you arrived at by
+forgetting a `where`.
+
+> Your jobs will crash until each one is wrapped. That friction is the feature — it
+> is a loud failure in development in exchange for not having a silent one in
+> production.
+
+The context lives in `AsyncLocalStorage`, not a module global, so two concurrent
+requests can't see each other's team.
+
+## Teams and membership
+
+```ts
+const team = await createTeam("Acme", user.id);   // creator becomes the owner
+
+await teamsFor(user.id);            // the teams a user is in
+await roleOf(user.id, team.id);     // "owner" | "admin" | "member" | null
+await memberOf(user.id, team.id, "admin");
+await switchTeam(user.id, team.id); // false if they aren't a member
+```
+
+A user is in a team **if and only if a membership row says so**. `teams.owner_id` is a
+convenience, not an authorization source.
+
+`switchTeam()` verifies membership, and so does `teamContext()` on every request —
+`users.current_team_id` is just a number on a row the user can influence, so it is
+checked, never trusted. Without that, switching teams would be a matter of writing
+someone else's id onto your own row.
+
+`Team` and `Membership` are deliberately **not** tenant-scoped: "which teams am I in?"
+is a question you have to answer *before* you know which team you're in.
+
+## Roles
+
+`owner` > `admin` > `member`, ordered — an owner can do anything an admin can.
+
+```ts
+router.delete("/posts/:post", …).middleware(requireRole("admin"));
+```
+
+```ts
+roleAtLeast("owner", "admin");   // true
+roleAtLeast("member", "admin");  // false
+```
+
+## Invitations
+
+```ts
+const { token } = await invite(team.id, "grace@example.com", "admin");
+await acceptInvitation(token, user.id, user.email);
+
+await pendingInvitations(team.id);
+await revokeInvitation(id);
+```
+
+Unlike a password-reset link, an invitation **is** a database row — it has to be
+listable ("3 pending") and revocable, and you can't revoke a stateless token. Only the
+token's **hash** is stored, so a database leak doesn't open every pending team.
+
+The invited address is re-checked on accept, so a **forwarded link doesn't let someone
+else join** in the invitee's place — which is the interesting attack on an invitation
+system. Invitations are single-use, expire (72h by default), and re-inviting the same
+address replaces the outstanding invitation rather than stacking duplicates.
+
+## Personal teams
+
+On by default: every new user gets a team of their own, and a solo user is simply a
+team of one.
+
+Worth leaving on even for an app that feels single-user. **Tenancy is not a feature
+you can add later** — bolting a `team_id` onto a schema that already has customer data
+means a backfill, a migration on every table, and rewriting every query. Ignoring a
+team you have costs one unused row. Needing a team you don't have costs a weekend.
+
+## Configuration
+
+```bash
+keel vendor:publish --tag teams-config
+```
+
+```ts
+export default {
+  userTable: "users",
+  personalTeams: true,
+  invitations: { expiresInHours: 72, url: "/invitations/:token" },
+};
+```
+
+## The schema
+
+| Table | |
+| --- | --- |
+| `teams` | name, slug, owner_id |
+| `team_memberships` | team_id, user_id, role — **unique per (team, user)**, enforced by the database |
+| `team_invitations` | team_id, email, role, token **hash**, expires_at |
+
+Plus `current_team_id` on your users table.
+
+
+
 ---
 
 <!-- source: docs/telemetry.md -->