Authentication, RBAC & Security Guide

flowchart TD
    subgraph Roles["Administrator Roles"]
        SuperAdmin["Super Administrator (super_admin)\nGlobal platform privileges\nManage systems, assign admins, view all data"]
        Admin["Standard Administrator (admin)\nFull read/write permissions for specific assigned systems"]
        TopicAdmin["Topic Scoped Administrator (topic_admin)\nRestricted to explicitly authorized subsystem slugs"]
    end

    subgraph AuthMethods["Authentication Methods"]
        PasswordLogin["Account + Password (Argon2id validation)"]
        EmailLogin["Email + 6-digit Code (SMTP driven)"]
    end

    subgraph Token["Stateless Credentials"]
        JWT["JWT Token (Bearer Scheme)\nContains: id, username, role, allowed_systems"]
    end

    subgraph Middlewares["Security Enforcement"]
        M1["require_admin_auth\nVerifies JWT signature and expiry"]
        M2["require_topic_access\nVerifies claims.allowed_systems contains system_slug"]
    end

    subgraph Resources["Protected APIs"]
        AdminAPI["Platform Admin API (/api/v1/admin/*)"]
        TopicAdminAPI["Topic Admin API (/api/v1/admin/s/{slug}/*)"]
        CustomExtAPI["Custom Subsystem API (/api/v1/s/{slug}/ext/*)"]
    end

    AuthMethods --> JWT
    JWT --> M1
    M1 --> AdminAPI
    M1 --> M2
    M2 --> TopicAdminAPI
    M2 --> CustomExtAPI

use foundry::prelude::*;

// 1. Hash a plaintext password for database persistence
let raw_password = "MySecurePassword2026!";
let password_hash = hash_password(raw_password)?;
// Yields: $argon2id$v=19$m=19456,t=2,p=1$vB8...$4Q8...

// 2. Verify raw candidate against stored hash
let is_valid = verify_password(raw_password, &password_hash)?;
assert!(is_valid);

#[derive(Debug, Clone, Serialize, Deserialize)]
pub struct AdminClaims {
    /// Unique administrator ID in the database
    pub sub: i64,
    /// Administrator username
    pub username: String,
    /// Role identifier: "super_admin" | "admin" | "topic_admin"
    pub role: String,
    /// Whitelist of authorized subsystem slugs (e.g. ["shop", "blog"])
    /// If role == "super_admin", this may be empty as superadmins bypass checks
    pub allowed_systems: Vec<String>,
    /// Token expiration timestamp (UTC seconds)
    pub exp: usize,
}

sequenceDiagram
    autonumber
    actor Admin as Admin Browser
    participant API as Foundry Auth API
    participant SMTP as SMTP Mail Relay (lettre)
    participant Store as Database / Cache

    Admin->>API: POST /api/v1/admin/auth/email/send-code\n{ "email": "admin@company.com" }
    Note over API: 1. Locate admin bound to email<br/>2. Enforce 60s cooldown limit<br/>3. Generate 6-digit numeric verification code
    API->>Store: Store code (5-minute TTL)
    API->>SMTP: Dispatch security code email
    SMTP-->>Admin: "Your Foundry login code is: 839201"

    Admin->>API: POST /api/v1/admin/auth/email/login\n{ "email": "admin@company.com", "code": "839201" }
    Note over API: Verify code match and timestamp validity
    API->>Store: Invalidate used code (Prevent replay)
    API-->>Admin: Returns JWT token and admin profile

use axum::{Router, routing::get, middleware::from_fn_with_state};
use foundry::prelude::*;
use foundry_engine::middleware::require_admin_auth;

pub fn protected_routes(state: AppState) -> Router {
    Router::new()
        .route("/export-report", get(export_report_handler))
        .route_layer(from_fn_with_state(state.clone(), require_admin_auth))
}

async fn export_report_handler(
    Extension(claims): Extension<AdminClaims>,
) -> ApiResponse<String> {
    ApiResponse::ok(format!("Welcome admin: {}, ID: {}", claims.username, claims.sub))
}