create-agent-rig 0.4.0 → 0.5.0

package/templates/skeleton/aws-serverless/infra/test/app-composition.test.ts

@@ -0,0 +1,137 @@
+import type { App, Stack } from 'aws-cdk-lib';
+import { Template } from 'aws-cdk-lib/assertions';
+import { describe, expect, it } from 'vitest';
+import { resolveAllowedOrigins } from '../lib/app-stack.js';
+
+// `bin/app.ts` is what every `cdk deploy` and every CI run actually builds, so
+// the CORS allow-list has to be correct THERE — a stack that can be handed the
+// right origin, by an entrypoint that hands it none, ships an app whose own
+// browser calls are blocked. The README's `curl` health check sends no `Origin`
+// header, so nothing downstream notices.
+//
+// The composition is exercised through the entrypoint rather than rebuilt here:
+// a test that re-wires the stacks itself passes just as happily while
+// `bin/app.ts` stays broken.
+
+const originsOfComposedApp = async (): Promise<unknown[]> => {
+  const { createApp } = (await import('../bin/app.js')) as { createApp: () => App };
+  const app = createApp();
+  const template = Template.fromStack(app.node.findChild('AppStack') as Stack);
+  const apis = template.findResources('AWS::ApiGatewayV2::Api');
+  return Object.values(apis).flatMap(
+    (api) =>
+      (api.Properties as { CorsConfiguration?: { AllowOrigins?: unknown[] } }).CorsConfiguration
+        ?.AllowOrigins ?? [],
+  );
+};
+
+/**
+ * `createApp()` builds its own `App`, so `new App({ context })` is not a seam
+ * here. CDK's own is: the CLI passes `-c key=value` to a synth through
+ * `CDK_CONTEXT_JSON`, which the `App` constructor reads — so setting it around
+ * one `createApp()` call reproduces `cdk deploy -c allowedOrigins=…` exactly,
+ * without the test knowing anything about how the stacks are wired.
+ *
+ * `process.env` is process-global, so this seam is not concurrency-safe: an
+ * `it.concurrent` in this file would have one case's context leak into
+ * another's synth. Keep these cases sequential.
+ */
+const withCdkContext = async <T>(context: Record<string, unknown>, run: () => Promise<T>) => {
+  const previous = process.env.CDK_CONTEXT_JSON;
+  process.env.CDK_CONTEXT_JSON = JSON.stringify(context);
+  try {
+    return await run();
+  } finally {
+    if (previous === undefined) delete process.env.CDK_CONTEXT_JSON;
+    else process.env.CDK_CONTEXT_JSON = previous;
+  }
+};
+
+/**
+ * The default composition is synthesised once and shared — but deliberately
+ * NOT from `beforeAll`. This project's `vitest.config.ts` raises `testTimeout`
+ * for exactly this cost and leaves `hookTimeout` at vitest's 10s default, so
+ * work put in a hook runs on a fuse a quarter the length of the one the config
+ * meant to give it. Synthesising here bundles three Lambdas with esbuild while
+ * sibling workers do the same; that contention is what made this suite fail
+ * intermittently with `Hook timed out in 10000ms`.
+ */
+let defaultComposition: Promise<unknown[]> | undefined;
+const defaultComposedOrigins = (): Promise<unknown[]> =>
+  (defaultComposition ??= originsOfComposedApp());
+
+/** What CDK emits for a cross-stack reference: a Join around an ImportValue. */
+const referencesTheWebDistribution = (origin: unknown): boolean => {
+  if (typeof origin === 'string') return false; // a hard-coded origin, whatever it says
+  const rendered = JSON.stringify(origin);
+  return /Fn::ImportValue/.test(rendered) && /WebStack/.test(rendered);
+};
+
+describe('the deployed app allows the origin it is actually served from', () => {
+  it('takes its allowed origin from the web distribution, not from a localhost no deploy uses', async () => {
+    // `distributionDomainName` is a synth-time token; CDK resolves it across
+    // stacks as an `Fn::ImportValue`, and `AllowOrigins` accepts it. So the
+    // entrypoint has no excuse to leave the two stacks unwired.
+    const appStackOrigins = await defaultComposedOrigins();
+    expect(appStackOrigins.length).toBeGreaterThan(0);
+    expect(appStackOrigins.some(referencesTheWebDistribution)).toBe(true);
+  });
+
+  it('still names who may call it: no wildcard reaches the composed app', async () => {
+    const appStackOrigins = await defaultComposedOrigins();
+    expect(appStackOrigins).not.toContain('*');
+    expect(JSON.stringify(appStackOrigins)).not.toContain('"*"');
+  });
+
+  it('carries the https scheme, without which no browser Origin header can match', async () => {
+    const appStackOrigins = await defaultComposedOrigins();
+    const distributionOrigin = appStackOrigins.find(referencesTheWebDistribution);
+    expect(JSON.stringify(distributionOrigin)).toContain('https://');
+  });
+});
+
+// The README and `AppStackProps.allowedOrigins` both advertise
+// `-c allowedOrigins=https://…` as the way to point the API at a custom domain.
+// It once did not work: the entrypoint passed `allowedOrigins` unconditionally
+// and props win, so the flag was discarded on synth with no error and no
+// warning — a green deploy, a CORS-blocked browser, and `allowOrigins: ['*']`
+// as the obvious repair for a hurried reader. That is the regression the rest
+// of this file exists to prevent, arriving through a different door, which is
+// why the door is pinned here.
+describe('the documented -c escape hatch reaches the composed app', () => {
+  it('serves the origin the flag names instead of discarding it for the CloudFront import', async () => {
+    const origins = await withCdkContext({ allowedOrigins: 'https://custom.example.com' }, () =>
+      originsOfComposedApp(),
+    );
+
+    expect(origins).toContain('https://custom.example.com');
+    expect(
+      origins.some(referencesTheWebDistribution),
+      'a custom domain that still allows only the CloudFront import is a blocked browser',
+    ).toBe(false);
+  });
+});
+
+// Two files read the same context key, and they once disagreed by one value:
+// the entrypoint asked `override === undefined` while `resolveAllowedOrigins`
+// treated `undefined` OR `null` as "nothing given". A `null` — writable in
+// `cdk.json`, `cdk.context.json` or `CDK_CONTEXT_JSON`, though never producible
+// by the `-c` flag — landed in the gap, and the entrypoint dropped the wired
+// origin as if an override existed while the stack fell back to a localhost no
+// deploy is served from. Green synth, blocked browser: this branch's whole
+// failure class. One predicate now, imported; this pins that it stays one.
+describe('a context that names no origin is not an override', () => {
+  it('keeps the wired CloudFront origin when allowedOrigins is present but null', async () => {
+    const origins = await withCdkContext({ allowedOrigins: null }, () => originsOfComposedApp());
+
+    expect(
+      origins.some(referencesTheWebDistribution),
+      'a null context must compose exactly like no context at all',
+    ).toBe(true);
+    // Asked of the resolver rather than spelled out: a literal copy of the
+    // localhost default passes vacuously the moment the default changes — it
+    // then forbids an origin nothing could have produced, and the leak this
+    // line exists to catch walks straight through.
+    expect(origins).not.toContain(resolveAllowedOrigins(undefined, undefined)[0]);
+  });
+});

package/templates/skeleton/aws-serverless/infra/test/app-stack.test.ts

@@ -1,38 +1,40 @@
 import { App } from 'aws-cdk-lib';
 import { Match, Template } from 'aws-cdk-lib/assertions';
-import { beforeAll, describe, expect, it } from 'vitest';
+import { describe, expect, it } from 'vitest';
 import { AppStack } from '../lib/app-stack.js';
 
-// Template.fromStack bundles the Lambda entries with esbuild — slow-ish, run once.
-let template: Template;
-
-beforeAll(() => {
-  const app = new App();
-  template = Template.fromStack(new AppStack(app, 'TestStack'));
-});
+// `Template.fromStack` bundles the Lambda entries with esbuild — slow-ish, so
+// it runs once and is shared. Deliberately not in `beforeAll`: this project's
+// `vitest.config.ts` raises `testTimeout` for exactly this cost and leaves
+// `hookTimeout` at vitest's 10s default, so the same work in a hook runs on a
+// much shorter fuse — and it is contended, because sibling workers are
+// bundling too.
+let synthesised: Template | undefined;
+const template = (): Template =>
+  (synthesised ??= Template.fromStack(new AppStack(new App(), 'TestStack')));
 
 describe('storage', () => {
   it('creates the single table with pk/sk and on-demand billing', () => {
-    template.hasResourceProperties('AWS::DynamoDB::Table', {
+    template().hasResourceProperties('AWS::DynamoDB::Table', {
       KeySchema: [
         { AttributeName: 'pk', KeyType: 'HASH' },
         { AttributeName: 'sk', KeyType: 'RANGE' },
       ],
       BillingMode: 'PAY_PER_REQUEST',
     });
-    template.resourceCountIs('AWS::DynamoDB::Table', 1);
+    template().resourceCountIs('AWS::DynamoDB::Table', 1);
   });
 });
 
 describe('queue discipline', () => {
   it('wires the DLQ with maxReceiveCount 3', () => {
-    template.hasResourceProperties('AWS::SQS::Queue', {
+    template().hasResourceProperties('AWS::SQS::Queue', {
       RedrivePolicy: Match.objectLike({ maxReceiveCount: 3 }),
     });
   });
 
   it('alarms as soon as one message reaches the DLQ', () => {
-    template.hasResourceProperties('AWS::CloudWatch::Alarm', {
+    template().hasResourceProperties('AWS::CloudWatch::Alarm', {
       MetricName: 'ApproximateNumberOfMessagesVisible',
       Threshold: 1,
       EvaluationPeriods: 1,
@@ -41,7 +43,7 @@ describe('queue discipline', () => {
   });
 
   it('feeds the worker one message at a time', () => {
-    template.hasResourceProperties('AWS::Lambda::EventSourceMapping', {
+    template().hasResourceProperties('AWS::Lambda::EventSourceMapping', {
       BatchSize: 1,
     });
   });
@@ -49,11 +51,11 @@ describe('queue discipline', () => {
 
 describe('functions and routes', () => {
   it('deploys exactly the create, list and worker functions — one purpose each', () => {
-    template.resourceCountIs('AWS::Lambda::Function', 3);
+    template().resourceCountIs('AWS::Lambda::Function', 3);
   });
 
   it('passes table and queue to the api via environment', () => {
-    template.hasResourceProperties('AWS::Lambda::Function', {
+    template().hasResourceProperties('AWS::Lambda::Function', {
       Environment: {
         Variables: Match.objectLike({
           TABLE_NAME: Match.anyValue(),
@@ -64,27 +66,41 @@ describe('functions and routes', () => {
   });
 
   it('exposes exactly two routes: POST /notes and GET /notes', () => {
-    template.hasResourceProperties('AWS::ApiGatewayV2::Route', {
+    template().hasResourceProperties('AWS::ApiGatewayV2::Route', {
       RouteKey: 'POST /notes',
     });
-    template.hasResourceProperties('AWS::ApiGatewayV2::Route', {
+    template().hasResourceProperties('AWS::ApiGatewayV2::Route', {
       RouteKey: 'GET /notes',
     });
-    template.resourceCountIs('AWS::ApiGatewayV2::Route', 2);
+    template().resourceCountIs('AWS::ApiGatewayV2::Route', 2);
   });
 
   it('allows the browser origin in: CORS is configured', () => {
-    template.hasResourceProperties('AWS::ApiGatewayV2::Api', {
+    template().hasResourceProperties('AWS::ApiGatewayV2::Api', {
       CorsConfiguration: Match.objectLike({
         AllowMethods: Match.arrayWith(['GET', 'POST']),
       }),
     });
   });
+
+  it('never allows every origin: the api names who may call it', () => {
+    const apis = template().findResources('AWS::ApiGatewayV2::Api');
+    const origins = Object.values(apis).flatMap(
+      (api) =>
+        (api.Properties as { CorsConfiguration?: { AllowOrigins?: unknown[] } }).CorsConfiguration
+          ?.AllowOrigins ?? [],
+    );
+
+    // A starter multiplies whatever it ships: `*` here becomes the default of
+    // every project generated from it. The web bundle has a known origin.
+    expect(origins.length).toBeGreaterThan(0);
+    expect(origins).not.toContain('*');
+  });
 });
 
 describe('least-privilege IAM', () => {
   it('grants writes to the creator, reads to the lister, queue send — nothing broad', () => {
-    const policies = template.findResources('AWS::IAM::Policy');
+    const policies = template().findResources('AWS::IAM::Policy');
     const statements = Object.values(policies).flatMap(
       (policy) =>
         (policy.Properties as { PolicyDocument: { Statement: Array<Record<string, unknown>> } })

package/templates/skeleton/aws-serverless/infra/test/web-stack.test.ts

@@ -1,20 +1,23 @@
 import { App } from 'aws-cdk-lib';
 import { Match, Template } from 'aws-cdk-lib/assertions';
-import { beforeAll, describe, it } from 'vitest';
+import { describe, it } from 'vitest';
 import { WebStack } from '../lib/web-stack.js';
 
 // The web stack is stateless serving only: a private bucket behind CloudFront.
 // The bundle itself is synced by the deploy step (see README) — synth stays
 // independent of `next build`.
-let template: Template;
-
-beforeAll(() => {
-  template = Template.fromStack(new WebStack(new App(), 'TestWebStack'));
-});
+//
+// Synthesised lazily rather than in a `beforeAll`, like its neighbours in this
+// directory: `vitest.config.ts` raises `testTimeout` and leaves `hookTimeout`
+// at 10 s, so a hook is the one place in the suite running on a short fuse.
+// This stack bundles no Lambda and takes ~370 ms — the reason to do it anyway
+// is that the next person copies whatever shape is here.
+let cached: Template | undefined;
+const template = () => (cached ??= Template.fromStack(new WebStack(new App(), 'TestWebStack')));
 
 describe('web serving stack', () => {
   it('keeps the bucket fully private', () => {
-    template.hasResourceProperties('AWS::S3::Bucket', {
+    template().hasResourceProperties('AWS::S3::Bucket', {
       PublicAccessBlockConfiguration: Match.objectLike({
         BlockPublicAcls: true,
         BlockPublicPolicy: true,
@@ -25,9 +28,9 @@ describe('web serving stack', () => {
   });
 
   it('serves through CloudFront with origin access control', () => {
-    template.resourceCountIs('AWS::CloudFront::Distribution', 1);
-    template.resourceCountIs('AWS::CloudFront::OriginAccessControl', 1);
-    template.hasResourceProperties('AWS::CloudFront::Distribution', {
+    template().resourceCountIs('AWS::CloudFront::Distribution', 1);
+    template().resourceCountIs('AWS::CloudFront::OriginAccessControl', 1);
+    template().hasResourceProperties('AWS::CloudFront::Distribution', {
       DistributionConfig: Match.objectLike({
         DefaultRootObject: 'index.html',
       }),
@@ -35,7 +38,7 @@ describe('web serving stack', () => {
   });
 
   it('exports the distribution domain and bucket name for the deploy step', () => {
-    template.hasOutput('WebBucketName', {});
-    template.hasOutput('WebUrl', {});
+    template().hasOutput('WebBucketName', {});
+    template().hasOutput('WebUrl', {});
   });
 });

package/templates/skeleton/aws-serverless/services/api/src/handlers/create-note.ts

@@ -1,11 +1,19 @@
 // The handler translates transport ⇄ domain and nothing else: decode the
 // payload, call the usecase, map the result (or the typed error) to HTTP.
-import type { APIGatewayProxyEventV2, APIGatewayProxyResultV2 } from 'aws-lambda';
+import type { APIGatewayProxyEventV2, APIGatewayProxyResultV2, Context } from 'aws-lambda';
 import { InvalidNoteError } from '@app/core';
 import { AppError } from '@app/shared';
 import { createNoteUsecase, type CreateNoteDeps } from '../usecases/create-note.js';
 
-type Handler = (event: APIGatewayProxyEventV2) => Promise<APIGatewayProxyResultV2>;
+/**
+ * Lambda passes the context as the second argument; the handler takes the one
+ * field it needs, so a log line can be tied back to the invocation that wrote
+ * it. Optional because the context is Lambda's to supply, not the caller's.
+ */
+type Handler = (
+  event: APIGatewayProxyEventV2,
+  context?: Pick<Context, 'awsRequestId'>,
+) => Promise<APIGatewayProxyResultV2>;
 
 const json = (statusCode: number, body: unknown): APIGatewayProxyResultV2 => ({
   statusCode,
@@ -14,7 +22,7 @@ const json = (statusCode: number, body: unknown): APIGatewayProxyResultV2 => ({
 });
 
 export function makeCreateNoteHandler(deps: CreateNoteDeps): Handler {
-  return async (event) => {
+  return async (event, context) => {
     let payload: unknown;
     try {
       const raw = event.isBase64Encoded
@@ -32,11 +40,30 @@ export function makeCreateNoteHandler(deps: CreateNoteDeps): Handler {
       if (error instanceof InvalidNoteError) {
         return json(400, { error: 'invalid note', issues: error.issues });
       }
-      if (error instanceof AppError) {
+      // A 4xx message was written for the caller to read. A 5xx one was not:
+      // `AppError` defaults to 500/INTERNAL, so a table name, a host or an SDK
+      // message arrives here wearing the same type as "title is required".
+      // Typed does not mean safe to show — the status decides.
+      //
+      // The status itself is kept: 503 tells a caller to retry and 500 does
+      // not, and that distinction is transport, not disclosure. Only the
+      // message is withheld.
+      if (error instanceof AppError && error.statusCode < 500) {
         return json(error.statusCode, { error: error.message, code: error.code });
       }
-      deps.log.error('unhandled error in create-note', { error: String(error) });
-      return json(500, { error: 'internal error' });
+      // Everything past here is withheld, so it has to be kept somewhere: the
+      // message AND its frames, because a message with no stack is not
+      // something anyone can debug from a log aggregator, and the request id,
+      // because a line nobody can tie to an invocation is barely a line.
+      deps.log.error('unhandled error in create-note', {
+        error: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+        // The one field of a withheld AppError worth keeping: it says WHICH
+        // internal failure this was, and it never reaches the caller.
+        code: error instanceof AppError ? error.code : undefined,
+        awsRequestId: context?.awsRequestId,
+      });
+      return json(error instanceof AppError ? error.statusCode : 500, { error: 'internal error' });
     }
   };
 }

package/templates/skeleton/aws-serverless/services/api/src/handlers/list-notes.ts

@@ -1,4 +1,4 @@
-import type { APIGatewayProxyResultV2 } from 'aws-lambda';
+import type { APIGatewayProxyEventV2, APIGatewayProxyResultV2, Context } from 'aws-lambda';
 import { AppError } from '@app/shared';
 import type { Logger } from '@app/shared';
 import { listNotesUsecase, type ListNotesDeps } from '../usecases/list-notes.js';
@@ -10,15 +10,28 @@ const json = (statusCode: number, body: unknown): APIGatewayProxyResultV2 => ({
 });
 
 export function makeListNotesHandler(deps: ListNotesDeps & { log: Logger }) {
-  return async (): Promise<APIGatewayProxyResultV2> => {
+  return async (
+    _event?: APIGatewayProxyEventV2,
+    context?: Pick<Context, 'awsRequestId'>,
+  ): Promise<APIGatewayProxyResultV2> => {
     try {
       return json(200, { notes: await listNotesUsecase(deps) });
     } catch (error) {
-      if (error instanceof AppError) {
+      // Same contract as create-note: a 4xx message was written for the caller,
+      // a 5xx one was not. The status survives — 503 tells a caller to retry
+      // and 500 does not — and only the message is withheld.
+      if (error instanceof AppError && error.statusCode < 500) {
         return json(error.statusCode, { error: error.message, code: error.code });
       }
-      deps.log.error('unhandled error in list-notes', { error: String(error) });
-      return json(500, { error: 'internal error' });
+      deps.log.error('unhandled error in list-notes', {
+        error: error instanceof Error ? error.message : String(error),
+        stack: error instanceof Error ? error.stack : undefined,
+        // The one field of a withheld AppError worth keeping: it says WHICH
+        // internal failure this was, and it never reaches the caller.
+        code: error instanceof AppError ? error.code : undefined,
+        awsRequestId: context?.awsRequestId,
+      });
+      return json(error instanceof AppError ? error.statusCode : 500, { error: 'internal error' });
     }
   };
 }

package/templates/skeleton/aws-serverless/services/api/src/usecases/create-note.ts

@@ -21,6 +21,17 @@ export interface CreateNoteDeps {
   log: Logger;
 }
 
+/**
+ * ⚠ These are **two writes and they are not atomic** — a dual write. The put
+ * can succeed and the publish then fail, which leaves a stored note whose event
+ * never happened: the worker does not run, nothing downstream hears about it,
+ * and nothing here compensates. The caller sees a 500 for a note that exists.
+ *
+ * That is a deliberate simplification for a skeleton, not a pattern to copy at
+ * scale. The two ways out, when it starts to matter: an **outbox** (write the
+ * event into the same transaction as the note, relay it after), or DynamoDB
+ * Streams feeding the worker, which removes the second write entirely.
+ */
 export async function createNoteUsecase(input: unknown, deps: CreateNoteDeps): Promise<Note> {
   const note = createNote(input, { id: deps.newId(), createdAt: deps.now() });
   await deps.notes.put(note);

package/templates/skeleton/aws-serverless/services/api/test/create-note.handler.test.ts

@@ -1,4 +1,8 @@
-import type { APIGatewayProxyEventV2, APIGatewayProxyStructuredResultV2 } from 'aws-lambda';
+import type {
+  APIGatewayProxyEventV2,
+  APIGatewayProxyStructuredResultV2,
+  Context,
+} from 'aws-lambda';
 import { AppError, createLogger } from '@app/shared';
 import { describe, expect, it } from 'vitest';
 import { makeCreateNoteHandler } from '../src/handlers/create-note.js';
@@ -7,6 +11,9 @@ import type { CreateNoteDeps } from '../src/usecases/create-note.js';
 const event = (body: string): APIGatewayProxyEventV2 =>
   ({ body, isBase64Encoded: false }) as APIGatewayProxyEventV2;
 
+/** Lambda always passes a context; the handler only ever needs the request id. */
+const lambdaContext = (awsRequestId: string): Context => ({ awsRequestId }) as Context;
+
 function stubDeps(overrides: Partial<CreateNoteDeps> = {}) {
   const deps: CreateNoteDeps = {
     notes: { put: async () => {} },
@@ -89,4 +96,116 @@ describe('POST /notes handler', () => {
     expect(result.body).not.toContain('secret detail');
     expect(logs.join('\n')).toContain('secret detail');
   });
+
+  // AppError defaults to statusCode 500 / code INTERNAL, so "typed" does not
+  // mean "safe to show": a table name, a host, an SDK message all arrive this
+  // way. Only a 4xx AppError is a message the caller was meant to read.
+  it('hides a typed error that carries the default status behind the same constant 500', async () => {
+    const handler = makeCreateNoteHandler(
+      stubDeps({
+        notes: {
+          put: () => Promise.reject(new AppError('table NotesTable-prod is not authorised')),
+        },
+      }),
+    );
+    const result = asResult(await handler(event(JSON.stringify({ title: 'T' }))));
+    expect(result.statusCode).toBe(500);
+    expect(result.body).not.toContain('NotesTable-prod');
+    expect(JSON.parse(result.body!)).toEqual({ error: 'internal error' });
+  });
+
+  // Withholding the message is not the same decision as flattening the status.
+  // 503 tells a caller to retry and 500 tells it not to bother, and that
+  // distinction is transport, not disclosure — the sibling handler pins it
+  // (`list-notes.test.ts`), and this one did not, so collapsing the status here
+  // passed the whole suite.
+  it('keeps a 5xx status the caller can act on, while still hiding the message', async () => {
+    const handler = makeCreateNoteHandler(
+      stubDeps({
+        notes: {
+          put: () =>
+            Promise.reject(
+              new AppError('table NotesTable-prod is throttling', {
+                statusCode: 503,
+                code: 'X',
+              }),
+            ),
+        },
+      }),
+    );
+    const result = asResult(await handler(event(JSON.stringify({ title: 'T' }))));
+    expect(result.statusCode).toBe(503);
+    expect(result.body).not.toContain('NotesTable-prod');
+    expect(JSON.parse(result.body!)).toEqual({ error: 'internal error' });
+  });
+
+  it('logs the typed internal error it hid, so the detail is kept and not lost', async () => {
+    const logs: string[] = [];
+    const handler = makeCreateNoteHandler(
+      stubDeps({
+        notes: {
+          put: () => Promise.reject(new AppError('table NotesTable-prod is not authorised')),
+        },
+        log: createLogger({}, (line) => logs.push(line)),
+      }),
+    );
+    await handler(event(JSON.stringify({ title: 'T' })));
+    expect(logs.join('\n')).toContain('NotesTable-prod');
+  });
+
+  it('logs the failure with its stack, not only its message', async () => {
+    const logs: string[] = [];
+    const boom = new Error('secret detail');
+    const handler = makeCreateNoteHandler(
+      stubDeps({
+        notes: { put: () => Promise.reject(boom) },
+        log: createLogger({}, (line) => logs.push(line)),
+      }),
+    );
+    await handler(event(JSON.stringify({ title: 'T' })));
+    // `String(error)` is "Error: secret detail" — a message with no frames is
+    // not something anyone can debug from CloudWatch.
+    expect(JSON.parse(logs[0]!)).toMatchObject({ stack: boom.stack });
+  });
+
+  // The response withholds everything about a 5xx AppError, so the log line is
+  // the only place left that can say WHICH internal failure it was — and `code`
+  // is the one field of that error which is safe to keep verbatim. Losing it
+  // flattens DATA_CORRUPT, INTERNAL and every future code into one shape nobody
+  // can triage. The body assertion lives here on purpose: the two halves of the
+  // contract ("kept in the log", "still absent from the response") must not
+  // drift apart.
+  it('logs the code of the internal error it withheld, and still keeps it out of the response', async () => {
+    const logs: string[] = [];
+    const handler = makeCreateNoteHandler(
+      stubDeps({
+        notes: {
+          put: () =>
+            Promise.reject(
+              new AppError('table NotesTable-prod returned a torn item', {
+                code: 'DATA_CORRUPT',
+              }),
+            ),
+        },
+        log: createLogger({}, (line) => logs.push(line)),
+      }),
+    );
+    const result = asResult(await handler(event(JSON.stringify({ title: 'T' }))));
+    expect(JSON.parse(logs[0]!)).toMatchObject({ code: 'DATA_CORRUPT' });
+    expect(result.body).not.toContain('DATA_CORRUPT');
+    expect(JSON.parse(result.body!)).toEqual({ error: 'internal error' });
+  });
+
+  it('carries the Lambda request id into the line it logs', async () => {
+    const logs: string[] = [];
+    const handler = makeCreateNoteHandler(
+      stubDeps({
+        notes: { put: () => Promise.reject(new Error('secret detail')) },
+        log: createLogger({}, (line) => logs.push(line)),
+      }),
+    );
+    // Without it a log line cannot be tied to the invocation that produced it.
+    await handler(event(JSON.stringify({ title: 'T' })), lambdaContext('req-42'));
+    expect(JSON.parse(logs[0]!)).toMatchObject({ awsRequestId: 'req-42' });
+  });
 });

package/templates/skeleton/aws-serverless/services/api/test/list-notes.test.ts

@@ -1,4 +1,8 @@
-import type { APIGatewayProxyStructuredResultV2 } from 'aws-lambda';
+import type {
+  APIGatewayProxyEventV2,
+  APIGatewayProxyStructuredResultV2,
+  Context,
+} from 'aws-lambda';
 import { AppError, createLogger } from '@app/shared';
 import { describe, expect, it } from 'vitest';
 import { makeListNotesHandler } from '../src/handlers/list-notes.js';
@@ -14,6 +18,10 @@ const note = {
 
 const asResult = (r: unknown) => r as APIGatewayProxyStructuredResultV2;
 
+/** Lambda always passes the event and the context; this route needs no body. */
+const getEvent = () => ({ isBase64Encoded: false }) as APIGatewayProxyEventV2;
+const lambdaContext = (awsRequestId: string): Context => ({ awsRequestId }) as Context;
+
 describe('listNotesUsecase', () => {
   it('returns what the model lists', async () => {
     expect(await listNotesUsecase({ notes: { list: async () => [note] } })).toEqual([note]);
@@ -49,3 +57,66 @@ describe('GET /notes handler', () => {
     expect(logs.join('')).toContain('secret');
   });
 });
+
+// The same leak create-note was fixed for, and this handler had it too:
+// `AppError` defaults to 500/INTERNAL, so a table name, a host or an SDK
+// message arrives wearing the same type as "title is required", and every one
+// of them used to reach the caller. Typed does not mean safe to show — the
+// status decides, and these pin that both handlers decide it the same way.
+describe('GET /notes keeps its internals to itself', () => {
+  const failWith = (error: unknown, sink: (line: string) => void = () => {}) =>
+    makeListNotesHandler({
+      notes: { list: () => Promise.reject(error) },
+      log: createLogger({}, sink),
+    });
+
+  it('hides a typed error that carries the default status behind a constant 500', async () => {
+    const handler = failWith(new AppError('table NotesTable-prod is not authorised'));
+    const result = asResult(await handler(getEvent(), lambdaContext('req-1')));
+    expect(result.statusCode).toBe(500);
+    expect(result.body).not.toContain('NotesTable-prod');
+    expect(JSON.parse(result.body!)).toEqual({ error: 'internal error' });
+  });
+
+  it('still forwards a 4xx message, which was written for the caller to read', async () => {
+    const handler = failWith(new AppError('unknown tag filter', { statusCode: 400, code: 'BAD' }));
+    const result = asResult(await handler(getEvent(), lambdaContext('req-2')));
+    expect(result.statusCode).toBe(400);
+    expect(JSON.parse(result.body!)).toEqual({ error: 'unknown tag filter', code: 'BAD' });
+  });
+
+  it('logs the internal error it hid with its stack, so the detail is kept and not lost', async () => {
+    const logs: string[] = [];
+    const boom = new AppError('table NotesTable-prod is not authorised');
+    await failWith(boom, (line) => logs.push(line))(getEvent(), lambdaContext('req-3'));
+    // `String(error)` is a message with no frames — not something anyone can
+    // debug from a log aggregator.
+    expect(JSON.parse(logs[0]!)).toMatchObject({ stack: boom.stack });
+  });
+
+  // Same contract as create-note: the response withholds everything about a 5xx
+  // AppError, so the log line is the only place that can still say WHICH
+  // internal failure it was, and `code` is the one field safe to keep verbatim.
+  // The body assertion stays beside it so the two halves cannot drift apart.
+  it('logs the code of the internal error it withheld, and still keeps it out of the response', async () => {
+    const logs: string[] = [];
+    const handler = failWith(
+      new AppError('table NotesTable-prod returned a torn item', { code: 'DATA_CORRUPT' }),
+      (line) => logs.push(line),
+    );
+    const result = asResult(await handler(getEvent(), lambdaContext('req-4')));
+    expect(JSON.parse(logs[0]!)).toMatchObject({ code: 'DATA_CORRUPT' });
+    expect(result.body).not.toContain('DATA_CORRUPT');
+    expect(JSON.parse(result.body!)).toEqual({ error: 'internal error' });
+  });
+
+  it('carries the Lambda request id into the line it logs', async () => {
+    const logs: string[] = [];
+    const handler = failWith(new AppError('table NotesTable-prod is not authorised'), (line) =>
+      logs.push(line),
+    );
+    // Without it a log line cannot be tied to the invocation that produced it.
+    await handler(getEvent(), lambdaContext('req-42'));
+    expect(JSON.parse(logs[0]!)).toMatchObject({ awsRequestId: 'req-42' });
+  });
+});