@aws-blocks/core 0.1.17 → 0.2.0

package/dist/cdk/__fixtures__/import-meta-handler.d.ts

@@ -0,0 +1,6 @@
+export declare const moduleDir: string;
+export declare const handler: () => Promise<{
+    statusCode: number;
+    body: string;
+}>;
+//# sourceMappingURL=import-meta-handler.d.ts.map

package/dist/cdk/__fixtures__/import-meta-handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"import-meta-handler.d.ts","sourceRoot":"","sources":["../../../src/cdk/__fixtures__/import-meta-handler.ts"],"names":[],"mappings":"AAYA,eAAO,MAAM,SAAS,QAAiC,CAAC;AAGxD,eAAO,MAAM,OAAO;;;EAAyE,CAAC"}

package/dist/cdk/__fixtures__/import-meta-handler.js

@@ -0,0 +1,13 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+// Repro fixture for the "handler bundles to CJS but uses import.meta.url" bug.
+//
+// The handler is bundled to CJS by NodejsFunction. In a CJS bundle `import.meta`
+// is empty, so this top-level `fileURLToPath(import.meta.url)` would become
+// `fileURLToPath(undefined)` and throw at Lambda load. blocksNodejsBundling shims
+// `import.meta.url` to a CommonJS equivalent, so the bundle loads and resolves a
+// real path instead of crashing — see bundling.test.ts.
+import { fileURLToPath } from 'node:url';
+export const moduleDir = fileURLToPath(import.meta.url);
+// Reference moduleDir so esbuild can't tree-shake the import.meta.url usage away.
+export const handler = async () => ({ statusCode: 200, body: JSON.stringify({ moduleDir }) });

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

@@ -1,6 +1,8 @@
 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';
+import type { BlocksDefaults } from './blocks-defaults.js';
 /**
  * Validate that the Node.js process was started with `--conditions=cdk`.
  *
@@ -13,12 +15,21 @@ export declare function assertCdkConditionActive(): void;
 export interface BlocksBackendProps {
     backendHandlerPath: string;
     backendCDKPath: string;
+    /**
+     * Stack-wide infrastructure defaults applied to every Building Block (removal
+     * policy, deletion protection, …). See {@link BlocksDefaults}. Start from
+     * `BlocksPresets.sandbox` or `BlocksPresets.production` and override
+     * individual fields as needed. A per-block option always wins over the
+     * corresponding stack default.
+     */
+    defaults: BlocksDefaults;
 }
 /** Shared infra setup — creates Lambda + API Gateway on the given scope. */
 export declare function setupBlocksInfra(scope: Construct, props: BlocksBackendProps, id?: string): {
     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 +53,10 @@ 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;
+    /** Infrastructure defaults for Building Blocks created under this backend. */
+    readonly defaults: BlocksDefaults;
     /**
      * 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;AAMvC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAI3D;;;;;;;GAOG;AACH,wBAAgB,wBAAwB,IAAI,IAAI,CAkB/C;AAED,MAAM,WAAW,kBAAkB;IACjC,kBAAkB,EAAE,MAAM,CAAC;IAC3B,cAAc,EAAE,MAAM,CAAC;IACvB;;;;;;OAMG;IACH,QAAQ,EAAE,cAAc,CAAC;CAC1B;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,kBAAkB,EAAE,EAAE,CAAC,EAAE,MAAM;;;;;EAyIxF;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;IACzC,8EAA8E;IAC9E,SAAgB,QAAQ,EAAE,cAAc,CAAC;IAEzC;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,MAAM,IAAI,MAAM,CAUnB;IAED,OAAO;WAyBM,MAAM,CAAC,KAAK,EAAE,SAAS,EAAE,EAAE,EAAE,MAAM,EAAE,KAAK,EAAE,kBAAkB;CAsB5E"}

package/dist/cdk/blocks-backend.js

@@ -3,10 +3,12 @@
 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';
 import { DEFAULT_NODE_RUNTIME } from './node-version.js';
+import { blocksNodejsBundling } from './bundling.js';
 import { addBlocksStackMetadata } from './stack-metadata.js';
 import { finalizeConfigRegistry, registerConfig } from './config-registry.js';
 import { BLOCKS_NAMESPACE, BLOCKS_RPC_PREFIX } from '../constants.js';
@@ -35,10 +37,34 @@ export function assertCdkConditionActive() {
 }
 /** Shared infra setup — creates Lambda + API Gateway on the given scope. */
 export function setupBlocksInfra(scope, props, id) {
+    // Fail fast with an actionable message at the create() call site if `defaults`
+    // is missing (e.g. a plain-JS caller, `as any`, or a dynamically-built props
+    // object) — otherwise the first Building Block to read `scope.defaults` throws
+    // a cryptic `Cannot read properties of undefined (reading 'removalPolicy')`.
+    if (!props.defaults) {
+        throw new Error('BlocksStack/BlocksBackend requires a `defaults` field. Pass a posture from ' +
+            '`@aws-blocks/core/cdk` — typically `defaults: sandboxMode ? BlocksPresets.sandbox : BlocksPresets.production`.');
+    }
+    // ── 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. AWSLambdaBasicExecutionRole is attached so the handler retains
+    // CloudWatch Logs permissions.
+    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: {
@@ -54,10 +80,13 @@ export function setupBlocksInfra(scope, props, id) {
              */
             BLOCKS_STACK_NAME: id ?? cdk.Stack.of(scope).stackName,
         },
-        bundling: {
+        // blocksNodejsBundling shims import.meta.* to CommonJS equivalents so a
+        // CJS-bundled `fileURLToPath(import.meta.url)` resolves instead of throwing at
+        // Lambda load. See ./bundling.ts.
+        bundling: blocksNodejsBundling({
             minify: true,
             esbuildArgs: { '--conditions': 'aws-runtime' },
-        },
+        }),
     });
     // In sandbox mode, allow localhost origins so the local dev frontend can
     // reach the deployed Lambda API via CORS.
@@ -126,7 +155,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 +179,10 @@ export class BlocksBackend extends Construct {
     gateway;
     handler;
     backendHandlerPath;
+    /** Shared IAM role assumed by all Blocks compute. Building Blocks grant to this role. */
+    executionRole;
+    /** Infrastructure defaults for Building Blocks created under this backend. */
+    defaults;
     /**
      * The fullId used by child Scopes to compute their env var names,
      * construct IDs, and physical resource names (e.g., DynamoDB table names).
@@ -185,10 +218,15 @@ export class BlocksBackend extends Construct {
         this.backendHandlerPath = props.backendHandlerPath;
         // 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;
         const infra = setupBlocksInfra(this, props, id);
         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,11 @@ 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 { BlocksPresets } from './blocks-defaults.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 +19,8 @@ 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';
+const importMetaHandlerPath = join(__dirname, '__fixtures__', 'import-meta-handler.js');
 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();
@@ -23,10 +28,12 @@ describe('ESM cache-busting (multi-stage)', () => {
         const backend1 = await BlocksBackend.create(stack, 'Stage1', {
             backendHandlerPath: handlerPath,
             backendCDKPath: sideEffectBackendPath,
+            defaults: BlocksPresets.production,
         });
         const backend2 = await BlocksBackend.create(stack, 'Stage2', {
             backendHandlerPath: handlerPath,
             backendCDKPath: sideEffectBackendPath,
+            defaults: BlocksPresets.production,
         });
         const findMarker = (scope) => scope.node.tryFindChild('SideEffectMarker');
         assert.ok(findMarker(backend1), 'Stage1 backend should have SideEffectMarker construct from module side effect');
@@ -40,6 +47,7 @@ describe('synth shape (drop into existing stack)', () => {
         const backend = await BlocksBackend.create(parent, 'Blocks', {
             backendHandlerPath: handlerPath,
             backendCDKPath: sideEffectBackendPath,
+            defaults: BlocksPresets.production,
         });
         // Public surface mirrors BlocksStack.
         assert.ok(backend.handler, 'BlocksBackend should expose .handler');
@@ -57,15 +65,104 @@ describe('synth shape (drop into existing stack)', () => {
         await BlocksBackend.create(parent, 'BackendA', {
             backendHandlerPath: handlerPath,
             backendCDKPath: sideEffectBackendPath,
+            defaults: BlocksPresets.production,
         });
         await BlocksBackend.create(parent, 'BackendB', {
             backendHandlerPath: handlerPath,
             backendCDKPath: sideEffectBackendPath,
+            defaults: BlocksPresets.production,
         });
         const template = Template.fromStack(parent);
         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,
+            defaults: BlocksPresets.production,
+        });
+        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,
+            defaults: BlocksPresets.production,
+        });
+        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,
+            defaults: BlocksPresets.production,
+        });
+        // 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('CJS bundle: import.meta.url in the handler is shimmed (no Lambda-load crash)', () => {
+    test('a handler that uses import.meta.url bundles successfully instead of throwing at load', async () => {
+        // The handler is bundled to CJS, where `import.meta` is empty. Left unshimmed,
+        // `fileURLToPath(import.meta.url)` compiles to `fileURLToPath(undefined)` and
+        // throws at Lambda load (esbuild only warns, so the broken bundle would deploy).
+        // blocksNodejsBundling shims import.meta.* to CommonJS equivalents, so bundling
+        // (which runs synchronously during construction) succeeds. The runtime behaviour
+        // of the emitted shim is verified directly in bundling.test.ts.
+        const app = new cdk.App();
+        const stack = new cdk.Stack(app, 'ImportMetaStack');
+        await assert.doesNotReject(() => BlocksBackend.create(stack, 'blocks', {
+            backendHandlerPath: importMetaHandlerPath,
+            backendCDKPath: sideEffectBackendPath,
+            defaults: BlocksPresets.production,
+        }));
+    });
+});
 describe('factory function support', () => {
     test('BlocksBackend.create() calls default export function with the backend instance', async () => {
         const app = new cdk.App();
@@ -73,6 +170,7 @@ describe('factory function support', () => {
         const backend = await BlocksBackend.create(stack, 'FactoryStage', {
             backendHandlerPath: handlerPath,
             backendCDKPath: factoryBackendPath,
+            defaults: BlocksPresets.production,
         });
         const marker = backend.node.tryFindChild('FactoryMarker');
         assert.ok(marker, 'Factory function should have created FactoryMarker on the backend');
@@ -85,6 +183,7 @@ describe('fullId is token-free (construct IDs / env-var keys)', () => {
         const backend = await BlocksBackend.create(stack, 'blocks', {
             backendHandlerPath: handlerPath,
             backendCDKPath: sideEffectBackendPath,
+            defaults: BlocksPresets.production,
         });
         assert.strictEqual(backend.fullId, 'TopLevelStack-blocks');
         assert.ok(!cdk.Token.isUnresolved(backend.fullId), 'fullId must not contain a token');
@@ -102,6 +201,7 @@ describe('fullId is token-free (construct IDs / env-var keys)', () => {
         const backend = await BlocksBackend.create(nested, 'blocks', {
             backendHandlerPath: handlerPath,
             backendCDKPath: sideEffectBackendPath,
+            defaults: BlocksPresets.production,
         });
         assert.ok(!cdk.Token.isUnresolved(backend.fullId), `fullId must be token-free inside a nested stack, got: ${backend.fullId}`);
         // Falls back to the top-level (concrete) stack name, keeping uniqueness.
@@ -116,6 +216,7 @@ describe('fullId is token-free (construct IDs / env-var keys)', () => {
         const backend = await BlocksBackend.create(nested, 'blocks', {
             backendHandlerPath: handlerPath,
             backendCDKPath: fullIdConstructBackendPath,
+            defaults: BlocksPresets.production,
         });
         // The construct ID is `${scope.fullId}Marker` → `ParentStack-blocks-blocks-dbMarker`.
         const expectedId = `${backend.fullId}-dbMarker`;
@@ -136,6 +237,7 @@ describe('fullId is token-free (construct IDs / env-var keys)', () => {
         const backend = await BlocksBackend.create(nested, 'blocks', {
             backendHandlerPath: handlerPath,
             backendCDKPath: sideEffectBackendPath,
+            defaults: BlocksPresets.production,
         });
         const template = Template.fromStack(nested);
         const fns = template.findResources('AWS::Lambda::Function');
@@ -149,3 +251,37 @@ describe('fullId is token-free (construct IDs / env-var keys)', () => {
         }
     });
 });
+describe('infrastructure defaults (backend-anchored)', () => {
+    test('each backend exposes its own defaults', async () => {
+        const app = new cdk.App();
+        const stack = new cdk.Stack(app, 'TwoBackendsStack');
+        const a = await BlocksBackend.create(stack, 'A', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: sideEffectBackendPath,
+            defaults: BlocksPresets.production,
+        });
+        const b = await BlocksBackend.create(stack, 'B', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: sideEffectBackendPath,
+            defaults: BlocksPresets.sandbox,
+        });
+        // Two backends in one stack must NOT clobber each other — defaults are
+        // anchored on the backend, not the shared stack.
+        assert.strictEqual(a.defaults, BlocksPresets.production);
+        assert.strictEqual(b.defaults, BlocksPresets.sandbox);
+    });
+    test('a nested block resolves its owning backend defaults via the tree-walk', async () => {
+        const app = new cdk.App();
+        const stack = new cdk.Stack(app, 'ResolveDefaultsStack');
+        const backend = await BlocksBackend.create(stack, 'Blocks', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: sideEffectBackendPath,
+            defaults: BlocksPresets.sandbox,
+        });
+        // A Scope under the backend resolves scope.defaults by walking up to it.
+        const outer = new Scope('outer');
+        const inner = new Scope('inner', { parent: outer });
+        assert.strictEqual(inner.defaults, backend.defaults);
+        assert.strictEqual(inner.defaults, BlocksPresets.sandbox);
+    });
+});

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

@@ -0,0 +1,44 @@
+import { RemovalPolicy } from 'aws-cdk-lib';
+/**
+ * Default values for every Amazon-authored Building Block created within a
+ * `BlocksStack` or `BlocksBackend`. A per-block option always overrides the
+ * corresponding default (`option ?? scope.defaults.field`).
+ *
+ * Start from {@link BlocksPresets} and override individual fields as needed.
+ */
+export interface BlocksDefaults {
+    /**
+     * What happens to a stateful resource (table, bucket, user pool) when the
+     * stack is deleted, via CDK/CloudFormation: `RETAIN` keeps the resource (and
+     * its data) behind; `DESTROY` tears it down. Applies only to CDK/CloudFormation
+     * deletions.
+     */
+    removalPolicy: RemovalPolicy;
+    /**
+     * Whether to block deletion of a stateful resource. Unlike `removalPolicy`,
+     * this guards against deletion through **any** path — CDK/CloudFormation as
+     * well as the CLI, API, and AWS console — until it is turned off.
+     */
+    deletionProtection: boolean;
+}
+/**
+ * Prepared starting points for {@link BlocksDefaults}. Pick one and override
+ * individual fields with a spread:
+ *
+ * ```ts
+ * defaults: { ...BlocksPresets.production, deletionProtection: false }
+ * ```
+ */
+export declare const BlocksPresets: {
+    /** Disposable development stacks: tear down cleanly, no delete guard. */
+    sandbox: {
+        removalPolicy: RemovalPolicy.DESTROY;
+        deletionProtection: false;
+    };
+    /** Durable, protected posture for permanent deployments. */
+    production: {
+        removalPolicy: RemovalPolicy.RETAIN;
+        deletionProtection: true;
+    };
+};
+//# sourceMappingURL=blocks-defaults.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"blocks-defaults.d.ts","sourceRoot":"","sources":["../../src/cdk/blocks-defaults.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;GAMG;AACH,MAAM,WAAW,cAAc;IAC9B;;;;;OAKG;IACH,aAAa,EAAE,aAAa,CAAC;IAE7B;;;;OAIG;IACH,kBAAkB,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,aAAa;IACzB,yEAAyE;;;;;IAKzE,4DAA4D;;;;;CAKnB,CAAC"}

package/dist/cdk/blocks-defaults.js

@@ -0,0 +1,23 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { RemovalPolicy } from 'aws-cdk-lib';
+/**
+ * Prepared starting points for {@link BlocksDefaults}. Pick one and override
+ * individual fields with a spread:
+ *
+ * ```ts
+ * defaults: { ...BlocksPresets.production, deletionProtection: false }
+ * ```
+ */
+export const BlocksPresets = {
+    /** Disposable development stacks: tear down cleanly, no delete guard. */
+    sandbox: {
+        removalPolicy: RemovalPolicy.DESTROY,
+        deletionProtection: false,
+    },
+    /** Durable, protected posture for permanent deployments. */
+    production: {
+        removalPolicy: RemovalPolicy.RETAIN,
+        deletionProtection: true,
+    },
+};

package/dist/cdk/blocks-defaults.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=blocks-defaults.test.d.ts.map

package/dist/cdk/blocks-defaults.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"blocks-defaults.test.d.ts","sourceRoot":"","sources":["../../src/cdk/blocks-defaults.test.ts"],"names":[],"mappings":""}

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

@@ -0,0 +1,22 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * BlocksPresets carry the expected posture. Resolution/anchoring (a block
+ * reading its owning backend's defaults, and two backends in one stack keeping
+ * separate postures) is covered in blocks-backend.test.ts, which has the
+ * fixtures to construct real backends.
+ */
+import { test, describe } from 'node:test';
+import assert from 'node:assert';
+import { RemovalPolicy } from 'aws-cdk-lib';
+import { BlocksPresets } from './blocks-defaults.js';
+describe('BlocksPresets', () => {
+    test('sandbox is disposable: DESTROY + deletion protection off', () => {
+        assert.strictEqual(BlocksPresets.sandbox.removalPolicy, RemovalPolicy.DESTROY);
+        assert.strictEqual(BlocksPresets.sandbox.deletionProtection, false);
+    });
+    test('production is durable: RETAIN + deletion protection on', () => {
+        assert.strictEqual(BlocksPresets.production.removalPolicy, RemovalPolicy.RETAIN);
+        assert.strictEqual(BlocksPresets.production.deletionProtection, true);
+    });
+});

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, BlocksPresets, 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';
@@ -21,10 +21,12 @@ describe('ESM cache-busting (multi-stage)', () => {
         const stack1 = await BlocksStack.create(app, 'PipelineStage1', {
             backendHandlerPath: handlerPath,
             backendCDKPath: sideEffectBackendPath,
+            defaults: BlocksPresets.production,
         });
         const stack2 = await BlocksStack.create(app, 'PipelineStage2', {
             backendHandlerPath: handlerPath,
             backendCDKPath: sideEffectBackendPath,
+            defaults: BlocksPresets.production,
         });
         const findMarker = (scope) => scope.node.tryFindChild('SideEffectMarker');
         assert.ok(findMarker(stack1), 'First stack should have SideEffectMarker from module side effect');
@@ -37,6 +39,7 @@ describe('factory function support', () => {
         const stack = await BlocksStack.create(app, 'FactoryBlocksStack', {
             backendHandlerPath: handlerPath,
             backendCDKPath: factoryBackendPath,
+            defaults: BlocksPresets.production,
         });
         const marker = stack.node.tryFindChild('FactoryMarker');
         assert.ok(marker, 'Factory function should have created FactoryMarker on the stack');
@@ -49,11 +52,45 @@ describe('legacy side-effect mode (no default export)', () => {
         const backend = await BlocksBackend.create(stack, 'LegacyStage', {
             backendHandlerPath: handlerPath,
             backendCDKPath: sideEffectBackendPath,
+            defaults: BlocksPresets.production,
         });
         const marker = backend.node.tryFindChild('SideEffectMarker');
         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,
+            defaults: BlocksPresets.production,
+        });
+        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,
+            defaults: BlocksPresets.production,
+        });
+        // 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;
@@ -65,6 +102,7 @@ describe('assertCdkConditionActive', () => {
             await assert.rejects(BlocksStack.create(app, 'MissingConditionStack', {
                 backendHandlerPath: handlerPath,
                 backendCDKPath: sideEffectBackendPath,
+                defaults: BlocksPresets.production,
             }), (err) => {
                 assert.ok(err.message.includes('Missing --conditions=cdk'), `Expected condition error, got: ${err.message}`);
                 return true;

package/dist/cdk/bundling.d.ts

@@ -0,0 +1,42 @@
+import { type BundlingOptions } from 'aws-cdk-lib/aws-lambda-nodejs';
+/**
+ * Wrap a `NodejsFunction` `bundling` config with the framework's hardened esbuild
+ * defaults, so every Lambda the framework bundles behaves consistently.
+ *
+ * **What it fixes.** `NodejsFunction` bundles to **CommonJS**, where `import.meta` is
+ * empty. Any bundled code that does `fileURLToPath(import.meta.url)` (a customer
+ * handler, a Building Block's `aws-runtime` code, or a dependency) would otherwise
+ * become `fileURLToPath(undefined)` and throw at Lambda load — esbuild only *warns*
+ * (`empty-import-meta`), so the broken bundle deploys and 502s on first invocation.
+ *
+ * **How.** For CJS output this shims `import.meta.url` / `import.meta.dirname` /
+ * `import.meta.filename` to their CommonJS equivalents (`pathToFileURL(__filename)`,
+ * `__dirname`, `__filename`) via an esbuild `--define` + `banner`. This is the same
+ * approach esbuild blesses (defining `import.meta` also suppresses the warning) and
+ * that Rollup applies by default, so:
+ * - a handler that reads `import.meta.url` no longer crashes at load, and
+ * - a bundled dependency that merely *contains* `import.meta` (even in dead code) no
+ *   longer trips a build failure.
+ *
+ * The value resolves to the **bundled output file** (esbuild flattens the module tree),
+ * which is correct for the common cases — a value computed at synth (e.g. a
+ * `migrationsPath`) or dead interop fallbacks — but note it does not point at your
+ * source layout. Runtime code that must read a file relative to itself should not rely
+ * on `import.meta.url` inside a bundle; resolve such paths at synth time or ship the
+ * file as an asset. ESM output (`OutputFormat.ESM`) supports `import.meta` natively and
+ * is left untouched.
+ *
+ * All other options (`minify`, `commandHooks`, `externalModules`, other `esbuildArgs`
+ * such as `--conditions`, and any caller `banner`) are preserved.
+ *
+ * @param options - The site-specific `NodejsFunction` bundling options (optional).
+ * @returns The same options with the CJS `import.meta` shim merged in.
+ *
+ * @example
+ * new lambda.NodejsFunction(scope, 'Handler', {
+ *   entry,
+ *   bundling: blocksNodejsBundling({ minify: true, esbuildArgs: { '--conditions': 'aws-runtime' } }),
+ * });
+ */
+export declare function blocksNodejsBundling(options?: BundlingOptions): BundlingOptions;
+//# sourceMappingURL=bundling.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"bundling.d.ts","sourceRoot":"","sources":["../../src/cdk/bundling.ts"],"names":[],"mappings":"AAGA,OAAO,EAAgB,KAAK,eAAe,EAAE,MAAM,+BAA+B,CAAC;AASnF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,eAAoB,GAAG,eAAe,CAwBnF"}