# auth-token-revocation Specification

## Purpose
TBD - created by archiving change add-session-expiry. Update Purpose after archive.
## Requirements
### Requirement: Logout Revokes the Caller's Tokens
The API SHALL provide an authenticated endpoint that revokes the access token the request was made with, together with the refresh tokens issued alongside it. Revoking an access token that is already revoked SHALL be a no-op rather than an error.

#### Scenario: Logging out
- **WHEN** an authenticated client calls the logout endpoint
- **THEN** the response is a success
- **AND** subsequent requests with that access token are rejected

#### Scenario: Refresh token dies with the access token
- **WHEN** a client logs out and then presents the refresh token it was holding
- **THEN** the refresh is rejected and no new token is issued

#### Scenario: Other devices are untouched
- **WHEN** an account is logged in on two devices and logs out on one
- **THEN** requests from the other device are still authorized

#### Scenario: Revoking an already-revoked token is a no-op
- **WHEN** the access token an authenticated request resolves to has already been revoked at the database level
- **THEN** marking it revoked again does not raise an error and the request's own outcome is unaffected by it

#### Scenario: Logout requires authentication
- **WHEN** the logout endpoint is called without a valid access token
- **THEN** the request is rejected and nothing is revoked

### Requirement: Token Revocation Covers Refresh Tokens
Wherever the system revokes an account's access tokens, it SHALL also revoke the refresh tokens issued alongside those access tokens. This SHALL hold for every existing revocation trigger, including password reset, an administrator updating or deactivating an account, and changes to an account's roles. After revocation it SHALL NOT be possible to obtain a new access token from a refresh token issued before it.

#### Scenario: Password reset closes the refresh path
- **WHEN** an account's password is reset
- **THEN** its access tokens are revoked
- **AND** presenting a refresh token issued before the reset does not yield a new access token

#### Scenario: Deactivated account cannot refresh back in
- **WHEN** an administrator deactivates an account
- **THEN** a refresh attempt with a previously issued refresh token is rejected

#### Scenario: Revocation of many accounts at once
- **WHEN** tokens are revoked for several accounts in one operation
- **THEN** the refresh tokens of every one of those accounts are revoked as well

### Requirement: Revocation Keeps Its Existing Scope and Exception Filters
Revocation SHALL keep honouring the scope filter and the excepted-token list it already accepts. Only refresh tokens belonging to access tokens that are actually revoked SHALL be revoked.

#### Scenario: Scope-limited revocation
- **WHEN** revocation is requested for the `admin` scope only, and an account holds one `admin` token and one `employee` token
- **THEN** the `admin` token and its refresh token are revoked
- **AND** the `employee` token and its refresh token still work

#### Scenario: Current token preserved
- **WHEN** an administrator updates their own account with the option that keeps the current token alive
- **THEN** that access token and its refresh token still work
- **AND** the account's other tokens and their refresh tokens are revoked
