@antelopejs/interface-dms 0.10.4 → 0.13.0

package/docs/2.auth/2.authentication.md

@@ -1,26 +1,25 @@
 ---
 title: "Authentication"
-description: "Authentication turns an incoming HTTP request into a `User` row."
+description: "The authentication decorators, `authenticateRequestUser`, and the token input they share."
+mode: reference
 ---
 
-# Authentication
-
 ## Overview
 
-Authentication turns an incoming HTTP request into a `User` row. The interface exposes one plain function, `authenticateRequestUser`, and four decorators with the `CreateAuthDecorator` contract of `@antelopejs/interface-auth`: `AuthRawUser`, `AuthUser`, `IfAuthUser` and `AuthOwnerOnly`. Each of them, and `authenticateRequestUser`, binds the verified user and tenant to the request, which [`getRequestTenantId`](/docs/interfaces/core/tenancy#resolve-the-requests-tenant) then answers.
+Authentication turns an incoming HTTP request into a `User` row. `@antelopejs/interface-dms/auth` exports one plain function, `authenticateRequestUser`, and four decorators: `AuthRawUser`, `AuthUser`, `IfAuthUser` and `AuthOwnerOnly`. Each of them binds the verified user and tenant to the request, and [`getRequestTenantId`](/docs/interfaces/core/tenancy#resolve-the-requests-tenant) then returns that tenant.
 
-All of them read the bearer token from the request's `Authorization` header (`Authorization: Bearer <token>`) and run the same two steps:
+All of them read the bearer token from the `Authorization` header of the request (`Authorization: Bearer <token>`) and run the same two steps:
 
-1. **Authenticator** — decodes the token into a `TenantTokenInput`: the user id, the tenant id, and the undecoded token itself.
-2. **Validator** — loads the user named by that id, verifies the token signature against that user, and applies the extra requirement the decorator stands for.
+1. The authenticator decodes the token into a `TenantTokenInput`: the user id, the tenant id, and the undecoded token itself.
+2. The validator loads the user named by that id and verifies the token against that user. It checks the signature, checks that the token was issued as an access token, and checks that the session the token names still exists. It then applies the extra requirement of the decorator.
 
-Whatever the validator returns is what gets injected. The four decorators differ only in the requirement they enforce and in what they do when it fails.
+The decorator injects whatever the validator returns. The four decorators differ only in the requirement they enforce and in what they do when it fails.
 
-The `User` type they inject comes from the `/db` subpath and is documented in [Users](/docs/interfaces/auth/users). The tokens they consume are produced by the generators in [Tokens and Sessions](/docs/interfaces/auth/tokens-and-sessions).
+The `User` type they inject comes from `@antelopejs/interface-dms/auth/db` and is described in [Users](/docs/interfaces/auth/users). The generators in [Tokens and sessions](/docs/interfaces/auth/tokens-and-sessions) produce the tokens they consume.
 
-## Require an Authenticated User
+## Require an authenticated user
 
-`AuthUser` injects the `User` and enforces email validation when the deployment's authentication configuration requires it. Use it for any route that must have a signed-in caller.
+`AuthUser` injects the `User`, and enforces email validation when the deployment sets `auth.mustValidateEmail`. A caller whose email is not validated then gets `401` (`Email not validated`). Use it on any route that must have a signed-in caller.
 
 ```typescript
 import { Controller, Get } from "@antelopejs/interface-api";
@@ -36,11 +35,11 @@ export class ProfileController extends Controller("/api/profile") {
 }
 ```
 
-The injected value is the full `User` row, including fields you do not want to return over HTTP. Pass it through `sanitizeUser` before serializing it — see [Users](/docs/interfaces/auth/users).
+The injected value is the full `User` row, including fields you must not return over HTTP. Pass it through `sanitizeUser` before you serialize it, as described in [Users](/docs/interfaces/auth/users).
 
-## Skip the Email-Validation Gate
+## Skip the email-validation gate
 
-`AuthRawUser` resolves the same `User` but does not apply the email-validation requirement. It is what the routes that exist *because* the email is not validated yet need — reading the current account, logging out, requesting a new validation mail — and it is also what modules use to gate their own API routes on a signed-in caller.
+`AuthRawUser` resolves the same `User` but does not apply the email-validation requirement. The routes that exist because the email is not validated yet use it: reading the current account, logging out, and requesting a new validation email. Modules also use it to gate their own API routes on a signed-in caller.
 
 ```typescript
 import { Controller, Get, Post } from "@antelopejs/interface-api";
@@ -65,11 +64,11 @@ export class AccountController extends Controller("/api/account") {
 }
 ```
 
-Both decorators inject the raw database row; neither strips sensitive fields. "Raw" here refers to skipping the email-validation step, not to the shape of the object.
+Both decorators inject the raw database row, and neither strips sensitive fields. "Raw" refers to the skipped email-validation step, not to the shape of the object.
 
-## Accept Anonymous Callers
+## Accept anonymous callers
 
-`IfAuthUser` is the optional variant. It injects `User | undefined` and does not reject the request: a missing token, a malformed token and a token that fails validation all resolve to `undefined`.
+`IfAuthUser` is the optional variant. It injects `User | undefined` and does not reject the request. A missing token, a malformed token, and a token that fails validation all resolve to `undefined`.
 
 ```typescript
 import { Controller, Get } from "@antelopejs/interface-api";
@@ -87,11 +86,11 @@ export class ArticleController extends Controller("/api/articles") {
 }
 ```
 
-Because an expired token resolves to `undefined` rather than a 401, a client-side refresh interceptor keyed on 401 responses does not fire for a route guarded this way. When a route must hard-fail on an expired session, guard it with `AuthUser` and give the anonymous path its own route.
+An expired token resolves to `undefined`, not to a 401. A client-side refresh interceptor that reacts to 401 responses therefore does not fire on a route guarded this way. When a route must fail on an expired session, guard it with `AuthUser` and give the anonymous path its own route.
 
-## Restrict a Route to Platform Owners
+## Restrict a route to platform owners
 
-`AuthOwnerOnly` requires the authenticated user to be a platform owner (`User.owner === true`). It answers `401` when no token is provided and `403` when the caller is authenticated but not an owner. The DMS applies it to pages under `/modules/`, which are owner-only administration spaces.
+`AuthOwnerOnly` requires the authenticated user to be a platform owner (`User.owner === true`). It answers `401` when no token is provided and `403` (`Owner-only`) when the caller is authenticated but not an owner. The DMS applies it to the pages a module declares (`/modules/<id>/...`), which are owner-only administration spaces, unless the page is public or declares `authOnly`.
 
 ```typescript
 import { Controller, Get } from "@antelopejs/interface-api";
@@ -109,11 +108,11 @@ export class MaintenanceController extends Controller("/api/maintenance") {
 }
 ```
 
-`AuthOwnerOnly` is a plain function that returns a ready-to-apply decorator, so it is written `@AuthOwnerOnly()` exactly like the three decorator factories above. It takes no arguments, because it pre-applies its own validator.
+`AuthOwnerOnly` is a plain function that returns a decorator ready to apply, so you write `@AuthOwnerOnly()` like the three decorator factories above. It takes no arguments, because it supplies its own validator.
 
-## Gate Every Route on a Controller
+## Gate every route on a controller
 
-`AuthRawUser`, `AuthUser` and `IfAuthUser` follow the `CreateAuthDecorator` contract, so they apply to a parameter, to a property, or to the controller class itself. A property provider is a computed property of the controller, resolved on every request the controller handles whether or not the handler reads it — so a decorated property gates the whole controller and gives the handlers a typed `this.user`.
+`AuthRawUser`, `AuthUser` and `IfAuthUser` apply to a parameter, to a property, or to the controller class itself. A property provider is a computed property of the controller. It is resolved on every request the controller handles, whether or not the handler reads it. A decorated property therefore gates the whole controller and gives the handlers a typed `this.user`.
 
 ```typescript
 import { Controller, Get, JSONBody, Post } from "@antelopejs/interface-api";
@@ -144,11 +143,11 @@ export class SettingsController extends Controller("/api/settings") {
 }
 ```
 
-This is the form the DMS uses when it wires authentication onto a page controller: the decorator is applied to the `user` property of the page class.
+The DMS uses this form when it wires authentication onto a page controller. It applies the decorator to the `user` property of the page class.
 
-## Read the Token Payload
+## Read the token payload
 
-`TenantTokenInput` is the value the authenticator step produces and the validator step consumes. It is exported from the root subpath.
+`TenantTokenInput` is the value the authenticator step produces and the validator step consumes. It is exported from `@antelopejs/interface-dms/auth`.
 
 ```typescript
 export interface TenantTokenInput {
@@ -160,17 +159,17 @@ export interface TenantTokenInput {
 
 | Field | Type | Description |
 | ----- | ---- | ----------- |
-| `tenantId` | `string` | The tenant the token was issued for, taken from the token's `tenantId` claim. |
+| `tenantId` | `string` | The tenant the token was issued for, taken from the `tenantId` claim of the token. |
 | `id` | `string` | The `_id` of the user the token was issued for. |
 | `rawToken` | `string` | The undecoded bearer token, used to verify the signature against the user. |
 
-The decoded payload carries no signature guarantee on its own: the validator is the step that verifies `rawToken` against the user it names.
+The decoded payload carries no signature guarantee on its own. The validator is the step that verifies `rawToken` against the user it names.
 
-## Authenticate Inside a Custom Provider
+## Authenticate inside a custom provider
 
-`authenticateRequestUser` performs the same authenticate-then-validate sequence outside the decorator machinery. Use it when you write your own parameter provider and need the user plus something else in one place.
+`authenticateRequestUser` runs the same authenticator and validator outside a decorator. Use it when you write your own parameter provider and need the user and something else in one place.
 
-```typescript
+```typescript fragment
 authenticateRequestUser(ctx: RequestContext): Promise<User>
 ```
 
@@ -178,7 +177,7 @@ authenticateRequestUser(ctx: RequestContext): Promise<User>
 | --------- | ----------- |
 | `ctx` | The request context handed to a parameter provider, from `@antelopejs/interface-api`. The function reads `ctx.rawRequest.headers.authorization`. |
 
-It runs the same validation as `AuthUser`, so the email-validation gate applies: a caller whose email is not validated is rejected when the deployment's configuration requires validation. Every failure throws an `HTTPResult` with status `401`.
+It runs the same validation as `AuthUser`, so the email-validation gate applies. A caller whose email is not validated is rejected when the deployment requires validation. Every failure throws an `HTTPResult` with status `401`. It also throws `401` when the request is already bound to another user or tenant.
 
 ```typescript
 import {
@@ -204,19 +203,42 @@ export const AuthBetaTester = MakeParameterAndPropertyDecorator(
 );
 ```
 
-This is how the DMS builds its tenant guards: `AuthTenantOwner` and `AuthTenantMember` in `@antelopejs/interface-dms/guards` both start from `authenticateRequestUser`, then resolve the request's tenant and check the caller's membership on top of it.
+The DMS builds its tenant guards the same way. `AuthTenantOwner` and `AuthTenantMember` in `@antelopejs/interface-dms/guards` authenticate the request, then resolve its tenant and check the caller's membership.
+
+A provider is also the way to add a requirement and keep the built-in one. A call site can pass a replacement validator, as in `@AuthUser(callback)`. That callback replaces the whole validation step, signature check included, and its return type is `boolean | User`. Such a call binds no tenant to the request. This interface exports no token-verification function, so a replacement validator cannot redo the signature check it removes.
+
+## Accept another credential family
+
+`@antelopejs/interface-dms/auth` also exports the `RequestPrincipal` and `RequestAuthenticator` types. A `RequestAuthenticator` lets one route accept a credential that is not a DMS JWT. The decorators on this page accept only the DMS JWT. To accept another credential, pass authenticators to `authenticateTenantRequest` in `@antelopejs/interface-dms/guards`, through its `authenticators` option.
+
+```typescript fragment
+interface RequestPrincipal {
+  user: User;
+  tenantId: string;
+}
+
+interface RequestAuthenticator {
+  recognizes(token: string): boolean;
+  authenticate(token: string): Promise<RequestPrincipal>;
+}
+```
+
+| Member | Contract |
+| ------ | -------- |
+| `recognizes` | Claims the credential family from the bearer token, without trusting its contents. It must also recognize a malformed credential of its own family. |
+| `authenticate` | Verifies the credential and reloads its user. It throws on an invalid, expired or revoked credential. |
 
-A provider is also the way to add a requirement without losing the built-in one. The `CreateAuthDecorator` contract lets a call site pass a replacement validator — `@AuthUser(callback)` — but that callback replaces the whole validation step, signature check included, and its return type is constrained to `boolean | User`; such a call binds no tenant to the request. This interface exports no token-verification primitive, so a replacement validator cannot redo the signature check it removes.
+A token that no authenticator recognizes falls back to the DMS JWT. A token that two authenticators recognize is refused with `401`. A principal is identity and tenant established together. It is not an authorization.
 
-## Decorator Reference
+## Decorator reference
 
 | Decorator | Injects | Email validation | On failure |
 | --------- | ------- | ---------------- | ---------- |
 | `AuthRawUser()` | `User` | Not checked | `401` |
 | `AuthUser()` | `User` | Enforced when the configuration requires it | `401` |
 | `IfAuthUser()` | `User \| undefined` | Enforced when the configuration requires it | Resolves to `undefined` |
-| `AuthOwnerOnly()` | `User` | Enforced when the configuration requires it | `401` without a token, `403` when not an owner |
+| `AuthOwnerOnly()` | `User` | Enforced when the configuration requires it | `401` without a valid token, `403` when not an owner |
 
-## Next Steps
+## Next steps
 
-Continue with [Tokens and Sessions](/docs/interfaces/auth/tokens-and-sessions) to see how the tokens these decorators consume are issued and validated.
+Continue with [Tokens and sessions](/docs/interfaces/auth/tokens-and-sessions) to see how the DMS issues and validates the tokens these decorators consume.

package/docs/2.auth/3.tokens-and-sessions.md

@@ -1,28 +1,27 @@
 ---
-title: "Tokens and Sessions"
-description: "The interface issues four kinds of token, and it records a login as a row in the `sessions` table."
+title: "Tokens and sessions"
+description: "The four token kinds, their generators and validators, the token payload, and the `Session` table and model."
+mode: reference
 ---
 
-# Tokens and Sessions
-
 ## Overview
 
-The interface issues four kinds of token, and it records a login as a row in the `sessions` table. Three of the four come with an exported validator; the access token is validated by the authentication decorators instead.
+The interface issues four kinds of token, and it records a login as a row in the `sessions` table. Three of the four token kinds have an exported validator. The authentication decorators validate the access token.
 
 | Token | Generated by | Validated by | Carries |
 | ----- | ------------ | ------------ | ------- |
-| Access | `generateAccessToken` | The authentication decorators in [Authentication](/docs/interfaces/auth/authentication) | `id`, `tenantId`, optional `sessionId` |
-| Refresh | `generateRefreshToken` | `validateRefreshToken` | `id`, `tenantId`, optional `sessionId` |
+| Access | `generateAccessToken` | The authentication decorators in [Authentication](/docs/interfaces/auth/authentication) | `id`, `tenantId`, optional `sessionId`, a purpose marker |
+| Refresh | `generateRefreshToken` | `validateRefreshToken` | `id`, `tenantId`, optional `sessionId`, a purpose marker |
 | Two-factor | `generateTwoFactorToken` | `validateTwoFactorToken` | `id`, `tenantId`, a purpose marker |
 | Tenant assignment | `generateTenantAssignmentToken` | `validateTenantAssignmentToken` | `id`, a purpose marker |
 
-Every generator takes the `User` it signs for, and every validator loads that user back before it returns. All seven are interface functions, so every call returns a promise.
+Every generator takes the `User` it signs for, and every validator loads that user before it returns. All seven functions are interface functions, so every call returns a promise. The purpose marker keeps one kind of token from being accepted as another. A refresh token sent as a bearer token fails authentication, for example.
 
-Access and refresh tokens are the pair a client holds: the access token goes in the `Authorization` header of ordinary requests, and the refresh token buys a new access token when it expires. Two-factor and tenant-assignment tokens are short-lived hand-offs that stand between a password check and a real session.
+A client holds the access and refresh pair. The access token goes in the `Authorization` header of ordinary requests, and the refresh token gets a new access token when the old one expires. Two-factor and tenant-assignment tokens are short-lived steps between a password check and a real session.
 
-## Issue an Access and Refresh Token Pair
+## Issue an access and refresh token pair
 
-```typescript
+```typescript fragment
 generateAccessToken(
   tenantId: string,
   user: User,
@@ -38,11 +37,11 @@ generateRefreshToken(
 
 | Parameter | Description |
 | --------- | ----------- |
-| `tenantId` | The tenant the token is scoped to. It lands in the token's `tenantId` claim and is what the request's tenant resolution reads back. |
-| `user` | The `User` the token is issued for. The user's `authKey` takes part in the signing secret, so rotating `authKey` invalidates every token previously issued to that user. |
-| `sessionId` | The `_id` of the `Session` row that records this login. Optional: a token issued without one is valid but is not tied to a revocable session. An access token issued with one is refused as soon as that row is deleted. |
+| `tenantId` | The tenant the token is scoped to. It goes in the `tenantId` claim of the token, and the request's tenant resolution reads it back. |
+| `user` | The `User` the token is issued for. The user's `authKey` is part of the signing secret, so rotating `authKey` invalidates every token issued to that user before. |
+| `sessionId` | The `_id` of the `Session` row that records this login. Optional. A token issued without it is valid but is not tied to a revocable session. An access token issued with it is refused as soon as that row is deleted. |
 
-Both return the signed `token` and its lifetime as `expiresIn` in milliseconds, taken from the deployment's `accessTokenLifetime` and `refreshTokenLifetime` configuration.
+Both functions return the signed `token`, and its lifetime as `expiresIn` in milliseconds. The lifetimes come from the `accessTokenLifetime` and `refreshTokenLifetime` settings of the deployment.
 
 ```typescript
 import {
@@ -79,15 +78,15 @@ export async function startSession(
 }
 ```
 
-## Validate a Refresh Token
+## Validate a refresh token
 
-```typescript
+```typescript fragment
 validateRefreshToken(
   token: string,
 ): Promise<{ id: string; tenantId: string; sessionId?: string }>
 ```
 
-The function decodes the token, loads the user it names, and verifies the signature against that user. It throws `HTTPResult(401)` when the user no longer exists or the signature does not check out. It returns the claims only — confirming that the session still exists, that the token is still its current one (`isCurrentRefreshToken`), and that the user still has access to `tenantId` is the caller's job.
+The function decodes the token, loads the user it names, and verifies the signature against that user. It also checks that the token was issued as a refresh token and carries non-empty `id` and `tenantId` claims. It throws `HTTPResult(401)` when the user no longer exists (`Invalid user`), and when the token is malformed, expired, badly signed or issued for another purpose. It returns the claims only. The caller must still confirm three things: that the session exists, that the token is its current one (`isCurrentRefreshToken`), and that the user still has access to `tenantId`.
 
 ```typescript
 import { HTTPResult } from "@antelopejs/interface-api";
@@ -130,13 +129,13 @@ export async function refresh(
 }
 ```
 
-Because the returned payload names a `tenantId`, the same call backs a tenant switch: validate the refresh token, check the user's membership of the target tenant, then issue a new pair for that tenant instead.
+The returned payload names a `tenantId`, so the same call also backs a tenant switch. Validate the refresh token, check the user's membership of the target tenant, then issue a new pair for that tenant.
 
-## Hand Off to a Second Factor
+## Hand off to a second factor
 
-When a user's credentials check out but the account has second factors enabled, issue a two-factor token instead of a session and let the client come back with the code.
+When the credentials of a user check out but the account has second factors enabled, issue a two-factor token instead of a session. The client then comes back with the code.
 
-```typescript
+```typescript fragment
 generateTwoFactorToken(
   tenantId: string,
   user: User,
@@ -150,7 +149,7 @@ validateTwoFactorToken(token: string): Promise<{
 }>
 ```
 
-`validateTwoFactorToken` rejects a token that was not issued for the two-factor purpose, and resolves the `User` for you so the verification route can read `twoFactorMethods`, `twoFactorSecret` and the rest without a second lookup. Whatever is wrong with the token (not a JWT, unknown user, bad signature, expired, another purpose), it throws the same `HTTPResult(401, "error.invalid_2fa_token")`, so a caller cannot tell which user ids exist. `expiresIn` is the token's lifetime in milliseconds.
+A two-factor token lives five minutes, and `expiresIn` gives that lifetime in milliseconds. `validateTwoFactorToken` rejects a token that was not issued for the two-factor purpose. It resolves the `User` for you, so the verification route can read `twoFactorMethods`, `twoFactorSecret` and the other fields without a second lookup. Whatever is wrong with the token, it throws the same `HTTPResult(401, "error.invalid_2fa_token")`: not a JWT, unknown user, bad signature, expired, or another purpose. A caller therefore cannot tell which user ids exist.
 
 ```typescript
 import { createHash } from "node:crypto";
@@ -192,13 +191,13 @@ export async function requestEmailCode(
 }
 ```
 
-Once the code checks out, the route issues a real access and refresh pair with the `tenantId` the two-factor token carried. `send2FAEmail` and the other mail entry points are covered in [Users](/docs/interfaces/auth/users).
+Once the code checks out, the route issues a real access and refresh pair for the `tenantId` the two-factor token carried. [Users](/docs/interfaces/auth/users) covers `send2FAEmail` and the other mail functions.
 
-## Hand Off Tenant Assignment
+## Hand off tenant assignment
 
-A user whose credentials are valid but who belongs to no tenant yet cannot receive an access token, because an access token is always scoped to a tenant. `generateTenantAssignmentToken` covers that gap: it signs the user without a tenant claim so an onboarding flow can pick or create one.
+A user whose credentials are valid but who belongs to no tenant yet cannot receive an access token, because an access token is always scoped to a tenant. `generateTenantAssignmentToken` fills that gap. It signs the user without a tenant claim, so an onboarding flow can pick or create a tenant.
 
-```typescript
+```typescript fragment
 generateTenantAssignmentToken(
   user: User,
 ): Promise<{ token: string; expiresIn: number }>
@@ -206,7 +205,7 @@ generateTenantAssignmentToken(
 validateTenantAssignmentToken(token: string): Promise<{ id: string; user: User }>
 ```
 
-`validateTenantAssignmentToken` rejects a token that was not issued for the tenant-assignment purpose and returns the user id together with the loaded `User`. Like the two-factor check, every refusal is the same `HTTPResult(401, "Invalid tenant assignment token")`.
+A tenant-assignment token lives fifteen minutes. `validateTenantAssignmentToken` rejects a token that was not issued for the tenant-assignment purpose, and returns the user id together with the loaded `User`. Like the two-factor check, every refusal is the same `HTTPResult(401, "Invalid tenant assignment token")`.
 
 ```typescript
 import {
@@ -231,7 +230,7 @@ export async function completeTenantAssignment(
 }
 ```
 
-## The Token Payload
+## The token payload
 
 `JwtUserPayload` describes the claims an access or refresh token carries about its subject. Use it as the target type when you decode a token yourself.
 
@@ -247,15 +246,15 @@ export interface JwtUserPayload {
 | ----- | ---- | ----------- |
 | `id` | `string` | The `_id` of the user the token was issued for. |
 | `tenantId` | `string` | The tenant the token is scoped to. |
-| `sessionId` | `string \| undefined` | The `Session` row backing the token, when the token was issued with one. |
+| `sessionId` | `string \| undefined` | The `Session` row behind the token, when the token was issued with one. |
 
-`TenantTokenInput` from [Authentication](/docs/interfaces/auth/authentication) names the same subject from the other side: it is what a validator receives — `id` and `tenantId` plus the undecoded `rawToken` — while `JwtUserPayload` is what the token itself says. The two overlap on `id` and `tenantId`; neither is a subset of the other.
+`TenantTokenInput`, from [Authentication](/docs/interfaces/auth/authentication), describes the same subject from the other side. It is what a validator receives: `id` and `tenantId`, plus the undecoded `rawToken`. `JwtUserPayload` is what the token itself says. The two types share `id` and `tenantId`, and neither is a subset of the other.
 
-## Record a Login Session
+## Record a login session
 
-`createSession` inserts a `Session` row for a login and returns its `_id`, ready to be passed as the `sessionId` of the token pair.
+`createSession` inserts a `Session` row for a login and returns its `_id`. Pass that id as the `sessionId` of the token pair.
 
-```typescript
+```typescript fragment
 createSession(
   sessionModel: SessionModel,
   userId: string,
@@ -268,14 +267,14 @@ createSession(
 | --------- | ----------- |
 | `sessionModel` | The `SessionModel` instance to insert through. |
 | `userId` | The `_id` of the user logging in. |
-| `userAgent` | The request's `User-Agent` header. It is parsed into the `browser`, `os` and `deviceType` fields; the raw string is kept in `userAgent`. |
-| `ip` | The caller's IP address, stored as-is. |
+| `userAgent` | The `User-Agent` header of the request. The DMS parses it into the `browser`, `os` and `deviceType` fields and keeps the raw string in `userAgent`. |
+| `ip` | The IP address of the caller, stored as given. |
 
-The row starts with an empty `refreshToken` and `location`, and with `createdAt` and `lastActiveAt` set to the current time. Record the refresh token with `sessionModel.replaceRefreshToken` once you have generated it, as in the first example on this page.
+The row starts with no refresh token hash, an empty `location`, and `createdAt` and `lastActiveAt` set to the current time. Record the refresh token with `sessionModel.replaceRefreshToken` once you have generated it, as in the first example on this page.
 
-## The Session Table
+## The session table
 
-`Session` is registered as the `sessions` table under the DMS core schema, so its rows are shared across tenants and its model is retrieved without a tenant instance. The class, its table-name constant and its model all live on the `/db` subpath.
+`Session` is registered as the `sessions` table in the DMS core schema. Its rows are shared across tenants, and you obtain its model without a tenant instance. The class, its table-name constant and its model all live in `@antelopejs/interface-dms/auth/db`.
 
 ```typescript
 import {
@@ -287,10 +286,12 @@ import {
 
 | Field | Type | Description |
 | ----- | ---- | ----------- |
-| `_id` | `string` | Primary key. This is the value that travels in the token's `sessionId` claim. |
-| `userId` | `string` | The owning user's `_id`. Indexed, and declared as a relation to the `User` table. |
-| `refreshTokenHash` | `string \| null` | sha256 of the refresh token currently valid for this session. Matching it on refresh is what makes a session revocable; the token itself is never stored. |
-| `sealedRefreshToken` | `string \| null` | The current refresh token encrypted under a key derived from its predecessor, so a client still holding the predecessor during the rotation grace window can be handed the current token. Unreadable without the predecessor. |
+| `_id` | `string` | Primary key. This value travels in the `sessionId` claim of the token. |
+| `userId` | `string` | The `_id` of the owning user. Indexed, and declared as a relation to the `User` table. |
+| `refreshTokenHash` | `string \| null`, optional | SHA-256 of the refresh token currently valid for this session. A refresh matches against it, which makes the session revocable. The token itself is never stored. |
+| `sealedRefreshToken` | `string \| null`, optional | The current refresh token, encrypted under a key derived from its predecessor. A client that still holds the predecessor during the rotation grace window can get the current token back. Without the predecessor, the value is unreadable. |
+| `previousRefreshTokenHash` | `string \| null`, optional | SHA-256 of the refresh token the last rotation replaced. |
+| `refreshTokenRotatedAt` | `Date \| null`, optional | When the last rotation happened. It starts the grace window. |
 | `userAgent` | `string` | The raw `User-Agent` string captured at login. |
 | `ip` | `string` | The IP address captured at login. |
 | `browser` | `string` | Browser name and version parsed from `userAgent`, or `"Unknown"`. |
@@ -298,23 +299,23 @@ import {
 | `deviceType` | `string` | Device class parsed from `userAgent`: `"mobile"`, `"tablet"`, or `"desktop"` when neither applies. |
 | `location` | `string` | Free-form location label. `createSession` leaves it empty. |
 | `createdAt` | `Date` | Set on insert by the creation-time decorator. Indexed. |
-| `lastActiveAt` | `Date` | Last time the session was seen. Refresh handlers update it. Indexed: a daily job deletes the sessions last active longer ago than `refreshTokenLifetime`. |
+| `lastActiveAt` | `Date` | The last time the session was used. Refresh handlers update it. Indexed. Every day at 03:30, a DMS job deletes the sessions last active longer ago than `refreshTokenLifetime`. |
 
 `SESSIONS_TABLE_NAME` holds the table name, `"sessions"`.
 
-`isCurrentRefreshToken(session, token)` tells whether a presented token is the session's current one, comparing hashes in constant time and still honouring a session written before hashing.
+`isCurrentRefreshToken(session, token)` tells whether a presented token is the current one of the session. It compares hashes in constant time, and returns `false` when the session has no `refreshTokenHash`.
 
-## Query Sessions with SessionModel
+## Query sessions with `SessionModel`
 
-`SessionModel` extends `BasicDataModel(Session, SESSIONS_TABLE_NAME)`, so it has the standard `get`, `getBy`, `getAll`, `insert`, `update` and `delete` operations, plus the refresh-token operations and two lookups by user.
+`SessionModel` extends `BasicDataModel(Session, SESSIONS_TABLE_NAME)`. It has the standard `get`, `getBy`, `getAll`, `insert`, `update` and `delete` operations, plus the refresh-token operations and two lookups by user.
 
 | Method | Signature | Description |
 | ------ | --------- | ----------- |
-| `replaceRefreshToken` | `(sessionId: string, refreshToken: string) => Promise<void>` | Make a token the session's current one, storing only its hash. |
-| `rotateRefreshToken` | `(sessionId: string, presentedToken: string, refreshToken: string, rotatedAt?: Date) => Promise<string \| null>` | Atomically replace the presented token with a new one. A client presenting the immediate predecessor within the grace window gets the current token back; any other token gets `null`. |
-| `deleteInactiveSince` | `(threshold: Date) => Promise<void>` | Delete the sessions last active before a date. |
-| `getByUserId` | `(userId: string) => Promise<Session[]>` | Every session belonging to a user, read through the `userId` index. |
-| `deleteByUserId` | `(userId: string) => Promise<void>` | Delete every session belonging to a user. |
+| `replaceRefreshToken` | `(sessionId: string, refreshToken: string) => Promise<void>` | Makes a token the current one of the session, storing only its hash. Clears the sealed token and the predecessor, so no grace window applies. |
+| `rotateRefreshToken` | `(sessionId: string, presentedToken: string, refreshToken: string, rotatedAt?: Date) => Promise<string \| null>` | Replaces the presented token with a new one in one atomic update, and sets `lastActiveAt`. A client that presents the immediate predecessor within the 15-second grace window gets the current token back. Any other token gets `null`. |
+| `deleteInactiveSince` | `(threshold: Date) => Promise<void>` | Deletes the sessions last active before a date. |
+| `getByUserId` | `(userId: string) => Promise<Session[]>` | Every session of a user, read through the `userId` index. |
+| `deleteByUserId` | `(userId: string) => Promise<void>` | Deletes every session of a user. |
 
 ```typescript
 import { Controller, Delete, Get } from "@antelopejs/interface-api";
@@ -345,8 +346,8 @@ export class SessionsController extends Controller("/api/sessions") {
 }
 ```
 
-Deleting a session stops refreshes from succeeding and cuts off the access tokens issued for it at once: the authentication decorators refuse an access token whose `sessionId` no longer names a session of its user. A token issued without a `sessionId` stays valid until it expires; to cut those off too, rotate the user's `authKey` as described in [Users](/docs/interfaces/auth/users).
+Deleting a session stops its refreshes, and cuts off the access tokens issued for it at once. The authentication decorators refuse an access token whose `sessionId` no longer names a session of its user. A token issued without a `sessionId` stays valid until it expires. To cut those tokens off too, rotate the user's `authKey`, as described in [Users](/docs/interfaces/auth/users).
 
-## Next Steps
+## Next steps
 
-Continue with [Users](/docs/interfaces/auth/users) for the `User` table, `UserModel`, `sanitizeUser`, and the account mail entry points.
+Continue with [Users](/docs/interfaces/auth/users) for the `User` table, `UserModel`, `sanitizeUser`, and the account mail functions.