@shaferllc/keel 0.80.0 → 0.81.1

package/docs/accounts.md

@@ -0,0 +1,214 @@
+# 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 |

package/docs/ai-manifest.json

@@ -1,10 +1,17 @@
 {
   "name": "@shaferllc/keel",
-  "version": "0.80.0",
+  "version": "0.81.1",
   "description": "The house framework for Node.js — a service container, providers, routing, JSX views, and a code-generating console.",
   "repo": "https://github.com/shaferllc/keel",
   "generated": "run `npm run build:ai` to regenerate",
   "docs": [
+    {
+      "slug": "accounts",
+      "title": "Accounts",
+      "summary": "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).",
+      "path": "docs/accounts.md",
+      "example": "docs/examples/accounts.ts"
+    },
     {
       "slug": "ai",
       "title": "Building Keel apps with AI",
@@ -355,6 +362,13 @@
       "path": "docs/storage.md",
       "example": "docs/examples/storage.ts"
     },
+    {
+      "slug": "teams",
+      "title": "Teams",
+      "summary": "Multi-tenancy, membership, roles, and invitations — where a row belongs to a team, and one team can never see another's.",
+      "path": "docs/teams.md",
+      "example": "docs/examples/teams.ts"
+    },
     {
       "slug": "telemetry",
       "title": "Telemetry",
@@ -475,6 +489,11 @@
       "kind": "value",
       "module": "helpers"
     },
+    {
+      "name": "AlterTableBuilder",
+      "kind": "value",
+      "module": "migrations"
+    },
     {
       "name": "AnyCommand",
       "kind": "type",
@@ -1380,6 +1399,11 @@
       "kind": "value",
       "module": "exceptions"
     },
+    {
+      "name": "ForeignKeyBuilder",
+      "kind": "value",
+      "module": "migrations"
+    },
     {
       "name": "formatMessage",
       "kind": "value",
@@ -1445,6 +1469,11 @@
       "kind": "value",
       "module": "social"
     },
+    {
+      "name": "GlobalScope",
+      "kind": "type",
+      "module": "model"
+    },
     {
       "name": "google",
       "kind": "value",
@@ -1890,11 +1919,46 @@
       "kind": "type",
       "module": "binding"
     },
+    {
+      "name": "ModelEvent",
+      "kind": "type",
+      "module": "model-events"
+    },
     {
       "name": "ModelFactory",
       "kind": "value",
       "module": "factory"
     },
+    {
+      "name": "ModelHook",
+      "kind": "type",
+      "module": "model-events"
+    },
+    {
+      "name": "ModelObserver",
+      "kind": "type",
+      "module": "model-events"
+    },
+    {
+      "name": "ModelQuery",
+      "kind": "value",
+      "module": "model-query"
+    },
+    {
+      "name": "MorphMany",
+      "kind": "value",
+      "module": "relations"
+    },
+    {
+      "name": "MorphOne",
+      "kind": "value",
+      "module": "relations"
+    },
+    {
+      "name": "MorphTo",
+      "kind": "value",
+      "module": "relations"
+    },
     {
       "name": "namedLogger",
       "kind": "value",
@@ -2265,6 +2329,11 @@
       "kind": "type",
       "module": "pages"
     },
+    {
+      "name": "registerMorphType",
+      "kind": "value",
+      "module": "relations"
+    },
     {
       "name": "Relation",
       "kind": "value",

package/docs/database.md

@@ -145,6 +145,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
@@ -174,6 +191,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.
@@ -576,6 +609,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`

package/docs/examples/accounts.ts

@@ -0,0 +1,150 @@
+// Typechecked example for docs/accounts.md.
+import { Application } from "@shaferllc/keel/core";
+import {
+  AccountsServiceProvider,
+  attempt,
+  completeTwoFactor,
+  confirmTwoFactor,
+  disableTwoFactor,
+  enableTwoFactor,
+  hasTwoFactor,
+  regenerateRecoveryCodes,
+  requestPasswordReset,
+  resetPassword,
+  sendVerificationEmail,
+  verifyEmail,
+  accountStore,
+  setAccountStore,
+  type AccountUser,
+} from "@shaferllc/keel/accounts";
+
+const app = new Application();
+
+/* ------------------------------- turning it on ---------------------------- */
+
+app.register(AccountsServiceProvider);
+
+/* ---------------------------------- login --------------------------------- */
+
+async function login(email: string, password: string) {
+  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 };
+  }
+
+  return { user: result.user };
+}
+
+async function finishTwoFactor(challenge: string, code: string) {
+  // Takes an authenticator code or a recovery code.
+  const user = await completeTwoFactor(challenge, code);
+  if (!user) return { error: "That code isn't valid." };
+
+  return { user };
+}
+
+/* ------------------------------ password reset ---------------------------- */
+
+async function forgot(email: string) {
+  await requestPasswordReset(email);
+  // Always the same answer, whether or not that address has an account.
+  return { status: "If that address has an account, a link is on its way." };
+}
+
+async function reset(token: string, password: string) {
+  const ok = await resetPassword(token, password);
+  return ok ? { status: "Password reset." } : { error: "That link is invalid or expired." };
+}
+
+/* --------------------------- email verification --------------------------- */
+
+async function afterRegistration(user: AccountUser) {
+  await sendVerificationEmail(user);
+}
+
+async function confirmEmail(token: string) {
+  const user = await verifyEmail(token);
+  return user ? { status: "Confirmed." } : { error: "That link is invalid or expired." };
+}
+
+/* -------------------------------- two factor ------------------------------ */
+
+async function startTwoFactor(user: AccountUser) {
+  // Step one: a secret and recovery codes — but 2FA is NOT on yet.
+  const setup = await enableTwoFactor(user, { issuer: "Acme" });
+
+  // Render setup.uri to a QR code locally. It contains the secret; never send it
+  // to a third-party QR service.
+  return {
+    uri: setup.uri,
+    secret: setup.secret,
+    recoveryCodes: setup.recoveryCodes, // shown once
+  };
+}
+
+async function finishSetup(user: AccountUser, code: string) {
+  // Step two: a working code turns it on. Without this, a bad scan locks them out.
+  const ok = await confirmTwoFactor(user, code);
+  return ok ? { status: "Two-factor is on." } : { error: "That code isn't valid." };
+}
+
+async function accountSettings(user: AccountUser) {
+  return {
+    twoFactorEnabled: hasTwoFactor(user),
+  };
+}
+
+async function newCodes(user: AccountUser) {
+  return regenerateRecoveryCodes(user); // invalidates the old set
+}
+
+async function turnOff(user: AccountUser) {
+  await disableTwoFactor(user);
+}
+
+/* ------------------------------ a custom store ---------------------------- */
+
+// Users somewhere other than a `users` table? Replace the whole store. (Anything
+// that can find a user and update one will do — here, a map.)
+const people = new Map<string | number, AccountUser>();
+
+setAccountStore({
+  async findById(id) {
+    return people.get(id) ?? null;
+  },
+  async findByEmail(email) {
+    for (const person of people.values()) {
+      if (person.email === email.toLowerCase()) return person;
+    }
+    return null;
+  },
+  async update(id, values) {
+    const person = people.get(id);
+    if (person) people.set(id, { ...person, ...values });
+  },
+});
+
+// The store the rest of the module reads through.
+const store = accountStore();
+
+export {
+  login,
+  finishTwoFactor,
+  forgot,
+  reset,
+  afterRegistration,
+  confirmEmail,
+  startTwoFactor,
+  finishSetup,
+  accountSettings,
+  newCodes,
+  turnOff,
+  app,
+  store,
+};

package/docs/examples/teams.ts

@@ -0,0 +1,101 @@
+// Typechecked example for docs/teams.md.
+import { Application, sessionMiddleware } from "@shaferllc/keel/core";
+import {
+  TeamsServiceProvider,
+  TenantModel,
+  TENANT_SCOPE,
+  acceptInvitation,
+  createTeam,
+  currentTeam,
+  invite,
+  memberOf,
+  pendingInvitations,
+  requireRole,
+  revokeInvitation,
+  roleAtLeast,
+  roleOf,
+  runForTeam,
+  switchTeam,
+  teamContext,
+  teamsFor,
+  withoutTenant,
+} from "@shaferllc/keel/teams";
+
+const app = new Application();
+app.register(TeamsServiceProvider);
+
+// Put every request inside a team; TenantModel queries are scoped from then on.
+const middleware = [sessionMiddleware(), teamContext()];
+
+/* -------------------------------- a tenant model -------------------------- */
+
+class Post extends TenantModel {
+  static override table = "posts";
+  static override fillable = ["title"];
+
+  declare id: number;
+  declare title: string;
+}
+
+async function inAHandler() {
+  const mine = await Post.all(); // only the current team's
+  const one = await Post.find(1); // null if it belongs to another team
+  const made = await Post.create({ title: "Hi" }); // stamped with the current team
+  return { mine, one, made, team: currentTeam() };
+}
+
+/* ------------------------------ outside a request ------------------------- */
+
+async function aJob(team: { id: number }) {
+  // Without this, the query throws — it does not quietly return every team's rows.
+  await runForTeam(team, async () => {
+    await Post.all();
+  });
+}
+
+async function anAdminReport() {
+  // Crossing tenants, said out loud so it can be found at audit time.
+  return withoutTenant(() => Post.withoutGlobalScope(TENANT_SCOPE).get());
+}
+
+/* --------------------------------- membership ----------------------------- */
+
+async function onboarding(userId: number) {
+  const team = await createTeam("Acme", userId);
+
+  await teamsFor(userId);
+  await roleOf(userId, team.id);
+  await memberOf(userId, team.id, "admin");
+  await switchTeam(userId, team.id); // false if they aren't a member
+
+  return team;
+}
+
+const adminsOnly = requireRole("admin");
+const ordered = roleAtLeast("owner", "admin"); // true
+
+/* -------------------------------- invitations ----------------------------- */
+
+async function inviteSomeone(teamId: number, userId: number) {
+  const { token, invitation } = await invite(teamId, "grace@example.com", "admin");
+
+  await pendingInvitations(teamId);
+  await revokeInvitation(invitation.id);
+
+  // The invited address is re-checked, so a forwarded link can't be redeemed by
+  // someone else.
+  return acceptInvitation(token, userId, "grace@example.com");
+}
+
+export {
+  app,
+  middleware,
+  Post,
+  inAHandler,
+  aJob,
+  anAdminReport,
+  onboarding,
+  adminsOnly,
+  ordered,
+  inviteSomeone,
+};