@aws/nx-plugin-mcp 1.0.0-rc.6 → 1.0.0-rc.60

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.
@@ -44,6 +46,7 @@ The generator creates two related projects in the `<directory>/<api-name>` direc
 <FileTree>
 
 - **model/** Smithy model project
+  - package.json Project manifest defining the project's package name and dependencies
   - project.json Project configuration and build targets
   - smithy-build.json Smithy build configuration
   - build.Dockerfile Docker configuration for building Smithy artifacts
@@ -67,7 +70,7 @@ The generator creates two related projects in the `<directory>/<api-name>` direc
 
 ### Infrastructure
 
-Since this generator creates infrastructure as code based on your chosen `iacProvider`, it will create a project in `packages/common` which includes the relevant CDK constructs or Terraform modules.
+Since this generator creates infrastructure as code based on your chosen `iac`, it will create a project in `packages/common` which includes the relevant CDK constructs or Terraform modules.
 
 The common infrastructure as code project is structured as follows:
 
@@ -221,6 +224,31 @@ You can change the folder structure however you like - all `.smithy` files in th
 For more details on Smithy and its syntax, refer to the [Smithy specification](https://smithy.io/2.0/spec/index.html).
 :::
 
+### Adding a Shape Library
+
+If you have several Smithy APIs which share the same data types, you can define those types once in a shape library rather than duplicating them in each model. A shape library is a Smithy project with no service — just reusable shapes — which any number of Smithy projects can depend on.
+
+Generate one with the <Link path="guides/smithy-project">`smithy#project`</Link> generator:
+
+<RunGenerator generator="smithy#project" requiredParameters={{ name: 'my-shapes', type: 'shapes' }} />
+
+Your API's model can then reference its shapes with `use`:
+
+```smithy
+$version: "2.0"
+
+namespace com.example.api
+
+use com.example.shared#Customer
+
+structure GetCustomerOutput {
+    @required
+    customer: Customer
+}
+```
+
+See the <Link path="guides/smithy-project">Smithy project guide</Link> for how to create a shape library and wire it up as a dependency of your API's model.
+
 ### Implementing Operations in TypeScript
 
 Operation implementations are located in the backend project's `src/operations/` directory. Each operation is implemented using the generated types from the TypeScript Server SDK (generated at build time from your Smithy model).
@@ -280,7 +308,7 @@ You must construct the context yourself in both `handler.ts` (the Lambda functio
 
 The generator configures structured logging using AWS Lambda Powertools with automatic context injection via Middy middleware.
 
-```typescript {4}
+```typescript {3}
 // handler.ts
 export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
   .use(captureLambdaHandler(tracer))
@@ -291,7 +319,7 @@ export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
 
 You can reference the logger from your operation implementations via the context:
 
-```typescript {6}
+```typescript {5}
 // operations/echo.ts
 import { ServiceContext } from '../context.js';
 import { Echo as EchoOperation } from '../generated/ssdk/index.js';
@@ -306,7 +334,7 @@ export const Echo: EchoOperation<ServiceContext> = async (input, ctx) => {
 
 AWS X-Ray tracing is configured automatically via the `captureLambdaHandler` middleware.
 
-```typescript {3}
+```typescript {2}
 // handler.ts
 export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
   .use(captureLambdaHandler(tracer))
@@ -317,7 +345,7 @@ export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
 
 You can add custom subsegments to your traces in your operations:
 
-```typescript {7, 11, 14}
+```typescript {6, 10, 13}
 // operations/echo.ts
 import { ServiceContext } from '../context.js';
 import { Echo as EchoOperation } from '../generated/ssdk/index.js';
@@ -340,7 +368,7 @@ export const Echo: EchoOperation<ServiceContext> = async (input, ctx) => {
 
 CloudWatch metrics are collected automatically for each request via the `logMetrics` middleware.
 
-```typescript {5}
+```typescript {4}
 // handler.ts
 export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
   .use(captureLambdaHandler(tracer))
@@ -351,7 +379,7 @@ export const handler = middy<APIGatewayProxyEvent, APIGatewayProxyResult>()
 
 You can add custom metrics in your operations:
 
-```typescript {7}
+```typescript {6}
 // operations/echo.ts
 import { MetricUnit } from '@aws-lambda-powertools/metrics';
 import { ServiceContext } from '../context.js';
@@ -401,6 +429,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 {5-8,17} ins={5-8,17}
+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:
@@ -434,14 +607,14 @@ The local server will not only hot-reload when you make TypeScript changes to yo
 
 ## Deploying your Smithy API
 
-The generator creates CDK or Terraform infrastructure based on your selected `iacProvider`.
+The generator creates CDK or Terraform infrastructure based on your selected `iac`.
 
 <Infrastructure>
 <Fragment slot="cdk">
 The CDK construct for deploying your API is in the `common/constructs` folder:
 
 ```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) {
@@ -468,7 +641,7 @@ This sets up:
 If you selected `Cognito` authentication, you will need to supply the `identity` property to the API construct:
 
 ```ts {9}
-import { MyApi, UserIdentity } from ':my-scope/common-constructs';
+import { MyApi, UserIdentity } from '@my-scope/common-constructs';
 
 export class ExampleStack extends Stack {
   constructor(scope: Construct, id: string) {
@@ -537,7 +710,7 @@ This sets up:
 :::note[Cognito Authentication]
 If you selected `Cognito` authentication, you will need to supply the Cognito configuration:
 
-```hcl {3, 5-6}
+```hcl {6-7}
 module "my_api" {
   source = "../../common/terraform/src/app/apis/my-api"
 
@@ -583,6 +756,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" />
@@ -614,7 +791,7 @@ If you are actively working on both your CDK infrastructure and Smithy API toget
 </Fragment>
 <Fragment slot="terraform">
 :::note[Terraform Limitations]
-We do not support type-safe integrations for Terraform, and therefore no code generation targets are configured if you selected Terraform for your `iacProvider`.
+We do not support type-safe integrations for Terraform, and therefore no code generation targets are configured if you selected Terraform for your `iac`.
 :::
 </Fragment>
 </Infrastructure>
@@ -662,3 +839,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

@@ -38,12 +38,13 @@ The generator will create the following project structure in the `<directory>/<n
     - stacks CDK Stack definitions
       - application-stack.ts Main application stack
   - cdk.json CDK configuration
+  - package.json Project manifest defining the project's package name and dependencies
   - project.json Project configuration and build targets
   - checkov.yml Checkov configuration file
 
 </FileTree>
 
-If you set the `enableStageConfig` option, the generator also creates two shared packages for centralized credential management (if they don't already exist):
+If you set the `stageConfig` option, the generator also creates two shared packages for centralized credential management (if they don't already exist):
 
 <FileTree>
 
@@ -99,13 +100,14 @@ new ApplicationStage(app, 'my-app-sandbox', {
 
 The `env` property tells CDK which AWS account and region to deploy to. `CDK_DEFAULT_ACCOUNT` and `CDK_DEFAULT_REGION` are resolved automatically by the CDK CLI from your active AWS credentials. See the [CDK environments documentation](https://docs.aws.amazon.com/cdk/v2/guide/environments.html) for more details.
 
-If you generated with `enableStageConfig`, the `main.ts` reads account and region from a centralized config file instead, falling back to environment variables when no config is set:
+If you generated with `stageConfig`, the `main.ts` reads account and region from a centralized config file instead, falling back to environment variables when no config is set:
 
-```ts title="src/main.ts (with enableStageConfig)"
-import stagesConfig from ':my-scope/common-infra-config';
+```ts title="src/main.ts (with stageConfig)"
+import { resolveStage } from '@my-scope/common-infra-config';
 
-const projectStages = stagesConfig.projects?.['packages/infra']?.stages ?? {};
-const sandboxConfig = projectStages['my-app-sandbox'];
+// Looks up the stage under this project (packages/infra), falling back to
+// shared stages. Returns undefined when no config exists for the stage.
+const sandboxConfig = resolveStage('packages/infra', 'my-app-sandbox');
 
 new ApplicationStage(app, 'my-app-sandbox', {
   env: {
@@ -158,12 +160,12 @@ export class ApplicationStage extends Stage {
 ### Stage Credential Configuration
 
 :::note[Staged Configuration]
-This section applies when you generate with `enableStageConfig`. Without it, the generator produces a simpler setup where you manage AWS credentials yourself (e.g., by exporting `AWS_PROFILE` before deploying).
+This section applies when you generate with `stageConfig`. Without it, the generator produces a simpler setup where you manage AWS credentials yourself (e.g., by exporting `AWS_PROFILE` before deploying).
 :::
 
 When you have multiple stages targeting different AWS accounts, managing credentials manually can be error-prone, especially as the number of stages grows.
 
-The `enableStageConfig` option solves this by generating two shared packages:
+The `stageConfig` option solves this by generating two shared packages:
 
 - **`packages/common/infra-config`** — A single config file where you map each stage to its AWS credentials, account, and region. This is importable from any package in your workspace, so your CDK `main.ts` can read account and region from the same source of truth.
 - **`packages/common/scripts`** — `infra-deploy` and `infra-destroy` commands that wrap CDK with automatic credential resolution. When you run `deploy`, the script reads the config, sets the right AWS environment variables for the CDK child process, and runs `cdk deploy`. Your shell environment is never modified.
@@ -242,7 +244,7 @@ Each stage config includes a required `region` and an optional `account`:
 The generated `main.ts` reads these values from the config so that CDK synthesis and deployment use the same environment settings:
 
 ```ts title="src/main.ts"
-const sandboxConfig = projectStages['my-app-sandbox'];
+const sandboxConfig = resolveStage('packages/infra', 'my-app-sandbox');
 new ApplicationStage(app, 'my-app-sandbox', {
   env: {
     account: sandboxConfig?.account ?? process.env.CDK_DEFAULT_ACCOUNT,
@@ -270,7 +272,7 @@ If, for example, you created a tRPC API called `my-api`, you can simply import a
 ```ts title="src/stacks/application-stack.ts" {3, 9-12}
 import { Stack, StackProps } from 'aws-cdk-lib';
 import { Construct } from 'constructs';
-import { MyApi } from ':my-scope/common-constructs';
+import { MyApi } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
   constructor(scope: Construct, id: string, props?: StackProps) {
@@ -286,12 +288,12 @@ 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';
 import { Construct } from 'constructs';
-import { MyWebsite } from ':my-scope/common-constructs';
+import { MyWebsite } from '@my-scope/common-constructs';
 
 export class ApplicationStack extends Stack {
   constructor(scope: Construct, id: string, props?: StackProps) {
@@ -338,7 +340,7 @@ There may be instances where you want to suppress certain rules on resources. Yo
 #### Supress a rule on a given construct
 
 ```typescript
-import { suppressRules } from ':my-scope/common-constructs';
+import { suppressRules } from '@my-scope/common-constructs';
 
 // suppresses the CKV_AWS_XXX for the given construct.
 suppressRules(construct, ['CKV_AWS_XXX'], 'Reason');
@@ -347,7 +349,7 @@ suppressRules(construct, ['CKV_AWS_XXX'], 'Reason');
 #### Supress a rule on a descendant construct
 
 ```typescript
-import { suppressRules } from ':my-scope/common-constructs';
+import { suppressRules } from '@my-scope/common-constructs';
 
 // Supresses the CKV_AWS_XXX for the construct or any of its descendants if it is an instance of Bucket
 suppressRules(construct, ['CKV_AWS_XXX'], 'Reason', (construct) => construct instanceof Bucket);
@@ -375,12 +377,20 @@ After a build, you can deploy your infrastructure to AWS using the `deploy` targ
 Use the `deploy-ci` target if deploying in a CI/CD pipeline. See below for more details.
 :::
 
-First, make sure you have AWS credentials configured. If you generated with `enableStageConfig` and have configured stage credentials in `packages/common/infra-config/src/stages.config.ts`, the deploy command will automatically resolve and apply the correct credentials for the target stage. Otherwise, ensure your AWS credentials are set in your environment (e.g., via `AWS_PROFILE` or environment variables). See the [AWS credentials documentation](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) for the available options.
+First, make sure you have AWS credentials configured. If you generated with `stageConfig` and have configured stage credentials in `packages/common/infra-config/src/stages.config.ts`, the deploy command will automatically resolve and apply the correct credentials for the target stage. Otherwise, ensure your AWS credentials are set in your environment (e.g., via `AWS_PROFILE` or environment variables). See the [AWS credentials documentation](https://docs.aws.amazon.com/sdkref/latest/guide/access.html) for the available options.
 
 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`.