@aws/nx-plugin-mcp 1.0.0-rc.9 → 1.0.0-rc.91

package/docs/guides/runtime-config.mdx

@@ -12,17 +12,19 @@ Runtime configuration is the mechanism used by Nx Plugin for AWS to pass deploy-
 
 Runtime configuration is organised into **namespaces**. Each namespace is a logical grouping of related configuration values. At deploy time, all namespaces are stored in **AWS AppConfig** as Configuration Profiles.
 
-Two built-in namespaces are used by generated constructs:
+Four built-in namespaces are used by generated constructs:
 
 - **`connection`** — configuration that enables generated projects to connect to each other:
   - **API URLs** — registered automatically by API constructs
   - **Cognito settings** — registered automatically by the UserIdentity construct
   - **Agent runtime ARNs** — added by the connection generator when you connect a React website to an Agent
 - **`agentcore`** — AgentCore runtime ARNs for agents and MCP servers. Registered automatically by the agent/MCP constructs and used for server-side discovery (agent → agent via A2A, agent → MCP server).
+- **`dynamodb`** — table names, registered automatically by DynamoDB table constructs and read by the generated table client.
+- **`database`** — Aurora connection details, registered automatically by relational database constructs and read by the generated database client.
 
-The `connection` namespace is also deployed as a `runtime-config.json` file to your website's S3 bucket, enabling client-side discovery of backend resources. The `agentcore` namespace is server-side only (via AppConfig) so agent runtime ARNs are not exposed to the frontend unless you explicitly connect a website to an agent.
+The `connection` namespace is also deployed as a `runtime-config.json` file to your website's S3 bucket, enabling client-side discovery of backend resources. The other namespaces are server-side only (via AppConfig), so values such as agent runtime ARNs and table names are not exposed to the frontend unless you explicitly connect a website to them.
 
-You can define as many additional namespaces as you like, providing a convenient alternative to environment variables for passing deploy-time values such as DynamoDB table names to your Lambda functions or other compute resources.
+You can define as many additional namespaces as you like, providing a convenient alternative to environment variables for passing deploy-time values to your Lambda functions or other compute resources.
 
 ```d2
 direction: down
@@ -70,7 +72,7 @@ Generated constructs automatically write relevant configuration to the `connecti
 The `RuntimeConfig` CDK construct is a stage-scoped singleton. Use `set()` to write a key into a namespace:
 
 ```ts title="packages/infra/src/stacks/application-stack.ts"
-import { RuntimeConfig } from ':my-scope/common-constructs';
+import { RuntimeConfig } from '@my-scope/common-constructs';
 
 const rc = RuntimeConfig.ensure(this);
 
@@ -107,6 +109,17 @@ Terraform wires runtime configuration across three `core/runtime-config/*` modul
    }
    ```
 
+   The `namespaces` variable defaults to every built-in namespace, so generated modules work without configuring it. To add namespaces of your own, list them alongside the built-in ones:
+
+   ```hcl title="packages/infra/src/main.tf"
+   module "runtime_config_appconfig" {
+     source = "../../common/terraform/src/core/runtime-config/appconfig"
+
+     application_name = "my-app-runtime-config"
+     namespaces       = ["connection", "agentcore", "database", "dynamodb", "tables"]
+   }
+   ```
+
 2. **`core/runtime-config/entry`** — one invocation per contribution. Generated API, agent and MCP modules call this internally to publish their URLs and ARNs. Call it directly to publish custom configuration.
 
    ```hcl title="packages/infra/src/main.tf"

package/docs/guides/security.mdx

@@ -0,0 +1,75 @@
+---
+title: Security
+description: Security features included in projects generated by the Nx Plugin for AWS
+---
+
+import Link from '@components/link.astro';
+
+:::caution[Reporting Security Issues]
+To report a potential security issue in the Nx Plugin for AWS itself, please refer to [SECURITY.md](https://github.com/awslabs/nx-plugin-for-aws/blob/main/SECURITY.md) — do not create a public GitHub issue.
+:::
+
+## Security Controls
+
+Projects scaffolded by the Nx Plugin for AWS include a number of security controls out of the box. This page provides an overview of those controls and links to the relevant guides for more detail.
+
+### Infrastructure Scanning
+
+Infrastructure projects are configured with [Checkov](https://www.checkov.io/) as part of the `build` target, so insecure infrastructure configuration fails the build:
+
+- CDK projects synthesize CloudFormation templates which are scanned by Checkov. See <Link path="/guides/typescript-infrastructure#security-testing">Security Testing</Link> for details.
+- Terraform projects run Checkov directly against your Terraform code. See <Link path="/guides/terraform-project">Terraform Projects</Link>.
+
+Where vended infrastructure suppresses a Checkov rule, the suppression is scoped to the specific resource and annotated with a justification. The shared `suppressRules` helper requires a reason for every suppression, and we recommend following the same practice in your own code. See <Link path="/guides/typescript-infrastructure#suppressing-checkov-checks">Suppressing Checkov Checks</Link>.
+
+### Container Image Scanning
+
+Projects which build container images (for example agents, MCP servers, and database migration images) include a `trivy` target which scans images for HIGH and CRITICAL vulnerabilities, exiting non-zero on findings. See <Link path="/guides/docker-bundling">Docker Bundling</Link> for details, including how to suppress findings with a `.trivyignore` file.
+
+### Credential Scanning
+
+Workspaces include [git-secrets](https://github.com/awslabs/git-secrets) pre-commit hooks which scan staged files for AWS credential patterns, preventing accidental commits of access keys and other sensitive values. See the <Link path="/guides/workspace#git-secrets">Git Secrets</Link> section of the workspace guide.
+
+### Authentication
+
+APIs, agents, and MCP servers use AWS IAM (SigV4) authentication by default:
+
+- <Link path="/guides/trpc">tRPC</Link>, <Link path="/guides/fastapi">FastAPI</Link>, and <Link path="/guides/ts-smithy-api">Smithy</Link> APIs default to IAM authentication, with Cognito and custom authorizers available as options. The vended custom authorizer stub denies requests by default.
+- <Link path="/guides/ts-agent">Agents</Link> and <Link path="/guides/ts-mcp-server">MCP servers</Link> deployed to Amazon Bedrock AgentCore Runtime use IAM (SigV4) authentication by default, with JWT-based Cognito authentication as an option.
+- The <Link path="/guides/react-website-auth">website auth generator</Link> vends an Amazon Cognito user pool with multi-factor authentication (MFA) required, a strong password policy, and deletion protection enabled.
+
+### Encryption
+
+Vended infrastructure encrypts data in transit and at rest:
+
+- Websites are served via CloudFront with HTTP redirected to HTTPS, and a response headers policy including HTTP Strict Transport Security (HSTS), a Content Security Policy, and other <Link path="/guides/react-website#security-headers">security headers</Link>. A WAF with AWS managed rules is associated with the distribution.
+- S3 buckets block all public access, enforce SSL-only access via bucket policies, are encrypted (KMS with key rotation for website content), and deliver server access logs to CloudWatch log groups encrypted with customer-managed KMS keys, where they can be queried with Logs Insights and alarmed on.
+- API access logs are written to CloudWatch log groups encrypted with customer-managed KMS keys with rotation enabled.
+- <Link path="/guides/ts-rdb">Aurora databases</Link> enable storage encryption with a customer-managed KMS key, generate credentials in AWS Secrets Manager (never hardcoded), and support automatic credential rotation.
+
+### Least Privilege
+
+Vended CDK constructs and Terraform modules follow least privilege:
+
+- Constructs expose `grant*` methods (for example `grantInvokeAccess` on APIs and agents, `grantConnect` on databases) so consumers grant only the access they need.
+- IAM policies in vended infrastructure are scoped to specific resources and actions. Where a wildcard resource is required by the AWS service (for example `ecr:GetAuthorizationToken`), it is limited to those actions and scoped with conditions where supported.
+
+### Dependency Licensing
+
+The <Link path="/guides/license">license generator</Link> configures automated license header management and dependency license checking against an allowlist of approved licenses, helping you catch problematic transitive dependencies before they ship.
+
+## Responsibility
+
+Security and compliance is a shared responsibility. AWS describes this through the [Shared Responsibility Model](https://aws.amazon.com/compliance/shared-responsibility-model/), which distinguishes between security *of* the cloud (the responsibility of AWS) and security *in* the cloud (your responsibility as the customer).
+
+The Nx Plugin for AWS helps you address parts of your side of that model. Its generators vend secure foundations and encode AWS best practices within the scope of the code they produce — the controls described above. This reduces the effort required to build securely, but it does not transfer ownership of security to the plugin.
+
+**You own the code that is generated into your workspace and remain responsible for its security.** Once vended, generated code is yours to modify, extend, and operate, and it must be treated the same as any other code you author.
+
+In particular:
+
+- **The scope of the plugin is limited to its generators.** The plugin has no knowledge of your application's business logic, data classification, threat model, or regulatory obligations, and cannot make decisions that depend on them.
+- **Authentication is configured, but authorization is not.** APIs are protected with authentication by default (for example IAM/SigV4), but the plugin cannot determine *which* authenticated principals should be permitted to perform *which* operations on *which* resources. Fine-grained authorization depends on your business logic and must be designed, implemented, and tested by you.
+- **Generated code is a starting point, not a finished product.** As you add functionality, you introduce security considerations the plugin cannot anticipate — input validation, data handling, secrets management, dependency choices, and integrations with other systems.
+
+Accordingly, you should review generated code and the applications you build on top of it in line with your own organisation's security policies, standards, and review processes, and subject them to the same threat modelling, security testing, and approval gates you apply to any production workload. The controls vended by the plugin are intended to complement those processes, not to replace them.

package/docs/guides/smithy-project.mdx

@@ -0,0 +1,167 @@
+---
+title: Smithy Projects
+description: Reference documentation for the Smithy project generator
+generator: smithy#project
+---
+import { FileTree, Steps } from '@astrojs/starlight/components';
+import RunGenerator from '@components/run-generator.astro';
+import Link from '@components/link.astro';
+import GeneratorParameters from '@components/generator-parameters.astro';
+import NxCommands from '@components/nx-commands.astro';
+import OptionFilter from '@components/option-filter.astro';
+
+[Smithy](https://smithy.io/) is an interface definition language for describing services and the data they exchange. The Smithy project generator creates a project containing a Smithy model.
+
+There are two kinds of Smithy project:
+
+- **Service** (`--type=service`) — a model which defines a service and its operations. This is what the <Link path="guides/ts-smithy-api">`ts#api --framework=smithy` generator</Link> creates for you alongside a TypeScript implementation.
+- **Shape library** (`--type=shapes`) — a model which defines reusable shapes but no service. Connect a shape library to your Smithy projects to share shapes between them, rather than duplicating the definitions in each.
+
+:::tip
+If you want an API with an implementation, use the <Link path="guides/ts-smithy-api">`ts#api` generator</Link> instead. It creates a Smithy model project _and_ a TypeScript server which implements it.
+:::
+
+## Usage
+
+### Generate a Smithy Project
+
+<RunGenerator generator="smithy#project" requiredParameters={{ name: 'my-shapes' }} />
+
+### Options
+
+<GeneratorParameters generator="smithy#project" />
+
+## Generator Output
+
+<OptionFilter when={{ type: 'shapes' }} description="Shape library: a model with no service">
+
+### Shape Library
+
+<FileTree>
+
+  - my-shapes
+    - src
+      - main.smithy Your shared shape definitions
+    - smithy-build.json Smithy build configuration
+    - project.json Project configuration and build targets
+
+</FileTree>
+
+A shape library defines shapes and nothing else:
+
+```smithy
+$version: "2.0"
+
+namespace com.example
+
+structure Customer {
+    @required
+    id: String
+
+    name: String
+    email: String
+}
+```
+
+Since a shape library has no service, its `smithy-build.json` configures no code generation — building it validates the model and assembles it into a single JSON model file at `dist/<my-shapes>/build/model.json`.
+
+</OptionFilter>
+
+<OptionFilter when={{ type: 'service' }} description="Service: a model which defines a service and its operations">
+
+### Service
+
+<FileTree>
+
+  - my-service
+    - src
+      - main.smithy Your service definition
+      - operations
+        - echo.smithy An example operation
+    - smithy-build.json Smithy build configuration, including code generation
+    - ssdk.rolldown.config.mjs Bundles the generated TypeScript Server SDK
+    - project.json Project configuration and build targets
+
+</FileTree>
+
+A service model defines a service shape and the operations it exposes:
+
+```smithy
+$version: "2.0"
+
+namespace com.example
+
+use aws.protocols#restJson1
+
+@title("MyService")
+@restJson1
+service MyService {
+    version: "1.0.0"
+    operations: [
+        Echo
+    ]
+}
+```
+
+Building a service project generates an OpenAPI specification and a TypeScript Server SDK into `dist/<my-service>/build/`.
+
+</OptionFilter>
+
+## Building
+
+Smithy projects build with the [Smithy CLI](https://smithy.io/2.0/guides/smithy-cli/index.html), which validates your model:
+
+<NxCommands commands={['build my-shapes']} />
+
+On macOS and Linux the CLI is resolved by [mise](https://mise.jdx.dev/), which the build fetches on demand, so there is nothing to install — it downloads and caches the pinned version the first time you build. On Windows it is a prerequisite you install yourself — see <Link path="guides/ts-smithy-api#building-on-windows">Building on Windows</Link>.
+
+## Depending on a Shape Library
+
+Building a shape library writes an assembled model to `dist/<my-shapes>/build/model.json`. This single file contains every shape the library defines, along with any it depends on, so a consumer only ever declares the libraries it references directly.
+
+To depend on a shape library from another Smithy project, make two changes to the consuming project:
+
+<Steps>
+
+1. Add the library's built model to `imports` in the consuming project's `smithy-build.json`. Paths are relative to that file, so the number of `../` segments matches how deeply the consuming project is nested — three for `packages/my-api/model` below:
+
+   ```json ins={4}
+   {
+     "version": "1.0",
+     "sources": ["src/"],
+     "imports": ["../../../dist/packages/my-shapes/build/model.json"],
+     ...
+   }
+   ```
+
+2. Add the library's `build` target as a dependency of the consuming project's `compile` target in its `project.json`, so the model exists before the consumer builds:
+
+   ```json ins={4}
+   {
+     "targets": {
+       "compile": {
+         "dependsOn": ["@my-scope/my-shapes:build"],
+         ...
+       }
+     }
+   }
+   ```
+
+</Steps>
+
+Your model can now reference the library's shapes with `use`:
+
+```smithy
+$version: "2.0"
+
+namespace com.example.api
+
+use com.example.shared#Customer
+
+structure GetCustomerOutput {
+    @required
+    customer: Customer
+}
+```
+
+Shape libraries can depend on other shape libraries the same way. Since each library's built model already contains its own dependencies, you only need to repeat these steps for the libraries you reference directly. A library reached by more than one path is resolved once — Smithy ignores duplicate but equivalent shape definitions.

package/docs/guides/terraform-project.mdx

@@ -9,6 +9,7 @@ import Link from '@components/link.astro';
 import GeneratorParameters from '@components/generator-parameters.astro';
 import NxCommands from '@components/nx-commands.astro';
 import OptionFilter from '@components/option-filter.astro';
+import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
 
 [Terraform](https://www.terraform.io/) is an open-source infrastructure as code software tool that enables you to safely and predictably create, change, and improve infrastructure.
 
@@ -48,10 +49,13 @@ For application projects (`--type=application`), the generator creates a complet
     - main.tf S3 bucket and policies for state storage
     - providers.tf AWS provider configuration
     - variables.tf Bootstrap variable definitions
-  - scripts Node helpers run by the nx `bootstrap` and `init` targets
+  - scripts Node helpers run by the nx `bootstrap`, `bootstrap-destroy` and `init` targets
     - aws-config.ts Resolves account + region via the AWS SDK credential chain
     - bootstrap.ts Pulls/pushes the bootstrap tfstate and runs `terraform apply`
+    - bootstrap-destroy.ts Empties the state bucket and runs `terraform destroy`
     - init.ts Runs `terraform init` with the S3 backend config
+    - env.ts Points `terraform init` at the shared provider cache
+  - checkov.yml Checkov configuration, including the checks to skip
   - project.json Project configuration and build targets
 
 </FileTree>
@@ -71,6 +75,7 @@ For library projects (`--type=library`), the generator creates a simpler structu
 
   - src
     - main.tf Main Terraform module file
+  - checkov.yml Checkov configuration, including the checks to skip
   - project.json Project configuration and build targets
 
 </FileTree>
@@ -84,7 +89,7 @@ Application projects include full deployment capabilities with remote state mana
 
 You can start writing your Terraform infrastructure inside `src/main.tf`, for example:
 
-```diff title="src/main.tf" {2-4}
+```diff title="src/main.tf" {16-19}
 -locals {
 -  account_id = data.aws_caller_identity.current.account_id
 -  aws_region = data.aws_region.current.id
@@ -108,7 +113,7 @@ You can start writing your Terraform infrastructure inside `src/main.tf`, for ex
 
 ### Cross project dependencies
 
-If you wanted to execute a module from a seperate project (lib), you could do so as follows:
+If you wanted to execute a module from a separate project (lib), you could do so as follows:
 
 ```
 module "lib_module" {
@@ -242,20 +247,114 @@ You can validate your Terraform configuration using the `validate` target:
 
 <NxCommands commands={['validate tf-infra']} />
 
-#### Formatting your Code
+#### Linting
 
-Format your Terraform code using the `fmt` target:
+Terraform projects use [`terraform fmt`](https://developer.hashicorp.com/terraform/cli/commands/fmt) to check formatting.
 
-<NxCommands commands={['fmt tf-infra']} />
+##### Running the Linter
+
+To invoke the linter to check your project, you can run the `lint` target.
+
+<NxCommands commands={["lint tf-infra"]} />
+
+##### Fixing Lint Issues
+
+The majority of linting or formatting issues can be fixed automatically by running with the `--configuration=fix` argument.
+
+<NxCommands commands={["lint tf-infra --configuration=fix"]} />
+
+Similarly if you would like to fix all lint issues in all packages in your workspace, you can run:
+
+<NxCommands commands={["run-many --target lint --all --configuration=fix"]} />
+
+:::tip[Shorthand Command]
+This has a shorthand command from the root of your workspace:
+
+<PackageManagerShortCommand commands={["lint"]} />
+:::
+
+##### Skipping Lint Issues
+
+To avoid linting issues slowing you down during development (particularly if you have non auto-fixable issues in your project), you can run a build with the `skip-lint` configuration:
+
+<NxCommands commands={["run-many --target build --configuration=skip-lint"]} />
+
+This skips the format check entirely during build.
+
+:::tip[Shorthand Command]
+This has a shorthand command from the root of your workspace:
+
+<PackageManagerShortCommand commands={["build:skip-lint"]} />
+:::
 
 #### Security Testing
 
-Run security checks on your infrastructure using Checkov with the `test` target:
+Run security checks on your infrastructure using Checkov with the `checkov` target:
 
-<NxCommands commands={['test tf-infra']} />
+<NxCommands commands={['checkov tf-infra']} />
 
 You will find your security test results in the root `dist` folder, under `dist/packages/<my-terraform-project>/checkov`.
 
+Checkov runs as part of `build`.
+
+Checks are configured in the project's `checkov.yml`. Add a check id to `skip-check` to suppress it across the whole project:
+
+```yaml title="checkov.yml"
+skip-check:
+  - CKV_AWS_115 # Concurrent execution limit
+  - CKV_AWS_116 # Dead Letter Queue
+```
+
+To suppress a check for a single resource instead, add a `#checkov:skip=<id>:<reason>` comment inside the resource block:
+
+```hcl
+resource "aws_s3_bucket" "example" {
+  #checkov:skip=CKV_AWS_18:Access logging not required for this bucket
+  bucket = "example"
+}
+```
+
+#### Running Terraform Tests
+
+The `test` target runs [Terraform's native test framework](https://developer.hashicorp.com/terraform/language/tests) over any `.tftest.hcl` files in your project:
+
+<NxCommands commands={['test tf-infra']} />
+
+A project with no test files is a no-op success, so you can add tests when you need them. `build` runs this target, so your tests run as part of a normal build.
+
+Each `run` block evaluates your configuration. Use `command = plan` to check what Terraform _would_ do (this expands the whole module graph, so it catches plan-time errors that `validate` cannot), or `command = apply` to create real resources and assert on their outputs. Declaring `mock_provider` means no API calls are made and no AWS credentials are needed, which keeps `plan` tests fast and safe to run in CI:
+
+```hcl title="src/main.tftest.hcl"
+mock_provider "aws" {
+  mock_data "aws_caller_identity" {
+    defaults = { account_id = "123456789012" }
+  }
+  mock_data "aws_region" {
+    defaults = { region = "us-east-1" }
+  }
+}
+
+variables {
+  aws_region  = "us-east-1"
+  environment = "dev"
+}
+
+run "plan_is_valid" {
+  command = plan
+
+  assert {
+    condition     = data.aws_caller_identity.current.account_id == "123456789012"
+    error_message = "Unexpected account id"
+  }
+}
+```
+
+Set every variable your configuration requires in the `variables` block, otherwise the run fails with "has a required variable ... with no set value".
+
+Every target that runs `terraform init` reuses a provider cache under `.terraform/plugin-cache` in your workspace root, so providers are downloaded once rather than on every run. Each project gets its own directory there: two `terraform init` runs filling one cache at the same time can each compute a different hash for the same provider, which terraform then rejects against your `.terraform.lock.hcl`. See the [Terraform documentation](https://developer.hashicorp.com/terraform/cli/config/config-file#provider-plugin-cache) for more information.
+
+Set `TF_PLUGIN_CACHE_DIR` in your environment to point the vended `init` script at a cache you manage yourself — a volume shared between workspaces, say. Note that the `test` target reads its path from `project.json`, so change it there too.
+
 <OptionFilter when={{ type: 'application' }} description="Application-only targets: plan / apply / destroy / etc.">
 ### Application-Only Targets
 
@@ -269,6 +368,12 @@ Before applying changes, you can see what Terraform will do by running the `plan
 
 This will create a plan file in `dist/packages/<my-terraform-project>/terraform/dev.tfplan`.
 
+`plan` depends on `assemble`, so it produces the artifacts your modules reference, such as the Lambda bundles and generated operations metadata, without running the lint, test and type-check gates.
+
+:::caution[Use `build` in your pipeline]
+`assemble` is used for faster iteration during development. Run `build` in your CI pipeline to ensure your project passes quality gates prior to a production deployment.
+:::
+
 #### Initializing Terraform
 
 Initialize your Terraform working directory with the `init` target:
@@ -310,6 +415,12 @@ This will permanently delete all resources managed by this Terraform configurati
 To clean up the bootstrap resources (S3 bucket for state storage):
 
 <NxCommands commands={['bootstrap-destroy tf-infra']} />
+
+This empties the state bucket before destroying it, and resolves the region from the AWS SDK credential chain, so it runs unattended in CI.
+
+:::caution[Destroy your infrastructure first]
+The state bucket holds the state for every environment, so run `destroy` for each environment before this. Once the bucket is gone, Terraform no longer knows about the resources it created.
+:::
 </OptionFilter>
 
 ## More Information

package/docs/guides/trpc.mdx

@@ -6,7 +6,9 @@ when:
   framework: [trpc]
   infra: [rest-lambda, http-lambda]
 ---
-import { FileTree, Tabs, TabItem } from '@astrojs/starlight/components';
+import { FileTree, Tabs, TabItem, CardGrid } from '@astrojs/starlight/components';
+import Astro from '@astrojs/react';
+import ConnectionCard from '@components/connection-card.astro';
 import Link from '@components/link.astro';
 import RunGenerator from '@components/run-generator.astro';
 import GeneratorParameters from '@components/generator-parameters.astro';
@@ -64,6 +66,7 @@ The generator will create the following project structure in the `<directory>/<a
     - client
       - index.ts Type-safe client for machine-to-machine API calls
   - tsconfig.json TypeScript configuration
+  - package.json Project manifest defining the project's package name and dependencies
   - project.json Project configuration and build targets
 
 </FileTree>
@@ -138,7 +141,7 @@ The example `echo` procedure is generated for you in `src/procedures/echo.ts`:
 export const echo = publicProcedure
   .input(EchoInputSchema)
   .output(EchoOutputSchema)
-  .query((opts) => ({ result: opts.input.message }));
+  .query((opts) => ({ message: opts.input.message }));
 ```
 
 To break down the above:
@@ -463,7 +466,7 @@ export const createIdentityPlugin = () => {
 </OptionFilter>
 
 <OptionFilter when={{ auth: 'cognito' }} description="Identity middleware example for Cognito-authenticated APIs">
-When you deploy with `auth: 'cognito'`, the API Gateway Cognito User Pools authorizer verifies the JWT that the caller supplies in the `Authorization` header and places the verified claims on the Lambda event at `event.requestContext.authorizer.claims`. Our middleware just reads those claims — no extra AWS SDK calls, no manual JWT verification.
+When you deploy with `auth: 'cognito'`, the API Gateway Cognito authorizer verifies the JWT that the caller supplies in the `Authorization` header and places the verified claims on the Lambda event. Our middleware just reads those claims — no extra AWS SDK calls, no manual JWT verification.
 
 First, we define what we'll add to the context:
 
@@ -478,7 +481,7 @@ export interface IIdentityContext {
 
 Note that we define an additional _optional_ property on the context. tRPC manages ensuring that this is defined in procedures which have correctly configured this middleware.
 
-Next, the middleware itself. The generator wires the authorizer to accept ID tokens, so `cognito:username` is the canonical username claim; we fall back to `username` for access tokens in case you reconfigure the authorizer:
+Next, the middleware itself:
 
 ```ts
 import { initTRPC, TRPCError } from '@trpc/server';
@@ -503,7 +506,7 @@ export const createIdentityPlugin = () => {
       | undefined;
 
     const sub = claims?.sub;
-    const username = claims?.['cognito:username'] ?? claims?.username;
+    const username = claims?.username;
 
     if (!sub || !username) {
       throw new TRPCError({
@@ -541,14 +544,14 @@ export const me = publicProcedure
   }));
 ```
 
-:::tip[Verifying the token]
-You don't need `aws-jwt-verify` or any other JWT-verification library here — the API Gateway Cognito User Pools authorizer has already verified the signature, issuer, audience, and expiry by the time your Lambda runs. If any of those checks fail, API Gateway returns `401 Unauthorized` and your handler is never invoked.
+:::tip[No token verification required]
+You don't need `aws-jwt-verify` or any other JWT-verification library here — the API Gateway Cognito User Pools authorizer has already verified the signature, issuer, scopes, and expiry by the time your Lambda runs. If any of those checks fail, API Gateway returns `401 Unauthorized` and your handler is never invoked.
 :::
 </OptionFilter>
 
 ## Deploying your tRPC API
 
-The tRPC API generator creates CDK or Terraform infrastructure as code based on your selected `iacProvider`. You can use this to deploy your tRPC API.
+The tRPC API generator creates CDK or Terraform infrastructure as code based on your selected `iac`. You can use this to deploy your tRPC API.
 
 <Infrastructure>
 <Fragment slot="cdk">
@@ -556,7 +559,7 @@ The CDK construct for deploying your API lives in the `common/constructs` folder
 
 <OptionFilter when={{ auth: ['iam', 'custom'] }} description="CDK usage for IAM or Custom authentication">
 ```ts {6-8}
-import { MyApi } from ':my-scope/common-constructs';
+import { MyApi } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -570,12 +573,14 @@ export class ExampleStack extends Stack {
 
 :::caution[Custom Lambda Authorizer]
 When using `Custom` auth, the construct creates a Lambda Authorizer internally from the generated `src/authorizer.ts` file, which **denies all requests by default**. You must implement your authorization logic in that file before your API will accept any traffic.
+
+Authorizer results are cached for 5 minutes, keyed on the `Authorization` header, so a revoked token may be accepted until its cached result expires. Reduce the cache duration in the generated infrastructure if you need faster revocation.
 :::
 </OptionFilter>
 
 <OptionFilter when={{ auth: 'cognito' }} description="CDK usage with Cognito authentication — pass the identity construct">
-```ts {6,9}
-import { MyApi, UserIdentity } from ':my-scope/common-constructs';
+```ts {6,10}
+import { MyApi, UserIdentity } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -630,7 +635,7 @@ module "my_api" {
 </OptionFilter>
 
 <OptionFilter when={{ auth: 'cognito' }} description="Terraform usage with Cognito authentication — supply user pool and client">
-```hcl {1-3, 8-9}
+```hcl {1-3, 8, 10-11}
 module "asset_bucket" {
   source = "../../common/terraform/src/core/asset-bucket"
 }
@@ -715,6 +720,8 @@ module "my_api" {
 <OptionFilter when={{ auth: 'custom' }} description="Custom Lambda Authorizer usage with Terraform">
 :::caution[Custom Lambda Authorizer]
 When using `Custom` auth, your API is protected by a Lambda Authorizer that **denies all requests by default**. You must implement your authorization logic in the generated `src/authorizer.ts` file before your API will accept any traffic.
+
+Authorizer results are cached for 5 minutes, keyed on the `Authorization` header, so a revoked token may be accepted until its cached result expires. Reduce the cache duration in the generated infrastructure if you need faster revocation.
 :::
 </OptionFilter>
 </Fragment>
@@ -726,12 +733,18 @@ When using `Custom` auth, your API is protected by a Lambda Authorizer that **de
 <Snippet name="api/waf-configuration" parentHeading="WAF" />
 </OptionFilter>
 
+<OptionFilter when={{ infra: 'rest-lambda' }} description="Access logging — REST APIs log requests to CloudWatch by default">
+### Access logging
+
+<Snippet name="api/access-logging" parentHeading="Access logging" />
+</OptionFilter>
+
 ### Integrations
 
 <Snippet name="api/type-safe-api-integrations" parentHeading="Integrations" />
 
 :::tip[CDK Type-Safe Integrations]
-If you selected CDK for your `iacProvider`, when you add or remove a procedure in your tRPC API, these changes will be reflected immediately in the CDK construct without the need to rebuild.
+If you selected CDK for your `iac`, when you add or remove a procedure in your tRPC API, these changes will be reflected immediately in the CDK construct without the need to rebuild.
 :::
 
 <OptionFilter when={{ auth: 'iam' }} description="Granting API invoke access — IAM-authenticated APIs only">
@@ -805,7 +818,7 @@ This will automatically reload when you make changes to your API.
 You can create a tRPC client to invoke your API in a type-safe manner. If you are calling your tRPC API from another backend, you can use the client in `src/client/index.ts`, for example:
 
 ```ts
-import { createMyApiClient } from ':my-scope/my-api';
+import { createMyApiClient } from '@my-scope/my-api';
 
 const client = createMyApiClient({ url: 'https://my-api-url.example.com/' });
 
@@ -817,3 +830,31 @@ If you are calling your API from a React website, consider using the <Link path=
 ## More Information
 
 For more information about tRPC, please refer to the [tRPC documentation](https://trpc.io/docs).
+
+## Connections
+
+Use the <Link path="guides/connection">`connection`</Link> generator to integrate this project with others in your workspace. The following connections involve this project:
+
+<CardGrid>
+  <ConnectionCard
+    title="React to tRPC"
+    description="Call a tRPC API from a React website"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-trpc`}
+    source="react"
+    target="trpc"
+  />
+  <ConnectionCard
+    title="tRPC API to Relational Database"
+    description="Connect a tRPC API to an Aurora relational database"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/trpc-rdb`}
+    source="trpc"
+    target="aurora"
+  />
+  <ConnectionCard
+    title="tRPC API to TypeScript DynamoDB"
+    description="Connect a tRPC API to a DynamoDB table"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/trpc-dynamodb`}
+    source="trpc"
+    target="dynamodb"
+  />
+</CardGrid>