# League Actor Model & Permissions (Canonical)

This document defines the canonical backend actor model and the permission rules for **league admin/owner** operations.

It is the source of truth for Subtask 0A in [`plans/league-admin-mvp-plan.md`](plans/league-admin-mvp-plan.md:1).

---

## Session identity (source of truth)

### What the authenticated session contains
- The API authentication layer attaches `request.user.userId` based on the session cookie (`gp_session`).
  - See [`AuthenticationGuard.canActivate()`](apps/api/src/domain/auth/AuthenticationGuard.ts:16).
- The backend uses an async request context (`AsyncLocalStorage`) to make the current request available to services.
  - See [`requestContextMiddleware()`](adapters/http/RequestContext.ts:24).
  - Wired globally for the API via [`AppModule.configure()`](apps/api/src/app.module.ts:49).

### Mapping: `userId` → `driverId`
Current canonical mapping (for MVP):
- The “actor” is derived from session, and `driverId === userId`.
- This is implemented by [`getActorFromRequestContext()`](apps/api/src/domain/auth/getActorFromRequestContext.ts:12).

Rationale:
- The current system uses the session user identity as the same identifier used by racing/league membership repositories (e.g. seeded admin user is `driver-1` in session).
- If/when we introduce a real user ↔ driver relationship (1:N), this function becomes the single authoritative mapping point.

---

## Canonical actor model

The API’s canonical “actor” is:

```ts
type Actor = { userId: string; driverId: string };
```

Returned by [`getActorFromRequestContext()`](apps/api/src/domain/auth/getActorFromRequestContext.ts:12).

Rules:
- All auth/permissions decisions use the actor derived from the authenticated session.
- Controllers and services must never use request-body “performer/admin IDs” for authorization decisions.

---

## League permissions: admin/owner

### Meaning of “league admin/owner”
A driver is authorized as a league admin if:
- They have an **active** membership in the league, and
- Their membership role is either `owner` or `admin`.

Authoritative check:
- Implemented in the core use case [`GetLeagueAdminPermissionsUseCase.execute()`](core/racing/application/use-cases/GetLeagueAdminPermissionsUseCase.ts:39) by loading membership and validating `status` + `role`.

### How it is validated server-side
Canonical enforcement entrypoint (API layer):
- [`requireLeagueAdminOrOwner()`](apps/api/src/domain/league/LeagueAuthorization.ts:15)

This helper:
- Derives the actor from session via [`getActorFromRequestContext()`](apps/api/src/domain/auth/getActorFromRequestContext.ts:12)
- Invokes the core use case with `performerDriverId: actor.driverId`

---

## Contract rule (non-negotiable)

**No league write operation may accept performer/admin IDs for auth decisions.**

Concretely:
- Request DTOs may still temporarily contain IDs for “target entities” (e.g. `targetDriverId`), but never the acting user/admin/performer ID.
- Any endpoint/service that needs “who is performing this” MUST obtain it from session-derived actor, not from request payload, params, or hardcoded values.

Tests:
- Actor derives from session, not payload: [`ActorFromSession`](apps/api/src/domain/auth/ActorFromSession.test.ts:17).
- Permission helper uses session-derived actor consistently: [`ActorFromSession`](apps/api/src/domain/auth/ActorFromSession.test.ts:30).
- Example application in a league write-like operation (`joinLeague`) ignores payload driverId and uses session actor: [`LeagueService`](apps/api/src/domain/league/LeagueService.test.ts:1).

---