GitRust GitRust
Connexion

eric / rustwarden

README.md 7035 octets

Guide développeur Rustwarden

Qu'est-ce que Rustwarden ?

Rustwarden est un framework backend Rust de gestion des utilisateurs et de l'authentification. Il fournit, sous forme de crates Cargo réutilisables, tout ce qu'un service web a besoin : authentification JWT, RBAC granulaire, OAuth2/OIDC, 2FA/TOTP, gestion d'équipes, sessions avec refresh token, file d'envoi d'emails, rate limiting et panneau d'administration optionnel. Le point d'entrée est RustwardenApp::builder(), un builder Rust idiomatique qui compose les couches et lance le serveur Axum.

Rustwarden n'est pas un gestionnaire de mots de passe. Malgré la ressemblance de nom, il n'a aucun lien avec Bitwarden ou Vaultwarden : pas de coffre-fort, pas de chiffrement de secrets personnels, pas d'extension navigateur. Les modules auth, oauth, totp, team, permission, resource sont des primitives génériques conçues pour être branchées dans n'importe quelle application backend SaaS, API REST ou service interne.

Le public cible est double. D'un côté, les développeurs consommateurs qui veulent intégrer Rustwarden dans leur propre projet Rust (SPA frontale séparée, application mobile, micro-service) sans réécrire la couche auth. De l'autre, les contributeurs qui souhaitent étendre le framework — ajouter un provider OAuth, affiner le RBAC, ou contribuer au protocole ActivityPub via rustwarden-fediverse.

Navigation du guide

FichierContenu
01-architecture-overview.mdVision globale, carte des crates, couches techniques, axes d'extension, features Cargo
02-request-lifecycle.mdCycle de vie complet d'une requête authentifiée, login, refresh, logout, extracteur AuthUser
03-configuration.mdVariables d'environnement, AuthConfig, ServerConfig, EmailConfig
04-builder-api.mdRustwardenApp::builder() — toutes les méthodes, exemples d'assemblage
05-consuming-the-framework.mdIntégration pas-à-pas dans un projet Rust existant, ajout de routes custom
06-contributing.mdConventions de code, règles Clippy, tests, processus de revue
07-security-model.mdModèle de menace, JWT blacklist, CSRF, rate limiting, bonnes pratiques ANSSI
08-fediverse-integration.mdBranchement de rustwarden-fediverse via traits, ActivityPub headless
09-hooks-and-events.mdTrait RustwardenHooks, liste des événements, exemple d'implémentation
10-testing-and-observability.mdStratégie de test (538 tests, pyramide, e2e fédération), état de l'observabilité et recommandations V2
11-audience-measurement.mdBrancher un script de suivi générique (URL + attributs data-*), CSP automatique, opposition du visiteur, migration d'un projet qui l'avait en dur

Par où commencer ?

flowchart TD
    START([Je découvre Rustwarden]) --> Q1{Quel est mon objectif ?}

    Q1 -->|Intégrer dans mon projet| CONSO[01 — Architecture overview]
    CONSO --> CONSO2[05 — Consuming the framework]
    CONSO2 --> CONSO3[04 — Builder API]

    Q1 -->|Contribuer au framework| CONTRIB[01 — Architecture overview]
    CONTRIB --> CONTRIB2[02 — Request lifecycle]
    CONTRIB2 --> CONTRIB3[06 — Contributing]

    Q1 -->|Brancher la fédération ActivityPub| FEDI[08 — Fediverse integration]

    Q1 -->|Auditer la sécurité| SEC[07 — Security model]
    SEC --> SEC2[02 — Request lifecycle]

    style START fill:#4a90d9,color:#fff
    style FEDI fill:#7c5cbf,color:#fff
    style SEC fill:#d94a4a,color:#fff

Glossaire express

TermeDéfinition
PrincipalEntité qui effectue une action — peut être un utilisateur local, un token personnel ou une identité fédérée. Voir resource_service::Principal.
Identity / IdentityKindDiscriminant dans le JWT (`kind: local
AuthUserExtracteur Axum qui valide le JWT entrant et injecte user_id, username, roles, permissions dans le handler. Retourne 401 si le token est absent ou invalide.
ClaimsStructure sérialisée dans le JWT : sub, jti, exp, iat, iss, aud, username, roles, permissions, kind.
jtiJWT ID — identifiant unique de chaque token, utilisé par JwtBlacklistService pour la révocation individuelle.
HookMéthode du trait RustwardenHooks appelée par le framework à un événement métier (login, logout, inscription, changement de rôle…). Le consumer implémente le trait et passe l'objet au builder.
ObserverSynonyme de hook dans le contexte de la fédération ActivityPub : FediverseEventObserver reçoit les activités (Follow, Like, etc.) depuis rustwarden-fediverse.
Refresh tokenToken opaque (64 chars alphanumériques, stocké haché en SHA-256) échangé contre une nouvelle paire JWT. Rotation automatique à chaque usage ; révocation globale en cas de réutilisation détectée.
Blacklist JWTTable jwt_blacklist qui stocke le hash SHA-256 des tokens révoqués. Consultée à chaque requête par JwtBlacklistService::is_blacklisted.
RustwardenAppApplication entièrement configurée, résultat de builder().build().await?. Expose database(), auth_config(), i18n_service() et la méthode run().
RustwardenBuilderBuilder fluide permettant de composer le framework : routes, hooks, UI, fédération, migrations auto, localisation.
headlessMode sans interface HTML — API JSON pure. Activé par .headless() sur le builder ou simplement en n'appelant pas .with_ui().
DashboardCardDTODTO permettant aux crates compagnons (rustwarden-fediverse-ui) d'injecter une carte dans le tableau de bord d'administration via add_dashboard_card().
AppErrorType d'erreur central du framework, converti automatiquement en réponse HTTP appropriée par IntoResponse.
LocalUserResolverTrait fédération que rustwarden-core expose pour que rustwarden-fediverse puisse résoudre un acteur AP en compte local sans dépendance inversée.

Liens utiles