Context examples

# JWT Authentication Middleware

**Context ID:** ctx_a1b2c3d4
**Saved by:** @john
**Agent:** claude-code (claude-sonnet-4-6)
**Repository:** acme/backend
**Branch:** feature/auth-middleware
**Date:** 2026-02-22T15:30:00Z

## Prompt
> Add JWT authentication to the login endpoint. Use the jsonwebtoken library.
> Tokens should expire after 24 hours. Protect the /api/users and /api/orders routes.

## What Was Done
- Created `src/auth/middleware.ts` — verifies JWT tokens on protected routes
- Created `src/auth/tokens.ts` — handles token signing and validation logic
- Modified `src/routes/login.ts` — added token generation on successful login
- Modified `src/routes/index.ts` — applied auth middleware to /api/users and /api/orders
- Updated `package.json` — added jsonwebtoken 9.0.2 and @types/jsonwebtoken

## Reasoning
Chose stateless JWT tokens over server-side sessions because the service is
API-only with no browser-based frontend. Server-side sessions would require
a session store (Redis or database table), adding infrastructure we don't need.
JWT tokens are self-contained and allow horizontal scaling without session
synchronization between instances.

RS256 (asymmetric) was chosen over HS256 (symmetric) to allow token verification
by downstream services without sharing the signing secret. The private key signs;
any service with the public key can verify.

## Key Decisions
- **Token expiry:** 24 hours — long enough for a full work day, short enough to limit
  exposure if a token is compromised. The internal tool has no "remember me" requirement.
- **Algorithm:** RS256 — enables key rotation by issuing a new private key without
  updating all consumers. HS256 would require updating every service simultaneously.
- **No refresh tokens in v1** — simplifies the implementation and reduces attack surface.
  If session persistence becomes a requirement, add refresh tokens then.
- **Middleware placement:** Applied at the router level (not individual route handlers)
  so new routes are protected by default unless explicitly opted out.

## Rejected Alternatives
- **Session cookies:** Requires a session store. Not suitable for this API-only service
  that needs to run stateless across multiple instances.
- **OAuth2 with an external provider (Auth0, Cognito):** Considered but rejected as
  overkill for an internal tool. Adds external dependency, cost, and configuration
  complexity that isn't justified for the current team size.
- **Paseto tokens (v2 local):** Technically better security properties than JWT, but the
  team has no familiarity with it and the jsonwebtoken library is mature and well-audited.
  Not worth the learning curve for an internal service.
- **API keys (static):** Considered for simplicity. Rejected because we need per-user
  identity tracking for the audit log requirement in FR-42.

## Risks & Open Questions
- **No rate limiting on the login endpoint.** A brute-force attack could enumerate
  passwords. Should add before going to production. Tracked in issue #88.
- **Token revocation not implemented.** A compromised token is valid until expiry (24h).
  Acceptable risk for an internal tool; would need a token blacklist or short-lived tokens
  with refresh if this becomes a customer-facing service.
- **Key rotation process not documented.** The RS256 approach enables rotation, but the
  runbook for actually rotating keys hasn't been written. @sarah to document before launch.

## Files
- `src/auth/middleware.ts` — new — JWT verification middleware; rejects requests with
  missing, expired, or invalid tokens with 401
- `src/auth/tokens.ts` — new — `signToken(userId)` and `verifyToken(token)` exports
- `src/routes/login.ts` — modified — calls `signToken(user.id)` and returns token in response
- `src/routes/index.ts` — modified — applies `authMiddleware` to /api/users and /api/orders
- `package.json` — modified — jsonwebtoken 9.0.2, @types/jsonwebtoken 9.0.7
- `keys/` — new directory — RS256 private and public keys (gitignored)

## Commits
- `a1b2c3d` Add JWT token signing and verification
- `d4e5f6a` Wire auth middleware to protected routes
- `e7f8g9h` Add login endpoint token generation
- `b0c1d2e` Add RS256 key generation script

## Verification
- All 14 unit tests passing
- Integration test: POST /login → 200, token returned
- Integration test: GET /api/users without token → 401
- Integration test: GET /api/users with valid token → 200
- Integration test: GET /api/users with expired token → 401
- Build: clean, no TypeScript errors