create-qpq-app 0.1.25 → 0.1.26

package/template/docusaurus/docs/actions/webserver/email/ask-email-parse.md

@@ -0,0 +1,54 @@
+---
+title: askEmailParse
+description: Parse a raw MIME message into addresses, subject, body, attachments and the provider's authentication verdicts.
+---
+
+# askEmailParse
+
+Parses a raw MIME message into an `EmailMessage`, the `message` a [defineEmailReceiver](../../../config/webserver/email-receiver.md) hands its `onEmail` inside an `EmailReceivedEvent`. A receiver parses for you; this is for a raw message an app obtained some other way.
+
+- **Action type:** `EmailActionType.Parse`
+- **At runtime:** pure on every platform (postal-mime in `quidproquo-actionprocessor-js`); throws `Invalid` when the bytes are not a MIME message.
+
+```typescript
+import { askFileReadBinaryContents } from 'quidproquo-core';
+import { askEmailParse } from 'quidproquo-webserver';
+
+export function* askHandleMail(drive: string, filepath: string) {
+  const raw = yield* askFileReadBinaryContents(drive, filepath);
+  const message = yield* askEmailParse(raw.base64Data);
+
+  if (message.authentication.dkim !== 'pass') {
+    return;
+  }
+
+  const [recipient] = message.recipients;
+  // ...
+}
+```
+
+## Signature
+
+```typescript
+function* askEmailParse(
+  rawBase64: string,
+): AskResponse<EmailMessage>;
+```
+
+## Returns
+
+An `EmailMessage`:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `recipients` | `string[]` | The addresses the provider delivered to (`Delivered-To` / `X-Original-To`), lower-cased. Key inbox lookups on these; the `to` header can name addresses the app never saw. |
+| `from`, `to`, `cc`, `replyTo` | `EmailMessageAddress[]` | Header mailboxes, `{ address, name? }`. Group addresses are flattened to their members. |
+| `subject` | `string` | Empty when absent. |
+| `text`, `html` | `string?` | The bodies, when present. |
+| `messageId`, `date` | `string?` | As sent. |
+| `attachments` | `EmailMessageAttachment[]` | `{ filename?, mimeType, base64Data }`. |
+| `authentication` | `EmailMessageAuthentication` | `{ spf?, dkim?, dmarc? }`: the raw result token from the provider's `Authentication-Results` header (`pass`, `fail`, `softfail`, `none`, ...). `from` is what the sender claims; these are the only evidence for who sent it. |
+
+## Related
+
+- [defineEmailReceiver](../../../config/webserver/email-receiver.md) — receives mail and calls its handler with this shape.

package/template/docusaurus/docs/config/config-aws/account-email-receiving.md

@@ -0,0 +1,33 @@
+---
+title: defineAccountEmailReceiving
+description: The account's one active SES receipt rule set, shared by every app that receives email.
+---
+
+# defineAccountEmailReceiving
+
+Declares the account's **SES receipt rule set** and makes it the active one. It is an account setting: declared once in `account.qpq.ts`, deployed by the `qpq-account` stack, and shared by every app's [`defineEmailReceiver`](../webserver/email-receiver.md) in that account and region.
+
+SES allows exactly one active rule set per account per region, which is why it cannot belong to an app. Each app's inf stack adds its own rule (matched on that app's receiving domain) to this set and never activates anything itself.
+
+- **On AWS:** creates a `ReceiptRuleSet` named `qpq-email-receiving` (fixed by the deploy package) and calls `SetActiveReceiptRuleSet` on it through a custom resource (CloudFormation can create a set but not activate one). Deleting the stack deactivates it first, since SES refuses to delete an active set. Nothing receives until this is deployed.
+
+```typescript
+import { defineAccountEmailReceiving } from 'quidproquo-config-aws';
+
+export default [
+  defineAccountEmailReceiving(),
+];
+```
+
+## Signature
+
+```typescript
+function defineAccountEmailReceiving(): AccountEmailReceivingQPQConfigSetting;
+```
+
+Takes no arguments.
+
+## Related
+
+- [defineEmailReceivingDomain](../webserver/email-receiving-domain.md) — the per-app domain mail is received on (bootstrap).
+- [defineEmailReceiver](../webserver/email-receiver.md) — the per-service rule that lands mail in a drive.

package/template/docusaurus/docs/config/core/crypto-key.md

@@ -7,11 +7,13 @@ description: Define a crypto key, an application-level encryption key for askCry
 
 Declares a **crypto key**: a named encryption key stories use through [askCryptoEncrypt](../../actions/core/crypto/ask-crypto-encrypt.md) and [askCryptoDecrypt](../../actions/core/crypto/ask-crypto-decrypt.md). The key material never leaves the provider; your code only ever sees opaque ciphertext blobs.
 
-- **On AWS:** provisions a KMS customer managed key with automatic rotation enabled, addressed by a deterministic alias derived from application/module/environment, and grants the service's role use of it (`kms:GenerateDataKey*`, `kms:Decrypt`, `kms:Encrypt`, `kms:DescribeKey`). Rotation needs nothing from the app: old key material stays available for decrypt.
+- **On AWS:** provisions a KMS customer managed key with automatic rotation enabled, addressed by a deterministic alias derived from application/module/environment, and grants the service's role use of it (`kms:GenerateDataKey*`, `kms:Decrypt`, `kms:Encrypt`, `kms:ReEncrypt*`, `kms:DescribeKey`). Rotation needs nothing from the app: old key material stays available for decrypt.
 - **On the dev server:** a local master key is seeded on first use at `.qpq-runtime/<app>/cryptoKeys/<service>.json`, so everything works offline with no AWS credentials.
 
 One application-level key is usually enough. Separation between callers comes from the `context` on each encrypt (see [askCryptoEncrypt](../../actions/core/crypto/ask-crypto-encrypt.md)), not from separate keys.
 
+The same key also encrypts data at rest: name it as `cryptoKeyName` on a [storage drive](./storage-drive.md) or [key-value store](./key-value-store.md) and that resource is encrypted with it instead of the provider's managed keys.
+
 ```typescript
 import { defineCryptoKey } from 'quidproquo-core';
 

package/template/docusaurus/docs/config/core/key-value-store.md

@@ -55,7 +55,8 @@ Zero or more sort keys. The list is significant:
 | `owner` | `CrossModuleOwner` | – | Declares that this store is owned by **another** module/service. Use this to read/write a store deployed elsewhere: the deploy grants this service IAM access to the foreign table instead of creating a new one. |
 | `ttlAttribute` | `string` | – | Name of a record attribute holding a Unix-epoch (seconds) timestamp. DynamoDB automatically deletes records once that time passes. |
 | `disablePointInTimeRecovery` | `boolean` | `false` | Point-in-time recovery (35-day continuous backups / restore) is on by default; set this to opt out. |
-| `encryption` | `boolean` | `false` | Enables customer-managed KMS encryption for the table (the KMS key comes from the service's AWS config). When a customer-managed key isn't configured, AWS-managed encryption is used instead; when `false`, DynamoDB's default provider-managed encryption still applies. |
+| `cryptoKeyName` | `string` | | Encrypts the table with the named [defineCryptoKey](./crypto-key.md) instead of DynamoDB's default provider-managed encryption, which applies when omitted. The key must be declared in the same config, owned or via `owner`; a foreign key's owning service must be deployed first, since DynamoDB validates the key when the table is created. |
+| `scoped` | `boolean` | `false` | Requires every action against this store to carry a scope; a call without one throws `InvalidScopeError`. [askKeyValueStoreScanAllScopes](../../actions/core/key-value-store/ask-key-value-store-scan-all-scopes.md) is the one exempt action. |
 | `onStream` | `KvsStreamSettings` | – | Turns on change data capture and runs a story for every insert/modify/remove on the store. See [Change data capture (`onStream`)](#change-data-capture-onstream). |
 
 ## Keys (`CompositeKvsKey`)
@@ -171,7 +172,7 @@ export default [
 
   // Encrypted store using a store owned by another service
   defineKeyValueStore('billing', 'accountId', [], {
-    encryption: true,
+    cryptoKeyName: 'main',
     owner: { module: 'billing-service' },
   }),
 ];
@@ -182,6 +183,6 @@ export default [
 - **Read a single record:** [askKeyValueStoreGet](../../actions/core/key-value-store/ask-key-value-store-get.md) · [askKeyValueStoreGetAll](../../actions/core/key-value-store/ask-key-value-store-get-all.md)
 - **Query & scan:** [askKeyValueStoreQuery](../../actions/core/key-value-store/ask-key-value-store-query.md) · [askKeyValueStoreScan](../../actions/core/key-value-store/ask-key-value-store-scan.md)
 - **Write:** [askKeyValueStoreUpsert](../../actions/core/key-value-store/ask-key-value-store-upsert.md) · [askKeyValueStoreUpdate](../../actions/core/key-value-store/ask-key-value-store-update.md) · [askKeyValueStoreDelete](../../actions/core/key-value-store/ask-key-value-store-delete.md)
-- **AWS tuning:** [defineAwsKmsKey](../config-aws/aws-kms-key.md) (customer-managed encryption key for the `encryption` flag), [defineAwsDyanmoOverrideForKvs](../config-aws/aws-dyanmo-override-for-kvs.md) (back the store with a pre-existing DynamoDB table), and [defineAwsDataStoreRemovalPolicy](../config-aws/aws-data-store-removal-policy.md) (retain vs destroy the table on teardown).
+- **AWS tuning:** [defineAwsDyanmoOverrideForKvs](../config-aws/aws-dyanmo-override-for-kvs.md) (back the store with a pre-existing DynamoDB table), and [defineAwsDataStoreRemovalPolicy](../config-aws/aws-data-store-removal-policy.md) (retain vs destroy the table on teardown).
 - [defineEventDocSummary](../features/event-doc-summary.md) — a real `onStream` consumer: rebuilds a document's summary record from its event log on every change.
 - **AWS implementation:** `QpqCoreKeyValueStoreConstruct` (DynamoDB table, LSIs, GSIs, TTL, PITR, KMS, IAM grants) and `QpqApiCoreKeyValueStoreStreamConstruct` (the `onStream` handler lambda + event source) in `quidproquo-deploy-awscdk`; KVS action processors in `quidproquo-actionprocessor-awslambda`.

package/template/docusaurus/docs/config/core/storage-drive.md

@@ -40,7 +40,8 @@ The name of the drive. This is the name you pass as the `drive` argument to ever
 | `global` | `boolean` | `false` | Marks the drive as globally accessible across the account rather than private to the owning module. |
 | `onEvent` | `StorageDriveEvents` | – | Story functions to run when files are created or deleted in the drive. See [File events](#file-events-onevent). |
 | `lifecycleRules` | `StorageDriveLifecycleRule[]` | – | Rules that transition files to cheaper [storage tiers](#storagedrivetier) or delete them after a period. See [Lifecycle rules](#lifecycle-rules). |
-| `encryption` | `boolean` | `false` | Enables customer-managed KMS encryption for the drive (the KMS key comes from the service's AWS config). When `false`, provider-managed encryption still applies (SSE-S3 on AWS) — this flag only controls the KMS upgrade. |
+| `cryptoKeyName` | `string` | | Encrypts the drive with the named [defineCryptoKey](./crypto-key.md) instead of the provider's managed encryption (SSE-S3 on AWS), which applies when omitted. The key must be declared in the same config, owned or via `owner`; a foreign key's owning service must be deployed first, since S3 validates the key when the bucket is created. |
+| `scoped` | `boolean` | `false` | Requires every file action against this drive to carry a scope; a call without one throws `InvalidScopeError`. Incompatible with `copyPath` (`defineStorageDrive` throws at config time if both are set), since seeded content is deployed outside every scope. |
 | `lockedDown` | `boolean` | `false` | Denies object reads to every principal except the owning service's runtime role (listing and bucket management are unaffected). On AWS, the service stack must pass its `serviceRole` to `QpqCoreStorageDriveConstruct`; synth throws if a `lockedDown` drive has no `serviceRole`. |
 | `owner` | `CrossModuleOwner<'storageDriveName'>` | – | Declares that this drive is owned by **another** module/service. Use this to read/write a drive deployed elsewhere: the deploy grants this service IAM access to the foreign drive instead of creating a new bucket. `{ module, application, feature, environment, storageDriveName }` — all optional; unset parts default to the current service. |
 
@@ -64,7 +65,7 @@ defineStorageDrive('images', {
 });
 ```
 
-The handler story receives a `StorageDriveEvent` (exported from quidproquo-webserver) describing the drive and filepath that changed.
+The handler story receives a `StorageDriveEvent` (exported from quidproquo-webserver) describing the drive and filepath that changed. On a `scoped` drive, the event also carries a `scope` field (the object's scope, with `filePaths` made scope-relative); the handler runs with it as the ambient storage scope, so file and KVS calls inside it inherit the partition.
 
 ## Lifecycle rules
 
@@ -120,7 +121,7 @@ export default [
   // Seeded, encrypted drive with a create handler
   defineStorageDrive('templates', {
     copyPath: './seed/templates',
-    encryption: true,
+    cryptoKeyName: 'main',
     onEvent: {
       create: '/entry/storageDrive/onTemplateUploaded::onTemplateUploaded',
     },
@@ -139,5 +140,5 @@ export default [
 - **CORS for browser access:** [defineStorageDriveCorsSettings](../webserver/storage-drive-cors-settings.md) (quidproquo-webserver) controls the allowed browser origins for direct-to-drive uploads/downloads.
 - [defineFederatedModuleStore](./federated-module-store.md) — loads a service's story code from a drive declared here.
 - [defineEventDocSummary](../features/event-doc-summary.md) — declares an event-document collection's asset bucket as a drive of this kind.
-- **AWS tuning:** [defineAwsKmsKey](../config-aws/aws-kms-key.md) (customer-managed encryption key for the `encryption` flag) and [defineAwsDataStoreRemovalPolicy](../config-aws/aws-data-store-removal-policy.md) (retain vs destroy the bucket on teardown).
+- **AWS tuning:** [defineAwsDataStoreRemovalPolicy](../config-aws/aws-data-store-removal-policy.md) (retain vs destroy the bucket on teardown).
 - **AWS implementation:** `QpqCoreStorageDriveConstruct` (bucket, lifecycle, KMS, IAM grants) in `quidproquo-deploy-awscdk`; file action processors in `quidproquo-actionprocessor-awslambda`.

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/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') {