@aws-blocks/core 0.3.0 → 0.5.0

package/README.md

@@ -76,6 +76,18 @@ The body is JSON-RPC 2.0:
 - `params` is a POSITIONAL array of the method's arguments. A named object also works (its values are used in order).
 - Errors come back as HTTP `200` with an `error` object in the body (per JSON-RPC), not as a non-2xx status.
 
+Error responses use these JSON-RPC codes:
+
+| Code | Meaning | When Blocks uses it |
+|------|---------|---------------------|
+| `-32700` | Parse error | Request body is not valid JSON. |
+| `-32600` | Invalid Request | Body is not a valid Blocks JSON-RPC request, such as missing `jsonrpc: "2.0"` or a `method` that is not `namespace.method`. |
+| `-32601` | Method not found | The requested namespace or method is not exported by the backend. |
+| `-32602` | Invalid params | Reserved for JSON-RPC parameter validation failures. Application-level validation should throw an `ApiError` with the appropriate HTTP status instead. |
+| `-32603` | Internal error | Reserved for generic JSON-RPC internal errors. Unhandled application errors currently use code `500`. |
+
+Errors thrown with `ApiError` use the positive HTTP status as the JSON-RPC `error.code` (for example, `401`, `404`, or `409`) and include `error.data.name` when an error name is available. The typed client converts JSON-RPC errors back into `ApiError`.
+
 Working example:
 
 ```bash
@@ -313,6 +325,19 @@ new Hosting(stack, 'Web', {
 
 The `framework` option selects the frontend type: `'spa' | 'static' | 'nextjs'`. When omitted, the framework is auto-detected by reading your app's OWN `package.json` (not `node_modules`): a `next` dependency → `nextjs`; otherwise `spa`; and `static` when there is no `package.json`. Set `framework: 'spa'` explicitly to override auto-detection — e.g. when a stray `next` dependency would otherwise trigger an unwanted Next.js/OpenNext build. Full reference lives in the source JSDoc.
 
+Old builds are retained for rollback and expired by an S3 lifecycle rule after `buildRetentionDays` (default **30**). The build currently being served is never expired regardless of deploy cadence — only superseded builds are cleaned up. Only builds superseded by a normal `Update` cutover are auto-tagged (and thus auto-expired): pre-existing/orphaned builds and aborted or rolled-back deploys are never tagged and need manual cleanup (e.g. an S3 inventory / Batch Operations sweep). Raise the window with `buildRetentionDays` (it must be ≥ `skewProtection.maxAge` in days):
+
+```typescript
+new Hosting(stack, 'Web', {
+  root: join(__dirname, '..'),
+  api: blocksStack,
+  buildRetentionDays: 90,
+});
+```
+
+Core's top-level `buildRetentionDays` maps to the L3 construct's `storage.buildRetentionDays`.
+
+
 ## Building Blocks
 
 Import Building Blocks from their specific packages (or from the `@aws-blocks/blocks` umbrella):

package/dist/api.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE;QACP,OAAO,EAAE,OAAO,CAAC;QACjB,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;QACxC,IAAI,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;QAC5B;;;;;;;;;;WAUG;QACH,GAAG,EAAE,GAAG,CAAC;QACT;;;;;WAKG;QACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B;;;;;;;;;WASG;QACH,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,CAAC;IACF,QAAQ,EAAE;QACR,OAAO,EAAE,OAAO,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,CAAC;KAC3B,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,KAAK,CAAC,CAAC;AAG1G,KAAK,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,IAAI;KAChE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,IAAI,KAAK,MAAM,CAAC,GACzD,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GACtC,KAAK;CACV,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,oBAAoB,eAAoC,CAAC;AAEtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAErD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,MAAM,WAAW,uBAAuB;IACtC,KAAK,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;CAChI;AAED,eAAO,MAAM,YAAY,EAAE,uBAKnB,CAAC"}
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAGA,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE;QACP,OAAO,EAAE,OAAO,CAAC;QACjB,IAAI,EAAE,cAAc,CAAC,UAAU,CAAC,GAAG,IAAI,CAAC;QACxC,IAAI,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;QACzB,IAAI,EAAE,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC;QAC5B;;;;;;;;;;WAUG;QACH,GAAG,EAAE,GAAG,CAAC;QACT;;;;;WAKG;QACH,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC/B;;;;;;;;;WASG;QACH,MAAM,CAAC,EAAE,WAAW,CAAC;KACtB,CAAC;IACF,QAAQ,EAAE;QACR,OAAO,EAAE,OAAO,CAAC;QACjB,MAAM,EAAE,MAAM,CAAC;QACf,IAAI,EAAE,CAAC,IAAI,EAAE,GAAG,KAAK,IAAI,CAAC;KAC3B,CAAC;CACH,CAAC;AAEF,MAAM,MAAM,UAAU,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,IAAI,CAAC,OAAO,EAAE,aAAa,KAAK,CAAC,CAAC;AAG1G,KAAK,QAAQ,CAAC,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,IAAI;KAChE,CAAC,IAAI,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC,GAAG,IAAI,EAAE,MAAM,IAAI,KAAK,MAAM,CAAC,GACzD,CAAC,GAAG,IAAI,EAAE,IAAI,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,GACtC,KAAK;CACV,CAAC;AAEF,yEAAyE;AACzE,eAAO,MAAM,oBAAoB,eAAoC,CAAC;AAEtE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAsCrD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA0FG;AACH,MAAM,WAAW,uBAAuB;IACtC,KAAK,CAAC,SAAS,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,GAAG,CAAC,EAAE,KAAK,EAAE,WAAW,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,UAAU,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,CAAC,CAAC,CAAC;CAChI;AAED,eAAO,MAAM,YAAY,EAAE,uBAQnB,CAAC"}

package/dist/api.js

@@ -2,9 +2,41 @@
 // SPDX-License-Identifier: Apache-2.0
 /** Marker symbol to identify ApiNamespace instances during discovery. */
 export const API_NAMESPACE_MARKER = Symbol.for('blocks:ApiNamespace');
+/**
+ * Record this namespace on its resolved compute so request routing can later
+ * map a namespace to the compute that hosts it.
+ *
+ * CDK-synth concern only: in the CDK bundle `scope.compute` resolves to the
+ * namespace's compute (the stack default today), and we append the name to its
+ * `namespaces` list. In the mock/runtime bundles — or a scopeless test — the
+ * property is absent, so `scope.compute` is `undefined` and this is a silent
+ * no-op. The public `ApiNamespace` signature is unchanged; this is a purely
+ * internal side effect.
+ *
+ * No `try/catch`: `BlocksBackend.create()` initializes the default compute
+ * before it imports the backend module that constructs any `ApiNamespace`, so
+ * the `compute` getter always resolves at this call site. If it ever threw
+ * here it would signal a genuine lifecycle violation (an `ApiNamespace` built
+ * before `create()` resolved), which should surface rather than be swallowed.
+ */
+function recordNamespaceOnCompute(scope, name) {
+    // An API created without a Scope stays unrecorded and routes to the
+    // default compute.
+    if (!scope || typeof scope !== 'object')
+        return;
+    const compute = scope.compute;
+    // Guard against duplicates so `namespaces` stays a set of names: a namespace
+    // could otherwise be recorded twice (e.g. a re-imported module during synth).
+    if (compute && Array.isArray(compute.namespaces) && !compute.namespaces.includes(name)) {
+        compute.namespaces.push(name);
+    }
+}
 export const ApiNamespace = class ApiNamespace {
     constructor(scope, name, handler) {
         handler[API_NAMESPACE_MARKER] = name;
+        // Record the namespace → compute association for per-compute routing.
+        // No-op outside CDK synth. Signature and returned handler are unchanged.
+        recordNamespaceOnCompute(scope, name);
         return handler;
     }
 };

package/dist/api.test.js

@@ -17,3 +17,25 @@ test('Different ApiNamespace names should not collide', () => {
     assert.strictEqual(api1[API_NAMESPACE_MARKER], 'api1');
     assert.strictEqual(api2[API_NAMESPACE_MARKER], 'api2');
 });
+// ApiNamespace records its name on the scope's resolved compute (CDK
+// synth), while staying a silent no-op where no compute is resolvable.
+test('ApiNamespace records its name on a resolvable compute', () => {
+    const compute = { namespaces: [] };
+    new ApiNamespace({ id: 'app', compute }, 'myapi', () => ({ ping: () => 'ok' }));
+    assert.deepStrictEqual(compute.namespaces, ['myapi']);
+});
+test('ApiNamespace is a no-op recorder when the scope has no compute', () => {
+    // The common Scope (mock/runtime) has no `compute`; recording must not throw
+    // and the handler is still tagged and returned unchanged.
+    const handler = new ApiNamespace(new Scope('no-compute'), 'plainapi', () => ({ x: () => 1 }));
+    assert.strictEqual(handler[API_NAMESPACE_MARKER], 'plainapi');
+});
+test('ApiNamespace records a namespace at most once per compute', () => {
+    // `namespaces` is a set of names: recording the same name twice (e.g. a
+    // re-imported module during synth) must not append a duplicate.
+    const compute = { namespaces: [] };
+    const scopeLike = { id: 'app', compute };
+    new ApiNamespace(scopeLike, 'dup', () => ({ ping: () => 'ok' }));
+    new ApiNamespace(scopeLike, 'dup', () => ({ ping: () => 'ok' }));
+    assert.deepStrictEqual(compute.namespaces, ['dup']);
+});

package/dist/bb-utils.d.ts

@@ -8,4 +8,5 @@ export { getMockDataDir } from './common/mock-data.js';
 export { API_NAMESPACE_MARKER } from './api.js';
 export { EventSourceMapping } from './lambda-handler.js';
 export { constantTimeEquals } from './common/crypto.js';
+export { sanitizeConfigKey } from './common/config.js';
 //# sourceMappingURL=bb-utils.d.ts.map

package/dist/bb-utils.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"bb-utils.d.ts","sourceRoot":"","sources":["../src/bb-utils.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC"}
+{"version":3,"file":"bb-utils.d.ts","sourceRoot":"","sources":["../src/bb-utils.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AACH,OAAO,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AACvD,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,qBAAqB,CAAC;AACzD,OAAO,EAAE,kBAAkB,EAAE,MAAM,oBAAoB,CAAC;AAGxD,OAAO,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC"}

package/dist/bb-utils.js

@@ -10,3 +10,6 @@ export { getMockDataDir } from './common/mock-data.js';
 export { API_NAMESPACE_MARKER } from './api.js';
 export { EventSourceMapping } from './lambda-handler.js';
 export { constantTimeEquals } from './common/crypto.js';
+// Defined in the config module (it owns the config-key contract), re-exported
+// here so BB authors get it alongside the other BB utilities.
+export { sanitizeConfigKey } from './common/config.js';

package/dist/cdk/apigateway-account.d.ts

@@ -0,0 +1,33 @@
+import type * as cdk from 'aws-cdk-lib';
+import { CfnAccount } from 'aws-cdk-lib/aws-apigateway';
+/**
+ * Ensure the account-level API Gateway CloudWatch Logs role exists on `stack`,
+ * creating it at most once per stack.
+ *
+ * API Gateway access logging — for both REST (v1) and WebSocket (v2) stages —
+ * requires an `AWS::ApiGateway::Account` whose `cloudWatchRoleArn` points at a
+ * role trusted by `apigateway.amazonaws.com` and carrying
+ * `AmazonAPIGatewayPushToCloudWatchLogs`. Nothing else in a Blocks stack
+ * provisions it, so a clean-account first deploy of any access-logging stage
+ * otherwise fails at CreateStage with "CloudWatch Logs role ARN must be set in
+ * account settings to enable logging".
+ *
+ * Callers should add their stage's dependency on the returned account so the
+ * account setting is applied before the stage is created.
+ *
+ * ⚠️ Single-Blocks-stack-per-region assumption. `AWS::ApiGateway::Account` is an
+ * account/region-level singleton (one effective `cloudWatchRoleArn` per region),
+ * but this provisions one per Blocks stack. If two Blocks stacks in the same
+ * account+region both enable access logging:
+ *   - on deploy, the later stack's role wins (overwrites the account setting); and
+ *   - on teardown of that later stack, its role is deleted and the account
+ *     setting is left pointing at a now-deleted role — silently breaking access
+ *     logging (or blocking `CreateStage`) for the surviving stack until it
+ *     redeploys.
+ * Enabling `accessLogging` is therefore safe for one Blocks stack per region.
+ * Multi-stack support (a shared/imported account) is deferred; if you run
+ * multiple Blocks stacks per region, manage the account role out-of-band and
+ * leave `accessLogging` to a single owner.
+ */
+export declare function ensureApiGatewayAccount(stack: cdk.Stack): CfnAccount;
+//# sourceMappingURL=apigateway-account.d.ts.map

package/dist/cdk/apigateway-account.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apigateway-account.d.ts","sourceRoot":"","sources":["../../src/cdk/apigateway-account.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,KAAK,GAAG,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,UAAU,EAAE,MAAM,4BAA4B,CAAC;AAaxD;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,GAAG,CAAC,KAAK,GAAG,UAAU,CAmBpE"}

package/dist/cdk/apigateway-account.js

@@ -0,0 +1,60 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { CfnAccount } from 'aws-cdk-lib/aws-apigateway';
+import { ManagedPolicy, Role, ServicePrincipal } from 'aws-cdk-lib/aws-iam';
+/**
+ * Global registry key for the per-stack API Gateway CloudWatch Logs account
+ * resource. Deliberately a `Symbol.for(...)` string key so the SAME symbol is
+ * shared across packages (core, hosting) — each package can carry its own copy
+ * of {@link ensureApiGatewayAccount} yet still find and reuse the one account a
+ * sibling package already created on the stack, instead of emitting a second
+ * `AWS::ApiGateway::Account` (which is account/region-level and would clash).
+ */
+const ACCOUNT_KEY = Symbol.for('BLOCKS_APIGATEWAY_ACCOUNT');
+/**
+ * Ensure the account-level API Gateway CloudWatch Logs role exists on `stack`,
+ * creating it at most once per stack.
+ *
+ * API Gateway access logging — for both REST (v1) and WebSocket (v2) stages —
+ * requires an `AWS::ApiGateway::Account` whose `cloudWatchRoleArn` points at a
+ * role trusted by `apigateway.amazonaws.com` and carrying
+ * `AmazonAPIGatewayPushToCloudWatchLogs`. Nothing else in a Blocks stack
+ * provisions it, so a clean-account first deploy of any access-logging stage
+ * otherwise fails at CreateStage with "CloudWatch Logs role ARN must be set in
+ * account settings to enable logging".
+ *
+ * Callers should add their stage's dependency on the returned account so the
+ * account setting is applied before the stage is created.
+ *
+ * ⚠️ Single-Blocks-stack-per-region assumption. `AWS::ApiGateway::Account` is an
+ * account/region-level singleton (one effective `cloudWatchRoleArn` per region),
+ * but this provisions one per Blocks stack. If two Blocks stacks in the same
+ * account+region both enable access logging:
+ *   - on deploy, the later stack's role wins (overwrites the account setting); and
+ *   - on teardown of that later stack, its role is deleted and the account
+ *     setting is left pointing at a now-deleted role — silently breaking access
+ *     logging (or blocking `CreateStage`) for the surviving stack until it
+ *     redeploys.
+ * Enabling `accessLogging` is therefore safe for one Blocks stack per region.
+ * Multi-stack support (a shared/imported account) is deferred; if you run
+ * multiple Blocks stacks per region, manage the account role out-of-band and
+ * leave `accessLogging` to a single owner.
+ */
+export function ensureApiGatewayAccount(stack) {
+    const existing = stack[ACCOUNT_KEY];
+    if (existing)
+        return existing;
+    const role = new Role(stack, 'BlocksApiGatewayCloudWatchRole', {
+        assumedBy: new ServicePrincipal('apigateway.amazonaws.com'),
+        managedPolicies: [
+            ManagedPolicy.fromAwsManagedPolicyName('service-role/AmazonAPIGatewayPushToCloudWatchLogs'),
+        ],
+    });
+    // `cloudWatchRoleArn: role.roleArn` already gives CDK an implicit dependency
+    // on the role, so no explicit node.addDependency is needed.
+    const account = new CfnAccount(stack, 'BlocksApiGatewayAccount', {
+        cloudWatchRoleArn: role.roleArn,
+    });
+    stack[ACCOUNT_KEY] = account;
+    return account;
+}

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

@@ -70,6 +70,12 @@ export declare function setupBlocksInfra(scope: Construct, props: BlocksBackendP
  */
 export declare class BlocksBackend extends Construct {
     readonly backendHandlerPath: string;
+    /**
+     * Path to the app's backend module (`props.backendCDKPath`). Exposed so Building Blocks that
+     * co-bundle the backend at synth (e.g. the Agent BB's AgentCore Runtime) can discover it via
+     * `globalThis.CURRENT_BLOCKS_STACK.backendModulePath`.
+     */
+    readonly backendModulePath: string;
     /** Shared IAM role assumed by all Blocks compute. Building Blocks grant to this role. */
     readonly executionRole: iam.IRole;
     /** Infrastructure defaults for Building Blocks created under this backend. */
@@ -82,6 +88,10 @@ export declare class BlocksBackend extends Construct {
     get gateway(): apigateway.RestApi;
     /** The default compute's RPC endpoint URL. To be removed once consumers move to the multi-compute model. */
     get apiUrl(): string;
+    /** The default compute's handler CloudWatch log group. Its retention comes from
+     * the compute's `logRetention` (falling back to `defaults.logRetention`); the
+     * `bb-logger` CDK construct is a no-op and no longer touches it. */
+    get handlerLogGroup(): cdk.aws_logs.ILogGroup;
     private requireDefaultCompute;
     /**
      * The fullId used by child Scopes to compute their env var names,
@@ -103,6 +113,7 @@ export declare class BlocksBackend extends Construct {
      * fallback to the (token-free) construct id should no resolvable name exist.
      */
     get fullId(): string;
+    private _vpcOptions?;
     private constructor();
     static create(scope: Construct, id: string, props: CoreBlocksBackendProps): Promise<BlocksBackend>;
 }

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;AACnC,OAAO,KAAK,KAAK,UAAU,MAAM,4BAA4B,CAAC;AAC9D,OAAO,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAE3C,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAIvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAE3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,KAAK,EAAE,qBAAqB,EAAuB,MAAM,sCAAsC,CAAC;AAEvG;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAkB/C;AAED;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,QAAU,CAAC;AAEtD,MAAM,WAAW,kBAAkB;IACjC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IAChE,8EAA8E;IAC9E,qBAAqB,EAAE,qBAAqB,CAAC;CAC9C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,kBAAkB,EAAE,EAAE,CAAC,EAAE,MAAM;;EAwFxF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAc,SAAQ,SAAS;IAC1C,SAAgB,kBAAkB,EAAE,MAAM,CAAC;IAC3C,yFAAyF;IACzF,SAAgB,aAAa,EAAE,GAAG,CAAC,KAAK,CAAC;IACzC,8EAA8E;IAC9E,SAAgB,QAAQ,EAAE,cAAc,CAAC;IACzC,iGAAiG;IACjG,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B,2GAA2G;IAC3G,IAAI,OAAO,IAAI,GAAG,CAAC,iBAAiB,CAAC,cAAc,CAElD;IACD,gHAAgH;IAChH,IAAI,OAAO,IAAI,UAAU,CAAC,OAAO,CAEhC;IACD,4GAA4G;IAC5G,IAAI,MAAM,IAAI,MAAM,CAEnB;IAED,OAAO,CAAC,qBAAqB;IAO7B;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,MAAM,IAAI,MAAM,CAUnB;IAED,OAAO;WAmBM,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,sBAAsB;CA6BhF"}
+{"version":3,"file":"blocks-backend.d.ts","sourceRoot":"","sources":["../../src/cdk/blocks-backend.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AACnC,OAAO,KAAK,KAAK,UAAU,MAAM,4BAA4B,CAAC;AAC9D,OAAO,KAAK,GAAG,MAAM,qBAAqB,CAAC;AAE3C,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAC3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,OAAO,KAAK,EAAE,qBAAqB,EAAuB,MAAM,sCAAsC,CAAC;AAQvG;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAkB/C;AAED;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,QAAU,CAAC;AAEtD,MAAM,WAAW,kBAAkB;IAClC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,EAAE,cAAc,CAAC;CACzB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,sBAAuB,SAAQ,kBAAkB;IACjE,8EAA8E;IAC9E,qBAAqB,EAAE,qBAAqB,CAAC;CAC7C;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,kBAAkB,EAAE,EAAE,CAAC,EAAE,MAAM;;EAqGxF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,aAAc,SAAQ,SAAS;IAC3C,SAAgB,kBAAkB,EAAE,MAAM,CAAC;IAC3C;;;;OAIG;IACH,SAAgB,iBAAiB,EAAE,MAAM,CAAC;IAC1C,yFAAyF;IACzF,SAAgB,aAAa,EAAE,GAAG,CAAC,KAAK,CAAC;IACzC,8EAA8E;IAC9E,SAAgB,QAAQ,EAAE,cAAc,CAAC;IACzC,iGAAiG;IACjG,eAAe,CAAC,EAAE,OAAO,CAAC;IAE1B,2GAA2G;IAC3G,IAAI,OAAO,IAAI,GAAG,CAAC,iBAAiB,CAAC,cAAc,CAElD;IACD,gHAAgH;IAChH,IAAI,OAAO,IAAI,UAAU,CAAC,OAAO,CAEhC;IACD,4GAA4G;IAC5G,IAAI,MAAM,IAAI,MAAM,CAEnB;IACD;;wEAEoE;IACpE,IAAI,eAAe,IAAI,GAAG,CAAC,QAAQ,CAAC,SAAS,CAE5C;IAED,OAAO,CAAC,qBAAqB;IAS7B;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,MAAM,IAAI,MAAM,CAUnB;IAED,OAAO,CAAC,WAAW,CAAC,CAAmB;IAEvC,OAAO;WA6BM,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,sBAAsB;CAyD/E"}

package/dist/cdk/blocks-backend.js

@@ -1,13 +1,17 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
+import { pathToFileURL } from 'node:url';
 import * as cdk from 'aws-cdk-lib';
 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';
-import { addBlocksStackMetadata } from './stack-metadata.js';
-import { finalizeConfigRegistry, registerConfig } from './config-registry.js';
 import { registerBuiltinRoutes } from '../builtin-routes.js';
+import { getComputes } from './compute/compute-registry.js';
+import { finalizeConfigRegistry, registerConfig } from './config-registry.js';
+import { finalizeDashboards } from './dashboard-registry.js';
+import { finalizeTracing } from './tracer-registry.js';
+import { addBlocksStackMetadata } from './stack-metadata.js';
+import { anyRequirementNeedsVpc, finalizeVpc, getOrCreateVpc, initializeVpc } from './vpc.js';
 /**
  * Validate that the Node.js process was started with `--conditions=cdk`.
  *
@@ -19,7 +23,7 @@ import { registerBuiltinRoutes } from '../builtin-routes.js';
 export function assertCdkConditionActive() {
     const nodeOptions = process.env.NODE_OPTIONS ?? '';
     const execArgv = process.execArgv ?? [];
-    const hasCdkCondition = execArgv.some(arg => arg === '--conditions=cdk') ||
+    const hasCdkCondition = execArgv.some((arg) => arg === '--conditions=cdk') ||
         execArgv.some((arg, i) => (arg === '--conditions' || arg === '-C') && execArgv[i + 1] === 'cdk') ||
         nodeOptions.includes('--conditions=cdk') ||
         /(?:--conditions|-C)\s+cdk/.test(nodeOptions);
@@ -64,19 +68,24 @@ export function setupBlocksInfra(scope, props, id) {
     // so permissions would quietly vanish. If a bring-your-own-role option is ever
     // added, it must resolve to a mutable role (`{ mutable: true }`).
     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.
+        // CompositePrincipal (rather than a bare ServicePrincipal) so a Building Block
+        // whose compute runs AS this shared role can add its own trust principal here
+        // (e.g. the Agent BB adds bedrock-agentcore in its CDK construct) — core stays
+        // agnostic and only Lambda is trusted by default.
         assumedBy: new iam.CompositePrincipal(new iam.ServicePrincipal('lambda.amazonaws.com')),
         managedPolicies: [
             iam.ManagedPolicy.fromAwsManagedPolicyName('service-role/AWSLambdaBasicExecutionRole'),
+            // When Lambda is placed in a VPC it needs ENI management permissions
+            ...(props.defaults.vpc
+                ? [iam.ManagedPolicy.fromAwsManagedPolicyName('service-role/AWSLambdaVPCAccessExecutionRole')]
+                : []),
         ],
     });
     // ── Resource Groups ───────────────────────────────────────────────────
     let rootStack = cdk.Stack.of(scope);
     while (rootStack.nestedStackParent)
         rootStack = rootStack.nestedStackParent;
-    const groupPrefix = (id && id !== rootStack.stackName) ? `${rootStack.stackName}-${id}` : rootStack.stackName;
+    const groupPrefix = id && id !== rootStack.stackName ? `${rootStack.stackName}-${id}` : rootStack.stackName;
     new CfnGroup(scope, 'StackResources', {
         name: `${groupPrefix}-resources`,
         resourceQuery: {
@@ -109,12 +118,20 @@ export function setupBlocksInfra(scope, props, id) {
     // ── Console redirect routes ───────────────────────────────────────────
     const region = cdk.Fn.ref('AWS::Region');
     const resourcesUrl = cdk.Fn.join('', [
-        'https://', region, '.console.aws.amazon.com/resource-groups/group/',
-        `${groupPrefix}-resources`, '?region=', region,
+        'https://',
+        region,
+        '.console.aws.amazon.com/resource-groups/group/',
+        `${groupPrefix}-resources`,
+        '?region=',
+        region,
     ]);
     const settingsUrl = cdk.Fn.join('', [
-        'https://', region, '.console.aws.amazon.com/resource-groups/group/',
-        `${groupPrefix}-settings`, '?region=', region,
+        'https://',
+        region,
+        '.console.aws.amazon.com/resource-groups/group/',
+        `${groupPrefix}-settings`,
+        '?region=',
+        region,
     ]);
     registerConfig(scope, 'BB_RESOURCES_GROUP_URL', resourcesUrl);
     registerConfig(scope, 'BB_SETTINGS_GROUP_URL', settingsUrl);
@@ -140,6 +157,12 @@ export function setupBlocksInfra(scope, props, id) {
  */
 export class BlocksBackend extends Construct {
     backendHandlerPath;
+    /**
+     * Path to the app's backend module (`props.backendCDKPath`). Exposed so Building Blocks that
+     * co-bundle the backend at synth (e.g. the Agent BB's AgentCore Runtime) can discover it via
+     * `globalThis.CURRENT_BLOCKS_STACK.backendModulePath`.
+     */
+    backendModulePath;
     /** Shared IAM role assumed by all Blocks compute. Building Blocks grant to this role. */
     executionRole;
     /** Infrastructure defaults for Building Blocks created under this backend. */
@@ -158,6 +181,12 @@ export class BlocksBackend extends Construct {
     get apiUrl() {
         return this.requireDefaultCompute().apiUrl;
     }
+    /** The default compute's handler CloudWatch log group. Its retention comes from
+     * the compute's `logRetention` (falling back to `defaults.logRetention`); the
+     * `bb-logger` CDK construct is a no-op and no longer touches it. */
+    get handlerLogGroup() {
+        return this.requireDefaultCompute().logGroup;
+    }
     requireDefaultCompute() {
         if (!this._defaultCompute) {
             throw new Error('Blocks backend not fully initialized — access .handler/.gateway/.apiUrl after BlocksBackend.create() resolves.');
@@ -194,15 +223,25 @@ export class BlocksBackend extends Construct {
         }
         return `${stackName}-${this.node.id}`;
     }
+    _vpcOptions;
     constructor(scope, id, props) {
         super(scope, id);
         this.backendHandlerPath = props.backendHandlerPath;
+        this.backendModulePath = props.backendCDKPath;
+        this._vpcOptions = props.defaults.vpc;
         // Expose self to Building Blocks at CDK time
         globalThis.CURRENT_BLOCKS_STACK = this;
         // Store defaults on the backend (not the stack) so several BlocksBackends
         // in one stack each keep their own posture; Building Blocks resolve them by
         // walking up to their owning backend (see Scope.defaults).
         this.defaults = props.defaults;
+        // Initialize VPC context before the default compute is created and before
+        // BBs are constructed, so both can discover it: the default compute
+        // (LambdaCompute) reads it via getVpcContext(this) to place its function in
+        // the VPC, and BBs (e.g. bb-data) read it to co-locate their resources.
+        if (this._vpcOptions) {
+            initializeVpc(this, this._vpcOptions);
+        }
         const infra = setupBlocksInfra(this, props, id);
         this.executionRole = infra.executionRole;
         // The default compute (and thus handler/gateway) is created in create(),
@@ -233,7 +272,27 @@ export class BlocksBackend extends Construct {
         }
         addBlocksStackMetadata(cdk.Stack.of(backend));
         // Finalize BB config → S3 (after all BBs have registered their config)
-        finalizeConfigRegistry(backend, backend.handler);
+        finalizeConfigRegistry(backend, backend.executionRole, getComputes(backend));
+        // Tracing is presence-gated: if the app contains a Tracer, enable X-Ray on
+        // every compute. Runs before the dashboard finalize.
+        finalizeTracing(backend, backend.executionRole);
+        // Build any deferred Dashboards now that every compute's observability
+        // state is settled — so the dashboard is order-independent.
+        finalizeDashboards(backend);
+        // Finalize VPC. Derived resource: use the customer's if provided, else
+        // lazily create one only if a Building Block requires it.
+        if (backend._vpcOptions) {
+            finalizeVpc(backend, backend._vpcOptions);
+        }
+        else if (anyRequirementNeedsVpc(backend)) {
+            const derived = getOrCreateVpc(backend);
+            const options = { network: derived };
+            initializeVpc(backend, options);
+            finalizeVpc(backend, options);
+            cdk.Annotations.of(backend).addInfoV2('blocks:vpc:derived', 'A Building Block required a VPC and none was provided, so Blocks created one ' +
+                '(with a NAT gateway, which has an ongoing cost). Pass `defaults.vpc: { network }` to ' +
+                'bring your own. See packages/blocks/VPC.md.');
+        }
         return backend;
     }
 }

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

@@ -14,6 +14,7 @@ import { BlocksBackend } from './blocks-backend.js';
 import { BlocksPresets } from './blocks-defaults.js';
 import { Compute } from './compute/compute.js';
 import { Scope } from './index.js';
+import { getVpcContext } from './vpc.js';
 // A real app gets its default compute from @aws-blocks/bb-lambda-compute (via
 // @aws-blocks/blocks), which core's own tests can't depend on. Use an
 // equivalent inline stub: a Compute that owns a NodejsFunction + API Gateway,
@@ -25,15 +26,32 @@ class StubLambdaCompute extends Compute {
     fn;
     apiGateway;
     apiUrl;
+    logGroup;
     constructor(scope, id) {
         super(id, { parent: scope });
+        this.logGroup = new cdk.aws_logs.LogGroup(this, 'HandlerLogGroup', {
+            removalPolicy: cdk.RemovalPolicy.DESTROY,
+        });
+        // Discover the shared VPC context from the owning stack/backend, mirroring
+        // LambdaCompute — so the core-side VPC placement plumbing (initializeVpc →
+        // getVpcContext) is exercised by these tests without depending on
+        // @aws-blocks/bb-lambda-compute.
+        const vpcContext = getVpcContext(this);
         this.fn = new lambda.NodejsFunction(this, 'Handler', {
             entry: this.backendHandlerPath,
             runtime: cdk.aws_lambda.Runtime.NODEJS_22_X,
             handler: 'handler',
             role: this.executionRole,
+            logGroup: this.logGroup,
             environment: { BLOCKS_STACK_NAME: this.backendStackName },
             bundling: { minify: true, esbuildArgs: { '--conditions': 'aws-runtime' } },
+            ...(vpcContext
+                ? {
+                    vpc: vpcContext.vpc,
+                    vpcSubnets: vpcContext.computeSubnets,
+                    securityGroups: [vpcContext.computeSecurityGroup],
+                }
+                : {}),
         });
         this.apiGateway = new apigateway.RestApi(this, 'API', { restApiName: 'Blocks API' });
         this.apiGateway.root.addProxy({
@@ -45,6 +63,16 @@ class StubLambdaCompute extends Compute {
     setEnv(key, value) {
         this.fn.addEnvironment(key, value);
     }
+    applyTracing() { }
+    healthWidgets(_region) {
+        return [];
+    }
+    loggingWidgets(_region) {
+        return [];
+    }
+    tracingWidgets(_region) {
+        return [];
+    }
 }
 const stubComputeFactory = (root) => new StubLambdaCompute(root, 'DefaultCompute');
 // Simulate the CDK condition being active (tests import CDK files directly)
@@ -60,7 +88,12 @@ const EXECUTION_ROLE_MARKER_ACTION = 'blocks-test:MarkerAction';
 const importMetaHandlerPath = join(__dirname, '__fixtures__', 'import-meta-handler.js');
 // Wraps BlocksBackend.create, injecting the stub default-compute factory the way
 // @aws-blocks/blocks injects LambdaCompute — so tests don't repeat it 15 times.
-const makeBackend = (scope, id, backendCDKPath) => BlocksBackend.create(scope, id, { backendHandlerPath: handlerPath, backendCDKPath, defaults: BlocksPresets.production, defaultComputeFactory: stubComputeFactory });
+const makeBackend = (scope, id, backendCDKPath) => BlocksBackend.create(scope, id, {
+    backendHandlerPath: handlerPath,
+    backendCDKPath,
+    defaults: BlocksPresets.production,
+    defaultComputeFactory: stubComputeFactory,
+});
 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();
@@ -123,11 +156,23 @@ describe('shared execution role', () => {
             Principal: { Service: 'lambda.amazonaws.com' },
         });
         assert.ok(JSON.stringify(blocksRole.Properties.ManagedPolicyArns ?? []).includes('AWSLambdaBasicExecutionRole'), 'BlocksRole should attach AWSLambdaBasicExecutionRole');
+        // Core is BB-agnostic: with no Building Block that runs AS the shared role, the trust policy
+        // must NOT allow any compute principal beyond Lambda (e.g. bedrock-agentcore is added by the
+        // Agent BB's own construct, not here — see packages/bb-agent).
+        assert.ok(!JSON.stringify(blocksRole.Properties.AssumeRolePolicyDocument).includes('bedrock-agentcore'), 'core must not trust bedrock-agentcore by default (no agent → no AgentCore trust)');
         // The Blocks handler references the shared role, not an auto-generated one.
         template.hasResourceProperties('AWS::Lambda::Function', {
             Role: { 'Fn::GetAtt': [blocksRoleId, 'Arn'] },
         });
     });
+    test('exposes backendModulePath (props.backendCDKPath) for co-bundling BBs', async () => {
+        const app = new cdk.App();
+        const parent = new cdk.Stack(app, 'BackendPathStack');
+        const backend = await makeBackend(parent, 'Blocks', sideEffectBackendPath);
+        // Building Blocks that co-bundle the app backend at synth time (e.g. the Agent BB's AgentCore
+        // Runtime) discover it via globalThis.CURRENT_BLOCKS_STACK.backendModulePath.
+        assert.strictEqual(backend.backendModulePath, sideEffectBackendPath);
+    });
     test('a nested block resolves executionRole via the construct-tree walk', async () => {
         const app = new cdk.App();
         const parent = new cdk.Stack(app, 'RoleResolveStack');
@@ -277,3 +322,45 @@ describe('infrastructure defaults (backend-anchored)', () => {
         assert.strictEqual(inner.defaults, BlocksPresets.sandbox);
     });
 });
+describe('VPC placement', () => {
+    test('places the handler Lambda in the VPC with a security group when vpc is provided', async () => {
+        const app = new cdk.App();
+        const parent = new cdk.Stack(app, 'VpcParent', {
+            env: { account: '123456789012', region: 'us-east-1' },
+        });
+        const vpc = new cdk.aws_ec2.Vpc(parent, 'AppVpc', { maxAzs: 2, natGateways: 1 });
+        await BlocksBackend.create(parent, 'Blocks', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: sideEffectBackendPath,
+            defaults: { ...BlocksPresets.production, vpc: { network: vpc } },
+            defaultComputeFactory: stubComputeFactory,
+        });
+        const template = Template.fromStack(parent);
+        // The handler Lambda is VPC-attached: it has a VpcConfig with subnets + SGs.
+        template.hasResourceProperties('AWS::Lambda::Function', {
+            VpcConfig: Match.objectLike({
+                SubnetIds: Match.anyValue(),
+                SecurityGroupIds: Match.anyValue(),
+            }),
+        });
+        // The VPC-access managed policy is attached to the execution role.
+        const policies = template.findResources('AWS::IAM::Role');
+        const hasVpcManagedPolicy = Object.values(policies).some((role) => JSON.stringify(role.Properties?.ManagedPolicyArns ?? []).includes('AWSLambdaVPCAccessExecutionRole'));
+        assert.ok(hasVpcManagedPolicy, 'execution role should have the VPC access managed policy');
+    });
+    test('no VpcConfig on the handler when vpc is omitted', async () => {
+        const app = new cdk.App();
+        const parent = new cdk.Stack(app, 'NoVpcParent');
+        await BlocksBackend.create(parent, 'Blocks', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: sideEffectBackendPath,
+            defaults: BlocksPresets.production,
+            defaultComputeFactory: stubComputeFactory,
+        });
+        const template = Template.fromStack(parent);
+        const fns = template.findResources('AWS::Lambda::Function');
+        for (const fn of Object.values(fns)) {
+            assert.strictEqual(fn.Properties?.VpcConfig, undefined, 'handler must not have VpcConfig when no VPC is configured');
+        }
+    });
+});