Rustwarden

Framework Rust pour la gestion d'utilisateurs et l'authentification securisee. Permet de creer rapidement des applications web avec authentification JWT, RBAC granulaire, gestion d'emails, et panneau d'administration.

Fonctionnalites

• Authentification JWT avec refresh tokens et blacklist automatique
• RBAC granulaire (roles + permissions par ressource)
• Panneau d'administration complet (CRUD users, roles, permissions, settings)
• Validation d'email avec token
• Reset de mot de passe par email (confirmation double-etape)
• File d'attente d'emails avec retry automatique
• Detection de bounces IMAP
• Protection CSRF
• Rate limiting configurable
• Internationalisation (fr, en, de, es)
• Middleware d'authentification et d'autorisation
• Mode headless (API-only) cle en main : routeur d'auth JSON canonique rustwarden_core::auth::auth_api_routes() monte en une ligne, comportement d'echec d'auth configurable (redirection vers login_path ou 401 JSON)
• Outil screen-select : genere le plan des ecrans UI a coder selon les fonctionnalites activees (docs/plans/ui-screens.md) puis recoche le realise par analyse statique (-- --check) — pour les UIs custom/headless
• Conformite ANSSI (complexite des mots de passe, HttpOnly cookies, etc.)
• OAuth2 / OpenID Connect (Google, GitHub, Discord, Microsoft) avec architecture extensible
• Federation ActivityPub optionnelle (RFC 0001+) : WebFinger, NodeInfo, login AP-native, invitations d'equipe cross-instance, modele de confiance allowlist/blocklist — fournie par le crate rustwarden-fediverse
• Variable APP_NAME pour personnaliser le branding partout dans l'UI

Architecture

rustwarden/
├── crates/
│   ├── rustwarden-core/            # Library : auth, RBAC, services, middleware, i18n, hooks
│   ├── rustwarden-ui/              # UI optionnelle : templates HTML, admin panel, handlers
│   ├── rustwarden-fediverse/       # Federation ActivityPub optionnelle (RFC 0001+)
│   ├── rustwarden-fediverse-ui/    # UI HTML de reference pour la federation
│   └── rustwarden-fediverse-guard/ # Detection d'abus et bans pour la federation (RFC 0028+)
├── app/                    # Application de reference (12 lignes de main.rs)
├── tools/
│   └── rustwarden-cli/     # Wizard interactif pour creer ou updater de nouveaux projets
├── locales/                # Fichiers de traduction (YAML)
├── static/                 # Fichiers statiques (CSS, JS, images)
├── database/               # Docker Compose pour PostgreSQL
└── docs/                   # Documentation complementaire
└── .env                    # Variable d'environnement

Crates

Stack technique

• Backend : Rust, Axum 0.8, SeaORM 2.0, Tokio
• Auth : JWT (HS256), bcrypt, sessions en memoire ou SeaORM
• Database : PostgreSQL
• Frontend (UI) : Askama, Tailwind CSS, DaisyUI, HTMX, Alpine.js
• Email : Lettre (SMTP), IMAP bounce detection

Demarrage rapide

Option 1 : Wizard CLI (recommande)

Le wizard interactif genere un projet autonome avec toute la configuration deja remplie.

# Compiler le wizard
cargo build -p rustwarden-cli

# Lancer le wizard
cargo run -p rustwarden-cli -- start-project

Le wizard demande interactivement :

1. Nom du projet (nom technique du crate)
2. Nom affiche (APP_NAME dans l'interface)
3. Description
4. Dossier cible
5. Mode (interface web ou API seule, federation optionnelle : aucune / headless / avec UI de reference)
6. Migrations automatiques (oui/non)
7. Port du serveur
8. Base de donnees (nom, utilisateur, mot de passe)
9. Administrateur (username, email, mot de passe)
10. SMTP (optionnel : host, port, identifiants)

Il genere un projet autonome avec :

• Les crates rustwarden-core et rustwarden-ui copies localement
• .env configure avec vos identifiants
• database/.env pour Docker PostgreSQL
• Un README.md et un DEVELOPER.md detaille
• Une page d'accueil personnalisee avec le nom de votre application
• Les templates HTML rebrandes automatiquement

# Apres generation
cd mon-app
# PostgreSQL n'ecoute que 127.0.0.1:5432. Copier database/env.sample vers
# database/.env et definir POSTGRES_PASSWORD (obligatoire, pas de repli).
cp database/env.sample database/.env
cd database && docker compose up -d && cd ..
cargo run
# Ouvrir http://localhost:3000

Option 2 : Comme dependance dans un projet existant

[dependencies]
rustwarden-core = { path = "../rustwarden/crates/rustwarden-core" }
rustwarden-ui = { path = "../rustwarden/crates/rustwarden-ui" }  # optionnel

use rustwarden_core::prelude::*;

#[tokio::main]
async fn main() -> anyhow::Result<()> {
    RustwardenApp::builder()
        .from_env()
        .with_ui(rustwarden_ui::default_routes)
        .auto_migrate(true)
        .merge_routes(my_routes())
        .build()
        .await?
        .run()
        .await
}

Option 3 : Mode headless (API-only)

RustwardenApp::builder()
    .from_env()
    .headless()                                                    // API-only : echec d'auth = 401 JSON (au lieu d'une redirection)
    .merge_machine_routes(rustwarden_core::auth::auth_api_routes()) // API d'auth /api/v1/auth/* prete a l'emploi
    .merge_routes(my_api_routes())                                 // vos routes metier
    .build()
    .await?
    .run()
    .await

En mode headless, aucun prefixe protege n'est enregistre par defaut : declarez les votres via .register_protected_prefix("/…"). Le chemin de login (login_path) et le mode d'echec (auth_failure_mode) sont configurables — voir la section Configuration.

Pour planifier les ecrans d'une UI custom, le binaire screen-select (livre avec rustwarden-core) genere docs/plans/ui-screens.md — la liste des ecrans a coder selon les fonctionnalites activees — puis recoche le realise par analyse statique des routes :

cargo run -p rustwarden-core --bin screen-select              # wizard : selection des fonctionnalites → plan
cargo run -p rustwarden-core --bin screen-select -- --check   # controle de couverture (recoche le realise)

Catalogue des ecrans et limites de detection : docs/SERVICES_REFERENCE.md §22.

Builder API

RustwardenApp::builder()
    .from_env()                              // charge .env + init logging
    .database_url("postgres://...")          // ou .database(db_connection)
    .address("0.0.0.0:8080")                 // adresse du serveur
    .with_ui(rustwarden_ui::browser_routes)  // UI SSR (canal browser, CSRF)
    .merge_machine_routes(rustwarden_ui::api_routes()) // API JSON de l'UI (canal machine, sans CSRF)
    .headless()                              // OU mode API-only (pas d'UI) → echec d'auth = 401 JSON
    .login_path("/connexion")                // chemin de redirection de login (defaut "/login")
    .auth_failure_mode(AuthFailureMode::Json401) // Redirect (defaut UI) ou Json401 (defaut headless)
    .merge_browser_routes(custom_ui_router)  // pages SSR mutantes → CSRF applique
    .merge_machine_routes(custom_api_router) // API JSON / webhooks → sans CSRF
    .register_protected_prefix("/espace")    // auth requise sur ce prefixe
    .hooks(MyHooks)                          // lifecycle hooks personnalises
    .auto_migrate(true)                      // migrations auto au demarrage
    .without_email()                         // desactiver l'email
    .without_background_tasks()              // desactiver les taches de fond
    .locale_dir("my_locales")                // repertoire de traductions
    .supported_locales(vec!["fr", "en"])     // locales supportees
    .default_locale("fr")                    // locale par defaut
    .build().await?
    .run().await

with_ui/merge_browser_routes = canal browser (CSRF applique) ; merge_machine_routes = canal machine (API Bearer/JSON, sans CSRF). rustwarden_ui::default_routes est deprecie (remettrait /api/v1/* sous CSRF) → utiliser browser_routes() + api_routes().

Sequencement interne du builder

1. Connexion a la base PostgreSQL
2. Migrations automatiques (si active)
3. Creation admin par defaut + initialisation app_settings
4. Configuration auth (JWT, sessions)
5. Demarrage des taches de fond (email queue, IMAP bounce, JWT cleanup)
6. Chargement i18n
7. Assemblage du router (UI + routes custom + middleware)
8. Demarrage du serveur HTTP

Mise a jour du framework (projets generes)

Les projets generes par le wizard embarquent les crates du framework en local (vendored). Pour les resynchroniser sur une version plus recente :

# Depuis le depot Rustwarden (le wizard demande le dossier du projet cible)
cargo run -p rustwarden-cli -- update-project

La commande synchronise les crates presentes dans le projet (rustwarden-core, rustwarden-ui, rustwarden-fediverse* selon le cas — binaire screen-select inclus), preserve les templates personnalises, supprime les fichiers retires du framework, propose d'ajouter la federation si elle est absente, puis rappelle les actions post-update (cargo check, migrations, screen-select).

# Depuis le dossier du projet consommateur
rm -rf crates/rustwarden-core crates/rustwarden-ui
cp -r /chemin/vers/Rustwarden/crates/rustwarden-core crates/
cp -r /chemin/vers/Rustwarden/crates/rustwarden-ui crates/
# Fichiers partages (si modifies)
cp -r /chemin/vers/Rustwarden/locales ./
cp -r /chemin/vers/Rustwarden/static ./

cargo check
cargo clippy -- -D warnings

Routes disponibles

Routes publiques

API REST (authentification)

Cet ensemble est fourni cle en main par rustwarden_core::auth::auth_api_routes() (a monter via merge_machine_routes). En mode UI, rustwarden_ui::api_routes() monte exactement le meme jeu de routes.

API REST (OAuth) (feature oauth)

API REST (utilisateurs)

Pages UI (authentification requise)

Pages admin (role admin requis)

Pages admin federation (feature fediverse)

Quand le binaire est compile avec --features fediverse, le dashboard admin affiche une carte "Federation ActivityPub" qui pointe vers /admin/fediverse/settings. Depuis ce hub :

Cote utilisateur final, le flow de connexion federee est expose sur /login/fediverse (et son SSE /login/fediverse/sse/{id}), l'ecran de consentement IdP sur /fediverse/consent/{id}, et la page d'acceptation d'invitation sur /fediverse/invite/{id}. Le profil utilisateur expose /profile/connected_apps pour lister les instances qu'il a autorisees.

Endpoints protocole (publics, hors UI) (feature fediverse)

Hooks (extension)

Implementez RustwardenHooks pour ajouter de la logique metier aux evenements du framework :

use rustwarden_core::prelude::*;
use async_trait::async_trait;
use sea_orm::DatabaseConnection;
use uuid::Uuid;

struct MyHooks;

#[async_trait]
impl RustwardenHooks for MyHooks {
    async fn on_user_registered(&self, db: &DatabaseConnection, user_id: Uuid, username: &str) -> anyhow::Result<()> {
        // Creer un workspace par defaut pour le nouvel utilisateur
        Ok(())
    }

    async fn on_user_login(&self, db: &DatabaseConnection, user_id: Uuid, username: &str) -> anyhow::Result<()> {
        // Logger l'activite, envoyer une notification...
        Ok(())
    }
}

Activez les hooks dans le builder :

RustwardenApp::builder()
    .from_env()
    .hooks(MyHooks)
    .build()
    .await?
    .run()
    .await

Hooks disponibles

RBAC (Roles et Permissions)

Le systeme RBAC permet de definir des roles avec des permissions granulaires.

Modele

• Role : nom unique (ex: admin, editor, viewer)
• Permission : nom unique (ex: users.read, users.create, articles.publish)
• Role-Permission : table de liaison many-to-many
• User-Role : table de liaison many-to-many

Utilisation dans les handlers

use rustwarden_core::services::permission_service::PermissionService;
use rustwarden_core::services::role_service::RoleService;

// Verifier si un utilisateur a une permission specifique
let has_perm = PermissionService::user_has_permission(&db, user_id, "articles.publish").await?;

// Recuperer les roles d'un utilisateur
let roles = RoleService::get_user_roles(&db, user_id).await?;

Administration

Le panneau d'administration (/admin/roles) permet de :

• Creer / modifier / supprimer des roles
• Attribuer des permissions aux roles
• Assigner des roles aux utilisateurs

Configuration (.env)

Application

Base de donnees

Serveur

JWT

Sessions

Rate limiting

Cookies

Comportement d'authentification

Admin initial

Email SMTP

File d'attente email

IMAP (detection de bounces)

OAuth / SSO (feature oauth)

Les credentials OAuth peuvent etre configures via l'interface Admin (/admin/settings) ou via ces variables d'environnement (fallback).

Federation ActivityPub (feature fediverse)

La feature est opt-in a la compilation : ajouter --features fediverse au binaire. Le crate rustwarden-core ne tire aucune des deps lourdes (activitypub_federation, rsa, reqwest, ammonia) tant que le binaire n'active pas la feature. Cote runtime, deux flags supplementaires dans app_settings controlent l'experience admin : fediverse_enabled (toggle global, defaut false) et fediverse_trust_mode (allowlist / open_with_blocklist). Reglage via /admin/fediverse/settings ou directement en SQL.

Wiring minimal dans main.rs (extrait de app/src/main.rs) :

#[cfg(feature = "fediverse")]
let builder = {
    use std::sync::Arc;
    let db = sea_orm::Database::connect(&std::env::var("DATABASE_URL")?).await?;
    let config = rustwarden_fediverse::FediverseConfig::from_env()?;
    let router = rustwarden_fediverse::routes::router(config, db.clone());
    let checker: Arc<dyn rustwarden_core::middleware::revocation::RemoteIdentityRevocationChecker> =
        Arc::new(
            rustwarden_fediverse::services::revocation::SeaOrmRemoteIdentityRevocationChecker::new(
                db.clone(),
            ),
        );
    builder
        .database(db)
        .register_protected_prefix("/fediverse/consent")
        .register_protected_prefix("/fediverse/invite")
        .register_revocation_checker(checker)
        .merge_routes(router)
};

Pour un essai local multi-instances (3 noeuds federes via Docker Compose), voir tests/fediverse-testbed/README.md. Guide operateur complet : docs/fediverse-operations.md.

Migrations

Les migrations sont gerees avec SeaORM Migration :

# Manuellement
cargo run --bin migrate

# Automatiquement au demarrage (via le builder)
.auto_migrate(true)

Pour combiner avec vos propres migrations :

use rustwarden_core::migrations::core_migrations;

struct AppMigrator;

impl MigratorTrait for AppMigrator {
    fn migrations() -> Vec<Box<dyn MigrationTrait>> {
        let mut all = core_migrations();
        all.push(Box::new(MyCustomMigration));
        all
    }
}

Internationalisation (i18n)

Les traductions sont dans locales/ au format YAML. 4 langues incluses : fr, en, de, es.

# locales/fr.yml
products:
  title: "Produits"
  empty: "Aucun produit trouve"

Utilisation dans un handler :

use rustwarden_core::i18n::service::I18nService;
use rustwarden_core::i18n::extractor::Locale;
use std::sync::Arc;
use axum::extract::Extension;

async fn my_page(
    locale: Locale,
    Extension(i18n): Extension<Arc<I18nService>>,
) -> String {
    i18n.t(&locale.0, "products.title")
}

La locale est detectee automatiquement dans cet ordre :

1. Cookie locale
2. Header Accept-Language
3. DEFAULT_LOCALE (env var)

Commandes utiles

Documentation complementaire