@aws-blocks/core 0.2.0 → 0.4.0

package/src/lambda-handler.test.ts

@@ -3,10 +3,11 @@
 
 import { describe, it, beforeEach } from 'node:test';
 import assert from 'node:assert';
-import { createLambdaHandler, _resetCorsPatterns, requestCookies, isApiGatewayHttpEvent, computeHttpDeadlineMs, classifyEvent, buildEventUrl, isLoopbackForwardedHost } from './lambda-handler.js';
+import { createLambdaHandler, _resetCorsPatterns, requestCookies, isApiGatewayHttpEvent, computeHttpDeadlineMs, classifyEvent, buildEventUrl, isLoopbackForwardedHost, TransientConfigError } from './lambda-handler.js';
 import type { LambdaContext } from './lambda-handler.js';
 import { registerRoute, clearRouteRegistry } from './raw-route.js';
 import { decodeRpcResponse } from './rpc.js';
+import { _resetConfigCache, _setS3Fetcher } from './common/config.js';
 import type { BlocksContext } from './api.js';
 
 beforeEach(() => {
@@ -29,6 +30,145 @@ async function invoke(backend: any, event: any): Promise<any> {
   return handler(event) as any;
 }
 
+// ── init self-heal (retry on failed initialization) ─────────────────────────
+
+describe('createLambdaHandler — init self-heal', () => {
+  it('retries initialize() on a later request instead of caching a failed init', async () => {
+    let initCalls = 0;
+    const backend = {
+      api: (_ctx: BlocksContext) => ({
+        async echo(msg: string) {
+          return { msg };
+        },
+      }),
+    };
+    // Fail the first initialization (e.g. config not readable yet in the brief post-deploy
+    // window), then succeed. The SAME handler instance must recover — a cached rejected
+    // initPromise would poison the container and fail every subsequent request.
+    const backendFactory = async () => {
+      initCalls++;
+      if (initCalls === 1) throw new Error('transient init failure');
+      return backend;
+    };
+    const handler = createLambdaHandler(backendFactory);
+
+    // 1st request: init fails, so the handler rejects.
+    await assert.rejects(() => handler(makeEvent()) as any, /transient init failure/);
+
+    // 2nd request: init is retried and succeeds → 200 (not a re-thrown cached rejection).
+    const res = (await handler(makeEvent())) as any;
+    assert.strictEqual(res.statusCode, 200);
+    assert.strictEqual(initCalls, 2, 'initialize() must be retried on the next request, not cached');
+  });
+
+  it('recovers from a transient-empty (post-deploy 404) config load on the next request', async () => {
+    // Reproduces the poisoned-container bug: the first S3 load hits the transient
+    // post-deploy window (NoSuchKey), so config resolves empty; the handler must
+    // NOT lock in that empty config, and the NEXT request must re-fetch and pick
+    // up the now-present config.
+    _resetConfigCache();
+    process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
+    process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';
+    delete process.env.SELFHEAL_KEY;
+
+    let fetchCall = 0;
+    const notFound = new Error('The specified key does not exist.');
+    (notFound as any).name = 'NoSuchKey';
+    _setS3Fetcher(async () => {
+      fetchCall++;
+      if (fetchCall === 1) throw notFound; // config not readable yet
+      return JSON.stringify({ SELFHEAL_KEY: 'ready' });
+    });
+
+    let backendImports = 0;
+    const handler = createLambdaHandler(async () => {
+      backendImports++;
+      return {
+        api: (_ctx: BlocksContext) => ({
+          async echo(msg: string) { return { msg, cfg: process.env.SELFHEAL_KEY }; },
+        }),
+      };
+    });
+
+    try {
+      // 1st request: transient-empty load → initialize() throws TransientConfigError
+      // BEFORE importing the backend (so we never lock in empty config), and the
+      // request rejects.
+      await assert.rejects(() => handler(makeEvent()) as any, TransientConfigError);
+      assert.strictEqual(backendImports, 0, 'backend must NOT be imported while config is unresolved');
+
+      // 2nd request: config now present → initialize() re-runs, re-fetches, and
+      // injects the config into process.env before importing the backend.
+      const res = (await handler(makeEvent())) as any;
+      assert.strictEqual(res.statusCode, 200);
+      const body = JSON.parse(res.body);
+      assert.strictEqual(body.result.cfg, 'ready', 'now-present config was injected on the retry');
+      assert.strictEqual(backendImports, 1, 'backend imported exactly once, on the successful retry');
+      assert.strictEqual(fetchCall, 2, 'S3 was re-fetched on the retry (transient miss is not cached)');
+    } finally {
+      _resetConfigCache();
+      delete process.env.BLOCKS_CONFIG_BUCKET;
+      delete process.env.BLOCKS_CONFIG_KEY;
+      delete process.env.SELFHEAL_KEY;
+    }
+  });
+
+  it('does NOT re-init for a config-less app (no bucket, local dev) — initialize runs once', async () => {
+    _resetConfigCache();
+    delete process.env.BLOCKS_CONFIG_BUCKET;
+    delete process.env.BLOCKS_CONFIG_KEY;
+
+    let backendImports = 0;
+    const handler = createLambdaHandler(async () => {
+      backendImports++;
+      return { api: (_ctx: BlocksContext) => ({ async echo(msg: string) { return { msg }; } }) };
+    });
+
+    try {
+      const r1 = (await handler(makeEvent())) as any;
+      const r2 = (await handler(makeEvent())) as any;
+      assert.strictEqual(r1.statusCode, 200);
+      assert.strictEqual(r2.statusCode, 200);
+      assert.strictEqual(backendImports, 1, 'no re-init for a genuinely config-less (local dev) app');
+    } finally {
+      _resetConfigCache();
+    }
+  });
+
+  it('does NOT re-init or spin for a genuinely-empty ({}) S3 config', async () => {
+    // A real, readable empty config must be treated as resolved — distinct from
+    // the transient 404 miss — so the container does not throw/retry forever nor
+    // re-fetch S3 on every request.
+    _resetConfigCache();
+    process.env.BLOCKS_CONFIG_BUCKET = 'test-bucket';
+    process.env.BLOCKS_CONFIG_KEY = 'blocks-config.json';
+
+    let fetchCall = 0;
+    _setS3Fetcher(async () => { fetchCall++; return JSON.stringify({}); });
+
+    let backendImports = 0;
+    const handler = createLambdaHandler(async () => {
+      backendImports++;
+      return { api: (_ctx: BlocksContext) => ({ async echo(msg: string) { return { msg }; } }) };
+    });
+
+    try {
+      const r1 = (await handler(makeEvent())) as any;
+      const r2 = (await handler(makeEvent())) as any;
+      const r3 = (await handler(makeEvent())) as any;
+      assert.strictEqual(r1.statusCode, 200);
+      assert.strictEqual(r2.statusCode, 200);
+      assert.strictEqual(r3.statusCode, 200);
+      assert.strictEqual(backendImports, 1, 'genuinely-empty config resolves; no re-init');
+      assert.strictEqual(fetchCall, 1, 'S3 fetched once and cached — no per-request re-fetch spin');
+    } finally {
+      _resetConfigCache();
+      delete process.env.BLOCKS_CONFIG_BUCKET;
+      delete process.env.BLOCKS_CONFIG_KEY;
+    }
+  });
+});
+
 // ── RPC body tests ──────────────────────────────────────────────────────────
 
 describe('createLambdaHandler — RPC body handling', () => {
@@ -1072,3 +1212,77 @@ describe('createLambdaHandler — sandbox forwarded-host reaches the route', ()
     assert.strictEqual(capturedHost, 'abc123.execute-api.us-east-1.amazonaws.com');
   });
 });
+
+// ── SQS partial batch failure tests ─────────────────────────────────────────
+
+/**
+ * These pin the runtime half of the bb-async-job BatchSize fix: with a batch
+ * larger than 1, failing records must be reported individually via
+ * `batchItemFailures` so SQS retries only those messages. If this response
+ * shape regresses, every successful sibling message in a partially-failing
+ * batch would be redelivered (or, worse, the failures silently dropped).
+ */
+function makeSqsBatchEvent(count: number) {
+  return {
+    Records: Array.from({ length: count }, (_, i) => ({
+      eventSource: 'aws:sqs',
+      eventSourceARN: 'arn:aws:sqs:us-east-1:123456789012:my-queue',
+      messageId: `msg-${i}`,
+      body: JSON.stringify({ n: i }),
+    })),
+  };
+}
+
+describe('handleEventSourceRecords — SQS partial batch responses', () => {
+  it('reports only the failed records of a mixed-success 10-record batch', async () => {
+    const processed: number[] = [];
+    const handlers = new Map<string, (record: any) => Promise<void>>();
+    handlers.set('aws:sqs:my-queue', async (record: any) => {
+      const { n } = JSON.parse(record.body);
+      if (n % 3 === 0) throw new Error(`boom on ${n}`);
+      processed.push(n);
+    });
+    (globalThis as any).__BLOCKS_LAMBDA_EVENT_HANDLERS__ = handlers;
+
+    try {
+      const handler = createLambdaHandler(async () => ({}));
+      const result: any = await handler(makeSqsBatchEvent(10));
+
+      assert.deepStrictEqual(
+        result.batchItemFailures.map((f: any) => f.itemIdentifier).sort(),
+        ['msg-0', 'msg-3', 'msg-6', 'msg-9']
+      );
+      assert.deepStrictEqual(processed.sort((a, b) => a - b), [1, 2, 4, 5, 7, 8]);
+    } finally {
+      delete (globalThis as any).__BLOCKS_LAMBDA_EVENT_HANDLERS__;
+    }
+  });
+
+  it('returns no batchItemFailures when every record in the batch succeeds', async () => {
+    const handlers = new Map<string, (record: any) => Promise<void>>();
+    handlers.set('aws:sqs:my-queue', async () => {});
+    (globalThis as any).__BLOCKS_LAMBDA_EVENT_HANDLERS__ = handlers;
+
+    try {
+      const handler = createLambdaHandler(async () => ({}));
+      const result: any = await handler(makeSqsBatchEvent(10));
+      assert.deepStrictEqual(result, {});
+    } finally {
+      delete (globalThis as any).__BLOCKS_LAMBDA_EVENT_HANDLERS__;
+    }
+  });
+
+  it('reports all records when the whole batch fails (no silent drop)', async () => {
+    const handlers = new Map<string, (record: any) => Promise<void>>();
+    handlers.set('aws:sqs:my-queue', async () => { throw new Error('always'); });
+    (globalThis as any).__BLOCKS_LAMBDA_EVENT_HANDLERS__ = handlers;
+
+    try {
+      const handler = createLambdaHandler(async () => ({}));
+      const result: any = await handler(makeSqsBatchEvent(10));
+      assert.strictEqual(result.batchItemFailures.length, 10);
+    } finally {
+      delete (globalThis as any).__BLOCKS_LAMBDA_EVENT_HANDLERS__;
+    }
+  });
+});

package/src/lambda-handler.ts

@@ -7,7 +7,7 @@ import { ApiError } from './errors.js';
 import { BLOCKS_RPC_PREFIX } from './constants.js';
 import { matchRoute, lockRouteRegistry } from './raw-route.js';
 import { registerBuiltinRoutes } from './builtin-routes.js';
-import { loadConfigToProcessEnv } from './common/config.js';
+import { loadConfigToProcessEnv, isConfigResolved } from './common/config.js';
 import {
   parseRpcRequest,
   successResponse,
@@ -297,6 +297,26 @@ export function createLambdaHandler(backendFactory: () => Promise<any>) {
   async function initialize() {
     await loadConfigToProcessEnv();
 
+    // If the app has config coordinates (BLOCKS_CONFIG_BUCKET/KEY set) but the
+    // load didn't actually resolve the config, we're in the transient post-deploy
+    // S3 window where blocks-config.json isn't readable yet. loadConfigFromS3()
+    // deliberately does NOT cache that empty result, so throw a typed transient
+    // error here — BEFORE importing the backend — so the createLambdaHandler()
+    // catch resets initPromise and the next request re-runs initialize(), which
+    // re-fetches from S3 and picks up the now-present config. Without this throw,
+    // initialize() would succeed with empty config, `handler` would be assigned,
+    // and the `if (!handler)` guard below would never fire again, poisoning the
+    // container for its whole life (it would import the backend against empty
+    // process.env and serve "not configured" 500s forever).
+    //
+    // A genuinely config-less app does NOT throw: the no-bucket local-dev path
+    // and a real empty `{}` config both cache their result, so isConfigResolved()
+    // is true and the retry never spins. Once the blob is readable the successful
+    // load caches, so there is no unbounded per-request S3 re-fetch either.
+    if (process.env.BLOCKS_CONFIG_BUCKET && process.env.BLOCKS_CONFIG_KEY && !isConfigResolved()) {
+      throw new TransientConfigError();
+    }
+
     // Merge hosting-provided CORS origins into the main env var so the lazy
     // getCorsPatterns() sees a combined value on first access.
     // loadConfigToProcessEnv() won't override CORS_ALLOWED_ORIGINS if it's
@@ -318,7 +338,18 @@ export function createLambdaHandler(backendFactory: () => Promise<any>) {
 
   return async (event: any, context?: LambdaContext) => {
     if (!handler) {
-      if (!initPromise) initPromise = initialize();
+      // Retry init on failure instead of caching the rejection. If initialize() throws (most often
+      // because loadConfigToProcessEnv() couldn't read blocks-config.json during the brief
+      // post-deploy window before it's readable), a memoized rejected promise would poison this
+      // container for its whole lifetime — every later request re-awaits the same rejection and 500s.
+      // Resetting initPromise lets the next invocation re-run initialize() (config.ts re-fetches,
+      // since it doesn't cache failures), so the handler self-heals once config is available.
+      if (!initPromise) {
+        initPromise = initialize().catch((err) => {
+          initPromise = null;
+          throw err;
+        });
+      }
       await initPromise;
     }
 
@@ -390,6 +421,27 @@ class HandlerTimeoutError extends Error {
   }
 }
 
+/**
+ * Thrown by `initialize()` when the app has config coordinates
+ * (BLOCKS_CONFIG_BUCKET/KEY) but the S3 config load resolved empty because
+ * blocks-config.json wasn't readable yet — the transient window right after a
+ * deploy, before the BucketDeployment settles.
+ *
+ * It flows through the `createLambdaHandler()` init catch, which resets
+ * `initPromise` so the NEXT request re-runs `initialize()` and picks up the
+ * now-present config (config.ts does not cache a not-found result, so the retry
+ * re-fetches). A distinct type keeps the recovery path greppable and testable
+ * and separates it from real init failures, which surface with their own error.
+ *
+ * @internal Exported for testing only.
+ */
+export class TransientConfigError extends Error {
+  constructor() {
+    super('[Blocks] Config not readable yet (transient post-deploy S3 window); will retry on next request');
+    this.name = 'TransientConfigError';
+  }
+}
+
 /**
  * Extract the request path from a Lambda event, normalizing between
  * API Gateway v1 (REST) and v2 (HTTP API) event shapes.

package/src/pipeline/index.ts

@@ -1,16 +1,69 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
 
-export {
-  Pipeline,
-  DeployStage,
-  __PIPELINE_STAGE_SCOPE__,
+import { __PIPELINE_STAGE_SCOPE__, DeployStage, Pipeline as LeafPipeline } from '@aws-blocks/pipeline';
+import type {
+	BranchConfig,
+	DeployStageProps,
+	PipelineProps,
+	PipelineSourceConfig,
+	PipelineStageConfig,
+	PipelineSynthConfig,
 } from '@aws-blocks/pipeline';
+import type { Construct } from 'constructs';
+import { blocksStoreConfig } from '../secret-naming.js';
+
+export { __PIPELINE_STAGE_SCOPE__, DeployStage };
 export type {
-  DeployStageProps,
-  BranchConfig,
-  PipelineProps,
-  PipelineSourceConfig,
-  PipelineSynthConfig,
-  PipelineStageConfig,
-} from '@aws-blocks/pipeline';
+	BranchConfig,
+	DeployStageProps,
+	PipelineProps,
+	PipelineSourceConfig,
+	PipelineStageConfig,
+	PipelineSynthConfig,
+};
+
+/**
+ * Merge the Blocks `/blocks/*` namespace as the DEFAULT store config, so a
+ * Blocks pipeline resolves `connectionArn` / `buildSecrets` from the same place
+ * the Blocks CLI (`npm run secret` / `npm run config`) writes. Per-kind and
+ * shallow: any field the caller sets (a custom `prefix`, a `stage`, a
+ * `cacheTtlSeconds`) wins over the Blocks default.
+ */
+function withBlocksDefaults<TConfig>(props: PipelineProps<TConfig>): PipelineProps<TConfig> {
+	const blocks = blocksStoreConfig();
+	return {
+		...props,
+		secretStore: { ...blocks.secretStore, ...props.secretStore },
+		configStore: { ...blocks.configStore, ...props.configStore },
+	};
+}
+
+/**
+ * Blocks `Pipeline` — the framework-neutral `@aws-blocks/pipeline` construct with
+ * the Blocks value namespace pinned. It defaults `secretStore` / `configStore` to
+ * `/blocks/secrets` and `/blocks/config` (the prefixes the Blocks `secret` /
+ * `config` CLIs write), mirroring how the Blocks `Hosting` block pins the same
+ * namespace — so a value set with `npm run secret`/`config` is the value the
+ * pipeline reads. Pass `secretStore` / `configStore` to override.
+ *
+ * @see {@link https://github.com/aws-devtools-labs/aws-blocks/blob/main/packages/pipeline/README.md}
+ */
+export class Pipeline<TConfig = Record<string, unknown>> extends LeafPipeline<TConfig> {
+	constructor(scope: Construct, id: string, props: PipelineProps<TConfig>) {
+		super(scope, id, withBlocksDefaults(props));
+	}
+
+	/**
+	 * Async constructor — required when `source.connectionArn` is a `config()`
+	 * marker (resolved at synth time). Pins the Blocks namespace, then delegates to
+	 * the leaf {@link LeafPipeline.create}.
+	 */
+	static async create<TConfig = Record<string, unknown>>(
+		scope: Construct,
+		id: string,
+		props: PipelineProps<TConfig>,
+	): Promise<LeafPipeline<TConfig>> {
+		return LeafPipeline.create(scope, id, withBlocksDefaults(props));
+	}
+}

package/src/pipeline.test.ts

@@ -0,0 +1,55 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+import assert from 'node:assert';
+import { afterEach, describe, it } from 'node:test';
+import { _setSynthSecretFetcher } from '@aws-blocks/hosting/constructs';
+import { config } from '@aws-blocks/hosting';
+import type * as cdk from 'aws-cdk-lib';
+import { App, Stack } from 'aws-cdk-lib';
+import { Pipeline } from './pipeline/index.js';
+import type { PipelineStageConfig } from './pipeline/index.js';
+
+const MOCK_CONNECTION_ARN = 'arn:aws:codeconnections:us-east-1:123456789012:connection/test-connection-id';
+
+function minimalStageFactory(scope: cdk.Stage, stageConfig: PipelineStageConfig): void {
+	new Stack(scope, 'AppStack', { env: stageConfig.env });
+}
+
+// B2: the core Pipeline wrapper must resolve values from the SAME namespace the
+// Blocks CLI writes (`/blocks/*`), not the leaf-neutral `/hosting/*` — otherwise
+// `npm run config -- set CONNECTION_ARN` writes one name and the deploy reads
+// another. The leaf default is `/hosting/config`; the wrapper must pin `/blocks/config`.
+void describe('core Pipeline pins the Blocks namespace', () => {
+	afterEach(() => _setSynthSecretFetcher(null));
+
+	void it('resolves a config() connectionArn under /blocks/config by default', async () => {
+		const seen: string[] = [];
+		_setSynthSecretFetcher(async (locator: string) => {
+			seen.push(locator);
+			return MOCK_CONNECTION_ARN;
+		});
+		await Pipeline.create(new App(), 'BlocksPipeline', {
+			source: { repo: 'my-org/my-app', connectionArn: config('CONNECTION_ARN') },
+			branches: [{ branch: 'main', stages: [{ name: 'prod' }] }],
+			stageFactory: minimalStageFactory,
+		});
+		// The Blocks CLI writes /blocks/config/CONNECTION_ARN; the wrapper must read it there.
+		assert.deepStrictEqual(seen, ['/blocks/config/CONNECTION_ARN']);
+	});
+
+	void it('lets the caller override the pinned prefix', async () => {
+		const seen: string[] = [];
+		_setSynthSecretFetcher(async (locator: string) => {
+			seen.push(locator);
+			return MOCK_CONNECTION_ARN;
+		});
+		await Pipeline.create(new App(), 'OverridePipeline', {
+			source: { repo: 'my-org/my-app', connectionArn: config('CONNECTION_ARN') },
+			branches: [{ branch: 'main', stages: [{ name: 'prod' }] }],
+			stageFactory: minimalStageFactory,
+			configStore: { prefix: '/myapp/config' },
+		});
+		assert.deepStrictEqual(seen, ['/myapp/config/CONNECTION_ARN']);
+	});
+});

package/src/rpc.test.ts

@@ -3,7 +3,7 @@
 
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
-import { decodeRpcResponse, errorResponseFromCatch, parseRpcRequest, RpcErrorCode } from './rpc.js';
+import { decodeRpcResponse, errorResponseFromCatch, parseRpcRequest, RpcErrorCode, MAX_RPC_BODY_BYTES } from './rpc.js';
 import { ApiError, isBlocksError } from './errors.js';
 
 describe('-32600 Invalid Request error shape', () => {
@@ -188,3 +188,46 @@ describe('ApiError status ↔ JSON-RPC error code', () => {
     );
   });
 });
+
+describe('request body size limit', () => {
+  it('accepts a normal-sized body', () => {
+    const result = parseRpcRequest(JSON.stringify({ jsonrpc: '2.0', method: 'ns.method', params: [], id: 1 }));
+    assert.strictEqual(result.ok, true);
+  });
+
+  it('rejects a body larger than MAX_RPC_BODY_BYTES with a PayloadTooLarge error', () => {
+    // A JSON string just over the limit (a single huge param value).
+    const huge = 'x'.repeat(MAX_RPC_BODY_BYTES + 1);
+    const body = JSON.stringify({ jsonrpc: '2.0', method: 'ns.method', params: [huge], id: 1 });
+    assert.ok(Buffer.byteLength(body, 'utf8') > MAX_RPC_BODY_BYTES);
+
+    const result = parseRpcRequest(body);
+    assert.strictEqual(result.ok, false);
+    if (result.ok) return; // narrow
+    const parsed = JSON.parse(result.response);
+    // Positive HTTP status (413), not a reserved -32xxx — so decodeRpcResponse
+    // surfaces it to the client as ApiError.status === 413.
+    assert.strictEqual(parsed.error.code, 413);
+    assert.strictEqual(parsed.error.data?.name, 'PayloadTooLarge');
+    assert.match(parsed.error.message, /exceeds/);
+    assert.match(parsed.error.message, /10 MiB/); // human-readable size crosses the wire
+
+    // Client round-trip: decodeRpcResponse surfaces it as ApiError.status 413
+    // (not 500), so consumer `e.status === 413` handling works.
+    assert.throws(
+      () => decodeRpcResponse(parsed),
+      (e: unknown) => e instanceof ApiError && e.status === 413 && isBlocksError(e, 'PayloadTooLarge'),
+    );
+  });
+
+  it('rejects an oversized body before attempting to parse it (invalid JSON still 413s, not a ParseError)', () => {
+    // Oversized AND not valid JSON — the size guard must win, proving the body
+    // is rejected before the (expensive) parse + before any handler/DB touch.
+    const oversizedGarbage = 'x'.repeat(MAX_RPC_BODY_BYTES + 1);
+    const result = parseRpcRequest(oversizedGarbage);
+    assert.strictEqual(result.ok, false);
+    if (result.ok) return;
+    const parsed = JSON.parse(result.response);
+    assert.strictEqual(parsed.error.data?.name, 'PayloadTooLarge');
+  });
+});

package/src/rpc.ts

@@ -32,6 +32,28 @@ export type RpcParseResult =
 
 const VERSION = '2.0' as const;
 
+/**
+ * Maximum accepted request-body size, in bytes (10 MiB).
+ *
+ * Matches the payload limit API Gateway enforces in production (~10 MB for a
+ * REST API). In prod an oversized body is rejected by API Gateway at the edge —
+ * before the Lambda is invoked — so this guard's rejection path effectively
+ * runs on the dev/mock server, where there is no edge to stop it: an oversized
+ * body would otherwise buffer and wedge the local database (e.g. PGlite). By
+ * enforcing the *same* limit locally, the dev server rejects the same oversized
+ * body prod would 413 at the edge, instead of failing only in one environment.
+ * Enforced in `parseRpcRequest`, the single choke point both the Lambda handler
+ * and the dev server route through.
+ *
+ * Note: this value is the Lambda + API Gateway limit. It lives here (in the
+ * compute-agnostic parser) because Lambda is the only compute path today. When
+ * a non-API-Gateway compute (e.g. container/ALB) is introduced, this should
+ * become compute-aware — sourced from / overridden by the compute layer (via
+ * the Compute `setEnv` config hook) rather than a fixed constant in `core` —
+ * since an ALB has a different payload limit. Tracked with the multi-compute work.
+ */
+export const MAX_RPC_BODY_BYTES = 10 * 1024 * 1024;
+
 /** Reserved JSON-RPC error codes. */
 export const RpcErrorCode = {
   ParseError:     -32700,
@@ -89,6 +111,25 @@ export function decodeRpcResponse(body: unknown): unknown {
  * anything about the JSON-RPC spec.
  */
 export function parseRpcRequest(bodyText: string): RpcParseResult {
+  // Reject oversized bodies before parsing or dispatch. See MAX_RPC_BODY_BYTES
+  // for the limit and its rationale.
+  if (Buffer.byteLength(bodyText, 'utf8') > MAX_RPC_BODY_BYTES) {
+    // Emit the real HTTP status (413) as the error code, not a reserved -32xxx:
+    // `decodeRpcResponse` maps a positive code straight to `ApiError.status`
+    // (reserved codes collapse to 500), mirroring the 504 handler-timeout path,
+    // so a caller's `e.status === 413` works. `name` (which crosses the wire,
+    // not the code) lets callers match with `isBlocksError(e, 'PayloadTooLarge')`.
+    return {
+      ok: false,
+      response: errorResponse(
+        413,
+        `Request body exceeds the ${MAX_RPC_BODY_BYTES} byte (${MAX_RPC_BODY_BYTES / (1024 * 1024)} MiB) limit`,
+        null,
+        { name: 'PayloadTooLarge' },
+      ),
+    };
+  }
+
   let parsed: any;
   try {
     parsed = JSON.parse(bodyText || '{}');

package/src/scripts/config.ts

@@ -0,0 +1,35 @@
+// Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * `blocks config` — manage a Blocks app's non-sensitive **config** values (SSM
+ * Parameter Store), pinned to the Blocks `/blocks/<stackId>/config` namespace
+ * (scoped to the app's stable `stackId` from `.blocks/config.json`). Thin wrapper
+ * over the shared `@aws-blocks/hosting` CLI with the kind fixed to `config`. The
+ * `secret` counterpart is `./secret.ts`.
+ *
+ * @module
+ */
+
+import { listValues, removeValue, runValueCli, setValue } from '@aws-blocks/hosting/scripts';
+import { blocksConfigPrefix } from '../secret-naming.js';
+
+/** Set (create or overwrite) a Blocks config value. */
+export function setConfig(key: string, value: string, opts: { stage?: string } = {}): Promise<void> {
+	return setValue('config', key, value, { prefix: blocksConfigPrefix(), ...opts });
+}
+
+/** List Blocks config keys (names only). */
+export function listConfig(opts: { stage?: string } = {}): Promise<string[]> {
+	return listValues('config', { prefix: blocksConfigPrefix(), ...opts });
+}
+
+/** Remove a Blocks config value. */
+export function removeConfig(key: string, opts: { stage?: string } = {}): Promise<boolean> {
+	return removeValue('config', key, { prefix: blocksConfigPrefix(), ...opts });
+}
+
+/** CLI dispatcher for `blocks config <set|list|remove> …`. */
+export function runConfigCli(argv: string[]): Promise<void> {
+	return runValueCli(argv, { kind: 'config', prefix: blocksConfigPrefix(), label: 'blocks config' });
+}

package/src/scripts/deploy.ts

@@ -6,6 +6,7 @@ import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
 import { join, resolve, dirname } from 'node:path';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { ensureSecrets, loadProductionEnv } from './ensure-secrets.js';
+import { assertAwsCredentials } from './preflight-credentials.js';
 import { applyExternalMigrations } from './external-migrations-step.js';
 import { trackCommand } from '../telemetry/trackCommand.js';
 import { getCdkTelemetryEnv } from './cdk-telemetry-env.js';
@@ -25,6 +26,10 @@ export async function deploy(options: DeployOptions) {
 
     process.env.BLOCKS_STAGE = 'production';
 
+    // Fail fast if AWS credentials are missing/expired, before generating the
+    // client and spending time in synth only to hit an opaque CDK credential error.
+    await assertAwsCredentials('deploy');
+
     // Provision secrets for production. projectRoot must match the root cdk
     // synth uses (passed as --context below) so the written parameter name
     // equals the one the app resolves at synth.