@aws/nx-plugin-mcp 1.0.0-rc.75 → 1.0.0-rc.77

package/docs/guides/connection/react-agui.mdx

@@ -92,6 +92,25 @@ The generated code handles authentication depending on your agent's configuratio
 - **IAM** (default): uses AWS SigV4-signed HTTP requests. Credentials are obtained from the Cognito Identity Pool configured with your website's auth.
 - **Cognito**: embeds the JWT access token in the `Authorization` header as a Bearer token.
 
+### Sessions and Threads
+
+AG-UI and AgentCore Runtime each identify a conversation differently, and the generated hook ties them together:
+
+- **`threadId`** — the AG-UI conversation identifier, sent in the request body. CopilotKit generates a random UUID per chat unless you pass an explicit `threadId`.
+- **Session ID** — the AgentCore Runtime session, sent in the `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` header. It selects the [microVM](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-how-it-works.html) serving the request, and is what your agent's `session.ts` / `session.py` keys conversation state on.
+
+The hook derives the session ID from the thread ID, right-padding it to the 33 characters AgentCore Runtime requires:
+
+```ts
+function agentCoreSessionId(input: RunAgentInput): string {
+  return (input.threadId ?? '').padEnd(33, '0');
+}
+```
+
+Leaving `threadId` unset is simplest — CopilotKit's generated UUID is already 36 characters. If you pass one explicitly, make it at least 33 characters, since padding maps thread IDs that differ only in trailing characters onto the same session.
+
+Both Session ID and Thread ID are provided by the browser. To restrict each user to their own conversations, refer to the <Link path="guides/py-agent">`py#agent`</Link> or <Link path="guides/ts-agent">`ts#agent`</Link> guide.
+
 ## Infrastructure
 
 <Snippet name="connection/react-agent-infrastructure" parentHeading="Infrastructure" />

package/docs/guides/py-agent.mdx

@@ -4,7 +4,7 @@ description: Generate a Python Agent for building AI agents with tools and deplo
 generator: py#agent
 ---
 
-import { FileTree, Tabs, TabItem, CardGrid } from '@astrojs/starlight/components';
+import { FileTree, Tabs, TabItem, CardGrid, Steps } from '@astrojs/starlight/components';
 import Astro from '@astrojs/react';
 import ConnectionCard from '@components/connection-card.astro';
 import RunGenerator from '@components/run-generator.astro';
@@ -516,6 +516,23 @@ The session ID itself comes from the AgentCore Runtime session (propagated via t
 :::note[Local Development]
 When running locally (`LOCAL_DEV=true`, set automatically by the `-dev` target), session data is always stored on disk under `tmp/agents/strands/<agent-name>` at the workspace root, regardless of the configured `session` option, for convenience.
 :::
+
+#### Restricting sessions to their owner
+
+The session ID arrives from the caller, so on its own it identifies a conversation but not who the conversation belongs to. AgentCore Runtime authorizes an invocation against the agent runtime resource ARN rather than against an individual session, which leaves the agent free to decide what a session means to your application.
+
+:::caution[The session also selects the microVM]
+A session ID selects the [microVM](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-how-it-works.html) that serves the request, so its filesystem, `/tmp` and in-process caches are shared by every request resolving to that session. Two callers who send the same session ID share those resources even when their stored conversations are separate.
+:::
+
+To restrict each user to their own conversations:
+
+<Steps>
+  1. Add an API to create a session, using <Link path="guides/trpc">tRPC</Link>, <Link path="guides/fastapi">FastAPI</Link> or <Link path="guides/ts-smithy-api">Smithy</Link>. Generate an opaque session ID (at least 33 characters) and store it alongside the calling user's ID — for example in a table created with the <Link path="guides/py-dynamodb">`py#dynamodb`</Link> generator. Each API guide shows how to retrieve the calling user's ID.
+  2. In your agent, look up the stored user ID for the session ID it was given, and reject the request when it does not match the caller. With `auth=cognito` the caller's JWT reaches your agent code, so its `sub` claim identifies them.
+</Steps>
+
+Generate the session ID rather than deriving it from user-supplied values such as a conversation name — anything a caller can predict, a caller can send.
 </OptionFilter>
 
 <OptionFilter when={{ framework: 'langchain' }} description="LangChain session management (session.py)">

package/docs/guides/react-website-auth.mdx

@@ -119,6 +119,42 @@ Set `advanced_security_mode` to `ENFORCED` in the `user_pool_add_ons` block in `
 </Fragment>
 </Infrastructure>
 
+#### Multi-factor authentication (MFA)
+
+By default users must configure MFA (an SMS code or a time-based one time password) before they can sign in. You can make MFA optional, turn it off entirely, or restrict which second-factor methods are available:
+
+<Infrastructure>
+<Fragment slot="cdk">
+```ts
+import { Mfa } from 'aws-cdk-lib/aws-cognito';
+
+new UserIdentity(this, 'Identity', {
+  mfa: Mfa.OPTIONAL,
+  mfaSecondFactor: { sms: false, otp: true },
+});
+```
+
+`mfa` accepts `Mfa.OFF` / `Mfa.OPTIONAL` / `Mfa.REQUIRED`. `mfaSecondFactor.sms` and `mfaSecondFactor.otp` enable or disable each second-factor method independently; they have no effect when `mfa` is `Mfa.OFF`. Setting `mfa: Mfa.REQUIRED` with both methods disabled is rejected at synth time, since nobody could then complete sign-in.
+</Fragment>
+<Fragment slot="terraform">
+```hcl
+module "user_identity" {
+  source = "../../common/terraform/src/core/user-identity"
+
+  mfa = "OPTIONAL"
+  mfa_second_factor_sms = false
+  mfa_second_factor_otp = true
+}
+```
+
+`mfa` accepts `"OFF"` / `"OPTIONAL"` / `"ON"`. `mfa_second_factor_sms` and `mfa_second_factor_otp` enable or disable each second-factor method independently; they have no effect when `mfa` is `"OFF"`.
+</Fragment>
+</Infrastructure>
+
+:::caution[SMS MFA is tied to phone number verification]
+Cognito rejects SMS-based phone number verification unless SMS is also an enabled MFA method whenever MFA is not off, in both CDK and Terraform. Disabling `mfaSecondFactor.sms` / `mfa_second_factor_sms` while `mfa` is on therefore also disables SMS-based phone number verification for the user pool.
+:::
+
 #### Web Application Firewall (WAF)
 
 By default the User Pool is associated with an [AWS WAFv2](https://docs.aws.amazon.com/waf/latest/developerguide/waf-chapter.html) Web ACL using the `AWSManagedRulesCommonRuleSet` and `AWSManagedRulesKnownBadInputsRuleSet` managed rule groups. You can disable this if you wish to manage your own Web ACL or do not require one:

package/docs/guides/ts-agent.mdx

@@ -4,7 +4,7 @@ description: Generate a TypeScript Agent for building AI agents with tools and d
 generator: ts#agent
 ---
 
-import { FileTree, Tabs, TabItem, CardGrid } from '@astrojs/starlight/components';
+import { FileTree, Tabs, TabItem, CardGrid, Steps } from '@astrojs/starlight/components';
 import Astro from '@astrojs/react';
 import ConnectionCard from '@components/connection-card.astro';
 import RunGenerator from '@components/run-generator.astro';
@@ -365,6 +365,23 @@ The session ID itself comes from the AgentCore Runtime session (propagated via t
 :::note[Local Development]
 When running locally (`LOCAL_DEV=true`, set automatically by the `-dev` target), session data is always stored on disk under `tmp/agents/strands/<agent-name>` at the workspace root, regardless of the configured `session` option, for convenience.
 :::
+
+#### Restricting sessions to their owner
+
+The session ID arrives from the caller, so on its own it identifies a conversation but not who the conversation belongs to. AgentCore Runtime authorizes an invocation against the agent runtime resource ARN rather than against an individual session, which leaves the agent free to decide what a session means to your application.
+
+:::caution[The session also selects the microVM]
+A session ID selects the [microVM](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-how-it-works.html) that serves the request, so its filesystem, `/tmp` and in-process caches are shared by every request resolving to that session. Two callers who send the same session ID share those resources even when their stored conversations are separate.
+:::
+
+To restrict each user to their own conversations:
+
+<Steps>
+  1. Add an API to create a session, using <Link path="guides/trpc">tRPC</Link>, <Link path="guides/fastapi">FastAPI</Link> or <Link path="guides/ts-smithy-api">Smithy</Link>. Generate an opaque session ID (at least 33 characters) and store it alongside the calling user's ID — for example in a table created with the <Link path="guides/ts-dynamodb">`ts#dynamodb`</Link> generator. Each API guide shows how to retrieve the calling user's ID.
+  2. In your agent, look up the stored user ID for the session ID it was given, and reject the request when it does not match the caller. With `auth=cognito` the caller's JWT reaches your agent code, so its `sub` claim identifies them.
+</Steps>
+
+Generate the session ID rather than deriving it from user-supplied values such as a conversation name — anything a caller can predict, a caller can send.
 </OptionFilter>
 
 ## Invoking your Agent

package/docs/snippets/dynamodb/deploying-table.mdx

@@ -2,6 +2,7 @@
 title: Deploying your DynamoDB Table
 ---
 import Infrastructure from '@components/infrastructure.astro';
+import Snippet from '@components/snippet.astro';
 
 The DynamoDB generator creates CDK or Terraform infrastructure based on your selected `iac`.
 
@@ -137,30 +138,8 @@ module "my_table" {
 </Fragment>
 </Infrastructure>
 
-### Encryption Key Rotation
+### Encryption
 
-The KMS key used to encrypt the table has automatic key rotation enabled by default. Disable it if your security policy manages rotation externally.
+The table is encrypted with a customer-managed KMS key by default, created automatically for you. Switch to an AWS managed key, the AWS owned key, or bring your own KMS key, if you manage encryption differently.
 
-#### Disable Encryption Key Rotation
-
-<Infrastructure>
-<Fragment slot="cdk">
-
-```ts title="packages/infra/src/stacks/application-stack.ts"
-import { MyTable } from '@my-scope/common-constructs';
-
-const table = new MyTable(this, 'Table', {
-  enableKeyRotation: false,
-});
-```
-</Fragment>
-<Fragment slot="terraform">
-
-```hcl title="packages/infra/src/main.tf"
-module "my_table" {
-  source              = "../../common/terraform/src/app/dynamodb/my-table"
-  enable_key_rotation = false
-}
-```
-</Fragment>
-</Infrastructure>
+<Snippet name="dynamodb/encryption-options" parentHeading="Encryption" />

package/docs/snippets/dynamodb/encryption-options.mdx

@@ -0,0 +1,168 @@
+---
+title: Encryption Options
+---
+import Infrastructure from '@components/infrastructure.astro';
+import OptionFilter from '@components/option-filter.astro';
+
+#### Use an AWS Managed Key
+
+Uses the shared `aws/dynamodb` KMS key that AWS manages on your behalf. It's visible in your account's KMS console and billed per request, but there's no key for you to create, rotate or delete.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { TableEncryption } from 'aws-cdk-lib/aws-dynamodb';
+import { MyTable } from '@my-scope/common-constructs';
+
+const table = new MyTable(this, 'Table', {
+  encryption: TableEncryption.AWS_MANAGED,
+});
+```
+
+:::tip[Checkov]
+Choosing `AWS_MANAGED` means the table is no longer encrypted with a customer-managed key, which fails Checkov's `CKV_AWS_119`. Suppress it on the table:
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { suppressRules } from '@my-scope/common-constructs';
+
+suppressRules(table.table, ['CKV_AWS_119'], 'Using an AWS managed key rather than a customer-managed CMK');
+```
+:::
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_table" {
+  source     = "../../common/terraform/src/app/dynamodb/my-table"
+  encryption = "AWS_MANAGED"
+}
+```
+</Fragment>
+</Infrastructure>
+
+#### Use the AWS Owned Key
+
+Uses a key fully owned and managed by AWS — free, with no key visible in your account at all. The simplest option when you don't need a customer- or account-visible key for compliance reasons.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { TableEncryption } from 'aws-cdk-lib/aws-dynamodb';
+import { MyTable } from '@my-scope/common-constructs';
+
+const table = new MyTable(this, 'Table', {
+  encryption: TableEncryption.DEFAULT,
+});
+```
+
+:::tip[Checkov]
+Choosing `DEFAULT` means the table is no longer encrypted with a customer-managed key, which fails Checkov's `CKV_AWS_119`. Suppress it on the table:
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { suppressRules } from '@my-scope/common-constructs';
+
+suppressRules(table.table, ['CKV_AWS_119'], 'Using the AWS owned key rather than a customer-managed CMK');
+```
+:::
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_table" {
+  source     = "../../common/terraform/src/app/dynamodb/my-table"
+  encryption = "DEFAULT"
+}
+```
+</Fragment>
+</Infrastructure>
+
+<OptionFilter when={{ iac: 'terraform' }} description="Switching an already-deployed table away from CUSTOMER_MANAGED">
+#### Switching away from CUSTOMER_MANAGED
+
+On an **already-deployed** table, changing `encryption` away from `CUSTOMER_MANAGED` (to either `AWS_MANAGED` or `DEFAULT`) in a single `terraform apply` fails: Terraform destroys the customer-managed key before updating the table, and DynamoDB then rejects the update because the key is already pending deletion.
+
+Work around it by updating the table's encryption directly via the AWS CLI first, then letting Terraform catch up and clean up the orphaned key:
+
+```bash
+# For AWS_MANAGED:
+aws dynamodb update-table --table-name <table-name> \
+  --sse-specification Enabled=true,SSEType=KMS,KMSMasterKeyId=alias/aws/dynamodb
+
+# For DEFAULT:
+aws dynamodb update-table --table-name <table-name> --sse-specification Enabled=false
+
+# Then wait for this to report ENABLED (or for SSEDescription to disappear, for DEFAULT):
+aws dynamodb describe-table --table-name <table-name> --query Table.SSEDescription.Status
+```
+
+Then update `encryption` in your Terraform config and run `terraform apply` as normal — Terraform now only needs to destroy the already-unused key, with nothing left depending on it.
+</OptionFilter>
+
+#### Use Your Own KMS Key
+
+Provide an existing customer-managed key instead of having one created for you. The key must already grant the DynamoDB service the permissions it needs in its own key policy.
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { Key } from 'aws-cdk-lib/aws-kms';
+import { MyTable } from '@my-scope/common-constructs';
+
+const key = Key.fromKeyArn(this, 'Key', 'arn:aws:kms:us-east-1:111111111111:key/my-key-id');
+
+const table = new MyTable(this, 'Table', {
+  encryptionKey: key,
+});
+```
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_table" {
+  source      = "../../common/terraform/src/app/dynamodb/my-table"
+  kms_key_arn = "arn:aws:kms:us-east-1:111111111111:key/my-key-id"
+}
+```
+</Fragment>
+</Infrastructure>
+
+#### Encryption Key Rotation
+
+When the table creates its own customer-managed KMS key (the default, and only when you haven't provided your own key), that key has automatic key rotation enabled by default. Disable it if your security policy manages rotation externally.
+
+##### Disable Encryption Key Rotation
+
+<Infrastructure>
+<Fragment slot="cdk">
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { MyTable } from '@my-scope/common-constructs';
+
+const table = new MyTable(this, 'Table', {
+  enableKeyRotation: false,
+});
+```
+
+:::tip[Checkov]
+Disabling key rotation, or bringing your own key that doesn't rotate, fails Checkov's `CKV_AWS_7`. Suppress it on the key:
+
+```ts title="packages/infra/src/stacks/application-stack.ts"
+import { suppressRules } from '@my-scope/common-constructs';
+
+suppressRules(table.table.encryptionKey!, ['CKV_AWS_7'], 'Key rotation is managed externally');
+```
+:::
+</Fragment>
+<Fragment slot="terraform">
+
+```hcl title="packages/infra/src/main.tf"
+module "my_table" {
+  source              = "../../common/terraform/src/app/dynamodb/my-table"
+  enable_key_rotation = false
+}
+```
+</Fragment>
+</Infrastructure>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws/nx-plugin-mcp",
-  "version": "1.0.0-rc.75",
+  "version": "1.0.0-rc.77",
   "repository": {
     "type": "git",
     "url": "https://github.com/awslabs/nx-plugin-for-aws.git",