create-qpq-app 0.1.5

package/template/docusaurus/docs/config/config-aws/aws-service-account-info.md

@@ -0,0 +1,114 @@
+---
+title: defineAwsServiceAccountInfo
+description: Bind a service to the AWS account and region it deploys to, and tune its Lambda/logging defaults.
+---
+
+# defineAwsServiceAccountInfo
+
+Binds this service to the **AWS account and region** it deploys into, and carries service-wide Lambda and logging defaults. It is the one required AWS setting — the deploy reads the target account/region from here, and cross-module resolution uses the `serviceInfoMap` to locate sibling services in other accounts/regions/environments. Exactly one `defineAwsServiceAccountInfo` is allowed per config.
+
+- **On AWS:** consumed throughout `quidproquo-deploy-awscdk` and `quidproquo-actionprocessor-awslambda` via `getAwsServiceAccountInfoConfig` and friends. `deployAccountId`/`deployRegion` set the CloudFormation stack env; `apiLayers` become Lambda layer references; `lambdaMaxMemoryInMiB` sets the default function memory; the `disable*` flags toggle X-Ray tracing, reserved concurrency, and the Lambda-warming schedule; `logServiceName`, `disableLogs`, and `instantLogs` drive the logging pipeline. Resources across the `serviceInfoMap` are matched by module/environment/feature/application to resolve cross-service references.
+
+```typescript
+import { defineAwsServiceAccountInfo } from 'quidproquo-config-aws';
+
+export default [
+  defineAwsServiceAccountInfo('123456789012', 'us-east-1'),
+];
+```
+
+## Signature
+
+```typescript
+function defineAwsServiceAccountInfo(
+  deployAccountId: string,
+  deployRegion: string,
+  serviceInfoMap?: ServiceAccountInfo[],
+  options?: QPQConfigAdvancedAwsServiceAccountInfoSettings,
+): AwsServiceAccountInfoQPQConfigSetting;
+```
+
+## Parameters
+
+### `deployAccountId` — `string` (required)
+
+The AWS account id this service deploys into. Sets the CloudFormation stack account and is the default account for the service's own resources.
+
+### `deployRegion` — `string` (required)
+
+The AWS region this service deploys into.
+
+### `serviceInfoMap` — `ServiceAccountInfo[]` (optional, default `[]`)
+
+The account/region (and environment/feature) coordinates of **other** services this one references, so cross-module resource lookups can resolve resources that live in different accounts, regions, environments, or features. The current service's own entry is added automatically. Each entry:
+
+```typescript
+type ServiceAccountInfo = {
+  moduleName: string;
+  applicationName?: string;
+  environment?: string;
+  feature?: string;
+  awsAccountId: string;
+  awsRegion: string;
+};
+```
+
+- **`moduleName`** — the module (service) name being located.
+- **`applicationName` / `environment` / `feature`** — optional narrowing; unset parts match the current service. Cross-service resolution scores candidates by how specifically they match.
+- **`awsAccountId` / `awsRegion`** — where that module is deployed.
+
+### `options` — `QPQConfigAdvancedAwsServiceAccountInfoSettings` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `apiLayers` | `ApiLayer[]` | `[]` | Lambda layers to attach to the service's functions. See [ApiLayer](#apilayer). |
+| `lambdaMaxMemoryInMiB` | `number` | `1024` | Default memory (MiB) for the service's Lambda functions. Individual functions may still override this. |
+| `logServiceName` | `string` | – | The service name used when writing structured logs. |
+| `disableLogs` | `boolean` | `false` | Turn off the log-shipping pipeline for the service. |
+| `disableLambdaWarming` | `boolean` | `false` | Don't create the scheduled warming rule that keeps functions warm. |
+| `disableReservedConcurrency` | `boolean` | `false` | Don't apply reserved concurrency to functions (leaves them on unreserved account concurrency). |
+| `disableTracing` | `boolean` | `false` | Deploy functions with X-Ray tracing set to `DISABLED` instead of `ACTIVE`. |
+| `instantLogs` | `boolean` | `false` | Flush logs immediately rather than batching them (higher cost/visibility trade-off). |
+
+### `ApiLayer`
+
+```typescript
+interface ApiLayer {
+  buildPath?: string;
+  name: string;
+  layerArn?: string;
+}
+```
+
+- **`name`** — identifier for the layer.
+- **`buildPath`** — optional local path to build the layer from.
+- **`layerArn`** — optional ARN of an existing published layer to reference.
+
+## Examples
+
+```typescript
+import { defineAwsServiceAccountInfo } from 'quidproquo-config-aws';
+
+export default [
+  // Minimal: just the deploy target
+  defineAwsServiceAccountInfo('123456789012', 'us-east-1'),
+
+  // With a sibling service in another account and some tuning
+  defineAwsServiceAccountInfo(
+    '123456789012',
+    'us-east-1',
+    [
+      { moduleName: 'billing-service', awsAccountId: '210987654321', awsRegion: 'us-east-1' },
+    ],
+    {
+      lambdaMaxMemoryInMiB: 2048,
+      disableLambdaWarming: true,
+    },
+  ),
+];
+```
+
+## Related
+
+- [defineAwsServiceDashboard](./aws-service-dashboard.md) and [defineAwsAlarm](./aws-alarm.md) — operational monitoring for the service defined here.
+- [defineAwsVirtualNetworkSettings](./aws-virtual-network-settings.md) — VPC tuning for the same service.

package/template/docusaurus/docs/config/config-aws/aws-service-dashboard.md

@@ -0,0 +1,61 @@
+---
+title: defineAwsServiceDashboard
+description: Deploy a ready-made operational CloudWatch dashboard for the service, with anomaly detection.
+---
+
+# defineAwsServiceDashboard
+
+Adds a default operational **CloudWatch dashboard** for this service — a single, config-derived view of its API traffic/errors/latency, Lambda invocations/errors/duration/concurrency, DynamoDB throttles/capacity, queue depth, and WAF allowed/blocked counts. It also enables anomaly detection on API latency and Lambda duration, with latency anomaly alarms routed the same way as the default per-resource alarms. Declare it on a service you want to watch operationally.
+
+- **On AWS:** deploys an `aws_cloudwatch.Dashboard` (`QpqConfigAwsDashboardConstruct` in `quidproquo-deploy-awscdk`). Widgets are built purely from config-derived resource names — API routes, service functions, queue consumers, schedules, and websocket handler Lambdas (infra Lambdas like deploy-event and storage-drive triggers are deliberately excluded). Unless disabled, it also creates anomaly-detector models (free) on API latency and Lambda duration to power the band widgets, plus API latency anomaly alarms that route via [`defineNotifyError`](../core/notify-error.md) (same opt-in and targets as the default resource alarms). Websocket APIs are absent from the metric widgets because their metrics dimension on the AWS-generated API id, which isn't knowable from config.
+
+:::note Cost
+CloudWatch dashboards are roughly US$3/month each beyond the first 3 free per account, so a dashboard per service adds up. Declare this only on services worth watching.
+:::
+
+```typescript
+import { defineAwsServiceDashboard } from 'quidproquo-config-aws';
+
+export default [
+  defineAwsServiceDashboard(),
+];
+```
+
+## Signature
+
+```typescript
+function defineAwsServiceDashboard(
+  options?: Omit<AwsServiceDashboardQPQConfigSetting, 'configSettingType' | 'uniqueKey'>,
+): AwsServiceDashboardQPQConfigSetting;
+```
+
+## Parameters
+
+### `options` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `disableAnomalyDetection` | `boolean` | `false` | Skip the anomaly-detector models, the anomaly-band widgets, and the API latency anomaly alarms. The rest of the dashboard (plain metric widgets) is still deployed. |
+
+:::note
+This is a single, service-wide setting (its `uniqueKey` is fixed) — declare it at most once per service.
+:::
+
+## Examples
+
+```typescript
+import { defineAwsServiceDashboard } from 'quidproquo-config-aws';
+
+export default [
+  // Full dashboard with anomaly detection
+  defineAwsServiceDashboard(),
+
+  // Dashboard without the anomaly-detection models, bands, and alarms
+  defineAwsServiceDashboard({ disableAnomalyDetection: true }),
+];
+```
+
+## Related
+
+- [defineAwsAlarm](./aws-alarm.md) — declare an additional custom alarm on a specific metric.
+- [defineNotifyError](../core/notify-error.md) — the routing target the dashboard's latency anomaly alarms use.

package/template/docusaurus/docs/config/config-aws/aws-virtual-network-settings.md

@@ -0,0 +1,88 @@
+---
+title: defineAwsVirtualNetworkSettings
+description: Tune the AWS VPC (AZs, NAT, endpoints, flow logs) that backs a core virtual network.
+---
+
+# defineAwsVirtualNetworkSettings
+
+Tunes the AWS **VPC** that backs a core [`defineVirtualNetwork(name)`](../core/virtual-network.md). The core define declares the network provider-agnostically; this AWS setting layers on the concrete VPC knobs — availability zones, NAT gateways, gateway/interface endpoints, and flow logs. It is secure-by-default: even when you never declare it, VPCs get flow logs to CloudWatch and the free S3/DynamoDB gateway endpoints. Declare it (keyed by the same network name) only to opt out of a default or to add interface endpoints / NAT / AZ overrides.
+
+- **On AWS:** resolved by `getAwsVirtualNetworkSettings` (falling back to defaults when absent) and applied by `BootstrapQpqCoreVirtualNetworkConstruct` in `quidproquo-deploy-awscdk`. It sets the VPC's `maxAzs` and `natGateways`, adds S3 and DynamoDB gateway endpoints unless disabled, adds any requested interface endpoints (one ENI per AZ, private DNS on), and — unless disabled — creates a flow-log group at `/qpq/vpc-flow-logs/{vpcName}` with the requested retention and traffic type.
+
+```typescript
+import { defineVirtualNetwork } from 'quidproquo-core';
+import { defineAwsVirtualNetworkSettings } from 'quidproquo-config-aws';
+
+export default [
+  defineVirtualNetwork('private-net'),
+
+  // Cheaper non-prod VPC: a single NAT gateway
+  defineAwsVirtualNetworkSettings('private-net', {
+    natGateways: 1,
+  }),
+];
+```
+
+## Signature
+
+```typescript
+function defineAwsVirtualNetworkSettings(
+  virtualNetworkName: string,
+  options?: QPQConfigAdvancedAwsVirtualNetworkSettings,
+): AwsVirtualNetworkQPQConfigSetting;
+```
+
+## Parameters
+
+### `virtualNetworkName` — `string` (required)
+
+The name of the core virtual network these settings apply to — it must match the name passed to `defineVirtualNetwork`. This is also the setting's `uniqueKey`.
+
+### `options` — `QPQConfigAdvancedAwsVirtualNetworkSettings` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `flowLogs` | `AwsVirtualNetworkFlowLogSettings` | flow logs on | VPC flow-log configuration. See [Flow logs](#flow-logs). |
+| `disableS3GatewayEndpoint` | `boolean` | `false` | Skip the free S3 gateway endpoint. Only disable if you have custom route-table requirements. |
+| `disableDynamoDbGatewayEndpoint` | `boolean` | `false` | Skip the free DynamoDB gateway endpoint. |
+| `interfaceEndpoints` | `string[]` | `[]` | AWS service short names to add interface endpoints for, e.g. `['secretsmanager', 'kms']` — resolved to `com.amazonaws.{region}.{name}`. Each costs roughly US$7.30/mo per AZ (~$14.60/mo at the default `maxAzs` 2) plus $0.01/GB, in exchange for that service's traffic never leaving the VPC (and not being billed through NAT). |
+| `natGateways` | `number` | CDK default (one per AZ) | Number of NAT gateways. `undefined` leaves the CDK default untouched (no subnet/NAT churn on already-deployed VPCs). Set to `1` to halve cost in non-prod (trading AZ redundancy for egress). **`0` is rejected** — qpq Lambdas are placed in `PRIVATE_WITH_EGRESS` subnets, which don't exist in a NAT-less VPC (passing `0` throws). Changing this on a deployed VPC replaces its subnets. |
+| `maxAzs` | `number` | `2` | Number of availability zones. Changing this on a deployed VPC replaces its subnets. |
+
+### Flow logs
+
+`AwsVirtualNetworkFlowLogSettings`:
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `disable` | `boolean` | `false` | Turn flow logs off. Flow logs are on unless disabled; CloudWatch ingestion is ~US$0.50/GB (typically cents-to-dollars/month for Lambda-only VPCs). |
+| `retentionDays` | `number` | `365` | CloudWatch log-group retention, rounded **up** to the nearest supported `RetentionDays` value at deploy time. |
+| `trafficType` | `AwsVpcFlowLogTrafficType` | `all` | Which traffic to record. |
+
+**`AwsVpcFlowLogTrafficType`:** `all`, `accept`, `reject`.
+
+## Examples
+
+```typescript
+import { defineVirtualNetwork } from 'quidproquo-core';
+import { defineAwsVirtualNetworkSettings, AwsVpcFlowLogTrafficType } from 'quidproquo-config-aws';
+
+export default [
+  defineVirtualNetwork('data-net'),
+
+  defineAwsVirtualNetworkSettings('data-net', {
+    maxAzs: 3,
+    // Keep Secrets Manager & KMS traffic inside the VPC
+    interfaceEndpoints: ['secretsmanager', 'kms'],
+    flowLogs: {
+      retentionDays: 30,
+      trafficType: AwsVpcFlowLogTrafficType.reject,
+    },
+  }),
+];
+```
+
+## Related
+
+- [defineVirtualNetwork](../core/virtual-network.md) — the core, provider-agnostic network these settings tune. Declare both, keyed by the same name.
+- [defineGraphDatabase](../core/graph-database.md) — an in-network data store that runs inside the tuned VPC.

package/template/docusaurus/docs/config/config-aws/bootstrap-aws-organization.md

@@ -0,0 +1,80 @@
+---
+title: defineBootstrapAwsOrganization
+description: Bootstrap an AWS Organizations organizational unit and its member accounts.
+---
+
+# defineBootstrapAwsOrganization
+
+Bootstraps an **AWS Organizations organizational unit (OU)** and a set of member AWS accounts placed inside it. Use this when standing up the account/organization structure that your applications will later deploy into.
+
+This is an **organization bootstrap setting**: it configures AWS Organizations itself, not a deployed service. It is declared in a bootstrap config and deployed by the bootstrap stack (`BootstrapQpqServiceStack`).
+
+- **On AWS:** deploys an `aws_organizations.CfnOrganizationalUnit` under the given root/parent OU, and one `aws_organizations.CfnAccount` per name in `accountNames`, each placed in the new OU. Member accounts are named `<organizationName>-<accountName>`, given a cross-account access role `account-<accountName>-AccessRole`, and assigned a generated `+`-suffixed email derived from `baseEmailAddress` (e.g. `me+<org>-<account>@example.com`). Deployed by `QpqBootstrapConfigAwsOrganizationConstruct`.
+
+```typescript
+import { defineBootstrapAwsOrganization } from 'quidproquo-config-aws';
+
+export default [
+  defineBootstrapAwsOrganization(
+    'r-abcd',                 // root/parent OU id
+    'aws+billing@example.com', // base email for generated account emails
+    'acme',                    // organization / OU name
+    ['prod', 'staging', 'dev'],// member account names
+  ),
+];
+```
+
+## Signature
+
+```typescript
+function defineBootstrapAwsOrganization(
+  rootAwsOrganizationalUnitId: string,
+  baseEmailAddress: string,
+  name: string,
+  accountNames: string[],
+): AwsOrganizationQPQConfigSetting;
+```
+
+## Parameters
+
+### `rootAwsOrganizationalUnitId` — `string` (required)
+
+The id of the parent OU (typically the organization root, e.g. `r-xxxx`) that the new organizational unit is created under. Also forms part of the setting's `uniqueKey` (`<rootAwsOrganizationalUnitId>-<name>`).
+
+### `baseEmailAddress` — `string` (required)
+
+A base email address used to generate a unique email for each member account. The construct splits it at `@` and produces `<local>+<organizationName>-<accountName>@<domain>` per account, so every AWS account gets a distinct, deliverable root email from a single mailbox.
+
+### `name` — `string` (required)
+
+The organization/OU name. Used as the created OU's name, as the prefix for each member account name (`<name>-<accountName>`), and within the generated account emails and the setting's `uniqueKey`.
+
+### `accountNames` — `string[]` (required)
+
+The member accounts to create inside the OU. Each entry produces one AWS account named `<name>-<accountName>` with an access role `account-<accountName>-AccessRole`.
+
+## Notes
+
+- Creating AWS accounts via CloudFormation is not reversible in the usual sense — removing an account from `accountNames` does not close the AWS account. Treat this as a one-way bootstrap and manage account lifecycle deliberately.
+- The source additionally sketches (currently commented out) support for per-account user access and an IAM Identity Center (SSO) admin permission set; those are not created by the current implementation.
+
+## Examples
+
+```typescript
+import { defineBootstrapAwsOrganization } from 'quidproquo-config-aws';
+
+export default [
+  defineBootstrapAwsOrganization(
+    'r-abcd',
+    'aws-ops@example.com',
+    'acme',
+    ['prod', 'staging', 'sandbox'],
+  ),
+];
+```
+
+## Related
+
+- [defineBootstrapWaf](./bootstrap-waf.md) — another bootstrap-phase setting deployed by the same `BootstrapQpqServiceStack`.
+- [defineAccountBudget](./account-budget.md), [defineAccountCloudTrail](./account-cloud-trail.md), [defineAccountSecurityServices](./account-security-services.md) — account-level settings applied per member account (from that account's own account config).
+- **AWS implementation:** `QpqBootstrapConfigAwsOrganizationConstruct` (Organizations OU + member accounts) in `quidproquo-deploy-awscdk`.

package/template/docusaurus/docs/config/config-aws/bootstrap-waf.md

@@ -0,0 +1,106 @@
+---
+title: defineBootstrapWaf
+description: Bootstrap the shared AWS WAF web ACLs (regional + CloudFront) for an app/environment that services opt into.
+---
+
+# defineBootstrapWaf
+
+Bootstraps the **shared AWS WAF (WAFv2) web ACLs** for an app + environment: a REGIONAL web ACL (for API Gateway stages) and a CLOUDFRONT web ACL (for CloudFront distributions). Both evaluate the same set of rules. Individual services then opt into protection with `defineWafProtection` in their config.
+
+This is a **bootstrap setting**: it is created once during the bootstrap phase for the whole app/environment rather than per-service. It is declared in a bootstrap config and deployed by the bootstrap stack (`BootstrapQpqServiceStack`). There is a single `defineBootstrapWaf` per config (its `uniqueKey` is the constant `'bootstrapWaf'`).
+
+- **On AWS:** deploys two `aws_wafv2.CfnWebACL`s with `defaultAction: allow` and shared rules. The REGIONAL ACL (`qpq-waf-regional-<app>-<env>`) is created by `QpqBootstrapConfigWafConstruct` in the bootstrap stack and publishes its ARN to SSM; each service's API stack attaches via a `WebACLAssociation`. The CLOUDFRONT ACL (`qpq-waf-cloudfront-<app>-<env>`) must live in `us-east-1`, so it is a sibling stack (`WafCloudFrontWebAclStack`) that hands its ARN back to the deploy region via SSM (directly if deploying to `us-east-1`, otherwise via a cross-region `AwsCustomResource`). CloudWatch metrics and sampled requests are enabled on every rule.
+
+```typescript
+import { defineBootstrapWaf } from 'quidproquo-config-aws';
+
+export default [
+  defineBootstrapWaf(),
+];
+```
+
+## Signature
+
+```typescript
+function defineBootstrapWaf(
+  options?: {
+    managedRuleGroups?: WafManagedRuleGroup[];
+    rateLimits?: WafRateLimit[];
+  },
+): BootstrapWafQPQConfigSetting;
+```
+
+## Parameters
+
+### `options` — (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `managedRuleGroups` | `WafManagedRuleGroup[]` | `[common, knownBadInputs, sqli]` | AWS-managed rule groups to enable, each added as a managed-rule-group statement with `overrideAction: none`. See [`WafManagedRuleGroup`](#wafmanagedrulegroup). |
+| `rateLimits` | `WafRateLimit[]` | `[]` (none) | Rate-based blocking rules (e.g. brute-force throttling on auth endpoints). Evaluated **before** the managed rule groups. See [`WafRateLimit`](#wafratelimit). |
+
+### `WafManagedRuleGroup`
+
+```typescript
+export enum WafManagedRuleGroup {
+  common = 'common',                 // AWSManagedRulesCommonRuleSet
+  knownBadInputs = 'knownBadInputs', // AWSManagedRulesKnownBadInputsRuleSet
+  sqli = 'sqli',                     // AWSManagedRulesSQLiRuleSet
+  ipReputation = 'ipReputation',     // AWSManagedRulesAmazonIpReputationList
+}
+```
+
+| Member | AWS managed rule set |
+| --- | --- |
+| `common` | `AWSManagedRulesCommonRuleSet` — broad OWASP-style protections. |
+| `knownBadInputs` | `AWSManagedRulesKnownBadInputsRuleSet` — blocks request patterns known to be malicious. |
+| `sqli` | `AWSManagedRulesSQLiRuleSet` — SQL-injection protections. |
+| `ipReputation` | `AWSManagedRulesAmazonIpReputationList` — Amazon IP reputation list. |
+
+### `WafRateLimit`
+
+```typescript
+export interface WafRateLimit {
+  name: string;
+  limit: number;
+  uriPathStartsWith?: string;
+}
+```
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Rule name (used to build the WAF rule and metric names, e.g. `rate-limit-<name>`). |
+| `limit` | `number` | Maximum requests per 5-minute window per source IP before that IP is blocked (`aggregateKeyType: IP`). |
+| `uriPathStartsWith` | `string` | Optional. Scope the rate limit to URI paths with this prefix (e.g. `/auth`) via a scope-down byte-match statement. Omit to rate limit all paths. |
+
+## Notes
+
+- Rate-limit rules are given the lowest priorities (evaluated first as cheap counters), then the managed rule groups follow.
+- To actually apply these ACLs, a service opts in with `defineWafProtection()` in its (shared) service config; the ACL ARNs are resolved by convention from SSM at deploy time, so the bootstrap must be deployed before the service's API/web stacks.
+
+## Examples
+
+```typescript
+import { defineBootstrapWaf, WafManagedRuleGroup } from 'quidproquo-config-aws';
+
+export default [
+  defineBootstrapWaf({
+    managedRuleGroups: [
+      WafManagedRuleGroup.common,
+      WafManagedRuleGroup.knownBadInputs,
+      WafManagedRuleGroup.sqli,
+      WafManagedRuleGroup.ipReputation,
+    ],
+    rateLimits: [
+      { name: 'auth-brute-force', limit: 100, uriPathStartsWith: '/auth' },
+      { name: 'global', limit: 5000 },
+    ],
+  }),
+];
+```
+
+## Related
+
+- [defineWafProtection](./waf-protection.md) — a per-service setting that opts a service's API Gateway stage and CloudFront distributions into these web ACLs.
+- [defineBootstrapAwsOrganization](./bootstrap-aws-organization.md) — another bootstrap-phase setting deployed by the same `BootstrapQpqServiceStack`.
+- **AWS implementation:** `QpqBootstrapConfigWafConstruct` (regional ACL) and `WafCloudFrontWebAclStack` (CloudFront ACL in us-east-1), with shared rule building in `wafRules.ts`, in `quidproquo-deploy-awscdk`.

package/template/docusaurus/docs/config/config-aws/domain-certificate.md

@@ -0,0 +1,69 @@
+---
+title: defineDomainCertificate
+description: Issue a real ACM certificate with DNS validation for a root domain and its subdomains.
+---
+
+# defineDomainCertificate
+
+Issues a real **ACM (AWS Certificate Manager) certificate**, DNS-validated against a Route 53 hosted zone, for a root domain and a set of subdomains. This is the concrete certificate that API Gateway and CloudFront distributions use for HTTPS. The webserver [`defineCertificate`](../webserver/certificate.md) is a portable shim that ultimately defers to a domain certificate like this one on AWS.
+
+- **On AWS:** each unique `(region, rootDomain)` becomes a `DomainCertificateStack` (via `createDomainCertificateStacks` in `quidproquo-deploy-awscdk`). The stack resolves the root domain through the same environment/feature prefixing as [`defineApi`](../webserver/api.md) (`resolveDomainRoot`), so `rootDomain: "example.com"` in a dev deploy issues against `development.example.com`. It looks up the hosted zone, creates an `aws_certificatemanager.Certificate` with `CertificateValidation.fromDns(...)` covering the resolved subdomains (and the apex when `includeApex`), and publishes the cert ARN to SSM (keyed by region + root domain) — writing cross-region via a custom resource when the cert region differs from the deploy region. Entries sharing a `(region, rootDomain)` are merged into one cert covering the union of their names.
+
+```typescript
+import { defineDomainCertificate } from 'quidproquo-config-aws';
+
+export default [
+  // A cert for api.example.com and admin.example.com in the deploy region
+  defineDomainCertificate('example.com', 'us-east-1', ['api', 'admin']),
+];
+```
+
+## Signature
+
+```typescript
+function defineDomainCertificate(
+  rootDomain: string,
+  region: string,
+  subdomains: string[],
+  options?: { includeApex?: boolean },
+): DomainCertificateQPQConfigSetting;
+```
+
+## Parameters
+
+### `rootDomain` — `string` (required)
+
+The base, un-prefixed apex domain — the same value you pass to `defineApi` / web-entry `rootDomain` fields. At synth time it is resolved against the config's environment and feature (a dev deploy of `"example.com"` becomes `development.example.com`, or `myfeature.development.example.com`). Together with `region` it forms the setting's `uniqueKey`.
+
+### `region` — `string` (required)
+
+The AWS region to issue the certificate in. CloudFront requires certificates in `us-east-1`, while regional API Gateway certs live in the deploy region — declaring both for the same apex is a valid, merged case.
+
+### `subdomains` — `string[]` (required)
+
+The subdomain labels to cover, each combined with the resolved apex (e.g. `'api'` → `api.<resolved-apex>`). At least one subdomain must be declared unless `includeApex` is `true`, or synth throws.
+
+### `options` — `{ includeApex?: boolean }` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `includeApex` | `boolean` | `false` | Also cover the resolved apex domain itself (in addition to the subdomains). Merged entries OR this flag together. |
+
+## Examples
+
+```typescript
+import { defineDomainCertificate } from 'quidproquo-config-aws';
+
+export default [
+  // Regional API cert in the deploy region
+  defineDomainCertificate('example.com', 'us-east-1', ['api']),
+
+  // CloudFront cert (must be us-east-1) covering the apex and www
+  defineDomainCertificate('example.com', 'us-east-1', ['www'], { includeApex: true }),
+];
+```
+
+## Related
+
+- [defineCertificate](../webserver/certificate.md) — the portable webserver shim that defers to this real ACM certificate on AWS.
+- [defineApi](../webserver/api.md) — its `rootDomain` uses the same resolution as this certificate's `rootDomain`.

package/template/docusaurus/docs/config/config-aws/event-bus-quick-subscription.md

@@ -0,0 +1,84 @@
+---
+title: defineEventBusQuickSubscription
+description: Attach direct SNS email or webhook subscribers to an event bus, with no compute in between.
+---
+
+# defineEventBusQuickSubscription
+
+Attaches **direct SNS subscribers** — an email address or an incident-tool webhook URL — to a core [event bus](../core/event-bus.md), with no queue or Lambda in between. It's for a bus used as an alert channel: messages published to the bus (for example alarm-state changes routed via `onAlarm.publishToEventBus`) reach a human out-of-band, without depending on the service's own compute being healthy. For rich, in-band handling, use the normal bus → queue → function pattern instead.
+
+This is an AWS-specific convenience — direct email/webhook delivery is an SNS feature, not a portable event-bus concept — which is why it lives in `quidproquo-config-aws` rather than on core's [`defineEventBus`](../core/event-bus.md).
+
+- **On AWS:** resolved by `getEventBusQuickSubscriptions` and applied in `QpqCoreEventBusConstruct` (`quidproquo-deploy-awscdk`) to the bus's SNS topic. An `email` subscription adds an `EmailSubscription`; a `url` subscription adds a `UrlSubscription` (http vs https auto-detected from the URL). Multiple calls for the same bus are additive. Quick subscriptions are **not** supported on FIFO event buses (SNS FIFO topics only allow SQS subscriptions) — declaring one there fails the deploy.
+
+```typescript
+import { defineEventBus } from 'quidproquo-core';
+import { defineEventBusQuickSubscription, EventBusQuickSubscriptionType } from 'quidproquo-config-aws';
+
+export default [
+  defineEventBus('ops-alerts'),
+
+  defineEventBusQuickSubscription('ops-alerts', [
+    { type: EventBusQuickSubscriptionType.email, email: 'oncall@example.com' },
+  ]),
+];
+```
+
+## Signature
+
+```typescript
+function defineEventBusQuickSubscription(
+  eventBusName: string,
+  subscriptions: EventBusQuickSubscription[],
+  options?: QPQConfigAdvancedEventBusQuickSubscriptionSettings,
+): EventBusQuickSubscriptionQPQConfigSetting;
+```
+
+## Parameters
+
+### `eventBusName` — `string` (required)
+
+The name of the event bus to attach subscribers to (the setting's `uniqueKey`). Matches the name passed to `defineEventBus`.
+
+### `subscriptions` — `EventBusQuickSubscription[]` (required)
+
+The endpoints SNS delivers to directly. Each is a discriminated union on `type`:
+
+```typescript
+type EventBusQuickSubscription =
+  | { type: EventBusQuickSubscriptionType.email; email: string }
+  | { type: EventBusQuickSubscriptionType.url; url: string };
+```
+
+| `type` | Field | Delivery |
+| --- | --- | --- |
+| `EventBusQuickSubscriptionType.email` | `email` | Sends an email to the address (SNS email confirmation applies). |
+| `EventBusQuickSubscriptionType.url` | `url` | POSTs to an incident-tool webhook (PagerDuty / Slack / OpsGenie); http/https auto-detected from the URL prefix. |
+
+### `options` — `QPQConfigAdvancedEventBusQuickSubscriptionSettings` (optional)
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `owner` | `CrossModuleOwner<'eventBusName'>` | – | The module that owns the target bus when it lives in another service (mirror the `owner` you pass to `defineEventBus`). The subscription then binds only to that owner's bus, so a same-named bus owned by a different module won't accidentally pick it up. Omit for a bus owned by this service. |
+
+## Examples
+
+```typescript
+import { defineEventBus } from 'quidproquo-core';
+import { defineEventBusQuickSubscription, EventBusQuickSubscriptionType } from 'quidproquo-config-aws';
+
+export default [
+  defineEventBus('ops-alerts'),
+
+  // Email plus a Slack/PagerDuty webhook — additive across calls
+  defineEventBusQuickSubscription('ops-alerts', [
+    { type: EventBusQuickSubscriptionType.email, email: 'oncall@example.com' },
+    { type: EventBusQuickSubscriptionType.url, url: 'https://hooks.example.com/incident' },
+  ]),
+];
+```
+
+## Related
+
+- [defineEventBus](../core/event-bus.md) — the core bus these subscribers attach to.
+- [defineAwsAlarm](./aws-alarm.md) — publish alarm state to the bus (via `onAlarm.publishToEventBus`) so these subscribers get notified.

package/template/docusaurus/docs/config/config-aws/waf-protection.md

@@ -0,0 +1,45 @@
+---
+title: defineWafProtection
+description: Opt a service's API Gateway stage and CloudFront distributions into the app's WAF web ACLs.
+---
+
+# defineWafProtection
+
+Opts this service into the **WAF (web application firewall)** web ACLs created for the app. The web ACLs themselves are provisioned once, in the bootstrap phase, by [`defineBootstrapWaf`](./bootstrap-waf.md) (a regional ACL for API Gateway and a CloudFront ACL in `us-east-1`). This setting is what associates a service's API Gateway stage and CloudFront distributions with those ACLs. It's a separate setting because service configs and the bootstrap config are separate arrays — the ACL ARNs are resolved by convention from SSM at deploy time (so the bootstrap WAF must be deployed first).
+
+- **On AWS:** flagged by `isWafProtectionEnabled` and consumed in `quidproquo-deploy-awscdk`. `ApiQpqWebserverApiConstruct` creates a `CfnWebACLAssociation` between the API Gateway stage and the regional web ACL ARN (read from SSM); `WebQpqWebserverWebEntryConstruct` sets the CloudFront distribution's `webAclId` to the CloudFront web ACL ARN (also from SSM). Without a bootstrap WAF deployed, there are no ACL ARNs to resolve.
+
+```typescript
+import { defineWafProtection } from 'quidproquo-config-aws';
+
+export default [
+  defineWafProtection(),
+];
+```
+
+## Signature
+
+```typescript
+function defineWafProtection(): WafProtectionQPQConfigSetting;
+```
+
+## Parameters
+
+This define takes no arguments — it's a presence flag. Include it in a service's config to attach that service's API Gateway stage and CloudFront distributions to the app's WAF web ACLs; omit it to leave the service unprotected. The rule content (managed rule groups, rate limits) is configured on the bootstrap side via [`defineBootstrapWaf`](./bootstrap-waf.md), not here.
+
+## Examples
+
+```typescript
+import { defineWafProtection } from 'quidproquo-config-aws';
+
+// A shared service config module
+export default [
+  // ...other settings...
+  defineWafProtection(),
+];
+```
+
+## Related
+
+- [defineBootstrapWaf](./bootstrap-waf.md) — creates the regional and CloudFront web ACLs, and configures their managed rule groups and rate limits, in the bootstrap config.
+- [defineApi](../webserver/api.md) — the API Gateway stage that gets the regional ACL association.

package/template/docusaurus/docs/config/core/_category_.json

@@ -0,0 +1,8 @@
+{
+  "label": "quidproquo-core",
+  "position": 1,
+  "link": {
+    "type": "generated-index",
+    "description": "Config settings (define* functions) exported from quidproquo-core."
+  }
+}