Merge branch 'aws:main' into claude/implement-blue-template-lKGq6

Author: sambloomberg-sketch

plugins/aws-core/skills/aws-amplify/SKILL.md

@@ -1,26 +1,28 @@
 # AI
 
+> **Prerequisites:** Backend defined in `amplify/backend.ts` with `defineBackend({ auth, data })`.
+
 ## Model Selection
 
 Use `a.ai.model()` to select an AI model in both `a.conversation()` and `a.generation()` routes. Pass a human-readable model name string:
 
 ```typescript
-aiModel: a.ai.model('Claude 3.5 Sonnet v2')
+aiModel: a.ai.model('Claude Sonnet 4.5')
 ```
 
-`a.ai.model()` accepts any supported model name:
+For the full list of supported models, see [AI Concepts: Models](https://docs.amplify.aws/react/ai/concepts/models/).
 
-- **Anthropic**: `'Claude 3 Haiku'`, `'Claude 3 Sonnet'`, `'Claude 3 Opus'`, `'Claude 3.5 Haiku'`, `'Claude 3.5 Sonnet'`, `'Claude 3.5 Sonnet v2'`, `'Claude 3.7 Sonnet'`, `'Claude Opus 4'`, `'Claude Sonnet 4'`, `'Claude Haiku 4.5'`, `'Claude Sonnet 4.5'`, `'Claude Opus 4.5'`, `'Claude Sonnet 4.6'`, `'Claude Opus 4.6'`
-- **Amazon**: `'Amazon Nova Pro'`, `'Amazon Nova Lite'`, `'Amazon Nova Micro'`
-- **Meta**: `'Llama 3.1 405B Instruct'`, `'Llama 3.1 70B Instruct'`, `'Llama 3.1 8B Instruct'`
-- **Cohere**: `'Cohere Command R+'`, `'Cohere Command R'`
-- **Mistral**: `'Mistral Large 2'`, `'Mistral Large'`, `'Mistral Small'`
+Key constraint: `a.generation()` routes only support Anthropic (Claude) models. `a.conversation()` routes work with any supported model.
 
 For models not in the supported list, use the raw escape hatch: `aiModel: { resourcePath: '<bedrock-model-id>' }`.
 
 Availability depends on the AWS region and Bedrock model access enablement.
 
-> **Note:** `a.generation()` routes only support Anthropic (Claude) models. `a.conversation()` routes work with any supported model.
+### Bedrock Model Access
+
+Some older or restricted models require explicit enablement in the AWS Bedrock console (Model access). On-demand foundation models (Claude Sonnet 4+, Nova) are available immediately. Amplify uses global inference profiles for cross-region model access.
+
+If you get `AccessDeniedException: Could not access the model with the specified model ID`, check **Bedrock → Model access** in your region.
 
 ## Backend: Conversation Routes
 
@@ -33,7 +35,7 @@ import { a, type ClientSchema } from '@aws-amplify/backend';
 
 const schema = a.schema({
   chat: a.conversation({
-    aiModel: a.ai.model('Claude 3.5 Sonnet v2'),
+    aiModel: a.ai.model('Claude Sonnet 4.5'),
     systemPrompt: 'You are a helpful assistant.',
   })
   .authorization(allow => allow.owner()),
@@ -44,12 +46,10 @@ const schema = a.schema({
 
 Use `a.generation()` for single-turn (stateless) inference.
 
-> **MUST:** Only Anthropic (Claude) models support `a.generation()` routes. Non-Anthropic models (Amazon Nova, Meta Llama, Cohere, Mistral) work with `a.conversation()` only.
-
 ```typescript
 const schema = a.schema({
   summarize: a.generation({
-    aiModel: a.ai.model('Claude 3.5 Sonnet v2'),
+    aiModel: a.ai.model('Claude Sonnet 4.5'),
     systemPrompt: 'Summarize the provided text concisely.',
     inferenceConfiguration: { maxTokens: 500, temperature: 0.3 },
   })
@@ -59,14 +59,16 @@ const schema = a.schema({
 });
 ```
 
-**CRITICAL — Authorization Constraints:**
+**Authorization constraints (these cause TypeError at CDK assembly if violated):**
 
-- **Conversation routes** (`a.conversation()`) **MUST** use `allow.owner()` authorization — `allow.authenticated()` and other non-owner strategies throw a TypeError at CDK assembly time (before deployment even begins).
-- **Generation routes** (`a.generation()`) **MUST** use non-owner authorization (`allow.authenticated()`, `allow.guest()`, `allow.group()`, or `allow.publicApiKey()`) — `allow.owner()` throws a TypeError at CDK assembly time (before deployment even begins).
+- **Conversation routes** (`a.conversation()`) require `allow.owner()` authorization — `allow.authenticated()` and other non-owner strategies throw a TypeError at CDK assembly time.
+- **Generation routes** (`a.generation()`) require non-owner authorization (`allow.authenticated()`, `allow.guest()`, `allow.group()`, or `allow.publicApiKey()`) — `allow.owner()` throws a TypeError at CDK assembly time.
 
 These constraints are asymmetric and frequently confused. Getting them wrong
 causes the CDK synthesis to fail with a non-obvious TypeError.
 
+> **Security:** Conversation history sent to Amazon Bedrock may contain PII. Do not log full request/response payloads in production. Enable CloudWatch Logs encryption (KMS) and set appropriate retention policies for any logs that may capture inference data.
+
 ### Backend Integration
 
 AI conversation and generation routes are part of your data schema. Import into `amplify/backend.ts`:
@@ -88,7 +90,7 @@ import { myToolFunc } from '../functions/my-tool/resource';
 
 const schema = a.schema({
   chat: a.conversation({
-    aiModel: a.ai.model('Claude 3.5 Sonnet v2'),
+    aiModel: a.ai.model('Claude Sonnet 4.5'),
     systemPrompt: 'You are a helpful assistant with tool access.',
     tools: [
       {
@@ -170,7 +172,7 @@ Pagination: use `limit` and `nextToken` parameters on `.list()`.
 
 Subscribe to streaming responses for real-time token delivery:
 
-In React, **MUST** wrap in `useEffect` and return the cleanup function:
+In React, wrap in `useEffect` and return the cleanup function:
 
 ```tsx
 useEffect(() => {
@@ -189,18 +191,6 @@ useEffect(() => {
 
 ## Pitfalls
 
-- **Conversation auth MUST be `allow.owner()`:** Using
-  `allow.authenticated()` or any other non-owner strategy on
-  `a.conversation()` throws a TypeError at CDK assembly time.
-- **Generation auth MUST NOT be `allow.owner()`:** Using
-  `allow.owner()` on `a.generation()` throws a TypeError at CDK assembly
-  time. Use `allow.authenticated()`, `allow.guest()`, or `allow.group()`.
-- **Missing AI route in data schema:** The conversation or generation
-  route **MUST** be defined in your `a.schema()` — without it, the
-  frontend client has no AI endpoint to call.
-- **Model availability:** Not all Bedrock models are enabled by default —
-  you **MUST** enable model access in the AWS console (Bedrock → Model
-  access) before using a model in `a.ai.model()`.
 - **Message content structure:** Both `sendMessage('Hello')` (string) and
   `sendMessage({ content: [{ text: 'Hello' }] })` (object) are valid. Use
   the object form when sending images or tool results.

plugins/aws-core/skills/aws-amplify/references/ai.md

@@ -1,5 +1,7 @@
 # Auth — Backend
 
+> **Prerequisites:** Backend defined in `amplify/backend.ts` with `defineBackend({ auth, data })`.
+
 ## Basic Auth Setup
 
 Define authentication in `amplify/auth/resource.ts`:
@@ -88,8 +90,8 @@ password-based login in the same `defineAuth` configuration.
 
 ## Social Login
 
-You **MUST** use `secret()` for OAuth client secrets — never hardcode
-credentials.
+Use `secret()` for OAuth client secrets — hardcoding credentials exposes
+them in source control.
 
 ```typescript
 import { defineAuth, secret } from '@aws-amplify/backend';
@@ -122,27 +124,34 @@ export const auth = defineAuth({
 });
 ```
 
-Set secrets via CLI: `echo "<value>" | npx ampx sandbox secret set GOOGLE_CLIENT_ID`.
-For provider-specific OAuth setup guides, **SHOULD** consult AWS
-documentation via available tools; when unavailable, **MUST** use web
+Set secrets via CLI: `echo -n "<value>" | npx ampx sandbox secret set MY_OAUTH_CLIENT_ID`. (The documented approach uses an interactive prompt; piping with `echo -n` is a practical alternative for scripts.)
+For provider-specific OAuth setup guides, consult AWS
+documentation via available tools; when unavailable, use web
 search or AWS CLI.
 
 ## SAML / OIDC (Enterprise)
 
-OIDC providers are configured directly in `externalProviders`:
+OIDC providers are configured inside `loginWith.externalProviders`:
 
 ```typescript
-externalProviders: {
-  oidc: [{
-    name: 'MyOIDC',
-    clientId: secret('OIDC_CLIENT_ID'),
-    clientSecret: secret('OIDC_CLIENT_SECRET'),
-    issuerUrl: 'https://idp.example.com',
-    attributeMapping: { email: 'email' },
-  }],
-  callbackUrls: ['http://localhost:3000/'],
-  logoutUrls: ['http://localhost:3000/'],
-}
+import { defineAuth, secret } from '@aws-amplify/backend';
+
+export const auth = defineAuth({
+  loginWith: {
+    email: true,
+    externalProviders: {
+      oidc: [{
+        name: 'MyOIDC',
+        clientId: secret('OIDC_CLIENT_ID'),
+        clientSecret: secret('OIDC_CLIENT_SECRET'),
+        issuerUrl: 'https://idp.example.com',
+        attributeMapping: { email: 'email' },
+      }],
+      callbackUrls: ['http://localhost:3000/'],
+      logoutUrls: ['http://localhost:3000/'],
+    },
+  },
+});
 ```
 
 **SAML** is NOT supported in `defineAuth` — the `ExternalProviderSpecificFactoryProps` type has no `saml` property. The lower-level `auth-construct` package supports SAML, but it was never wired up to the high-level API. Use CDK escape hatches via `backend.auth.resources` to configure SAML providers:
@@ -182,21 +191,51 @@ import { defineFunction } from '@aws-amplify/backend';
 export const preSignUp = defineFunction({ name: 'pre-sign-up' });
 ```
 
-### Guest (Unauthenticated) Access
+> **Tip:** Auth trigger handlers need `@types/aws-lambda` for TypeScript types.
+
+### Trigger Lambda + Data Table Access
+
+If a trigger Lambda (e.g., `postConfirmation`) needs to write to a `defineData` table, this can create a circular dependency. Workarounds:
+
+1. **Access via `backend.auth.resources`** (avoids cycle when trigger is in auth stack):
+
+```typescript
+// backend.ts
+const postConfirmFn = backend.auth.resources.userPool.triggers?.postConfirmation;
+const table = backend.data.resources.tables['UserProfile'];
+table.grantWriteData(postConfirmFn);
+postConfirmFn.addEnvironment('TABLE_NAME', table.tableName);
+```
+
+1. **Separate DynamoDB table** — create via CDK (not `defineData`) to avoid stack coupling.
+
+## Guest (Unauthenticated) Access
 
 Guest access is **enabled by default** in Amplify Gen2 — the Cognito Identity Pool is created with `allowUnauthenticatedIdentities: true` automatically.
 
-To use guest access in your data models, set `defaultAuthorizationMode` to `'iam'`:
+To use guest access in your data models, set `defaultAuthorizationMode` to `'iam'` and add `allow.guest()` authorization rules:
 
 ```typescript
+const schema = a.schema({
+  Todo: a.model({
+    content: a.string(),
+  }).authorization(allow => [
+    allow.guest().to(['read']),   // unauthenticated users can read
+    allow.owner(),                // owners can CRUD
+  ]),
+});
+
 export const data = defineData({
   schema,
   authorizationModes: {
-    defaultAuthorizationMode: 'iam',
+    defaultAuthorizationMode: 'iam',   // required for guest access
+    apiKeyAuthorizationMode: { expiresInDays: 7 }, // optional alternative
   },
 });
 ```
 
+> **Security:** Guest access grants unauthenticated users IAM-authorized access. For production, explicitly evaluate whether guest access is needed and prefer `allow.authenticated()` as the default. If guest access is required, scope it to read-only on non-sensitive models only.
+
 To **disable** guest access, use a CDK override in `backend.ts`:
 
 ```typescript
@@ -208,8 +247,8 @@ cfnIdentityPool.allowUnauthenticatedIdentities = false;
 
 - **Trigger not registered (silent no-op):** Defining a trigger function
   with `defineFunction` but NOT adding it to `triggers: {}` in `defineAuth`
-  causes a **silent no-op** — the function deploys but never fires. You
-  **MUST** both define AND register: `triggers: { preSignUp, postConfirmation }`.
+  causes a **silent no-op** — the function deploys but never fires.
+  Both define AND register: `triggers: { preSignUp, postConfirmation }`.
 - **Hardcoded secrets:** Using string literals instead of `secret()` for
   OAuth credentials exposes them in source control.
 - **Missing scopes:** Social providers default to minimal scopes — add
@@ -220,8 +259,9 @@ cfnIdentityPool.allowUnauthenticatedIdentities = false;
 - **MFA method mismatch:** Enabling `sms: true` in MFA requires a phone
   number attribute on the user pool — add `phone_number` to user attributes.
   Similarly, `email: true` in MFA requires an email attribute on the user pool.
-- **Secrets in CI/CD:** For branch environments, use:
-  `npx ampx secret set KEY_NAME --branch main --app-id APP_ID`.
+- **Secrets in CI/CD:** For branch environments, manage secrets through the
+  **Amplify console** (App settings → Environment variables → Secrets).
+  The `ampx sandbox secret` command only works for local sandbox environments.
 
 ## Links