| name | express-zod-api-hardening |
| description | Build and harden Amy's Echo backend APIs using Express 5 and Zod contracts. Use when adding or modifying server routes, middleware, request validation, auth/profile checks, error handling, and response-shape guarantees. |
Express Zod API Hardening
Apply this skill for server route work to keep API behavior safe and predictable.
1) Design explicit request/response contracts
- Define request schemas with Zod at route boundaries.
- Use strict parsing for params/body/query before business logic.
- Return normalized error payloads for validation failures.
2) Implement Express 5-safe route flow
- Parse and validate request input immediately.
- Execute auth/session checks.
- Execute profile-scope checks when relevant.
- Call domain service.
- Return typed/sanitized response.
- Forward unexpected failures to centralized error handling.
3) Prevent common reliability regressions
- Never allow partial success states after validation/auth failure.
- Keep rate limiting and input size limits in place for mutation endpoints.
- Enforce
401 for expired/invalid auth and 4xx rejection for missing profile context, and terminate the flow before any success response path.
4) Verify route changes
- Run targeted route tests (
npm run test:ts --prefix server -- <route-test>).
- Run server type-check and full tests when contract risk is broad.
- Re-test neighboring routes that share middleware/utilities.
References
- Express and Zod primary docs:
references/official-express-zod-docs.md
- Route hardening checklist:
references/route-hardening-checklist.md
