refactor(jwt)!: switch from HMAC-HS256 to RS256 asymmetric signing (ADR-T-007 Phase 3)

Replace the shared HMAC secret (`session_signing_key` /
`email_verification_signing_key`) with an RSA-2048 key pair for
all JWT operations.

Key changes:

- Sign tokens with `EncodingKey` (private) and verify with
  `DecodingKey` (public), both resolved once at startup from PEM
  files or inline PEM configuration.
- Include a `kid` (Key ID) header derived from the SHA-256 hash
  of the public key, preparing for future key rotation.
- Ship a development key pair at `share/default/jwt/` with a loud
  startup warning when it is used.
- Remove `JwtSigningSecret`, the mandatory-option check for
  `auth.session_signing_key`, and all three serde aliases.
- Verification (`verify`, `verify_email_token`) is now synchronous
  since keys are pre-loaded — no config lock needed per request.
- Update all config files, container scripts, tests, and docs to
  use `private_key_path` / `public_key_path`.

BREAKING CHANGE: The `auth.session_signing_key` and
`auth.email_verification_signing_key` config fields are removed.
Deployers must provide an RSA key pair via `auth.private_key_path` /
`auth.public_key_path` (or the inline `_pem` variants). Existing
HS256 tokens will be rejected after upgrade.

Author: peer-cat

.env.local

@@ -1,7 +1,7 @@
 DATABASE_URL=sqlite://storage/database/data.db?mode=rwc
 TORRUST_INDEX_CONFIG_TOML=
-TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__SESSION_SIGNING_KEY=MaxVerstappenWC2021-session-key!
-TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__EMAIL_VERIFICATION_SIGNING_KEY=MaxVerstappenWC2021-emailverify!
+TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__PRIVATE_KEY_PATH=./share/default/jwt/private.pem
+TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__PUBLIC_KEY_PATH=./share/default/jwt/public.pem
 USER_ID=1000
 TORRUST_TRACKER_CONFIG_TOML=
 TORRUST_TRACKER_CONFIG_OVERRIDE_CORE__DATABASE__DRIVER=Sqlite3

Cargo.lock

@@ -88,6 +88,7 @@ serde_derive = "1"
 serde_json = "1"
 serde_with = "3"
 sha-1 = "0"
+sha2 = "0"
 sqlx = { version = "0", features = ["migrate", "mysql", "runtime-tokio-native-tls", "sqlite", "time"] }
 tera = { version = "1", default-features = false }
 text-colorizer = "1"

Cargo.toml

@@ -95,15 +95,18 @@ TORRUST_INDEX_CONFIG_TOML=$(cat "./storage/index/etc/index.toml") cargo run
 
 _For deployment, you __should__ override:
 
-- The `tracker_api_token` and the JWT signing keys by using environmental variables:_
+- The `tracker_api_token` and RSA key paths by using environmental variables:_
 
 ```sh
-# Please use the secret that you generated for the torrust-tracker configuration.
+# Generate an RSA key pair for JWT signing:
+# openssl genrsa -out private.pem 2048
+# openssl rsa -in private.pem -pubout -out public.pem
+
 # 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__SESSION_SIGNING_KEY="your-session-signing-secret-here!" \
-  TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__EMAIL_VERIFICATION_SIGNING_KEY="your-email-verify-secret-here!!" \
+  TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__PRIVATE_KEY_PATH="/path/to/private.pem" \
+  TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__PUBLIC_KEY_PATH="/path/to/public.pem" \
   cargo run
 ```
 
@@ -128,7 +131,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`, redesign claims to RFC 7519, split into per-purpose signing keys, and enforce minimum secret length.
+- [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, and move to RS256 asymmetric signing with a public/private RSA key pair.
 
 ## Contributing
 

README.md

@@ -1,6 +1,6 @@
 # ADR-T-007: Refactor the JWT System
 
-**Status:** Phase 2 implemented
+**Status:** Phase 3 implemented
 **Date:** 2026-04-14
 
 ## Context
@@ -388,21 +388,25 @@ phased rollout that subsumes Options A and B.
 - **Breaking change:** existing HS256 tokens are invalidated;
   users must re-login.
 
-#### Phase 3 — RS256 Asymmetric Signing (Option C scope)
+#### Phase 3 — RS256 Asymmetric Signing (Option C scope) ✅ Implemented
 
-- Replace `HS256` with `RS256` (`Algorithm::RS256`).
-- Config provides:
+- ✅ Replace `HS256` with `RS256` (`Algorithm::RS256`).
+- ✅ Config provides:
   - `auth.private_key_path` (PEM / PKCS#8) for signing.
   - `auth.public_key_path` for verification.
-  - Alternatively, inline PEM via environment variable.
-- Generate a default development key pair on first run (with a
-  loud warning) so the zero-config experience is preserved for
-  local development.
-- Use `EncodingKey::from_rsa_pem` / `DecodingKey::from_rsa_pem`.
-- Only the signing service loads the private key; the
+  - Alternatively, inline PEM via environment variable
+    (`auth.private_key_pem`, `auth.public_key_pem`).
+- ✅ Development key pair shipped at `share/default/jwt/` with loud
+  startup warning when the default dev keys are used.
+- ✅ Use `EncodingKey::from_rsa_pem` / `DecodingKey::from_rsa_pem`.
+- ✅ Only the signing service loads the private key; the
   verification path uses the public key.
-- Add a `kid` (Key ID) field to the JWT header to support future
-  key rotation.
+- ✅ A `kid` (Key ID) is included in every JWT header (SHA-256
+  fingerprint of the public key) to support future key rotation.
+- **Breaking change:** existing HS256 tokens and config
+  (`session_signing_key`, `email_verification_signing_key`) are
+  no longer supported. Deployers must generate an RSA key pair
+  and update their configuration.
 
 #### Future — Optional Revocation (Option E scope)
 

adr/007-jwt-system-refactor.md

@@ -13,8 +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__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!}
+      - TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__PRIVATE_KEY_PATH=${TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__PRIVATE_KEY_PATH:-/var/lib/torrust/index/jwt/private.pem}
+      - TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__PUBLIC_KEY_PATH=${TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__PUBLIC_KEY_PATH:-/var/lib/torrust/index/jwt/public.pem}
     networks:
       - server_side
     ports:

compose.yaml

@@ -8,7 +8,8 @@ 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__SESSION_SIGNING_KEY="MaxVerstappenWC2021-session-key!" \
+    TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__PRIVATE_KEY_PATH="/var/lib/torrust/index/jwt/private.pem" \
+    TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__PUBLIC_KEY_PATH="/var/lib/torrust/index/jwt/public.pem" \
     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/private/e2e-env-up.sh

@@ -8,7 +8,8 @@ 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__SESSION_SIGNING_KEY="MaxVerstappenWC2021-session-key!" \
+    TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__PRIVATE_KEY_PATH="/var/lib/torrust/index/jwt/private.pem" \
+    TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__PUBLIC_KEY_PATH="/var/lib/torrust/index/jwt/public.pem" \
     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" \

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

@@ -149,8 +149,10 @@ 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__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_CONFIG_OVERRIDE_AUTH__PRIVATE_KEY_PATH` - Override of the RSA private key PEM file path for JWT signing. If set, this value overrides any value set in the config.
+- `TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__PUBLIC_KEY_PATH` - Override of the RSA public key PEM file path for JWT verification. If set, this value overrides any value set in the config.
+- `TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__PRIVATE_KEY_PEM` - Override with an inline RSA private key PEM string instead of a file path.
+- `TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__PUBLIC_KEY_PEM` - Override with an inline RSA public key PEM string instead of a file path.
 - `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`).
@@ -203,7 +205,8 @@ 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__SESSION_SIGNING_KEY="MaxVerstappenWC2021-session-key!" \
+    --env TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__PRIVATE_KEY_PATH="/var/lib/torrust/index/jwt/private.pem" \
+    --env TORRUST_INDEX_CONFIG_OVERRIDE_AUTH__PUBLIC_KEY_PATH="/var/lib/torrust/index/jwt/public.pem" \
     --env USER_ID="$(id -u)" \
     --publish 0.0.0.0:3001:3001/tcp \
     --volume ./storage/index/lib:/var/lib/torrust/index:Z \

docs/containers.md

@@ -15,8 +15,8 @@ threshold = "info"
 token = "MyAccessToken"
 
 [auth]
-session_signing_key = "MaxVerstappenWC2021-session-key!"
-email_verification_signing_key = "MaxVerstappenWC2021-emailverify!"
+private_key_path = "/var/lib/torrust/index/jwt/private.pem"
+public_key_path = "/var/lib/torrust/index/jwt/public.pem"
 
 [database]
 connect_url = "mysql://root:root_secret_password@mysql:3306/torrust_index"