feat(jwt): add token revocation via per-user generation counter (ADR-T-007 Phase 4)

Add a `token_generation` column to `torrust_users` and embed a `gen`
claim in every session JWT. Password changes, admin-role grants, and
bans increment the counter, instantly invalidating all outstanding
tokens for that user.

Revocation is checked at three entry points (defence in depth):
- `Authentication::get_user_id_from_bearer_token`
- `verify_token_handler`
- `authentication::Service::renew_token`

Rework the `BearerToken` extractor to reject missing or malformed
`Authorization` headers at the extraction boundary instead of deferring
the check downstream. Remove the `bearer_token::Extract` wrapper and
`get_optional_logged_in_user` free function; the logic now lives
directly in the extractors.

Add `AuthError::TokenRevoked` for revoked-token responses.

Add crate tests for the JWT module (sign/verify round-trips, audience
cross-contamination, tampered tokens) and for `parse_token` (whitespace
trimming, empty bearer, non-ASCII rejection).

Author: peer-cat

CHANGELOG.md

@@ -13,12 +13,60 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - 188 crate-level tests for the domain error system (`src/tests/errors/`):
   status-code mapping, display messages, `From` impl coverage, and
   `ApiError` delegation (ADR-T-006 §1–§4).
+- ADR-T-007: Document rationale for JWT system refactor.
+- Centralised JWT module (`src/jwt.rs`) consolidating all `jsonwebtoken` usage:
+  key loading, signing, verification, and algorithm configuration.
+- `SessionClaims` with RFC 7519 registered claims (`sub`, `iss`, `aud`, `iat`,
+  `exp`) plus advisory `role`, `username`, and revocation `gen` fields.
+- `VerifyClaims` with `aud: "email-verification"` for purpose separation.
+- RSA key pair configuration: `auth.private_key_path` / `auth.public_key_path`
+  (or inline PEM via `auth.private_key_pem` / `auth.public_key_pem`).
+- Development RSA key pair shipped at `share/default/jwt/` with loud startup
+  warning when the default dev keys are detected.
+- `kid` (Key ID) header in every JWT for future key rotation support.
+- Configurable token lifetimes: `auth.session_token_lifetime_secs` (default:
+  2 weeks) and `auth.email_verification_token_lifetime_secs` (default: ~10 years).
+- `token_generation` column on `torrust_users` (migration for SQLite and MySQL).
+- Token revocation: password changes, role changes (admin grant), and bans
+  increment `token_generation`; tokens with an older `gen` claim are rejected.
+- Revocation checks at three entry points (defence in depth):
+  `Authentication::get_user_id_from_bearer_token`, `verify_token_handler`,
+  and `authentication::Service::renew_token`.
+- `BearerToken` extractor rejects missing/malformed `Authorization` headers at
+  the extraction boundary (`AuthError::TokenNotFound` / `AuthError::TokenInvalid`).
+- `ExtractOptionalLoggedInUser` catches extraction rejection and returns `None`
+  for anonymous requests.
+- `AuthError::TokenRevoked` variant for revoked-token responses.
+- Crate tests for the JWT module (session + email-verification round-trips,
+  audience cross-contamination, tampered/garbage tokens).
+- Crate tests for `parse_token` (valid extraction, whitespace trimming,
+  empty bearer, missing prefix, non-ASCII rejection).
 
 ### Changed
 
+- **BREAKING:** JWT signing algorithm changed from HMAC-HS256 to RS256
+  (RSA + SHA-256). Existing HS256 tokens are invalidated; users must re-login.
+- **BREAKING:** JWT claims redesigned from `UserClaims { user, exp }` to
+  `SessionClaims { sub, iss, aud, iat, exp, role, username, gen }`. Existing
+  tokens without the new claims fail deserialization.
+- **BREAKING:** Configuration keys changed — `auth.user_claim_token_pepper` /
+  `auth.session_signing_key` / `auth.email_verification_signing_key` replaced
+  by `auth.private_key_path` and `auth.public_key_path` (or inline PEM).
+  Deployers must generate an RSA key pair.
 - **BREAKING:** Replace `ServiceError` (41 variants) and `ServiceResult` with
   domain-scoped error enums: `AuthError`, `UserError`, `TorrentError`,
   `CategoryTagError`, and a thin `ApiError` wrapper (ADR-T-006).
+- `Authentication::get_user_id_from_bearer_token` now takes `BearerToken`
+  directly instead of `Option<BearerToken>`.
+- `ExtractLoggedInUser` and `ExtractOptionalLoggedInUser` use `BearerToken`
+  directly instead of the old `Extract` wrapper.
+- `parse_token` returns `Result` instead of panicking on malformed headers.
+- JWT `exp` validation relies solely on the `jsonwebtoken` library; redundant
+  manual expiration check removed.
+- Token signing uses `Result` propagation instead of `.unwrap()` / `.expect()`.
+- `UserClaims` is now a type alias for `SessionClaims` (backward-compatible).
+- `VerifyClaims` moved from `mailer` into the `jwt` module (re-exported for
+  backward compatibility).
 - Service functions now return domain-specific `Result<T, DomainError>` instead
   of `Result<T, ServiceError>`.
 - Each domain error co-locates its HTTP status-code mapping via a
@@ -28,6 +76,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Removed
 
+- `bearer_token::Extract` wrapper struct (replaced by `BearerToken` directly).
+- `get_optional_logged_in_user` free function (logic moved into extractors).
+- `get_claims_from_bearer_token` private method on `Authentication` (inlined).
+- `ClaimTokenPepper` / `JwtSigningSecret` / `user_claim_token_pepper` config
+  keys (replaced by RSA key pair configuration).
 - `ServiceError` enum and `ServiceResult` type alias from `src/errors.rs`.
 - `http_status_code_for_service_error` and `map_database_error_to_service_error`
   helper functions.

adr/007-jwt-system-refactor.md

@@ -1,6 +1,6 @@
 # ADR-T-007: Refactor the JWT System
 
-**Status:** Phase 3 implemented
+**Status:** Phase 4 implemented
 **Date:** 2026-04-14
 
 ## Context
@@ -340,9 +340,8 @@ phased rollout that subsumes Options A and B.
   does not currently need instant revocation badly enough to
   justify the infrastructure cost and loss of statelessness.
 - **Option E (hybrid revocation):** The `token_generation` column
-  approach is elegant but adds complexity that can be layered on
-  later without changing the token format. It remains a valid
-  follow-up if revocation becomes a priority.
+  approach was originally deferred but has since been implemented
+  in Phase 4. See the Phase 4 section below.
 
 ### Implementation Phases
 
@@ -384,7 +383,9 @@ phased rollout that subsumes Options A and B.
   authenticated request (the authorization service already does
   this via `get_role`) so the token role is advisory only.
 - ✅ Enforce a minimum secret length (32 bytes) at config
-  validation time.
+  validation time. *(With Phase 3's move to RS256, this is now
+  enforced implicitly: `EncodingKey::from_rsa_pem` /
+  `DecodingKey::from_rsa_pem` reject invalid PEM at startup.)*
 - **Breaking change:** existing HS256 tokens are invalidated;
   users must re-login.
 
@@ -408,14 +409,23 @@ phased rollout that subsumes Options A and B.
   no longer supported. Deployers must generate an RSA key pair
   and update their configuration.
 
-#### Future — Optional Revocation (Option E scope)
-
-- Add a `token_generation` column to `torrust_users`.
-- Include `gen` in `SessionClaims`; reject stale generations on
-  verify.
-- Increment generation on password change, role change, or ban.
-- This phase is independent and can be shipped whenever revocation
-  becomes a priority.
+#### Phase 4 — Optional Revocation (Option E scope) ✅ Implemented
+
+- ✅ Add a `token_generation` column (default `0`) to
+  `torrust_users`.
+- ✅ Include `gen` in `SessionClaims`; reject tokens whose `gen`
+  is older than the current database value.
+- ✅ Increment `token_generation` on password change, role change
+  (admin grant), and ban.
+- ✅ Validation performed in the `Authentication` web layer
+  (`get_user_id_from_bearer_token`), the `verify_token_handler`,
+  and the `renew_token` service method.
+  *Defence in depth:* the generation check is intentionally
+  repeated at each entry point rather than consolidated into a
+  single layer, so that no call path can accidentally bypass
+  revocation.
+- **Breaking change:** existing tokens without a `gen` claim will
+  fail deserialization and be rejected (users re-login once).
 
 ### Configuration Migration
 
@@ -438,10 +448,25 @@ A migration guide will accompany the release that ships Phase 3.
 - Deployers must generate and manage an RSA key pair (Phase 3).
   A development-mode auto-generated key reduces friction for
   local setups.
-- Token revocation is **not** included in the initial scope but
-  the architecture cleanly supports adding it later (Phase 4 /
-  Option E).
+- Token revocation via a `token_generation` counter is included
+  (Phase 4 / Option E). Password changes, role changes, and bans
+  increment the counter and invalidate outstanding tokens.
 - The centralised `jwt` module makes future algorithm changes
   (e.g., migrating to EdDSA) a localised, single-module change.
 - External services can verify tokens using only the public key,
   enabling zero-trust verification without secret sharing.
+
+## Remaining Issues
+
+- **Problem #11 (`BearerToken` extractor returns `Ok(None)`).**
+  ✅ **Resolved.** The `BearerToken` extractor now implements
+  `FromRequestParts` directly and **rejects** missing
+  (`AuthError::TokenNotFound`) or malformed
+  (`AuthError::TokenInvalid`) `Authorization` headers at the
+  extraction boundary. The `Extract` wrapper has been removed.
+  `ExtractLoggedInUser` uses `BearerToken` directly (fails if
+  missing). `ExtractOptionalLoggedInUser` catches the rejection
+  and returns `None` for anonymous requests.
+  `Authentication::get_user_id_from_bearer_token` now takes
+  `BearerToken` (not `Option<BearerToken>`), eliminating the
+  `None`-handling indirection.

migrations/mysql/20260414000000_torrust_user_token_generation.sql

@@ -0,0 +1 @@
+ALTER TABLE torrust_users ADD COLUMN token_generation BIGINT NOT NULL DEFAULT 0

migrations/sqlite3/20260414000000_torrust_user_token_generation.sql

@@ -0,0 +1 @@
+ALTER TABLE torrust_users ADD COLUMN token_generation INTEGER NOT NULL DEFAULT 0

src/app.rs

@@ -74,7 +74,7 @@ pub async fn run(configuration: Configuration, api_version: &Version) -> Running
 
     let database = Arc::new(database::connect(&database_connect_url).await.expect("Database error."));
     let json_web_token = Arc::new(JsonWebToken::new(configuration.clone()).await);
-    let auth = Arc::new(Authentication::new(json_web_token.clone()));
+    let auth = Arc::new(Authentication::new(json_web_token.clone(), database.clone()));
 
     // Repositories
     let category_repository = Arc::new(DbCategoryRepository::new(database.clone()));
@@ -154,6 +154,7 @@ pub async fn run(configuration: Configuration, api_version: &Version) -> Running
     let authentication_service = Arc::new(Service::new(
         configuration.clone(),
         json_web_token.clone(),
+        database.clone(),
         user_repository.clone(),
         user_profile_repository.clone(),
         user_authentication_repository.clone(),

src/config/v2/auth.rs

@@ -15,10 +15,13 @@ const DEFAULT_PUBLIC_KEY_PATH: &str = "./share/default/jwt/public.pem";
 
 /// Authentication options.
 ///
-/// ## Phase 3 (ADR-T-007)
+/// ## JWT signing (ADR-T-007)
 ///
-/// JWT signing has moved from HMAC-HS256 with shared secrets to
-/// RS256 (RSA + SHA-256) with a public/private key pair.
+/// JWT signing uses RS256 (RSA + SHA-256) with a public/private key
+/// pair. Session and email-verification tokens share the same key
+/// pair; purpose separation is via the `aud` claim. A per-user
+/// `token_generation` counter enables near-instant revocation on
+/// password change, role change, or ban.
 ///
 /// Configuration supports two mechanisms (in priority order):
 ///

src/databases/database.rs

@@ -238,6 +238,13 @@ pub trait Database: Sync + Send {
     /// Grant a user the administrator role.
     async fn grant_admin_role(&self, user_id: i64) -> Result<(), Error>;
 
+    /// Get the current `token_generation` counter for a user.
+    async fn get_token_generation(&self, user_id: i64) -> Result<u64, Error>;
+
+    /// Increment the `token_generation` counter for a user, invalidating
+    /// all outstanding session tokens.
+    async fn increment_token_generation(&self, user_id: i64) -> Result<(), Error>;
+
     /// Verify a user's email with `user_id`.
     async fn verify_email(&self, user_id: i64) -> Result<(), Error>;
 

src/databases/mysql.rs

@@ -299,6 +299,30 @@ impl Database for Mysql {
             })
     }
 
+    async fn get_token_generation(&self, user_id: i64) -> Result<u64, database::Error> {
+        query_as("SELECT token_generation FROM torrust_users WHERE user_id = ?")
+            .bind(user_id)
+            .fetch_one(&self.pool)
+            .await
+            .map(|(v,): (i64,)| u64::try_from(v).unwrap_or(0))
+            .map_err(|_| database::Error::UserNotFound)
+    }
+
+    async fn increment_token_generation(&self, user_id: i64) -> Result<(), database::Error> {
+        query("UPDATE torrust_users SET token_generation = token_generation + 1 WHERE user_id = ?")
+            .bind(user_id)
+            .execute(&self.pool)
+            .await
+            .map_err(|_| database::Error::Error)
+            .and_then(|v| {
+                if v.rows_affected() > 0 {
+                    Ok(())
+                } else {
+                    Err(database::Error::UserNotFound)
+                }
+            })
+    }
+
     async fn verify_email(&self, user_id: i64) -> Result<(), database::Error> {
         query("UPDATE torrust_user_profiles SET email_verified = TRUE WHERE user_id = ?")
             .bind(user_id)

src/databases/sqlite.rs

@@ -295,6 +295,30 @@ impl Database for Sqlite {
             })
     }
 
+    async fn get_token_generation(&self, user_id: i64) -> Result<u64, database::Error> {
+        query_as("SELECT token_generation FROM torrust_users WHERE user_id = ?")
+            .bind(user_id)
+            .fetch_one(&self.pool)
+            .await
+            .map(|(v,): (i64,)| u64::try_from(v).unwrap_or(0))
+            .map_err(|_| database::Error::UserNotFound)
+    }
+
+    async fn increment_token_generation(&self, user_id: i64) -> Result<(), database::Error> {
+        query("UPDATE torrust_users SET token_generation = token_generation + 1 WHERE user_id = ?")
+            .bind(user_id)
+            .execute(&self.pool)
+            .await
+            .map_err(|_| database::Error::Error)
+            .and_then(|v| {
+                if v.rows_affected() > 0 {
+                    Ok(())
+                } else {
+                    Err(database::Error::UserNotFound)
+                }
+            })
+    }
+
     async fn verify_email(&self, user_id: i64) -> Result<(), database::Error> {
         query("UPDATE torrust_user_profiles SET email_verified = TRUE WHERE user_id = ?")
             .bind(user_id)

src/errors.rs

@@ -36,6 +36,9 @@ pub enum AuthError {
     #[error("Token invalid.")]
     TokenInvalid,
 
+    #[error("Token has been revoked. Please sign in again.")]
+    TokenRevoked,
+
     #[error("Unauthorized action.")]
     UnauthorizedAction,
 
@@ -70,6 +73,7 @@ impl AuthError {
             Self::TokenNotFound
             | Self::TokenExpired
             | Self::TokenInvalid
+            | Self::TokenRevoked
             | Self::LoggedInUserNotFound
             | Self::UnauthorizedActionForGuests => StatusCode::UNAUTHORIZED,
             Self::InternalServerError | Self::DatabaseError => StatusCode::INTERNAL_SERVER_ERROR,