gridpilot.gg/docs/architecture/shared/AUTH_CONTRACT.md

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
• Website UX flow: docs/architecture/website/WEBSITE_AUTH_FLOW.md

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

4) Shared terminology (hard)

• Guard: API enforcement mechanism
• Blocker: website UX prevention mechanism

Shared contract: docs/architecture/shared/BLOCKERS_AND_GUARDS.md