@aws-blocks/core 0.1.13 → 0.1.18

package/README.md

@@ -63,7 +63,7 @@ The typed `import { api } from 'aws-blocks'` client is the normal path. The HTTP
 
 `POST` to the RPC path `/aws-blocks/api`:
 
-- Local dev: `http://localhost:3001/aws-blocks/api`
+- Local dev: `http://localhost:3000/aws-blocks/api` (the default template serves the backend and frontend from a single front door on `:3000`). Only the `backend` and `amplify` templates serve the API on `:3001`.
 - Deployed: the API Gateway stage URL + `/aws-blocks/api`
 
 The body is JSON-RPC 2.0:
@@ -79,15 +79,70 @@ The body is JSON-RPC 2.0:
 Working example:
 
 ```bash
-curl -X POST http://localhost:3001/aws-blocks/api \
+curl -X POST http://localhost:3000/aws-blocks/api \
   -H 'Content-Type: application/json' \
   -d '{"jsonrpc":"2.0","method":"api.greet","params":["World"],"id":1}'
 # → {"jsonrpc":"2.0","result":{"message":"Hello, World!"},"id":1}
 ```
 
-### ApiError / isBlocksError
+#### How the server reads `params` (and what it rejects)
 
-Typed error handling across the wire.
+The request body is parsed by `parseRpcRequest`, which turns `params` into the positional argument list your method is called with:
+
+| Body `params` | Arguments the method receives |
+|---|---|
+| `["World", 42]` (array) | `('World', 42)`, used as-is |
+| `{"name":"World","times":42}` (object) | `('World', 42)` via `Object.values()`, so **key insertion order decides argument order** |
+| omitted or `null` | `()`, no arguments |
+
+A named object is convenient for `curl`, but it is only safe when the keys are written in the same order as the method signature. Prefer the array form in anything automated.
+
+One shape that looks reasonable and is **not** supported: a top-level JSON **array** as the whole body (a JSON-RPC batch). The parser reads `jsonrpc` and `method` off the body object, so an array body fails validation instead of running anything:
+
+```bash
+curl -X POST http://localhost:3000/aws-blocks/api \
+  -H 'Content-Type: application/json' \
+  -d '[{"jsonrpc":"2.0","method":"api.greet","params":["a"],"id":1}]'
+# → HTTP 200
+# {"jsonrpc":"2.0","error":{"code":-32600,"message":"Invalid Request: expected JSON-RPC 2.0 — ...",
+#    "data":{"name":"InvalidRequest"}},"id":null}
+```
+
+`id` is `null` in that response because an array body has no `id` to echo. Send one call per request. Body that isn't valid JSON at all returns `-32700 Parse error`, also with HTTP `200`.
+
+#### Runtime config (`/.blocks-sandbox/config.json`)
+
+The generated client does not hardcode the API URL; it resolves one at first call, in this order:
+
+1. `BLOCKS_API_URL` env var (set by the Hosting construct on SSR compute).
+2. `BLOCKS_CONFIG` env var (the whole config as JSON).
+3. Node only: the file `.blocks-sandbox/config.json`, read from the **process working directory**.
+4. Browser only: `fetch('/.blocks-sandbox/config.json')`.
+
+Both env vars are normally written for you: `Hosting` injects them into every SSR compute function at synth, and `npm run sandbox` sets `BLOCKS_API_URL` on the dev server it spawns. You set `BLOCKS_API_URL` yourself only when you run the SSR host outside that tooling, like a framework dev server on its own port (`BLOCKS_API_URL=http://localhost:3001/aws-blocks/api next dev`) or your own container. `BLOCKS_CONFIG` is Hosting's serialized `backendConfig` rather than a knob to hand-write, so prefer `BLOCKS_API_URL` for a custom host.
+
+Two things about that path burn time when debugging:
+
+- The directory is **dotted**: `/.blocks-sandbox/config.json`. `/config.json` is not a route and never was: locally the dev server only answers `GET /.blocks-sandbox/config.json`, and in production the Hosting construct only adds a `/.blocks-sandbox/*` static behaviour. A `404` from `curl http://localhost:3000/config.json` says nothing about your config.
+- `{"_placeholder":true}` is a **valid, expected** body in the frontend build output. The Hosting construct writes that stub into the static assets directory during CDK synth so the file exists as a static route while the real `apiUrl` is still an unresolved CloudFormation token; the deploy then uploads the resolved config over it. Finding the stub in `dist/.blocks-sandbox/config.json` (or on the origin between synth and deploy) is the design working, not a broken config.
+
+What you should see instead, per environment:
+
+```bash
+# Local dev / sandbox: served by the dev server itself, Cache-Control: no-store
+curl http://localhost:3000/.blocks-sandbox/config.json
+# → {"apiUrl":"http://localhost:3000/aws-blocks/api","environment":"local"}
+
+# After a deploy: written by the deploy script and uploaded to the origin
+cat .blocks-sandbox/config.json
+# → { "apiUrl": "https://<id>.execute-api.<region>.amazonaws.com/prod/aws-blocks/api", "environment": "production" }
+```
+
+So a real config problem looks like the client throwing `Blocks API URL not configured` (or `... is not configured (source: ...)`), not like a `404` on `/config.json`. If a **deployed** origin keeps serving `{"_placeholder":true}` after a successful deploy, that is a genuine bug: the config upload or the CloudFront invalidation did not land.
+
+### ApiError / isBlocksError / hasAuthError
+
+Typed error handling across the wire. All three are exported from `@aws-blocks/core`, and re-exported from `@aws-blocks/blocks`.
 
 ```typescript
 import { ApiError, isBlocksError } from '@aws-blocks/core';
@@ -101,32 +156,140 @@ catch (e) {
 }
 ```
 
+#### `new ApiError(message, status, options?)`
+
+```typescript
+new ApiError(
+  message: string,
+  status: number,
+  options?: { name?: string; cause?: unknown; retriable?: boolean },
+)
+```
+
+| Argument | Required | What it does |
+|---|---|---|
+| `message` | yes | Human-facing text. Crosses the wire, so don't put internals in it. |
+| `status` | yes | HTTP status code. Any number; nothing validates it against a known status. |
+| `options.name` | no | The structured error name `isBlocksError` / `hasAuthError` match on (e.g. `'ItemNotFoundException'`). Defaults to `'ApiError'`, which carries no meaning, so treat it as "unnamed". |
+| `options.cause` | no | Underlying error. **Stays server-side**, never serialized. |
+| `options.retriable` | no | `true` when the caller can retry the same action without restarting the flow (wrong MFA code, wrong password on re-prompt). Defaults to `false`. |
+
+The instance exposes `message`, `name`, `status` and `retriable` as readable properties, and it is a real `Error`, so `instanceof Error` and stack traces behave normally.
+
+How `status` reaches the client over JSON-RPC: an uncaught error inside an RPC method is encoded as an error response whose **`code` is the `ApiError`'s `status`** (positive numbers can't collide with the reserved `-32xxx` range). `name` and `retriable` ride along in `error.data`. A non-`ApiError` throw becomes code `500` with no `data.name`.
+
+```jsonc
+// throw new ApiError('Username already taken', 409,
+//   { name: 'ConditionalCheckFailedException', retriable: true })
+{ "jsonrpc": "2.0", "id": 1, "error": {
+  "code": 409,
+  "message": "Username already taken",
+  "data": { "name": "ConditionalCheckFailedException", "retriable": true }
+}}
+```
+
+The client decodes that back into an `ApiError` with the same `status`, `name` and `retriable`, which is why the same `isBlocksError(e, ...)` check works on both sides. Reserved JSON-RPC codes (`-32600`, `-32700`, …) decode to `status: 500`.
+
+#### `hasAuthError(state, name)`
+
+```typescript
+import { hasAuthError } from '@aws-blocks/core';
+
+function hasAuthError<T extends { errorName?: string }, N extends string>(
+  state: T | null | undefined,
+  name: N,
+): state is T & { errorName: N }
+```
+
+The auth blocks' recommended client path (`setAuthState()` / `getAuthState()`) **returns** a failed `AuthState` instead of throwing, so there is no `Error` for `isBlocksError` to inspect. `hasAuthError` is the equivalent guard for that returned object: it compares `state.errorName` to `name` and narrows the type. It's a plain equality check, so a `null` / `undefined` state and a state with no `errorName` both return `false` and no defensive wrapping is needed.
+
+```typescript
+const next = await authApi.setAuthState({ action: 'signIn', username, password });
+if (hasAuthError(next, AuthBasicErrors.InvalidCredentials)) {
+  // unknown user or wrong password → offer sign-up
+}
+```
+
+Rule of thumb: **thrown error → `isBlocksError`; returned `AuthState` → `hasAuthError`.** Match on the block's error constant, never on the human-facing `error` string.
+
 ### RawRoute
 
-Path-based HTTP routing Building Block for endpoints that need full request/response control — webhooks, REST APIs, health checks, file downloads. Use `ApiNamespace` (RPC) for typed function calls; use `RawRoute` when you need raw HTTP semantics.
+Path-based HTTP routing Building Block for endpoints that need full request/response control: webhooks, health checks, redirects, file downloads, anything a browser or third party has to hit with a plain `GET`. Use `ApiNamespace` (RPC) for typed function calls; use `RawRoute` when you need raw HTTP semantics.
+
+```typescript
+new RawRoute(scope: ScopeParent, id: string, options: {
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+  path?: string;
+  handler: (context: BlocksContext) => Promise<void>;
+})
+```
+
+A full `GET` that sets its own status, content type and body:
 
 ```typescript
 import { RawRoute } from '@aws-blocks/blocks';
 
-// Explicit path
-new RawRoute(scope, 'GetUser', {
+new RawRoute(scope, 'status', {
   method: 'GET',
-  path: '/users/{id}',
-  handler: async (context) => {
-    const userId = context.request.params.id;
-    context.response.send({ id: userId });
+  path: '/status',
+  handler: async (ctx) => {
+    ctx.response.status = 200;
+    ctx.response.headers.set('Content-Type', 'text/html; charset=utf-8');
+    ctx.response.send('<h1>ok</h1>');
   },
 });
+```
 
-// Derived path — path omitted, becomes /health from scope chain
-new RawRoute(scope, 'health', { method: 'GET', handler: async (ctx) => {
-  ctx.response.send({ status: 'ok' });
-}});
+```bash
+curl -i http://localhost:3000/status
+# HTTP/1.1 200 OK
+# content-type: text/html; charset=utf-8
+#
+# <h1>ok</h1>
 ```
 
-Supports exact paths (`/health`), named parameters (`/users/{id}`), and wildcards (`/files/*`). Path can be omitted — it's derived from scope-chain IDs.
+The handler returns nothing; you write the response through `ctx.response`:
+
+| On `ctx.response` | Notes |
+|---|---|
+| `status: number` | Assignable. Defaults to `200`. |
+| `headers: Headers` | Standard `Headers`. Set `Content-Type` yourself; a string body is sent as-is, an object is serialized as JSON. |
+| `send(body)` | Call once with the body. `send('')` for an empty body (redirects, `204`). |
+
+And what you read from `ctx.request`:
+
+| On `ctx.request` | Notes |
+|---|---|
+| `params` | Path parameters, e.g. route `/users/{id}` + request `/users/42` → `{ id: '42' }`. Always `{}` for RPC methods. |
+| `url` | Absolute `URL` of the request. Use `url.searchParams` for the query string. |
+| `headers` | Request `Headers`, including `cookie`. |
+| `json()` / `text()` / `body` | Body as parsed JSON, raw text, or a `ReadableStream`. |
+| `signal` | `AbortSignal` that fires just before the platform's timeout response. Pass it to `fetch`/SDK calls. `undefined` in local dev. |
+
+Reading a path parameter and a query parameter:
+
+```typescript
+new RawRoute(scope, 'user', {
+  method: 'GET',
+  path: '/users/{id}',
+  handler: async (ctx) => {
+    ctx.response.headers.set('Content-Type', 'application/json');
+    ctx.response.send({ id: ctx.request.params.id, q: ctx.request.url.searchParams.get('q') });
+  },
+});
+// GET /users/42?q=hello → {"id":"42","q":"hello"}
+```
+
+Path syntax: exact (`/health`), named parameter capturing one segment (`/users/{id}`), or a trailing wildcard capturing the rest (`/files/*`, available as `params['*']`). One wildcard per route, last segment only. Named parameters are URL-decoded; wildcard captures are not, so validate them before touching a filesystem or an S3 key.
+
+`path` can be omitted, in which case it is derived from the scope-chain IDs, so `Scope('app') → Scope('v1') → RawRoute('health')` gives `/v1/health`. That means restructuring your construct tree silently changes URLs, so pass an explicit `path` for anything a client depends on.
+
+Registration rules worth knowing before you hit them at runtime:
 
-📖 **Full RawRoute documentation (see source repo)**
+- Routes must be constructed while the backend module is loading (top level of `aws-blocks/index.ts`, or from a block's constructor). Registering after the handler is created throws.
+- `/aws-blocks` itself and `/aws-blocks/api` (plus anything under it) are reserved for RPC dispatch, and `/` is not routable, so use a sub-path.
+- The same `method` + `path` twice throws `RawRouteErrors.DuplicateRoute`; catch it with `isBlocksError(e, RawRouteErrors.DuplicateRoute)`.
+- No extra AWS resources are created. The existing API Gateway proxy already forwards every path to the same Lambda, which checks the route registry before falling through to RPC.
 
 ### Pipeline
 

package/dist/cdk/blocks-backend.d.ts

@@ -1,5 +1,6 @@
 import * as cdk from 'aws-cdk-lib';
 import * as apigateway from 'aws-cdk-lib/aws-apigateway';
+import * as iam from 'aws-cdk-lib/aws-iam';
 import { Construct } from 'constructs';
 /**
  * Validate that the Node.js process was started with `--conditions=cdk`.
@@ -19,6 +20,7 @@ export declare function setupBlocksInfra(scope: Construct, props: BlocksBackendP
     handler: cdk.aws_lambda_nodejs.NodejsFunction;
     gateway: cdk.aws_apigateway.RestApi;
     apiUrl: string;
+    executionRole: cdk.aws_iam.Role;
 };
 /**
  * Standalone CDK construct that provisions the Blocks backend: a single Lambda
@@ -42,6 +44,8 @@ export declare class BlocksBackend extends Construct {
     readonly gateway: apigateway.RestApi;
     readonly handler: cdk.aws_lambda_nodejs.NodejsFunction;
     readonly backendHandlerPath: string;
+    /** Shared IAM role assumed by all Blocks compute. Building Blocks grant to this role. */
+    readonly executionRole: iam.IRole;
     /**
      * The fullId used by child Scopes to compute their env var names,
      * construct IDs, and physical resource names (e.g., DynamoDB table names).

package/dist/cdk/blocks-backend.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"blocks-backend.d.ts","sourceRoot":"","sources":["../../src/cdk/blocks-backend.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AAEnC,OAAO,KAAK,UAAU,MAAM,4BAA4B,CAAC;AAEzD,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAQvC;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAkB/C;AAED,MAAM,WAAW,kBAAkB;IACjC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,kBAAkB,EAAE,EAAE,CAAC,EAAE,MAAM;;;;EA0GxF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAc,SAAQ,SAAS;IAC1C,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC;IAC5C,SAAgB,OAAO,EAAE,GAAG,CAAC,iBAAiB,CAAC,cAAc,CAAC;IAC9D,SAAgB,kBAAkB,EAAE,MAAM,CAAC;IAE3C;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,MAAM,IAAI,MAAM,CAUnB;IAED,OAAO;WAmBM,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB;CAsB5E"}
+{"version":3,"file":"blocks-backend.d.ts","sourceRoot":"","sources":["../../src/cdk/blocks-backend.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AAEnC,OAAO,KAAK,UAAU,MAAM,4BAA4B,CAAC;AACzD,OAAO,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAE3C,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAQvC;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAkB/C;AAED,MAAM,WAAW,kBAAkB;IACjC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;CACxB;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,kBAAkB,EAAE,EAAE,CAAC,EAAE,MAAM;;;;;EA6HxF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAc,SAAQ,SAAS;IAC1C,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,OAAO,EAAE,UAAU,CAAC,OAAO,CAAC;IAC5C,SAAgB,OAAO,EAAE,GAAG,CAAC,iBAAiB,CAAC,cAAc,CAAC;IAC9D,SAAgB,kBAAkB,EAAE,MAAM,CAAC;IAC3C,yFAAyF;IACzF,SAAgB,aAAa,EAAE,GAAG,CAAC,KAAK,CAAC;IAEzC;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,MAAM,IAAI,MAAM,CAUnB;IAED,OAAO;WAoBM,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB;CAsB5E"}

package/dist/cdk/blocks-backend.js

@@ -3,6 +3,7 @@
 import * as cdk from 'aws-cdk-lib';
 import * as lambda from 'aws-cdk-lib/aws-lambda-nodejs';
 import * as apigateway from 'aws-cdk-lib/aws-apigateway';
+import * as iam from 'aws-cdk-lib/aws-iam';
 import { CfnGroup } from 'aws-cdk-lib/aws-resourcegroups';
 import { Construct } from 'constructs';
 import { pathToFileURL } from 'node:url';
@@ -35,10 +36,28 @@ export function assertCdkConditionActive() {
 }
 /** Shared infra setup — creates Lambda + API Gateway on the given scope. */
 export function setupBlocksInfra(scope, props, id) {
+    // ── Shared execution role ──────────────────────────────────────────────
+    // A single IAM role that every Building Block grants to. Provisioned here so
+    // it exists before the backend module is imported (Building Blocks reach it
+    // via `scope.executionRole`). Block grants sit on the role's default (inline)
+    // policy, exactly as they did on the auto-generated NodejsFunction role.
+    //
+    // AWSLambdaBasicExecutionRole is attached explicitly because the auto-role
+    // included it by default — omitting it would silently break CloudWatch Logs.
+    const executionRole = new iam.Role(scope, 'BlocksRole', {
+        // CompositePrincipal (rather than a bare ServicePrincipal) so additional
+        // compute types can assume this same shared role as they are introduced
+        // (e.g. ECS tasks via ecs-tasks.amazonaws.com), by adding principals here.
+        assumedBy: new iam.CompositePrincipal(new iam.ServicePrincipal('lambda.amazonaws.com')),
+        managedPolicies: [
+            iam.ManagedPolicy.fromAwsManagedPolicyName('service-role/AWSLambdaBasicExecutionRole'),
+        ],
+    });
     const handler = new lambda.NodejsFunction(scope, 'Handler', {
         entry: props.backendHandlerPath,
         runtime: DEFAULT_NODE_RUNTIME,
         handler: 'handler',
+        role: executionRole,
         memorySize: 2048,
         timeout: cdk.Duration.seconds(60 * 15),
         environment: {
@@ -126,7 +145,7 @@ export function setupBlocksInfra(scope, props, id) {
     registerConfig(scope, 'BB_RESOURCES_GROUP_URL', resourcesUrl);
     registerConfig(scope, 'BB_SETTINGS_GROUP_URL', settingsUrl);
     registerBuiltinRoutes();
-    return { handler, gateway: api, apiUrl: `${api.url}${BLOCKS_RPC_PREFIX.slice(1)}` };
+    return { handler, gateway: api, apiUrl: `${api.url}${BLOCKS_RPC_PREFIX.slice(1)}`, executionRole };
 }
 /**
  * Standalone CDK construct that provisions the Blocks backend: a single Lambda
@@ -150,6 +169,8 @@ export class BlocksBackend extends Construct {
     gateway;
     handler;
     backendHandlerPath;
+    /** Shared IAM role assumed by all Blocks compute. Building Blocks grant to this role. */
+    executionRole;
     /**
      * The fullId used by child Scopes to compute their env var names,
      * construct IDs, and physical resource names (e.g., DynamoDB table names).
@@ -189,6 +210,7 @@ export class BlocksBackend extends Construct {
         this.handler = infra.handler;
         this.gateway = infra.gateway;
         this.apiUrl = infra.apiUrl;
+        this.executionRole = infra.executionRole;
         // Override BLOCKS_STACK_NAME to include the parent stack name so runtime
         // resource lookups (DynamoDB table names) match the CDK-time fullId
         // and are unique per deployment.

package/dist/cdk/blocks-backend.test.js

@@ -5,8 +5,10 @@ import assert from 'node:assert';
 import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import * as cdk from 'aws-cdk-lib';
-import { Template } from 'aws-cdk-lib/assertions';
+import { Template, Match } from 'aws-cdk-lib/assertions';
+import { PolicyStatement } from 'aws-cdk-lib/aws-iam';
 import { BlocksBackend } from './blocks-backend.js';
+import { Scope } from './index.js';
 // Simulate the CDK condition being active (tests import CDK files directly)
 before(() => {
     process.env.NODE_OPTIONS = (process.env.NODE_OPTIONS ?? '') + ' --conditions=cdk';
@@ -16,6 +18,7 @@ const handlerPath = join(__dirname, '__fixtures__', 'handler.js');
 const sideEffectBackendPath = join(__dirname, '__fixtures__', 'side-effect-backend.js');
 const factoryBackendPath = join(__dirname, '__fixtures__', 'factory-backend.js');
 const fullIdConstructBackendPath = join(__dirname, '__fixtures__', 'fullid-construct-backend.js');
+const EXECUTION_ROLE_MARKER_ACTION = 'blocks-test:MarkerAction';
 describe('ESM cache-busting (multi-stage)', () => {
     test('BlocksBackend.create() with same backendCDKPath but different IDs produces constructs in each', async () => {
         const app = new cdk.App();
@@ -66,6 +69,73 @@ describe('synth shape (drop into existing stack)', () => {
         template.resourceCountIs('AWS::ApiGateway::RestApi', 2);
     });
 });
+describe('shared execution role', () => {
+    test('exposes executionRole on the backend', async () => {
+        const app = new cdk.App();
+        const parent = new cdk.Stack(app, 'RoleSurfaceStack');
+        const backend = await BlocksBackend.create(parent, 'Blocks', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: sideEffectBackendPath,
+        });
+        assert.ok(backend.executionRole, 'BlocksBackend should expose .executionRole');
+    });
+    test('synth produces a Lambda-assumable role with basic execution, and the handler uses it', async () => {
+        const app = new cdk.App();
+        const parent = new cdk.Stack(app, 'RoleSynthStack');
+        await BlocksBackend.create(parent, 'Blocks', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: sideEffectBackendPath,
+        });
+        const template = Template.fromStack(parent);
+        // The shared role (logical id derived from the 'BlocksRole' construct id)
+        // is assumable by Lambda and carries AWSLambdaBasicExecutionRole (so
+        // CloudWatch Logs keep working after swapping off the auto-role). Other
+        // roles exist (API Gateway CloudWatch role, config BucketDeployment role),
+        // so we target ours by logical id.
+        const roles = template.findResources('AWS::IAM::Role');
+        const blocksRoleId = Object.keys(roles).find(k => k.includes('BlocksRole'));
+        assert.ok(blocksRoleId, 'expected a role from the BlocksRole construct');
+        const blocksRole = roles[blocksRoleId];
+        assert.deepStrictEqual(blocksRole.Properties.AssumeRolePolicyDocument.Statement[0], {
+            Action: 'sts:AssumeRole',
+            Effect: 'Allow',
+            Principal: { Service: 'lambda.amazonaws.com' },
+        });
+        assert.ok(JSON.stringify(blocksRole.Properties.ManagedPolicyArns ?? []).includes('AWSLambdaBasicExecutionRole'), 'BlocksRole should attach AWSLambdaBasicExecutionRole');
+        // The Blocks handler references the shared role, not an auto-generated one.
+        template.hasResourceProperties('AWS::Lambda::Function', {
+            Role: { 'Fn::GetAtt': [blocksRoleId, 'Arn'] },
+        });
+    });
+    test('a nested block resolves executionRole via the construct-tree walk', async () => {
+        const app = new cdk.App();
+        const parent = new cdk.Stack(app, 'RoleResolveStack');
+        const backend = await BlocksBackend.create(parent, 'Blocks', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: sideEffectBackendPath,
+        });
+        // Build nested Scopes under the backend (outer → inner), the same shape a
+        // real Building Block tree has, and grant a uniquely-named marker action to
+        // `this.executionRole` from the innermost scope. If the getter's tree-walk
+        // failed, it would resolve the wrong role (or throw), and the marker would
+        // not land on the backend's shared role.
+        // `create()` sets globalThis.CURRENT_BLOCKS_STACK = backend, so a parent-less
+        // Scope attaches under the backend (the same way a real backend module's
+        // top-level blocks do); `inner` is then nested one level deeper.
+        const outer = new Scope('outer');
+        const inner = new Scope('inner', { parent: outer });
+        // Resolves to the backend's shared role from two levels deep.
+        assert.strictEqual(inner.executionRole, backend.executionRole);
+        inner.executionRole.addToPrincipalPolicy(new PolicyStatement({ actions: [EXECUTION_ROLE_MARKER_ACTION], resources: ['*'] }));
+        // The grant lands on the shared role's default inline policy (AWS::IAM::Policy).
+        const template = Template.fromStack(parent);
+        template.hasResourceProperties('AWS::IAM::Policy', {
+            PolicyDocument: {
+                Statement: Match.arrayWith([Match.objectLike({ Action: EXECUTION_ROLE_MARKER_ACTION })]),
+            },
+        });
+    });
+});
 describe('factory function support', () => {
     test('BlocksBackend.create() calls default export function with the backend instance', async () => {
         const app = new cdk.App();

package/dist/cdk/blocks-stack.test.js

@@ -6,7 +6,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname, join } from 'node:path';
 import * as cdk from 'aws-cdk-lib';
 import { BlocksBackend } from './blocks-backend.js';
-import { BlocksStack } from './index.js';
+import { BlocksStack, Scope } from './index.js';
 // Simulate the CDK condition being active (tests import CDK files directly)
 before(() => {
     process.env.NODE_OPTIONS = (process.env.NODE_OPTIONS ?? '') + ' --conditions=cdk';
@@ -54,6 +54,37 @@ describe('legacy side-effect mode (no default export)', () => {
         assert.ok(marker, 'Side-effect-only module should register construct via globalThis.CURRENT_BLOCKS_STACK');
     });
 });
+describe('shared execution role (BlocksStack)', () => {
+    // The role synth shape and the Scope.executionRole tree-walk are shared code
+    // (setupBlocksInfra + the getter), covered in blocks-backend.test.ts. The only
+    // BlocksStack-specific behavior is that its own constructor wires
+    // executionRole — a separate code path from BlocksBackend's constructor.
+    test('BlocksStack wires executionRole via its constructor', async () => {
+        const app = new cdk.App();
+        const stack = await BlocksStack.create(app, 'StackRoleStack', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: sideEffectBackendPath,
+        });
+        assert.ok(stack.executionRole, 'BlocksStack should expose a populated .executionRole');
+    });
+});
+describe('executionRole globalThis fallback', () => {
+    test('resolves via globalThis.CURRENT_BLOCKS_STACK when no owner is in the tree', async () => {
+        const app = new cdk.App();
+        const stack = await BlocksStack.create(app, 'FallbackStack', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: sideEffectBackendPath,
+        });
+        // A Scope whose construct-tree ancestry has no BlocksStack/BlocksBackend
+        // (parented under a plain cdk.Stack) exhausts the tree-walk and falls back
+        // to globalThis.CURRENT_BLOCKS_STACK. The `as any` is test plumbing — a
+        // plain Stack isn't a ScopeParent, but it IS a valid Construct parent.
+        const plainStack = new cdk.Stack(app, 'PlainStack');
+        globalThis.CURRENT_BLOCKS_STACK = stack;
+        const orphan = new Scope('orphan', { parent: plainStack });
+        assert.strictEqual(orphan.executionRole, stack.executionRole, 'fallback resolves to the ambient stack role');
+    });
+});
 describe('assertCdkConditionActive', () => {
     test('BlocksStack.create() throws when --conditions=cdk is missing', async () => {
         const origNodeOptions = process.env.NODE_OPTIONS;

package/dist/cdk/index.d.ts

@@ -14,6 +14,8 @@ export declare class BlocksStack extends cdk.Stack implements BaseBlocksStack {
     readonly gateway: cdk.aws_apigateway.RestApi;
     readonly handler: cdk.aws_lambda_nodejs.NodejsFunction;
     readonly backendHandlerPath: string;
+    /** Shared IAM role assumed by all Blocks compute. Building Blocks grant to this role. */
+    readonly executionRole: cdk.aws_iam.IRole;
     private constructor();
     static create(scope: Construct, id: string, props: BlocksStackProps): Promise<BlocksStack>;
 }
@@ -24,6 +26,17 @@ export declare class Scope extends Construct {
     readonly bbVersion?: string;
     constructor(id: string, options?: ScopeOptions);
     get handler(): cdk.aws_lambda_nodejs.NodejsFunction;
+    /**
+     * The shared IAM role assumed by all Blocks compute. Building Blocks grant
+     * their permissions to this role instead of to an individual function's
+     * auto-role. CDK's `grant*()` / `addToPrincipalPolicy()` route those grants
+     * to the role's default (inline) policy — exactly where they landed on the
+     * auto-generated role before.
+     *
+     * Resolves the same way as {@link handler}: walk up to the owning
+     * BlocksStack/BlocksBackend, falling back to the ambient stack.
+     */
+    get executionRole(): cdk.aws_iam.IRole;
     get fullId(): string;
     protected buildUserAgentChain(): [string, string][];
     registerClientMiddleware(_packageSpecifier: string): void;

package/dist/cdk/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cdk/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,WAAW,IAAI,eAAe,EACnC,KAAK,WAAW,EAChB,KAAK,YAAY,EAElB,MAAM,oBAAoB,CAAC;AAK5B,OAAO,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,gCAAgC,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAE7F,qBAAa,WAAY,SAAQ,GAAG,CAAC,KAAM,YAAW,eAAe;IACnE,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,OAAO,EAAE,GAAG,CAAC,cAAc,CAAC,OAAO,CAAC;IACpD,SAAgB,OAAO,EAAE,GAAG,CAAC,iBAAiB,CAAC,cAAc,CAAC;IAC9D,SAAgB,kBAAkB,EAAE,MAAM,CAAC;IAE3C,OAAO;WAcM,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB;CA6B1E;AAED,qBAAa,KAAM,SAAQ,SAAS;IAClC,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,SAAgB,MAAM,EAAE,WAAW,CAAC;IAEpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;gBAEhB,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;IAO9C,IAAI,OAAO,yCAWV;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,SAAS,CAAC,mBAAmB,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE;IAKnD,wBAAwB,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI;IACzD,qBAAqB,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI;IACtD,0BAA0B,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IACrH,IAAI,gBAAgB,IAAI,SAAS,MAAM,EAAE,CAAe;IACxD,IAAI,cAAc,IAAI,SAAS,MAAM,EAAE,CAAe;CACvD"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/cdk/index.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AACnC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAGvC,OAAO,EACL,KAAK,gBAAgB,EACrB,KAAK,WAAW,IAAI,eAAe,EACnC,KAAK,WAAW,EAChB,KAAK,YAAY,EAElB,MAAM,oBAAoB,CAAC;AAK5B,OAAO,EAAE,aAAa,EAAE,KAAK,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AAC7E,OAAO,EAAE,oBAAoB,EAAE,MAAM,mBAAmB,CAAC;AACzD,OAAO,EAAE,gCAAgC,EAAE,MAAM,aAAa,CAAC;AAC/D,OAAO,EAAE,cAAc,EAAE,sBAAsB,EAAE,MAAM,sBAAsB,CAAC;AAC9E,OAAO,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAC9C,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,YAAY,EAAE,sBAAsB,EAAE,MAAM,cAAc,CAAC;AAE7F,qBAAa,WAAY,SAAQ,GAAG,CAAC,KAAM,YAAW,eAAe;IACnE,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,SAAgB,MAAM,EAAE,MAAM,CAAC;IAC/B,SAAgB,OAAO,EAAE,GAAG,CAAC,cAAc,CAAC,OAAO,CAAC;IACpD,SAAgB,OAAO,EAAE,GAAG,CAAC,iBAAiB,CAAC,cAAc,CAAC;IAC9D,SAAgB,kBAAkB,EAAE,MAAM,CAAC;IAC3C,yFAAyF;IACzF,SAAgB,aAAa,EAAE,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC;IAEjD,OAAO;WAeM,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,gBAAgB;CA6B1E;AAED,qBAAa,KAAM,SAAQ,SAAS;IAClC,SAAgB,EAAE,EAAE,MAAM,CAAC;IAC3B,SAAgB,MAAM,EAAE,WAAW,CAAC;IAEpC,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;gBAEhB,EAAE,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,YAAY;IAO9C,IAAI,OAAO,yCAWV;IAED;;;;;;;;;OASG;IACH,IAAI,aAAa,IAAI,GAAG,CAAC,OAAO,CAAC,KAAK,CAUrC;IAED,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,SAAS,CAAC,mBAAmB,IAAI,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE;IAKnD,wBAAwB,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI;IACzD,qBAAqB,CAAC,iBAAiB,EAAE,MAAM,GAAG,IAAI;IACtD,0BAA0B,CAAC,YAAY,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,EAAE,QAAQ,EAAE,CAAC,MAAM,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI;IACrH,IAAI,gBAAgB,IAAI,SAAS,MAAM,EAAE,CAAe;IACxD,IAAI,cAAc,IAAI,SAAS,MAAM,EAAE,CAAe;CACvD"}

package/dist/cdk/index.js

@@ -20,6 +20,8 @@ export class BlocksStack extends cdk.Stack {
     gateway;
     handler;
     backendHandlerPath;
+    /** Shared IAM role assumed by all Blocks compute. Building Blocks grant to this role. */
+    executionRole;
     constructor(scope, id, props) {
         super(scope, id, props);
         this.id = id;
@@ -30,6 +32,7 @@ export class BlocksStack extends cdk.Stack {
         this.handler = infra.handler;
         this.gateway = infra.gateway;
         this.apiUrl = infra.apiUrl;
+        this.executionRole = infra.executionRole;
     }
     static async create(scope, id, props) {
         assertCdkConditionActive();
@@ -80,6 +83,27 @@ export class Scope extends Construct {
         // Fallback to globalThis for backward compatibility
         return globalThis.CURRENT_BLOCKS_STACK.handler;
     }
+    /**
+     * The shared IAM role assumed by all Blocks compute. Building Blocks grant
+     * their permissions to this role instead of to an individual function's
+     * auto-role. CDK's `grant*()` / `addToPrincipalPolicy()` route those grants
+     * to the role's default (inline) policy — exactly where they landed on the
+     * auto-generated role before.
+     *
+     * Resolves the same way as {@link handler}: walk up to the owning
+     * BlocksStack/BlocksBackend, falling back to the ambient stack.
+     */
+    get executionRole() {
+        let current = this;
+        while (current.node.scope) {
+            current = current.node.scope;
+            if (current instanceof BlocksStack || current instanceof BlocksBackend) {
+                return current.executionRole;
+            }
+        }
+        // Fallback to globalThis for backward compatibility
+        return globalThis.CURRENT_BLOCKS_STACK.executionRole;
+    }
     get fullId() {
         return computeScopeFullId(this);
     }

package/dist/cors.d.ts

@@ -1,3 +1,12 @@
+/**
+ * `Access-Control-Max-Age` for preflight responses, in seconds.
+ *
+ * Chromium caps the preflight cache at 7200s and silently clamps anything
+ * higher, so a larger value buys nothing while widening the window in which a
+ * stale per-origin grant can be served. Shared by the Lambda handler and the
+ * local dev server so the two can't drift.
+ */
+export declare const CORS_MAX_AGE = "7200";
 /**
  * Parse a comma-separated CORS origin string into anchored RegExp patterns.
  *
@@ -24,6 +33,23 @@ export declare function getCorsPatterns(): RegExp[] | null;
  * @returns `true` if the origin matches at least one pattern, `false` otherwise
  */
 export declare function isOriginAllowed(origin: string): boolean;
+/**
+ * Build the CORS response headers for a request origin.
+ *
+ * Only reflects the origin when it matches the configured allowlist. When no
+ * allowlist is configured, or the origin is configured-but-not-allowed, no
+ * `Access-Control-Allow-Origin` / `Access-Control-Allow-Credentials` headers
+ * are emitted, so a disallowed origin is never reflected back.
+ *
+ * `Vary: Origin` is always emitted, including on the not-allowed path: the
+ * response headers depend on the request `Origin`, so any shared cache (CDN,
+ * forward proxy) must key on it or it can serve one origin's grant — or one
+ * origin's *absence* of a grant — to a different origin.
+ *
+ * @param origin - The `Origin` header value from the request (may be empty)
+ * @returns The CORS headers to merge into the response
+ */
+export declare function buildCorsHeaders(origin: string): Record<string, string>;
 /**
  * Build a 403 Forbidden response for cross-origin requests from disallowed origins.
  */
@@ -33,7 +59,7 @@ export declare function corsRejection(): {
     body: string;
 };
 /**
- * Reset the lazy CORS pattern cache. **For testing only.**
+ * Reset the lazy CORS pattern cache and the warned-origin set. **For testing only.**
  */
 export declare function _resetCorsPatterns(): void;
 //# sourceMappingURL=cors.d.ts.map

package/dist/cors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../src/cors.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAYvD;AAcD;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,EAAE,GAAG,IAAI,CAcjD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAIvD;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAMrG;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}
+{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../src/cors.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,SAAS,CAAC;AAEnC;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAYvD;AAcD;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,EAAE,GAAG,IAAI,CAcjD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAIvD;AAqBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASvE;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAMrG;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAGzC"}