Push notification 2fa

[runleveldev]

Pull Request Summary: Push Notification-Based 2FA

Overview

Implements a configurable push notification-based two-factor authentication (2FA) system using MieWeb Auth App for enhanced security.

Features Added

1. Data Model & Database

• New Setting model for key-value configuration storage
• Migration creates Settings table with key (primary) and value columns
• Seeder initializes:
  • push_notification_url → ''
  • push_notification_enabled → 'false'

2. Admin Settings UI (/settings)

• Admin-only configuration page for push notification settings
• Fields:
  • Push Notification URL: Text input for notification service endpoint
  • Enable Push Notification 2FA: Checkbox to activate feature
• Validation: Cannot enable 2FA without a valid URL
• Access Control: 403 Forbidden for non-admin users
• Accessibility: Full ARIA labels, semantic HTML, keyboard navigation

3. LDAP Integration (ldap.conf)

• Dynamically configures authentication backends based on settings:
  • Enabled: AUTH_BACKENDS=sql,notification + NOTIFICATION_URL=${url}/send-notification
  • Disabled: AUTH_BACKENDS=sql (default)

4. Login Flow with 2FA

After password verification, before session creation:

• POSTs to ${push_notification_url}/send-notification with:

  {
    "username": "...",
    "title": "Authentication Request",
    "body": "Please review and respond...",
    "actions": [
      {"icon": "approve", "title": "Approve", "callback": "approve"},
      {"icon": "reject", "title": "Reject", "callback": "reject"}
    ]
  }

• Response handling:
  • ✅ action === 'approve' (case-insensitive) → Login succeeds
  • ❌ action !== 'approve' → Login denied
  • 📱 No device found → Shows registration link
  • 🔴 HTTP error → Login denied

5. Documentation

• Admin Guide: New settings.md with configuration instructions, screenshots, and workflow
• Developer Docs: Updated system-architecture.md with:
  • Push Notification Service in architecture diagram
  • Enhanced authentication sequence diagram showing 2FA flow
  • API specification for notification service
• Database Schema: Added Setting entity to database-schema.md

Files Changed

New Files (5)

• setting.js - Setting model
• 20260120165508-create-settings.js - Database migration
• 20260120165612-push-notification-settings.js - Initial settings
• settings.js - Settings page routes
• index.ejs - Settings UI
• settings.md - Admin documentation
• settings-page.png - Screenshot

Modified Files (7)

• login.js - 2FA integration
• sites.js - ldap.conf generation
• server.js - Settings route registration
• login.ejs - HTML error messages with hyperlinks
• create-a-container/views/partials/header.ejs - Settings navigation link
• database-schema.md - Setting entity
• system-architecture.md - Architecture diagrams
• index.md - Feature list update

Testing Performed

• ✅ Admin user can access and configure settings
• ✅ Non-admin users receive 403 Forbidden
• ✅ Validation prevents enabling 2FA without URL
• ✅ Login with 2FA: Approve → success
• ✅ Login with 2FA: Reject → denied
• ✅ No device registered → shows registration link
• ✅ 2FA disabled → normal login flow

Security Considerations

• Admin-only access to settings configuration
• Generic 403 error messages prevent information leakage
• Case-insensitive action comparison for robustness
• Graceful handling of notification service failures