@aws-blocks/core 0.1.0

package/dist/cdk/blocks-backend.js

@@ -0,0 +1,214 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+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 { CfnGroup } from 'aws-cdk-lib/aws-resourcegroups';
+import { Construct } from 'constructs';
+import { DEFAULT_NODE_RUNTIME } from './node-version.js';
+import { addBlocksStackMetadata } from './stack-metadata.js';
+import { finalizeConfigRegistry, registerConfig } from './config-registry.js';
+import { BLOCKS_NAMESPACE, BLOCKS_RPC_PREFIX } from '../constants.js';
+import { registerBuiltinRoutes } from '../builtin-routes.js';
+/**
+ * Validate that the Node.js process was started with `--conditions=cdk`.
+ *
+ * Without this condition, conditional exports in Building Block packages
+ * resolve to their mock/default entry points instead of the CDK entry points.
+ * This causes a silent deployment failure: CDK synth "succeeds" but produces
+ * no real infrastructure (no tables, no IAM, no Lambda configs).
+ */
+export function assertCdkConditionActive() {
+    const nodeOptions = process.env.NODE_OPTIONS ?? '';
+    const execArgv = process.execArgv ?? [];
+    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);
+    if (!hasCdkCondition) {
+        throw new Error('Missing --conditions=cdk: Building Blocks will silently load mock implementations instead of CDK constructs.\n\n' +
+            'Fix: Set NODE_OPTIONS="--conditions=cdk" before running CDK synth:\n' +
+            '  NODE_OPTIONS="--conditions=cdk" npx cdk synth\n\n' +
+            'Or use the Blocks CLI commands (npm run deploy / npm run sandbox) which set this automatically.');
+    }
+}
+/** Shared infra setup — creates Lambda + API Gateway on the given scope. */
+export function setupBlocksInfra(scope, props, id) {
+    const handler = new lambda.NodejsFunction(scope, 'Handler', {
+        entry: props.backendHandlerPath,
+        runtime: DEFAULT_NODE_RUNTIME,
+        handler: 'handler',
+        memorySize: 2048,
+        timeout: cdk.Duration.seconds(60 * 15),
+        environment: {
+            NODE_ENV: 'production',
+            /**
+             * BLOCKS_STACK_NAME is used at runtime to derive physical resource names
+             * (DynamoDB table names, env var prefixes). It must match the CDK-time
+             * fullId of the BlocksStack/BlocksBackend so resource lookups work correctly.
+             *
+             * For BlocksStack: this equals the stack name (id).
+             * For BlocksBackend: the caller overrides this after construction to include
+             * the parent stack name for deployment uniqueness.
+             */
+            BLOCKS_STACK_NAME: id ?? cdk.Stack.of(scope).stackName,
+        },
+        bundling: {
+            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.
+    const isSandbox = scope.node.tryGetContext('sandboxMode') === 'true' ||
+        scope.node.tryGetContext('sandboxMode') === true;
+    if (isSandbox) {
+        handler.addEnvironment('CORS_ALLOWED_ORIGINS', '^https?://(localhost|127\\.0\\.0\\.1)(:\\d+)?$');
+    }
+    const api = new apigateway.RestApi(scope, 'API', {
+        restApiName: 'Blocks API',
+        deployOptions: { cachingEnabled: false },
+    });
+    const integration = new apigateway.LambdaIntegration(handler);
+    // Build the nested resource tree for /aws-blocks/api.
+    // Intermediate resource gets a proxy so sub-paths (RawRoutes) still reach Lambda.
+    const awsBlocksResource = api.root.addResource(BLOCKS_NAMESPACE.slice(1));
+    awsBlocksResource.addProxy({ defaultIntegration: integration, anyMethod: true });
+    const apiResource = awsBlocksResource.addResource('api');
+    apiResource.addMethod('POST', integration);
+    apiResource.addMethod('OPTIONS', integration);
+    api.root.addProxy({ defaultIntegration: integration, anyMethod: true });
+    // ── 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;
+    new CfnGroup(scope, 'StackResources', {
+        name: `${groupPrefix}-resources`,
+        resourceQuery: {
+            type: 'CLOUDFORMATION_STACK_1_0',
+            query: {
+                resourceTypeFilters: [
+                    'AWS::CloudWatch::Dashboard',
+                    'AWS::Cognito::UserPool',
+                    'AWS::DynamoDB::Table',
+                    'AWS::Logs::LogGroup',
+                    'AWS::RDS::DBCluster',
+                    'AWS::RDS::DBInstance',
+                    'AWS::S3::Bucket',
+                    'AWS::SQS::Queue',
+                ],
+                stackIdentifier: cdk.Stack.of(scope).stackId,
+            },
+        },
+    });
+    new CfnGroup(scope, 'StackSettings', {
+        name: `${groupPrefix}-settings`,
+        resourceQuery: {
+            type: 'TAG_FILTERS_1_0',
+            query: {
+                resourceTypeFilters: ['AWS::SSM::Parameter'],
+                tagFilters: [{ key: 'aws-blocks-stack', values: [rootStack.stackName] }],
+            },
+        },
+    });
+    // ── 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,
+    ]);
+    const settingsUrl = cdk.Fn.join('', [
+        '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);
+    registerBuiltinRoutes();
+    return { handler, gateway: api, apiUrl: `${api.url}${BLOCKS_RPC_PREFIX.slice(1)}` };
+}
+/**
+ * Standalone CDK construct that provisions the Blocks backend: a single Lambda
+ * function fronted by API Gateway with RPC + catch-all proxy routing.
+ *
+ * Use this to embed a Blocks backend into any existing CDK stack. Building Blocks
+ * instantiated during the `backendCDKPath` import will automatically attach to
+ * this construct's Lambda handler.
+ *
+ * @example Drop into an existing stack
+ * ```ts
+ * const blocks = await BlocksBackend.create(myStack, 'Blocks', {
+ *   backendHandlerPath: join(__dirname, 'handler.ts'),
+ *   backendCDKPath: join(__dirname, 'infra.ts'),
+ * });
+ * // blocks.apiUrl, blocks.handler, blocks.gateway available
+ * ```
+ */
+export class BlocksBackend extends Construct {
+    apiUrl;
+    gateway;
+    handler;
+    backendHandlerPath;
+    /**
+     * The fullId used by child Scopes to compute their env var names,
+     * construct IDs, and physical resource names (e.g., DynamoDB table names).
+     *
+     * Includes the CDK stack name to ensure physical resources are unique
+     * per deployment. This matches what the runtime sees via BLOCKS_STACK_NAME.
+     *
+     * IMPORTANT: this value MUST be token-free. Child Scopes embed `fullId` in
+     * CDK construct IDs (e.g. `${fullId}DsqlMigrationFn`), and CDK forbids
+     * unresolved tokens in construct IDs ("ID components may not include
+     * unresolved tokens"). It is also used to build env-var keys that must match
+     * byte-for-byte between synth time and runtime.
+     *
+     * A nested stack (e.g. Amplify Gen2 `backend.createStack('blocks')`) has a
+     * tokenized `stackName` that only resolves at deploy time. We therefore walk
+     * up to the top-level stack, whose name is concrete at synth time and still
+     * unique per deployment. The `Token.isUnresolved` guard is a defensive
+     * fallback to the (token-free) construct id should no resolvable name exist.
+     */
+    get fullId() {
+        let stack = cdk.Stack.of(this);
+        while (stack.nestedStackParent) {
+            stack = stack.nestedStackParent;
+        }
+        const stackName = stack.stackName;
+        if (cdk.Token.isUnresolved(stackName)) {
+            return this.node.id;
+        }
+        return `${stackName}-${this.node.id}`;
+    }
+    constructor(scope, id, props) {
+        super(scope, id);
+        this.backendHandlerPath = props.backendHandlerPath;
+        // Expose self to Building Blocks at CDK time
+        globalThis.CURRENT_BLOCKS_STACK = this;
+        const infra = setupBlocksInfra(this, props, id);
+        this.handler = infra.handler;
+        this.gateway = infra.gateway;
+        this.apiUrl = infra.apiUrl;
+        // 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.
+        this.handler.addEnvironment('BLOCKS_STACK_NAME', this.fullId);
+    }
+    static async create(scope, id, props) {
+        assertCdkConditionActive();
+        const backend = new BlocksBackend(scope, id, props);
+        // ESM caches modules by URL — append a unique query string so each stage re-executes the module body
+        const mod = await import(`${props.backendCDKPath}?stack=${id}`);
+        if (typeof mod.default === 'function') {
+            try {
+                await mod.default(backend);
+            }
+            catch (error) {
+                throw new Error(`Error executing default export function for backend "${id}": ${error instanceof Error ? error.message : error}`, { cause: error });
+            }
+        }
+        addBlocksStackMetadata(cdk.Stack.of(backend));
+        // Finalize BB config → S3 (after all BBs have registered their config)
+        finalizeConfigRegistry(backend, backend.handler);
+        return backend;
+    }
+}

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

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

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

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

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

@@ -0,0 +1,151 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { test, describe, before } from 'node:test';
+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 { BlocksBackend } from './blocks-backend.js';
+// Simulate the CDK condition being active (tests import CDK files directly)
+before(() => {
+    process.env.NODE_OPTIONS = (process.env.NODE_OPTIONS ?? '') + ' --conditions=cdk';
+});
+const __dirname = dirname(fileURLToPath(import.meta.url));
+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');
+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();
+        const stack = new cdk.Stack(app, 'TestStack');
+        const backend1 = await BlocksBackend.create(stack, 'Stage1', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: sideEffectBackendPath,
+        });
+        const backend2 = await BlocksBackend.create(stack, 'Stage2', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: sideEffectBackendPath,
+        });
+        const findMarker = (scope) => scope.node.tryFindChild('SideEffectMarker');
+        assert.ok(findMarker(backend1), 'Stage1 backend should have SideEffectMarker construct from module side effect');
+        assert.ok(findMarker(backend2), 'Stage2 backend should have SideEffectMarker construct from re-executed module');
+    });
+});
+describe('synth shape (drop into existing stack)', () => {
+    test('BlocksBackend lives inside the parent stack and synthesizes Lambda + API Gateway', async () => {
+        const app = new cdk.App();
+        const parent = new cdk.Stack(app, 'MyExistingStack');
+        const backend = await BlocksBackend.create(parent, 'Blocks', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: sideEffectBackendPath,
+        });
+        // Public surface mirrors BlocksStack.
+        assert.ok(backend.handler, 'BlocksBackend should expose .handler');
+        assert.ok(backend.gateway, 'BlocksBackend should expose .gateway');
+        assert.ok(backend.apiUrl, 'BlocksBackend should expose .apiUrl');
+        // Synth produces the expected resources inside the parent stack —
+        // no separate stack is created.
+        const template = Template.fromStack(parent);
+        template.hasResourceProperties('AWS::Lambda::Function', {});
+        template.resourceCountIs('AWS::ApiGateway::RestApi', 1);
+    });
+    test('multiple BlocksBackends in the same parent stack do not collide', async () => {
+        const app = new cdk.App();
+        const parent = new cdk.Stack(app, 'MultiBackendStack');
+        await BlocksBackend.create(parent, 'BackendA', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: sideEffectBackendPath,
+        });
+        await BlocksBackend.create(parent, 'BackendB', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: sideEffectBackendPath,
+        });
+        const template = Template.fromStack(parent);
+        template.resourceCountIs('AWS::ApiGateway::RestApi', 2);
+    });
+});
+describe('factory function support', () => {
+    test('BlocksBackend.create() calls default export function with the backend instance', async () => {
+        const app = new cdk.App();
+        const stack = new cdk.Stack(app, 'FactoryTestStack');
+        const backend = await BlocksBackend.create(stack, 'FactoryStage', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: factoryBackendPath,
+        });
+        const marker = backend.node.tryFindChild('FactoryMarker');
+        assert.ok(marker, 'Factory function should have created FactoryMarker on the backend');
+    });
+});
+describe('fullId is token-free (construct IDs / env-var keys)', () => {
+    test('top-level stack: fullId is {stackName}-{id} and resolvable', async () => {
+        const app = new cdk.App();
+        const stack = new cdk.Stack(app, 'TopLevelStack');
+        const backend = await BlocksBackend.create(stack, 'blocks', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: sideEffectBackendPath,
+        });
+        assert.strictEqual(backend.fullId, 'TopLevelStack-blocks');
+        assert.ok(!cdk.Token.isUnresolved(backend.fullId), 'fullId must not contain a token');
+    });
+    test('nested stack: fullId stays token-free (regression for #714 / Amplify Gen2)', async () => {
+        // Amplify Gen2 wires Blocks into a NestedStack via backend.createStack('blocks').
+        // A NestedStack has a tokenized stackName that only resolves at deploy time —
+        // embedding it in fullId broke construct IDs with
+        // "ID components may not include unresolved tokens".
+        const app = new cdk.App();
+        const parent = new cdk.Stack(app, 'ParentStack');
+        const nested = new cdk.NestedStack(parent, 'blocks');
+        // Sanity: the nested stack's own name really is a token.
+        assert.ok(cdk.Token.isUnresolved(nested.stackName), 'precondition: NestedStack.stackName should be an unresolved token');
+        const backend = await BlocksBackend.create(nested, 'blocks', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: sideEffectBackendPath,
+        });
+        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.
+        assert.strictEqual(backend.fullId, 'ParentStack-blocks');
+    });
+    test('child Scope can use fullId as a construct ID inside a nested stack', async () => {
+        // The fixture mirrors bb-distributed-data: it builds a construct whose ID is
+        // `${this.fullId}Marker`. If fullId carried a token, synth would throw.
+        const app = new cdk.App();
+        const parent = new cdk.Stack(app, 'Gen2ParentStack');
+        const nested = new cdk.NestedStack(parent, 'blocks');
+        const backend = await BlocksBackend.create(nested, 'blocks', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: fullIdConstructBackendPath,
+        });
+        // The construct ID is `${scope.fullId}Marker` → `ParentStack-blocks-blocks-dbMarker`.
+        const expectedId = `${backend.fullId}-dbMarker`;
+        assert.ok(nested.node.tryFindChild(expectedId), `expected a child construct with id "${expectedId}"`);
+        // Full synth must not throw on unresolved-token-in-construct-id.
+        assert.doesNotThrow(() => app.synth());
+    });
+    test('BLOCKS_STACK_NAME env var equals fullId (CDK-time ↔ runtime invariant)', async () => {
+        // Physical resource names (DynamoDB tables, DSQL env-var keys, IAM ARNs) are
+        // derived from fullId on BOTH sides: at synth via BlocksBackend.fullId, and at
+        // runtime via the root parent `{ id: process.env.BLOCKS_STACK_NAME }`. They MUST
+        // be byte-for-byte identical, otherwise the runtime looks up names/grants that
+        // were never created. BlocksBackend keeps them in sync by writing fullId into the
+        // handler's BLOCKS_STACK_NAME env var — assert that contract holds and is token-free.
+        const app = new cdk.App();
+        const parent = new cdk.Stack(app, 'InvariantParent');
+        const nested = new cdk.NestedStack(parent, 'blocks');
+        const backend = await BlocksBackend.create(nested, 'blocks', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: sideEffectBackendPath,
+        });
+        const template = Template.fromStack(nested);
+        const fns = template.findResources('AWS::Lambda::Function');
+        const envValues = Object.values(fns)
+            .map((fn) => fn.Properties?.Environment?.Variables?.BLOCKS_STACK_NAME)
+            .filter((v) => typeof v === 'string');
+        assert.ok(envValues.length > 0, 'expected a Lambda with a BLOCKS_STACK_NAME env var');
+        for (const value of envValues) {
+            assert.strictEqual(value, backend.fullId, 'BLOCKS_STACK_NAME must equal BlocksBackend.fullId so runtime names match synth');
+            assert.ok(!cdk.Token.isUnresolved(value), `BLOCKS_STACK_NAME must be token-free, got: ${value}`);
+        }
+    });
+});

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

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

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

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

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

@@ -0,0 +1,78 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { test, describe, before } from 'node:test';
+import assert from 'node:assert';
+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';
+// Simulate the CDK condition being active (tests import CDK files directly)
+before(() => {
+    process.env.NODE_OPTIONS = (process.env.NODE_OPTIONS ?? '') + ' --conditions=cdk';
+});
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const handlerPath = join(__dirname, '__fixtures__', 'handler.js');
+const sideEffectBackendPath = join(__dirname, '__fixtures__', 'side-effect-backend.js');
+const factoryBackendPath = join(__dirname, '__fixtures__', 'factory-backend.js');
+describe('ESM cache-busting (multi-stage)', () => {
+    test('BlocksStack.create() with same backendCDKPath but different IDs produces constructs in each', async () => {
+        const app = new cdk.App();
+        const stack1 = await BlocksStack.create(app, 'PipelineStage1', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: sideEffectBackendPath,
+        });
+        const stack2 = await BlocksStack.create(app, 'PipelineStage2', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: sideEffectBackendPath,
+        });
+        const findMarker = (scope) => scope.node.tryFindChild('SideEffectMarker');
+        assert.ok(findMarker(stack1), 'First stack should have SideEffectMarker from module side effect');
+        assert.ok(findMarker(stack2), 'Second stack should have SideEffectMarker from re-executed module (cache busted)');
+    });
+});
+describe('factory function support', () => {
+    test('BlocksStack.create() calls default export function with the stack instance', async () => {
+        const app = new cdk.App();
+        const stack = await BlocksStack.create(app, 'FactoryBlocksStack', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: factoryBackendPath,
+        });
+        const marker = stack.node.tryFindChild('FactoryMarker');
+        assert.ok(marker, 'Factory function should have created FactoryMarker on the stack');
+    });
+});
+describe('legacy side-effect mode (no default export)', () => {
+    test('module with only side effects still registers constructs via globalThis', async () => {
+        const app = new cdk.App();
+        const stack = new cdk.Stack(app, 'LegacyTestStack');
+        const backend = await BlocksBackend.create(stack, 'LegacyStage', {
+            backendHandlerPath: handlerPath,
+            backendCDKPath: sideEffectBackendPath,
+        });
+        const marker = backend.node.tryFindChild('SideEffectMarker');
+        assert.ok(marker, 'Side-effect-only module should register construct via globalThis.CURRENT_BLOCKS_STACK');
+    });
+});
+describe('assertCdkConditionActive', () => {
+    test('BlocksStack.create() throws when --conditions=cdk is missing', async () => {
+        const origNodeOptions = process.env.NODE_OPTIONS;
+        const origExecArgv = process.execArgv;
+        process.env.NODE_OPTIONS = '';
+        process.execArgv = [];
+        try {
+            const app = new cdk.App();
+            await assert.rejects(BlocksStack.create(app, 'MissingConditionStack', {
+                backendHandlerPath: handlerPath,
+                backendCDKPath: sideEffectBackendPath,
+            }), (err) => {
+                assert.ok(err.message.includes('Missing --conditions=cdk'), `Expected condition error, got: ${err.message}`);
+                return true;
+            });
+        }
+        finally {
+            process.env.NODE_OPTIONS = origNodeOptions;
+            process.execArgv = origExecArgv;
+        }
+    });
+});

package/dist/cdk/config-registry.d.ts

@@ -0,0 +1,26 @@
+import * as cdk from 'aws-cdk-lib';
+import type { Construct } from 'constructs';
+/**
+ * Register a config entry for a Building Block. This replaces
+ * `handler.addEnvironment(key, value)` for BB resource mappings.
+ *
+ * The entry will be serialized into a JSON config file in S3, loaded
+ * by the Lambda at cold start. This avoids the 4KB env var limit.
+ *
+ * @param scope - The CDK construct (used to find the parent stack)
+ * @param key - The config key (same string the runtime will use to look it up)
+ * @param value - The config value (can be a CDK token that resolves at deploy time)
+ */
+export declare function registerConfig(scope: Construct, key: string, value: unknown): void;
+/**
+ * Finalize the config registry: create an S3 bucket, upload the config JSON,
+ * set env vars on the handler, and grant read access.
+ *
+ * Must be called after all BBs are constructed (i.e., after the backendCDKPath
+ * import completes in BlocksStack.create() / BlocksBackend.create()).
+ *
+ * @param scope - The CDK construct to create resources under
+ * @param handler - The Lambda function that needs to read the config
+ */
+export declare function finalizeConfigRegistry(scope: Construct, handler: cdk.aws_lambda.IFunction): void;
+//# sourceMappingURL=config-registry.d.ts.map

package/dist/cdk/config-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config-registry.d.ts","sourceRoot":"","sources":["../../src/cdk/config-registry.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,GAAG,MAAM,aAAa,CAAC;AAInC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAuB5C;;;;;;;;;;GAUG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,SAAS,EAAE,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,IAAI,CAIlF;AAED;;;;;;;;;GASG;AACH,wBAAgB,sBAAsB,CACrC,KAAK,EAAE,SAAS,EAChB,OAAO,EAAE,GAAG,CAAC,UAAU,CAAC,SAAS,GAC/B,IAAI,CA6CN"}

package/dist/cdk/config-registry.js

@@ -0,0 +1,80 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import * as cdk from 'aws-cdk-lib';
+import * as s3 from 'aws-cdk-lib/aws-s3';
+import * as s3deploy from 'aws-cdk-lib/aws-s3-deployment';
+import * as iam from 'aws-cdk-lib/aws-iam';
+const REGISTRY_KEY = Symbol.for('BLOCKS_CONFIG_REGISTRY');
+/**
+ * Get or create the config registry for a given stack.
+ * The registry collects BB config entries (env var key → CDK token value)
+ * and serializes them to an S3 JSON file at synth time.
+ */
+function getRegistry(stack) {
+    let state = stack[REGISTRY_KEY];
+    if (!state) {
+        state = { entries: new Map(), finalized: false };
+        stack[REGISTRY_KEY] = state;
+    }
+    return state;
+}
+/**
+ * Register a config entry for a Building Block. This replaces
+ * `handler.addEnvironment(key, value)` for BB resource mappings.
+ *
+ * The entry will be serialized into a JSON config file in S3, loaded
+ * by the Lambda at cold start. This avoids the 4KB env var limit.
+ *
+ * @param scope - The CDK construct (used to find the parent stack)
+ * @param key - The config key (same string the runtime will use to look it up)
+ * @param value - The config value (can be a CDK token that resolves at deploy time)
+ */
+export function registerConfig(scope, key, value) {
+    const stack = cdk.Stack.of(scope);
+    const registry = getRegistry(stack);
+    registry.entries.set(key, value);
+}
+/**
+ * Finalize the config registry: create an S3 bucket, upload the config JSON,
+ * set env vars on the handler, and grant read access.
+ *
+ * Must be called after all BBs are constructed (i.e., after the backendCDKPath
+ * import completes in BlocksStack.create() / BlocksBackend.create()).
+ *
+ * @param scope - The CDK construct to create resources under
+ * @param handler - The Lambda function that needs to read the config
+ */
+export function finalizeConfigRegistry(scope, handler) {
+    const stack = cdk.Stack.of(scope);
+    const registry = getRegistry(stack);
+    if (registry.finalized)
+        return;
+    registry.finalized = true;
+    if (registry.entries.size === 0)
+        return;
+    const configBucket = new s3.Bucket(scope, 'BlocksConfigBucket', {
+        removalPolicy: cdk.RemovalPolicy.DESTROY,
+        autoDeleteObjects: true,
+        encryption: s3.BucketEncryption.S3_MANAGED,
+        blockPublicAccess: s3.BlockPublicAccess.BLOCK_ALL,
+        lifecycleRules: [
+            { noncurrentVersionExpiration: cdk.Duration.days(1) },
+        ],
+    });
+    const configKey = 'blocks-config.json';
+    const configObject = cdk.Lazy.any({
+        produce: () => Object.fromEntries(registry.entries),
+    });
+    const deployment = new s3deploy.BucketDeployment(scope, 'BlocksConfigDeployment', {
+        sources: [s3deploy.Source.jsonData(configKey, configObject)],
+        destinationBucket: configBucket,
+        prune: false,
+    });
+    handler.addEnvironment('BLOCKS_CONFIG_BUCKET', configBucket.bucketName);
+    handler.addEnvironment('BLOCKS_CONFIG_KEY', configKey);
+    // Scope IAM grant to the specific config key
+    handler.addToRolePolicy(new iam.PolicyStatement({
+        actions: ['s3:GetObject'],
+        resources: [`${configBucket.bucketArn}/${configKey}`],
+    }));
+}

package/dist/cdk/index.d.ts

@@ -0,0 +1,35 @@
+import * as cdk from 'aws-cdk-lib';
+import { Construct } from 'constructs';
+import { type BlocksStackProps, type BlocksStack as BaseBlocksStack, type ScopeParent, type ScopeOptions } from '../common/index.js';
+export { BlocksBackend, type BlocksBackendProps } from './blocks-backend.js';
+export { DEFAULT_NODE_RUNTIME } from './node-version.js';
+export { SandboxDisableDeletionProtection } from './mixins.js';
+export { registerConfig, finalizeConfigRegistry } from './config-registry.js';
+export { synthGuard } from './synth-guard.js';
+export type { ScopeOptions } from '../index.js';
+export { ApiError, isBlocksError } from '../errors.js';
+export declare class BlocksStack extends cdk.Stack implements BaseBlocksStack {
+    readonly id: string;
+    readonly apiUrl: string;
+    readonly gateway: cdk.aws_apigateway.RestApi;
+    readonly handler: cdk.aws_lambda_nodejs.NodejsFunction;
+    readonly backendHandlerPath: string;
+    private constructor();
+    static create(scope: Construct, id: string, props: BlocksStackProps): Promise<BlocksStack>;
+}
+export declare class Scope extends Construct {
+    readonly id: string;
+    readonly parent: ScopeParent;
+    readonly bbName?: string;
+    readonly bbVersion?: string;
+    constructor(id: string, options?: ScopeOptions);
+    get handler(): cdk.aws_lambda_nodejs.NodejsFunction;
+    get fullId(): string;
+    protected buildUserAgentChain(): [string, string][];
+    registerClientMiddleware(_packageSpecifier: string): void;
+    registerDevAttachment(_packageSpecifier: string): void;
+    registerLambdaEventHandler(_eventSource: string, _identifier: string, _handler: (record: any) => Promise<void>): void;
+    get clientMiddleware(): readonly string[];
+    get devAttachments(): readonly string[];
+}
+//# sourceMappingURL=index.d.ts.map

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

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