admin/_docs/02_tasks/todo/AZ-535_logout_revocation.md

Logout Endpoint + Revocation Surface for Verifiers

Task: AZ-535_logout_revocation Name: Logout endpoint + revocation surface for verifiers Description: Add POST /logout, POST /logout/all, admin-only POST /sessions/{sid}/revoke, and a GET /sessions/revoked?since=<ts> snapshot endpoint that verifiers (satellite-provider, gps-denied, ui) poll to maintain a local denylist. Without this, JWTs cannot be revoked before exp. Complexity: 3 points Dependencies: AZ-531 (needs the sessions table); coordinate jti/sid claim stamping Component: Admin API + Services + DataAccess Tracker: AZ-535 Epic: AZ-529

Problem

With stateless JWT validation, logout doesn't actually exist. Calling /logout on admin can clear admin's session, but satellite-provider, gps-denied, and any other verifier keep accepting the same token until exp. There is no way to forcibly kick a session in real time (e.g. "GPS permission revoked, end the flight").

Outcome

• POST /logout endpoint: revokes the caller's current session (refresh + all access tokens minted from it). Idempotent.
• POST /logout/all endpoint: revokes every session for the caller's user (full "sign out everywhere").
• POST /sessions/{sid}/revoke (admin-only): revoke any session by id ("GPS permission revoked, kill flight UAV-117 mission M-042").
• Verifiers consume revocation via either:
  • Pull mode (default): GET /sessions/revoked?since=<unix-ts> returns [{ jti, sid, exp }]. Verifiers poll every 30 s and maintain a local denylist with TTL = token's remaining lifetime.
  • Push mode (optional): a Redis pub/sub channel auth:revoked for sub-second propagation. Pull is mandatory; push is best-effort acceleration.

Scope

Included

• POST /logout, POST /logout/all, POST /sessions/{sid}/revoke handlers in Azaion.AdminApi/Program.cs.
• GET /sessions/revoked?since=<ts> endpoint authenticated via service-to-service JWT issued to each verifier identity (each verifier has a dedicated Role=Service user).
• Update sessions table with revoked_at, revoked_reason, revoked_by_user_id (these columns may already be present from AZ-531; if so, this ticket only adds revoked_by_user_id).
• Snapshot endpoint must auto-prune entries whose exp < now() so the response stays bounded.
• Tests: logout works, all-logout works, admin-revoke works, revoked endpoint returns recent revocations and excludes expired.

Excluded

• Verifier-side denylist consumption (per-verifier ticket, filed when admin ships).
• Redis pub/sub push channel — nice-to-have; pull-based snapshot is the contract.
• Per-permission revocation in real time (e.g. "revoke just GPS, keep session alive") — architecturally requires moving permissions out of the JWT; future ticket.

Acceptance Criteria

AC-1: /logout revokes the session Given a valid access + refresh token pair When POST /logout is called with the access token Then the session row is marked revoked_at=now(), revoked_reason='user_logout'. The refresh token stops working.

AC-2: /logout/all revokes every session for the user Given user U has 3 active sessions When POST /logout/all is called from any one of them Then all 3 sessions are revoked.

AC-3: Admin can revoke any session by id Given user U has session SID-X When an Admin-role JWT calls POST /sessions/SID-X/revoke Then SID-X is marked revoked with revoked_by_user_id = the admin's id.

AC-4: /sessions/revoked snapshot returns recent revocations Given 5 sessions revoked in the last hour, 2 of which already expired When GET /sessions/revoked?since=<1h-ago> is called by an authenticated verifier Then response is the 3 non-expired ones, with [{ jti, sid, exp }]. Cache-Control: no-cache (this is real-time data).

AC-5: Idempotent logout Given a session already revoked When POST /logout is called again with the same token Then 200 with { already_revoked: true }. No DB write.

Blackbox Tests

AC Ref	Initial Data/Conditions	What to Test	Expected Behavior	NFR References
AC-1	Active session	POST /logout	Session revoked, refresh dead	—
AC-2	User with 3 sessions	POST /logout/all from any	All 3 revoked	—
AC-3	Admin JWT, target SID-X	POST /sessions/SID-X/revoke	SID-X revoked with admin id	—
AC-4	5 revoked (2 expired)	GET /sessions/revoked?since=…	Returns 3 non-expired	—
AC-5	Already-revoked session	POST /logout again	200 already_revoked, no DB write	—

Risks / Notes

• The pull endpoint must NOT leak revocations across users to non-admin callers. Verifier identity is service-level (each verifier has a dedicated Role=Service user with read-revocations permission); they get the global feed. Regular users only see their own sessions if a future endpoint is added.
• 30 s polling means up to 30 s of "stale token works" after logout. Documented as acceptable; for sub-second, deploy the optional Redis push.
• Coordinate auto-prune cadence to keep snapshot < 5 KB even at high revocation rates.