@antelopejs/interface-dms 0.7.1 → 0.7.3

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

@@ -0,0 +1,75 @@
+---
+title: "Introduction"
+description: "The auth domain answers who is calling: authentication decorators, tokens and sessions, users and external identities."
+---
+
+# 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.
+
+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 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.
+
+## Dependencies
+
+This interface 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.
+
+## Quick Start
+
+The following controller gates a route on an authenticated user and returns the account with its secrets stripped.
+
+```typescript
+import { Controller, Get } from "@antelopejs/interface-api";
+import {
+  AuthUser,
+  sanitizeUser,
+} from "@antelopejs/interface-dms/auth";
+import type { User } from "@antelopejs/interface-dms/auth/db";
+
+export class ProfileController extends Controller("/api/profile") {
+  @Get("")
+  profile(@AuthUser() user: User): Promise<Partial<User>> {
+    // 401 before this line runs when the token is missing or invalid
+    return sanitizeUser(user);
+  }
+}
+```
+
+A client reaches it by sending the access token issued at login in the `Authorization` header, as `Bearer <access token>`.
+
+## Documentation Sections
+
+- [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

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

@@ -0,0 +1,222 @@
+---
+title: "Authentication"
+description: "Authentication turns an incoming HTTP request into a `User` row."
+---
+
+# Authentication
+
+## Overview
+
+Authentication turns an incoming HTTP request into a `User` row. The interface exposes one plain function, `authenticateRequestUser`, and four decorators built with `CreateAuthDecorator` from `@antelopejs/interface-auth`: `AuthRawUser`, `AuthUser`, `IfAuthUser` and `AuthOwnerOnly`.
+
+All of them read the bearer token from the request's `Authorization` header (`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.
+
+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 `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).
+
+## 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.
+
+```typescript
+import { Controller, Get } from "@antelopejs/interface-api";
+import { AuthUser } from "@antelopejs/interface-dms/auth";
+import type { User } from "@antelopejs/interface-dms/auth/db";
+
+export class ProfileController extends Controller("/api/profile") {
+  @Get("")
+  getProfile(@AuthUser() user: User): { id: string; email: string } {
+    // 401 before the handler runs when the token is missing or invalid
+    return { id: user._id, email: user.email };
+  }
+}
+```
+
+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).
+
+## 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.
+
+```typescript
+import { Controller, Get, Post } from "@antelopejs/interface-api";
+import {
+  AuthRawUser,
+  sendEmailValidationEmail,
+} from "@antelopejs/interface-dms/auth";
+import type { User } from "@antelopejs/interface-dms/auth/db";
+
+export class AccountController extends Controller("/api/account") {
+  @Get("/me")
+  me(@AuthRawUser() user: User): { email: string; isValidated: boolean } {
+    return { email: user.email, isValidated: user.isValidated };
+  }
+
+  @Post("/resend-validation")
+  async resendValidation(@AuthRawUser() user: User): Promise<{ sent: true }> {
+    // reachable while user.isValidated is still false
+    await sendEmailValidationEmail(user);
+    return { sent: true };
+  }
+}
+```
+
+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.
+
+## 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`.
+
+```typescript
+import { Controller, Get } from "@antelopejs/interface-api";
+import { IfAuthUser } from "@antelopejs/interface-dms/auth";
+import type { User } from "@antelopejs/interface-dms/auth/db";
+
+export class ArticleController extends Controller("/api/articles") {
+  @Get("")
+  list(@IfAuthUser() user: User | undefined) {
+    // a missing, malformed or expired token all land here as `undefined`
+    return user
+      ? { scope: "member", readerId: user._id }
+      : { scope: "anonymous" };
+  }
+}
+```
+
+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.
+
+## 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.
+
+```typescript
+import { Controller, Get } from "@antelopejs/interface-api";
+import { AuthOwnerOnly } from "@antelopejs/interface-dms/auth";
+import type { User } from "@antelopejs/interface-dms/auth/db";
+
+export class MaintenanceController extends Controller("/api/maintenance") {
+  private jobs: string[] = ["reindex", "purge-sessions"];
+
+  @Get("/jobs")
+  listJobs(@AuthOwnerOnly() owner: User) {
+    // only reached when owner.owner === true
+    return { requestedBy: owner.email, jobs: this.jobs };
+  }
+}
+```
+
+`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.
+
+## Gate Every Route on a Controller
+
+`AuthRawUser`, `AuthUser` and `IfAuthUser` are built with `CreateAuthDecorator`, 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`.
+
+```typescript
+import { Controller, Get, JSONBody, Post } from "@antelopejs/interface-api";
+import { AuthUser } from "@antelopejs/interface-dms/auth";
+import type { User } from "@antelopejs/interface-dms/auth/db";
+
+interface Settings {
+  theme: string;
+}
+
+export class SettingsController extends Controller("/api/settings") {
+  @AuthUser()
+  declare user: User;
+
+  private settings: Record<string, Settings> = {};
+
+  @Get("")
+  read(): Settings {
+    return this.settings[this.user._id] ?? { theme: "light" };
+  }
+
+  @Post("")
+  write(@JSONBody() body: Settings): Settings {
+    // also authenticated: the provider ran before the handler
+    this.settings[this.user._id] = body;
+    return body;
+  }
+}
+```
+
+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.
+
+## Read the Token Payload
+
+`TenantTokenInput` is the value the authenticator step produces and the validator step consumes. It is exported from the root subpath.
+
+```typescript
+export interface TenantTokenInput {
+  tenantId: string;
+  id: string;
+  rawToken: string;
+}
+```
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `tenantId` | `string` | The tenant the token was issued for, taken from the token's `tenantId` claim. |
+| `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.
+
+## 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.
+
+```typescript
+authenticateRequestUser(ctx: RequestContext): Promise<User>
+```
+
+| Parameter | Description |
+| --------- | ----------- |
+| `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`.
+
+```typescript
+import {
+  HTTPResult,
+  type RequestContext,
+  SetParameterProvider,
+} from "@antelopejs/interface-api";
+import { MakeParameterAndPropertyDecorator } from "@antelopejs/interface-core/decorators";
+import { authenticateRequestUser } from "@antelopejs/interface-dms/auth";
+
+const FORBIDDEN = 403;
+
+export const AuthBetaTester = MakeParameterAndPropertyDecorator(
+  (target, key, index) => {
+    SetParameterProvider(target, key, index, async (ctx: RequestContext) => {
+      const user = await authenticateRequestUser(ctx);
+      if (!user.email.endsWith("@example.com")) {
+        throw new HTTPResult(FORBIDDEN, "Beta testers only");
+      }
+      return user;
+    });
+  },
+);
+```
+
+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.
+
+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`. This interface exports no token-verification primitive, so a replacement validator cannot redo the signature check it removes.
+
+## 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 |
+
+## 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.

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

@@ -0,0 +1,352 @@
+---
+title: "Tokens and Sessions"
+description: "The interface issues four kinds of token, and it records a login as a row in the `sessions` table."
+---
+
+# 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.
+
+| 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` |
+| 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.
+
+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.
+
+## Issue an Access and Refresh Token Pair
+
+```typescript
+generateAccessToken(
+  tenantId: string,
+  user: User,
+  sessionId?: string,
+): Promise<{ expiresIn: number; token: string }>
+
+generateRefreshToken(
+  tenantId: string,
+  user: User,
+  sessionId?: string,
+): Promise<{ expiresIn: number; token: string }>
+```
+
+| 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. |
+
+Both return the signed `token` and its lifetime as `expiresIn` in milliseconds, taken from the deployment's `accessTokenLifetime` and `refreshTokenLifetime` configuration.
+
+```typescript
+import {
+  createSession,
+  generateAccessToken,
+  generateRefreshToken,
+} from "@antelopejs/interface-dms/auth";
+import type {
+  SessionModel,
+  User,
+} from "@antelopejs/interface-dms/auth/db";
+
+export async function startSession(
+  sessionModel: SessionModel,
+  user: User,
+  tenantId: string,
+  userAgent: string,
+  ip: string,
+) {
+  const sessionId = await createSession(sessionModel, user._id, userAgent, ip);
+
+  const access = await generateAccessToken(tenantId, user, sessionId);
+  const refresh = await generateRefreshToken(tenantId, user, sessionId);
+
+  // store the token's hash on the session so it can be matched and revoked
+  await sessionModel.replaceRefreshToken(sessionId, refresh.token);
+
+  return {
+    token_type: "Bearer",
+    access_token: access.token,
+    expires_in: access.expiresIn,
+    refresh_token: refresh.token,
+  };
+}
+```
+
+## Validate a Refresh Token
+
+```typescript
+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.
+
+```typescript
+import { HTTPResult } from "@antelopejs/interface-api";
+import {
+  generateAccessToken,
+  validateRefreshToken,
+} from "@antelopejs/interface-dms/auth";
+import {
+  isCurrentRefreshToken,
+  type SessionModel,
+  type UserModel,
+} from "@antelopejs/interface-dms/auth/db";
+
+const UNAUTHORIZED = 401;
+
+export async function refresh(
+  userModel: UserModel,
+  sessionModel: SessionModel,
+  token: string,
+) {
+  const payload = await validateRefreshToken(token);
+
+  const user = await userModel.get(payload.id);
+  if (!user) throw new HTTPResult(UNAUTHORIZED, "error.invalid_token");
+
+  if (payload.sessionId) {
+    const session = await sessionModel.get(payload.sessionId);
+    if (!session || !isCurrentRefreshToken(session, token)) {
+      throw new HTTPResult(UNAUTHORIZED, "error.session_expired");
+    }
+    await sessionModel.update(payload.sessionId, { lastActiveAt: new Date() });
+  }
+
+  const access = await generateAccessToken(
+    payload.tenantId,
+    user,
+    payload.sessionId,
+  );
+  return { access_token: access.token, expires_in: access.expiresIn };
+}
+```
+
+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.
+
+## 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.
+
+```typescript
+generateTwoFactorToken(
+  tenantId: string,
+  user: User,
+): Promise<{ token: string; expiresIn: number }>
+
+validateTwoFactorToken(token: string): Promise<{
+  id: string;
+  tenantId: string;
+  purpose?: string;
+  user: User;
+}>
+```
+
+`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.
+
+```typescript
+import { createHash } from "node:crypto";
+import {
+  generateTwoFactorToken,
+  send2FAEmail,
+  validateTwoFactorToken,
+} from "@antelopejs/interface-dms/auth";
+import type {
+  User,
+  UserModel,
+} from "@antelopejs/interface-dms/auth/db";
+
+export async function beginTwoFactor(tenantId: string, user: User) {
+  const { token, expiresIn } = await generateTwoFactorToken(tenantId, user);
+  return {
+    requires_2fa: true,
+    two_factor_token: token,
+    expires_in: expiresIn,
+    methods: user.twoFactorMethods,
+  };
+}
+
+export async function requestEmailCode(
+  userModel: UserModel,
+  twoFactorToken: string,
+  code: string,
+) {
+  const { user } = await validateTwoFactorToken(twoFactorToken);
+
+  // Stored hashed, the way the DMS's own verification route reads it back.
+  user.twoFactorEmailCode = createHash("sha256")
+    .update(JSON.stringify([user._id, code]))
+    .digest("hex");
+  user.twoFactorEmailCodeRequestedAt = new Date();
+  await userModel.update(user);
+
+  await send2FAEmail(user, code);
+}
+```
+
+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).
+
+## 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.
+
+```typescript
+generateTenantAssignmentToken(
+  user: User,
+): Promise<{ token: string; expiresIn: number }>
+
+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")`.
+
+```typescript
+import {
+  generateAccessToken,
+  generateTenantAssignmentToken,
+  validateTenantAssignmentToken,
+} from "@antelopejs/interface-dms/auth";
+import type { User } from "@antelopejs/interface-dms/auth/db";
+
+export async function offerTenantAssignment(user: User) {
+  const { token } = await generateTenantAssignmentToken(user);
+  return { requires_tenant_assignment: true, tenant_assignment_token: token };
+}
+
+export async function completeTenantAssignment(
+  assignmentToken: string,
+  tenantId: string,
+) {
+  const { user } = await validateTenantAssignmentToken(assignmentToken);
+  // the caller attaches the user to `tenantId` before issuing real tokens
+  return generateAccessToken(tenantId, user);
+}
+```
+
+## 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.
+
+```typescript
+export interface JwtUserPayload {
+  id: string;
+  tenantId: string;
+  sessionId?: string;
+}
+```
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `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. |
+
+`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.
+
+## 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.
+
+```typescript
+createSession(
+  sessionModel: SessionModel,
+  userId: string,
+  userAgent: string,
+  ip: string,
+): Promise<string>
+```
+
+| Parameter | Description |
+| --------- | ----------- |
+| `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. |
+
+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 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.
+
+```typescript
+import {
+  SESSIONS_TABLE_NAME,
+  Session,
+  SessionModel,
+} from "@antelopejs/interface-dms/auth/db";
+```
+
+| 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. |
+| `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"`. |
+| `os` | `string` | OS name and version parsed from `userAgent`, or `"Unknown"`. |
+| `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`. |
+
+`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.
+
+## 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.
+
+| 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. |
+
+```typescript
+import { Controller, Delete, Get } from "@antelopejs/interface-api";
+import { Model } from "@antelopejs/interface-database-decorators";
+import { AuthUser } from "@antelopejs/interface-dms/auth";
+import {
+  SessionModel,
+  type User,
+} from "@antelopejs/interface-dms/auth/db";
+
+export class SessionsController extends Controller("/api/sessions") {
+  @AuthUser()
+  declare user: User;
+
+  @Model(SessionModel)
+  declare sessionModel: SessionModel;
+
+  @Get("")
+  list() {
+    return this.sessionModel.getByUserId(this.user._id);
+  }
+
+  @Delete("")
+  revokeAll() {
+    // drops every session; their access tokens stop working with them
+    return this.sessionModel.deleteByUserId(this.user._id);
+  }
+}
+```
+
+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).
+
+## Next Steps
+
+Continue with [Users](/docs/interfaces/auth/users) for the `User` table, `UserModel`, `sanitizeUser`, and the account mail entry points.