@aws/nx-plugin-mcp 1.0.0-rc.8 → 1.0.0-rc.80

package/docs/guides/runtime-config.mdx

@@ -70,7 +70,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);
 

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

@@ -84,7 +84,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 +108,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" {

package/docs/guides/trpc.mdx

@@ -1,12 +1,14 @@
 ---
 title: tRPC
 description: Reference documentation for tRPC
-generator: ts#trpc-api
+generator: ts#api
 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';
@@ -25,11 +27,11 @@ The tRPC API generator creates a new tRPC API with AWS CDK or Terraform infrastr
 
 You can generate a new tRPC API in two ways:
 
-<RunGenerator generator="ts#trpc-api" />
+<RunGenerator generator="ts#api" requiredParameters={{ framework: 'trpc' }} />
 
 ### Options
 
-<GeneratorParameters generator="ts#trpc-api" />
+<GeneratorParameters generator="ts#api" />
 
 <Snippet name="api/api-choice-note" />
 
@@ -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) {
@@ -574,8 +577,8 @@ When using `Custom` auth, the construct creates a Lambda Authorizer internally f
 </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 +633,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"
 }
@@ -726,12 +729,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 +814,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 +826,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>