nexus-scribe-auth

Authentication and authorization services including JWT tokens, MFA, and account protection.

Overview

Comprehensive authentication system with:

• JWT token generation and validation
• Password hashing with Argon2id
• TOTP-based multi-factor authentication
• Role-based access control
• Account lockout protection

Password Hashing

Secure password hashing using Argon2id:

use nexus_scribe_auth::{hash_password, verify_password};

// Hash password
let hash = hash_password("SecurePassword123!")?;

// Verify password
let valid = verify_password("SecurePassword123!", &hash)?;
assert!(valid);

JWT Tokens

Generate Access Token

use nexus_scribe_auth::{generate_access_token, validate_token, UserRole};

let token = generate_access_token(
    user_id,
    "user@example.com",
    UserRole::Admin,
    &jwt_secret,
    3600,  // 1 hour expiry
)?;

Token Types

Type	Purpose	Expiry
Access	API authentication	1 hour
Refresh	Token renewal	30 days
PreMfa	MFA verification pending	5 minutes

Pre-MFA Tokens

Issued when MFA is required but not yet completed:

use nexus_scribe_auth::{generate_pre_mfa_token, validate_pre_mfa_token};

// After password verification
let pre_mfa_token = generate_pre_mfa_token(
    user_id,
    "user@example.com",
    UserRole::User,
    &jwt_secret,
)?;

// Verify it's a pre-MFA token
let claims = validate_pre_mfa_token(&pre_mfa_token, &jwt_secret)?;

Multi-Factor Authentication

TOTP Setup

use nexus_scribe_auth::{generate_totp_secret, verify_totp_code};

// Generate secret for user enrollment
let secret = generate_totp_secret();
// Share with user for authenticator app setup

// Verify code from user
let valid = verify_totp_code(&secret, "123456")?;

Supports clock drift tolerance of +/- 30 seconds.

Password Policy

use nexus_scribe_auth::{validate_password_strength, PasswordPolicy};

let policy = PasswordPolicy {
    min_length: 12,
    require_uppercase: true,
    require_lowercase: true,
    require_digit: true,
    require_special: true,
};

let result = validate_password_strength("WeakPass", &policy);
// Returns Err with list of violations

Account Lockout

Protection against brute-force attacks:

use nexus_scribe_auth::{
    check_account_lockout,
    record_failed_login,
    reset_lockout,
    LockoutConfig,
};

let config = LockoutConfig {
    max_failed_attempts: 5,
    base_lockout_duration_secs: 15 * 60,  // 15 minutes
    max_lockout_duration_secs: 24 * 60 * 60,  // 24 hours
    attempt_window_secs: 15 * 60,
};

// Check before login attempt
let status = check_account_lockout("user@example.com", &config);
if status.is_locked {
    return Err("Account locked. Try again in {} seconds", status.retry_after_secs);
}

// Record failed attempt
let result = record_failed_login("user@example.com", &config);
if result.is_locked {
    // Account is now locked
}

// Reset on successful login
reset_lockout("user@example.com");

Features:

• Exponential backoff (doubles with each lockout)
• Per-user tracking
• Automatic window reset

Claims Structure

pub struct Claims {
    pub sub: String,       // User ID
    pub email: String,
    pub role: UserRole,
    pub exp: i64,          // Expiration
    pub iat: i64,          // Issued at
    pub token_type: TokenType,
    pub org_id: Option<String>,  // Multi-tenant support
}

Usage

[dependencies]
nexus-scribe-auth = { path = "../nexus-scribe-auth" }