Torvian.eu/chatbot
Watch
1
0
Fork
You've already forked chatbot
 0
Code Issues Pull requests Projects Releases 12 Packages Wiki Activity Actions
12 releases 12 tags
  • v0.4.0 835ad81813

    v0.4.0 Stable

    rwachters released this 2026-05-15 17:15:48 +00:00 | 611 commits to master since this release

    Torvian Chatbot v0.4.0

    Release Date: May 15, 2026

    🔐 Security & Authentication Overhaul

    This major release introduces comprehensive security enhancements to Torvian chatbot, featuring device trust management, multi-device session verification, email-based verification flows, and security alert mechanisms. The authentication architecture has been significantly refactored for better maintainability and extensibility.

    What's New

    🛡️ Device Trust & Security

    • Device Identity Tracking: Each client device gets a persistent identifier for security purposes
    • Account Security Modes: Choose between disabled, warning, or strict security levels
    • Unrecognized Device Alerts: Users are notified of login attempts from new devices with verification requirements
    • Trusted Device Management: Users can view and revoke previously trusted devices
    • Device-Based IP Tracking: Session IP addresses are recorded for suspicious activity detection

    📧 Email Verification Flows

    • Device Verification Email: Unrecognized devices receive an email verification link
    • Email Change Support: Users can change their account email address securely
    • SMTP Configuration: Full SMTP support with TLS/auth for email delivery
    • Email Validation: Email format and ownership validation before account changes

    🔑 Enhanced Password & Session Management

    • Configurable Auth Policies: Server-enforced username and password validation rules
    • Required Password Changes: Force users to change passwords when needed
    • Failed Login Protection: Sliding-window lockout after too many failed login attempts
    • Session Management: List active sessions, revoke specific sessions, or logout all sessions at once
    • Password-Protected Operations: Current password verification for sensitive account changes
    • Restricted Session Mode: Unverified devices have limited capabilities until verified

    🚨 Security Alerts & Resolution

    • Login Alerts: See all unrecognized device attempts that triggered verification
    • Trust or Dismiss: Users can acknowledge alerts to mark devices as trusted or dismiss them
    • Restricted Actions: Blocked session operations from unverified devices to prevent accidental damage
    • Permission Enforcement: Consistent authorization checks across all account operations

    🔄 Architecture Improvements (Backend)

    • Service Layer Refactoring: Split monolithic AuthenticationService into focused services:
      • TokenService - JWT and refresh token management
      • DeviceTrustService - Device trust and verification
      • SecurityAuditService - Audit record management
      • AccountManagementService - User account operations
    • ViewModel Refactoring: Split authentication flow into focused ViewModels for better state management
    • Error Handling: Structured API error codes instead of fragile string matching

    📊 Feature Details

    User-Facing Features

    • ✅ View and manage active sessions from device
    • ✅ Revoke access from other sessions without logging out
    • ✅ Logout all sessions at once
    • ✅ Change email address securely
    • ✅ Change password with current password verification
    • ✅ View security alerts for unrecognized logins
    • ✅ Trust or dismiss security alerts
    • ✅ Review and remove trusted devices
    • ✅ Forced password change flow for admin-triggered resets
    • ✅ Clipboard-friendly device ID sharing

    Server-Side Features

    • ✅ Device verification token lifecycle management
    • ✅ Rate-limited verification attempts
    • ✅ Single-use verification tokens (one-time links)
    • ✅ SMTP-based email notifications
    • ✅ Reverse proxy configuration support (for X-Forwarded-For headers)
    • ✅ Configurable security modes per environment
    • ✅ Public authentication policy endpoint for client validation rules
    • ✅ Audit trails for all device and session activities
    • ✅ Database migrations for all new security tables

    API Additions

    Session & Device Management:

    • GET /api/v1/auth/sessions - List active sessions
    • DELETE /api/v1/auth/logout?sessionId={id} - Revoke specific session
    • POST /api/v1/auth/logout-all - Logout all sessions
    • GET /api/v1/auth/trusted-devices - List trusted devices
    • DELETE /api/v1/auth/trusted-devices/{deviceId} - Revoke trusted device

    Device Verification (Authenticated):

    • POST /api/v1/auth/request-device-verification - Request verification email for current session

    Device Verification (Public):

    • GET /api/v1/public/auth/verify-device?token={token} - Verify device via email link (returns HTML success/failure page)
    • POST /api/v1/public/auth/request-device-verification - Public endpoint for users in STRICT mode without verified device

    Security & Account (Authenticated):

    • GET /api/v1/auth/security-alerts - Retrieve unrecognized login alerts
    • POST /api/v1/auth/security-alerts/{alertId}/resolve - Trust/dismiss alert
    • POST /api/v1/auth/change-password - Change password
    • POST /api/v1/auth/complete-required-password-change - Forced password change completion
    • POST /api/v1/auth/change-email - Change email address
    • GET /api/v1/auth/policy - Fetch account validation policy (public)

    ⚙️ Configuration Changes

    New Configuration Options

    Account Security & Authentication:

    {
  "accountSecurityMode": "WARNING",
  "authPolicy": {
    "passwordConfig": {
      "minLength": 8,
      "maxLength": 128,
      "requireLowercase": true,
      "requireUppercase": true,
      "requireDigit": true,
      "requireSpecialChar": true,
      "checkCommonPasswords": true
    },
    "usernameConfig": {
      "minLength": 3,
      "maxLength": 50,
      "allowedRegexPattern": "^[a-zA-Z0-9_-]+$"
    },
    "maxFailedAttempts": 10,
    "lockoutWindowMinutes": 5
  }
}

    Note: maxFailedAttempts is the maximum failed login attempts allowed within lockoutWindowMinutes before the account is temporarily locked. accountSecurityMode accepts: DISABLED, WARNING, or STRICT.

    Email Verification:

    {
  "email": {
    "provider": "smtp",
    "fromAddress": "noreply@example.com",
    "properties": {
      "host": "smtp.example.com",
      "port": "587",
      "user_env": "SMTP_USER",
      "password_env": "SMTP_PASSWORD",
      "auth": "true",
      "starttls": "true",
      "mail.smtp.ssl.trust": "smtp.example.com"
    }
  },
  "serverUrl": "https://chatbot.example.com"
}

    Note: Sensitive SMTP credentials should be provided via environment variables (prefixed with _env suffix) or in a separate secrets.json file, not in the main config.

    Reverse Proxy:

    {
  "reverseProxy": {
    "enabled": false,
    "proxyCount": 1,
    "useXForwardedHeaders": true,
    "useForwardedHeaders": false
  }
}

    Note: Enable reverseProxy.enabled and set proxyCount to match the number of proxies in front of your server (e.g., 1 for Caddy/Nginx). Set useForwardedHeaders to false for security unless your proxy explicitly overwrites this header.

    Migration Guide

    For Self-Hosted Deployments

    1. Update Configuration Files

      • Copy new settings from application.example-local.json or application.example-vps.json
      • Set accountSecurityMode to match your deployment profile
      • Configure SMTP settings if using email verification
      • Enable reverse proxy support if behind a proxy

    2. Database Migrations

      • 5 new migration files will be automatically applied on server startup:
        • V5__security_audit.sql - Security audit table
        • V6__user_trusted_devices.sql - Trusted devices table
        • V7__user_sessions_is_restricted.sql - Session restriction flag
        • V8__user_sessions_device_id.sql - Device ID on sessions
        • V9__failed_login_attempts.sql - Failed attempts tracking
        • V10__security_audit_status.sql - Alert status tracking
        • V11__device_verification_tokens.sql - Verification tokens

    3. Client Updates

      • Desktop, Web, and Android clients updated for new security flows
      • Device ID is generated and persisted locally on first launch
      • Users will see verification prompts for first-time device logins

    For Docker/Container Users

    • Environment variables support all new config options via env-mapping.json
    • Database migrations run automatically on container startup
    • No manual migration steps required

    🔄 Breaking Changes

    Client Applications:

    • Login endpoints now require deviceId in request payload
    • Auth ViewModel replaced with focused ViewModels - update dependency injection
    • Device identity must be generated and persisted by clients

    API Consumers:

    • Login response now includes isRestricted flag for device status
    • New verification-required error code for unverified devices
    • Email configuration required for device verification flows

    Server Deployment:

    • Email configuration is required if account security mode is enabled
    • SMTP credentials must be set in environment/config before first use
    • Reverse proxy setup may require explicit trust configuration

    📋 Database Migrations Summary

    Migration Purpose
    V5 Security audit tracking (device, IP, timestamp, status)
    V6 User trusted devices (device-user relationships)
    V7 Session restriction flag (for unverified devices)
    V8 Device ID field on sessions
    V9 Failed login attempts sliding-window tracking
    V10 Security audit status (PENDING/TRUSTED/DISMISSED)
    V11 Device verification tokens (single-use verification)

    📦 New Dependencies

    • jakarta.mail:jakarta.mail-api - Email API
    • com.sun.mail:angus-mail - Mail transport provider

    🧪 Testing & Validation

    For Users

    1. Login from a new device - you should receive a verification email
    2. Click verification link or use the in-app verification dialog
    3. After verification, device is marked as trusted
    4. Check "Trusted Devices" in user menu to see all trusted devices
    5. Try changing your email or password - both require current password confirmation

    For Administrators

    1. Monitor security audit logs for suspicious patterns
    2. Configure account security mode appropriate for your deployment (strict for high-security)
    3. Test email delivery if enabled
    4. Verify IP tracking is correct if behind a reverse proxy
    5. Check failed login attempts are being tracked properly

    For Integration Teams

    1. Update clients to send deviceId with login requests
    2. Handle verification-required error code appropriately
    3. Update UI to display restricted session state
    4. Implement email verification dialog if needed
    5. Fetch account validation policy from public endpoint

    🐛 Known Limitations

    • Device trust is device-scoped, not session-scoped (one device = one trusted identity)
    • Email verification tokens expire after 24 hours
    • Failed login window is rolling (calculated from each attempt)
    • Reverse proxy IP detection requires explicit trust configuration
    • SMTP is the only email provider currently supported

    📚 Documentation

    • See docs/Misc/arrow-typed-errors.md for error handling patterns
    • Review deploy/server/application.example-vps.json for production configuration
    • Check server/dev-config-sample/ for development setup examples

    🙏 Contributors

    Thanks to everyone who tested, reviewed, and provided feedback on the security features!

    📝 Release Notes Highlights

    Total Changes: 45 commits
    Files Modified: 150+ files
    New Services: 5 (Token, DeviceTrust, SecurityAudit, AccountManagement, SecurityNotification)
    New ViewModels: 5 (AuthEntry, Session, AccountManagement, SecurityAudit, UserProfile)
    New API Endpoints: 11
    New Database Tables: 5
    Test Coverage: 25+ new test classes

    🔗 Related Issues & PRs

    • PR #211: Settings and server details improvements
    • PR #212: Comprehensive security and session management
    • PR #213: Authentication refactoring and finalization

    For upgrading from v0.3.x, please review the Breaking Changes section above.

    Enjoy the enhanced security features in Torvian Chatbot v0.4.0! 🚀

    Downloads