@zerotal/arch 1.7.0

package/docs/pagination.md

@@ -0,0 +1,340 @@
+---
+title: Pagination
+description: Split large query results into pages with the metadata and URL helpers a UI needs.
+---
+
+# Pagination
+
+The [query builder](/docs/query-builder) and [ORM](/docs/orm/queries) share four
+paginators, each a terminal method on any query. Each returns a result object
+carrying the rows plus the metadata, cursors, and URL helpers a UI needs.
+
+| Method                                  | Strategy               | Runs `COUNT`? | Best for                                |
+| --------------------------------------- | ---------------------- | ------------- | --------------------------------------- |
+| `paginate(perPage, page)`               | Offset + total         | Yes           | Numbered page UIs (1, 2, 3, …)          |
+| `simplePaginate(perPage, page)`         | Offset, next/prev only | No            | "Previous / Next" without page numbers  |
+| `cursorPaginate({ cursor, limit })`     | Keyset on `id`         | No            | Infinite scroll, very large tables      |
+| `keysetPaginate({ column, direction })` | Keyset on any column   | No            | Cursor paging on a sort other than `id` |
+
+> **Note** — This is **data-layer** pagination. For Flow's reactive,
+> server-driven paginated components, see
+> [Flow › Pagination](/docs/flow/pagination).
+
+## Getting Started
+
+Pagination ships with `@zerotal/orm` as query-builder methods — nothing to
+install or register. Call them at the end of any query:
+
+```typescript
+const page = await Post.query().latest().paginate();
+```
+
+## paginate — full numbered pages
+
+```typescript
+// in a controller
+const page = await Post.query()
+  .where("status", "published")
+  .orderBy("created_at", "desc")
+  .paginate(15); // reads ?page= from the request
+
+page.data; // Post[] for this page
+page.total; // total matching rows
+page.lastPage; // total number of pages
+```
+
+It runs a `COUNT` (ignoring limit/offset) then fetches the page, so you get a
+complete picture — at the cost of the extra count query. `perPage` defaults to 15;
+omit `page` and it reads the request's current page (`?page=`, or the page a Flow
+component registered).
+
+```typescript
+async paginate<T>(perPage?: number, page?: number): Promise<PaginateResult<T>>
+```
+
+### Result shape
+
+The object you get back carries the rows under `data` plus everything a UI needs to
+draw a pager — the current page, the total, the last page, and the 1-based `from`/`to`
+indices for "showing 1–15 of 240" labels. The nested `meta` repeats the same numbers in
+the shape API clients usually expect, so you can return it straight from a JSON
+endpoint:
+
+```typescript
+// type: PaginateResult<T>
+interface PaginateResult<T> {
+  data: T[];
+  total: number;
+  page: number;
+  perPage: number;
+  lastPage: number;
+  from: number | null; // 1-based index of the first row (null if empty)
+  to: number | null; // 1-based index of the last row (null if empty)
+  meta: { from; to; currentPage; lastPage; perPage; total; path };
+  // URL + state helpers ↓
+}
+```
+
+### URL & state helpers
+
+```typescript
+// using a PaginateResult `page`
+page.hasMorePages; // boolean
+page.onFirstPage; // boolean
+page.onLastPage; // boolean
+
+page.nextPageUrl(); // '?page=2'  | null on the last page
+page.previousPageUrl(); // '?page=1'  | null on the first page
+page.url(3); // '?page=3'
+page.url(3, "/posts", { q: "bun" }); // '/posts?q=bun&page=3'
+
+// Render a numbered pager — extra query params are merged onto every link
+page.links("/posts", { q: "bun" });
+// → [{ page: 1, url: '/posts?q=bun&page=1', active: false }, …]
+```
+
+`nextPageUrl`, `previousPageUrl`, `url`, and `links` all accept an optional base URL
+and extra query params, which are preserved across links so filters survive
+
+## simplePaginate — next / prev only
+
+Skips the `COUNT` entirely by fetching `perPage + 1` rows to detect whether
+another page follows. Use it when you don't need a total or page numbers:
+
+```typescript
+// in a controller
+const page = await Post.query().latest().simplePaginate(20);
+
+page.data; // up to 20 rows
+page.hasMorePages; // true if a further page exists
+page.nextPageUrl();
+page.onFirstPage;
+```
+
+```typescript
+async simplePaginate<T>(perPage?: number, page?: number): Promise<SimplePaginateResult<T>>
+```
+
+> **Note** — Argument order is `simplePaginate(perPage, page)` — **`perPage`
+> first**, matching `paginate(perPage, page)`. `perPage` defaults to 15; omit
+> `page` to read the request's current page.
+
+There is no `total` or `lastPage` — that's the trade-off for dropping the count.
+
+## cursorPaginate — keyset pagination on id
+
+Cursor (keyset) pagination walks the table by `id` with `WHERE id > cursor ORDER
+BY id ASC`, fetching `limit + 1` rows to detect a next page. It has **no
+`COUNT`** and stays fast no matter how deep you scroll — ideal for
+infinite-scroll feeds and very large tables:
+
+```typescript
+// in a controller
+let result = await Post.query().cursorPaginate({ limit: 20 });
+
+result.data; // first 20 posts
+result.nextCursor; // pass to the next call; null on the last page
+result.prevCursor; // cursor that produced the previous page; null on the first
+result.hasMore; // boolean
+
+// Next page:
+const more = await Post.query().cursorPaginate({ cursor: result.nextCursor!, limit: 20 });
+```
+
+```typescript
+async cursorPaginate<T>(options?: { cursor?: number; limit?: number }): Promise<CursorPaginateResult<T>>
+```
+
+Defaults: `{ cursor: 0, limit: 15 }`. Because it orders by `id` ascending, the
+cursor is stable even as rows are inserted. The trade-off vs. `paginate()` is no
+random page access and no total count.
+
+## keysetPaginate — keyset pagination on any column
+
+`keysetPaginate()` generalises `cursorPaginate()`: it accepts **any sort
+column**, supports `'asc'` and `'desc'`, and returns an **opaque base64 cursor**
+that encodes the last row's sort value so clients cannot interpret or tamper with
+it. A secondary `id ASC` tiebreaker keeps page boundaries stable when the sort
+column isn't unique.
+
+```typescript
+// in a controller
+// First page, newest first
+const p1 = await Post.query().keysetPaginate({ column: "created_at", direction: "desc" });
+
+p1.data; // first page of rows
+p1.nextCursor; // opaque base64 string | null on the last page
+
+// Next page — pass the opaque cursor straight back
+const p2 = await Post.query().keysetPaginate({
+  column: "created_at",
+  direction: "desc",
+  cursor: p1.nextCursor!,
+});
+```
+
+```typescript
+async keysetPaginate<T>(options?: KeysetOptions): Promise<KeysetPaginateResult<T>>
+
+interface KeysetOptions {
+  cursor?: string | null; // opaque cursor from the previous page; null = first page
+  column?: string; // sort column, must be a safe identifier (default 'id')
+  direction?: "asc" | "desc"; // default 'asc'
+  limit?: number; // default 15
+}
+```
+
+> **Danger** — The `column` must be a safe SQL identifier; `keysetPaginate()`
+> rejects anything else (e.g. `name; DROP TABLE users--`) by throwing. Never
+> build the column name from raw, unvalidated user input.
+
+## Choosing a paginator
+
+- **Numbered admin tables / search results** → `paginate()` — you want page
+  numbers and a total.
+- **Lightweight "Load more" / Prev-Next** → `simplePaginate()` — skip the count,
+  keep it cheap.
+- **Infinite scroll keyed on `id`** → `cursorPaginate()` — constant-time paging,
+  no count, simplest cursor.
+- **Cursor paging on a sort other than `id`** (e.g. `created_at`, `score`) →
+  `keysetPaginate()` — any column, opaque tamper-proof cursors.
+
+All four work identically on a raw `DB.table(...)` query (returning plain rows)
+and on a `Model.query()` (returning hydrated models with eager-loaded
+relations).
+
+## Putting it together
+
+Two patterns cover most real use.
+
+### A filtered, numbered results page
+
+Paginate _after_ applying filters and sorting, then pass the current filters to
+`links()` so they ride along on every page URL — without that, clicking "page 2" would
+silently drop the user's search:
+
+```typescript
+// in a controller — GET /search?q=bun&page=2
+const q = http.query("q", "");
+
+const page = await Post.query()
+  .when(q, (query, term) => query.whereLike("title", `%${term}%`))
+  .latest()
+  .paginate(15, Number(http.query("page", "1")));
+
+return view("search", {
+  results: page.data,
+  total: page.total,
+  // every link keeps ?q=… so the filter survives paging
+  pager: page.links("/search", { q }),
+});
+```
+
+### An infinite-scroll API endpoint
+
+For a feed the client scrolls forever, return the rows plus the next cursor and nothing
+else — no count, no page numbers. The client sends the cursor back to fetch more:
+
+```typescript
+// in a controller — GET /api/posts?cursor=128
+const result = await Post.query()
+  .with("author")
+  .cursorPaginate({ cursor: Number(http.query("cursor", "0")), limit: 20 });
+
+return {
+  posts: result.data,
+  nextCursor: result.nextCursor, // null when there's nothing left to load
+};
+```
+
+When the sort isn't `id` — a "newest first" feed, say — reach for `keysetPaginate()`
+instead and hand the opaque `nextCursor` string back the same way.
+
+## Testing
+
+Set your suite up once as described in [Testing](/docs/testing). Pagination bugs
+live at the edges, so test the boundaries rather than the happy page.
+
+A `paginate()` result carries `data` plus the counts, so one call proves several
+things at once:
+
+```typescript
+// tests/pagination/Posts.test.ts
+import { test, expect } from "bun:test";
+import { PostFactory } from "../../database/factories/PostFactory.ts";
+import { Post } from "../../app/models/Post.ts";
+
+test("reports the right totals on the last page", async () => {
+  await PostFactory.count(25).create();
+
+  const page = await Post.query().orderBy("id").paginate(10, 3); // 10 per page, page 3
+
+  expect(page.data).toHaveLength(5); // the remainder
+  expect(page.total).toBe(25);
+  expect(page.lastPage).toBe(3);
+  expect(page.from).toBe(21);
+  expect(page.to).toBe(25);
+});
+```
+
+**The three cases worth pinning down** are the ones that produce a broken UI
+rather than an exception:
+
+```typescript
+// tests/pagination/Posts.test.ts
+test("an empty result reports null bounds, not zero", async () => {
+  const page = await Post.query().where("status", "nothing").paginate();
+
+  expect(page.data).toEqual([]);
+  expect(page.total).toBe(0);
+  expect(page.from).toBeNull(); // not 0 — a pager rendering "0–0 of 0" is a bug
+  expect(page.to).toBeNull();
+});
+
+test("a page past the end is empty rather than an error", async () => {
+  await PostFactory.count(5).create();
+
+  const page = await Post.query().orderBy("id").paginate(10, 99);
+
+  expect(page.data).toEqual([]);
+  expect(page.page).toBe(99);
+});
+```
+
+> **Warning** — Paginating without an `orderBy` gives the database licence to
+> return rows in any order, so the same row can appear on two pages and another
+> on none. A test that seeds five rows and reads one page will not catch it —
+> order explicitly, and the bug never exists.
+
+## References
+
+### Query methods
+
+| Method           | Signature                                                                        | Description                                                   |
+| ---------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------- |
+| `paginate`       | `paginate(perPage?, page?): Promise<PaginateResult<T>>`                          | Offset pagination with a `COUNT` total and `lastPage`.        |
+| `simplePaginate` | `simplePaginate(perPage?, page?): Promise<SimplePaginateResult<T>>`              | Offset next/prev pagination, no count.                        |
+| `cursorPaginate` | `cursorPaginate({ cursor?, limit?, column? }): Promise<CursorPaginateResult<T>>` | Keyset pagination on `column` (default `id`, numeric cursor). |
+| `keysetPaginate` | `keysetPaginate(options?): Promise<KeysetPaginateResult<T>>`                     | Keyset pagination on any column (opaque base64 cursor).       |
+
+### `PaginateResult<T>` helpers
+
+| Member            | Signature                                          | Description                                       |
+| ----------------- | -------------------------------------------------- | ------------------------------------------------- |
+| `hasMorePages`    | `boolean`                                          | True when a page follows the current one.         |
+| `onFirstPage`     | `boolean`                                          | True on the first page.                           |
+| `onLastPage`      | `(): boolean`                                      | True on the last page.                            |
+| `nextPageUrl`     | `(baseUrl?, query?): string \| null`               | URL of the next page, or `null` on the last.      |
+| `previousPageUrl` | `(baseUrl?, query?): string \| null`               | URL of the previous page, or `null` on the first. |
+| `elements`        | `(each?): (number \| "...")[]`                     | Page-number window with `"..."` gaps for a pager. |
+| `url`             | `(page, baseUrl?, query?): string`                 | URL for any page number.                          |
+| `links`           | `(baseUrl?, query?): Array<{ page; url; active }>` | One link per page for rendering a numbered pager. |
+
+> **Tip** — `SimplePaginateResult<T>` exposes the same URL helpers and
+> `hasMorePages`, but has no `links()`, `onLastPage`, `total`, or `lastPage`.
+
+## Next steps
+
+- [Query Builder](/docs/query-builder) — building the query you paginate.
+- [ORM Queries](/docs/orm/queries) — model queries, scopes, and eager loading.
+- [Flow › Pagination](/docs/flow/pagination) — reactive paginated components.

package/docs/password-reset.md

@@ -0,0 +1,335 @@
+---
+title: Password Reset
+description: Generate, email, and verify hashed reset tokens so users can securely set a new password.
+---
+
+# Password Reset
+
+`PasswordBroker` handles the full password reset flow: generating and storing a
+hashed token, emailing the reset link, verifying the token on submission, and
+calling your password-update logic. It is database-agnostic — you supply the query
+functions.
+
+The broker never stores or emails the raw token. It generates a random plain token,
+**SHA-256 hashes it** before handing it to `storeToken`, and emails the plain token
+to the user. On `reset()` it re-hashes the submitted token and compares — so a leaked
+database row can't be turned back into a working reset link.
+
+> **Danger** — Store only the hashed token, exactly as the broker hands it to `storeToken`. Persisting the plain token would let anyone with database access forge a working reset link.
+
+## Getting Started
+
+`PasswordBroker` ships in the auth package:
+
+```bash
+# in your project root
+bun add @zerotal/auth
+```
+
+There is no provider or `config/` file to register — you construct the broker
+yourself and supply the query functions, so it works with any storage backend.
+
+## Migration
+
+The broker reads and writes through your query functions, so it needs a table to
+back them. The default examples below use a `password_reset_tokens` table keyed by
+email:
+
+```typescript
+// database/migrations/xxxx_create_password_reset_tokens.ts
+await Schema.create("password_reset_tokens", (table) => {
+  table.string("email").primary();
+  table.string("token");
+  table.timestamp("expires_at").nullable();
+  table.timestamp("created_at").nullable();
+});
+```
+
+> **Note** — The broker decides validity from `createdAt + expireMinutes`, so the
+> table must carry `created_at` and `findToken` must return it.
+
+## Wire up the broker
+
+Create the broker once and export it so controllers can import it. Pass an object
+implementing `PasswordBrokerOptions` — each query function maps the broker onto your
+storage:
+
+```typescript
+// app/auth/passwords.ts
+import { PasswordBroker, Hash } from "@zerotal/auth";
+import { Notify } from "@zerotal/notifications";
+import { DB } from "@zerotal/orm";
+import { User } from "#app/models/User.ts";
+import { PasswordResetNotification } from "#app/notifications/PasswordResetNotification.ts";
+
+export const broker = new PasswordBroker({
+  expireMinutes: 60,
+
+  // The broker decides validity from `createdAt + expireMinutes`, so findToken
+  // MUST return createdAt and storeToken MUST persist created_at.
+  findToken: async (email) => {
+    const row = await DB.table("password_reset_tokens")
+      .where("email", email)
+      .first<{ token: string; created_at: string }>();
+    return row ? { token: row.token, createdAt: new Date(row.created_at) } : null;
+  },
+
+  storeToken: (email, hash, expiresAt) =>
+    DB.table("password_reset_tokens").upsert(
+      { email },
+      { token: hash, created_at: new Date(), expires_at: expiresAt },
+    ),
+
+  deleteToken: (email) => DB.table("password_reset_tokens").where("email", email).delete(),
+
+  pruneTokens: (cutoff) =>
+    DB.table("password_reset_tokens").where("expires_at", "<", cutoff).delete(),
+
+  // PasswordResetNotification implements toMail(); { email } is the on-demand recipient.
+  sendResetLink: (email, token) =>
+    Notify.queue({ email }, new PasswordResetNotification(token, email)),
+
+  resetPassword: async (email, newPassword) => {
+    const user = await User.where("email", email).firstOrFail();
+    await user.fill({ password: await Hash.make(newPassword) }).save();
+  },
+});
+```
+
+> **Warning** — `findToken` receives the email and `sendResetLink` receives the
+> **plain** token; `storeToken` receives the **hashed** token. Don't swap them — the
+> broker hashes the plain token before `storeToken` and re-hashes the submitted
+> token on `reset()` to compare.
+
+### The notification
+
+```typescript
+// app/notifications/PasswordResetNotification.ts
+import { Notification, MailMessage, type Notifiable } from "@zerotal/notifications";
+
+export class PasswordResetNotification extends Notification {
+  constructor(
+    private readonly token: string,
+    private readonly email: string,
+  ) {
+    super();
+  }
+
+  channels(): string[] {
+    return ["mail"];
+  }
+
+  toMail(_notifiable: Notifiable): MailMessage {
+    const url = `https://myapp.com/reset-password?token=${this.token}&email=${encodeURIComponent(this.email)}`;
+    return new MailMessage().subject("Reset your password").html(`
+      <p>Click the link below to reset your password. This link expires in 60 minutes.</p>
+      <p><a href="${url}">${url}</a></p>
+      <p>If you did not request a password reset, no action is needed.</p>
+    `);
+  }
+}
+```
+
+## Controller
+
+The controller wires the broker into request handlers: one pair for requesting a
+link, one pair for submitting the new password. Compare the broker result against the
+[`PASSWORDS` constants](#passwords-constants) rather than raw strings.
+
+```typescript
+// app/controllers/PasswordResetController.ts
+import { broker } from "#app/auth/passwords.ts";
+import { Auth, PASSWORDS } from "@zerotal/auth";
+import { User } from "#app/models/User.ts";
+import type { HttpContext } from "zerotal";
+
+export class PasswordResetController {
+  showForm(ctx: HttpContext) {
+    ctx.view(ForgotPasswordPage({ errors: ctx.flashed("errors") }));
+  }
+
+  async sendLink(ctx: HttpContext) {
+    const { email } = await ctx.body<{ email: string }>();
+    await broker.sendResetLink(email);
+    // Same response regardless of whether the email exists — don't reveal account presence
+    ctx.flash("success", "If that address is registered, a reset link is on its way.");
+    ctx.redirect("/login", 303);
+  }
+
+  showReset(ctx: HttpContext) {
+    ctx.view(
+      ResetPasswordPage({
+        token: ctx.query("token") ?? "",
+        email: ctx.query("email") ?? "",
+        errors: ctx.flashed("errors"),
+      }),
+    );
+  }
+
+  async reset(ctx: HttpContext) {
+    const { token, email, password } = await ctx.body<{
+      token: string;
+      email: string;
+      password: string;
+    }>();
+
+    const result = await broker.reset(token, email, password);
+
+    if (result === PASSWORDS.TOKEN) {
+      ctx.flash("errors", { token: ["This reset link is invalid or has expired."] });
+      ctx.redirect(`/reset-password?token=${token}&email=${encodeURIComponent(email)}`, 303);
+      return;
+    }
+
+    // Log the user in immediately after a successful reset
+    const user = await User.where("email", email).first();
+    if (user) {
+      ctx.session.regenerate();
+      await Auth.login(user);
+    }
+
+    ctx.flash("success", "Your password has been reset.");
+    ctx.redirect("/dashboard", 303);
+  }
+}
+```
+
+> **Danger** — Always respond identically whether or not the email exists, as
+> `sendLink` does above. Branching the response leaks which addresses have accounts.
+
+## Routes
+
+```typescript
+// routes/web.ts
+import { GuestMiddleware } from "@zerotal/auth";
+import { PasswordResetController } from "#app/controllers/PasswordResetController.ts";
+
+Router.get("/forgot-password", PasswordResetController, "showForm", [GuestMiddleware]);
+Router.post("/forgot-password", PasswordResetController, "sendLink", [GuestMiddleware]);
+Router.get("/reset-password", PasswordResetController, "showReset", [GuestMiddleware]);
+Router.post("/reset-password", PasswordResetController, "reset", [GuestMiddleware]);
+```
+
+`GuestMiddleware` keeps already-authenticated users out of the reset flow.
+
+> **Warning** — Add a [rate limiter](/docs/rate-limiting) to `POST /forgot-password` so the endpoint can't be used to spray reset emails or probe which addresses exist.
+
+## Pruning expired tokens
+
+Expired rows accumulate because `reset()` only deletes a token when it's used or
+found expired on lookup. Call `broker.prune()` on a schedule to clear the rest — it
+delegates to your `pruneTokens` function with the cutoff date:
+
+```typescript
+// app/schedules/PrunePasswordTokens.ts
+import { Schedule } from "@zerotal/scheduler";
+import { broker } from "#app/auth/passwords.ts";
+
+export class PrunePasswordTokens extends Schedule {
+  cron = "0 * * * *"; // hourly
+  async handle() {
+    await broker.prune();
+  }
+}
+```
+
+See [Scheduler](/docs/scheduler) for the worker setup.
+
+## PASSWORDS constants
+
+Always compare against the constants rather than the raw strings — the values are
+namespaced and may change.
+
+| Constant          | Value               | Returned by                                            |
+| ----------------- | ------------------- | ------------------------------------------------------ |
+| `PASSWORDS.SENT`  | `'passwords.sent'`  | `sendResetLink()` once the link is dispatched          |
+| `PASSWORDS.TOKEN` | `'passwords.token'` | `reset()` when the token is missing, wrong, or expired |
+| `PASSWORDS.RESET` | `'passwords.reset'` | `reset()` after the password is updated                |
+
+## Testing
+
+Set your suite up once as described in [Testing](/docs/testing) — everything
+below assumes `createApp()` from your `tests/helpers.ts`.
+
+The broker needs no application at all, because **your options own the
+delivery**. `sendResetLink(email, token)` is a callback you wrote, so a test
+captures the token instead of sending mail:
+
+```typescript
+// tests/auth/password-reset.test.ts
+import { test, expect } from "bun:test";
+import { PasswordBroker } from "@zerotal/auth";
+
+test("a reset token changes the password, once", async () => {
+  const store = new Map<string, { token: string; createdAt: Date }>();
+  let sent: string | undefined;
+  let password: string | undefined;
+
+  const broker = new PasswordBroker({
+    findToken: async (email) => store.get(email) ?? null,
+    storeToken: async (email, hash) =>
+      void store.set(email, { token: hash, createdAt: new Date() }),
+    deleteToken: async (email) => void store.delete(email),
+    pruneTokens: async () => {},
+    sendResetLink: async (_email, token) => void (sent = token),
+    resetPassword: async (_email, next) => void (password = next),
+  });
+
+  expect(await broker.sendResetLink("jane@example.com")).toBe("passwords.sent");
+
+  expect(await broker.reset(sent!, "jane@example.com", "new-secret")).toBe("passwords.reset");
+  expect(password).toBe("new-secret");
+
+  // Single-use: replaying the same token must fail.
+  expect(await broker.reset(sent!, "jane@example.com", "other")).toBe("passwords.token");
+});
+```
+
+**Every failure returns `"passwords.token"` rather than throwing**, so assert on
+the return value — a `expect(...).toThrow()` here will never fire. Three cases
+earn a test: a wrong token, an expired one, and the replay above.
+
+On the HTTP side, the case worth pinning down is that a miss is indistinguishable
+from a hit:
+
+```typescript
+// tests/http/password-reset.test.ts
+const res = await app.post("/forgot-password", { email: "nobody@example.com" });
+
+// Deliberately identical to the registered-address case — the response must not
+// reveal whether the account exists.
+res.assertRedirect("/forgot-password");
+```
+
+## References
+
+The constructor takes `PasswordBrokerOptions`; `expireMinutes` is the only optional
+field (default `60`), the rest are query functions you must supply.
+
+### Constructor options
+
+| Option                               | Signature                                                                | Description                                                 |
+| ------------------------------------ | ------------------------------------------------------------------------ | ----------------------------------------------------------- |
+| `expireMinutes`                      | `number` (optional, default `60`)                                        | Minutes until a reset token expires.                        |
+| `findToken(email)`                   | `(email: string) => Promise<{ token: string; createdAt: Date } \| null>` | Look up the stored hashed token and its creation time.      |
+| `storeToken(email, hash, expiresAt)` | `(email: string, hash: string, expiresAt: Date) => Promise<void>`        | Persist the **hashed** token and its expiry.                |
+| `deleteToken(email)`                 | `(email: string) => Promise<void>`                                       | Remove a single user's token after use or expiry.           |
+| `pruneTokens(cutoff)`                | `(cutoff: Date) => Promise<void>`                                        | Delete all tokens created before `cutoff`.                  |
+| `sendResetLink(email, token)`        | `(email: string, token: string) => Promise<void>`                        | Deliver the **plain** token to the user (usually via mail). |
+| `resetPassword(email, newPassword)`  | `(email: string, newPassword: string) => Promise<void>`                  | Apply the new password to the user record.                  |
+
+### Broker methods
+
+| Method                          | Signature                                                                                             | Description                                        |
+| ------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------- |
+| `sendResetLink(email)`          | `(email: string) => Promise<'passwords.sent'>`                                                        | Generate + store a hashed token and send the link. |
+| `reset(token, email, password)` | `(token: string, email: string, password: string) => Promise<'passwords.token' \| 'passwords.reset'>` | Verify the token and update the password.          |
+| `prune()`                       | `() => Promise<void>`                                                                                 | Delete tokens older than `expireMinutes`.          |
+
+## Next steps
+
+- [Encryption & Hashing](/docs/encryption) — the `Hash` facade used in `resetPassword`.
+- [Authentication](/docs/authentication) — logging the user in after a reset.
+- [Notifications](/docs/notifications) — building and queueing the `PasswordResetNotification`.
+- [Rate Limiting](/docs/rate-limiting) — throttle the forgot-password endpoint.
+- [Scheduler](/docs/scheduler) — run `prune()` on a recurring schedule.