@aws-blocks/core 0.1.13 → 0.1.17

package/README.md

@@ -63,7 +63,7 @@ The typed `import { api } from 'aws-blocks'` client is the normal path. The HTTP
 
 `POST` to the RPC path `/aws-blocks/api`:
 
-- Local dev: `http://localhost:3001/aws-blocks/api`
+- Local dev: `http://localhost:3000/aws-blocks/api` (the default template serves the backend and frontend from a single front door on `:3000`). Only the `backend` and `amplify` templates serve the API on `:3001`.
 - Deployed: the API Gateway stage URL + `/aws-blocks/api`
 
 The body is JSON-RPC 2.0:
@@ -79,15 +79,70 @@ The body is JSON-RPC 2.0:
 Working example:
 
 ```bash
-curl -X POST http://localhost:3001/aws-blocks/api \
+curl -X POST http://localhost:3000/aws-blocks/api \
   -H 'Content-Type: application/json' \
   -d '{"jsonrpc":"2.0","method":"api.greet","params":["World"],"id":1}'
 # → {"jsonrpc":"2.0","result":{"message":"Hello, World!"},"id":1}
 ```
 
-### ApiError / isBlocksError
+#### How the server reads `params` (and what it rejects)
 
-Typed error handling across the wire.
+The request body is parsed by `parseRpcRequest`, which turns `params` into the positional argument list your method is called with:
+
+| Body `params` | Arguments the method receives |
+|---|---|
+| `["World", 42]` (array) | `('World', 42)`, used as-is |
+| `{"name":"World","times":42}` (object) | `('World', 42)` via `Object.values()`, so **key insertion order decides argument order** |
+| omitted or `null` | `()`, no arguments |
+
+A named object is convenient for `curl`, but it is only safe when the keys are written in the same order as the method signature. Prefer the array form in anything automated.
+
+One shape that looks reasonable and is **not** supported: a top-level JSON **array** as the whole body (a JSON-RPC batch). The parser reads `jsonrpc` and `method` off the body object, so an array body fails validation instead of running anything:
+
+```bash
+curl -X POST http://localhost:3000/aws-blocks/api \
+  -H 'Content-Type: application/json' \
+  -d '[{"jsonrpc":"2.0","method":"api.greet","params":["a"],"id":1}]'
+# → HTTP 200
+# {"jsonrpc":"2.0","error":{"code":-32600,"message":"Invalid Request: expected JSON-RPC 2.0 — ...",
+#    "data":{"name":"InvalidRequest"}},"id":null}
+```
+
+`id` is `null` in that response because an array body has no `id` to echo. Send one call per request. Body that isn't valid JSON at all returns `-32700 Parse error`, also with HTTP `200`.
+
+#### Runtime config (`/.blocks-sandbox/config.json`)
+
+The generated client does not hardcode the API URL; it resolves one at first call, in this order:
+
+1. `BLOCKS_API_URL` env var (set by the Hosting construct on SSR compute).
+2. `BLOCKS_CONFIG` env var (the whole config as JSON).
+3. Node only: the file `.blocks-sandbox/config.json`, read from the **process working directory**.
+4. Browser only: `fetch('/.blocks-sandbox/config.json')`.
+
+Both env vars are normally written for you: `Hosting` injects them into every SSR compute function at synth, and `npm run sandbox` sets `BLOCKS_API_URL` on the dev server it spawns. You set `BLOCKS_API_URL` yourself only when you run the SSR host outside that tooling, like a framework dev server on its own port (`BLOCKS_API_URL=http://localhost:3001/aws-blocks/api next dev`) or your own container. `BLOCKS_CONFIG` is Hosting's serialized `backendConfig` rather than a knob to hand-write, so prefer `BLOCKS_API_URL` for a custom host.
+
+Two things about that path burn time when debugging:
+
+- The directory is **dotted**: `/.blocks-sandbox/config.json`. `/config.json` is not a route and never was: locally the dev server only answers `GET /.blocks-sandbox/config.json`, and in production the Hosting construct only adds a `/.blocks-sandbox/*` static behaviour. A `404` from `curl http://localhost:3000/config.json` says nothing about your config.
+- `{"_placeholder":true}` is a **valid, expected** body in the frontend build output. The Hosting construct writes that stub into the static assets directory during CDK synth so the file exists as a static route while the real `apiUrl` is still an unresolved CloudFormation token; the deploy then uploads the resolved config over it. Finding the stub in `dist/.blocks-sandbox/config.json` (or on the origin between synth and deploy) is the design working, not a broken config.
+
+What you should see instead, per environment:
+
+```bash
+# Local dev / sandbox: served by the dev server itself, Cache-Control: no-store
+curl http://localhost:3000/.blocks-sandbox/config.json
+# → {"apiUrl":"http://localhost:3000/aws-blocks/api","environment":"local"}
+
+# After a deploy: written by the deploy script and uploaded to the origin
+cat .blocks-sandbox/config.json
+# → { "apiUrl": "https://<id>.execute-api.<region>.amazonaws.com/prod/aws-blocks/api", "environment": "production" }
+```
+
+So a real config problem looks like the client throwing `Blocks API URL not configured` (or `... is not configured (source: ...)`), not like a `404` on `/config.json`. If a **deployed** origin keeps serving `{"_placeholder":true}` after a successful deploy, that is a genuine bug: the config upload or the CloudFront invalidation did not land.
+
+### ApiError / isBlocksError / hasAuthError
+
+Typed error handling across the wire. All three are exported from `@aws-blocks/core`, and re-exported from `@aws-blocks/blocks`.
 
 ```typescript
 import { ApiError, isBlocksError } from '@aws-blocks/core';
@@ -101,32 +156,140 @@ catch (e) {
 }
 ```
 
+#### `new ApiError(message, status, options?)`
+
+```typescript
+new ApiError(
+  message: string,
+  status: number,
+  options?: { name?: string; cause?: unknown; retriable?: boolean },
+)
+```
+
+| Argument | Required | What it does |
+|---|---|---|
+| `message` | yes | Human-facing text. Crosses the wire, so don't put internals in it. |
+| `status` | yes | HTTP status code. Any number; nothing validates it against a known status. |
+| `options.name` | no | The structured error name `isBlocksError` / `hasAuthError` match on (e.g. `'ItemNotFoundException'`). Defaults to `'ApiError'`, which carries no meaning, so treat it as "unnamed". |
+| `options.cause` | no | Underlying error. **Stays server-side**, never serialized. |
+| `options.retriable` | no | `true` when the caller can retry the same action without restarting the flow (wrong MFA code, wrong password on re-prompt). Defaults to `false`. |
+
+The instance exposes `message`, `name`, `status` and `retriable` as readable properties, and it is a real `Error`, so `instanceof Error` and stack traces behave normally.
+
+How `status` reaches the client over JSON-RPC: an uncaught error inside an RPC method is encoded as an error response whose **`code` is the `ApiError`'s `status`** (positive numbers can't collide with the reserved `-32xxx` range). `name` and `retriable` ride along in `error.data`. A non-`ApiError` throw becomes code `500` with no `data.name`.
+
+```jsonc
+// throw new ApiError('Username already taken', 409,
+//   { name: 'ConditionalCheckFailedException', retriable: true })
+{ "jsonrpc": "2.0", "id": 1, "error": {
+  "code": 409,
+  "message": "Username already taken",
+  "data": { "name": "ConditionalCheckFailedException", "retriable": true }
+}}
+```
+
+The client decodes that back into an `ApiError` with the same `status`, `name` and `retriable`, which is why the same `isBlocksError(e, ...)` check works on both sides. Reserved JSON-RPC codes (`-32600`, `-32700`, …) decode to `status: 500`.
+
+#### `hasAuthError(state, name)`
+
+```typescript
+import { hasAuthError } from '@aws-blocks/core';
+
+function hasAuthError<T extends { errorName?: string }, N extends string>(
+  state: T | null | undefined,
+  name: N,
+): state is T & { errorName: N }
+```
+
+The auth blocks' recommended client path (`setAuthState()` / `getAuthState()`) **returns** a failed `AuthState` instead of throwing, so there is no `Error` for `isBlocksError` to inspect. `hasAuthError` is the equivalent guard for that returned object: it compares `state.errorName` to `name` and narrows the type. It's a plain equality check, so a `null` / `undefined` state and a state with no `errorName` both return `false` and no defensive wrapping is needed.
+
+```typescript
+const next = await authApi.setAuthState({ action: 'signIn', username, password });
+if (hasAuthError(next, AuthBasicErrors.InvalidCredentials)) {
+  // unknown user or wrong password → offer sign-up
+}
+```
+
+Rule of thumb: **thrown error → `isBlocksError`; returned `AuthState` → `hasAuthError`.** Match on the block's error constant, never on the human-facing `error` string.
+
 ### RawRoute
 
-Path-based HTTP routing Building Block for endpoints that need full request/response control — webhooks, REST APIs, health checks, file downloads. Use `ApiNamespace` (RPC) for typed function calls; use `RawRoute` when you need raw HTTP semantics.
+Path-based HTTP routing Building Block for endpoints that need full request/response control: webhooks, health checks, redirects, file downloads, anything a browser or third party has to hit with a plain `GET`. Use `ApiNamespace` (RPC) for typed function calls; use `RawRoute` when you need raw HTTP semantics.
+
+```typescript
+new RawRoute(scope: ScopeParent, id: string, options: {
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE' | 'PATCH' | 'HEAD' | 'OPTIONS';
+  path?: string;
+  handler: (context: BlocksContext) => Promise<void>;
+})
+```
+
+A full `GET` that sets its own status, content type and body:
 
 ```typescript
 import { RawRoute } from '@aws-blocks/blocks';
 
-// Explicit path
-new RawRoute(scope, 'GetUser', {
+new RawRoute(scope, 'status', {
   method: 'GET',
-  path: '/users/{id}',
-  handler: async (context) => {
-    const userId = context.request.params.id;
-    context.response.send({ id: userId });
+  path: '/status',
+  handler: async (ctx) => {
+    ctx.response.status = 200;
+    ctx.response.headers.set('Content-Type', 'text/html; charset=utf-8');
+    ctx.response.send('<h1>ok</h1>');
   },
 });
+```
 
-// Derived path — path omitted, becomes /health from scope chain
-new RawRoute(scope, 'health', { method: 'GET', handler: async (ctx) => {
-  ctx.response.send({ status: 'ok' });
-}});
+```bash
+curl -i http://localhost:3000/status
+# HTTP/1.1 200 OK
+# content-type: text/html; charset=utf-8
+#
+# <h1>ok</h1>
 ```
 
-Supports exact paths (`/health`), named parameters (`/users/{id}`), and wildcards (`/files/*`). Path can be omitted — it's derived from scope-chain IDs.
+The handler returns nothing; you write the response through `ctx.response`:
+
+| On `ctx.response` | Notes |
+|---|---|
+| `status: number` | Assignable. Defaults to `200`. |
+| `headers: Headers` | Standard `Headers`. Set `Content-Type` yourself; a string body is sent as-is, an object is serialized as JSON. |
+| `send(body)` | Call once with the body. `send('')` for an empty body (redirects, `204`). |
+
+And what you read from `ctx.request`:
+
+| On `ctx.request` | Notes |
+|---|---|
+| `params` | Path parameters, e.g. route `/users/{id}` + request `/users/42` → `{ id: '42' }`. Always `{}` for RPC methods. |
+| `url` | Absolute `URL` of the request. Use `url.searchParams` for the query string. |
+| `headers` | Request `Headers`, including `cookie`. |
+| `json()` / `text()` / `body` | Body as parsed JSON, raw text, or a `ReadableStream`. |
+| `signal` | `AbortSignal` that fires just before the platform's timeout response. Pass it to `fetch`/SDK calls. `undefined` in local dev. |
+
+Reading a path parameter and a query parameter:
+
+```typescript
+new RawRoute(scope, 'user', {
+  method: 'GET',
+  path: '/users/{id}',
+  handler: async (ctx) => {
+    ctx.response.headers.set('Content-Type', 'application/json');
+    ctx.response.send({ id: ctx.request.params.id, q: ctx.request.url.searchParams.get('q') });
+  },
+});
+// GET /users/42?q=hello → {"id":"42","q":"hello"}
+```
+
+Path syntax: exact (`/health`), named parameter capturing one segment (`/users/{id}`), or a trailing wildcard capturing the rest (`/files/*`, available as `params['*']`). One wildcard per route, last segment only. Named parameters are URL-decoded; wildcard captures are not, so validate them before touching a filesystem or an S3 key.
+
+`path` can be omitted, in which case it is derived from the scope-chain IDs, so `Scope('app') → Scope('v1') → RawRoute('health')` gives `/v1/health`. That means restructuring your construct tree silently changes URLs, so pass an explicit `path` for anything a client depends on.
+
+Registration rules worth knowing before you hit them at runtime:
 
-📖 **Full RawRoute documentation (see source repo)**
+- Routes must be constructed while the backend module is loading (top level of `aws-blocks/index.ts`, or from a block's constructor). Registering after the handler is created throws.
+- `/aws-blocks` itself and `/aws-blocks/api` (plus anything under it) are reserved for RPC dispatch, and `/` is not routable, so use a sub-path.
+- The same `method` + `path` twice throws `RawRouteErrors.DuplicateRoute`; catch it with `isBlocksError(e, RawRouteErrors.DuplicateRoute)`.
+- No extra AWS resources are created. The existing API Gateway proxy already forwards every path to the same Lambda, which checks the route registry before falling through to RPC.
 
 ### Pipeline
 

package/dist/cors.d.ts

@@ -1,3 +1,12 @@
+/**
+ * `Access-Control-Max-Age` for preflight responses, in seconds.
+ *
+ * Chromium caps the preflight cache at 7200s and silently clamps anything
+ * higher, so a larger value buys nothing while widening the window in which a
+ * stale per-origin grant can be served. Shared by the Lambda handler and the
+ * local dev server so the two can't drift.
+ */
+export declare const CORS_MAX_AGE = "7200";
 /**
  * Parse a comma-separated CORS origin string into anchored RegExp patterns.
  *
@@ -24,6 +33,23 @@ export declare function getCorsPatterns(): RegExp[] | null;
  * @returns `true` if the origin matches at least one pattern, `false` otherwise
  */
 export declare function isOriginAllowed(origin: string): boolean;
+/**
+ * Build the CORS response headers for a request origin.
+ *
+ * Only reflects the origin when it matches the configured allowlist. When no
+ * allowlist is configured, or the origin is configured-but-not-allowed, no
+ * `Access-Control-Allow-Origin` / `Access-Control-Allow-Credentials` headers
+ * are emitted, so a disallowed origin is never reflected back.
+ *
+ * `Vary: Origin` is always emitted, including on the not-allowed path: the
+ * response headers depend on the request `Origin`, so any shared cache (CDN,
+ * forward proxy) must key on it or it can serve one origin's grant — or one
+ * origin's *absence* of a grant — to a different origin.
+ *
+ * @param origin - The `Origin` header value from the request (may be empty)
+ * @returns The CORS headers to merge into the response
+ */
+export declare function buildCorsHeaders(origin: string): Record<string, string>;
 /**
  * Build a 403 Forbidden response for cross-origin requests from disallowed origins.
  */
@@ -33,7 +59,7 @@ export declare function corsRejection(): {
     body: string;
 };
 /**
- * Reset the lazy CORS pattern cache. **For testing only.**
+ * Reset the lazy CORS pattern cache and the warned-origin set. **For testing only.**
  */
 export declare function _resetCorsPatterns(): void;
 //# sourceMappingURL=cors.d.ts.map

package/dist/cors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../src/cors.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAYvD;AAcD;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,EAAE,GAAG,IAAI,CAcjD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAIvD;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAMrG;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAEzC"}
+{"version":3,"file":"cors.d.ts","sourceRoot":"","sources":["../src/cors.ts"],"names":[],"mappings":"AAGA;;;;;;;GAOG;AACH,eAAO,MAAM,YAAY,SAAS,CAAC;AAEnC;;;;;;;;;;GAUG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,EAAE,CAYvD;AAcD;;;;;GAKG;AACH,wBAAgB,eAAe,IAAI,MAAM,EAAE,GAAG,IAAI,CAcjD;AAED;;;;;GAKG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAIvD;AAqBD;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CASvE;AAED;;GAEG;AACH,wBAAgB,aAAa,IAAI;IAAE,UAAU,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAMrG;AAED;;GAEG;AACH,wBAAgB,kBAAkB,IAAI,IAAI,CAGzC"}

package/dist/cors.js

@@ -1,5 +1,14 @@
 // Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
 // SPDX-License-Identifier: Apache-2.0
+/**
+ * `Access-Control-Max-Age` for preflight responses, in seconds.
+ *
+ * Chromium caps the preflight cache at 7200s and silently clamps anything
+ * higher, so a larger value buys nothing while widening the window in which a
+ * stale per-origin grant can be served. Shared by the Lambda handler and the
+ * local dev server so the two can't drift.
+ */
+export const CORS_MAX_AGE = '7200';
 /**
  * Parse a comma-separated CORS origin string into anchored RegExp patterns.
  *
@@ -67,19 +76,63 @@ export function isOriginAllowed(origin) {
         return false;
     return patterns.some(re => re.test(origin));
 }
+/**
+ * Distinct origins already warned about, so a caller retrying — or a bot
+ * spraying bogus `Origin` values — can't amplify one log line per request now
+ * that this helper runs on every response path.
+ */
+const warnedOrigins = new Set();
+/** Cap on {@link warnedOrigins} so an untrusted input can't grow it unbounded. */
+const WARNED_ORIGINS_LIMIT = 100;
+function warnDisallowedOriginOnce(origin) {
+    if (warnedOrigins.has(origin))
+        return;
+    if (warnedOrigins.size < WARNED_ORIGINS_LIMIT)
+        warnedOrigins.add(origin);
+    const example = 'CORS_ALLOWED_ORIGINS=https://myapp\\.com,^https?://(localhost|127\\.0\\.0\\.1)(:\\d+)?$';
+    console.warn(`[CORS] Origin "${origin}" is not allowed. Set the CORS_ALLOWED_ORIGINS environment variable to allow this origin. Example: ${example}`);
+}
+/**
+ * Build the CORS response headers for a request origin.
+ *
+ * Only reflects the origin when it matches the configured allowlist. When no
+ * allowlist is configured, or the origin is configured-but-not-allowed, no
+ * `Access-Control-Allow-Origin` / `Access-Control-Allow-Credentials` headers
+ * are emitted, so a disallowed origin is never reflected back.
+ *
+ * `Vary: Origin` is always emitted, including on the not-allowed path: the
+ * response headers depend on the request `Origin`, so any shared cache (CDN,
+ * forward proxy) must key on it or it can serve one origin's grant — or one
+ * origin's *absence* of a grant — to a different origin.
+ *
+ * @param origin - The `Origin` header value from the request (may be empty)
+ * @returns The CORS headers to merge into the response
+ */
+export function buildCorsHeaders(origin) {
+    const headers = { Vary: 'Origin' };
+    if (isOriginAllowed(origin)) {
+        headers['Access-Control-Allow-Origin'] = origin;
+        headers['Access-Control-Allow-Credentials'] = 'true';
+    }
+    else if (origin) {
+        warnDisallowedOriginOnce(origin);
+    }
+    return headers;
+}
 /**
  * Build a 403 Forbidden response for cross-origin requests from disallowed origins.
  */
 export function corsRejection() {
     return {
         statusCode: 403,
-        headers: { 'Content-Type': 'application/json' },
+        headers: { 'Content-Type': 'application/json', Vary: 'Origin' },
         body: JSON.stringify({ error: 'Forbidden: cross-origin request rejected' }),
     };
 }
 /**
- * Reset the lazy CORS pattern cache. **For testing only.**
+ * Reset the lazy CORS pattern cache and the warned-origin set. **For testing only.**
  */
 export function _resetCorsPatterns() {
     _corsPatterns = undefined;
+    warnedOrigins.clear();
 }

package/dist/cors.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 { parseCorsPatterns, _resetCorsPatterns } from './cors.js';
+import { parseCorsPatterns, _resetCorsPatterns, buildCorsHeaders, CORS_MAX_AGE } from './cors.js';
 import { createLambdaHandler } from './lambda-handler.js';
 import { clearRouteRegistry } from './raw-route.js';
 // ── parseCorsPatterns unit tests ────────────────────────────────────────────
@@ -49,6 +49,81 @@ describe('parseCorsPatterns', () => {
         assert.ok(patterns[0].test('http://localhost:9999'));
     });
 });
+// ── buildCorsHeaders unit tests ─────────────────────────────────────────────
+describe('buildCorsHeaders', () => {
+    beforeEach(() => {
+        delete process.env.CORS_ALLOWED_ORIGINS;
+        delete process.env.CORS_HOSTING_ORIGINS;
+        _resetCorsPatterns();
+    });
+    it('reflects an origin that matches the configured allowlist', () => {
+        process.env.CORS_ALLOWED_ORIGINS = 'https://myapp\\.example\\.com';
+        _resetCorsPatterns();
+        const headers = buildCorsHeaders('https://myapp.example.com');
+        assert.strictEqual(headers['Access-Control-Allow-Origin'], 'https://myapp.example.com');
+        assert.strictEqual(headers['Access-Control-Allow-Credentials'], 'true');
+    });
+    it('never reflects an origin that is not on a configured allowlist', () => {
+        process.env.CORS_ALLOWED_ORIGINS = 'https://myapp\\.example\\.com';
+        _resetCorsPatterns();
+        const headers = buildCorsHeaders('https://evil.example.com');
+        assert.strictEqual(headers['Access-Control-Allow-Origin'], undefined);
+        assert.strictEqual(headers['Access-Control-Allow-Credentials'], undefined);
+        assert.deepStrictEqual(headers, { Vary: 'Origin' });
+    });
+    it('never reflects an origin when no allowlist is configured', () => {
+        const headers = buildCorsHeaders('https://evil.example.com');
+        assert.strictEqual(headers['Access-Control-Allow-Origin'], undefined);
+        assert.deepStrictEqual(headers, { Vary: 'Origin' });
+    });
+    it('returns no reflection headers when there is no origin', () => {
+        process.env.CORS_ALLOWED_ORIGINS = 'https://myapp\\.example\\.com';
+        _resetCorsPatterns();
+        assert.deepStrictEqual(buildCorsHeaders(''), { Vary: 'Origin' });
+    });
+    it('always sets Vary: Origin so shared caches key on the request origin', () => {
+        process.env.CORS_ALLOWED_ORIGINS = 'https://myapp\\.example\\.com';
+        _resetCorsPatterns();
+        assert.strictEqual(buildCorsHeaders('https://myapp.example.com').Vary, 'Origin');
+        assert.strictEqual(buildCorsHeaders('https://evil.example.com').Vary, 'Origin');
+        assert.strictEqual(buildCorsHeaders('').Vary, 'Origin');
+    });
+    it('warns only once per distinct disallowed origin', () => {
+        process.env.CORS_ALLOWED_ORIGINS = 'https://myapp\\.example\\.com';
+        _resetCorsPatterns();
+        const original = console.warn;
+        const lines = [];
+        console.warn = (msg) => { lines.push(msg); };
+        try {
+            buildCorsHeaders('https://evil.example.com');
+            buildCorsHeaders('https://evil.example.com');
+            buildCorsHeaders('https://evil.example.com');
+            assert.strictEqual(lines.length, 1, 'repeat requests from one origin should warn once');
+            buildCorsHeaders('https://other.example.com');
+            assert.strictEqual(lines.length, 2, 'a distinct origin should still warn');
+            assert.ok(lines[0].includes('https://evil.example.com'));
+            assert.ok(lines[1].includes('https://other.example.com'));
+        }
+        finally {
+            console.warn = original;
+        }
+    });
+    it('does not warn for an allowed origin or an absent origin', () => {
+        process.env.CORS_ALLOWED_ORIGINS = 'https://myapp\\.example\\.com';
+        _resetCorsPatterns();
+        const original = console.warn;
+        const lines = [];
+        console.warn = (msg) => { lines.push(msg); };
+        try {
+            buildCorsHeaders('https://myapp.example.com');
+            buildCorsHeaders('');
+            assert.strictEqual(lines.length, 0);
+        }
+        finally {
+            console.warn = original;
+        }
+    });
+});
 // ── isOriginAllowed + getCorsPatterns integration via handler ────────────────
 // These tests exercise the full CORS flow through createLambdaHandler to
 // verify origin validation, header injection, and rejection work end-to-end.
@@ -137,7 +212,11 @@ describe('createLambdaHandler — CORS origin validation', () => {
         assert.strictEqual(result.headers['Access-Control-Allow-Credentials'], 'true');
         assert.ok(result.headers['Access-Control-Allow-Methods']);
         assert.ok(result.headers['Access-Control-Allow-Headers']);
-        assert.strictEqual(result.headers['Access-Control-Max-Age'], '86400');
+        assert.strictEqual(result.headers['Access-Control-Max-Age'], CORS_MAX_AGE);
+        assert.strictEqual(result.headers['Vary'], 'Origin');
+    });
+    it('pins Access-Control-Max-Age at the browser preflight cap', () => {
+        assert.strictEqual(CORS_MAX_AGE, '7200');
     });
     it('OPTIONS preflight with rejected origin returns 403', async () => {
         const result = await invoke(echoBackend, makeEvent({

package/dist/errors.test.js

@@ -2,7 +2,32 @@
 // SPDX-License-Identifier: Apache-2.0
 import { describe, it } from 'node:test';
 import assert from 'node:assert';
-import { ApiError, isBlocksError, hasAuthError } from './errors.js';
+import { ApiError, DEFAULT_API_ERROR_NAME, isBlocksError, hasAuthError } from './errors.js';
+describe('ApiError constructor', () => {
+    it('exposes message and status, and stays a real Error', () => {
+        const e = new ApiError('Not found', 404);
+        assert.ok(e instanceof Error);
+        assert.strictEqual(e.message, 'Not found');
+        assert.strictEqual(e.status, 404);
+    });
+    it('defaults name to ApiError and retriable to false', () => {
+        const e = new ApiError('boom', 500);
+        assert.strictEqual(e.name, DEFAULT_API_ERROR_NAME);
+        assert.strictEqual(e.retriable, false);
+    });
+    it('takes name, cause and retriable from the options argument', () => {
+        const cause = new Error('root');
+        const e = new ApiError('Username already taken', 409, {
+            name: 'ConditionalCheckFailedException',
+            cause,
+            retriable: true,
+        });
+        assert.strictEqual(e.name, 'ConditionalCheckFailedException');
+        assert.strictEqual(e.status, 409);
+        assert.strictEqual(e.retriable, true);
+        assert.strictEqual(e.cause, cause);
+    });
+});
 describe('isBlocksError', () => {
     it('matches a thrown ApiError by name', () => {
         const e = new ApiError('nope', 401, { name: 'InvalidCredentialsException' });

package/dist/hosting.d.ts.map

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

package/dist/hosting.js

@@ -11,11 +11,13 @@ import { join, resolve } from 'node:path';
 import { HostingConstruct, generateBuildId, } from '@aws-blocks/hosting/constructs';
 import { detectFramework, getAdapter, normalizeBasePath, } from '@aws-blocks/hosting/adapters';
 import { BLOCKS_RPC_PREFIX, BLOCKS_AUTH_PREFIX } from './constants.js';
+import { BLOCKS_SANDBOX_DIR } from './common/constants.js';
 import { registerConfig } from './cdk/config-registry.js';
 import { getRegisteredRoutes } from './raw-route.js';
 // ─── Default build output directories per framework ──────────────
 const DEFAULT_BUILD_DIRS = {
     nextjs: '.next',
+    sveltekit: 'build',
     spa: 'dist',
     static: 'dist',
 };
@@ -164,6 +166,18 @@ export class Hosting extends Construct {
         const blocksSandboxDir = join(staticDir, '.blocks-sandbox');
         mkdirSync(blocksSandboxDir, { recursive: true });
         writeFileSync(join(blocksSandboxDir, 'config.json'), JSON.stringify({ _placeholder: true }));
+        // ── 5a. Mark config.json as a no-cache path ─────────────────────
+        //    config.json is a fixed-name, mutable runtime-config file: it must
+        //    NOT inherit the content-hashed mutable-asset cache-control
+        //    (`s-maxage=31536000`) applied to `/assets/<hash>.js`. Registering it
+        //    as a no-cache path uploads the build-time placeholder with
+        //    `no-cache, no-store, must-revalidate` so an edge never caches it
+        //    long-term; the real config is deployed in step 8 with `max-age=60`.
+        const configNoCachePath = `${BLOCKS_SANDBOX_DIR}/config.json`;
+        const existingNoCachePaths = manifest.staticAssets.noCachePaths ?? [];
+        manifest.staticAssets.noCachePaths = existingNoCachePaths.includes(configNoCachePath)
+            ? existingNoCachePaths
+            : [...existingNoCachePaths, configNoCachePath];
         // ── 5b. Inject static route for .blocks-sandbox config ──────────
         //    Insert a static route for /.blocks-sandbox/* so CloudFront
         //    serves config.json from S3 instead of routing to compute.
@@ -249,7 +263,18 @@ export class Hosting extends Construct {
                 destinationKeyPrefix: `builds/${buildId}/.blocks-sandbox`,
                 prune: false,
                 distribution: hosting.distribution,
-                distributionPaths: ['/.blocks-sandbox/*'],
+                // The skew-protection viewer-request CloudFront 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 that key and is
+                // a no-op for config.json. Invalidate the post-rewrite key too. (The
+                // primary guard against staleness is step 5a's no-cache placeholder;
+                // this is defense-in-depth so a post-deploy invalidation actually
+                // clears any edge entry at its real key.)
+                distributionPaths: [
+                    `/builds/${buildId}/.blocks-sandbox/*`,
+                    '/.blocks-sandbox/*',
+                ],
                 cacheControl: [s3deploy.CacheControl.fromString('public, max-age=60, must-revalidate')],
             });
             // Ensure the config deployment runs AFTER the hosting construct's