@antelopejs/interface-dms 0.10.3 → 0.12.0

package/docs/1.core/8.realtime.md

@@ -1,33 +1,32 @@
 ---
 title: "Realtime"
 description: "Publish events on topics from the backend, and how page-bound topics reach the browsers viewing the page."
+mode: reference
 ---
 
-# Realtime
-
 ## Overview
 
-Realtime works on topics. A topic is a plain string a page declares interest in, and any backend code can publish a message on it. `RegisterPageTopic` binds a topic to a page id; `PublishMessage` sends an event on that topic to every client currently subscribed to it. `SubscribeMessage` is the read half: it lets backend code receive what is published, instead of only feeding the dashboard's own streams.
+Realtime works on topics. A topic is a plain string that a page declares interest in, and any backend code can publish a message on it. `RegisterPageTopic` binds a topic to a page id. `PublishMessage` sends an event on that topic to every client session subscribed to it. `SubscribeMessage` is the read half. It lets backend code receive what is published, in addition to the streams the dashboard opens for its pages.
 
 Everything on this page lives in `@antelopejs/interface-dms/realtime`.
 
-## How a Page Ends Up Subscribed
+## How a page ends up subscribed
 
-Subscription is derived, not requested by the publisher:
+The page-topic registry derives the subscriptions. The publisher never requests them.
 
-1. A page — or a component on it — calls `RegisterPageTopic(pageId, topic)` at registration time. `pageId` is the page's `fullId` ([Pages and Modules](/docs/interfaces/core/pages-and-modules)), not its slug.
-2. A client opens a realtime session and reports which page it is on. The backend checks that the user may access that page, then subscribes the session to every topic registered for that page id, and drops the topics that are no longer wanted.
-3. `PublishMessage(topic, type)` delivers to the sessions currently subscribed to `topic` — with a `tenantId`, only to those of that tenant (see [Tenant-scoped messages](#tenant-scoped-messages)).
+1. A page, or a component on it, calls `RegisterPageTopic(pageId, topic)` at registration time. `pageId` is the page's `fullId` ([Pages and modules](/docs/interfaces/core/pages-and-modules)), not its slug.
+2. A client opens a realtime session and reports which page it is on. The backend checks that the user may access that page. It then subscribes the session to every topic registered for that page id, and drops the topics the session no longer needs.
+3. `PublishMessage(topic, type)` delivers to the sessions subscribed to `topic`. With a `tenantId`, it delivers only to the sessions of that tenant (see [Tenant-scoped messages](#tenant-scoped-messages)).
 
-So a publisher never addresses a page or a user. It addresses a topic, and the page-topic registry decides who is listening.
+A publisher never addresses a page or a user. It addresses a topic, and the page-topic registry decides who is listening.
 
-Registering the same topic for the same page twice is harmless — a page's topics are a set.
+A page's topics are a set, so registering the same topic for the same page twice has no further effect.
 
-A binding belongs to the module that registered it: it is removed when that module is unloaded, and it survives a reload of the DMS module, which gets every binding back from the core. Registering from `onCreated`, as below, makes the module whose page it is that owner.
+A binding belongs to the module that registered it. The DMS removes the binding when that module is unloaded. The binding survives a reload of the DMS module, which gets every binding back from the core. A registration from `onCreated`, as in the next example, makes the module whose page it is the owner.
 
-## Register a Topic for a Page
+## Register a topic for a page
 
-The typical caller is a component builder's `onCreated` callback, which receives the `PageMetadata` of the page the component was declared on ([Components](/docs/interfaces/core/components)):
+The usual caller is the `onCreated` callback of a component builder. The callback receives the page the component was declared on, typed `CreatedPage`: its `target`, and its `pageInfo.fullId` and `pageInfo.fullSlug`. At run time it is the page's `PageMetadata` ([Components](/docs/interfaces/core/components)).
 
 ```typescript
 import { ComponentBuilder } from "@antelopejs/interface-dms/component";
@@ -46,17 +45,17 @@ export function StockCounter(options: { fetchUrl: string }) {
 }
 ```
 
-Registering from `onCreated` is what makes the binding follow the component: whichever page the component is placed on gets the topic. The chart builders of the [Base](/docs/interfaces/base/introduction) domain do exactly this — a chart declaring `realtimeTopic` registers each of its topics on the page it is placed on.
+A registration from `onCreated` makes the binding follow the component, because every page the component is placed on gets the topic. The blocks of the [Base](/docs/interfaces/base/introduction) domain that take a `realtimeTopic` option, such as the chart and KPI cards, work the same way. Each one registers its topics on the page it is placed on.
 
-To bind a topic to a page you know statically, call `RegisterPageTopic` with that page's `fullId` directly.
+To bind a topic to a page you know when you write the code, call `RegisterPageTopic` with that page's `fullId`.
 
-```typescript
+```typescript fragment
 RegisterPageTopic(pageId: string, topic: string): void
 ```
 
-## Publish a Message
+## Publish a message
 
-```typescript
+```typescript fragment
 import { Controller, Post } from "@antelopejs/interface-api";
 import { PublishMessage } from "@antelopejs/interface-dms/realtime";
 import { STOCK_TOPIC } from "../components/stock-counter";
@@ -74,7 +73,7 @@ export class StockController extends Controller("/api/stock") {
 }
 ```
 
-```typescript
+```typescript fragment
 PublishMessage(
   topic: string,
   type: string,
@@ -84,25 +83,25 @@ PublishMessage(
 
 | Parameter | Description |
 | --------- | ----------- |
-| `topic` | The topic to publish on. Subscribers are the sessions on a page that registered this topic. |
-| `type` | The event type carried with the message, for subscribers that distinguish several kinds of event on one topic. |
-| `options` | Optional payload, actor and tenant. |
+| `topic` | The topic to publish on. The browser sessions that receive it are those on a page that registered this topic. Backend `SubscribeMessage` handlers on the topic receive it regardless. |
+| `type` | The event type carried with the message, for subscribers that tell apart several kinds of event on one topic. |
+| `options` | The optional payload, actor and tenant. |
 
 ### `PublishMessageOptions`
 
 | Option | Type | Description |
 | ------ | ---- | ----------- |
 | `payload` | `Record<string, unknown>` | Data carried with the event. |
-| `actorId` | `string` | Identifies who caused the event, so a client can ignore an event it triggered itself. |
-| `tenantId` | `string` | The tenant the event is about: only the sessions of that tenant receive it. Omitted, the message is global and reaches every tenant. |
+| `actorId` | `string` | Who caused the event, so a client can ignore an event it triggered itself. |
+| `tenantId` | `string` | The tenant the event is about. Only the sessions of that tenant receive it. Without it, the message is global and reaches every tenant. |
 
-`PublishMessage` resolves once the message has been handed to the broker. It does not report how many sessions received it, and publishing on a topic no page registered is not an error — it simply reaches nobody.
+`PublishMessage` resolves once the broker has the message. It does not report how many sessions received it. A message on a topic that no page registered is not an error. It reaches no browser session, and backend `SubscribeMessage` handlers on the topic still receive it.
 
 ### Tenant-scoped messages
 
-Page topics are shared by every tenant: a page registers the same topic whichever workspace views it. A message published without a `tenantId` therefore reaches the sessions of **every** workspace on that page — each one refetches, and a paused live page counts the message in its "N new" banner. Publish a workspace's data with the tenant it belongs to:
+Every tenant shares the page topics, because a page registers the same topic whichever workspace views it. A message published without a `tenantId` reaches the sessions of **every** workspace on that page. Each of those pages refetches, and a paused live page counts the message in its "N new" banner. Publish the data of a workspace with the tenant it belongs to:
 
-```typescript
+```typescript fragment
 import { getRequestTenantId } from "@antelopejs/interface-dms/request-tenant";
 
 await PublishMessage(CAMPAIGN_TOPIC, "campaign.sent", {
@@ -111,17 +110,17 @@ await PublishMessage(CAMPAIGN_TOPIC, "campaign.sent", {
 });
 ```
 
-A session is bound to the tenant of the request that opened it, and receives the messages of that tenant plus the global ones. When the browser switches workspace (or account), the client opens a new session in the new one, and the server ends a session whose page requests come from a workspace or account other than its own, so the previous workspace's messages stop with it. A session on the connection a browser's tabs share is ended alone: the other tabs' sessions on it stay. Keep messages without a tenant for what is the same for every workspace: a platform-wide setting, a catalogue shared by all tenants.
+A session belongs to the tenant of the request that opened it. It receives the messages of that tenant and the global ones. When the browser switches workspace or account, the client opens a new session in the new one. The server ends a session whose page requests come from another workspace or account, so the messages of the previous workspace stop with it. The tabs of a browser share one connection, and the server ends the session of one tab alone. The sessions of the other tabs stay open. Keep messages without a tenant for data that is the same for every workspace, such as a platform-wide setting or a catalog that every tenant shares.
 
-A session on a platform page (a page of a module, which only the platform owner opens) receives the messages of **every** tenant on that page's topics, whichever workspace the owner has open: such a page lists the data of all of them.
+A platform page is a page of a module, which only the platform owner opens. A session on a platform page receives the messages of **every** tenant on that page's topics, whichever workspace the owner has open, because such a page lists the data of all of them.
 
-The table views of the [Base](/docs/interfaces/base/tables#realtime) domain publish their row changes and presence for the writer's tenant, or for every tenant when their rows live in the shared schema. Messages to one user (notifications) and the menu invalidations already name their audience in the topic.
+The table views of the [Base](/docs/interfaces/base/table-events-and-helpers#realtime) domain publish their row changes and presence for the tenant of the writer. When their rows live in the shared core schema, they publish for every tenant. Messages to one user (notifications) and the menu invalidations already name their audience in the topic.
 
-## Subscribe from the Backend
+## Subscribe from the backend
 
-`SubscribeMessage` receives every message published on a topic, whichever instance and whichever tenant published it (a handler serving one tenant filters on `message.tenantId` itself): the subscription rides the same broker as `PublishMessage`, so what one instance publishes reaches subscribers on every other.
+`SubscribeMessage` receives every message published on a topic, whichever instance and whichever tenant published it. A handler that serves one tenant filters on `message.tenantId` itself. The subscription uses the same broker as `PublishMessage`, so what one instance publishes reaches the subscribers on every other instance.
 
-```typescript
+```typescript fragment
 import { SubscribeMessage } from "@antelopejs/interface-dms/realtime";
 import { STOCK_TOPIC } from "../components/stock-counter";
 
@@ -134,7 +133,7 @@ const unsubscribe = SubscribeMessage(STOCK_TOPIC, (message) => {
 });
 ```
 
-```typescript
+```typescript fragment
 function SubscribeMessage(
   topic: string,
   handler: RealtimeMessageHandler,
@@ -148,21 +147,21 @@ type UnsubscribeMessage = () => void;
 
 | Field | Type | Description |
 | ----- | ---- | ----------- |
-| `topic` | `string` | Topic the message was published on. |
-| `type` | `string` | Event type given to `PublishMessage`. |
+| `topic` | `string` | The topic the message was published on. |
+| `type` | `string` | The event type given to `PublishMessage`. |
 | `payload` | `Record<string, unknown>` | Data carried with the event, when the publisher sent any. |
 | `actorId` | `string` | Who caused the event, when the publisher named an actor. |
-| `tenantId` | `string` | The tenant the message was published for; absent on a global message. |
-| `ts` | `number` | Publication timestamp. |
+| `tenantId` | `string` | The tenant the message was published for. Absent on a global message. |
+| `ts` | `number` | The publication timestamp, in milliseconds since the epoch. |
 
-Paired with `PublishMessage`, this turns the DMS's broker into one a module can use for realtime channels of its own — its own endpoint subscribes here and the DMS carries the messages — instead of bringing a second broker to do the same job.
+With `PublishMessage` and `SubscribeMessage` together, a module can run realtime channels of its own on the DMS broker. Its own endpoint subscribes here and the DMS carries the messages, so the module needs no second broker.
 
-Three properties to design around:
+Design a subscriber around three properties:
 
-- **Handlers must not throw.** They are called on the delivering instance's event loop, and nothing catches for you.
-- **Delivery is fire-and-forget.** There is no replay: a message published while nobody was subscribed is gone. Do not use a topic as a queue.
-- **Unsubscribing is automatic** when the registering module is unloaded. The returned `UnsubscribeMessage` is for ending a subscription earlier than that; calling it twice is a no-op.
+- **Handlers must not throw.** The DMS calls them on the event loop of the delivering instance. The broker catches a thrown error or a rejected promise and logs it, and the error never reaches the publisher.
+- **Delivery is fire-and-forget.** The broker keeps no message for later. A message published while nobody was subscribed is gone, so do not use a topic as a queue.
+- **Unsubscribing is automatic** when the registering module is unloaded. Call the returned `UnsubscribeMessage` to end a subscription earlier. A second call has no effect.
 
-## Next Steps
+## Next steps
 
-[Quick Actions](/docs/interfaces/core/quick-actions) covers the other way a module reaches the running dashboard: entries in the command palette.
+[Quick actions](/docs/interfaces/core/quick-actions) covers another way a module reaches the running dashboard: entries in the command palette.

package/docs/1.core/9.quick-actions.md

@@ -1,23 +1,20 @@
 ---
-title: "Quick Actions"
-description: "A quick action is a shortcut the backend contributes to the dashboard's command palette: a labelled entry, grouped under a category, that points at a registered page, a table creation form, a table toolbar button, or…"
+title: "Quick actions"
+description: "A quick action is a shortcut a backend module adds to the dashboard's command palette and header menu. Categories, actions, targets, and how access is computed."
+mode: reference
 ---
 
-# Quick Actions
-
-## Overview
-
-A quick action is a shortcut the backend contributes to the dashboard's command palette: a labelled entry, grouped under a category, that points at a registered page, a table creation form, a table toolbar button, or an event. Actions register at import time. Access follows the target page and, for a form or a button, the permission of what it opens.
+A quick action is a shortcut a backend module adds to the dashboard. The command palette and the quick actions menu in the dashboard header both list it. Each action has a label, belongs to a category, and points at a registered page. Running it opens that page, opens a table's creation form, presses a table toolbar button, or emits an event. Actions register when their file is imported. Access follows the target page, and for a form or a button, the permission of what it opens.
 
 Both functions live in `@antelopejs/interface-dms/quick-actions`.
 
-## Declare a Category and Its Actions
+## Declare a category and its actions
 
-`QuickActionCategory(id, info)` registers the group; `QuickAction(id, info)` registers an entry in it. Both return the registered record. Create the category first: registering an action whose category is unknown throws.
+`QuickActionCategory(id, info)` registers a category, and `QuickAction(id, info)` registers an action in it. Both return the registered record. Register the category first, because registering an action whose category is unknown throws `QuickAction category "<id>" is not registered. Register the category before its actions.`
 
 This example assumes your application exports a registered `TasksPage` from `./pages/tasks`.
 
-```typescript
+```typescript fragment
 import { TasksPage } from "./pages/tasks";
 import {
   QuickAction,
@@ -38,44 +35,55 @@ QuickAction("tasks-new", {
 });
 ```
 
-Actions are keyed by their category id and their own id, so the same action id may appear under two categories. Registering an id that is already taken keeps the first registration.
+An action's key is its category id and its own id, so the same action id may appear under two categories. Registering a category id or an action key that is already taken keeps the first registration.
+
+Declare quick actions in a file your module imports, next to the pages they point at, so the registrations run at import time.
 
 ## `QuickActionCategoryInfo`
 
 | Field | Type | Description |
 | ----- | ---- | ----------- |
-| `id` | `string` | Category id. Supplied as the first argument of `QuickActionCategory`, not inside `info`. |
-| `displayName` | `string` | Group label. Required. |
+| `id` | `string` | Category id. Passed as the first argument of `QuickActionCategory`, not inside `info`. |
+| `displayName` | `string` | Category label. Required. |
 | `icon` | `string` | Icon name. |
-| `order` | `number` | Sort order among categories. |
+| `order` | `number` | Sort order among categories, ascending. A missing `order` counts as `0`. |
 
 ## `QuickActionInfo`
 
 | Field | Type | Description |
 | ----- | ---- | ----------- |
-| `id` | `string` | Action id. Supplied as the first argument of `QuickAction`, not inside `info`. |
-| `category` | `QuickActionCategoryInfo` | The record returned by `QuickActionCategory`. Required. |
-| `displayName` | `string` | Entry label. Required. |
+| `id` | `string` | Action id. Passed as the first argument of `QuickAction`, not inside `info`. |
+| `category` | `QuickActionCategoryInfo` | The record `QuickActionCategory` returned. Required. |
+| `displayName` | `string` | Action label. Required. |
 | `icon` | `string` | Icon name. Required. |
-| `order` | `number` | Sort order within the category. |
+| `order` | `number` | Sort order within the category, ascending. A missing `order` counts as `0`. |
 | `target` | `QuickActionTarget` | What running the action does. Required. |
 
-Access is computed per caller from the registered target page, including its permission and tenant access gate ([Permissions](/docs/interfaces/core/permissions)). An `openForm` target also checks the selected table's create action; a `button` target checks the button's own `permission`. Configure access on the destination rather than adding a separate `permission` property to the quick action.
+## Access
+
+The DMS computes access per caller from the target page, including its permission and its tenant access gate ([Permissions](/docs/interfaces/core/permissions)). An `openForm` target also checks the permission of the selected table's `add` action. A `button` target also checks the button's own `permission`, and a button with no permission adds no check. A quick action has no `permission` property of its own. Configure access on the page, the table or the button it points at.
+
+The DMS leaves out an action the caller cannot run, and a category whose actions were all left out. It also leaves out, with a server warning, an action whose target cannot be resolved:
+
+- The target `page` is not a registered page.
+- An explicit `component` is not mounted on the page.
+- `component` is omitted and the page has no matching component or several of them.
+- The `button` is not declared by the selected component.
 
 ## `QuickActionTarget`
 
-Every target requires `page`, the registered page controller class. The frontend URL derives from that page, so renaming a route does not leave a stale URL in the action.
+Every target requires `page`, the registered page controller class. The DMS derives the frontend route from that page, so a renamed route does not leave a stale URL in the action.
 
-| Variant | Fields | Meaning |
+| Variant | Fields | Effect |
 | ------- | ------ | ------- |
-| `"navigate"` | `page`, optional `query` | Navigate to the page with optional string query parameters. |
-| `"openForm"` | `page`, optional `component` | Open a table's creation form. Select the component explicitly if the page has more than one eligible table. |
-| `"button"` | `page`, `button`, optional `component` | Open the page and press the table toolbar button whose `id` is `button`, e.g. to open the modal it opens. Select the component explicitly if several components of the page declare that button id. |
-| `"event"` | `page`, `name`, optional `payload` | Navigate to the page and emit the named event. |
+| `"navigate"` | `page`, optional `query` | Navigates to the page, with optional string query parameters. |
+| `"openForm"` | `page`, optional `component` | Navigates to the page and opens a table's creation form. Pass `component` when the page mounts more than one component that can create a row. |
+| `"button"` | `page`, `button`, optional `component` | Navigates to the page and presses the table toolbar button whose `id` is `button`, for example to open the modal it opens. Pass `component` when several components of the page declare that button id. |
+| `"event"` | `page`, `name`, optional `payload` | Dispatches a window `CustomEvent` named `name` on the current page, with `payload` as its `detail`. It does not navigate. `page` only sets who can see the action. |
 
-The following examples assume an existing registered `BooksPage` with a `TableView` stored in its static `table` field. For a nested table, pass a target such as `BooksPage.content.targetChild("table")` instead.
+The following examples assume a registered `BooksPage` with a `TableView` in its static `table` field. For a nested table, pass a target such as `BooksPage.content.targetChild("table")` instead.
 
-```typescript
+```typescript fragment
 import { BooksPage } from "./pages/books";
 import {
   QuickAction,
@@ -94,7 +102,6 @@ QuickAction("catalog-new-book", {
   target: { type: "openForm", page: BooksPage, component: BooksPage.table },
 });
 
-// BooksPage.table declares customButtons: [{ id: "import", permission: "add", … }]
 QuickAction("catalog-import", {
   category: catalog,
   displayName: "$my_app.quick_actions.import_books",
@@ -110,6 +117,6 @@ QuickAction("catalog-refresh", {
 });
 ```
 
-Declare quick actions in a file imported by your module so the registrations run at import time, next to the pages they point at.
+The `catalog-import` action assumes that `BooksPage.table` declares a custom button with `id: "import"` in its `customButtons`.
 
-[Layout Banners](/docs/interfaces/core/layout-banners) covers the other global surface a backend module contributes to: messages under the dashboard header.
+[Layout banners](/docs/interfaces/core/layout-banners) covers messages under the dashboard header, the other global place a backend module adds to.

package/docs/2.auth/1.introduction.md

@@ -1,50 +1,48 @@
 ---
 title: "Introduction"
 description: "The auth domain answers who is calling: authentication decorators, tokens and sessions, users and external identities."
+mode: explanation
 ---
 
-# Introduction
-
 ## Overview
 
-The `auth` domain of `@antelopejs/interface-dms` answers one question for the DMS: who is calling. It resolves the bearer token on an HTTP request into a `User` row, issues and validates the tokens that make such a request possible, records logins as sessions, binds the accounts a user owns on external login providers, and owns the `users`, `sessions` and `user_external_identities` tables together with their models.
+The `auth` domain of `@antelopejs/interface-dms` answers one question for the DMS: who is calling. It resolves the bearer token of an HTTP request into a `User` row. It issues and validates the tokens that make such a request possible, records logins as sessions, and binds the accounts a user owns on external login providers. It also owns the `users`, `sessions` and `user_external_identities` tables and their models.
 
-It stops at identity. Deciding what an authenticated caller is allowed to do — permissions, roles, tenant membership — belongs to the [Core](/docs/interfaces/core/introduction) domain, whose tenant guards build on the `authenticateRequestUser` function documented here.
+The domain stops at identity. The [Core](/docs/interfaces/core/introduction) domain decides what an authenticated caller may do, through permissions, roles and tenant membership. Its tenant guards build on the `authenticateRequestUser` function this domain exports.
 
 The domain is published under three subpaths:
 
 | Subpath | Contents |
 | ------- | -------- |
-| `@antelopejs/interface-dms/auth` | The authentication decorators, `authenticateRequestUser`, the token generators and validators, `createSession`, `sanitizeUser`, the external-identity functions, `announceRegistration`, and the account mail entry points. |
-| `@antelopejs/interface-dms/auth/db` | The `User`, `Session` and `UserExternalIdentity` tables, their models, and the table-name constants. |
-| `@antelopejs/interface-dms/auth/password` | The password policy: `PASSWORD_MIN_LENGTH`, `PASSWORD_PATTERN` and `isPasswordCompliant`. Pure values, usable without the DMS loaded. |
-
-## Key Features
-
-- **Request Authentication Decorators** — Gate a route, a controller property, or a whole controller class on a valid bearer token with `AuthUser` and `AuthRawUser`, and receive the resolved `User`.
-- **Optional Authentication** — Serve the same route to signed-in and anonymous callers with `IfAuthUser`, which injects `User | undefined` instead of rejecting the request.
-- **Owner-Only Gate** — Restrict administration surfaces to platform owners with `AuthOwnerOnly`, which answers `403` to an authenticated non-owner.
-- **Composable Authentication** — Build your own parameter providers on `authenticateRequestUser`, the same primitive the DMS tenant guards start from.
-- **Token Lifecycle** — Issue and validate tenant-scoped access and refresh tokens, plus the short-lived two-factor and tenant-assignment tokens that stand between a password check and a real session.
-- **Revocable Sessions** — Record each login as a `Session` row carrying its device, IP and current refresh token, so a single session or every session of a user can be revoked.
-- **User Table and Model** — A `User` table with hashed passwords through `HashModifier`, and a `UserModel` with lookups by email and by owner flag.
-- **External Login Providers** — Bind the accounts a user owns on GitHub, Google or any configured provider with `linkExternalIdentity`, and resolve a provider profile back to a user on the next login.
-- **Safe Responses** — Strip authentication secrets from a user with `sanitizeUser` before returning it over HTTP.
-- **One Password Policy** — Check a password against the policy the DMS enforces with `isPasswordCompliant`, so a module's own signup accepts exactly what the DMS accepts.
-- **Account Emails** — Send the second-factor, email-validation, password-reset and invite messages the authentication flows depend on.
-- **One Registration Path** — Run the notifications and the `USER_REGISTERED` hook through `announceRegistration`, whichever flow created the account.
+| `@antelopejs/interface-dms/auth` | The authentication decorators, `authenticateRequestUser`, the token generators and validators, `createSession`, `sanitizeUser`, the external-identity functions, `announceRegistration`, the account mail functions, and the `RequestPrincipal` and `RequestAuthenticator` types. |
+| `@antelopejs/interface-dms/auth/db` | The `User`, `Session` and `UserExternalIdentity` tables, their models, the table-name constants, `normalizeEmail`, `isCurrentRefreshToken` and `buildExternalIdentityId`. |
+| `@antelopejs/interface-dms/auth/password` | The password policy: `PASSWORD_MIN_LENGTH`, `PASSWORD_PATTERN` and `isPasswordCompliant`. These are plain values and a pure function, usable without the DMS loaded. |
+
+## What the domain provides
+
+- **Request authentication decorators.** `AuthUser` and `AuthRawUser` gate a route, a controller property, or a whole controller class on a valid bearer token, and inject the resolved `User`.
+- **Optional authentication.** `IfAuthUser` serves the same route to signed-in and anonymous callers. It injects `User | undefined` instead of rejecting the request.
+- **An owner-only gate.** `AuthOwnerOnly` restricts administration routes to platform owners. It answers `403` to an authenticated caller who is not an owner.
+- **Composable authentication.** `authenticateRequestUser` runs the same checks outside a decorator. The DMS tenant guards start from it, and your own parameter providers can too.
+- **Token lifecycle.** The domain issues and validates access and refresh tokens scoped to a tenant. It also issues the short-lived two-factor and tenant-assignment tokens that sit between a password check and a real session.
+- **Revocable sessions.** Each login is a `Session` row with its device, IP, and the hash of its current refresh token. You can revoke one session, or every session of a user.
+- **The user table and model.** The `User` table hashes passwords through `HashModifier`. `UserModel` looks users up by email and by owner flag.
+- **External login providers.** `linkExternalIdentity` binds the accounts a user owns on GitHub, Google, or any configured provider. On the next login, the DMS resolves the provider profile back to the user.
+- **Safe responses.** `sanitizeUser` strips authentication secrets from a user before you return it over HTTP.
+- **One password policy.** `isPasswordCompliant` checks a password against the policy the DMS enforces, so the signup of a module accepts exactly what the DMS accepts.
+- **Account emails.** The domain sends the second-factor, email-validation, password-reset and invite messages that the authentication flows depend on.
+- **One registration path.** `announceRegistration` runs the notifications and the `USER_REGISTERED` hook, whichever flow created the account.
 
 ## Dependencies
 
-This interface relies on the following AntelopeJS packages:
+This domain relies on the following AntelopeJS packages:
 
-- [@antelopejs/interface-auth](https://github.com/AntelopeJS/interface-auth) - `CreateAuthDecorator`, which builds the authentication decorators from a source, an authenticator and a validator.
-- [@antelopejs/interface-api](https://github.com/AntelopeJS/interface-api) - Controllers, `RequestContext` and `HTTPResult`, used to read the request and to reject it.
-- [@antelopejs/interface-database-decorators](https://github.com/AntelopeJS/interface-database-decorators) - Table definitions, the `HashModifier` mixin, and `BasicDataModel` for the user and session models.
-- [@antelopejs/interface-database](https://github.com/AntelopeJS/interface-database) - Query value proxies used by the owner lookups on `UserModel`.
-- [@antelopejs/interface-core](https://github.com/AntelopeJS/interface-core) - `InterfaceFunction`, which wires the token, sanitization and mail entry points to their implementation.
+- [`@antelopejs/interface-api`](https://github.com/AntelopeJS/interface-api): Controllers, `RequestContext`, `SetParameterProvider` and `HTTPResult`, used to read the request and to reject it.
+- [`@antelopejs/interface-core`](https://github.com/AntelopeJS/interface-core): `InterfaceFunction`, which wires the token, sanitization and mail functions to their implementation, and the decorator factories the authentication decorators are built with.
+- [`@antelopejs/interface-database-decorators`](https://github.com/AntelopeJS/interface-database-decorators): Table definitions, the `HashModifier` mixin, and `BasicDataModel` for the user, session and identity models.
+- [`@antelopejs/interface-database`](https://github.com/AntelopeJS/interface-database): The query value proxies behind the owner lookups of `UserModel`.
 
-## Quick Start
+## Quick start
 
 The following controller gates a route on an authenticated user and returns the account with its secrets stripped.
 
@@ -65,11 +63,11 @@ export class ProfileController extends Controller("/api/profile") {
 }
 ```
 
-A client reaches it by sending the access token issued at login in the `Authorization` header, as `Bearer <access token>`.
+A client calls it with the access token issued at login, in the `Authorization` header, as `Bearer <access token>`.
 
-## Documentation Sections
+## Pages in this section
 
-- [Authentication](/docs/interfaces/auth/authentication) - Resolve a request to a user with the authentication decorators and `authenticateRequestUser`
-- [Tokens and Sessions](/docs/interfaces/auth/tokens-and-sessions) - Issue and validate access, refresh, two-factor and tenant-assignment tokens, and record login sessions
-- [Users](/docs/interfaces/auth/users) - The user table and model, password hashing, the password policy, sanitization, the account mail entry points, and announcing a registration
-- [External Identities](/docs/interfaces/auth/external-identities) - Bind and read the accounts a user owns on external login providers
+- [Authentication](/docs/interfaces/auth/authentication): Resolve a request to a user with the authentication decorators and `authenticateRequestUser`.
+- [Tokens and sessions](/docs/interfaces/auth/tokens-and-sessions): Issue and validate access, refresh, two-factor and tenant-assignment tokens, and record login sessions.
+- [Users](/docs/interfaces/auth/users): The user table and model, password hashing, the password policy, sanitization, the account mail functions, and announcing a registration.
+- [External identities](/docs/interfaces/auth/external-identities): Bind and read the accounts a user owns on external login providers.