@aws-blocks/core 0.1.17 → 0.2.0

package/src/cdk/blocks-backend.ts

@@ -4,12 +4,15 @@
 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 type { BlocksDefaults } from './blocks-defaults.js';
 import { BLOCKS_NAMESPACE, BLOCKS_RPC_PREFIX } from '../constants.js';
 import { registerBuiltinRoutes } from '../builtin-routes.js';
 
@@ -44,14 +47,50 @@ export 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 function setupBlocksInfra(scope: Construct, props: BlocksBackendProps, id?: string) {
+  // 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: {
@@ -67,10 +106,13 @@ export function setupBlocksInfra(scope: Construct, props: BlocksBackendProps, 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
@@ -152,7 +194,7 @@ export function setupBlocksInfra(scope: Construct, props: BlocksBackendProps, id
 
   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 };
 }
 
 /**
@@ -177,6 +219,10 @@ export class BlocksBackend extends Construct {
   public readonly gateway: apigateway.RestApi;
   public readonly handler: cdk.aws_lambda_nodejs.NodejsFunction;
   public readonly backendHandlerPath: string;
+  /** Shared IAM role assumed by all Blocks compute. Building Blocks grant to this role. */
+  public readonly executionRole: iam.IRole;
+  /** Infrastructure defaults for Building Blocks created under this backend. */
+  public readonly defaults: BlocksDefaults;
 
   /**
    * The fullId used by child Scopes to compute their env var names,
@@ -217,10 +263,16 @@ export class BlocksBackend extends Construct {
     // Expose self to Building Blocks at CDK time
     (globalThis as any).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

package/src/cdk/blocks-defaults.test.ts

@@ -0,0 +1,25 @@
+// 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/src/cdk/blocks-defaults.ts

@@ -0,0 +1,49 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+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 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,
+	},
+} satisfies Record<string, BlocksDefaults>;

package/src/cdk/blocks-stack.test.ts

@@ -7,7 +7,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(() => {
@@ -26,11 +26,13 @@ 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: any) => scope.node.tryFindChild('SideEffectMarker');
@@ -53,6 +55,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');
@@ -68,6 +71,7 @@ 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');
@@ -78,6 +82,48 @@ describe('legacy side-effect mode (no default export)', () => {
   });
 });
 
+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 as any).CURRENT_BLOCKS_STACK = stack;
+    const orphan = new Scope('orphan', { parent: plainStack as any });
+
+    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;
@@ -92,6 +138,7 @@ describe('assertCdkConditionActive', () => {
         BlocksStack.create(app, 'MissingConditionStack', {
           backendHandlerPath: handlerPath,
           backendCDKPath: sideEffectBackendPath,
+          defaults: BlocksPresets.production,
         }),
         (err: Error) => {
           assert.ok(err.message.includes('Missing --conditions=cdk'), `Expected condition error, got: ${err.message}`);

package/src/cdk/bundling.test.ts

@@ -0,0 +1,90 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { test, describe } from 'node:test';
+import assert from 'node:assert';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { mkdtempSync, rmSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { createRequire } from 'node:module';
+import { build } from 'esbuild';
+import { OutputFormat } from 'aws-cdk-lib/aws-lambda-nodejs';
+import { blocksNodejsBundling } from './bundling.js';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const importMetaFixture = join(__dirname, '__fixtures__', 'import-meta-handler.js');
+const requireCjs = createRequire(import.meta.url);
+
+describe('blocksNodejsBundling', () => {
+  test('injects the import.meta.* CJS shim for the default (CJS) output', () => {
+    const out = blocksNodejsBundling({ minify: true, esbuildArgs: { '--conditions': 'aws-runtime' } });
+
+    // Caller options are preserved.
+    assert.equal(out.minify, true);
+    assert.equal(out.esbuildArgs?.['--conditions'], 'aws-runtime');
+
+    // All three import.meta path properties are substituted.
+    assert.ok(out.esbuildArgs?.['--define:import.meta.url']);
+    assert.ok(out.esbuildArgs?.['--define:import.meta.dirname']);
+    assert.ok(out.esbuildArgs?.['--define:import.meta.filename']);
+
+    // The banner defines the substituted identifiers via CommonJS primitives.
+    assert.match(out.banner ?? '', /pathToFileURL\(__filename\)/);
+    assert.match(out.banner ?? '', /__dirname/);
+    assert.match(out.banner ?? '', /__filename/);
+  });
+
+  test('leaves ESM output untouched (import.meta works natively there)', () => {
+    const input = { format: OutputFormat.ESM, esbuildArgs: { '--conditions': 'aws-runtime' } };
+    const out = blocksNodejsBundling(input);
+
+    assert.deepEqual(out, input);
+    assert.equal(out.esbuildArgs?.['--define:import.meta.url'], undefined);
+    assert.equal(out.banner, undefined);
+  });
+
+  test('prepends the shim while keeping a caller-supplied banner', () => {
+    const out = blocksNodejsBundling({ banner: '// caller banner' });
+    assert.match(out.banner ?? '', /pathToFileURL\(__filename\)/);
+    assert.ok((out.banner ?? '').includes('// caller banner'));
+  });
+
+  test('a CJS bundle built with the shim resolves import.meta.url at load (no crash)', async () => {
+    // Bundle the fixture exactly as NodejsFunction would: apply the helper's `banner`
+    // and its `--define:import.meta.*` esbuildArgs. Without the shim this fixture's
+    // top-level `fileURLToPath(import.meta.url)` becomes `fileURLToPath(undefined)`
+    // and throws when the module is loaded.
+    const opts = blocksNodejsBundling({ minify: true });
+    const define: Record<string, string> = {};
+    for (const [key, value] of Object.entries(opts.esbuildArgs ?? {})) {
+      const m = key.match(/^--define:(.+)$/);
+      if (m) define[m[1]] = String(value);
+    }
+
+    const tmp = mkdtempSync(join(tmpdir(), 'bb-shim-'));
+    const outfile = join(tmp, 'out.cjs');
+    try {
+      await build({
+        entryPoints: [importMetaFixture],
+        bundle: true,
+        platform: 'node',
+        format: 'cjs',
+        minify: true,
+        banner: { js: opts.banner ?? '' },
+        define,
+        outfile,
+        logLevel: 'silent',
+      });
+
+      // Loading the bundle must not throw, and import.meta.url must resolve to a real
+      // (file-URL-derived) path rather than being undefined.
+      const mod = requireCjs(outfile);
+      assert.equal(typeof mod.moduleDir, 'string');
+      assert.ok(mod.moduleDir.length > 0, 'moduleDir should resolve to a non-empty path');
+      assert.equal(typeof mod.handler, 'function');
+    } finally {
+      rmSync(tmp, { recursive: true, force: true });
+    }
+  });
+});

package/src/cdk/bundling.ts

@@ -0,0 +1,76 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { OutputFormat, type BundlingOptions } from 'aws-cdk-lib/aws-lambda-nodejs';
+
+/** Banner-defined identifiers the shim substitutes `import.meta.*` with (CJS only). */
+const IMPORT_META_SHIM = {
+  url: '__blocksImportMetaUrl',
+  dirname: '__blocksImportMetaDirname',
+  filename: '__blocksImportMetaFilename',
+} as const;
+
+/**
+ * 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 function blocksNodejsBundling(options: BundlingOptions = {}): BundlingOptions {
+  // ESM output has real `import.meta` — nothing to shim, and `require` in the banner
+  // wouldn't resolve. Only the CommonJS bundle needs the shim.
+  if (options.format === OutputFormat.ESM) return options;
+
+  const shimBanner = [
+    `const ${IMPORT_META_SHIM.url}=require('url').pathToFileURL(__filename).href;`,
+    `const ${IMPORT_META_SHIM.dirname}=__dirname;`,
+    `const ${IMPORT_META_SHIM.filename}=__filename;`,
+  ].join('');
+
+  return {
+    ...options,
+    // Prepend the shim definitions; keep any caller-supplied banner after them.
+    banner: options.banner ? `${shimBanner}\n${options.banner}` : shimBanner,
+    esbuildArgs: {
+      ...options.esbuildArgs,
+      // Substitute import.meta.* with the banner identifiers. Also suppresses esbuild's
+      // empty-import-meta warning, so import.meta anywhere in the graph is safe.
+      '--define:import.meta.url': IMPORT_META_SHIM.url,
+      '--define:import.meta.dirname': IMPORT_META_SHIM.dirname,
+      '--define:import.meta.filename': IMPORT_META_SHIM.filename,
+    },
+  };
+}

package/src/cdk/compute/compute.ts

@@ -0,0 +1,37 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import { Scope } from '../index.js';
+
+/**
+ * Base class for a Blocks *compute* — a runtime that executes handler code
+ * (Lambda today; containers later). A compute owns the physical function/service
+ * plus its ingress, and receives config via {@link setEnv}.
+ *
+ * The backend entry and stack name a compute needs are inherited from
+ * {@link Scope} (`backendHandlerPath` / `backendStackName`), which resolve them
+ * from the owning BlocksStack/BlocksBackend — never caller-supplied, so every
+ * compute in an app runs the same backend and agrees on the resource-name
+ * namespace.
+ *
+ * The abstract base lives in core (a framework primitive); concrete computes
+ * live in their own packages (e.g. `LambdaCompute` in `@aws-blocks/bb-lambda-compute`).
+ *
+ * @internal Not exported from the package's public entry points. Customers
+ * cannot instantiate a compute until the customer-facing surface exists.
+ */
+export abstract class Compute extends Scope {
+	/**
+	 * API namespaces assigned to run on this compute — recorded so request
+	 * routing can map a namespace to the compute that hosts it. Currently
+	 * unpopulated (no compute assignment surface yet).
+	 */
+	readonly namespaces: string[] = [];
+
+	/**
+	 * Inject a runtime configuration value (an environment variable) into this
+	 * compute. The framework calls this instead of `handler.addEnvironment()`
+	 * directly so config targets the right compute.
+	 */
+	abstract setEnv(key: string, value: string): void;
+}

package/src/cdk/index.ts

@@ -15,11 +15,17 @@ import {
 import { setupBlocksInfra, BlocksBackend, assertCdkConditionActive } from './blocks-backend.js';
 import { addBlocksStackMetadata } from './stack-metadata.js';
 import { finalizeConfigRegistry } from './config-registry.js';
+import { type BlocksDefaults, BlocksPresets } from './blocks-defaults.js';
 
 export { BlocksBackend, type BlocksBackendProps } from './blocks-backend.js';
 export { DEFAULT_NODE_RUNTIME } from './node-version.js';
+export { blocksNodejsBundling } from './bundling.js';
 export { SandboxDisableDeletionProtection } from './mixins.js';
 export { registerConfig, finalizeConfigRegistry } from './config-registry.js';
+export {
+  type BlocksDefaults,
+  BlocksPresets,
+} from './blocks-defaults.js';
 export { synthGuard } from './synth-guard.js';
 export type { ScopeOptions } from '../index.js';
 export { ApiError, isBlocksError, hasAuthError, DEFAULT_API_ERROR_NAME } from '../errors.js';
@@ -30,11 +36,16 @@ export class BlocksStack extends cdk.Stack implements BaseBlocksStack {
   public readonly gateway: cdk.aws_apigateway.RestApi;
   public readonly handler: cdk.aws_lambda_nodejs.NodejsFunction;
   public readonly backendHandlerPath: string;
+  /** Shared IAM role assumed by all Blocks compute. Building Blocks grant to this role. */
+  public readonly executionRole: cdk.aws_iam.IRole;
+  /** Infrastructure defaults for Building Blocks created under this stack. */
+  public readonly defaults: BlocksDefaults;
 
   private constructor(scope: Construct, id: string, props: BlocksStackProps) {
     super(scope, id, props);
     this.id = id;
     this.backendHandlerPath = props.backendHandlerPath;
+    this.defaults = props.defaults;
 
     // Set globalThis so Building Blocks attach directly to this stack
     (globalThis as any).CURRENT_BLOCKS_STACK = this;
@@ -43,6 +54,7 @@ export class BlocksStack extends cdk.Stack implements BaseBlocksStack {
     this.handler = infra.handler;
     this.gateway = infra.gateway;
     this.apiUrl = infra.apiUrl;
+    this.executionRole = infra.executionRole;
   }
 
   static async create(scope: Construct, id: string, props: BlocksStackProps) {
@@ -83,30 +95,118 @@ export class Scope extends Construct {
   readonly bbName?: string;
   readonly bbVersion?: string;
 
+  /**
+   * The owning stack/backend (the root of the Blocks construct tree), resolved
+   * once at construction: the nearest BlocksStack/BlocksBackend up the construct
+   * tree, or the ambient `globalThis.CURRENT_BLOCKS_STACK` fallback. All
+   * root-derived accessors below read from this instead of each repeating the
+   * tree walk.
+   */
+  private readonly root: BlocksStack | BlocksBackend;
+
   constructor(id: string, options?: ScopeOptions) {
     const parent = options?.parent || (globalThis as any).CURRENT_BLOCKS_STACK;
     super(parent, id);
     this.id = id;
     this.parent = parent;
+    this.root = this.resolveRoot();
   }
 
-  get handler() {
-    // Walk up the construct tree to find the owning BlocksStack/BlocksBackend
+  /**
+   * Walk up the construct tree to the nearest owning BlocksStack/BlocksBackend;
+   * fall back to the ambient `globalThis.CURRENT_BLOCKS_STACK`. Called once from
+   * the constructor; the result is cached in {@link root}.
+   */
+  private resolveRoot(): BlocksStack | BlocksBackend {
     let current: Construct = this;
     while (current.node.scope) {
         current = current.node.scope as Construct;
         if (current instanceof BlocksStack || current instanceof BlocksBackend) {
-            return current.handler;
+            return current;
         }
     }
-    // Fallback to globalThis for backward compatibility
-    return ((globalThis as any).CURRENT_BLOCKS_STACK as { handler: cdk.aws_lambda_nodejs.NodejsFunction }).handler;
+    // Fallback to the ambient stack. In production this is always a real
+    // BlocksStack/BlocksBackend; the cast also admits the test doubles that set
+    // globalThis.CURRENT_BLOCKS_STACK to a stub exposing the same surface.
+    return (globalThis as any).CURRENT_BLOCKS_STACK as BlocksStack | BlocksBackend;
+  }
+
+  get handler() {
+    return this.root.handler;
+  }
+
+  /**
+   * The shared IAM role assumed by all Blocks compute. Building Blocks grant
+   * their permissions to this role; CDK's `grant*()` / `addToPrincipalPolicy()`
+   * route those grants to the role's default (inline) policy.
+   */
+  get executionRole(): cdk.aws_iam.IRole {
+    return this.root.executionRole;
+  }
+
+  /**
+   * The backend entry file the owning BlocksStack/BlocksBackend runs — the
+   * single handler entry shared across the whole app.
+   */
+  get backendHandlerPath(): string {
+    return this.root.backendHandlerPath;
+  }
+
+  /**
+   * The owning stack/backend's token-free root identity. This is the value the
+   * runtime receives as `BLOCKS_STACK_NAME` and rebuilds `fullId` from, so
+   * physical resource names (DynamoDB tables, env-var keys, IAM ARNs) derived
+   * from `fullId` match byte-for-byte between synth and runtime — otherwise the
+   * runtime looks up names that were never created. `BlocksBackend` exposes this
+   * as `fullId` ({@link BlocksBackend.fullId}); `BlocksStack` as `id`.
+   */
+  get backendStackName(): string {
+    const name = this.root instanceof BlocksBackend ? this.root.fullId : this.root.id;
+    if (!name) {
+      throw new Error('Owning Blocks stack/backend has no id to derive BLOCKS_STACK_NAME');
+    }
+    return name;
   }
 
   get fullId(): string {
     return computeScopeFullId(this);
   }
 
+  /**
+   * The stack-wide infrastructure {@link BlocksDefaults} registered by
+   * `BlocksStack.create` / `BlocksBackend.create`. Read these in a Building
+   * Block's CDK constructor to resolve a durability value, letting a per-block
+   * option override:
+   *
+   * ```ts
+   * const removalPolicy = options?.removalPolicy ?? this.defaults.removalPolicy;
+   * ```
+   */
+  get defaults(): BlocksDefaults {
+    // Resolve the same way as handler/executionRole: walk up to the owning
+    // BlocksStack/BlocksBackend and read its defaults, so several backends in
+    // one stack each keep their own posture. Falls back to the ambient stack,
+    // then to the production preset when none was registered.
+    let current: Construct = this;
+    while (current.node.scope) {
+        current = current.node.scope as Construct;
+        if (current instanceof BlocksStack || current instanceof BlocksBackend) {
+            return current.defaults;
+        }
+    }
+    const ambient = ((globalThis as any).CURRENT_BLOCKS_STACK as { defaults?: BlocksDefaults } | undefined)?.defaults;
+    if (ambient) return ambient;
+    // No owning BlocksStack/BlocksBackend in the tree and none ambient — this is
+    // usually a deliberate test stub, but could be a real misconfiguration (a
+    // block built outside any Blocks backend). Fall back to the safe production
+    // posture, and log so it's debuggable if it fires unexpectedly.
+    console.warn(
+      `[Blocks] Scope "${this.id}" resolved infrastructure defaults with no owning ` +
+      'BlocksStack/BlocksBackend in scope; falling back to BlocksPresets.production.',
+    );
+    return BlocksPresets.production;
+  }
+
   protected buildUserAgentChain(): [string, string][] {
     return [];
   }