## ADDED Requirements

### Requirement: Access Token Lifetime
Access tokens SHALL expire 30 minutes after they are issued. The lifetime SHALL be configured per token scope, but SHALL be enforced as a single value shared by every scope — the minimum across the configured scopes — because the underlying token issuer has no per-scope lifetime of its own. With `admin` and `employee` both configured to 30 minutes, this distinction is not currently observable.

#### Scenario: Token expires
- **WHEN** an access token is issued and 30 minutes pass
- **THEN** requests presenting that token are rejected

#### Scenario: Token valid immediately after issuance
- **WHEN** an access token has just been issued and has not reached its expiry
- **THEN** a request presenting that token is authorized

#### Scenario: Both scopes use the same lifetime
- **WHEN** an `admin`-scoped token and an `employee`-scoped token are issued at the same moment
- **THEN** both expire at the same time

### Requirement: Refresh Token Lifetime
Refresh tokens SHALL expire 3 days after they are issued. The lifetime SHALL be configured per token scope, but SHALL be enforced as a single value shared by every scope — the minimum across the configured scopes — for the same reason as the access-token lifetime above. With `admin` and `employee` both configured to 3 days, this distinction is not currently observable.

#### Scenario: Refresh token expires
- **WHEN** a refresh token is issued and 3 days pass without it being used
- **THEN** presenting it is rejected and no new token is issued

### Requirement: Refresh Token Rotation
Refreshing with `grant_type=refresh_token` SHALL return both a new access token and a new refresh token. The refresh token that was presented and the access token it belonged to SHALL both stop working. A refresh token SHALL NOT be usable more than once.

#### Scenario: Refresh returns a new pair
- **WHEN** a client refreshes with a valid refresh token
- **THEN** the response contains a new access token and a new refresh token

#### Scenario: Old refresh token stops working
- **WHEN** a client refreshes with a refresh token and receives a new one
- **THEN** presenting the previous refresh token again is rejected

#### Scenario: Old access token stops working
- **WHEN** a client refreshes a token pair
- **THEN** the access token that was refreshed no longer authorizes requests

### Requirement: Idle Timeout Through Rotation
Each refresh SHALL set the new refresh token's expiry to 3 days from the moment of the refresh, not from the expiry of the token it replaces. A session that is refreshed before its refresh token expires SHALL therefore continue indefinitely, and a session left unused for more than 3 days SHALL require a new login.

#### Scenario: Expiry is recomputed on refresh
- **WHEN** a client refreshes on day 2 of a refresh token's 3-day life
- **THEN** the new refresh token expires 3 days after the refresh, not 1 day after it

#### Scenario: Session in regular use continues
- **WHEN** a client refreshes at least once every 3 days over several months
- **THEN** no new login is required

#### Scenario: Session unused for more than 3 days ends
- **WHEN** a client's most recent refresh token was issued more than 3 days ago and has not been used
- **THEN** a refresh attempt is rejected
- **AND** the user must log in again

### Requirement: Authentication Error Codes
Authentication failures SHALL be returned as HTTP 401 with a body containing an `error` code and a `message`, using distinct codes so a client can tell whether refreshing is worth attempting. The codes SHALL be `invalid_credentials` for a rejected password grant, `token_expired` when the presented access token is a well-formed token whose expiry has passed, `token_invalid` for any other rejected access token, and `session_expired` for a rejected refresh grant.

#### Scenario: Expired access token
- **WHEN** a request presents an access token whose expiry has passed
- **THEN** the response is 401 with `error` = `token_expired`

#### Scenario: Revoked access token
- **WHEN** a request presents an access token that has been revoked but has not yet expired
- **THEN** the response is 401 with `error` = `token_invalid`

#### Scenario: Missing or malformed token
- **WHEN** a request to an authenticated endpoint carries no bearer token, or one that cannot be parsed
- **THEN** the response is 401 with `error` = `token_invalid`

#### Scenario: Rejected refresh
- **WHEN** a request to the login endpoint with `grant_type=refresh_token` is rejected because the refresh token has expired, has been used already, or has been revoked
- **THEN** the response is 401 with `error` = `session_expired`

#### Scenario: Wrong password
- **WHEN** a login request with `grant_type=password` carries an incorrect password
- **THEN** the response is 401 with `error` = `invalid_credentials`

#### Scenario: Error classification does not authorize anything
- **WHEN** a request presents a token that the guard has rejected
- **THEN** the token's contents are used only to choose the error code
- **AND** the request remains unauthorized whatever the token claims

### Requirement: Pre-existing Tokens Are Revoked on Deploy
Access tokens and refresh tokens issued before this change carry a one-year expiry. They SHALL all be revoked when the change is deployed, so that no token issued under the previous policy remains usable.

#### Scenario: Old token stops working
- **WHEN** a client presents an access token issued before the deploy
- **THEN** the request is rejected

#### Scenario: Old refresh token stops working
- **WHEN** a client presents a refresh token issued before the deploy
- **THEN** the refresh is rejected and the user must log in again
