Merge torrust#856: feat!: refactor roles & permissions system (ADR-T-008)

1998ccb refactor(auth): post-review hardening for ADR-T-008 (Peer Cat)
c461db0 feat(auth): add Moderator role, exhaustive Admin grants, and hardened diagnostics (Peer Cat)
737c4c2 feat: ADR-T-008 Phase 4 — E2E tests for permissions system (Peer Cat)
44ccd66 feat: implement ADR-T-008 Phase 3 — resource-level authorization (Peer Cat)
58c23cf refactor(auth): enforce permissions at HTTP boundary with RequirePermission<A> (Peer Cat)
70701db refactor(auth)!: replace Casbin with native PermissionMatrix (ADR-T-008) (Peer Cat)

Pull request description:

  ## Summary

  Replace the Casbin-based authorization system with a native Rust permission model built on exhaustive `Role` and `Action` enums. Adding a new role or action without deciding its permission is now a **compile error**, eliminating silent policy gaps.

  ### Motivation

  The prior system had three intertwined authorization mechanisms (Casbin RBAC, a bare `administrator` boolean in the DB, and scattered inline ownership checks). This made the permission surface hard to audit, impossible to extend with intermediate roles, and left resource-level authorization as ad-hoc string comparisons sprinkled through service methods.

  ### What changed

  **Phase 1 — Native `PermissionMatrix`** (`refactor(auth)!`)
  - Replace `casbin` crate with a `HashSet<(Role, Action)>` table populated by exhaustive `match` arms.
  - Introduce `Role` enum (`Guest`, `Registered`, `Admin`) with `Display`/`FromStr`/serde support.
  - Rename `ACTION` → `Action` (Rust conventions).
  - Migrate DB from `administrator: bool` to `role: String`; backfill existing rows.
  - Remove the `unstable.auth.casbin` config section entirely.

  **Phase 2 — `RequirePermission<A>` extractor**
  - Generic Axum extractor resolves identity from the bearer token, looks up `Role` in the DB, and checks the matrix — all before the handler runs.
  - `ActionMarker` trait + `action_markers!` macro bind each handler to an `Action` at the type level (compile-time enforcement).
  - Remove `authorization::Service` and strip auth concerns from service methods.
  - Delete the old `ExtractOptionalLoggedInUser` / `ExtractLoggedInUser` extractors.

  **Phase 3 — Resource-level authorization & permissions discovery**
  - `can_on_resource()` method: Admin bypasses ownership; other roles must be the resource owner.
  - `GET /v1/user/me/permissions` endpoint returns the caller's resolved role and allowed actions.
  - `[permissions.overrides]` TOML config — operators can grant/deny `(role, action)` tuples without touching Rust source.
  - Drop the legacy `administrator` column (MySQL + SQLite migrations).
  - Remove `admin: bool` from all API responses.

  **Phase 4 — E2E tests**
  - Five E2E tests covering permission discovery (admin / registered / guest) and TOML override propagation (grant + deny paths).
  - `TestEnv::start_with()` config-mutator support for isolated test environments.

  **Phase 5 — Moderator role & hardening**
  - Add `Role::Moderator` with a scoped permission set (tags + `DeleteTorrent`).
  - Replace `Admin => true` wildcard with exhaustive action match — new actions are a compile error until granted per-role.
  - Emit `warn!` when TOML overrides grant high-risk actions to non-admin roles.
  - Improved logging in registration and `grant_admin_role` paths.

  ### Additional cleanup
  - Update all API doc examples to RS256 JWT format (post ADR-T-007).
  - Fix several README typos and stale "Torrust Tracker" → "Torrust Index" references.
  - AGENTS.md: add "Counts and Numbers" guideline.

  ### Breaking changes
  - `administrator: bool` replaced by `role: String` in API responses.
  - The `casbin` configuration section is removed.
  - `ACTION` enum renamed to `Action`.

  ### Stats
  ~64 files changed, ~3k insertions, ~1k deletions across source, tests, migrations, docs, and the ADR.

ACKs for top commit:
  peer-cat:
    ACK 1998ccb
  da2ce7:
    ACK 1998ccb

Tree-SHA512: 8289b69bae573e150537e453d859131968d31b8117468e7f18b36d6be0cc0ae2c7fe2ec13b17f291098ec593dde5b5c75804cb3b8b68249644c350c920ae4bfb

Author: da2ce7

AGENTS.md

@@ -22,6 +22,12 @@ suite, for example when finishing up.)
 When running tests, tee to a temp file (`/tmp/...`) and then grep that
 file after the tests have completed.
 
+## Counts and Numbers
+
+Do not use exact numbers, i.e. not: "100 tests passed".
+Instead, use fuzzy numbers, e.g. "A hundred tests passed" or "~320 functions in total".
+Precise numbers may be used for qualified historical records. e.g. "on 21.12.1992 phase 3 was marked as accepted with 465 passing tests and 3 failures."
+
 ## Test Locations
 
 We use three levels of tests based upon viability. In general, crate tests

CHANGELOG.md

@@ -9,10 +9,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Added
 
+- ADR-T-008: Document rationale for roles and permissions refactor.
 - ADR-T-006: Document rationale for error system refactor.
 - 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).
+- Native `PermissionMatrix` replacing Casbin: compile-time checked `Role` and
+  `Action` enums with an exhaustive default-deny policy table (ADR-T-008).
+- `Permissions` trait abstraction for the authorization backend, consumed by
+  the `RequirePermission<A>` extractor via `AppData.permissions`.
+- `role: TEXT` column on `torrust_users` (migration for SQLite and MySQL);
+  existing `administrator = true` rows migrated to `role = 'admin'`, others
+  to `role = 'registered'`.
+- `role: String` field on `TokenResponse`, `UserCompact`, `UserProfile`, and
+  `UserFull` API response models.
+- `RequirePermission<A>` Axum extractor enforcing role-based authorization at
+  the HTTP boundary before the handler runs (ADR-T-008 Phase 2).
+- `ActionMarker` trait and `action_markers!` macro mapping zero-sized types to
+  `Action` enum variants for compile-time handler–permission binding.
+- `Actor` struct yielded by `RequirePermission` carrying the resolved
+  `user_id` and `Role` for downstream handler use.
+- `Actor::try_user_id()` non-panicking accessor returning `Option<UserId>`,
+  safe for handlers that may serve guests (ADR-T-008).
+- `Actor::is_authenticated()` convenience predicate (ADR-T-008).
+- Compile-time `action_markers!` ↔ `Action::ALL` sync assertion: adding an
+  `Action` variant without a matching marker (or vice versa) is a compile
+  error (ADR-T-008).
+- E2E tests for non-owner update and delete denial (`and_non_owners` module
+  in `tests/e2e/web/api/v1/contexts/torrent/contract.rs`) (ADR-T-008 Phase 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.
@@ -52,6 +76,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Changed
 
 - **BREAKING:** Raise MSRV from 1.85 to 1.88.
+- **BREAKING:** `administrator: bool` replaced by `role: String` in API
+  responses (`TokenResponse`, `UserCompact`, etc.). The legacy `admin: bool`
+  field has been removed entirely (ADR-T-008).
+- **BREAKING:** `administrator` column dropped from `torrust_users`; the
+  `role: TEXT` column is now the sole authority. Migration
+  `20260415000001_torrust_drop_administrator_column` handles both SQLite
+  (table-rebuild) and MySQL (`DROP COLUMN`).
+- **BREAKING:** `ACTION` enum renamed to `Action`; variants unchanged.
+- All HTTP handlers that require authorization now use
+  `RequirePermission<A>` extractors instead of calling
+  `authorization::Service::authorize()` (ADR-T-008 Phase 2).
+- Service methods no longer receive `maybe_user_id` for authorization
+  purposes — they receive an already-authorized `Actor` or are called
+  unconditionally.
+- Unauthorized requests are rejected at the extractor boundary before
+  reaching the service layer (fail-fast).
+- First-user auto-admin grant in `RegistrationService::register` now logs
+  a `warn!` on failure instead of silently discarding the `Result` via
+  `drop()`.
 - **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
@@ -66,8 +109,6 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
   `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.
@@ -80,10 +121,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Each domain error co-locates its HTTP status-code mapping via a
   `status_code()` method.
 - Error `From` impls use `tracing::error!` instead of `eprintln!`.
+- JWT session token `role` claim now carries the database `role` value
+  directly (`"registered"`, `"admin"`) instead of the previous mapping
+  (`"user"`, `"admin"`).
+- v1→v2 upgrade path: `insert_imported_user` now writes the `role` column
+  (`"admin"` / `"registered"`) instead of the removed `administrator` column.
 - Standardise all error derives on `thiserror`.
 
 ### Removed
 
+- `admin: bool` field from `TokenResponse`, `LoggedInUserData`, and
+  `TokenRenewalData` — superseded by `role: String` (ADR-T-008).
+- `UserCompact::is_admin()` convenience method — no longer needed after
+  `admin: bool` removal.
+- `administrator` column from `torrust_users` schema (migration for both
+  SQLite and MySQL).
+- `casbin` crate dependency and all Casbin-related code
+  (`CasbinConfiguration`, `CasbinEnforcer`, the `ACTION` enum in
+  SCREAMING_CASE) — replaced by the native `PermissionMatrix` (ADR-T-008).
+- `unstable.auth.casbin` configuration section (`Unstable`, `Auth`, `Casbin`
+  config structs in `src/config/v2/unstable.rs`).
 - `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).
@@ -93,6 +150,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - `http_status_code_for_service_error` and `map_database_error_to_service_error`
   helper functions.
 - `IntoResponse` impl for `database::Error` (now handled by domain errors).
+- `authorization::Service` struct — replaced by `RequirePermission<A>`
+  extractors consulting `PermissionMatrix` directly (ADR-T-008 Phase 2).
+- `ExtractLoggedInUser` (`user_id.rs`) and `ExtractOptionalLoggedInUser`
+  (`optional_user_id.rs`) extractors — replaced by `RequirePermission<A>`
+  (ADR-T-008 Phase 2).
+- Dead `Action` variants `GetSettings` and `GetCanonicalInfoHash` (no
+  corresponding handlers existed).
 
 ## [4.0.0] - 2026-03-23