@aws-blocks/core 0.2.0 → 0.4.0

package/dist/scripts/secret.js

@@ -0,0 +1,29 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * `blocks secret` — manage a Blocks app's **secrets** (AWS Secrets Manager),
+ * pinned to the Blocks `/blocks/<stackId>/secrets` namespace (scoped to the app's
+ * stable `stackId` from `.blocks/config.json`, so two apps in one account never
+ * collide). Thin wrapper over the shared `@aws-blocks/hosting` CLI with the kind
+ * fixed to `secret`. The `config` counterpart is `./config.ts`.
+ *
+ * @module
+ */
+import { listValues, removeValue, runValueCli, setValue } from '@aws-blocks/hosting/scripts';
+import { blocksSecretPrefix } from '../secret-naming.js';
+/** Set (create or overwrite) a Blocks secret. */
+export function setSecret(key, value, opts = {}) {
+    return setValue('secret', key, value, { prefix: blocksSecretPrefix(), ...opts });
+}
+/** List Blocks secret keys (names only). */
+export function listSecrets(opts = {}) {
+    return listValues('secret', { prefix: blocksSecretPrefix(), ...opts });
+}
+/** Remove a Blocks secret. */
+export function removeSecret(key, opts = {}) {
+    return removeValue('secret', key, { prefix: blocksSecretPrefix(), ...opts });
+}
+/** CLI dispatcher for `blocks secret <set|list|remove> …`. */
+export function runSecretCli(argv) {
+    return runValueCli(argv, { kind: 'secret', prefix: blocksSecretPrefix(), label: 'blocks secret' });
+}

package/dist/scripts/secret.test.d.ts

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

package/dist/scripts/secret.test.d.ts.map

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

package/dist/scripts/secret.test.js

@@ -0,0 +1,28 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+import { runConfigCli } from './config.js';
+import { runSecretCli } from './secret.js';
+// argv parsing + validation only (no live SSM/Secrets Manager). The set/list/
+// remove SDK calls are exercised end-to-end during deploy verification.
+void describe('blocks secret / config CLI argv parsing', () => {
+    void it('rejects an unknown subcommand', async () => {
+        await assert.rejects(runSecretCli(['frobnicate']), /Unknown subcommand/);
+        await assert.rejects(runConfigCli(['frobnicate']), /Unknown subcommand/);
+    });
+    void it('requires a key for set (label reflects the kind)', async () => {
+        await assert.rejects(runSecretCli(['set']), /Usage: blocks secret set/);
+        await assert.rejects(runConfigCli(['set']), /Usage: blocks config set/);
+    });
+    void it('key-only set falls through to the hidden prompt (TTY error, not usage)', async () => {
+        await assert.rejects(runSecretCli(['set', 'ONLY_KEY']), /stdin is not a TTY/);
+    });
+    void it('requires a key for remove', async () => {
+        await assert.rejects(runSecretCli(['remove']), /Usage: blocks secret remove/);
+        await assert.rejects(runConfigCli(['remove']), /Usage: blocks config remove/);
+    });
+    void it('validates the key before any store call', async () => {
+        await assert.rejects(runSecretCli(['set', '1bad', 'value']), /Invalid key/);
+    });
+});

package/dist/scripts/typegen.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `blocks typegen` — generate the type-safe key augmentation for `getSecret` /
+ * `getConfig` in a Blocks app. Statically scans the app's `secret('...')` /
+ * `config('...')` calls (no execution, no AWS credentials) and writes a `.d.ts`
+ * that narrows the runtime getters to your declared keys (autocomplete + typo
+ * errors) with no call-site change.
+ *
+ * Thin pass-through to the `@aws-blocks/hosting` engine — the getters live on
+ * `@aws-blocks/hosting`, so the generated file augments that module by default;
+ * a Blocks app needs no extra configuration.
+ *
+ * @module
+ */
+export { runTypegenCli } from '@aws-blocks/hosting/scripts';
+//# sourceMappingURL=typegen.d.ts.map

package/dist/scripts/typegen.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"typegen.d.ts","sourceRoot":"","sources":["../../src/scripts/typegen.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC"}

package/dist/scripts/typegen.js

@@ -0,0 +1,16 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+/**
+ * `blocks typegen` — generate the type-safe key augmentation for `getSecret` /
+ * `getConfig` in a Blocks app. Statically scans the app's `secret('...')` /
+ * `config('...')` calls (no execution, no AWS credentials) and writes a `.d.ts`
+ * that narrows the runtime getters to your declared keys (autocomplete + typo
+ * errors) with no call-site change.
+ *
+ * Thin pass-through to the `@aws-blocks/hosting` engine — the getters live on
+ * `@aws-blocks/hosting`, so the generated file augments that module by default;
+ * a Blocks app needs no extra configuration.
+ *
+ * @module
+ */
+export { runTypegenCli } from '@aws-blocks/hosting/scripts';

package/dist/secret-naming.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Blocks-owned namespaces for hosting values.
+ *
+ * The mechanism (markers, resolvers, path/env naming) lives in the
+ * framework-neutral `@aws-blocks/hosting` package, which defaults to neutral
+ * `/hosting/secrets` and `/hosting/config` prefixes so a non-Blocks consumer
+ * never inherits Blocks branding.
+ *
+ * This module is the ONE place Blocks pins its own namespaces. The prefixes are
+ * **scoped to the app's stable `stackId`** (from the committed `.blocks/config.json`)
+ * — `/blocks/<stackId>/secrets` (Secrets Manager) and `/blocks/<stackId>/config`
+ * (SSM Parameter Store) — so two Blocks apps in one account/region never collide.
+ *
+ * Both sides derive the scope from the SAME source: the out-of-band CLI
+ * (`npm run secret`/`config`) and the CDK synth both call {@link blocksStoreConfig},
+ * which reads `stackId` via {@link getStackId}. When `.blocks/config.json` is absent
+ * (e.g. a bare unit test) both sides fall back to the unscoped `/blocks/secrets` /
+ * `/blocks/config` identically — so the CLI write and the deploy read can never
+ * diverge, whether the id is present or not. `stackId` is stage-independent
+ * (prod and sandbox share it); use the opt-in `stage` segment for per-stage values.
+ *
+ * @module
+ */
+import type { StoreConfig } from '@aws-blocks/hosting/constructs';
+/** Base Blocks prefix for `secret()` values (Secrets Manager); scoped by `stackId`. */
+export declare const BLOCKS_SECRET_PARAMETER_PREFIX = "/blocks/secrets";
+/** Base Blocks prefix for `config()` values (SSM Parameter Store); scoped by `stackId`. */
+export declare const BLOCKS_CONFIG_PARAMETER_PREFIX = "/blocks/config";
+/** The Blocks `secret()` prefix, scoped to `stackId` when available. */
+export declare function blocksSecretPrefix(stackId?: string): string;
+/** The Blocks `config()` prefix, scoped to `stackId` when available. */
+export declare function blocksConfigPrefix(stackId?: string): string;
+/**
+ * The **actual store name** of a Blocks `secret()` key in AWS Secrets Manager —
+ * routed through {@link secretStoreLocator} so it matches exactly what the CLI
+ * writes, the IAM grant scopes to, and the runtime resolver reads. Secrets Manager
+ * names are slash-free at the root, so this is `blocks/<stackId>/secrets/<KEY>`
+ * (no leading slash), NOT an SSM-style path. Pass `stackId` to compute it without
+ * reading `.blocks/config.json`.
+ *
+ * @example 'blocks/myapp/secrets/STRIPE_KEY'
+ */
+export declare function blocksSecretParameterName(key: string, stackId?: string): string;
+/**
+ * The **actual store name** of a Blocks `config()` key in SSM Parameter Store —
+ * routed through {@link secretStoreLocator} for consistency with the CLI/grant/
+ * runtime path. SSM keeps the leading-slash path.
+ *
+ * @example '/blocks/myapp/config/FEATURE_FLAGS'
+ */
+export declare function blocksConfigParameterName(key: string, stackId?: string): string;
+/**
+ * The Blocks store config passed to the shared hosting engine — `stackId`-scoped
+ * prefixes (falling back to the unscoped base when `.blocks/config.json` is absent).
+ * Both the CLI and the CDK synth call this, so they resolve identical names.
+ */
+export declare function blocksStoreConfig(stackId?: string): StoreConfig;
+//# sourceMappingURL=secret-naming.d.ts.map

package/dist/secret-naming.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"secret-naming.d.ts","sourceRoot":"","sources":["../src/secret-naming.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAEH,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gCAAgC,CAAC;AAIlE,uFAAuF;AACvF,eAAO,MAAM,8BAA8B,oBAAoB,CAAC;AAEhE,2FAA2F;AAC3F,eAAO,MAAM,8BAA8B,mBAAmB,CAAC;AAgB/D,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAG3D;AAED,wEAAwE;AACxE,wBAAgB,kBAAkB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAG3D;AAED;;;;;;;;;GASG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAC,GAAG,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,WAAW,CAK/D"}

package/dist/secret-naming.js

@@ -0,0 +1,67 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import { secretStoreLocator } from '@aws-blocks/hosting';
+import { getStackId } from './scripts/stack-id.js';
+/** Base Blocks prefix for `secret()` values (Secrets Manager); scoped by `stackId`. */
+export const BLOCKS_SECRET_PARAMETER_PREFIX = '/blocks/secrets';
+/** Base Blocks prefix for `config()` values (SSM Parameter Store); scoped by `stackId`. */
+export const BLOCKS_CONFIG_PARAMETER_PREFIX = '/blocks/config';
+/**
+ * Resolve the app's `stackId` (stable, stage-independent, from `.blocks/config.json`),
+ * or `undefined` when it can't be read. Never throws — a missing id means both the
+ * CLI and synth fall back to the unscoped base prefix, so they still agree.
+ */
+function resolveStackId(explicit) {
+    if (explicit)
+        return explicit;
+    try {
+        return getStackId();
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The Blocks `secret()` prefix, scoped to `stackId` when available. */
+export function blocksSecretPrefix(stackId) {
+    const id = resolveStackId(stackId);
+    return id ? `/blocks/${id}/secrets` : BLOCKS_SECRET_PARAMETER_PREFIX;
+}
+/** The Blocks `config()` prefix, scoped to `stackId` when available. */
+export function blocksConfigPrefix(stackId) {
+    const id = resolveStackId(stackId);
+    return id ? `/blocks/${id}/config` : BLOCKS_CONFIG_PARAMETER_PREFIX;
+}
+/**
+ * The **actual store name** of a Blocks `secret()` key in AWS Secrets Manager —
+ * routed through {@link secretStoreLocator} so it matches exactly what the CLI
+ * writes, the IAM grant scopes to, and the runtime resolver reads. Secrets Manager
+ * names are slash-free at the root, so this is `blocks/<stackId>/secrets/<KEY>`
+ * (no leading slash), NOT an SSM-style path. Pass `stackId` to compute it without
+ * reading `.blocks/config.json`.
+ *
+ * @example 'blocks/myapp/secrets/STRIPE_KEY'
+ */
+export function blocksSecretParameterName(key, stackId) {
+    return secretStoreLocator(key, { prefix: blocksSecretPrefix(stackId), store: 'secrets-manager' });
+}
+/**
+ * The **actual store name** of a Blocks `config()` key in SSM Parameter Store —
+ * routed through {@link secretStoreLocator} for consistency with the CLI/grant/
+ * runtime path. SSM keeps the leading-slash path.
+ *
+ * @example '/blocks/myapp/config/FEATURE_FLAGS'
+ */
+export function blocksConfigParameterName(key, stackId) {
+    return secretStoreLocator(key, { prefix: blocksConfigPrefix(stackId), store: 'ssm' });
+}
+/**
+ * The Blocks store config passed to the shared hosting engine — `stackId`-scoped
+ * prefixes (falling back to the unscoped base when `.blocks/config.json` is absent).
+ * Both the CLI and the CDK synth call this, so they resolve identical names.
+ */
+export function blocksStoreConfig(stackId) {
+    return {
+        secretStore: { prefix: blocksSecretPrefix(stackId) },
+        configStore: { prefix: blocksConfigPrefix(stackId) },
+    };
+}

package/dist/secret-naming.test.d.ts

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

package/dist/secret-naming.test.d.ts.map

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

package/dist/secret-naming.test.js

@@ -0,0 +1,40 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+import assert from 'node:assert';
+import { describe, it } from 'node:test';
+import { secretStoreLocator } from '@aws-blocks/hosting';
+import { BLOCKS_CONFIG_PARAMETER_PREFIX, BLOCKS_SECRET_PARAMETER_PREFIX, blocksConfigParameterName, blocksConfigPrefix, blocksSecretParameterName, blocksSecretPrefix, blocksStoreConfig, } from './secret-naming.js';
+// These run with no `.blocks/config.json` in cwd, so they exercise the UNSCOPED
+// fallback. A real Blocks app has the file, so it gets the `stackId`-scoped path
+// (covered by the explicit-stackId cases below).
+void describe('Blocks value namespaces — fallback (no .blocks/config.json)', () => {
+    void it('falls back to the unscoped /blocks/secrets and /blocks/config bases', () => {
+        assert.strictEqual(BLOCKS_SECRET_PARAMETER_PREFIX, '/blocks/secrets');
+        assert.strictEqual(BLOCKS_CONFIG_PARAMETER_PREFIX, '/blocks/config');
+        // Secrets Manager names are slash-free at the root; SSM keeps the leading slash.
+        assert.strictEqual(blocksSecretParameterName('STRIPE_KEY'), 'blocks/secrets/STRIPE_KEY');
+        assert.strictEqual(blocksConfigParameterName('FEATURE_FLAGS'), '/blocks/config/FEATURE_FLAGS');
+        assert.deepStrictEqual(blocksStoreConfig(), {
+            secretStore: { prefix: '/blocks/secrets' },
+            configStore: { prefix: '/blocks/config' },
+        });
+    });
+    void it('matches the store locator the CLI/grant/runtime actually use (no divergent name)', () => {
+        assert.strictEqual(blocksSecretParameterName('K'), secretStoreLocator('K', { prefix: BLOCKS_SECRET_PARAMETER_PREFIX, store: 'secrets-manager' }));
+        assert.strictEqual(blocksConfigParameterName('K'), secretStoreLocator('K', { prefix: BLOCKS_CONFIG_PARAMETER_PREFIX, store: 'ssm' }));
+    });
+});
+void describe('Blocks value namespaces — stackId-scoped (B5)', () => {
+    void it('scopes the prefix by stackId so two apps in one account never collide', () => {
+        assert.strictEqual(blocksSecretPrefix('myapp'), '/blocks/myapp/secrets');
+        assert.strictEqual(blocksConfigPrefix('myapp'), '/blocks/myapp/config');
+        assert.deepStrictEqual(blocksStoreConfig('myapp'), {
+            secretStore: { prefix: '/blocks/myapp/secrets' },
+            configStore: { prefix: '/blocks/myapp/config' },
+        });
+    });
+    void it('scoped store names match secretStoreLocator (SM slash-free, SSM leading-slash)', () => {
+        assert.strictEqual(blocksSecretParameterName('STRIPE_KEY', 'myapp'), 'blocks/myapp/secrets/STRIPE_KEY');
+        assert.strictEqual(blocksConfigParameterName('FEATURE_FLAGS', 'myapp'), '/blocks/myapp/config/FEATURE_FLAGS');
+    });
+});

package/dist/version.d.ts

@@ -1,2 +1,2 @@
-export declare const CORE_VERSION = "0.2.0";
+export declare const CORE_VERSION = "0.4.0";
 //# sourceMappingURL=version.d.ts.map

package/dist/version.js

@@ -1,2 +1,2 @@
 // Auto-generated by scripts/generate-version.mjs — do not edit manually
-export const CORE_VERSION = '0.2.0';
+export const CORE_VERSION = '0.4.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aws-blocks/core",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/aws-devtools-labs/aws-blocks.git",
@@ -52,6 +52,7 @@
       "require": "./dist/server/index.js"
     },
     "./scripts": "./dist/scripts/index.js",
+    "./scripts/generate-client-worker": "./dist/scripts/generate-client-worker.js",
     "./db-naming": {
       "types": "./dist/db-naming.d.ts",
       "default": "./dist/db-naming.js"
@@ -78,8 +79,10 @@
   "dependencies": {
     "@aws-blocks/hosting": "*",
     "@aws-blocks/pipeline": "*",
+    "@aws-sdk/client-cloudformation": "^3.700.0",
     "@aws-sdk/client-s3": "^3.700.0",
     "@aws-sdk/client-ssm": "^3.700.0",
+    "@aws-sdk/client-sts": "^3.700.0",
     "cross-spawn": "^7.0.6",
     "http-proxy": "^1.18.1"
   },

package/src/api.test.ts

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

package/src/api.ts

@@ -59,6 +59,42 @@ export const API_NAMESPACE_MARKER = Symbol.for('blocks:ApiNamespace');
 
 import type { ScopeParent } from './common/index.js';
 
+/**
+ * Structural view of a scope that resolves a compute carrying a recordable
+ * namespace list. Only the CDK `Scope` satisfies this at runtime (via its
+ * `compute` getter); in the mock/runtime bundles the property is absent.
+ */
+type ComputeResolvingScope = { compute?: { namespaces?: string[] } };
+
+/**
+ * Record this namespace on its resolved compute so request routing can later
+ * map a namespace to the compute that hosts it.
+ *
+ * CDK-synth concern only: in the CDK bundle `scope.compute` resolves to the
+ * namespace's compute (the stack default today), and we append the name to its
+ * `namespaces` list. In the mock/runtime bundles — or a scopeless test — the
+ * property is absent, so `scope.compute` is `undefined` and this is a silent
+ * no-op. The public `ApiNamespace` signature is unchanged; this is a purely
+ * internal side effect.
+ *
+ * No `try/catch`: `BlocksBackend.create()` initializes the default compute
+ * before it imports the backend module that constructs any `ApiNamespace`, so
+ * the `compute` getter always resolves at this call site. If it ever threw
+ * here it would signal a genuine lifecycle violation (an `ApiNamespace` built
+ * before `create()` resolved), which should surface rather than be swallowed.
+ */
+function recordNamespaceOnCompute(scope: ScopeParent | null | undefined, name: string): void {
+  // An API created without a Scope stays unrecorded and routes to the
+  // default compute.
+  if (!scope || typeof scope !== 'object') return;
+  const compute = (scope as ComputeResolvingScope).compute;
+  // Guard against duplicates so `namespaces` stays a set of names: a namespace
+  // could otherwise be recorded twice (e.g. a re-imported module during synth).
+  if (compute && Array.isArray(compute.namespaces) && !compute.namespaces.includes(name)) {
+    compute.namespaces.push(name);
+  }
+}
+
 /**
  * Define a type-safe API namespace that works seamlessly between frontend and backend.
  * 
@@ -157,6 +193,9 @@ export interface ApiNamespaceConstructor {
 export const ApiNamespace: ApiNamespaceConstructor = class ApiNamespace {
   constructor(scope: ScopeParent, name: string, handler: any) {
     handler[API_NAMESPACE_MARKER] = name;
+    // Record the namespace → compute association for per-compute routing.
+    // No-op outside CDK synth. Signature and returned handler are unchanged.
+    recordNamespaceOnCompute(scope, name);
     return handler;
   }
 } as any;

package/src/bb-utils.ts

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

package/src/cdk/apigateway-account.ts

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