@shaferllc/keel 0.80.0 → 0.81.0

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.
@@ -12745,12 +12999,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
@@ -13328,6 +13611,85 @@ 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
+```
+
+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 +13739,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 +13782,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.
 
 ---

package/llms.txt

@@ -9,6 +9,7 @@ Userland imports everything from `@shaferllc/keel/core`.
 
 ## Docs
 
+- [Accounts](https://github.com/shaferllc/keel/blob/main/docs/accounts.md): 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).
 - [Building Keel apps with AI](https://github.com/shaferllc/keel/blob/main/docs/ai.md): Keel is built to be written with an AI agent.
 - [API Resources](https://github.com/shaferllc/keel/blob/main/docs/api-resources.md): apiResource(router, Model, options) generates a full CRUD REST API from a Keel model — explicit, server-side, and composed from pieces you already have.
 - [Architecture](https://github.com/shaferllc/keel/blob/main/docs/architecture.md): Keel is small on purpose. This page maps the pieces and traces a request from socket to response. Nothing here is magic — every layer is a short, readable file in src/core/, and this guide is mostly a reading order for it.
@@ -73,6 +74,7 @@ Userland imports everything from `@shaferllc/keel/core`.
 
 Every topic has a runnable, type-checked example:
 
+- [Accounts example](https://github.com/shaferllc/keel/blob/main/docs/examples/accounts.ts)
 - [API Resources example](https://github.com/shaferllc/keel/blob/main/docs/examples/api-resources.ts)
 - [Authentication example](https://github.com/shaferllc/keel/blob/main/docs/examples/authentication.ts)
 - [Authorization example](https://github.com/shaferllc/keel/blob/main/docs/examples/authorization.ts)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.80.0",
+  "version": "0.81.0",
   "type": "module",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "license": "MIT",
@@ -61,6 +61,10 @@
       "types": "./dist/api/index.d.ts",
       "import": "./dist/api/index.js"
     },
+    "./accounts": {
+      "types": "./dist/accounts/index.d.ts",
+      "import": "./dist/accounts/index.js"
+    },
     "./billing": {
       "types": "./dist/billing/index.d.ts",
       "import": "./dist/billing/index.js"
@@ -93,7 +97,7 @@
     "test:coverage": "node --import tsx --test --experimental-test-coverage --test-coverage-exclude='tests/**' tests/*.test.ts",
     "build:ai": "tsx scripts/build-ai.ts",
     "build:watch-ui": "vite build --config src/watch/ui/vite.config.ts",
-    "build:watch-copy": "mkdir -p dist/watch/ui && cp -R src/watch/ui/dist dist/watch/ui/dist && cp src/watch/watch.config.stub dist/watch/ && cp src/openapi/openapi.config.stub dist/openapi/ && cp src/api/api.config.stub dist/api/ && cp src/billing/billing.config.stub dist/billing/",
+    "build:watch-copy": "mkdir -p dist/watch/ui && cp -R src/watch/ui/dist dist/watch/ui/dist && cp src/watch/watch.config.stub dist/watch/ && cp src/openapi/openapi.config.stub dist/openapi/ && cp src/api/api.config.stub dist/api/ && cp src/billing/billing.config.stub dist/billing/ && cp src/accounts/accounts.config.stub dist/accounts/",
     "build": "npm run build:ai && npm run build:watch-ui && rm -rf dist && tsc -p tsconfig.build.json && npm run build:watch-copy",
     "prepare": "npm run build",
     "typecheck:tests": "tsc --noEmit -p tsconfig.tests.json",