Research notes and the concrete controls applied to this system's public REST API, organized by pattern.
The API is public (any client can reach GET /events, and /auth/* must
accept unauthenticated traffic by definition). The realistic risks for a
system like this are: credential stuffing / signup spam against /auth/*,
casual scraping/volumetric abuse of public read endpoints, privilege
escalation (a User calling an Admin/Organizer-only action), injected
content surfacing in emails or client UIs, and an over-permissioned Lambda
turning one bug into a wider blast radius. Each is addressed below.
- Amazon Cognito JWT authorizer on every non-public route
(
api-stack.ts) — API Gateway validates the token's signature, expiry, and audience before the Lambda ever runs; a request with no token or a tampered one never reaches application code. - Defense in depth on top of the authorizer: each handler still calls
requireRole(ctx, ...)(lib/auth-context.ts) and, where relevant, the service layer checks resource ownership (event.organizerId === ctx.userId). A route wired to the wrong authorizer scope isn't the only thing standing between a User and an Admin action. - No self-service path to ADMIN.
/auth/signuponly acceptsUSERorORGANIZER;PATCH /admin/users/{userId}/roleexplicitly rejectsADMINas a target value. See decisions.md.
- Every request body and query string is parsed through a Zod schema
(
lib/validation.ts) before touching business logic — unknown/malformed input never reaches a service or repository. DynamoDB calls always useExpressionAttributeValues(parameterized), never string-concatenated user input, so injection into a Dynamo expression isn't possible. - HTML-escaping in outbound email (
lib/html.ts, used byservices/email-templates.ts): event titles and rejection reasons are organizer/admin-supplied free text that ends up embedded in HTML emails sent to other users. Without escaping, a title like<img src=x onerror=...>would be injected verbatim into a Registration or Rejection email. Covered bytests/unit/services/email-templates.test.ts.
HTTP API's built-in throttling is configured per stage and per route in
api-stack.ts:
- A baseline of 50 req/s (burst 100) applies to the whole API —
enough for normal use, low enough to blunt casual scraping of the
public
GET /events/GET /events/{eventId}endpoints. /auth/*routes are throttled to 5 req/s (burst 10) specifically — tighter, because these are the highest-value target for credential stuffing, automated signup spam, and password-reset-code enumeration.
This is a cheap, no-extra-infrastructure mitigation. AWS WAF (rate-based rules, managed rule groups for known bad actors) was considered and is the natural next step for a production deployment, but was left out here to stay inside Free Tier — WAF Web ACLs and rules carry an hourly charge that API Gateway throttling doesn't.
Every Lambda gets exactly the permissions its route needs, computed per
route in api-stack.ts's applyGrants() — nothing is attached at a
shared/stack level:
- DynamoDB:
grantReadData/grantWriteData/grantReadWriteDatascoped to the specific table(s) a handler touches, driven by thetablesfield on eachRouteDefinition.GET /eventsnever gets write access to the Events table;POST /events/{eventId}/registergets read+write on Events (to adjustregisteredCount) but only write on Registrations (it never needs to read one back). - SNS:
notificationsTopic.grantPublish(fn)only for the three routes that actually publish (register,cancel-registration,admin/review-event). - Cognito: each
/auth/*Lambda gets exactly onecognito-idp:*action (e.g.login.tsgets onlyInitiateAuth, notSignUporAdminCreateUser), scoped to this specific User Pool's ARN — not*. - SES: the notification dispatcher's
ses:SendEmailis scoped toarn:aws:ses:<region>:<account>:identity/*, not all resources. - Cross-stack: the post-confirmation trigger's
cognito-idp:AdminAddUserToGroupgrant is scoped touserPool.userPoolArn, not every pool in the account.
CDK's L2 grant*() helpers generate the underlying least-privilege IAM
policy automatically (resource ARN + minimal action list) — see
decisions.md
for why that was a factor in choosing CDK over hand-written Terraform IAM
documents.
- API Gateway (HTTP API) is HTTPS-only by default — there is no HTTP listener to disable.
- CORS is currently
allowOrigins: ['*'](api-stack.ts) since no frontend origin exists yet — tighten this to the actual frontend origin(s) once the frontend is built, tracked as a follow-up. - Error responses are a fixed
{ error: { code, message } }shape (lib/http.ts) built from typedApiErrorsubclasses — internal details (stack traces, AWS SDK error internals) are logged to CloudWatch via Powertools but never returned to the client. Unhandled exceptions always map to a generic500 INTERNAL_ERROR.
What's monitored (see also architecture.md)
- CloudWatch alarm on API error rate ≥ 5% over a 5-minute window
(
monitoring-stack.ts,MathExpressionover customApiErrors/ApiRequestsEMF metrics) — catches slow-burn failures a raw error count threshold misses. - Per-Lambda error-count alarms, DynamoDB throttle alarms, and a
FailedRegistrationscustom metric (capacity conflicts, duplicate registration, registering for a non-approved/past event) all feed the same ops SNS topic.