docs

docs/architecture/api/AUTH_FLOW.md

@@ -0,0 +1,47 @@
+# Authentication and Authorization Flow (API)
+
+This document defines how authentication and authorization are enforced in the API.
+
+Shared contract:
+
+- [`docs/architecture/shared/AUTH_CONTRACT.md`](docs/architecture/shared/AUTH_CONTRACT.md:1)
+
+## 1) Enforcement location (strict)
+
+All enforcement happens in the API.
+
+The API must:
+
+- authenticate the actor from the session
+- authorize the actor for the requested capability
+- deny requests deterministically with appropriate HTTP status
+
+## 2) Canonical request flow
+
+```text
+HTTP Request
+  ↓
+Authentication (resolve actor)
+  ↓
+Authorization (roles, permissions, scope)
+  ↓
+Controller (transport-only)
+  ↓
+Core Use Case
+  ↓
+Presenter mapping
+  ↓
+HTTP Response
+```
+
+## 3) Non-negotiable rules
+
+1. Deny by default unless explicitly public.
+2. The actor identity is derived from the session.
+3. Controllers do not contain business rules.
+
+Related:
+
+- Authorization model: [`docs/architecture/api/AUTHORIZATION.md`](docs/architecture/api/AUTHORIZATION.md:1)
+- Guards definition: [`docs/architecture/api/GUARDS.md`](docs/architecture/api/GUARDS.md:1)
+