docs

docs/architecture/shared/AUTH_CONTRACT.md

@@ -0,0 +1,51 @@
+# Authentication and Authorization (Shared Contract)
+
+This document defines the shared, cross-app contract for authentication and authorization.
+
+It does not define Next.js routing details or NestJS guard wiring.
+
+App-specific documents:
+
+- API enforcement: [`docs/architecture/api/AUTH_FLOW.md`](docs/architecture/api/AUTH_FLOW.md:1)
+- Website UX flow: [`docs/architecture/website/WEBSITE_AUTH_FLOW.md`](docs/architecture/website/WEBSITE_AUTH_FLOW.md:1)
+
+## 1) Core principle (non-negotiable)
+
+The API is the single source of truth for:
+
+- who the actor is
+- what the actor is allowed to do
+
+The website may improve UX. It does not enforce security.
+
+## 2) Authentication (strict)
+
+Authentication answers:
+
+- who is this actor
+
+Rules:
+
+- the actor identity is derived from the authenticated session
+- the client must never be allowed to claim an identity
+
+## 3) Authorization (strict)
+
+Authorization answers:
+
+- is this actor allowed to perform this action
+
+Rules:
+
+- authorization is enforced in the API
+- the website may hide or disable UI, but cannot enforce correctness
+
+See: [`docs/architecture/api/AUTHORIZATION.md`](docs/architecture/api/AUTHORIZATION.md:1)
+
+## 4) Shared terminology (hard)
+
+- Guard: API enforcement mechanism
+- Blocker: website UX prevention mechanism
+
+Shared contract: [`docs/architecture/shared/BLOCKERS_AND_GUARDS.md`](docs/architecture/shared/BLOCKERS_AND_GUARDS.md:1)
+