@antelopejs/interface-dms 0.7.1 → 0.7.2

package/docs/1.core/3.components.md

@@ -0,0 +1,287 @@
+---
+title: "Components"
+description: "A component is a serializable description of a piece of UI, not a live object."
+---
+
+# Components
+
+## Overview
+
+A component is a serializable description of a piece of UI, not a live object. `ComponentBuilder` collects a component name, an options object, children, watches and actions; `serialize()` turns that into plain JSON-safe data; the page layout route returns the result. Nothing in this interface renders anything.
+
+Everything on this page lives in `@antelopejs/interface-dms/component`. The [Base](/docs/interfaces/base/introduction) domain ships the concrete builders (`Form`, `TableView`, `Grid`, the chart family) built on top of these types; use this page when you write a builder of your own or when you need to know what a serialized component looks like.
+
+## The Serialize-Then-Render Contract
+
+Two shapes describe the same component on the two sides of serialization:
+
+```typescript
+interface ComponentInfo<T = unknown, C = Component<T>, ChildType = ComponentChild<T, C>> {
+  componentName: string;
+  options?: T;
+  children?: ChildType[];
+}
+
+type ComponentInfoSerialized<T = unknown> = Omit<ComponentInfo<T>, "children"> & {
+  children?: ChildSerialized[];
+};
+```
+
+`ComponentInfo` is what a builder holds: `children` carry live `Component` instances. `ComponentInfoSerialized` is what the page layout carries: every child has been replaced by its own serialized description.
+
+| Type | Shape |
+| ---- | ----- |
+| `ComponentChild<T, C>` | `{ id: string; component: C; slot?: string; [key: string]: unknown }` |
+| `BaseComponentChild` | `ComponentChild` with `component` fixed to `Component` |
+| `ChildSerialized` | `{ id: string; component: ComponentInfoSerialized; slot?: string; [key: string]: unknown }` |
+| `ComponentInfoPromise<T>` | `MaybePromise<ComponentInfo<T, Component<T>, BaseComponentChild>>` |
+| `ComponentMetadata` | `{ name: string; description?: string; icon?: string }` |
+
+The extra index signature on a child is the escape hatch for per-child props a container needs (a grid column span, a tab label): whatever you pass in the child metadata survives serialization next to `id`, `component` and `slot`.
+
+## Build a Component
+
+`ComponentBuilder<T>` is the class you instantiate with the frontend component name. Every method returns `this`, so calls chain.
+
+```typescript
+import { ComponentBuilder } from "@antelopejs/interface-dms/component";
+
+interface CounterOptions {
+  title: string;
+  fetchUrl: string;
+}
+
+export function Counter(options: CounterOptions) {
+  return new ComponentBuilder<CounterOptions>("acme-counter")
+    .options(options)
+    .meta({ name: options.title, icon: "i-ph-hash" });
+}
+```
+
+Assign the result to a static field of a page class and `@RegisterPage()` picks it up ([Pages and Modules](/docs/interfaces/core/pages-and-modules)).
+
+| Method | Description |
+| ------ | ----------- |
+| `options(opts?)` | Replace the options object. A `watchActions` key on the input is stripped: watches are declared with `watch`/`watchOn` only. |
+| `mergeOptions(opts)` | Shallow-merge into the existing options. Logs a warning and does nothing when no options were set. |
+| `child(id, component, metadata?)` | Append a child with its own positional permission. `metadata` may carry `slot` plus any additional props. A duplicate `id` logs a warning. |
+| `meta(meta)` | Merge into the component metadata (`name`, `description`, `icon`). |
+| `onCreated(callback)` | Run `callback(pageMetadata)` when the component's page registers. |
+| `onFilter(callback)` | Transform the options per caller, from their permission set. |
+| `watch(event, functionId, opts?)` | Declare a watch on this component. |
+| `watchOn(childId, event, functionId, opts?)` | Declare a watch spliced into a child's options at serialization time. |
+| `watchFilter(callback)` | Filter the accumulated watches per caller. |
+| `action(id, definition)` | Declare an `Action` on the component. |
+| `button(id, { permission? })` | Register a named button a quick action can press, with the permission (an action id of this component, or any `Action`) that gates it. A duplicate `id` logs a warning. The table view registers its `customButtons` that carry an `id`. |
+| `navBadge({ count, page? })` | Publish a count as the navigation badge of a page (`NavBadgeSource`): `count(ctx, user)` answers it for the caller on each page visit — a number, drawn neutral, or `{ count, tone }` ([Navigation badges](#navigation-badges)) — and throws to publish nothing for a caller who may not read it. `page` names the page controller the badge goes to, the component's own page by default. A table view's tab declared with `navBadge` publishes through it; a component of your own calls it directly (the DMS's notifications, security and roles pages do). A count of zero shows no badge, and a page's static `MenuOptions.badge` wins. |
+| `before(anchor)` | Place the component above `anchor` (a component key of the target page) when injecting it into another page. |
+| `after(anchor)` | Place it below `anchor`. |
+| `order(value)` | Break ties between components landing at the same spot. Defaults to 0. |
+
+### Navigation badges
+
+`count` answers a number, drawn as a neutral grey pill, or a `NavBadgeCount` that also gives the tone it is drawn in, with the colours of the dashboard's status pills:
+
+```typescript
+interface NavBadgeCount {
+  count: number;
+  tone?: Tone; // from "@antelopejs/interface-dms/base/types/tone"
+}
+
+component.navBadge({
+  count: async (_ctx, user) => {
+    const [overdue, dueSoon] = await countInvoices(user._id);
+    return overdue > 0
+      ? { count: overdue + dueSoon, tone: "error" }
+      : { count: dueSoon, tone: "warning" };
+  },
+});
+```
+
+Pick the tone on the grid the DMS's own notifications follow: `error` for an immediate risk, `warning` for something to check, `primary` for an action available, `success` for good news, `neutral` (or no tone) for plain information; `secondary` and `info` are accepted too. When several components publish a badge for one page, their counts add up and the badge takes the strongest of their tones, in this order: `error`, `warning`, `primary`, `secondary`, `success`, `info`, `neutral`. Each page visit serves the counts as `navBadges`, `{ badge, tone? }` by page full id, next to the page and never in the site layout a browser keeps for minutes.
+
+### Placement
+
+The last three methods only mean something on a component declared inside a `@RegisterPageExtension` class; on a component declared on its own page they are ignored. Together they build a `ComponentPlacement`:
+
+```typescript
+type PlacementSide = "before" | "after" | "end";
+
+interface ComponentPlacement {
+  side: PlacementSide;
+  anchor?: readonly string[];
+  order: number;
+}
+
+const DEFAULT_PLACEMENT: ComponentPlacement = { side: "end", order: 0 };
+```
+
+`anchor` is a component key of the target page: the name of the static field it declared the component under, passed as `.before("table")`, or a dotted path to a nested position, `.before("content.tasks")` — stored as the split path. The target page is never imported, so the key is a string. A component that declares no placement gets `DEFAULT_PLACEMENT` — appended after every component of the target page, with no ordering hint. Read the current value off `component.placement`, which is `undefined` until one of the three methods is called.
+
+Lower `order` comes first, and equal orders fall back to the extension class name and then to declaration order, so the result never depends on module start order. [Pages and Modules](/docs/interfaces/core/pages-and-modules) covers the extension mechanism these describe placement for.
+
+### Children and Slots
+
+```typescript
+import { ComponentBuilder } from "@antelopejs/interface-dms/component";
+import { Placeholder } from "@antelopejs/interface-dms/base";
+
+const panel = new ComponentBuilder<{ title: string }>("acme-panel")
+  .options({ title: "Overview" })
+  .child("header", Placeholder({ label: "Header" }), { slot: "header" })
+  .child("body", Placeholder({ label: "Body" }), { slot: "default", grow: true });
+```
+
+The `grow: true` above is an arbitrary extra prop: it lands on the serialized child alongside `id`, `component` and `slot`.
+
+## The `Component` Class
+
+`ComponentBuilder` extends `Component<T>`, which is also usable directly when you already hold a `ComponentInfo`:
+
+```typescript
+new Component<T>(
+  componentInfo: ComponentInfoPromise<T>,
+  metadata: ComponentMetadata,
+  onPageCreated?: (page: PageMetadata) => void,
+)
+```
+
+`PageMetadata` is the page record described in [Pages and Modules](/docs/interfaces/core/pages-and-modules).
+
+| Member | Description |
+| ------ | ----------- |
+| `componentInfo` | The `ComponentInfo`, possibly a promise. |
+| `metadata` | The `ComponentMetadata`. |
+| `actions` | `Record<string, Action>` of the declared actions. |
+| `getAction(id)` | One action, or `undefined`. |
+| `getButton(id)` | One registered button (`ComponentButton`), or `undefined`. |
+| `resolveButtonPermissionId(permission)` | The permission id a button's `permission` stands for on this component, or `undefined` when it cannot be resolved (callers treat that as refused). |
+| `onPageCreated` | The callback run when the owning page registers. |
+| `onFilterCallback` | The per-caller options filter, when one is installed. |
+| `placement` | The `ComponentPlacement`, or `undefined` when none was declared. |
+| `serialize()` | `Promise<ComponentInfoSerialized<T>>` — awaits the component info and serializes every child. |
+| `serializeSync()` | The same, for a component whose info is not a promise. |
+
+Both serialize methods normalize `children` to `[]` when the component has none.
+
+Because `componentInfo` may be a promise, a builder can resolve data at registration time. Use `serialize()` unless you know the info is synchronous.
+
+## Actions
+
+An action is a named capability of a component that carries its own permission — "add a row", "export", "restore". Declare one on the builder:
+
+```typescript
+import { ComponentBuilder } from "@antelopejs/interface-dms/component";
+
+const table = new ComponentBuilder<{ fetchUrl: string }>("acme-table")
+  .options({ fetchUrl: "/api/things" })
+  .action("export", {
+    title: "$acme.table.action_export",
+    icon: "i-ph-download-simple",
+    description: "$acme.table.action_export_description",
+  });
+
+const exportAction = table.getAction("export");
+```
+
+`ActionDefinition` carries `title` (required), and optional `icon`, `description` and `defaultGranted`.
+
+An `Action` instance exposes:
+
+| Member | Description |
+| ------ | ----------- |
+| `id` | The action id, as passed to `action()`. |
+| `definition` | The `ActionDefinition`. |
+| `permissionId` | The component's permission id with `.<id>` appended, or `undefined` while the component has no permission id yet. |
+| `toPermission()` | A `Permission` built from the definition, or `undefined` when `permissionId` is. |
+
+The component's permission id only exists once the owning page has registered, so read `permissionId` from `onCreated` or later — not while the builder is still being assembled.
+
+An `Action` is accepted anywhere a permission is: as the `permission` option of a page ([Pages and Modules](/docs/interfaces/core/pages-and-modules)) and as the target of `AuthUserWithPermission` ([Permissions](/docs/interfaces/core/permissions)).
+
+`getPermissionIdRef` is the seam that lets `Action` resolve its component's permission id without importing the page module: it is an object with a single `get(component)` method, replaced by `dms/page` when that module loads. Consumers read `permissionId`; there is no reason to call or reassign the ref.
+
+## Per-Caller Filtering
+
+`onFilter` rewrites a component's options for the caller who requested the page layout. It runs during layout resolution, after the component itself passed its permission check.
+
+```typescript
+import { ComponentBuilder } from "@antelopejs/interface-dms/component";
+
+interface ListOptions {
+  fetchUrl: string;
+  allowBulkDelete: boolean;
+}
+
+const list = new ComponentBuilder<ListOptions>("acme-list")
+  .options({ fetchUrl: "/api/things", allowBulkDelete: true })
+  .onFilter((permissions, options) => ({
+    ...options,
+    allowBulkDelete: permissions.has("things.delete"),
+  }));
+```
+
+The callback receives `(permissions: Set<string>, options: T, permissionId: string, context: ComponentFilterContext)` and returns the options — synchronously or as a promise. The third argument is the component position's own permission id, including the full parent path for a child, so a filter can derive the ids of the actions it needs to test. The fourth is the request the layout is built for: its `tenantId`, its `user` (undefined when unauthenticated), and `query`, the page URL's query when the request carries one (what a header button's `availability` reads; check its values like any input).
+
+## Watches
+
+A watch binds an event on a component to a registered function. The backend only describes the binding.
+
+```typescript
+watch<F extends string>(event: string, functionId: F, opts?: WatchOptions<F>): this
+watchOn<F extends string>(childId: string, event: string, functionId: F, opts?: WatchOptions<F>): this
+```
+
+| `WatchOptions` field | Type | Description |
+| -------------------- | ---- | ----------- |
+| `params` | `WatchFunctionParams<F>` | Arguments handed to the function. Typed per `functionId` when the function declares its parameter map. |
+| `onParam` | `WatchActionCondition \| WatchActionCondition[]` | Conditions on the event payload, each `{ key, value }`. |
+| `requirePermission` | `string` | Permission id the caller must hold; the watch is dropped from the layout otherwise. |
+
+`watch` targets the component itself; `watchOn(childId, ...)` targets a child added with `child()` and is spliced into that child's serialized options. Calling `watchOn` with an unknown child id logs a warning.
+
+```typescript
+import {
+  Form,
+  FormEvents,
+  FormFunctions,
+} from "@antelopejs/interface-dms/base/form";
+
+const form = Form({ title: "Profile", fields: [] }).watch(
+  FormEvents.FIELD_CHANGE,
+  FormFunctions.SET_FIELD_DISABLED,
+  {
+    params: { targetField: "adminNotes", setDisabled: true },
+    onParam: [
+      { key: "fieldId", value: "isOwner" },
+      { key: "value", value: false },
+    ],
+    requirePermission: "pages.crm.contacts.form",
+  },
+);
+```
+
+`watchFilter(callback)` narrows the watch list per caller: it receives `(permissions, watches, permissionId)` and returns the watches to keep. It runs right after `onFilter` in the same filtering pass, and the `requirePermission` narrowing is applied to whatever it returns.
+
+## Component Events
+
+`ComponentEvents` holds the lifecycle event names:
+
+| Constant | Value |
+| -------- | ----- |
+| `ComponentEvents.LOAD` | `"DmsComponent.Load"` |
+| `ComponentEvents.UNLOAD` | `"DmsComponent.Unload"` |
+
+Use them as the `event` argument of `watch` or `watchOn`, or as the event name in a page setup function's `on()` subscription ([Pages and Modules](/docs/interfaces/core/pages-and-modules)).
+
+## `RegisterComponentSlot`
+
+`RegisterComponentSlot(slotId: string, resolver: ComponentSlotResolver): () => void`, from `@antelopejs/interface-dms/component-slots`, claims a component slot. The resolver receives the options of each component declaring that `slotId`, once per layout request, and returns the replacement options. Returning the input unchanged contributes nothing.
+
+`SlotOptions` is `Record<string, unknown>`; `ComponentSlotResolver` is `(options: SlotOptions) => MaybePromise<SlotOptions>`. The latest claim for an id wins. The returned release function removes the claim only if that resolver still owns it, so releasing an older claim does not remove a newer one.
+
+Use the returned function when the claiming module stops. [TableView form slots](/docs/components/tables#tableview-options) show how a controller exposes a slot; the controller still owns validation and persistence of contributed fields.
+
+## Next Steps
+
+[Permissions](/docs/interfaces/core/permissions) covers the ids these components and actions register, and the guards that check them.

package/docs/1.core/4.permissions.md

@@ -0,0 +1,279 @@
+---
+title: "Permissions"
+description: "Permission ids are hierarchical strings built from the page tree: a page's `fullId`, then every component id in the position's path, then the action id when present."
+---
+
+# Permissions
+
+## Overview
+
+Permission ids are hierarchical strings built from the page tree: a page's `fullId`, then every component id in the position's path, then the action id when present. A role holds a flat list of granted ids; a platform owner holds the wildcard `*`. Two functions answer "what can this user do" — `GetUserPermissions` returns the base set from roles, `GetEffectiveUserPermissions` runs that set through the registered resolvers. Authorization surfaces use the effective set.
+
+The surface spans three subpaths:
+
+| Subpath | Contains |
+| ------- | -------- |
+| `@antelopejs/interface-dms/permissions` | The registry, the module-scope marks, and the permission computation |
+| `@antelopejs/interface-dms/permissions-resolver` | Registering and running resolvers |
+| `@antelopejs/interface-dms/guards` | Route guards |
+
+## Register a Permission
+
+Pages, components and actions register their own permissions when the page registers ([Pages and Modules](/docs/interfaces/core/pages-and-modules)). Register a standalone one when a capability has no component behind it:
+
+```typescript
+import { RegisterPermission } from "@antelopejs/interface-dms/permissions";
+
+RegisterPermission("reports.export", {
+  id: "reports.export",
+  title: "$my_app.perm.reports_export",
+  icon: "i-ph-download",
+  description: "$my_app.perm.reports_export_description",
+  dependencies: ["reports.view"],
+  defaultGranted: false,
+});
+```
+
+### `Permission`
+
+| Field | Type | Description |
+| ----- | ---- | ----------- |
+| `id` | `string` | The permission id. Required. |
+| `title` | `string` | Label shown in the roles editor. Required. |
+| `icon` | `string` | Icon name. |
+| `description` | `string` | Longer description. |
+| `dependencies` | `string[]` | Permission ids this one needs to be of any use. The roles editor grants them with it (and takes it away with them), and a role is saved with them and the ids they sit under. `HasPermission` requires them, like the ids above: a registered dependency the set lacks makes the permission count for nothing. An unregistered one counts as held. |
+| `defaultGranted` | `boolean` | Treat the permission as held by every caller, without a role grant. |
+
+`RegisterPermission(id, permission)` takes the id twice — once as the registry key, once inside the record — so keep them equal.
+
+`UnregisterPermission(id)` drops a permission from the grantable tree again. It exists for registrations undone while the process keeps running — a page extension whose module stopped, for instance. A permission left behind after its surface is gone stays offered in the roles editor and stays grantable, so anything that registers a permission conditionally should unregister it on the same condition.
+
+## Read the Registry
+
+```typescript
+import {
+  GetPermission,
+  GetPermissions,
+} from "@antelopejs/interface-dms/permissions";
+
+const permission = await GetPermission("reports.export");
+const tree = await GetPermissions();
+```
+
+`GetPermission(id)` resolves to the `Permission` or `undefined`. `GetPermissions()` resolves to a `Record<string, PermissionTree>` keyed by the first id segment, where
+
+```typescript
+type PermissionTree = {
+  data?: Permission;
+  children: Record<string, PermissionTree>;
+};
+```
+
+Each level keys its children by the next dot-separated segment. `data` is absent for a level that exists only to hold children.
+
+Both are interface functions and return promises even though the registry is in-process.
+
+## Compute a User's Permissions
+
+```typescript
+import {
+  GetEffectiveUserPermissions,
+  GetUserPermissions,
+  HasPermission,
+} from "@antelopejs/interface-dms/permissions";
+```
+
+| Function | Signature |
+| -------- | --------- |
+| `GetUserPermissions` | `(user: { owner?: boolean }, roleIds: string[], roleModel: RoleModel) => Promise<Set<string>>` |
+| `GetEffectiveUserPermissions` | `(user: { _id: string; owner?: boolean }, tenantId: string, roleIds: string[], roleModel: RoleModel) => Promise<Set<string>>` |
+| `HasPermission` | `(permissions: Set<string>, permissionId: string) => Promise<boolean>` |
+
+`GetUserPermissions` returns `Set(["*"])` for a user with `owner: true`, an empty set when `roleIds` is empty, and otherwise the union of the `permissions` arrays of the roles it loads through `roleModel`. This is the **base** set: it does not account for resolvers, so do not authorize against it.
+
+`GetEffectiveUserPermissions` composes that base set with `ApplyPermissionsResolvers` and is the set every authorization surface uses.
+
+`HasPermission` resolves in this order:
+
+1. `true` when the set holds the wildcard `*`.
+2. `false` when the id is module-scoped.
+3. `true` when the registered permission carries `defaultGranted`.
+4. `false` when the set does not hold the id.
+5. `true` when the set also holds every id the permission sits under (`pages.sales` and `pages` for `pages.sales.orders`), `false` otherwise. An id above it that is not a registered permission, or that carries `defaultGranted`, counts as held.
+
+The wildcard is checked first, so a platform owner passes even for a module-scoped id. Step 5 makes a grant worth nothing without its parents: a table's `delete` action is refused to a role that holds neither the table nor its page. The roles editor and the role routes store a grant with every id above it, so only a role saved before they did, or a set a resolver reshaped, can miss one.
+
+```typescript
+import { GetModel } from "@antelopejs/interface-database-decorators";
+import {
+  RoleModel,
+  TenantMemberModel,
+} from "@antelopejs/interface-dms/db";
+import {
+  GetEffectiveUserPermissions,
+  HasPermission,
+} from "@antelopejs/interface-dms/permissions";
+import type { User } from "@antelopejs/interface-dms/auth/db";
+
+async function canExport(user: User, tenantId: string): Promise<boolean> {
+  const member = await GetModel(TenantMemberModel, tenantId).getByUser(user._id);
+  const permissions = await GetEffectiveUserPermissions(
+    user,
+    tenantId,
+    member?.roleIds ?? [],
+    GetModel(RoleModel, tenantId),
+  );
+  return HasPermission(permissions, "reports.export");
+}
+```
+
+`RoleModel` and `TenantMemberModel` come from [Tenancy](/docs/interfaces/core/tenancy).
+
+## Module-Scoped Permissions
+
+Permissions belonging to a module page or category are never added to the grantable permission tree, and a role grant on such an id never grants anything. They are marked instead:
+
+```typescript
+import {
+  IsModuleScopedPermission,
+  MarkModuleScopedPermission,
+  UnmarkModuleScopedPermission,
+} from "@antelopejs/interface-dms/permissions";
+
+MarkModuleScopedPermission("modules.automation.builder");
+IsModuleScopedPermission("modules.automation.builder.canvas.add"); // true
+UnmarkModuleScopedPermission("modules.automation.builder");
+```
+
+`IsModuleScopedPermission(id)` walks the id upward one dot-separated segment at a time, so marking a page id also covers every component and action id derived from it. `UnmarkModuleScopedPermission(id)` removes the mark for that exact id only.
+
+Page registration calls `MarkModuleScopedPermission` for you whenever `isInsideModule` holds ([Pages and Modules](/docs/interfaces/core/pages-and-modules)); call it directly only for ids you build outside that path.
+
+## Reshape the Effective Set
+
+A permissions resolver receives a caller's current permission set for a tenant and returns the set to use instead.
+
+```typescript
+import { RegisterPermissionsResolver } from "@antelopejs/interface-dms/permissions-resolver";
+
+export async function construct(): Promise<void> {
+  RegisterPermissionsResolver({
+    id: "my_app.plan-limits",
+    order: 100,
+    resolver: async (userId, tenantId, currentPermissions) => {
+      const allowed = await loadPlanPermissions(tenantId);
+      return new Set([...currentPermissions].filter((p) => allowed.has(p)));
+    },
+  });
+}
+```
+
+```typescript
+type PermissionsResolverFn = (
+  userId: string,
+  tenantId: string,
+  currentPermissions: Set<string>,
+) => Promise<Set<string>> | Set<string>;
+```
+
+`PermissionsResolverInfo` carries `id`, `resolver` and `order`.
+
+Semantics the interface guarantees:
+
+- Resolvers run in ascending `order`, each seeing the previous one's result; equal `order` runs in registration order, which is module load order.
+- Registering an id twice replaces the earlier resolver rather than adding a second one.
+- A resolver that throws aborts the computation and fails the request. It is never skipped.
+- The registration is removed when the registering module unloads; there is no unregister call.
+- Register in `construct()` so the resolver is active before the API serves requests.
+
+`ApplyPermissionsResolvers(userId, tenantId, basePermissions)` runs the pipeline and resolves to the effective set. Prefer `GetEffectiveUserPermissions`, which computes the base set for you and calls it.
+
+A resolver shapes a permission set. It cannot deny a surface that consults no permission set, and it cannot revoke a `defaultGranted` permission, which `HasPermission` grants after the resolvers ran. To cut a tenant off from the product entirely, register a tenant access gate instead ([Tenancy](/docs/interfaces/core/tenancy)).
+
+## Guard a Route
+
+Three decorators from `@antelopejs/interface-dms/guards` gate a route on the caller.
+
+### `AuthUserWithPermission`
+
+`AuthUserWithPermission(target, options?)` requires an authenticated user holding the exact registered permission of `target`, which is a `Component`, a page controller class, or an `Action` ([Components](/docs/interfaces/core/components)). A child component resolves to its full positional path. `options` is the same `TenantGuardOptions` the two tenant guards take, described below.
+
+```typescript
+import { Controller, Get } from "@antelopejs/interface-api";
+import { AuthUserWithPermission } from "@antelopejs/interface-dms/guards";
+import type { User } from "@antelopejs/interface-dms/auth/db";
+import { InvoicesPage } from "../pages/invoices";
+
+export class InvoiceReportController extends Controller("/api/invoices") {
+  @Get("/summary")
+  async summary(@AuthUserWithPermission(InvoicesPage) _user: User) {
+    // reachable only by a caller holding the InvoicesPage permission
+  }
+}
+```
+
+The guard resolves the target's permission id, loads the caller's membership in the tenant carried by the token, computes their effective permissions and calls `HasPermission`. It answers `403` when the permission is missing, and also when the token carries no tenant claim — a permission can only be granted inside a tenant. A target that carries no permission id yet passes the authentication check only. The tenant access gate runs whenever the token carries a tenant claim, including for a target with no permission id, and it runs before the permission is resolved — unless `options.bypassTenantAccessGate` is set, which skips the gate while leaving the permission check in place.
+
+### `AuthTenantOwner` and `AuthTenantMember`
+
+Both resolve the tenant from the request's JWT `tenantId` claim and check the caller's membership in it. `AuthTenantOwner` additionally requires `isTenantOwner`. Each answers `401` without a token and `403` when the requirement is not met, and each runs the tenant access gate before returning the user.
+
+```typescript
+import { Controller, Post } from "@antelopejs/interface-api";
+import {
+  AuthTenantMember,
+  AuthTenantOwner,
+} from "@antelopejs/interface-dms/guards";
+import type { User } from "@antelopejs/interface-dms/auth/db";
+
+export class BillingController extends Controller("/api/billing") {
+  @Post("/portal-session")
+  async portalSession(
+    @AuthTenantOwner({ bypassTenantAccessGate: true }) user: User,
+  ) {
+    // stays reachable for a tenant a gate denies
+  }
+
+  @Post("/usage")
+  async usage(@AuthTenantMember() user: User) {
+    // any member of the request's tenant
+  }
+}
+```
+
+`TenantGuardOptions` has one field, and all three guards accept it:
+
+| Option | Type | Description |
+| ------ | ---- | ----------- |
+| `bypassTenantAccessGate` | `boolean` | Skip the tenant access gate for this route. Reserved for routes that must stay reachable when a gate denies the tenant. |
+
+The opt-out has two mirrors elsewhere, for the surfaces a route guard does not cover: `MenuOptions.bypassTenantAccessGate` keeps a page and its menu entry reachable ([Pages and Modules](/docs/interfaces/core/pages-and-modules)), and `TableViewOptions.bypassTenantAccessGate` covers a table view's data routes, which belong to a controller rather than to any one page.
+
+A denial from a gate surfaces as a `403` whose body is the gate's `code` ([Tenancy](/docs/interfaces/core/tenancy)).
+
+### Guards as Properties
+
+All three are parameter *and* property decorators. Declared as a class property, a guard gates every route on that controller:
+
+```typescript
+import { Controller, Post } from "@antelopejs/interface-api";
+import { AuthTenantMember } from "@antelopejs/interface-dms/guards";
+import type { User } from "@antelopejs/interface-dms/auth/db";
+
+export class FilesController extends Controller("/api/files") {
+  @AuthTenantMember()
+  declare user: User;
+
+  @Post("/presign")
+  async presign() {
+    // the guard already ran, whether or not this handler reads `this.user`
+  }
+}
+```
+
+A property provider runs on every request to a route of the controller, independently of whether the handler body reads the property. That is what makes the property form a guard rather than a convenience: removing the read does not remove the check.
+
+## Next Steps
+
+[Tenancy](/docs/interfaces/core/tenancy) covers the tenant the guards resolve, the roles the permission sets come from, and the access gates.