Section 03 · Infrastructure & Setup
Authentication & Endpoints
Auth system simplicity, documentation, testing, and HTTP endpoint security
This guide walks you through auditing a project's authentication system and HTTP endpoint security.
The Goal: Secure by Default
Authentication should be simple enough to explain in two sentences, yet robust enough to withstand scrutiny. Every endpoint should be protected unless explicitly marked public, and the system should fail fast before wasting resources on unauthorized requests.
- Simple — auth flow explainable in 2-3 sentences, single entry point
- Documented — auth system described for developers and AI agents
- Tested — comprehensive tests covering happy paths and failure cases
- Default-deny — endpoints protected unless explicitly public
- Fail-fast — auth validated before any expensive operations
- Verified — webhooks validate signatures before processing payloads
Before You Start
- Confirm you're in the target repository's root directory
- Complete AUTH-001 first - tracing the auth flow informs all other checks
- Have the user available for questions about auth architecture and external services
auth-system
Auth flow can be explained in 2-3 sentences, single entry point, obvious from code
“Explain your auth flow in 2 sentences — can you?”
Auth flow documented in README, docs/, or inline; matches actual implementation
“Does the auth documentation match what the code actually does?”
Auth source in repo (not compiled), no undocumented external dependencies
“Is auth logic readable in the repo, or buried in a black box?”
Tests cover login, logout, expiry, invalid tokens, unauthorized access
“What happens if someone sends an expired token — tested?”
http-endpoints
OpenAPI/Swagger or markdown docs exist, not exposed in production unless intentional
“Is /api-docs exposed to the public on your production app?”
Routes listable via CLI or centralized files, no dynamic registration
“Can you list every route in this app in under 30 seconds?”
Default-deny pattern, authorization checks for privileged routes
“Is every new route secure by default, or opt-in?”
No DB queries, file uploads, or external calls before auth check
“Could a bad actor hammer your DB before auth even runs?”
JWT signature or cached session lookup, no DB hit per request
“Every request hitting the DB just to verify who you are?”
All webhooks verify signatures before processing, or are behind Zero Trust
“Could anyone POST fake events to your webhook endpoints?”