Skip to content

Security: ForkYeahMan/Azubi_Final_Capstone

Security

docs/security.md

API Security

Research notes and the concrete controls applied to this system's public REST API, organized by pattern.

Threat model, briefly

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.

Authentication & authorization

  • 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/signup only accepts USER or ORGANIZER; PATCH /admin/users/{userId}/role explicitly rejects ADMIN as a target value. See decisions.md.

Input validation & sanitization

  • 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 use ExpressionAttributeValues (parameterized), never string-concatenated user input, so injection into a Dynamo expression isn't possible.
  • HTML-escaping in outbound email (lib/html.ts, used by services/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 by tests/unit/services/email-templates.test.ts.

Rate limiting / throttling

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.

Least-privilege IAM

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 / grantReadWriteData scoped to the specific table(s) a handler touches, driven by the tables field on each RouteDefinition. GET /events never gets write access to the Events table; POST /events/{eventId}/register gets read+write on Events (to adjust registeredCount) 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 one cognito-idp:* action (e.g. login.ts gets only InitiateAuth, not SignUp or AdminCreateUser), scoped to this specific User Pool's ARN — not *.
  • SES: the notification dispatcher's ses:SendEmail is scoped to arn:aws:ses:<region>:<account>:identity/*, not all resources.
  • Cross-stack: the post-confirmation trigger's cognito-idp:AdminAddUserToGroup grant is scoped to userPool.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.

Transport & response hygiene

  • 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 typed ApiError subclasses — 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 generic 500 INTERNAL_ERROR.

What's monitored (see also architecture.md)

  • CloudWatch alarm on API error rate ≥ 5% over a 5-minute window (monitoring-stack.ts, MathExpression over custom ApiErrors/ ApiRequests EMF metrics) — catches slow-burn failures a raw error count threshold misses.
  • Per-Lambda error-count alarms, DynamoDB throttle alarms, and a FailedRegistrations custom metric (capacity conflicts, duplicate registration, registering for a non-approved/past event) all feed the same ops SNS topic.

There aren't any published security advisories