refactor(jwt): implement ADR-T-007 Phase 2 — per-purpose signing keys and RFC 7519 claims

Split the single shared JWT signing secret into two separate keys:
`session_signing_key` and `email_verification_signing_key`, so a
compromise of one key does not affect the other token type.

Session tokens (`SessionClaims`, née `UserClaims`) now carry proper
RFC 7519 registered claims: `sub` (user ID), `iss` ("torrust-index"),
`aud` ("session"), `iat`, and `exp`. The `role` and `username` fields
are advisory only — the authoritative role is always re-checked from
the database on each authenticated request.

Email-verification tokens (`VerifyClaims`) gain an `aud`
("email-verification") claim and `iat`, and are now validated with
audience + issuer checks by the `jsonwebtoken` library instead of a
manual `iss` string comparison.

Other changes:
- Enforce a 32-byte minimum length on `JwtSigningSecret`.
- Accept `jwt_signing_secret` and `user_claim_token_pepper` as legacy
  serde aliases for `session_signing_key` for backward compatibility.
- Provide `UserClaims` as a type alias so existing imports keep
  compiling.
- Update all config files, doc examples, and tests.

Ref: ADR-T-007

Author: peer-cat

.env.local

@@ -1,6 +1,7 @@
 DATABASE_URL=sqlite://storage/database/data.db?mode=rwc
 TORRUST_INDEX_CONFIG_TOML=
-TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__JWT_SIGNING_SECRET=MaxVerstappenWC2021
+TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__SESSION_SIGNING_KEY=MaxVerstappenWC2021-session-key!
+TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__EMAIL_VERIFICATION_SIGNING_KEY=MaxVerstappenWC2021-emailverify!
 USER_ID=1000
 TORRUST_TRACKER_CONFIG_TOML=
 TORRUST_TRACKER_CONFIG_OVERRIDE_CORE__DATABASE__DRIVER=Sqlite3

README.md

@@ -95,14 +95,15 @@ TORRUST_INDEX_CONFIG_TOML=$(cat "./storage/index/etc/index.toml") cargo run
 
 _For deployment, you __should__ override:
 
-- The `tracker_api_token` and the `index_auth_jwt_signing_secret` by using environmental variables:_
+- The `tracker_api_token` and the JWT signing keys by using environmental variables:_
 
 ```sh
 # Please use the secret that you generated for the torrust-tracker configuration.
-# Override secret in configuration using an environmental variable
+# Override secrets in configuration using environmental variables
 TORRUST_INDEX_CONFIG_TOML=$(cat "./storage/index/etc/index.toml") \
   TORRUST_INDEX_CONFIG_OVERRIDE_TRACKER__TOKEN=$(cat "./storage/tracker/lib/tracker_api_admin_token.secret") \
-  TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__JWT_SIGNING_SECRET="MaxVerstappenWC2021" \
+  TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__SESSION_SIGNING_KEY="your-session-signing-secret-here!" \
+  TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__EMAIL_VERIFICATION_SIGNING_KEY="your-email-verify-secret-here!!" \
   cargo run
 ```
 
@@ -127,7 +128,7 @@ The following services are provided by the default configuration:
 - [ADR-T-004: Remove `located-error` Package](adr/004-remove-located-error.md) — Replace the `torrust-index-located-error` wrapper with `tracing` for error context.
 - [ADR-T-005: Migrate to Rust Edition 2024](adr/005-edition-2024.md) — Migrate the entire workspace to `edition = "2024"` and raise the MSRV to 1.85.
 - [ADR-T-006: Refactor the Error System](adr/006-error-system-refactor.md) — Replace the 41-variant `ServiceError` god enum with domain-scoped error enums (`AuthError`, `UserError`, `TorrentError`, `CategoryTagError`) and a thin `ApiError` wrapper.
-- [ADR-T-007: Refactor the JWT System](adr/007-jwt-system-refactor.md) — Centralise JWT handling into `src/jwt.rs`, rename `ClaimTokenPepper` → `JwtSigningSecret`, make token lifetimes configurable, and fix panics in token parsing.
+- [ADR-T-007: Refactor the JWT System](adr/007-jwt-system-refactor.md) — Centralise JWT handling into `src/jwt.rs`, redesign claims to RFC 7519, split into per-purpose signing keys, and enforce minimum secret length.
 
 ## Contributing
 

adr/007-jwt-system-refactor.md

@@ -1,6 +1,6 @@
 # ADR-T-007: Refactor the JWT System
 
-**Status:** Phase 1 implemented
+**Status:** Phase 2 implemented
 **Date:** 2026-04-14
 
 ## Context
@@ -362,9 +362,9 @@ phased rollout that subsumes Options A and B.
   `session_token_lifetime_secs`,
   `email_verification_token_lifetime_secs`.
 
-#### Phase 2 — Claim Redesign + Per-Purpose Keys (Option B scope)
+#### Phase 2 — Claim Redesign + Per-Purpose Keys (Option B scope) ✅ Implemented
 
-- Redesign `UserClaims` → `SessionClaims`:
+- ✅ Redesign `UserClaims` → `SessionClaims`:
   ```rust
   struct SessionClaims {
       sub: UserId,      // subject = user ID
@@ -376,14 +376,15 @@ phased rollout that subsumes Options A and B.
       username: String, // convenience, non-authoritative
   }
   ```
-- Redesign `VerifyClaims` with `aud: "email-verification"`.
-- Split config into two independent keys:
+- ✅ Redesign `VerifyClaims` with `aud: "email-verification"`.
+- ✅ Split config into two independent keys:
   `auth.session_signing_key` and
   `auth.email_verification_signing_key`.
-- Re-validate the user's role from the database on every
-  authenticated request (with a short-lived cache) so the token
-  role is advisory only.
-- Enforce a minimum secret length at config validation time.
+- ✅ Re-validate the user's role from the database on every
+  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.
 - **Breaking change:** existing HS256 tokens are invalidated;
   users must re-login.
 

compose.yaml

@@ -13,7 +13,8 @@ services:
       - TORRUST_INDEX_DATABASE=${TORRUST_INDEX_DATABASE:-e2e_testing_sqlite3}
       - TORRUST_INDEX_DATABASE_DRIVER=${TORRUST_INDEX_DATABASE_DRIVER:-sqlite3}
       - TORRUST_INDEX_CONFIG_OVERRIDE_TRACKER__TOKEN=${TORRUST_INDEX_CONFIG_OVERRIDE_TRACKER__TOKEN:-MyAccessToken}
-      - TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__JWT_SIGNING_SECRET=${TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__JWT_SIGNING_SECRET:-MaxVerstappenWC2021}
+      - TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__SESSION_SIGNING_KEY=${TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__SESSION_SIGNING_KEY:-MaxVerstappenWC2021-session-key!}
+      - TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__EMAIL_VERIFICATION_SIGNING_KEY=${TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__EMAIL_VERIFICATION_SIGNING_KEY:-MaxVerstappenWC2021-emailverify!}
     networks:
       - server_side
     ports:

contrib/dev-tools/container/e2e/sqlite/mode/private/e2e-env-up.sh

@@ -8,7 +8,7 @@ USER_ID=${USER_ID:-1000} \
     TORRUST_INDEX_DATABASE="e2e_testing_sqlite3" \
     TORRUST_INDEX_DATABASE_DRIVER="sqlite3" \
     TORRUST_INDEX_CONFIG_OVERRIDE_TRACKER__TOKEN="MyAccessToken" \
-    TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__JWT_SIGNING_SECRET="MaxVerstappenWC2021" \
+    TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__SESSION_SIGNING_KEY="MaxVerstappenWC2021-session-key!" \
     TORRUST_TRACKER_CONFIG_TOML=$(cat ./share/default/config/tracker.private.e2e.container.sqlite3.toml) \
     TORRUST_TRACKER_DATABASE="e2e_testing_sqlite3" \
     TORRUST_TRACKER_CONFIG_OVERRIDE_CORE__DATABASE__DRIVER="sqlite3" \

contrib/dev-tools/container/e2e/sqlite/mode/public/e2e-env-up.sh

@@ -8,7 +8,7 @@ USER_ID=${USER_ID:-1000} \
     TORRUST_INDEX_DATABASE="e2e_testing_sqlite3" \
     TORRUST_INDEX_DATABASE_DRIVER="sqlite3" \
     TORRUST_INDEX_CONFIG_OVERRIDE_TRACKER__TOKEN="MyAccessToken" \
-    TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__JWT_SIGNING_SECRET="MaxVerstappenWC2021" \
+    TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__SESSION_SIGNING_KEY="MaxVerstappenWC2021-session-key!" \
     TORRUST_TRACKER_CONFIG_TOML=$(cat ./share/default/config/tracker.public.e2e.container.sqlite3.toml) \
     TORRUST_TRACKER_DATABASE="e2e_testing_sqlite3" \
     TORRUST_TRACKER_CONFIG_OVERRIDE_CORE__DATABASE__DRIVER="sqlite3" \

docs/containers.md

@@ -149,7 +149,8 @@ The following environmental variables can be set:
 
 - `TORRUST_INDEX_CONFIG_TOML_PATH` - The in-container path to the index configuration file, (default: `"/etc/torrust/index/index.toml"`).
 - `TORRUST_INDEX_CONFIG_OVERRIDE_TRACKER__TOKEN` - Override of the admin token. If set, this value overrides any value set in the config.
-- `TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__JWT_SIGNING_SECRET` - Override of the auth JWT signing secret. If set, this value overrides any value set in the config.
+- `TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__SESSION_SIGNING_KEY` - Override of the auth session signing key. If set, this value overrides any value set in the config.
+- `TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__EMAIL_VERIFICATION_SIGNING_KEY` - Override of the auth email-verification signing key. If set, this value overrides any value set in the config.
 - `TORRUST_INDEX_DATABASE_DRIVER` - The database type used for the container, (options: `sqlite3`, `mysql`, default `sqlite3`). Please Note: This dose not override the database configuration within the `.toml` config file.
 - `TORRUST_INDEX_CONFIG_TOML` - Load config from this environmental variable instead from a file, (i.e: `TORRUST_INDEX_CONFIG_TOML=$(cat index-index.toml)`).
 - `USER_ID` - The user id for the runtime crated `torrust` user. Please Note: This user id should match the ownership of the host-mapped volumes, (default `1000`).
@@ -202,7 +203,7 @@ mkdir -p ./storage/index/lib/ ./storage/index/log/ ./storage/index/etc/
 ## Run Torrust Index Container Image
 docker run -it \
     --env TORRUST_INDEX_CONFIG_OVERRIDE_TRACKER__TOKEN="MySecretToken" \
-    --env TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__JWT_SIGNING_SECRET="MaxVerstappenWC2021" \
+    --env TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__SESSION_SIGNING_KEY="MaxVerstappenWC2021-session-key!" \
     --env USER_ID="$(id -u)" \
     --publish 0.0.0.0:3001:3001/tcp \
     --volume ./storage/index/lib:/var/lib/torrust/index:Z \

share/default/config/index.container.mysql.toml

@@ -15,7 +15,8 @@ threshold = "info"
 token = "MyAccessToken"
 
 [auth]
-jwt_signing_secret = "MaxVerstappenWC2021"
+session_signing_key = "MaxVerstappenWC2021-session-key!"
+email_verification_signing_key = "MaxVerstappenWC2021-emailverify!"
 
 [database]
 connect_url = "mysql://root:root_secret_password@mysql:3306/torrust_index"

share/default/config/index.container.sqlite3.toml

@@ -15,7 +15,8 @@ threshold = "info"
 token = "MyAccessToken"
 
 [auth]
-jwt_signing_secret = "MaxVerstappenWC2021"
+session_signing_key = "MaxVerstappenWC2021-session-key!"
+email_verification_signing_key = "MaxVerstappenWC2021-emailverify!"
 
 [database]
 connect_url = "sqlite:///var/lib/torrust/index/database/sqlite3.db?mode=rwc"

share/default/config/index.development.sqlite3.toml

@@ -17,7 +17,8 @@ threshold = "info"
 token = "MyAccessToken"
 
 [auth]
-jwt_signing_secret = "MaxVerstappenWC2021"
+session_signing_key = "MaxVerstappenWC2021-session-key!"
+email_verification_signing_key = "MaxVerstappenWC2021-emailverify!"
 
 # Uncomment if you want to enable TSL for development
 #[net.tsl]