API security baseline

Every handler that reads a body, query string, path param or header must parse it through a schema (zod, pydantic, JSON Schema…) before the value reaches a service or a query. Passing an unvalidated object straight through is rejected, including when a type annotation claims its shape. A type annotation is a compile-time claim about runtime data you do not control — mass assignment and injection both enter through the gap between the two.

Blocks: an unvalidated boundary is exploitable the day it ships, and it is trivially visible in the diff.

A handler that loads a resource by id must also assert that the resource belongs to the caller — owner, tenant, or an explicit permission check — in the same query or immediately after it. Authenticated is not authorized. Route-level middleware cannot see which row you fetched, so IDOR is the flaw that survives every layer of generic protection.

Blocks: this is the most common exploitable bug in AI-written CRUD code.

Responses are built from an explicit DTO or a named column selection. Returning an entity directly, or spreading one into the response object, is rejected. A `select *` plus a spread leaks whatever column someone adds next — password hashes, internal flags, soft-delete markers — and nothing in the diff that adds the column will look wrong.

Blocks: the leak is silent and retroactive — it appears without anyone editing this file.

A webhook handler verifies the provider signature over the unparsed request body before any parsing, database write, or side effect. Body-parsing middleware must be disabled on those routes. An unverified webhook endpoint is an unauthenticated write endpoint that anyone who reads your docs can call.

Blocks: an unsigned webhook route is a direct path into your write model.

Credentials, API keys and signing secrets are read from the typed config module. A literal secret, a value committed in a fixture, or a `process.env.X || "dev-secret"` style fallback is rejected. A fallback secret becomes the production secret on the first deploy where the environment variable is missing, and nothing fails loudly enough for anyone to notice.

Blocks: a committed or defaulted secret is a disclosure the moment it merges.

The allowed origins are an explicit list from config. Reflecting `req.headers.origin`, or combining a wildcard with credentials, is rejected. Reflecting the caller's origin with credentials enabled removes the same-origin policy for every authenticated route at once.

Blocks: it silently disables the browser protection the rest of the auth design assumes.

API keys, session tokens and signatures are compared with a constant-time function (`crypto.timingSafeEqual`, `hmac.compare_digest`), never `===` or `==`. String comparison returns early on the first differing byte, so the response time leaks how much of the secret the attacker already guessed — and the fix is one function call, so there is no reason to leave the leak there.

Warns rather than blocks: the attack is real but slow and noisy, and the fix is a one-line follow-up.

Any route reachable without a session — login, signup, password reset, public search, magic links — must attach a rate limiter or reference the gateway policy that covers it in a comment. Without one, credential stuffing and reset-email flooding cost the attacker nothing.

Warns: the limiter often lives at the gateway rather than in the diff, so this asks the reviewer to confirm it exists somewhere rather than failing the build.

Client-facing errors carry a stable machine-readable code and a generic message. The stack trace, the failing query and the upstream response body go to the log only. Echoing `err.message` to the client is how connection strings, SQL fragments and internal hostnames end up in a bug report screenshot.

Warns: it is an information leak, not a direct compromise — but it feeds every other attack.

Log an event name and the ids involved. Never log a request body, an authorization header, a token, or a full user record — including inside a catch block. Logs are shipped to third parties and retained far longer than the data policy that covers the database.

Warns: it is a compliance and retention problem rather than an immediate breach.