create-qpq-app 0.1.24 → 0.1.26

package/template/docusaurus/docs/config/features/event-doc-routes.md

@@ -63,6 +63,7 @@ The single `options` argument is an `EventDocRoutesOptions`:
 | `onPublish` | `string` | – | Name of a registered inline function. When set, every successful append of a Publish event invokes it with `{ docId, event, summary, state, previousState }` — the FOLDED document as of the publish event and as of the event before it (latest-shaped, snapshot-seeded, so hook cost tracks the burst since the last snapshot, never the log) — after the event is durably written. This is the seam for syncing a folded document into a materialized read model: use `state`, never re-fold. Errors propagate to the caller: the event has landed but the side effect did not, so the caller learns the read model may be stale. |
 | `onAppend` | `string` | – | Name of a registered inline function. When set, EVERY successful append (domain events and lifecycle events alike) invokes it with `{ docId, event, summary, state, previousState }` — the FOLDED document as of the event and as of its predecessor (latest-shaped, snapshot-seeded) — after the event is durably written. This is the seam for reacting to any mutation (e.g. broadcasting the doc's fresh fold, or diffing `previousState` vs `state` to detect a transition). Runs after `onPublish` when both fire on the same Publish event. Errors propagate to the caller: the event has landed but the side effect did not. |
 | `scopeResolver` | `string` | – | Name of a registered inline function. When set, every route invokes it with `{ event }` before running; a non-null result becomes the ambient storage scope for the whole request, transparently partitioning the collection's stores and assets (e.g. per-tenant). Null means unscoped. Omit for collections that never partition. |
+| `authorise` | `string` | – | Name of a registered inline function. When set, every route invokes it with `{ event, storeName, action }` inside the resolved scope, before the handler; it throws to refuse. `action` is `read` (list, get, listEvents, render, references, listAssets, getAsset), `create`, `write` (appendEvent, createAsset) or `delete` (remove). [defineTenantedEventDoc](./tenanted-event-doc.md) sets this to the tenant authoriser, which requires the caller to hold `eventDoc:<storeName>:<action>`. |
 | `excludeRoutes` | `EventDocRouteName[]` | `[]` | Route names to leave unmounted (`'list' \| 'get' \| 'listEvents' \| 'render' \| 'references' \| 'create' \| 'appendEvent' \| 'createAsset' \| 'getAsset' \| 'listAssets' \| 'remove'`). For a collection that must own one of these itself instead of using the stock behavior — e.g. a `create` that must also perform some side effect the stock controller doesn't know about. |
 
 Append-time validation, rendering, references, and snapshotting are no longer per-route options: they come from the collection's registered `EventDocFunctions` object (`collectReferences`, `render`, `foldSnapshotViews`, and the doc type's own fold-gate `validators`), addressed by `eventDocFunctionsName(storeName, type)`. Register it with [defineDynamicFunctions](../core/dynamic-functions.md) directly (a multi-type store calling `defineEventDocRoutes` per type) or let [defineEventDoc](./event-doc.md) do it for the single-type case.

package/template/docusaurus/docs/config/features/event-doc.md

@@ -25,7 +25,7 @@ export default [
 
 ## Registering a collection's functions
 
-`functions` is an `EventDocFunctions` object: `{ storeName, type, foldSnapshotViews, collectReferences, render? }`. The object `createEventDocDefinition` returns — given `storeName`/`type` in its config — satisfies this shape directly, so a collection with no service-only render can register its definition verbatim. A collection that needs a render step only service code can perform (resolving linked docs, reading blob-drive assets) layers it on with `extendEventDocFunctions(definition, { render })`, which returns a new object and never mutates the definition itself.
+`functions` is an `EventDocFunctions` object: `{ storeName, type, foldSnapshotViews, foldDocumentState, collectReferences, collectReferencesFromState, validateEvent, render? }`. The object `createEventDocDefinition` returns — given `storeName`/`type` in its config — satisfies this shape directly, so a collection with no service-only render can register its definition verbatim. A collection that needs a render step only service code can perform (resolving linked docs, reading blob-drive assets) layers it on with `extendEventDocFunctions(definition, { render })`, which returns a new object and never mutates the definition itself.
 
 `runtime` is a [`QpqFunctionRuntime`](../core/dynamic-functions.md#runtime--qpqfunctionruntime-required) path to that SAME export — the dynamic-functions pattern: identity is read off the object here at config time, behaviour is loaded from the path by the processors at request time. Both must point at the exact object being registered, or the registration and the runtime will disagree about what the collection can do.
 
@@ -59,6 +59,7 @@ The collection's callable surface, read for its identity (`storeName`, `type`) a
 | `foldDocumentState` | `(events, seedState?) => unknown` | yes | The document view at one point, LATEST-shaped, resumable from a stored snapshot's era-pinned document state. The read side's fold: render, references, as-of reads, and the append hooks' state derivation all go through it. |
 | `collectReferences` | `(events) => EventDocLink[]` | yes | The `EventDocLink`s this doc's whole HISTORY depends on; `[]` for a leaf doc type. Invoked by the transfer manifest walk (it exports the whole history). |
 | `collectReferencesFromState` | `(state) => EventDocLink[]` | yes | The `EventDocLink`s the CURRENT state depends on; `[]` for a leaf doc type. Invoked by the references route against a snapshot-seeded folded state. |
+| `validateEvent` | `(event, state) => Nullable<string> \| AskResponse<Nullable<string>>` | yes | The append pre-write gate: checked against the state the event will land on, before the write (see [askEventDocEventAppend](../../actions/features/event-doc/ask-event-doc-event-append.md)). Return a rejection reason string to refuse the append, `null` to allow it. A collection with no domain rules can pass `() => null`. |
 | `render` | `(input: EventDocRenderInput) => EventDocRenderResult \| AskResponse<EventDocRenderResult>` | no | Render the resolved, already-folded document state (`input.state`, resolved snapshot-seeded by the route). Omit and `GET {basePath}/{id}/render` 404s as "no renderer configured". Plain function or story — the dynamic-functions processor runs either. |
 
 ### `runtime` — `QpqFunctionRuntime` (required)

package/template/docusaurus/docs/config/features/tenant-stores.md

@@ -47,7 +47,7 @@ The record store holds `TenantRecord` rows, derived from the tenant event doc on
 
 ```typescript
 type TenantRecord = {
-  tenantId: string;
+  tenantId: TenantId;
   name: string;
   brandColors?: Record<string, string>;
   logoUrl?: string;
@@ -62,21 +62,26 @@ The membership store holds `TenantMembership` rows, one per `(user, tenant)` lin
 
 ```typescript
 type TenantMembership = {
-  tenantId: string;
+  tenantId: TenantId;
   userId: string;
-  role: TenantMembershipRole;
+  roles: string[];
+  grants: TenantPermissionGrant[];
   disabled?: boolean;
   joinedAt: QpqIsoDateTime;
   addedByUserId: string;
+  rolesUpdatedAt: QpqIsoDateTime;
+  rolesUpdatedByUserId: string;
 };
 ```
 
-`role` is `TenantMembershipRole.owner` or `TenantMembershipRole.member` — see [defineTenant](./tenant.md#routes-mounted) for who can change it. A `disabled` member fails the membership check everywhere (scope resolver, WebSocket scope, tenant routes) but still appears in the member list, so an owner can re-enable them.
+`TenantId` is a branded string (`Brand<string, 'TenantId'>`): ids the system mints or stores are branded with `toTenantId`, and ids arriving on a request (the tenant header, a path param, a WebSocket claim) go through `askTenantIdParse`, which answers `BadRequest` for anything that is not a valid scope segment. Every tenant story takes a `TenantId`, so a user id or a scope string cannot be passed where a tenant id belongs.
+
+`roles` are codes from the catalog passed to [defineTenant](./tenant.md) (`roles.catalog`), expanded to permissions at read time, so a catalog change takes effect on every row at once and a retired code grants nothing. `grants` are direct `{ permission, selector }` entries; a selector is `{ kind: 'all' }`, `{ kind: 'ids', ids }` or `{ kind: 'resourceKinds', kinds }`, and is the only way a permission is narrowed to specific resources. A `disabled` member fails the membership check everywhere (scope resolver, WebSocket scope, tenant routes) and holds no permissions, but still appears in the member list so an admin can re-enable them.
 
 ## Notes
 
 - The tenant event-doc collection is the source of truth; the `tenantRecords` table is a read model. The sync between them is the `askTenantOnPublish` inline function, which [defineTenant](./tenant.md) registers and wires into the collection's `onPublish` hook.
-- Creating a tenant writes a `TenantMembership` row with `role: owner` for the caller, so the creator becomes the tenant's first member. The same table serves both the access check (`userId`+`tenantId` keyed get) and, via its `tenantId`/`userId` GSI, a tenant's member list — there is no separate reverse index to keep in lock-step.
+- Creating a tenant writes a `TenantMembership` row with `roles: ['tenantAdmin']` for the caller, so the creator becomes the tenant's first member and its first admin. The same table serves both the access check (`userId`+`tenantId` keyed get) and, via its `tenantId`/`userId` GSI, a tenant's member list — there is no separate reverse index to keep in lock-step.
 - Services that do **not** own these stores still call [defineTenant](./tenant.md) (with the same `owner`) to get the scope resolver and a cross-module reference to the membership table — they never call `defineTenantStores` themselves.
 
 ## Related

package/template/docusaurus/docs/config/features/tenant.md

@@ -7,13 +7,13 @@ description: Wire up org/tenant support across every service in one call — the
 
 Wires up **everything for org/tenant support**, declared identically in every service that needs it. You always pass the same `owner`; what actually materializes depends on whether the current module is that owner. It returns a `QPQConfig` (an array of config settings) composed of:
 
-- The scope-resolver and connection-scope-resolver [inline functions](../core/inline-function.md) (`TENANT_SCOPE_RESOLVER_FN`, `TENANT_CONNECTION_SCOPE_RESOLVER_FN`) — registered in **every** service, so each can tenant-scope its own collections and WebSocket connections. The tenant collection itself is an ordinary tenanted collection too: a tenant doc lives in whatever scope the request that created it ran under (the creator's personal partition, or the active tenant when an org creates a sub-tenant), and every tenant route resolves its scope with the same resolver. The cross-scope registry surface is the membership table plus the materialized `TenantRecord` store below, both unscoped.
+- The scope-resolver and connection-scope-resolver [inline functions](../core/inline-function.md) (`TENANT_SCOPE_RESOLVER_FN`, `TENANT_CONNECTION_SCOPE_RESOLVER_FN`) — registered in **every** service, so each can tenant-scope its own collections and WebSocket connections. The tenant collection itself is an ordinary tenanted collection too, with one rule of its own: a tenant doc lives under its own `TENANT#<id>` scope from creation, so it is edited from inside the tenant (header, membership, and the `eventDoc:tenants:*` permission) and nobody owns it. The creator leaving changes nothing. The cross-scope registry surface is the membership table plus the materialized `TenantRecord` store below, both unscoped.
 - The `tenantMemberships` membership table ([key-value store](../core/key-value-store.md)) — declared with `owner` everywhere, so non-owner services get a cross-module reference to the owner's table instead of their own copy.
 - Everything else, gated to the owner's deploy only via [defineServiceSettings](../core/service-settings.md):
   - The tenant stores ([defineTenantStores](./tenant-stores.md)): the tenant event-doc collection plus the materialized record table.
   - The publish-to-record-store sync: an inline function (`askTenantOnPublish`) that runs on every published tenant document, re-folds the full event log, and upserts the resulting `TenantRecord`. It is a plain upsert of the fold result, so publish retries and repair re-runs are safe.
   - The stock event-doc CRUD at `{basePath}` ([defineEventDocRoutes](./event-doc-routes.md) for the `tenants` store, `tenant` type, with the publish sync wired in as `onPublish`, and `create` excluded — see below).
-  - The membership-gated routes at `{myTenantsBasePath}`: list my tenants, create, get record, get logo, and manage members (list, add, remove).
+  - The membership-gated routes at `{myTenantsBasePath}`: list my tenants, create, get record, get logo, my membership, the role catalog, and manage members (list, add, remove, set roles).
 
 - **On AWS:** on the owner's deploy, this deploys everything [defineTenantStores](./tenant-stores.md) deploys (two DynamoDB tables and an S3 bucket) plus the `tenantMemberships` table and the API Gateway routes and Lambda handlers from [defineEventDocRoutes](./event-doc-routes.md) and the tenant routes below. On every other service's deploy, only the `tenantMemberships` reference resolves (no new table); the inline functions deploy no infrastructure of their own anywhere.
 
@@ -38,16 +38,39 @@ All paths are prefixed with the version segment `/v{version}` (default `/v1`) an
 
 | Method | Path | Purpose |
 | --- | --- | --- |
-| `GET` | `{myTenantsBasePath}` | The authenticated user's tenants, as `EventDocSummary` rows. Runs under the request's scope: memberships homed in the caller's current partition hydrate live (drafts included); the rest hydrate from the published `TenantRecord` registry. |
-| `POST` | `{myTenantsBasePath}` | Create a tenant (body `{ name }`); the caller becomes its first member. Runs under the request's scope, so the new tenant doc lands in the caller's current partition. This is the only way to create a tenant — the stock `create` route is excluded at `{basePath}` so a new tenant is never made without also linking its creator. |
+| `GET` | `{myTenantsBasePath}` | The authenticated user's tenants, as `EventDocSummary` rows: each enabled membership's live summary, read from that tenant's own scope (drafts included, soft-deleted excluded). |
+| `POST` | `{myTenantsBasePath}` | Create a tenant (body `{ name }`); the caller becomes its first member with the built-in `tenantAdmin` role. The doc is written under the new tenant's own scope, whatever scope the request ran under. This is the only way to create a tenant — the stock `create` route is excluded at `{basePath}` so a new tenant is never made without also linking its creator. Any authenticated user may create one; nothing deletes one. |
 | `GET` | `{myTenantsBasePath}/{id}` | One tenant's materialized record (the fast path). Members only: non-members get `Forbidden`, a missing record gets `NotFound`. |
-| `GET` | `{myTenantsBasePath}/{id}/logo` | A presigned, short-lived URL for the tenant's logo blob. Members only: non-members get `Forbidden`; a missing record or a tenant with no logo gets `NotFound`. Presigned in the scope the tenant doc was published under (recorded on the `TenantRecord`), not the reader's own scope, since the logo asset lives in the doc's home partition. |
-| `GET` | `{myTenantsBasePath}/{id}/members` | The tenant's members as `TenantMember[]` (`userId`, `email`, `name`, hydrated from the user directory). Members only: non-members get `Forbidden`. |
-| `POST` | `{myTenantsBasePath}/{id}/members` | Add an existing user directory account to the tenant (body `{ email }`). Owner only: non-owners get `Forbidden`. No invite flow — an email with no matching account gets `NotFound`. Idempotent: re-adding a member is a no-op that still returns the `TenantMember`. |
-| `PATCH` | `{myTenantsBasePath}/{id}/members/{userId}` | Change a member's `role` and/or `disabled` flag (body a `TenantMemberUpdateRequest`, either field optional — omitted fields keep their current value). Owner only: non-owners get `Forbidden`; an unknown `userId` gets `NotFound`. A caller can never demote or disable themself: `BadRequest`. |
-| `DELETE` | `{myTenantsBasePath}/{id}/members/{userId}` | Remove a member from the tenant. Owner only: non-owners get `Forbidden`. The owner can never be removed, even by themself: `BadRequest`. |
+| `GET` | `{myTenantsBasePath}/{id}/logo` | A presigned, short-lived URL for the tenant's logo blob. Members only: non-members get `Forbidden`; a missing record or a tenant with no logo gets `NotFound`. Presigned in the tenant's own scope, not the reader's, since that is where the logo asset lives. |
+| `GET` | `{myTenantsBasePath}/{id}/membership` | The caller's own membership row as a `TenantCallerMembership` (the row plus the full list of permission keys it expands to, for a UI to build its nav from). Enabled members only: a missing or disabled membership gets `Forbidden`. |
+| `GET` | `{myTenantsBasePath}/{id}/roles` | The tenant's role catalog as `TenantRoleOption[]` (`{ code, name }`), for a role picker. Members only: non-members get `Forbidden`. |
+| `GET` | `{myTenantsBasePath}/{id}/members` | A page of the tenant's members as `TenantMember[]` (`userId`, `email`, `name`, `roles`, `disabled`, hydrated from the user directory). Members only: non-members get `Forbidden`. Query `limit` and `nextPageKey` page through. |
+| `POST` | `{myTenantsBasePath}/{id}/members` | Add an existing user directory account to the tenant with no roles (body `{ email }`). Needs `tenant:members:manage`: without it, `Forbidden`. No invite flow — an email with no matching account gets `NotFound`. Idempotent: re-adding a member is a no-op that still returns the `TenantMember`. |
+| `PATCH` | `{myTenantsBasePath}/{id}/members/{userId}` | Change a member's `disabled` flag (body `{ disabled? }`). Needs `tenant:members:manage`: without it, `Forbidden`; an unknown `userId` gets `NotFound`. A caller can never disable themself, and nobody may disable the last member who can assign roles: `BadRequest`. |
+| `PUT` | `{myTenantsBasePath}/{id}/members/{userId}/roles` | Replace a member's `roles` (catalog codes) and `grants` (direct permission grants) wholesale (body `{ roles, grants }`). Needs `tenant:roles:assign`: without it, `Forbidden`; an unknown role code or a change that would leave nobody able to assign roles gets `BadRequest`; an unknown `userId` gets `NotFound`. |
+| `DELETE` | `{myTenantsBasePath}/{id}/members/{userId}` | Remove a member from the tenant. Needs `tenant:members:manage`, except that a caller may always remove themself (leave). Either way, the last member who can assign roles is never removed. |
 
-On top of these, the stock event-doc route set (get, append, list events, assets, remove, and so on — everything but `create`) is mounted at `{basePath}`, named after the model type like any other collection; see [defineEventDocRoutes](./event-doc-routes.md#routes-mounted) for the list. `{basePath}` and `{myTenantsBasePath}` must be distinct and neither may be a path segment under the other: `{basePath}/{id}` matches any single segment, so a literal sibling path would be ambiguous with a tenant whose id happens to match it.
+On top of these, the stock event-doc route set (get, append, list events, assets, remove, and so on — everything but `create`) is mounted at `{basePath}`, named after the model type like any other collection; see [defineEventDocRoutes](./event-doc-routes.md#routes-mounted) for the list. Inside a tenant those routes require `eventDoc:tenants:<action>`, which the built-in `tenantAdmin` role holds, so editing branding is an admin act. `{basePath}` and `{myTenantsBasePath}` must be distinct and neither may be a path segment under the other: `{basePath}/{id}` matches any single segment, so a literal sibling path would be ambiguous with a tenant whose id happens to match it.
+
+## Permissioned routes
+
+`createTenantedRouteDefinition` stamps out a route family whose handlers run inside the request's typed scope after the membership gate. Its config takes a `permission` on top of the usual `knownErrors` and `schema`:
+
+```typescript
+import { createTenantedRouteDefinition } from 'quidproquo-features';
+
+const caseRoute = createTenantedRouteDefinition('users', {}, { [ErrorTypeEnum.Forbidden]: 403 });
+
+export const approveCase = caseRoute(
+  ['POST', '/cases/{id}/approval'],
+  function* (event, params) { ... },
+  { permission: { permission: CasePermission.Approve, resourceIdParam: 'id', message: 'You cannot approve cases here.' } },
+);
+```
+
+The order is authenticate, resolve the tenant header, membership, permission, then the handler. The permission is judged against the membership row the gate already read, so it costs no extra store read. `permission` is a bare key or an object: `resourceIdParam` names the path param holding the resource id (a member with a grant scoped to specific ids is checked against that id; without it only a tenant-wide grant satisfies), `allowPersonalScope` lets the route run ungated when no tenant header is sent (default is to refuse, since a personal partition has no roles to check), and `message` replaces the default `Missing permission: <key>` text. A route with no `permission` is membership-only.
+
+For a check that needs the loaded resource, such as its kind, call `askTenantAssertPermission(requirement, message, userDirectoryName)` from the handler's logic after reading it.
 
 ## Signature
 
@@ -67,16 +90,17 @@ The single `options` argument is a `TenantOptions` (a `TenantRoutesOptions` plus
 | `routeAuthSettings` | `RouteAuthSettings` | – (required) | Auth applied to every mounted route (see [route](../webserver/route.md)). Required here, unlike the generic event-doc routes: tenant routes are meaningless unauthenticated, since membership keys off the user. Only used on the owner's deploy. |
 | `version` | `number` | `1` | Version number for the `/v{version}` path prefix on every route. Only used on the owner's deploy. |
 | `tenantHeaderName` | `string` | `'x-qpq-tenant-id'` | The header the client sends its selected tenant id on. Exposed to the tenant routes as the `tenantHeaderName` global, which the scope resolver reads. |
+| `roles` | `{ catalog?: TenantRoleCatalog; creatorRoles?: string[] }` | catalog just `tenantAdmin`; creator gets `[tenantAdmin]` | `catalog` is the app's roles, role code to `{ code, name, permissions }`, merged with the built-in `tenantAdmin` role (the reserved code may not be redefined). `creatorRoles` is what a tenant's creator is seeded with; every code must be in the catalog and at least one must hold `tenant:roles:assign`, checked at config time. Both are published as the `tenantRoles` global in every service. |
 
 ## Notes
 
 - Tenant state is event-sourced: the `tenants` event-doc collection is the audit-trailed source of truth, and the `tenantRecords` table is a read model synced on publish. Request handlers never write the record table directly.
 - The `tenants` collection is scope-resolved like any other tenanted collection (see [defineTenantedEventDoc](./tenanted-event-doc.md)): a doc is only visible/editable from the scope that owns it, including through the stock CRUD at `{basePath}`. There is no cross-scope doc read — listing memberships homed in another scope goes through the published `TenantRecord`, not the doc store.
-- The `TenantRecord` produced by the publish sync carries `tenantId`, `name`, `brandColors`, `logo` (an asset ref, resolved to a URL via the get-logo route above), `scope` (the storage scope the doc was published under, used to presign the logo for cross-scope readers), `createdAt`, `updatedAt`, `createdByUserId`, and a `status` derived from the summary (`deleted` when the summary has a `deletedAt`, otherwise `active`).
+- The `TenantRecord` produced by the publish sync carries `tenantId`, `name`, `brandColors`, `logo` (an asset ref, resolved to a URL via the get-logo route above), `createdAt`, `updatedAt`, `createdByUserId`, and a `status` derived from the summary (`deleted` when the summary has a `deletedAt`, otherwise `active`).
 - `defineTenant` registers the scope resolver but does not apply it to anything. To tenant-scope one of your own collections, pass `TENANT_SCOPE_RESOLVER_FN` as that collection's `scopeResolver` option (or use [defineTenantedEventDoc](./tenanted-event-doc.md), which does this for you).
 - The scope resolver always resolves to a typed scope — a membership-checked `TENANT#<id>` for a request that names a tenant, or the caller's own `PERSONAL#<userId>` when it doesn't. A tenant-scoped collection or connection is never left unscoped.
 - Every service — owner and non-owner alike — calls `defineTenant` with the same `owner`. There is no separate call for non-owning services anymore: the gating happens internally via [defineServiceSettings](../core/service-settings.md).
-- Membership rows carry a `TenantMembershipRole` (`owner` or `member`, see [defineTenantStores](./tenant-stores.md)): the tenant's creator starts as `owner`. Owners manage membership (add/remove/update role or disabled); members merely belong. A single `tenantMemberships` table (keyed `userId`+`tenantId`, with a `tenantId`/`userId` GSI) serves both the access check and a tenant's member list, so there is no separate index to keep in lock-step.
+- Membership rows carry the member's `roles` (catalog codes) and direct `grants` (see [defineTenantStores](./tenant-stores.md)): the tenant's creator starts with `roles.creatorRoles` (by default just the built-in `tenantAdmin` role), and `tenantAdmin` holds `tenant:members:manage` (add, remove, disable members), `tenant:roles:assign` (set roles) and the tenant collection's own `eventDoc:tenants:*` keys. A member with no roles can list members, read the published record, and read the role catalog, and nothing else. The last member who can assign roles can never be removed or disabled, whether by role change, disable, or removal. A single `tenantMemberships` table (keyed `userId`+`tenantId`, with a `tenantId`/`userId` GSI) serves the access check, the permission check and a tenant's member list.
 
 ## Related
 

package/template/docusaurus/docs/config/features/tenanted-email-receiver.md

@@ -0,0 +1,79 @@
+---
+title: defineTenantedEmailReceiver
+description: Let tenants register email addresses and run a story, inside the tenant's scope, for every message that arrives on one.
+---
+
+# defineTenantedEmailReceiver
+
+A [defineEmailReceiver](../webserver/email-receiver.md) whose messages are routed to tenants. A tenant registers addresses on the app's [receiving domain](../webserver/email-receiving-domain.md) through the routes at `basePath` (any local part, `finance.commbank`, `info.anz`, first come, global across tenants), and `onEmail` runs once per delivered registered recipient **inside that tenant's scope** with a `TenantedEmailReceivedEvent`. Mail to an address nobody registered is logged and dropped.
+
+The recipient is what names the tenant, and the mail provider delivered the message there, so routing cannot be spoofed by a sender. Who the message is *from* is the handler's business: `message.from` plus `message.authentication` (SPF/DKIM/DMARC verdicts) is the evidence, and a per-inbox allow list is app data.
+
+Needs [defineTenant](./tenant.md) in the same service: the routes gate on the tenant header and membership, and check `tenant:email:inboxes:manage`, which the app bundles into a role in its `roles.catalog` (`TenantEmailPermission.InboxesManage`).
+
+```typescript
+import { defineTenantedEmailReceiver } from 'quidproquo-features';
+
+export default [
+  defineTenantedEmailReceiver('inbound', {
+    onEmail: '/entry/email/onTenantEmail::onTenantEmail',
+    basePath: '/email/inboxes',
+    routeAuthSettings: { userDirectoryName: 'app-users' },
+  }),
+];
+```
+
+The handler runs under `TENANT#<id>`, so anything it writes to a scoped drive or store is partitioned by the inbox's tenant:
+
+```typescript
+import { AskResponse } from 'quidproquo-core';
+import { TenantedEmailReceivedEvent, TenantedEmailReceivedEventResponse } from 'quidproquo-features';
+
+export function* onTenantEmail({ message, recipient, inbox }: TenantedEmailReceivedEvent): AskResponse<TenantedEmailReceivedEventResponse> {
+  if (message.authentication.dkim !== 'pass') {
+    return;
+  }
+  // inbox.tenantId is the tenant; the ambient storage scope is already its scope
+}
+```
+
+## Routes
+
+All three require the tenant header (an inbox belongs to a tenant, never to a person) and `tenant:email:inboxes:manage` in it.
+
+| Method | Path | Description |
+| --- | --- | --- |
+| `GET` | `{basePath}` | The tenant's inboxes as `TenantEmailInboxView[]`: the row plus `addresses`, the full address on every receiving host. |
+| `POST` | `{basePath}` | Register an address (body `{ address, label? }`). The local part is lower-cased and must be a plain dot-atom (`a-z 0-9 . _ + -`, no leading/trailing/double dots, at most 64 chars); a host in the body is ignored. `BadRequest` when malformed, `Conflict` when already held by any tenant. |
+| `DELETE` | `{basePath}/{address}` | Release an address the tenant holds. Another tenant's address reads as `NotFound`. |
+
+## Signature
+
+```typescript
+function defineTenantedEmailReceiver(
+  name: string,
+  options: TenantedEmailReceiverOptions,
+): QPQConfig;
+```
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | The receiver's name, passed to the underlying `defineEmailReceiver`. |
+| `options.onEmail` | `QpqFunctionRuntime` | The story run per (message, registered recipient), inside the tenant's scope. |
+| `options.basePath` | `` `/${string}` `` | Root of the inbox routes. |
+| `options.routeAuthSettings` | `RouteAuthSettings` | The user directory the routes authenticate against; membership is checked against it. |
+| `options.version` | `number` | Route version prefix, default 1. |
+
+## What it declares
+
+- The `qpq-tenant-email-inboxes` store (unscoped by necessity: a message names an inbox before any scope exists), keyed by local part with a `tenantId` index.
+- The inline function registration for `onEmail`.
+- The underlying `defineEmailReceiver`, whose handler does the routing.
+- The three routes.
+
+## Related
+
+- [defineEmailReceiver](../webserver/email-receiver.md) — the untenanted receiver this builds on, and the `EmailMessage` shape.
+- [defineTenant](./tenant.md) — membership, the roles catalog, and the tenant header.

package/template/docusaurus/docs/config/features/tenanted-event-doc.md

@@ -1,13 +1,26 @@
 ---
 title: defineTenantedEventDoc
-description: A defineEventDoc with the tenant scope resolver pre-wired, so the collection's stores and assets partition per tenant.
+description: A defineEventDoc with the tenant scope resolver and authoriser pre-wired, so the collection partitions per tenant and every route requires a permission.
 ---
 
 # defineTenantedEventDoc
 
-A [defineEventDoc](./event-doc.md) with the tenant scope resolver pre-wired as its `scopeResolver`, so the collection's stores and assets partition per tenant: request header → membership check → tenant scope, or the caller's own personal scope when no header is sent — the collection is never unscoped. It takes the same arguments as `defineEventDoc` minus `scopeResolver`, which it fills in for you.
+A [defineEventDoc](./event-doc.md) with the tenant scope resolver pre-wired as its `scopeResolver` and the tenant authoriser as its `authorise`. The collection's stores and assets partition per tenant: request header, membership check, tenant scope, or the caller's own personal scope when no header is sent. The collection is never unscoped. Inside a tenant, every route also requires the caller to hold the collection's permission for that route, `eventDoc:<storeName>:<action>` where action is `read`, `create`, `write` or `delete`. Personal-scope requests are not permission-checked, since a personal partition has no second party to protect. It takes the same arguments as `defineEventDoc` minus `scopeResolver` and `authorise`, which it fills in for you.
 
-The deploying service must still register the resolver implementation by calling [defineTenant](./tenant.md) (with the same `owner` used everywhere else). Use plain [defineEventDoc](./event-doc.md) for collections that never partition by tenant.
+The deploying service must still register both implementations by calling [defineTenant](./tenant.md) (with the same `owner` used everywhere else). Use plain [defineEventDoc](./event-doc.md) for collections that never partition by tenant.
+
+Bundle a collection's keys into roles with `eventDocPermissions`, which builds them from the store name so the catalog and the check cannot drift:
+
+```typescript
+import { eventDocPermissions } from 'quidproquo-features';
+
+const articles = eventDocPermissions('articles');
+
+export const APP_ROLE_CATALOG = {
+  editor: { code: 'editor', name: 'Editor', permissions: [articles.read, articles.create, articles.write] },
+  reader: { code: 'reader', name: 'Reader', permissions: [articles.read] },
+};
+```
 
 ```typescript
 import { defineTenantedEventDoc, defineTenant } from 'quidproquo-features';
@@ -17,7 +30,9 @@ export default [
   ...defineTenant({
     owner: { module: 'ca' },
     basePath: '/tenants',
+    myTenantsBasePath: '/my-tenants',
     routeAuthSettings: { userDirectoryName: 'users' },
+    roles: { catalog: APP_ROLE_CATALOG },
   }),
 
   ...defineTenantedEventDoc(articleDefinition, '/entry/eventDocs::articleDefinition', {
@@ -37,19 +52,19 @@ function defineTenantedEventDoc(
 ): QPQConfig;
 ```
 
-`TenantedEventDocCollectionOptions` is `EventDocCollectionOptions` with `scopeResolver` omitted — see [defineEventDoc](./event-doc.md#parameters) for the remaining options.
+`TenantedEventDocCollectionOptions` is `EventDocCollectionOptions` with `scopeResolver` and `authorise` omitted — see [defineEventDoc](./event-doc.md#parameters) for the remaining options.
 
 ## Parameters
 
-Same as [defineEventDoc](./event-doc.md#parameters): `functions`, `runtime`, and `options` (`basePath`, `routeAuthSettings`, `version`, `onPublish`, `onAppend`, without `scopeResolver`, which this always sets to `TENANT_SCOPE_RESOLVER_FN`).
+Same as [defineEventDoc](./event-doc.md#parameters): `functions`, `runtime`, and `options` (`basePath`, `routeAuthSettings`, `version`, `onPublish`, `onAppend`, without `scopeResolver` and `authorise`, which this always sets to `TENANT_SCOPE_RESOLVER_FN` and `TENANT_EVENT_DOC_AUTHORISER_FN`).
 
 ## Returns
 
-Same as [defineEventDoc](./event-doc.md) — a `QPQConfig` array with the collection's `scopeResolver` already pointed at the tenant scope resolver.
+Same as [defineEventDoc](./event-doc.md) — a `QPQConfig` array with the collection's `scopeResolver` and `authorise` already pointed at the tenant implementations.
 
 ## Related
 
 - [defineEventDoc](./event-doc.md) — the underlying define this pre-configures.
-- [defineTenant](./tenant.md) — registers `TENANT_SCOPE_RESOLVER_FN`, the inline function this wires in by name.
+- [defineTenant](./tenant.md) — registers `TENANT_SCOPE_RESOLVER_FN` and `TENANT_EVENT_DOC_AUTHORISER_FN`, the inline functions this wires in by name.
 - [defineTenantedWebSocketQueue](./tenanted-web-socket-queue.md) — the same pattern applied to a WebSocket queue's `connectionScopeResolver`.
 - [defineTenantedEventDocTransfer](./tenanted-event-doc-transfer.md) — the same pattern applied to a collection's export/import routes.

package/template/docusaurus/docs/config/webserver/email-receiver.md

@@ -0,0 +1,65 @@
+---
+title: defineEmailReceiver
+description: Run a story for every email sent to the app's receiving domain.
+---
+
+# defineEmailReceiver
+
+Receives mail sent to **any address** at the app's [receiving domain](./email-receiving-domain.md) and runs `onEmail` once per message with an `EmailReceivedEvent` whose `message` is the parsed `EmailMessage`: who it is from, who it was delivered to, subject, bodies, attachments and the provider's SPF/DKIM verdicts. Like an `HTTPEvent` for a route, the event is all the handler sees; the transport is the receiver's own.
+
+Dynamic inboxes need no configuration: an address is just a local part, so `<inboxId>@inbox.<domain>` works the moment the receiver exists, and mapping an inbox to a tenant is a row in a key-value store keyed on `message.recipients`.
+
+- **On AWS:** adds one receipt rule, named from the app, environment, module and receiver, to the account's rule set ([defineAccountEmailReceiving](../config-aws/account-email-receiving.md)), matching the receiving host of every root with an S3 action into a drive the receiver owns (`email-<name>`). That drive's create handler parses each raw message with [askEmailParse](../../actions/webserver/email/ask-email-parse.md), runs `onEmail` as an inline function, and deletes the object; a message whose handler threw stays until a one-day lifecycle rule sweeps it. The drive's bucket policy lets exactly that rule write and nothing else. Synth fails if the service declares no [receiving domain](./email-receiving-domain.md).
+- **On the dev server:** nothing receives mail. Deployed platforms only.
+
+A throwing handler loses that message after the platform's retries. Catch inside the handler to do otherwise.
+
+```typescript
+import { defineEmailReceiver } from 'quidproquo-webserver';
+
+export default [
+  defineEmailReceiver('support', {
+    onEmail: '/entry/email/onSupportEmail::onSupportEmail',
+  }),
+];
+```
+
+The handler:
+
+```typescript
+import { AskResponse } from 'quidproquo-core';
+import { EmailReceivedEvent, EmailReceivedEventResponse } from 'quidproquo-webserver';
+
+export function* onSupportEmail({ message }: EmailReceivedEvent): AskResponse<EmailReceivedEventResponse> {
+  if (message.authentication.dkim !== 'pass') {
+    return;
+  }
+
+  const [recipient] = message.recipients;
+  // resolve the inbox from the recipient, then do the work
+}
+```
+
+## Signature
+
+```typescript
+function defineEmailReceiver(
+  name: string,
+  options: EmailReceiverOptions,
+): QPQConfig;
+```
+
+Returns the receiver setting, the inline function registration for `onEmail`, and the receiver's drive, as one config fragment.
+
+## Parameters
+
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | The receiver's name; part of the rule, drive and function names. |
+| `options.onEmail` | `QpqFunctionRuntime` | The story run per message, with an `EmailReceivedEvent` (`{ message: EmailMessage }`) as its only argument. |
+
+## Related
+
+- [askEmailParse](../../actions/webserver/email/ask-email-parse.md) — the `EmailMessage` shape, and parsing a raw message obtained some other way.
+- [defineEmailReceivingDomain](./email-receiving-domain.md) — the domain mail is received on (bootstrap and service).
+- [defineAccountEmailReceiving](../config-aws/account-email-receiving.md) — the account rule set (account).

package/template/docusaurus/docs/config/webserver/email-receiving-domain.md

@@ -0,0 +1,41 @@
+---
+title: defineEmailReceivingDomain
+description: The app's inbound email domain, verified with the mail provider and MX-routed to it.
+---
+
+# defineEmailReceivingDomain
+
+Declares the app's **receiving domain**: `<subdomain>.<env>.<root>` on every root, resolved like every other host through the app's [domain resolver](../../domains.md) (`inbox.development.example.com` with the default shape). Every [`defineEmailReceiver`](./email-receiver.md) in the app receives at this domain, at any local part.
+
+Like [`defineDns`](./dns.md), it is declared in two places: in the bootstrap config, whose stack owns the zone and so creates the records, and in every service that declares a receiver, which resolves its rule's recipients from it. Put it next to `defineDns` in the app's shared service define.
+
+- **On AWS:** per root, creates an SES `EmailIdentity` for the receiving host (its DKIM CNAMEs land in the host's zone) and an MX record on it pointing at `inbound-smtp.<region>.amazonaws.com`. SES email receiving is only offered in some regions; the deploy region must be one of them. The identity also lets the app send to its own inboxes while the SES account is in sandbox.
+
+```typescript
+// bootstrap.qpq.ts, and the shared service define
+import { defineDns, defineEmailReceivingDomain } from 'quidproquo-webserver';
+
+export default [
+  defineDns('example.com'),
+  defineEmailReceivingDomain('inbox'),
+];
+```
+
+## Signature
+
+```typescript
+function defineEmailReceivingDomain(
+  subdomain?: string,
+): EmailReceivingDomainQPQWebServerConfigSetting;
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `subdomain` | `string` | `'inbox'` | The subdomain under the site root that receives mail. |
+
+## Related
+
+- [defineAccountEmailReceiving](../config-aws/account-email-receiving.md) — the account rule set the app's rules go into.
+- [defineEmailReceiver](./email-receiver.md) — where received mail lands.

package/template/scripts/smoke/runSmokeRun.mjs

@@ -82,7 +82,7 @@ export const runSmokeRun = async (apiUrl, log) => {
     const run = await callApi('GET', `/smoke/run/${runId}`);
     const { summary } = run;
     log(
-      `status=${run.status} completed ${summary.completed}/${summary.total} passed ${summary.passed} failed ${summary.failed}`
+      `status=${run.status} completed ${summary.completed}/${summary.total} passed ${summary.passed} failed ${summary.failed} skipped ${summary.skipped}`
     );
 
     if (run.status === 'passed' || run.status === 'failed') {

package/template/docusaurus/docs/config/config-aws/aws-kms-key.md

@@ -1,100 +0,0 @@
----
-title: defineAwsKmsKey
-description: Register a customer-managed KMS key to encrypt a storage drive or key-value store.
----
-
-# defineAwsKmsKey
-
-Registers an existing **customer-managed KMS key** (by ARN) and binds it to a specific [storage drive](../core/storage-drive.md) or [key-value store](../core/key-value-store.md). It is the AWS-side companion to the `encryption: true` flag on those resources: when a drive or store opts into customer-managed encryption, this setting tells the deploy which KMS key to use. Without a matching key registered here, the `encryption` flag has no key to reference.
-
-- **On AWS:** looked up by `getAwsKmsKeyForStorageDrive` / `getAwsKmsKeyForKeyValueStore` in `quidproquo-config-aws`, keyed by target type + resource name + owning module. `QpqCoreStorageDriveConstruct` and `QpqCoreKeyValueStoreConstruct` in `quidproquo-deploy-awscdk` resolve the key with `aws_kms.Key.fromKeyArn(...)` and set it as the bucket / table `encryptionKey`. The deploy also grants the service's roles the KMS actions (`kms:Decrypt`, `kms:GenerateDataKey*`, `kms:Encrypt`, `kms:ReEncrypt*`, `kms:DescribeKey`) needed to use the key. The key itself is referenced, not created — you provision and manage the key (and its key policy) separately.
-
-```typescript
-import { defineAwsKmsKey, AwsKmsKeyTargetType } from 'quidproquo-config-aws';
-
-export default [
-  defineAwsKmsKey(
-    'uploads-key',
-    'arn:aws:kms:us-east-1:123456789012:key/abcd-1234-...',
-    AwsKmsKeyTargetType.storageDrive,
-    { name: 'user-uploads', module: 'my-service' },
-  ),
-];
-```
-
-## Signature
-
-```typescript
-function defineAwsKmsKey(
-  keyname: string,
-  arn: string,
-  type: AwsKmsKeyTargetType,
-  owner: AwsKmsKeyOwner,
-): AwsKmsKeyQPQConfigSetting;
-```
-
-## Parameters
-
-### `keyname` — `string` (required)
-
-A unique name for this key registration (its `uniqueKey` within the config). An identifier for the entry — not the AWS key alias.
-
-### `arn` — `string` (required)
-
-The ARN of the existing customer-managed KMS key. This exact ARN is imported via `Key.fromKeyArn`.
-
-### `type` — `AwsKmsKeyTargetType` (required)
-
-Which kind of data store this key encrypts. The lookup matches on this together with the owner, so a store only picks up a key registered for its own resource type.
-
-| Value | Encrypts |
-| --- | --- |
-| `storageDrive` | A [storage drive](../core/storage-drive.md) (S3 bucket) with `encryption: true`. |
-| `keyValueStore` | A [key-value store](../core/key-value-store.md) (DynamoDB table) with `encryption: true`. |
-
-### `owner` — `AwsKmsKeyOwner` (required)
-
-Identifies the resource the key belongs to. Both fields are matched against the target store at deploy time.
-
-```typescript
-type AwsKmsKeyOwner = {
-  name: string;    // the storage-drive / key-value-store name
-  module: string;  // the module that owns that resource
-};
-```
-
-- **`name`** — the storage-drive or key-value-store name (matches the value passed to `defineStorageDrive` / `defineKeyValueStore`).
-- **`module`** — the module that owns that resource. For a store owned by the current service this is the service's own module name; set it to another module to key a foreign resource.
-
-## Examples
-
-```typescript
-import { defineKeyValueStore } from 'quidproquo-core';
-import { defineStorageDrive } from 'quidproquo-core';
-import { defineAwsKmsKey, AwsKmsKeyTargetType } from 'quidproquo-config-aws';
-
-export default [
-  // A drive and a store that both request customer-managed encryption
-  defineStorageDrive('user-uploads', { encryption: true }),
-  defineKeyValueStore('billing', 'invoiceId', { encryption: true }),
-
-  // Bind each to its KMS key
-  defineAwsKmsKey(
-    'uploads-key',
-    'arn:aws:kms:us-east-1:123456789012:key/uploads-...',
-    AwsKmsKeyTargetType.storageDrive,
-    { name: 'user-uploads', module: 'my-service' },
-  ),
-  defineAwsKmsKey(
-    'billing-key',
-    'arn:aws:kms:us-east-1:123456789012:key/billing-...',
-    AwsKmsKeyTargetType.keyValueStore,
-    { name: 'billing', module: 'my-service' },
-  ),
-];
-```
-
-## Related
-
-- [defineStorageDrive](../core/storage-drive.md) — its `encryption` flag selects a key registered here.
-- [defineKeyValueStore](../core/key-value-store.md) — its `encryption` flag selects a key registered here.