@aws-blocks/core 0.1.12 → 0.1.17

package/dist/hosting.test.js

@@ -1134,4 +1134,77 @@ describe('Hosting', () => {
                 `found DependsOn=${JSON.stringify(dependsOn)}`);
         });
     });
+    describe('config.json stale-placeholder guard (#173)', () => {
+        // Helper: pull every BucketDeployment custom resource's Properties.
+        const bucketDeployments = (stack) => {
+            const crs = Template.fromStack(stack).findResources('Custom::CDKBucketDeployment');
+            return Object.values(crs).map((cr) => cr.Properties);
+        };
+        it('uploads the placeholder config.json with a no-cache directive, never the 1-year mutable cache-control', () => {
+            // The build-time placeholder (`{_placeholder:true}`) is written into the
+            // static dir. If it inherits the mutable asset tier's
+            // `s-maxage=31536000` and an edge caches it during the deploy window, the
+            // edge serves the placeholder for up to a year — breaking every client
+            // API call. It must instead be uploaded as a no-cache path so the edge
+            // never caches it long-term.
+            createSpaBuildOutput(tmpDir);
+            const app = new App();
+            const stack = new Stack(app, 'PlaceholderCacheStack');
+            new Hosting(stack, 'Hosting', { root: tmpDir, api: MOCK_API });
+            const deployments = bucketDeployments(stack);
+            const cc = (p) => p.SystemMetadata?.['cache-control'];
+            const includes = (p) => p.Include ?? [];
+            const excludes = (p) => p.Exclude ?? [];
+            // A deployment must upload `.blocks-sandbox/config.json` with the
+            // no-cache directive (this is the placeholder upload).
+            const noCacheDeploy = deployments.find((p) => includes(p).includes('.blocks-sandbox/config.json') &&
+                cc(p) === 'no-cache, no-store, must-revalidate');
+            assert.ok(noCacheDeploy, 'placeholder .blocks-sandbox/config.json must be uploaded with ' +
+                '"no-cache, no-store, must-revalidate"');
+            // No deployment may cover the placeholder with the 1-year mutable
+            // cache-control: the mutable/other tier must EXCLUDE it.
+            const leaks = deployments.filter((p) => {
+                const directive = cc(p);
+                return (typeof directive === 'string' &&
+                    directive.includes('s-maxage=31536000') &&
+                    !excludes(p).includes('.blocks-sandbox/config.json'));
+            });
+            assert.strictEqual(leaks.length, 0, 'no mutable-tier deployment may apply s-maxage=31536000 to ' +
+                '.blocks-sandbox/config.json');
+        });
+        it('registers the placeholder as a no-cache path even for a static-only site (no api)', () => {
+            // The placeholder is always written (step 5), so its no-cache
+            // registration must not depend on `props.api`. This guards against a
+            // regression that moves the registration inside an `if (props.api)`
+            // block, which would reopen the stale-placeholder window for
+            // static-only sites.
+            createSpaBuildOutput(tmpDir);
+            const app = new App();
+            const stack = new Stack(app, 'StaticOnlyPlaceholderStack');
+            new Hosting(stack, 'Hosting', { root: tmpDir });
+            Template.fromStack(stack).hasResourceProperties('Custom::CDKBucketDeployment', Match.objectLike({
+                Include: Match.arrayWith(['.blocks-sandbox/config.json']),
+                SystemMetadata: Match.objectLike({
+                    'cache-control': 'no-cache, no-store, must-revalidate',
+                }),
+            }));
+        });
+        it('invalidates the post-rewrite cache key (/builds/<id>/.blocks-sandbox/*)', () => {
+            // The viewer-request skew-protection function rewrites the URI to
+            // `/builds/<buildId>/.blocks-sandbox/config.json` BEFORE the cache
+            // lookup, so the real edge cache key lives under `/builds/<id>/`.
+            // Invalidating only `/.blocks-sandbox/*` never matches it.
+            createSpaBuildOutput(tmpDir);
+            const app = new App();
+            const stack = new Stack(app, 'InvalidationPathStack');
+            new Hosting(stack, 'Hosting', { root: tmpDir, api: MOCK_API });
+            // Assert via Template + Match so a CDK property rename fails loudly here
+            // rather than silently skipping a structural-heuristic lookup.
+            Template.fromStack(stack).hasResourceProperties('Custom::CDKBucketDeployment', Match.objectLike({
+                DistributionPaths: Match.arrayWith([
+                    Match.stringLikeRegexp('^/builds/.+/\\.blocks-sandbox/\\*$'),
+                ]),
+            }));
+        });
+    });
 });

package/dist/lambda-handler.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"lambda-handler.d.ts","sourceRoot":"","sources":["../src/lambda-handler.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAerD,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAElE;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,2BAAkC,CAAC;AAG9D;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;CAErB,CAAC;AAoDX;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAWlF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,GAAG,GAAG,GAAG,CAwD7C;AAiBD;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAErE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,GAAG,GAAG,UAAU,CAWpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAEzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAIrE;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,wBAAwB,IAAI,MAAM,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,IA0BtD,OAAO,GAAG,EAAE,UAAU,aAAa,kBAkElD"}
+{"version":3,"file":"lambda-handler.d.ts","sourceRoot":"","sources":["../src/lambda-handler.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,iBAAiB,EAAE,MAAM,kBAAkB,CAAC;AAerD,OAAO,EAAE,iBAAiB,EAAE,kBAAkB,EAAE,MAAM,WAAW,CAAC;AAElE;;;;;;;;GAQG;AACH,eAAO,MAAM,cAAc,2BAAkC,CAAC;AAG9D;;;GAGG;AACH,eAAO,MAAM,kBAAkB;;CAErB,CAAC;AAqCX;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAC,aAAa,EAAE,MAAM,GAAG,SAAS,GAAG,OAAO,CAWlF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,GAAG,GAAG,GAAG,CAwD7C;AAiBD;;;;;;;GAOG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,WAAW,GAAG,SAAS,GAAG,QAAQ,CAAC;AAErE;;;;;;;;;;;;;GAaG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,GAAG,GAAG,UAAU,CAWpD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,GAAG,GAAG,OAAO,CAEzD;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,CAAC,EAAE,aAAa,GAAG,MAAM,CAIrE;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,wBAAwB,IAAI,MAAM,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,mBAAmB,CAAC,cAAc,EAAE,MAAM,OAAO,CAAC,GAAG,CAAC,IA0BtD,OAAO,GAAG,EAAE,UAAU,aAAa,kBAiElD"}

package/dist/lambda-handler.js

@@ -8,7 +8,7 @@ import { matchRoute, lockRouteRegistry } from './raw-route.js';
 import { registerBuiltinRoutes } from './builtin-routes.js';
 import { loadConfigToProcessEnv } from './common/config.js';
 import { parseRpcRequest, successResponse, errorResponse, errorResponseFromCatch, methodNotFoundResponse, } from './rpc.js';
-import { getCorsPatterns, isOriginAllowed, corsRejection } from './cors.js';
+import { getCorsPatterns, isOriginAllowed, corsRejection, buildCorsHeaders, CORS_MAX_AGE } from './cors.js';
 export { parseCorsPatterns, _resetCorsPatterns } from './cors.js';
 /**
  * AsyncLocalStorage that carries the inbound HTTP request cookies through
@@ -28,18 +28,6 @@ globalThis.__BLOCKS_REQUEST_COOKIES_STORE__ = requestCookies;
 export const EventSourceMapping = {
     SQS: 'aws:sqs',
 };
-// ── CORS helpers (private to handler) ───────────────────────────────────────
-function buildCorsHeaders(origin) {
-    const headers = {};
-    if (isOriginAllowed(origin)) {
-        headers['Access-Control-Allow-Origin'] = origin;
-        headers['Access-Control-Allow-Credentials'] = 'true';
-    }
-    else if (origin) {
-        console.warn(`[CORS] Origin "${origin}" is not allowed. Set the CORS_ALLOWED_ORIGINS environment variable to allow this origin. Example: CORS_ALLOWED_ORIGINS=https://myapp\\.com,^https?://(localhost|127\\.0\\.0\\.1)(:\\d+)?$`);
-    }
-    return headers;
-}
 // ── Helpers ─────────────────────────────────────────────────────────────────
 /**
  * Decode the Lambda event body and return both the raw string and a ReadableStream.
@@ -330,7 +318,7 @@ export function createLambdaHandler(backendFactory) {
                 // Timeout won the race — build a 504 response. Format depends on
                 // whether the request targeted an RPC endpoint (structured JSON-RPC
                 // error envelope) or a plain HTTP path (simple error JSON).
-                const origin = event.headers?.origin || event.headers?.Origin || '*';
+                const origin = event.headers?.origin || event.headers?.Origin || '';
                 const requestPath = getRequestPath(event);
                 const isRpcPath = requestPath === BLOCKS_RPC_PREFIX || requestPath.startsWith(BLOCKS_RPC_PREFIX + '/');
                 const body = isRpcPath
@@ -340,8 +328,7 @@ export function createLambdaHandler(backendFactory) {
                     statusCode: 504,
                     headers: {
                         'Content-Type': 'application/json',
-                        'Access-Control-Allow-Origin': origin,
-                        'Access-Control-Allow-Credentials': 'true',
+                        ...buildCorsHeaders(origin),
                     },
                     body,
                 };
@@ -414,7 +401,7 @@ function createHandler(backend) {
                     ...corsHeaders,
                     'Access-Control-Allow-Methods': 'GET, POST, PUT, DELETE, PATCH, HEAD, OPTIONS',
                     'Access-Control-Allow-Headers': 'Content-Type, Authorization',
-                    'Access-Control-Max-Age': '86400',
+                    'Access-Control-Max-Age': CORS_MAX_AGE,
                 },
                 body: '',
             };

package/dist/lambda-handler.test.js

@@ -2,7 +2,7 @@
 // SPDX-License-Identifier: Apache-2.0
 import { describe, it, beforeEach } from 'node:test';
 import assert from 'node:assert';
-import { createLambdaHandler, requestCookies, isApiGatewayHttpEvent, computeHttpDeadlineMs, classifyEvent, buildEventUrl, isLoopbackForwardedHost } from './lambda-handler.js';
+import { createLambdaHandler, _resetCorsPatterns, requestCookies, isApiGatewayHttpEvent, computeHttpDeadlineMs, classifyEvent, buildEventUrl, isLoopbackForwardedHost } from './lambda-handler.js';
 import { registerRoute, clearRouteRegistry } from './raw-route.js';
 import { decodeRpcResponse } from './rpc.js';
 beforeEach(() => {
@@ -499,7 +499,7 @@ describe('createLambdaHandler — timeout guard for API Gateway events', () => {
         assert.strictEqual(body.jsonrpc, '2.0');
         assert.strictEqual(body.error.code, 504);
     });
-    it('504 response includes CORS headers from event origin', async () => {
+    it('504 response includes CORS headers for an allowed origin', async () => {
         const backend = {
             api: () => ({
                 async echo() {
@@ -508,6 +508,9 @@ describe('createLambdaHandler — timeout guard for API Gateway events', () => {
                 },
             }),
         };
+        process.env.CORS_ALLOWED_ORIGINS = 'https://myapp\\.example\\.com';
+        delete process.env.CORS_HOSTING_ORIGINS;
+        _resetCorsPatterns();
         const event = makeEvent({
             headers: {
                 'Content-Type': 'application/json',
@@ -519,6 +522,60 @@ describe('createLambdaHandler — timeout guard for API Gateway events', () => {
         assert.strictEqual(result.statusCode, 504);
         assert.strictEqual(result.headers['Access-Control-Allow-Origin'], 'https://myapp.example.com');
         assert.strictEqual(result.headers['Access-Control-Allow-Credentials'], 'true');
+        delete process.env.CORS_ALLOWED_ORIGINS;
+        _resetCorsPatterns();
+    });
+    it('504 response omits CORS headers when no allowlist is configured', async () => {
+        const backend = {
+            api: () => ({
+                async echo() {
+                    await new Promise(resolve => setTimeout(resolve, 5_000));
+                    return {};
+                },
+            }),
+        };
+        delete process.env.CORS_ALLOWED_ORIGINS;
+        delete process.env.CORS_HOSTING_ORIGINS;
+        _resetCorsPatterns();
+        const event = makeEvent({
+            headers: {
+                'Content-Type': 'application/json',
+                origin: 'https://evil.example.com',
+            },
+        });
+        const ctx = makeLambdaContext(50);
+        const result = await invokeWithContext(backend, event, ctx);
+        assert.strictEqual(result.statusCode, 504);
+        assert.strictEqual(result.headers['Access-Control-Allow-Origin'], undefined);
+        assert.strictEqual(result.headers['Access-Control-Allow-Credentials'], undefined);
+        delete process.env.CORS_ALLOWED_ORIGINS;
+        _resetCorsPatterns();
+    });
+    it('disallowed origin with a configured allowlist is rejected with 403 before the timeout path', async () => {
+        const backend = {
+            api: () => ({
+                async echo() {
+                    await new Promise(resolve => setTimeout(resolve, 5_000));
+                    return {};
+                },
+            }),
+        };
+        process.env.CORS_ALLOWED_ORIGINS = 'https://myapp\\.example\\.com';
+        delete process.env.CORS_HOSTING_ORIGINS;
+        _resetCorsPatterns();
+        const event = makeEvent({
+            headers: {
+                'Content-Type': 'application/json',
+                origin: 'https://evil.example.com',
+            },
+        });
+        const ctx = makeLambdaContext(50);
+        const result = await invokeWithContext(backend, event, ctx);
+        assert.strictEqual(result.statusCode, 403);
+        assert.strictEqual(result.headers['Access-Control-Allow-Origin'], undefined);
+        assert.strictEqual(result.headers['Access-Control-Allow-Credentials'], undefined);
+        delete process.env.CORS_ALLOWED_ORIGINS;
+        _resetCorsPatterns();
     });
 });
 describe('createLambdaHandler — async events bypass timeout guard', () => {

package/dist/redact.d.ts

@@ -44,8 +44,9 @@ export declare const REDACTED: "[REDACTED]";
 export declare function redactForLogging(value: unknown, seen?: WeakSet<object>): unknown;
 /**
  * Convenience for log call sites: redact `value` and serialize it to a JSON
- * string. Returns a safe placeholder instead of throwing if serialization
- * fails (e.g. a BigInt slips through), so logging can never crash a request.
+ * string. Returns `'undefined'` when JSON serialization produces no output,
+ * or a safe placeholder if serialization throws (e.g. a BigInt slips through),
+ * so logging can never crash a request.
  */
 export declare function redactToJson(value: unknown): string;
 //# sourceMappingURL=redact.d.ts.map

package/dist/redact.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,sDAAsD;AACtD,eAAO,MAAM,QAAQ,EAAG,YAAqB,CAAC;AAwC9C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,GAAE,OAAO,CAAC,MAAM,CAAiB,GAAG,OAAO,CA2C/F;AAED;;;;GAIG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAMnD"}
+{"version":3,"file":"redact.d.ts","sourceRoot":"","sources":["../src/redact.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AAEH,sDAAsD;AACtD,eAAO,MAAM,QAAQ,EAAG,YAAqB,CAAC;AAwC9C;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,OAAO,EAAE,IAAI,GAAE,OAAO,CAAC,MAAM,CAAiB,GAAG,OAAO,CA2C/F;AAED;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAMnD"}

package/dist/redact.js

@@ -121,12 +121,13 @@ export function redactForLogging(value, seen = new WeakSet()) {
 }
 /**
  * Convenience for log call sites: redact `value` and serialize it to a JSON
- * string. Returns a safe placeholder instead of throwing if serialization
- * fails (e.g. a BigInt slips through), so logging can never crash a request.
+ * string. Returns `'undefined'` when JSON serialization produces no output,
+ * or a safe placeholder if serialization throws (e.g. a BigInt slips through),
+ * so logging can never crash a request.
  */
 export function redactToJson(value) {
     try {
-        return JSON.stringify(redactForLogging(value));
+        return JSON.stringify(redactForLogging(value)) ?? 'undefined';
     }
     catch {
         return '[unserializable]';

package/dist/redact.test.js

@@ -179,6 +179,15 @@ describe('redactToJson', () => {
         // BigInt is not JSON-serializable and survives redaction (not a sensitive key).
         assert.equal(redactToJson({ big: 10n }), '[unserializable]');
     });
+    it('returns a string for undefined', () => {
+        assert.equal(redactToJson(undefined), 'undefined');
+    });
+    it('returns a string for function values', () => {
+        assert.equal(redactToJson(() => { }), 'undefined');
+    });
+    it('returns a string for symbol values', () => {
+        assert.equal(redactToJson(Symbol('x')), 'undefined');
+    });
     it('does not leak secrets even when truncation would apply downstream', () => {
         const json = redactToJson([{ action: 'signIn', username: 'u', password: 'p'.repeat(50) }]);
         assert.ok(!json.includes('pppp'));

package/dist/rpc.test.js

@@ -2,7 +2,8 @@
 // SPDX-License-Identifier: Apache-2.0
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
-import { parseRpcRequest, RpcErrorCode } from './rpc.js';
+import { decodeRpcResponse, errorResponseFromCatch, parseRpcRequest, RpcErrorCode } from './rpc.js';
+import { ApiError, isBlocksError } from './errors.js';
 describe('-32600 Invalid Request error shape', () => {
     it('returns proper JSON-RPC 2.0 envelope with error code', () => {
         const result = parseRpcRequest(JSON.stringify({ method: 'ns.method', id: 1 }));
@@ -58,3 +59,78 @@ describe('-32600 Invalid Request error shape', () => {
         }
     });
 });
+describe('params decoding', () => {
+    it('uses an array of params as positional args', () => {
+        const result = parseRpcRequest(JSON.stringify({ jsonrpc: '2.0', method: 'api.greet', params: ['World', 42], id: 1 }));
+        assert.strictEqual(result.ok, true);
+        if (result.ok) {
+            assert.deepStrictEqual(result.request.args, ['World', 42]);
+            assert.strictEqual(result.request.apiNamespace, 'api');
+            assert.strictEqual(result.request.method, 'greet');
+        }
+    });
+    it('flattens an object of named params in key order', () => {
+        const result = parseRpcRequest(JSON.stringify({ jsonrpc: '2.0', method: 'api.greet', params: { name: 'World', times: 42 }, id: 1 }));
+        assert.strictEqual(result.ok, true);
+        if (result.ok)
+            assert.deepStrictEqual(result.request.args, ['World', 42]);
+    });
+    it('yields no args when params is omitted', () => {
+        const result = parseRpcRequest(JSON.stringify({ jsonrpc: '2.0', method: 'api.ping', id: 7 }));
+        assert.strictEqual(result.ok, true);
+        if (result.ok)
+            assert.deepStrictEqual(result.request.args, []);
+    });
+});
+describe('batch requests (top-level JSON array body)', () => {
+    it('rejects an array body as Invalid Request with a null id', () => {
+        const result = parseRpcRequest(JSON.stringify([
+            { jsonrpc: '2.0', method: 'api.greet', params: ['a'], id: 1 },
+            { jsonrpc: '2.0', method: 'api.greet', params: ['b'], id: 2 },
+        ]));
+        assert.strictEqual(result.ok, false);
+        if (!result.ok) {
+            const parsed = JSON.parse(result.response);
+            assert.strictEqual(parsed.error.code, RpcErrorCode.InvalidRequest);
+            assert.strictEqual(parsed.error.data.name, 'InvalidRequest');
+            assert.strictEqual(parsed.id, null);
+        }
+    });
+    it('reports a parse error for a body that is not JSON at all', () => {
+        const result = parseRpcRequest('{oops');
+        assert.strictEqual(result.ok, false);
+        if (!result.ok) {
+            const parsed = JSON.parse(result.response);
+            assert.strictEqual(parsed.error.code, RpcErrorCode.ParseError);
+            assert.strictEqual(parsed.id, null);
+        }
+    });
+});
+describe('ApiError status ↔ JSON-RPC error code', () => {
+    it('encodes the HTTP status as the error code, with name and retriable in data', () => {
+        const encoded = errorResponseFromCatch(new ApiError('Username already taken', 409, { name: 'ConditionalCheckFailedException', retriable: true }), 1);
+        const parsed = JSON.parse(encoded);
+        assert.strictEqual(parsed.error.code, 409);
+        assert.strictEqual(parsed.error.message, 'Username already taken');
+        assert.strictEqual(parsed.error.data.name, 'ConditionalCheckFailedException');
+        assert.strictEqual(parsed.error.data.retriable, true);
+    });
+    it('encodes a non-ApiError throw as code 500 with no data.name', () => {
+        const parsed = JSON.parse(errorResponseFromCatch(new Error('plain'), 2));
+        assert.strictEqual(parsed.error.code, 500);
+        assert.strictEqual(parsed.error.data, undefined);
+    });
+    it('round-trips status, name and retriable back into an ApiError on the client', () => {
+        const wire = JSON.parse(errorResponseFromCatch(new ApiError('Username already taken', 409, { name: 'ConditionalCheckFailedException', retriable: true }), 1));
+        assert.throws(() => decodeRpcResponse(wire), (e) => {
+            assert.ok(e instanceof ApiError);
+            assert.strictEqual(e.status, 409);
+            assert.strictEqual(e.retriable, true);
+            assert.ok(isBlocksError(e, 'ConditionalCheckFailedException'));
+            return true;
+        });
+    });
+    it('decodes reserved -32xxx codes as status 500', () => {
+        assert.throws(() => decodeRpcResponse({ jsonrpc: '2.0', error: { code: RpcErrorCode.InvalidRequest, message: 'Invalid Request' }, id: null }), (e) => e instanceof ApiError && e.status === 500);
+    });
+});

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

@@ -1 +1 @@
-{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../../src/scripts/console.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED,wBAAsB,WAAW,CAAC,OAAO,EAAE,cAAc,iBAqBxD"}
+{"version":3,"file":"console.d.ts","sourceRoot":"","sources":["../../src/scripts/console.ts"],"names":[],"mappings":"AAOA,MAAM,WAAW,cAAc;IAC7B,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AA6BD,wBAAsB,WAAW,CAAC,OAAO,EAAE,cAAc,iBAqBxD"}

package/dist/scripts/console.js

@@ -3,6 +3,34 @@
 import { execFileSync } from 'node:child_process';
 import { readFileSync } from 'node:fs';
 import { trackCommand } from '../telemetry/trackCommand.js';
+function resolveRegion() {
+    const fromEnv = process.env.AWS_REGION || process.env.AWS_DEFAULT_REGION;
+    if (fromEnv)
+        return fromEnv;
+    try {
+        const fromConfig = execFileSync('aws', ['configure', 'get', 'region'], { encoding: 'utf-8' }).trim();
+        if (fromConfig)
+            return fromConfig;
+    }
+    catch {
+        // aws CLI not configured — fall through to default.
+    }
+    return 'us-east-1';
+}
+/** Launch the URL in the default browser. Best-effort: no opener (headless/CI) is not a failure. */
+function openInBrowser(url) {
+    const opener = process.platform === 'darwin' ? 'open' :
+        process.platform === 'win32' ? 'cmd' :
+            'xdg-open';
+    const args = process.platform === 'win32' ? ['/c', 'start', '', url] : [url];
+    try {
+        execFileSync(opener, args, { stdio: 'ignore' });
+    }
+    catch {
+        // Headless environment (CI, remote shell) — the URL is already printed above.
+        console.log('(Could not launch a browser automatically — open the URL above manually.)');
+    }
+}
 export async function openConsole(options) {
     return trackCommand('console', async () => {
         let stackName;
@@ -16,10 +44,10 @@ export async function openConsole(options) {
         else {
             throw new Error('Must provide either stackId or outputsFile');
         }
-        const region = execFileSync('aws', ['configure', 'get', 'region'], { encoding: 'utf-8' }).trim() || 'us-east-1';
+        const region = resolveRegion();
         const stackUrl = `https://${region}.console.aws.amazon.com/cloudformation/home?region=${region}#/stacks?filteringText=${encodeURIComponent(stackName)}`;
         console.log('Opening AWS Console...');
         console.log(stackUrl);
-        execFileSync('open', [stackUrl], { stdio: 'inherit' });
+        openInBrowser(stackUrl);
     });
 }

package/dist/scripts/deploy-stream.d.ts

@@ -0,0 +1,181 @@
+/** What to do with a signal that arrives while a deploy is in flight. */
+export type DeploySignalAction = 'defer' | 'abort';
+export interface DeploySignalResponse {
+    action: DeploySignalAction;
+    /** Operator-facing line explaining what happened and how to force an abort. */
+    message: string;
+    /**
+     * True when this signal is a duplicate delivery of one the operator already
+     * sent (see {@link SIGNAL_COALESCE_MS}), so the caller can skip logging it
+     * twice.
+     */
+    coalesced?: boolean;
+}
+/** Signals whose delivery we take over while a deploy is in flight. */
+export declare const DEPLOY_SIGNALS: readonly NodeJS.Signals[];
+/** Default gap (ms) of silence after which the runner prints a progress heartbeat. */
+export declare const DEFAULT_HEARTBEAT_MS = 30000;
+/** Grace (ms) given to the child tree to exit after an operator-requested abort. */
+export declare const ABORT_GRACE_MS = 10000;
+/**
+ * Grace (ms) we wait after the child exits for its stdout/stderr pipes to end,
+ * so the last CloudFormation lines are relayed before we resolve. Bounded
+ * because a lingering grandchild could hold the pipe open forever; losing a
+ * trailing line is strictly better than hanging a finished deploy.
+ */
+export declare const STREAM_FLUSH_GRACE_MS = 2000;
+/**
+ * Window (ms) in which repeated SIGTERMs count as ONE operator request.
+ *
+ * A single external signal reaches this process more than once. `npm run deploy`
+ * runs `npm -> sh -> tsx -> node`, so a process-group SIGTERM is delivered to
+ * the node process directly AND relayed to it a second time by `tsx`, which
+ * forwards SIGTERM/SIGINT to its child. Measured on a real deploy: one
+ * `kill -TERM -<pgid>` produced two SIGTERMs about 50ms apart. Without this
+ * window the second delivery is read as "the operator insisted" and the deploy
+ * is abandoned, which is the exact failure this module exists to prevent.
+ *
+ * 2s is far longer than a delivery burst (tens of ms) and far shorter than a
+ * deliberate repeat (a human running `kill` twice, or a supervisor's
+ * SIGTERM-then-escalate cycle), so both intents stay distinguishable.
+ */
+export declare const SIGNAL_COALESCE_MS = 2000;
+/**
+ * Decide how to answer a signal that arrives while CloudFormation is still
+ * converging. This is the whole "decouple the CLI lifecycle from the in-flight
+ * deploy" policy, kept pure so it can be asserted directly.
+ *
+ * - `SIGHUP` → always `defer`. A hangup means the terminal or parent shell went
+ *   away (a backgrounded `npm run deploy &`, a closed SSH session). The deploy
+ *   is server-side work that is already paid for; killing the CLI here is what
+ *   produced the phantom failures, so we keep streaming instead. Duplicate
+ *   deliveries inside {@link SIGNAL_COALESCE_MS} are coalesced so one hangup
+ *   logs one line, not one per delivery.
+ * - `SIGTERM` → `defer` the first time. A lone SIGTERM is almost always
+ *   process-group collateral (a harness reaping the parent shell, a supervisor
+ *   tidying up) rather than a deliberate "stop the deploy", so it only warns.
+ *   Repeats inside {@link SIGNAL_COALESCE_MS} are duplicate *deliveries* of that
+ *   same signal (the group delivers it, then `tsx` relays it) and are coalesced
+ *   into the first. A SIGTERM after that window is a deliberate repeat and
+ *   aborts. A SIGKILL follow-up (`docker stop`, most CI cancels) is uncatchable
+ *   and still ends the process immediately, so this cannot wedge a shutdown.
+ * - `SIGINT` → always `abort`. Ctrl-C is unambiguous, interactive intent, so it
+ *   stays responsive on the first press.
+ *
+ * @param signal - the signal received.
+ * @param msSinceFirstDeferral - ms since the first deferral of *this* signal, or
+ *   `null` when this signal has not been deferred yet. Each signal is tracked
+ *   separately, so a deferred SIGHUP never consumes the SIGTERM abort budget
+ *   (and a repeated SIGHUP is deduped the same way a repeated SIGTERM is).
+ * @param coalesceWindowMs - see {@link SIGNAL_COALESCE_MS}.
+ */
+export declare function decideSignalResponse(signal: NodeJS.Signals, msSinceFirstDeferral: number | null, coalesceWindowMs?: number): DeploySignalResponse;
+/**
+ * Split a byte stream into whole lines across chunk boundaries.
+ *
+ * The child's output arrives in arbitrary chunks, so a naive
+ * `chunk.toString().split('\n')` emits torn lines (and drops the tail). This
+ * keeps the partial trailing line buffered until it completes; {@link flush}
+ * returns whatever is left when the stream ends (CDK's final line has no
+ * trailing newline).
+ */
+export declare function createLineAssembler(): {
+    push(chunk: string): string[];
+    flush(): string[];
+};
+/** Human-readable elapsed time (`45s`, `4m 05s`) for progress lines. */
+export declare function formatElapsed(ms: number): string;
+export interface CdkDeployArgsOptions {
+    /** Project root passed to synth as `--context projectRoot=…`. */
+    projectRoot: string;
+    /** Path (relative to the project root) CDK writes stack outputs to. */
+    outputsFile: string;
+}
+/**
+ * Build the `cdk deploy` argv used by `npm run deploy`.
+ *
+ * Two of these flags exist purely so the deploy is observable — losing either
+ * one brings back the 0-byte stdout:
+ *
+ * - `--ci`: the CDK CLI picks its log stream as `isCI ? stdout : stderr`, so
+ *   without it every CloudFormation event goes to **stderr** and a caller
+ *   capturing stdout (`npm run deploy > deploy.log`) sees nothing for the whole
+ *   multi-minute deploy. With it, progress goes to stdout and only error-level
+ *   messages stay on stderr.
+ * - `--progress events`: print one line per resource transition instead of the
+ *   redrawing progress bar. The bar needs a TTY, which a piped/backgrounded
+ *   deploy does not have, and a half-rendered bar is not a usable progress
+ *   signal in a log file.
+ */
+export declare function buildCdkDeployArgs({ projectRoot, outputsFile }: CdkDeployArgsOptions): string[];
+/** Minimal sink surface so tests can capture the relayed streams. */
+export interface OutputSink {
+    write(chunk: string): unknown;
+}
+/** Minimal signal-registration surface ({@link process} satisfies it). */
+export interface SignalRegistry {
+    on(signal: NodeJS.Signals, handler: () => void): unknown;
+    off(signal: NodeJS.Signals, handler: () => void): unknown;
+}
+export interface RunStreamingOptions {
+    cwd?: string;
+    env?: NodeJS.ProcessEnv;
+    /** Prefix used by the runner's own progress/status lines. Defaults to `deploy`. */
+    label?: string;
+    /** Idle gap before a heartbeat line is printed. `0` disables heartbeats. */
+    heartbeatMs?: number;
+    /** Where child stdout and runner progress lines go. Defaults to `process.stdout`. */
+    stdout?: OutputSink;
+    /** Where child stderr goes. Defaults to `process.stderr`. */
+    stderr?: OutputSink;
+    /** Injected for tests. */
+    now?: () => number;
+    /** Injected for tests: signal registration seam. */
+    signalTarget?: SignalRegistry;
+}
+/** Raised when the child exits non-zero, is killed, or the operator aborts. */
+export declare class DeployProcessError extends Error {
+    readonly exitCode: number | null;
+    readonly signal: NodeJS.Signals | null;
+    readonly aborted: boolean;
+    constructor(message: string, details?: {
+        exitCode?: number | null;
+        signal?: NodeJS.Signals | null;
+        aborted?: boolean;
+    });
+}
+/**
+ * Run a long deployment command, relaying its output line by line as it happens
+ * and keeping it alive across a stray SIGTERM/SIGHUP.
+ *
+ * Behaviour that matters to callers:
+ * - **Streamed, non-empty stdout.** Child stdout is relayed to `stdout` the
+ *   moment a line completes (never buffered until exit) and child stderr to
+ *   `stderr`, so `npm run deploy | tee` shows CloudFormation progress live.
+ * - **Idle heartbeat.** While the child is silent for `heartbeatMs`, a
+ *   `still deploying` line with elapsed time is written to `stdout`, so a
+ *   ten-minute RDS resource never looks like a hung process.
+ * - **Own process group (POSIX only).** The child is spawned `detached` on
+ *   POSIX, so a process-group signal aimed at the parent shell
+ *   (`kill -TERM -pgid`, a harness reaping a backgrounded job) cannot kill the
+ *   CDK CLI behind our back; this runner is the only thing that signals it.
+ *   Windows has neither process groups nor OS-delivered SIGTERM/SIGHUP, so the
+ *   signal resilience below does not apply there — a `taskkill` on the tree ends
+ *   the deploy, and the abort path reaps by pid via `terminateProcessTree`.
+ * - **No stdin.** The child gets `ignore` for stdin so a backgrounded deploy
+ *   can never be stopped by SIGTTIN trying to read a terminal it no longer
+ *   owns; the caller must keep passing `--require-approval never`.
+ * - **Signal policy (POSIX).** See {@link decideSignalResponse}: a deferred
+ *   signal only logs (which itself doubles as a progress signal on stdout),
+ *   while an abort reaps the child tree and throws a {@link DeployProcessError}
+ *   with `aborted: true`. Repeat deliveries of the same signal inside
+ *   {@link SIGNAL_COALESCE_MS} log once, not once per delivery.
+ * - **Streams stay separated.** Child stdout and child stderr are relayed to
+ *   their own sinks and never merged, so a deploy failure reason (which the CDK
+ *   CLI keeps on stderr even under `--ci`) stays on stderr while progress is on
+ *   stdout.
+ *
+ * Resolves when the child exits 0; otherwise throws {@link DeployProcessError}.
+ */
+export declare function runStreaming(command: string, args: string[], options?: RunStreamingOptions): Promise<void>;
+//# sourceMappingURL=deploy-stream.d.ts.map

package/dist/scripts/deploy-stream.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"deploy-stream.d.ts","sourceRoot":"","sources":["../../src/scripts/deploy-stream.ts"],"names":[],"mappings":"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"}