@aws/nx-plugin-mcp 1.0.0-rc.4 → 1.0.0-rc.41

package/docs/guides/ts-smithy-api.mdx

@@ -1,13 +1,15 @@
 ---
 title: Smithy TypeScript API
 description: Reference documentation for Smithy TypeScript API
-generator: ts#smithy-api
+generator: ts#api
 when:
   framework: [smithy]
   infra: [rest-lambda]
 ---
 
-import { FileTree } from '@astrojs/starlight/components';
+import { FileTree, 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';
@@ -27,11 +29,11 @@ The Smithy TypeScript API generator creates a new API using Smithy for service d
 
 You can generate a new Smithy TypeScript API in two ways:
 
-<RunGenerator generator="ts#smithy-api" />
+<RunGenerator generator="ts#api" requiredParameters={{ framework: 'smithy' }} />
 
 ### Options
 
-<GeneratorParameters generator="ts#smithy-api" />
+<GeneratorParameters generator="ts#api" />
 
 :::tip[Integration Pattern]
 The `integrationPattern` option defaults to `isolated`, which creates one Lambda per Smithy operation. Select `shared` if you would prefer a single shared Lambda handler for the whole API, with optional per-operation overrides.
@@ -401,6 +403,151 @@ export const MyOperation: MyOperationHandler<ServiceContext> = async (input) =>
 };
 ```
 
+### Accessing the Calling User
+
+When your API is protected by authentication, your operations often need to know who is calling. The recommended approach is to resolve the caller's identity once in the handler and pass it through the [service context](#service-context) for consumption by specific operations.
+
+We'll model the unauthorized case as a Smithy error so it serializes to a proper `403` response. Add it to your model, for example in `model/src/operations/errors.smithy`, and reference it on any operation that requires identity:
+
+```smithy
+$version: "2.0"
+
+namespace your.namespace
+
+/// Thrown when the calling user cannot be determined
+@error("client")
+@httpError(403)
+structure UnauthorizedError {
+    @required
+    message: String
+}
+```
+
+First, expose the resolved identity on the service context in `src/context.ts`. We provide it as a function so that the `UnauthorizedError` is thrown from within an operation (where the Server SDK serializes it to a `403`), rather than from the handler:
+
+```ts {4-7,15} ins={4-7,15}
+import { Logger } from '@aws-lambda-powertools/logger';
+import { Metrics } from '@aws-lambda-powertools/metrics';
+import { Tracer } from '@aws-lambda-powertools/tracer';
+
+export interface Identity {
+  sub: string;
+  username: string;
+}
+
+/**
+ * Context provided to all operations.
+ */
+export interface ServiceContext {
+  tracer: Tracer;
+  logger: Logger;
+  metrics: Metrics;
+  getIdentity: () => Promise<Identity>;
+}
+```
+
+Next, write the resolver in `src/identity.ts`. It throws `UnauthorizedError` when the caller cannot be determined. The implementation depends on your selected `auth` method:
+
+<OptionFilter when={{ auth: 'iam' }} description="Identity resolution for IAM-authenticated APIs">
+For `IAM` authentication, we look up the caller in Cognito using the sub extracted from the API Gateway event:
+
+```ts
+import { CognitoIdentityProvider } from '@aws-sdk/client-cognito-identity-provider';
+import type { APIGatewayProxyEvent } from 'aws-lambda';
+import { Identity } from './context.js';
+import { UnauthorizedError } from './generated/ssdk/index.js';
+
+const cognito = new CognitoIdentityProvider();
+
+export const getIdentity = async (
+  event: APIGatewayProxyEvent,
+): Promise<Identity> => {
+  const cognitoAuthenticationProvider =
+    event.requestContext?.identity?.cognitoAuthenticationProvider;
+
+  let sub: string | undefined = undefined;
+  if (cognitoAuthenticationProvider) {
+    const providerParts = cognitoAuthenticationProvider.split(':');
+    sub = providerParts[providerParts.length - 1];
+  }
+
+  if (!sub) {
+    throw new UnauthorizedError({ message: 'Unable to determine calling user' });
+  }
+
+  const { Users } = await cognito.listUsers({
+    // Assumes user pool id is configured in lambda environment
+    UserPoolId: process.env.USER_POOL_ID!,
+    Limit: 1,
+    Filter: `sub="${sub}"`,
+  });
+
+  if (!Users || Users.length !== 1) {
+    throw new UnauthorizedError({ message: `No user found with subjectId ${sub}` });
+  }
+
+  return { sub, username: Users[0].Username! };
+};
+```
+</OptionFilter>
+
+<OptionFilter when={{ auth: 'cognito' }} description="Identity resolution for Cognito-authenticated APIs">
+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 event at `event.requestContext.authorizer.claims`:
+
+```ts
+import type { APIGatewayProxyEvent } from 'aws-lambda';
+import { Identity } from './context.js';
+import { UnauthorizedError } from './generated/ssdk/index.js';
+
+export const getIdentity = async (
+  event: APIGatewayProxyEvent,
+): Promise<Identity> => {
+  const claims = event.requestContext?.authorizer?.claims as
+    | Record<string, string>
+    | undefined;
+
+  const sub = claims?.sub;
+  const username = claims?.username;
+
+  if (!sub || !username) {
+    throw new UnauthorizedError({ message: 'Unable to determine calling user' });
+  }
+
+  return { sub, username };
+};
+```
+
+:::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>
+
+Then wire the resolver into the context in `src/handler.ts`:
+
+```ts {2,8} ins={2,8}
+import { Service } from './service.js';
+import { getIdentity } from './identity.js';
+// ...
+const httpResponse = await serviceHandler.handle(httpRequest, {
+  tracer,
+  logger,
+  metrics,
+  getIdentity: () => getIdentity(event),
+});
+```
+
+We can now use the resolved identity in an operation, for example in `src/operations/echo.ts`:
+
+```ts
+import { ServiceContext } from '../context.js';
+import { Echo as EchoOperation } from '../generated/ssdk/index.js';
+
+export const Echo: EchoOperation<ServiceContext> = async (input, ctx) => {
+  const identity = await ctx.getIdentity();
+  return { message: `${identity.username} says ${input.message}` };
+};
+```
+
 ## Building and Code Generation
 
 The Smithy model project uses [Docker](https://www.docker.com/) to build the Smithy artifacts and generate the TypeScript Server SDK:
@@ -583,6 +730,10 @@ output "lambda_function_name" {
 
 <Snippet name="api/waf-configuration" parentHeading="WAF" />
 
+### Access logging
+
+<Snippet name="api/access-logging" parentHeading="Access logging" />
+
 ### Integrations
 
 <Snippet name="api/type-safe-api-integrations" parentHeading="Integrations" />
@@ -662,3 +813,31 @@ resource "aws_iam_role_policy_attachment" "api_invoke_access" {
 ## Invoking your Smithy API
 
 To invoke your API from a React website, you can use the <Link path="guides/connection/react-smithy">`connection`</Link> generator, which provides type-safe client generation from your Smithy model.
+
+## 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 Smithy API"
+    description="Call a Smithy API from a React website"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/react-smithy`}
+    source="react"
+    target="smithy"
+  />
+  <ConnectionCard
+    title="Smithy API to Relational Database"
+    description="Connect a Smithy API to an Aurora relational database"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/smithy-rdb`}
+    source="smithy"
+    target="aurora"
+  />
+  <ConnectionCard
+    title="Smithy API to TypeScript DynamoDB"
+    description="Connect a Smithy API to a DynamoDB table"
+    href={`/nx-plugin-for-aws/${Astro.currentLocale || 'en'}/guides/connection/smithy-dynamodb`}
+    source="smithy"
+    target="dynamodb"
+  />
+</CardGrid>

package/docs/guides/typescript-infrastructure.mdx

@@ -286,7 +286,7 @@ export class ApplicationStack extends Stack {
 
 ### Website Infrastructure
 
-If you have used the <Link path="guides/react-website">CloudScape website</Link> generator, you will notice you already have a construct in `packages/common/constructs` to deploy it. For example:
+If you have used the <Link path="guides/react-website">React Website</Link> generator, you will notice you already have a construct in `packages/common/constructs` to deploy it. For example:
 
 ```ts title="src/stacks/application-stack.ts" {3, 9-10}
 import { Stack, StackProps } from 'aws-cdk-lib';
@@ -381,6 +381,14 @@ Then run the deploy target:
 
 <NxCommands commands={['deploy <my-infra> <my-infra>-sandbox/*']} />
 
+:::tip[Express Mode for Faster Deployments]
+The `deploy` target waits for full resource stabilization by default, favouring consistency over speed. To speed up iteration during development, opt into [CloudFormation express mode](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cloudformation-express-mode.html) by passing CDK's `--express` flag:
+
+<NxCommands commands={['deploy <my-infra> <my-infra>-sandbox/* --express']} />
+
+Express mode finishes once resource configuration is confirmed applied rather than waiting for full stabilization, with propagation continuing in the background, for significantly faster iteration cycles. It is intended for development and iteration.
+:::
+
 :::tip[Selective Stack Deployment]
 The above command deploys _all_ stacks for the `<my-infra>-sandbox` stage. You can specify other stages so long as they are defined in `main.ts`.
 

package/docs/guides/typescript-project.mdx

@@ -11,7 +11,7 @@ import NxCommands from '@components/nx-commands.astro';
 import PackageManagerShortCommand from '@components/package-manager-short-command.astro';
 import Link from '@components/link.astro';
 
-The TypeScript project generator can be used to create a modern [TypeScript](https://www.typescriptlang.org/) library or application configured with best practices such as [ECMAScript Modules (ESM)](https://www.typescriptlang.org/docs/handbook/modules/reference.html), TypeScript [project references](https://www.typescriptlang.org/docs/handbook/project-references.html), [Vitest](https://vitest.dev/) for running tests and [ESLint](https://eslint.org/) for static analysis.
+The TypeScript project generator can be used to create a modern [TypeScript](https://www.typescriptlang.org/) library or application configured with best practices such as [ECMAScript Modules (ESM)](https://www.typescriptlang.org/docs/handbook/modules/reference.html), TypeScript [project references](https://www.typescriptlang.org/docs/handbook/project-references.html), [Vitest](https://vitest.dev/) for running tests and [Biome](https://biomejs.dev/) for linting and formatting.
 
 ## Usage
 
@@ -38,7 +38,6 @@ The generator will create the following project structure in the `<directory>/<n
   - tsconfig.lib.json TypeScript configuration for your library (your runtime or packaged source)
   - tsconfig.spec.json TypeScript configuration for your tests
   - vitest.config.mts Configuration for Vitest
-  - eslint.config.mjs Configuration for ESLint
 
 </FileTree>
 
@@ -198,7 +197,7 @@ If you're building an AWS Lambda function, check out the <Link path="/guides/ts-
 
 If you are publishing your TypeScript project to NPM, you must create a `package.json` file for it.
 
-This must declare the dependencies that your project references. Since at build time your project will resolve dependencies installed via the workspace root `package.json`, it's recommended to configure the [Nx Dependency Checks ESLint Plugin](https://nx.dev/nx-api/eslint-plugin/documents/dependency-checks) to ensure that your published project's `package.json` includes all dependencies you use in your project.
+This must declare the dependencies that your project references. Since at build time your project will resolve dependencies installed via the workspace root `package.json`, Biome's `noUndeclaredDependencies` rule will warn you if your project imports a package that isn't listed in its `package.json`.
 
 ### Building
 
@@ -269,11 +268,7 @@ If you are a VSCode user, we recommend installing the [Vitest Runner for VSCode
 
 ## Linting
 
-TypeScript projects use [ESLint](https://eslint.org/) for linting, along with [Prettier](https://prettier.io/) for formatting.
-
-We recommend configuring ESLint in the workspace root `eslint.config.mjs` file, as changes to this will apply to all TypeScript projects in your workspace and ensure consistency.
-
-Likewise, you can configure Prettier in the root `.prettierrc` file.
+TypeScript projects use [Biome](https://biomejs.dev/) for linting and formatting. Biome is configured in the workspace root `biome.json` file — changes to this apply to all TypeScript projects in your workspace and ensure consistency.
 
 ### Running the Linter
 
@@ -283,7 +278,7 @@ To invoke the linter to check your project, you can run the `lint` target.
 
 ### Fixing Lint Issues
 
-The majority of linting or formatting issues can be fixed automatically. You can tell ESLint to fix lint issues by running with the `--configuration=fix` argument.
+The majority of linting or formatting issues can be fixed automatically by running with the `--configuration=fix` argument.
 
 <NxCommands commands={["lint <project-name> --configuration=fix"]} />
 
@@ -303,7 +298,7 @@ To avoid linting issues slowing you down during development (particularly if you
 
 <NxCommands commands={["run-many --target build --configuration=skip-lint"]} />
 
-This will still run ESLint as part of the build, but the lint target will always be considered successful.
+This skips the lint target entirely during build.
 
 :::tip[Shorthand Command]
 This has a shorthand command from the root of your workspace:

package/docs/guides/workspace.mdx

@@ -134,7 +134,7 @@ This will run the chosen target as well as the targets it depends on.
 
 ### Linting
 
-New workspaces are configured with [ESLint](https://eslint.org/) for static analysis and [Prettier](https://prettier.io/) for code formatting. Running `lint` applies both to all projects.
+New workspaces are configured with [Biome](https://biomejs.dev/) for static analysis and code formatting. Running `lint` checks all projects for issues, and `lint --configuration=fix` auto-fixes them.
 
 ### Git Secrets
 
@@ -181,7 +181,7 @@ export default {
 } satisfies AwsNxPluginConfig;
 ```
 
-- **`iac.provider`** — the default infrastructure-as-code provider (`cdk` or `terraform`) used by generators that emit infrastructure (e.g. `ts#infra`, `ts#trpc-api`, `py#fast-api`). Generators that accept an `--iac` flag default to `inherit`, which reads this value.
+- **`iac.provider`** — the default infrastructure-as-code provider (`cdk` or `terraform`) used by generators that emit infrastructure (e.g. `ts#infra`, `ts#api`, `py#api`). Generators that accept an `--iac` flag default to `inherit`, which reads this value.
 - **`containers.engine`** — the container CLI (`docker` or `finch`) baked into generated build/push/login commands. CDK image-asset builds also pick this up via the `CDK_DOCKER` environment variable. See the <Link path="guides/docker-bundling">Docker bundling guide</Link> for details.
 
 You can edit either setting at any time — subsequent generator runs will pick up the new value.

package/docs/snippets/agent/architecture.mdx

@@ -23,7 +23,7 @@ ecr: ECR {
 
 agentcore: Strands Agent\n(AgentCore Runtime) {
   shape: image
-  icon: /nx-plugin-for-aws/icons/aws/bedrock-agentcore.svg
+  icon: /nx-plugin-for-aws/icons/aws/bedrock-agentcore-runtime.svg
 }
 
 bedrock: Bedrock\n(Model Inference) {

package/docs/snippets/agent/bedrock-deployment.mdx

@@ -169,4 +169,8 @@ module "my_project_agent" {
 
 :::note[Custom OIDC Providers]
 If you require custom JWT authentication with a non-Cognito OIDC provider, you can modify the generated CDK construct or Terraform module for your agent directly. Note that the connection generator will only support `IAM` or `Cognito` authentication.
+:::
+
+:::caution[Security Best Practices]
+When implementing your agent's business logic, review the [Bedrock AgentCore Runtime security best practices](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-security-best-practices.html).
 :::

package/docs/snippets/agent/runtime-arn.mdx

@@ -61,4 +61,25 @@ The Bedrock AgentCore Runtime dataplane URL for invoking the agent is as follows
 https://bedrock-agentcore.<region>.amazonaws.com/runtimes/<url-encoded-arn>/invocations
 ```
 
+:::tip[Invocation URL]
+Your infrastructure can also output the full invocation URL directly, with the ARN encoding handled for you:
+
+<Infrastructure>
+<Fragment slot="cdk">
+```ts
+new CfnOutput(this, 'AgentUrl', {
+  value: agent.invocationUrl,
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+```terraform
+output "agent_url" {
+  value = module.my_project_agent.invocation_url
+}
+```
+</Fragment>
+</Infrastructure>
+:::
+
 The exact way to invoke this URL depends upon the authentication method used.

package/docs/snippets/agent/securing-your-agent.mdx

@@ -0,0 +1,39 @@
+---
+title: Securing your Agent
+---
+
+Agents act on untrusted input and can drive real actions through their tools, so it's worth considering security from the start. The following practices apply to the generated agent.
+
+### Treat model input and output as untrusted
+
+Prompts can contain adversarial instructions (prompt injection), and model output is non-deterministic — neither should be trusted in security-sensitive logic:
+
+- Define strict input schemas for your tools, as in the generated example tool. Constrain values to what the tool actually needs (enums, length limits, numeric ranges) rather than accepting free-form strings.
+- Never pass model output directly into shell commands, SQL queries, code evaluation, or rendered HTML without validation or encoding.
+- Apply authorization checks in your tools and downstream services — don't rely on the system prompt to prevent the model from misusing a tool it has access to.
+
+Strands' [Prompt Engineering](https://strandsagents.com/docs/user-guide/safety-security/prompt-engineering/) and [Responsible AI](https://strandsagents.com/docs/user-guide/safety-security/responsible-ai/) guides cover writing robust, safety-conscious system prompts.
+
+### Scope tool permissions tightly
+
+Grant the agent's IAM role only the permissions its tools need. The vended CDK constructs and Terraform modules expose `grant*` methods and scoped policies for this purpose — for example granting an agent access to invoke a specific API rather than attaching broad managed policies. Where a tool acts on behalf of a user, prefer authorizing the action using the calling user's identity (passed through via the request context) over the agent's own ambient permissions.
+
+### Provide a kill switch
+
+Because model behaviour can change in unexpected ways, plan for quickly disabling or swapping the model without a code change:
+
+- Read the model ID from configuration (for example a `MODEL_ID` environment variable) so operators can switch or roll back to a different model by updating configuration.
+- Gate the agent behind a feature flag so its AI functionality can be disabled entirely. When disabled, return a generic message rather than an error, and ensure the rest of your application degrades gracefully.
+
+Document how to flip these controls in your operational runbook.
+
+### Protect sensitive data
+
+- Avoid logging prompts and completions, which may contain user data. The generated agent's model error logging hook logs error metadata only, not conversation content — keep this property when adding your own logging.
+- Return generic error messages to users; log detailed errors server-side.
+- Isolate conversation state between users and sessions, and authorize access to any persisted session data.
+- Redact personally identifiable information (PII) from prompts and outputs — either with a Bedrock Guardrail sensitive information filter (below) or, for Strands agents, the approaches in the [PII Redaction](https://strandsagents.com/docs/user-guide/safety-security/pii-redaction/) guide.
+
+### Amazon Bedrock Guardrails
+
+[Amazon Bedrock Guardrails](https://docs.aws.amazon.com/bedrock/latest/userguide/guardrails.html) provide configurable content filters, denied topics, and sensitive information (PII) filters which are evaluated on model input and output. You can attach a guardrail to the model used by the generated agent:

package/docs/snippets/api/access-logging.mdx

@@ -0,0 +1,33 @@
+---
+title: Access logging
+---
+import Infrastructure from '@components/infrastructure.astro';
+
+For REST APIs, the generated infrastructure enables [access logging](https://docs.aws.amazon.com/apigateway/latest/developerguide/set-up-logging.html) by default, writing one structured JSON line per request to a dedicated CloudWatch Logs group. The log group is encrypted with a customer-managed KMS key and retained for one year.
+
+API Gateway writes access logs using an account-level CloudWatch Logs role. This role is configured on the `AWS::ApiGateway::Account` setting, which is a **singleton per region per account** — there is only one role for every REST API in the region. To manage this safely across multiple independently-deployed stacks, the generated infrastructure:
+
+- Creates a shared CloudWatch Logs role and configures it on the account only when no working role is already set, so deployments never overwrite a role another stack owns.
+- Leaves the account setting untouched on teardown, so destroying one stack never disables logging for other REST APIs in the region.
+
+<Infrastructure>
+<Fragment slot="cdk">
+The account role is managed by the `ApiGatewayAccount` construct, a stack-scoped singleton resolved via `ApiGatewayAccount.ensure(scope)`. Each REST API's stage depends on it, and the role is configured by a Lambda-backed custom resource.
+
+You can customise the access log format by passing `deployOptions` when constructing your API:
+
+```ts {3-5}
+const api = new MyApi(this, 'MyApi', {
+  integrations: MyApi.defaultIntegrations(this).build(),
+  deployOptions: {
+    accessLogFormat: AccessLogFormat.clf(),
+  },
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+The account role is managed by the `core/api/api-gateway-account` module, which is instantiated by the generated API module. It configures the account idempotently and is never reset on `terraform destroy`.
+
+You can customise the access log format by editing the `access_log_settings` block on the `aws_api_gateway_stage` resource in the generated API module.
+</Fragment>
+</Infrastructure>

package/docs/snippets/api/type-safe-api-integrations.mdx

@@ -172,6 +172,37 @@ module "my_api" {
 </Fragment>
 </Infrastructure>
 
+#### Customising Options Per-Operation
+
+<Infrastructure>
+<Fragment slot="cdk">
+To customise the options used to create the default integration for _specific_ operations (without affecting the others), you can use the `withOperationOptions` method. For example, if you would like to increase the Lambda function timeout for just one operation:
+
+```ts {4-6}
+const api = new MyApi(this, 'MyApi', {
+  integrations: MyApi.defaultIntegrations(this)
+    .withOperationOptions({
+      sayHello: {
+        timeout: Duration.seconds(60),
+      },
+    })
+    .build(),
+});
+
+// The selected operations remain default integrations, so they're still typed accordingly:
+api.integrations.sayHello.handler.addToRolePolicy(new PolicyStatement({ ... }));
+```
+
+The options you specify are merged with the default integration options (and any options set via `withDefaultOptions`). Note that you cannot specify options for operations which you have replaced via `withOverrides`, since these no longer use the default integration.
+
+You will encounter a type error if the same operation is targeted by both `withOperationOptions` and `withOverrides`, regardless of the order in which you call them.
+
+</Fragment>
+<Fragment slot="terraform">
+To customise options for specific operations with Terraform, you need to edit the generated Terraform module to configure individual Lambda functions per operation (see the [Explicit Integrations](#explicit-integrations) section below).
+</Fragment>
+</Infrastructure>
+
 #### Overriding Integrations
 
 <Infrastructure>

package/docs/snippets/api/waf-configuration.mdx

@@ -6,7 +6,7 @@ import Infrastructure from '@components/infrastructure.astro';
 For REST APIs, the generated construct associates an [AWS WAFv2](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) Web ACL with the API Gateway stage by default. The Web ACL uses the AWS managed default ruleset ([`AWSManagedRulesCommonRuleSet`](https://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-baseline.html#aws-managed-rule-groups-baseline-crs) and [`AWSManagedRulesKnownBadInputsRuleSet`](https://docs.aws.amazon.com/waf/latest/developerguide/aws-managed-rule-groups-baseline.html#aws-managed-rule-groups-baseline-known-bad-inputs)), providing protection against common web exploits including the OWASP Top 10. WAF request logs are written to a CloudWatch Logs group.
 
 :::caution[SizeRestrictions_BODY deviation from defaults]
-The `SizeRestrictions_BODY` rule from `AWSManagedRulesCommonRuleSet` is overridden to `Count` rather than `Block`, since the rule's 8 KB limit is too restrictive for most APIs. Oversized requests will still be recorded as metrics so you can monitor them. See the [AWS WAF body size limits](https://docs.aws.amazon.com/waf/latest/developerguide/waf-rule-statement-oversize-handling.html) guide for more details.
+The `SizeRestrictions_BODY` rule from `AWSManagedRulesCommonRuleSet` is overridden to `Count` rather than `Block`, since the rule's 8 KB limit is too restrictive for most APIs. Oversized requests will still be recorded as metrics so you can monitor them. See the [AWS WAF body size limits](https://docs.aws.amazon.com/waf/latest/developerguide/waf-rule-statement-oversize-handling.html) guide for more details. API Gateway natively enforces its [maximum payload size of 10 MB](https://docs.aws.amazon.com/apigateway/latest/developerguide/limits.html), returning a `413` for larger requests.
 :::
 
 You can edit the generated rest-api construct to add, remove, or adjust rules (for example, to add [rate-based rules](https://docs.aws.amazon.com/waf/latest/developerguide/waf-rule-statement-type-rate-based.html) or additional managed rule groups).

package/docs/snippets/connection/dynamodb-local-development.mdx

@@ -2,6 +2,6 @@
 title: DynamoDB Local Development
 ---
 
-The `connection` generator configures your project's `serve-local` target to depend on the DynamoDB project's `serve-local` target. DynamoDB Local will start automatically alongside your project when running `serve-local`.
+The `connection` generator configures your project's `dev` target to depend on the DynamoDB project's `dev` target. DynamoDB Local will start automatically alongside your project when running `dev`.
 
-The `SERVE_LOCAL=true` environment variable is set automatically, so `getDynamoDBClient()` and `resolveTableName()` connect to the local DynamoDB Local instance instead of AWS.
+The `LOCAL_DEV=true` environment variable is set automatically, so `getDynamoDBClient()` and `resolveTableName()` connect to the local DynamoDB Local instance instead of AWS.

package/docs/snippets/connection/py-dynamodb-local-development.mdx

@@ -0,0 +1,7 @@
+---
+title: Python DynamoDB Local Development
+---
+
+The `connection` generator configures your project's `dev` target to depend on the DynamoDB project's `dev` target. DynamoDB Local will start automatically alongside your project when running `dev`.
+
+The `LOCAL_DEV=true` environment variable is set automatically, so `is_local()` returns `True` and your PynamoDB entities connect to the local DynamoDB instance instead of AWS.

package/docs/snippets/connection/py-lambda-rdb-ssl-requirements.mdx

@@ -0,0 +1,7 @@
+---
+title: SSL Requirements when Connecting without RDS Proxy
+---
+
+The Amazon Linux 2023 Lambda execution environment's built-in CA trust store includes the Amazon Root CAs used by RDS, so no additional configuration is needed.
+
+When using RDS Proxy, you do not need to configure the RDS CA bundle in your Lambda function.

package/docs/snippets/connection/rdb-api-infrastructure.mdx

@@ -2,6 +2,7 @@
 title: RDB API Infrastructure
 ---
 import Infrastructure from '@components/infrastructure.astro';
+import Link from '@components/link.astro';
 
 To allow your API to connect to the database at runtime, the API Lambda functions must be deployed into the same VPC as the database and granted network and IAM access.
 
@@ -39,34 +40,65 @@ This example grants every handler in your API access, but if only some handlers
 </Fragment>
 <Fragment slot="terraform">
 
-Pass the database module outputs into your API module so it can reach the database and read its runtime configuration:
+Deploy the API into the same VPC as the database, grant it `rds-db:connect` via `additional_iam_policy_statements`, and open the network path with a pair of security group rules. The `aws_vpc.main` and `aws_subnet` resources are defined in the database deployment guide:
 
 ```hcl title="packages/infra/src/main.tf"
 module "my_database" {
   source              = "../../common/terraform/src/app/dbs/my-database"
-  vpc_id              = module.vpc.vpc_id
-  database_subnet_ids = module.vpc.private_isolated_subnet_ids
-  lambda_subnet_ids   = module.vpc.private_subnet_ids
+  vpc_id              = aws_vpc.main.id
+  database_subnet_ids = aws_subnet.database[*].id
+  lambda_subnet_ids   = aws_subnet.private[*].id
 }
 
 module "api" {
-  source             = "..."
-  vpc_id             = module.vpc.vpc_id
-  private_subnet_ids = module.vpc.private_subnet_ids
-
-  appconfig_application_id     = module.my_database.appconfig_application_id
-  database_cluster_resource_id = module.my_database.cluster_resource_id
-  database_runtime_user        = module.my_database.database_runtime_user
-  database_security_group_id   = module.my_database.security_group_id
-  database_port                = module.my_database.cluster_port
-
-  environment_variables = {
-    RUNTIME_CONFIG_APP_ID = module.my_database.appconfig_application_id
-  }
+  source     = "../../common/terraform/src/app/apis/my-api"
+  enable_vpc = true
+  vpc_id     = aws_vpc.main.id
+  subnet_ids = aws_subnet.private[*].id
+
+  appconfig_application_id  = module.runtime_config_appconfig.application_id
+  appconfig_application_arn = module.runtime_config_appconfig.application_arn
+
+  additional_iam_policy_statements = [
+    {
+      Effect = "Allow"
+      Action = ["rds-db:connect"]
+      Resource = [
+        "arn:aws:rds-db:${data.aws_region.current.region}:${data.aws_caller_identity.current.account_id}:dbuser:${module.my_database.connect_resource_id}/${module.my_database.database_runtime_user}"
+      ]
+    }
+  ]
+}
+
+resource "aws_vpc_security_group_ingress_rule" "api_to_database" {
+  description                  = "Allow the API Lambda functions to connect to the database"
+  security_group_id            = module.my_database.security_group_id
+  referenced_security_group_id = module.api.security_group_id
+  from_port                    = module.my_database.cluster_port
+  to_port                      = module.my_database.cluster_port
+  ip_protocol                  = "tcp"
+}
+
+resource "aws_vpc_security_group_egress_rule" "api_to_database" {
+  description                  = "Allow outbound traffic from the API Lambda functions to the database"
+  security_group_id            = module.api.security_group_id
+  referenced_security_group_id = module.my_database.security_group_id
+  from_port                    = module.my_database.cluster_port
+  to_port                      = module.my_database.cluster_port
+  ip_protocol                  = "tcp"
 }
 ```
 
-Deploy the API Lambda functions into **private subnets with egress**, not private isolated subnets. Ensure the API Lambda role has `rds-db:connect` permission and that its security group can reach the database security group on the database port.
+Deploy the API Lambda functions into **private subnets with egress**, not private isolated subnets. `appconfig_application_id`/`appconfig_application_arn` come from the shared <Link path="guides/runtime-config">runtime configuration</Link> AppConfig application declared once in your root module, not from the database module — passing them sets `RUNTIME_CONFIG_APP_ID` on the Lambda functions and grants them read access to the application. Include the `database` namespace when instantiating it so the database module's runtime configuration entry is deployed:
+
+```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"]
+}
+```
 
 </Fragment>
 </Infrastructure>