create-qpq-app 0.1.5

package/template/docusaurus/docs/config/webserver/auth-system.md

@@ -0,0 +1,110 @@
+---
+title: defineAuthSystem
+description: Bundle a complete username/password login flow — a user directory plus the HTTP routes to log in, refresh tokens, respond to challenges, and recover passwords.
+---
+
+# defineAuthSystem
+
+Bundles a complete username/password **authentication system** into a single config entry: it declares a [user directory](../../config/core/user-directory.md) and wires up all the HTTP endpoints needed to log in, refresh access tokens, respond to auth challenges (including MFA / software-token association), recover a forgotten password, and change a password. The handler stories ship inside quidproquo-webserver — you don't write them — so a single `defineAuthSystem(...)` call gives a service a working auth API.
+
+`defineAuthSystem` is a convenience that expands into several lower-level config settings; understanding those makes its behaviour clear. It emits:
+
+1. A top-level [`defineUserDirectory`](../../config/core/user-directory.md) (ungated, so other services can reference it to validate access tokens), owned by the given service.
+2. A `defineServiceSettings` block (gated to the owning service) containing a global that records the directory name, plus one route per auth endpoint.
+
+- **On AWS:** deploys whatever the emitted settings deploy — a Cognito user pool + app client for the user directory (see [defineUserDirectory](../../config/core/user-directory.md)) and API Gateway routes/Lambdas for each endpoint. `defineAuthSystem` itself provisions no infrastructure beyond what those settings do.
+
+```typescript
+import { defineAuthSystem } from 'quidproquo-webserver';
+
+export default [
+  defineAuthSystem('auth', 'app-users', {
+    selfSignUpEnabled: true,
+    basePath: '/auth',
+  }),
+];
+```
+
+## Signature
+
+```typescript
+function defineAuthSystem(
+  service: string,
+  directoryName: string,
+  options?: AuthSystemOptions,
+): QPQConfig;
+```
+
+Note the return type is `QPQConfig` (an array of config settings), not a single setting — spread it into, or include it in, your config array.
+
+## Parameters
+
+### `service` — `string` (required)
+
+The service/module that owns the auth system. The user directory is declared with `owner: { module: service }`, and the login endpoints are placed inside a `defineServiceSettings` block keyed on this service, so they only deploy with that service.
+
+### `directoryName` — `string` (required)
+
+The name of the [user directory](../../config/core/user-directory.md) to create and authenticate against. This is the same name you pass as `userDirectoryName` to the [User Directory actions](../../actions/core/user-directory/ask-user-directory-authenticate-user.md), and it is recorded in a global (`qpq-auth-user-directory`) so the built-in auth handler stories can resolve it at runtime. The `/changePassword` route is configured with `routeAuthSettings.userDirectoryName = directoryName`, so it requires a valid access token from this directory.
+
+### `options` — `AuthSystemOptions` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `phoneRequired` | `boolean` | `false` | Forwarded to the user directory: makes `phoneNumber` a required, auto-verified attribute. See [defineUserDirectory](../../config/core/user-directory.md#parameters). |
+| `selfSignUpEnabled` | `boolean` | `false` | Forwarded to the user directory: allows users to sign themselves up. See [defineUserDirectory](../../config/core/user-directory.md#parameters). |
+| `emailTemplates` | `EmailTemplates` | – | Forwarded to the user directory: story functions that customise the verification / password-reset emails. See [Email templates](../../config/core/user-directory.md#email-templates). |
+| `mfa` | `UserDirectoryMfaSettings` | – | Forwarded to the user directory: multi-factor authentication configuration. See [MFA](../../config/core/user-directory.md#mfa). |
+| `basePath` | `string` | `''` | A path prefix applied to every auth route. E.g. `'/auth'` produces `/auth/login`, `/auth/refreshToken`, and so on. |
+| `allowedOrigins` | `string[]` | – | Allowed browser origins (CORS) applied to every generated auth route. |
+
+## Generated routes
+
+With `basePath` = `''` (the default), `defineAuthSystem` registers these `POST` routes, each handled by a built-in `authController` story:
+
+| Path | Handler | Auth required |
+| --- | --- | --- |
+| `/login` | `login` | No |
+| `/refreshToken` | `refreshToken` | No |
+| `/challenge` | `respondToAuthChallenge` | No |
+| `/associateSoftwareToken` | `associateSoftwareToken` | No |
+| `/forgotPassword` | `forgotPassword` | No |
+| `/forgotPassword/confirm` | `confirmForgotPassword` | No |
+| `/changePassword` | `changePassword` | Yes — valid access token for `directoryName` |
+
+Each path is prefixed with `basePath` when provided (e.g. `/auth/login`). The handler stories correspond to the [User Directory actions](../../actions/core/user-directory/ask-user-directory-authenticate-user.md) — for example `login` authenticates a user, `refreshToken` refreshes an access token, and `respondToAuthChallenge` completes a challenge/MFA flow.
+
+## How auth ties routes to the user directory
+
+A route becomes authenticated by setting `routeAuthSettings.userDirectoryName` (which `defineAuthSystem` does for `/changePassword`). At runtime the webserver validates the caller's access token against that directory before invoking the handler — decoding the token, checking it is valid, and making its claims/roles available. Any route in the application (not just the ones generated here) can opt into the same protection by referencing this directory's name, because the directory is declared ungated at the top level.
+
+To protect your own routes with this directory, set `routeAuthSettings: { userDirectoryName: 'app-users' }` on the route (optionally with `scopes` to require specific claims). API-key auth is the complementary mechanism — see [defineApiKey](./api-key.md).
+
+## Examples
+
+```typescript
+import { defineAuthSystem, UserDirectoryMfaMode } from 'quidproquo-webserver';
+
+export default [
+  // Minimal: creates the 'app-users' directory + /login, /refreshToken, etc.
+  ...defineAuthSystem('auth', 'app-users'),
+
+  // Prefixed, self sign-up, required MFA, custom emails
+  ...defineAuthSystem('auth', 'app-users', {
+    basePath: '/auth',
+    selfSignUpEnabled: true,
+    mfa: { mode: UserDirectoryMfaMode.required },
+    emailTemplates: {
+      verifyEmail: '/entry/auth/verifyEmail::verifyEmail',
+    },
+    allowedOrigins: ['https://app.example.com'],
+  }),
+];
+```
+
+## Related
+
+- [defineUserDirectory](../../config/core/user-directory.md) — the user directory `defineAuthSystem` creates; documents the directory options that `phoneRequired`, `selfSignUpEnabled`, `emailTemplates`, and `mfa` forward to, plus the AWS Cognito infrastructure.
+- [defineApiKey](./api-key.md) — the complementary auth mechanism (shared-secret / machine callers) for routes.
+- **User Directory actions** — the auth operations the generated handlers wrap: [askUserDirectoryAuthenticateUser](../../actions/core/user-directory/ask-user-directory-authenticate-user.md), [askUserDirectoryRefreshToken](../../actions/core/user-directory/ask-user-directory-refresh-token.md), [askUserDirectoryRespondToAuthChallenge](../../actions/core/user-directory/ask-user-directory-respond-to-auth-challenge.md), [askUserDirectoryChangePassword](../../actions/core/user-directory/ask-user-directory-change-password.md), [askUserDirectoryForgotPassword](../../actions/core/user-directory/ask-user-directory-forgot-password.md), [askUserDirectoryConfirmForgotPassword](../../actions/core/user-directory/ask-user-directory-confirm-forgot-password.md), [askUserDirectoryAssociateSoftwareToken](../../actions/core/user-directory/ask-user-directory-associate-software-token.md).
+- **Routes and APIs** — the generated endpoints are `defineRoute` settings; see the route / `defineApi` config settings in quidproquo-webserver to add and protect your own routes with this directory.

package/template/docusaurus/docs/config/webserver/cache.md

@@ -0,0 +1,94 @@
+---
+title: defineCache
+description: Define a named CDN cache policy (TTLs) that web entries and SEO routes reference by name.
+---
+
+# defineCache
+
+Defines a named **cache policy** — a set of CDN cache TTLs — that other web settings reference by name. A [web entry](./web-entry.md) applies it via `cacheSettingsName`, and a [defineSeo](./seo.md) route can reference its own cache policy the same way. Declaring caching once and referencing it by name keeps a consistent policy across behaviors.
+
+- **On AWS:** deploys a CloudFront `CachePolicy` (`QpqWebServerCacheConstruct` in `quidproquo-deploy-awscdk`) with the configured min/default/max TTLs. The policy caches on an allow-list of headers — `x-qpq-is-bot` (so bot vs. human responses cache separately, which pairs with SEO edge rendering) plus the CORS request headers (`Origin`, `Access-Control-Request-Headers`, `Access-Control-Request-Method`) — and enables gzip and brotli. The policy id is exported so web entries in other stacks can attach it.
+
+```typescript
+import { defineCache } from 'quidproquo-webserver';
+
+export default [
+  defineCache('default', {
+    minTTLInSeconds: 0,
+    defaultTTLInSeconds: 86400,
+    maxTTLInSeconds: 31536000,
+    mustRevalidate: false,
+  }),
+];
+```
+
+## Signature
+
+```typescript
+function defineCache(
+  name: string,
+  cache: CacheSettings,
+  options?: QPQConfigAdvancedCacheSettings,
+): CacheQPQWebServerConfigSetting;
+```
+
+## Parameters
+
+### `name` — `string` (required)
+
+The cache policy's name and `uniqueKey`. This is the value other settings pass as `cacheSettingsName`.
+
+### `cache` — `CacheSettings` (required)
+
+```typescript
+export interface CacheSettings {
+  minTTLInSeconds: number;
+  maxTTLInSeconds: number;
+  defaultTTLInSeconds: number;
+  mustRevalidate: boolean;
+}
+```
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `minTTLInSeconds` | `number` | Minimum time an object stays cached before the CDN checks origin for a newer version. |
+| `defaultTTLInSeconds` | `number` | Time an object is cached when origin sends no `Cache-Control`/`Expires` directive of its own. |
+| `maxTTLInSeconds` | `number` | Maximum time an object stays cached, capping any longer TTL requested by origin headers. |
+| `mustRevalidate` | `boolean` | Intended to require revalidation of stale content. **Note:** this field is not currently applied by the AWS cache construct (the TTLs above drive caching); set it for forward-compatibility but rely on the TTLs for behavior today. |
+
+### `options` — `QPQConfigAdvancedCacheSettings` (optional)
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `owner` | `CrossModuleOwner<'cacheName'>` | Declares that this cache policy is owned by **another** module/service, so this service references the policy deployed there instead of creating a new one. |
+| `deprecated` | `boolean` | Standard advanced-settings flag marking the policy as deprecated. |
+
+## Examples
+
+```typescript
+import { defineCache, defineWebEntry } from 'quidproquo-webserver';
+
+export default [
+  // Cache aggressively by default, but bypass the SPA shell so deploys land instantly
+  defineCache('default', {
+    minTTLInSeconds: 0,
+    defaultTTLInSeconds: 86400,
+    maxTTLInSeconds: 31536000,
+    mustRevalidate: false,
+  }),
+
+  defineWebEntry('website', {
+    buildPath: './web/dist',
+    cacheSettingsName: 'default',
+    ignoreCache: ['index.html'],
+    domain: { onRootDomain: true, rootDomain: 'example.com' },
+  }),
+];
+```
+
+## Related
+
+- [defineWebEntry](./web-entry.md) — applies a cache policy via `cacheSettingsName` and lists `ignoreCache` bypass patterns.
+- [defineSeo](./seo.md) — SEO routes can reference their own cache policy by name.
+- [askWebEntryInvalidateCache](../../actions/webserver/web-entry/ask-web-entry-invalidate-cache.md) — force cached objects to be re-fetched before their TTL expires.
+- **AWS implementation:** `QpqWebServerCacheConstruct` (CloudFront `CachePolicy`) in `quidproquo-deploy-awscdk`.

package/template/docusaurus/docs/config/webserver/certificate.md

@@ -0,0 +1,64 @@
+---
+title: defineCertificate
+description: Legacy declaration of a TLS certificate for a domain — kept for backwards compatibility; certificates are now provisioned centrally.
+---
+
+# defineCertificate
+
+Declares a TLS certificate for a domain rooted at a service's [DNS base](./dns.md).
+
+:::warning Legacy / no-op on AWS
+`defineCertificate` is kept only for **backwards compatibility**. Its AWS construct (`QpqWebserverCertificateConstruct`) is now a no-op shim that creates no resources. Certificates are provisioned centrally by the deploy pipeline via `defineDomainCertificate` (in the bootstrap config) and are consumed by service constructs through an internal SSM lookup. New configs should rely on that central certificate rather than calling `defineCertificate`.
+:::
+
+- **On AWS:** nothing. The central `DomainCertificateStack` creates an **ACM certificate** with **DNS validation** against the existing Route53 hosted zone, then publishes its ARN to SSM so API Gateway custom domains and [CloudFront domain proxies](./domain-proxy.md) can look it up. `defineCertificate` itself no longer participates in that.
+
+```typescript
+import { defineCertificate } from 'quidproquo-webserver';
+
+export default [
+  // Legacy: certificate covering a subdomain of the service's DNS base
+  defineCertificate(false, 'example.com', 'app'),
+];
+```
+
+## Signature
+
+```typescript
+function defineCertificate(
+  onRootDomain: boolean,
+  rootDomain: string,
+  subdomain?: string,
+  options?: QPQConfigAdvancedCertificateSettings,
+): CertificateQPQWebServerConfigSetting;
+```
+
+## Parameters
+
+| Parameter | Type | Default | Description |
+| --- | --- | --- | --- |
+| `onRootDomain` | `boolean` | – | Whether the certificate is issued against the shared root domain rather than the service's own subdomain. Combined with `subdomain` it forms the config's `uniqueKey`. |
+| `rootDomain` | `string` | – | The root domain the certificate belongs to (matches the service's [`dnsBase`](./dns.md)). |
+| `subdomain` | `string` | – | Optional subdomain the certificate covers. |
+| `options` | `QPQConfigAdvancedCertificateSettings` | – | Advanced settings. Currently an empty interface (it extends the shared `QPQConfigAdvancedSettings`, e.g. cross-module `owner`), reserving room for future options. |
+
+## Examples
+
+```typescript
+import { defineCertificate } from 'quidproquo-webserver';
+
+export default [
+  // Certificate on the root domain
+  defineCertificate(true, 'example.com'),
+
+  // Certificate for a specific subdomain
+  defineCertificate(false, 'example.com', 'admin'),
+];
+```
+
+## Related
+
+- [defineDns](./dns.md) — declares the `rootDomain` this certificate is rooted at.
+- [defineDomainProxy](./domain-proxy.md) — a CloudFront proxy that consumes the central certificate for its domain.
+- [defineSubdomainRedirect](./subdomain-redirect.md) — related domain-level configuration.
+- [defineDomainCertificate](../config-aws/domain-certificate.md) — the real ACM certificate (with DNS validation) this portable shim defers to on AWS.

package/template/docusaurus/docs/config/webserver/default-route-options.md

@@ -0,0 +1,77 @@
+---
+title: defineDefaultRouteOptions
+description: Declare CORS and auth defaults that are merged into every route in a service.
+---
+
+# defineDefaultRouteOptions
+
+Declares **default route options** — CORS origins and auth settings that are merged into every [route](./route.md) in the service. Use it to apply a shared authentication policy or a common set of allowed browser origins once, instead of repeating the same options on each route.
+
+- **On AWS:** no infrastructure of its own. The defaults are merged into each route's options at runtime by the API Lambda; see [defineApi](./api.md).
+
+```typescript
+import { defineDefaultRouteOptions } from 'quidproquo-webserver';
+
+export default [
+  defineDefaultRouteOptions('web', {
+    allowedOrigins: ['https://app.example.com'],
+    routeAuthSettings: {
+      userDirectoryName: 'users',
+    },
+  }),
+];
+```
+
+## Signature
+
+```typescript
+function defineDefaultRouteOptions(
+  groupName: string,
+  routeOptions: RouteOptions,
+): DefaultRouteOptionsQPQWebServerConfigSetting;
+```
+
+## Parameters
+
+### `groupName` — `string` (required)
+
+A unique key for this set of defaults. Every declared default-route-options setting is currently merged into every route in the service regardless of `groupName`; the name simply keeps multiple declarations distinct within the config.
+
+### `routeOptions` — `RouteOptions` (required)
+
+The options to merge into each route.
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `allowedOrigins` | `(string \| ServiceAllowedOrigin)[]` | Browser origins allowed to call routes (CORS). Unioned with each route's own `allowedOrigins`. |
+| `routeAuthSettings` | `RouteAuthSettings` | Default auth policy — `userDirectoryName`, `scopes`, and `apiKeys`. Merged with each route's own auth settings (user directory falls back to the default; scopes and api keys are combined). |
+
+The shapes of `RouteOptions`, `RouteAuthSettings`, and `ServiceAllowedOrigin` are documented on the [defineRoute](./route.md) page.
+
+## Notes
+
+- Merging is **additive**: `allowedOrigins` are unioned and `routeAuthSettings.scopes`/`apiKeys` are combined across the defaults and the per-route options. `userDirectoryName` on a route takes precedence over the default when both are set.
+
+## Examples
+
+```typescript
+import { defineDefaultRouteOptions, defineRoute } from 'quidproquo-webserver';
+
+export default [
+  // Apply a user directory and CORS origin to all routes
+  defineDefaultRouteOptions('web', {
+    allowedOrigins: ['https://app.example.com'],
+    routeAuthSettings: { userDirectoryName: 'users' },
+  }),
+
+  // Inherits the user directory + origin above; adds a scope requirement
+  defineRoute('POST', '/orders', '/src/routes/orders/create::createOrder', {
+    routeAuthSettings: { scopes: ['orders:write'] },
+  }),
+];
+```
+
+## Related
+
+- [defineRoute](./route.md) — the routes these defaults are merged into.
+- [defineApi](./api.md) — the API the routes are served under.

package/template/docusaurus/docs/config/webserver/dns.md

@@ -0,0 +1,57 @@
+---
+title: defineDns
+description: Declare the base DNS domain a service lives under, so every domain, certificate, and DNS record it deploys hangs off one root.
+---
+
+# defineDns
+
+Declares the **base DNS domain** for a service. Everything else in quidproquo-webserver that needs a hostname — API custom domains, web entries, [domain proxies](./domain-proxy.md), and [subdomain redirects](./subdomain-redirect.md) — derives its fully-qualified name from this single `dnsBase`. A service has one DNS base.
+
+- **On AWS:** `defineDns` does **not** create a Route53 hosted zone by itself. The hosted zone for `dnsBase` (after environment/feature prefixing) must already exist in Route53 — deploy constructs look it up with `HostedZone.fromLookup`, then add the `A` records they need into that existing zone. Think of `defineDns` as declaring "this is my root domain"; the zone that owns it is expected to be there already.
+
+```typescript
+import { defineDns } from 'quidproquo-webserver';
+
+export default [
+  defineDns('example.com'),
+];
+```
+
+## Signature
+
+```typescript
+function defineDns(
+  dnsBase: string,
+): DnsQPQWebServerConfigSetting;
+```
+
+## Parameters
+
+### `dnsBase` — `string` (required)
+
+The root domain the service is served from, e.g. `'example.com'`. This value becomes the config's `uniqueKey` and is the base that all of the service's hostnames are built on. quidproquo prefixes it per environment and feature before use, so a single config deploys cleanly to multiple environments:
+
+- In `production` the base stays `example.com`.
+- In another environment it becomes `<environment>.example.com` (e.g. `development.example.com`).
+- With a feature branch it becomes `<feature>.<environment>.example.com`.
+- A service's own resources then live under `<service>.<base>` (e.g. an API at `api.<service>.development.example.com`).
+
+The list of declared bases is what [askDnsList](../../actions/webserver/dns/ask-dns-list.md) returns at runtime.
+
+## Examples
+
+```typescript
+import { defineDns } from 'quidproquo-webserver';
+
+export default [
+  // Serve this service under example.com (and its env/feature-prefixed variants)
+  defineDns('example.com'),
+];
+```
+
+## Related
+
+- [askDnsList](../../actions/webserver/dns/ask-dns-list.md) — returns the `dnsBase` values declared with `defineDns`.
+- [defineCertificate](./certificate.md) — TLS certificate for a domain rooted at this base.
+- [defineDomainProxy](./domain-proxy.md) — front a domain under this base with CloudFront.
+- [defineSubdomainRedirect](./subdomain-redirect.md) — redirect a subdomain under this base to another URL.

package/template/docusaurus/docs/config/webserver/domain-proxy.md

@@ -0,0 +1,109 @@
+---
+title: defineDomainProxy
+description: Front a domain with a CloudFront distribution that proxies all requests to another HTTP origin.
+---
+
+# defineDomainProxy
+
+Puts a **CloudFront distribution** in front of a domain (rooted at the service's [DNS base](./dns.md)) and proxies every request through to another HTTP origin. Use it to serve an external or internal backend under your own domain with HTTPS, optional caching, and optional WAF protection.
+
+- **On AWS:** deploys an `aws_cloudfront.Distribution` (`WebQpqWebserverDomainProxyConstruct` in `quidproquo-deploy-awscdk`) whose default behaviour points at an `HttpOrigin` for `httpProxyDomain`, forwards all viewer headers/methods, and applies the chosen viewer-protocol policy. It attaches the requested custom domain names, a looked-up ACM certificate (from the central certificate stack), a cache policy (named cache config or caching-disabled), and — when WAF is enabled for the service — the shared CloudFront web ACL. It then creates a Route53 **`A` alias record** per domain name pointing at the distribution, and adds a caching-disabled behaviour for each `ignoreCache` path pattern.
+
+```typescript
+import { defineDomainProxy, DomainProxyViewerProtocolPolicy } from 'quidproquo-webserver';
+
+export default [
+  defineDomainProxy('marketing-proxy', {
+    httpProxyDomain: 'origin.internal.example.com',
+    domain: {
+      rootDomain: 'example.com',
+      onRootDomain: true,
+    },
+    domainProxyViewerProtocolPolicy: DomainProxyViewerProtocolPolicy.REDIRECT_TO_HTTPS,
+  }),
+];
+```
+
+## Signature
+
+```typescript
+function defineDomainProxy(
+  name: string,
+  options: QPQConfigAdvancedDomainProxySettings,
+): DomainProxyQPQWebServerConfigSetting;
+```
+
+## Parameters
+
+### `name` — `string` (required)
+
+Unique name for this proxy (the config's `uniqueKey`). Used to derive the distribution's export name.
+
+### `options` — `QPQConfigAdvancedDomainProxySettings` (required)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `httpProxyDomain` | `string` | – | The origin hostname CloudFront forwards requests to (the backend being proxied). |
+| `domain` | `DomainProxyDomainOptions` | – | Which domain names the distribution answers on. See [Domain options](#domain-options). |
+| `domainProxyViewerProtocolPolicy` | `DomainProxyViewerProtocolPolicy` | – | How CloudFront treats HTTP vs HTTPS from viewers. See [Viewer protocol policy](#viewer-protocol-policy). |
+| `cacheSettingsName` | `string` | – | Name of a cache config (declared elsewhere in the service) to use as the distribution's cache policy. When omitted, caching is disabled. |
+| `ignoreCache` | `string[]` | `[]` | Path patterns that always bypass the cache — each becomes an extra CloudFront behaviour with caching disabled. |
+
+### Domain options
+
+```typescript
+export interface DomainProxyDomainOptions {
+  rootDomain: string;
+  subDomainNames?: string[];
+  onRootDomain: boolean;
+}
+```
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `rootDomain` | `string` | The root domain (matches the service's [`dnsBase`](./dns.md)); the apex is resolved from it with the usual environment/feature prefixing, and the hosted zone is looked up in Route53. |
+| `subDomainNames` | `string[]` | Subdomains to serve, each expanded to `<subDomain>.<apex>`. An `A` alias record is created for each. |
+| `onRootDomain` | `boolean` | When `true` and no subdomains are given, the distribution also answers on the apex domain itself. |
+
+### Viewer protocol policy
+
+```typescript
+export enum DomainProxyViewerProtocolPolicy {
+  HTTPS_ONLY = 'https-only',
+  REDIRECT_TO_HTTPS = 'redirect-to-https',
+  ALLOW_ALL = 'allow-all',
+}
+```
+
+| Member | Meaning |
+| --- | --- |
+| `HTTPS_ONLY` | Serve HTTPS only; reject plain HTTP. |
+| `REDIRECT_TO_HTTPS` | Redirect HTTP requests to HTTPS. |
+| `ALLOW_ALL` | Accept both HTTP and HTTPS. |
+
+## Examples
+
+```typescript
+import { defineDomainProxy, DomainProxyViewerProtocolPolicy } from 'quidproquo-webserver';
+
+export default [
+  // Proxy specific subdomains, HTTPS only, with a named cache config and a bypass path
+  defineDomainProxy('api-proxy', {
+    httpProxyDomain: 'backend.example.net',
+    domain: {
+      rootDomain: 'example.com',
+      subDomainNames: ['api', 'api-v2'],
+      onRootDomain: false,
+    },
+    domainProxyViewerProtocolPolicy: DomainProxyViewerProtocolPolicy.HTTPS_ONLY,
+    cacheSettingsName: 'short-cache',
+    ignoreCache: ['/health', '/webhooks/*'],
+  }),
+];
+```
+
+## Related
+
+- [defineDns](./dns.md) — declares the `rootDomain` this proxy attaches to.
+- [defineCertificate](./certificate.md) — related certificate configuration (the proxy uses the central certificate).
+- [defineSubdomainRedirect](./subdomain-redirect.md) — redirect a subdomain instead of proxying it.

package/template/docusaurus/docs/config/webserver/file-upload-settings.md

@@ -0,0 +1,63 @@
+---
+title: defineFileUploadSettings
+description: Set service-wide limits for multipart/form-data file uploads.
+---
+
+# defineFileUploadSettings
+
+Declares **service-wide limits for multipart/form-data file uploads** — maximum file size, file count, field count, field size, and accepted content types. Sensible defaults apply even when this setting is not declared; declare it only to override them.
+
+- **On AWS:** no infrastructure of its own. The limits are enforced by the API Lambda's multipart parser when handling upload requests (see [defineApi](./api.md)). API Gateway independently caps request payloads at 10MB.
+
+```typescript
+import { defineFileUploadSettings } from 'quidproquo-webserver';
+
+export default [
+  defineFileUploadSettings({
+    maxFileSizeBytes: 5 * 1024 * 1024,
+    allowedMimeTypes: ['image/*', 'application/pdf'],
+  }),
+];
+```
+
+## Signature
+
+```typescript
+function defineFileUploadSettings(
+  fileUploadSettings: Partial<FileUploadSettings>,
+): FileUploadSettingsQPQWebServerConfigSetting;
+```
+
+## Parameters
+
+### `fileUploadSettings` — `Partial<FileUploadSettings>` (required)
+
+Any subset of the limits below; unspecified fields keep their default.
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `maxFileSizeBytes` | `number` | `10485760` (10 MB) | Maximum size of any single uploaded file. Uploads with a larger file are rejected with a `413`. The default matches API Gateway's 10MB request cap. |
+| `maxFileCount` | `number` | `10` | Maximum number of files in a single multipart request. |
+| `maxFieldCount` | `number` | `100` | Maximum number of non-file fields in a single multipart request. |
+| `maxFieldSizeBytes` | `number` | `1048576` (1 MB) | Maximum size of any single non-file field value. Larger values are truncated by the parser. |
+| `allowedMimeTypes` | `string[]` | – (any) | Content types accepted for uploaded files, e.g. `['image/*', 'application/pdf']` (`type/*` wildcards supported). Omit to accept any content type. |
+
+## Examples
+
+```typescript
+import { defineFileUploadSettings } from 'quidproquo-webserver';
+
+export default [
+  // Images only, up to 5MB each, at most 3 per request
+  defineFileUploadSettings({
+    maxFileSizeBytes: 5 * 1024 * 1024,
+    maxFileCount: 3,
+    allowedMimeTypes: ['image/png', 'image/jpeg'],
+  }),
+];
+```
+
+## Related
+
+- [defineApi](./api.md) — the API whose Lambda enforces these limits.
+- [defineRoute](./route.md) — the routes that accept uploads.

package/template/docusaurus/docs/config/webserver/migration.md

@@ -0,0 +1,83 @@
+---
+title: defineMigration
+description: Register deploy-time migration stories that run once per deploy to evolve data as your service changes.
+---
+
+# defineMigration
+
+Registers a set of **migrations** — stories that run at deploy time to evolve existing data when your service changes (rename a field, backfill a column, reshape records). Each migration runs **at most once** across the lifetime of the service: quidproquo tracks which migrations have already run and only executes the ones that are new in the current deploy.
+
+`defineMigration` is a convenience wrapper that expands into several lower-level config settings. It is built on [defineDeployEvent](../core/deploy-event.md), so its work is triggered by the deploy-event pipeline and ultimately runs through [askProcessEvent](../../actions/core/event/ask-process-event.md), just like every other event source.
+
+- **What it declares:** a [global](../core/global.md) (`qpqMigrations`) holding the migration list, a [key-value store](../core/key-value-store.md) (`qpqMigrations`) that records which migrations have run, a [deploy event](../core/deploy-event.md) (`qpqMigrations`) that reacts to stack changes, and a [queue](../core/queue.md) (`qpqMigrations`) that actually executes each migration story. The queue is configured to run **one migration at a time** (`maxConcurrentExecutions: 1`, `batchSize: 1`, `concurrency: 1`) so migrations never run concurrently.
+
+```typescript
+import { defineMigration } from 'quidproquo-webserver';
+import { DeployEventType } from 'quidproquo-core';
+
+export default [
+  defineMigration([
+    {
+      runtime: '/entry/migrations/2026-addFullName::addFullName',
+      deployType: DeployEventType.Api,
+    },
+  ]),
+];
+```
+
+## How it runs
+
+The generated deploy event fires on each qualifying stack status change:
+
+- **On the first (Create) deploy** every migration is recorded as *already run* without executing it — a freshly created service is expected to start from clean [seed](./seed.md) data, so there is nothing to migrate.
+- **On later (Update) deploys** each migration whose `deployType` matches the stack that changed and that has **not** already been recorded is enqueued on the `qpqMigrations` queue (which runs its story) and then recorded as run. Migrations already recorded are skipped, so re-deploying is safe.
+
+## Signature
+
+```typescript
+function defineMigration(
+  migrations: Migration[],
+  options?: QPQConfigAdvancedMigrationSettings,
+): QPQConfig;
+```
+
+Unlike most `define*` helpers (which return a single config setting), `defineMigration` returns a `QPQConfig` — an array of settings — because it composes several underlying resources.
+
+## Parameters
+
+### `migrations` — `Migration[]` (required)
+
+The list of migrations to register. Each entry:
+
+```typescript
+export interface Migration {
+  runtime: QpqFunctionRuntime;
+  deployType: DeployEventType;
+}
+```
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `runtime` | `QpqFunctionRuntime` | The migration story to run, usually a relative path string of the form `'/path/to/file::exportedFunctionName'`. Its source path becomes the migration's identity — this is the key stored in the tracking key-value store, so it is how quidproquo knows a given migration has already run. |
+| `deployType` | `DeployEventType` | Which deploy this migration belongs to, so it only runs when the matching stack updates. One of `DeployEventType.Api`, `DeployEventType.Web`, or `DeployEventType.Unknown`. |
+
+### `options` — `QPQConfigAdvancedMigrationSettings` (optional)
+
+Extends the shared `QPQConfigAdvancedSettings`. Forwarded to the underlying key-value store and queue.
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `deprecated` | `boolean` | `false` | Marks the underlying resources as deprecated. |
+
+## Notes
+
+- Migrations run **sequentially** (never in parallel), one message per batch.
+- Because identity is derived from the story's source path, moving or renaming a migration file makes quidproquo treat it as a brand-new migration that will run again.
+- A migration story receives no payload — it is executed for its side effects on your data.
+
+## Related
+
+- [defineSeed](./seed.md) — the companion helper: seeds initial data on the first deploy, whereas migrations evolve existing data on later deploys.
+- [defineDeployEvent](../core/deploy-event.md) — the lower-level deploy-time hook this is built on.
+- [askProcessEvent](../../actions/core/event/ask-process-event.md) — the pipeline that runs the migration story.
+- [defineQueue](../core/queue.md) / [defineKeyValueStore](../core/key-value-store.md) / [defineGlobal](../core/global.md) — the resources `defineMigration` generates.