security-design

name	security-design
description	Use when designing anything with a trust boundary — auth systems, secrets handling, service-to-service calls, user input surfaces. Design-time security; review-time checks live in the core doctrine.

Security Design

Design-time rules. (Review-time checks — injection, XSS, SSRF, path traversal — already run in the core doctrine's Phase 4 pass; don't duplicate them here.)

Threat model at the boundary

• New trust boundary (new input surface, new caller, new stored credential, new network hop) ⇒ a written 10-minute STRIDE pass in the plan: what can be Spoofed, Tampered, Repudiated, Info-leaked, DoS'd, Elevated. Skipping this is skipping the design.
• Name the assets (what's worth stealing), the actors (who touches the boundary), and the blast radius of each credential before writing the auth code.

Secrets

• Injected at runtime: env vars from a secret manager / KMS, mounted files. Never in code, config files, images, or logs — grep the diff for high-entropy strings and known prefixes (sk-, ghp_, AKIA) in review.
• One secret, one purpose, one owner. Shared "the API key" across services means rotation breaks everything at once.
• Rotation is designed in, not bolted on: two valid credentials during the window (old + new), then revoke.
• .env files are for local dev only and are gitignored; the presence of a real production secret in one is an incident, not a convention.

Authentication

• Service-to-service: mTLS or short-lived signed tokens (OIDC/workload identity). Static shared API keys between services are a migration debt the day they ship.
• Token lifetimes: access tokens ≤ 1 hour; refresh tokens rotate on every use and are revocable server-side. A non-expiring token is a credential leak with a delay.
• Passwords: argon2id/bcrypt via a maintained library, never hand-rolled comparison (timing) or hashing.
• Webhooks verify signatures (HMAC with timestamp, reject old timestamps) — a webhook endpoint without verification is an open command channel.

Authorization

• Deny by default. The absence of a rule is a rejection, not an allow.
• Authz decisions live in one place (middleware/policy layer/service method) — scattered if user.role == checks guarantee one path forgets.
• Check at the resource, not just the route: GET /orders/{id} verifies the order belongs to the caller (IDOR is the most common real-world authz bug).
• Log authz denials with actor + resource + rule — silent denials hide both attacks and misconfigurations.

Data

• Validate input at the boundary (schema, types, ranges); encode output at the sink (HTML-escape at render, parameterize at SQL). Middle layers pass data through untouched.
• PII gets an inventory: which tables, which logs, which backups. You cannot honor deletion requests for data you can't locate.
• Encrypt in transit everywhere (TLS internal too); at rest for anything you'd disclose in a breach notification.

When NOT to apply

Local dev tools and single-user scripts with no network surface: skip mTLS/rotation ceremony. The secrets rules apply everywhere — "it's just a script" is how keys reach GitHub.