Skip to content

TODO.md

Latest commit

 

History

History
198 lines (162 loc) · 12.1 KB

TODO.md

File metadata and controls

198 lines (162 loc) · 12.1 KB
Raw

Neev - Project Status & TODO

Enterprise User Management Package for Laravel Last updated: 2026-07-02

Completed Features

Authentication

  • Password-based login/registration
  • Magic link (passwordless) authentication
  • Passkey/WebAuthn support (biometric, hardware keys)
  • OAuth/Social login (Google, GitHub, Microsoft, Apple)
  • Password reset via email link
  • Password change for authenticated users
  • Configurable password complexity rules (min/max, mixed case, numbers, symbols)
  • Email verification with signed links

Multi-Factor Authentication (MFA)

  • TOTP authenticator app support (Google Authenticator, Authy, 1Password)
  • Email OTP (6-digit codes with configurable expiry)
  • Recovery codes (8 single-use backup codes, hash-stored)
  • Preferred MFA method tracking per user
  • MFA enforcement during login flow
  • Setup verification (pending → active): authenticator only enforced after the user proves the setup with a valid TOTP; abandoned setups purged by neev:clean-pending-mfa-setups

Team Management

  • Team CRUD with auto-slug generation
  • Invite members by email with signed links
  • Role-based access (member, admin, owner)
  • Accept/reject invitations
  • Request-to-join flow for public teams
  • Team switching (multi-team users)
  • Ownership transfer
  • Reserved slug prevention

Domain Federation

  • Email domain claiming by teams
  • DNS verification for domains
  • Auto-join rules based on email domain
  • Primary domain assignment per team
  • Custom security rules per domain

Multi-Tenancy

  • Subdomain-based tenant routing
  • Custom domain support with DNS verification
  • TenantResolver service (singleton, hostname-based)
  • Per-tenant authentication configuration
  • Per-tenant SSO (Microsoft Entra ID, Google Workspace, Okta)
  • TenantSSOManager with dynamic Socialite configuration
  • Auto-provisioning of SSO users
  • Single/multi-tenant user mode option

Security

  • Brute force protection (progressive delay via login_throttle: exponential backoff after delay_after failures, capped at max_delay_seconds)
  • Login attempt tracking (IP, browser, OS, device, GeoIP location)
  • Password history (prevents reusing last N passwords)
  • Password expiry enforcement (password_expiry_days config + opt-in neev:password-not-expired middleware, added in v0.4.0)
  • Email verification enforcement (opt-in neev:verified-email middleware, added in v0.4.4)
  • MaxMind GeoIP integration for IP geolocation

API & Access Tokens

  • Persistent API tokens with permission scoping
  • Temporary login tokens with auto-expiry
  • Token CRUD (create, update, delete, list, bulk delete)
  • SHA256 token hashing

Email Management

  • Single email per user on the users table (separate emails/passwords tables dropped and consolidated onto users)
  • Email verification tracking
  • Email change with reverification
  • Mailables: VerifyUserEmail, EmailOTP, LoginUsingLink, TeamInvitation, TeamJoinRequest

Views & UI

  • 66 Blade templates (auth, account, team, components, layouts)
  • 35+ reusable Blade components
  • Guest & authenticated layouts
  • Email templates (5 files)

Database

  • 12 migrations covering the schema (users + login_attempts, otps, passkeys, multi_factor_auths, recovery_codes, tenants, access_tokens, teams + memberships, team_invitations, domains, team_auth_settings, tenant_auth_settings); password history stored as JSON on users

Console Commands

  • neev:install - Setup wizard (tenant yes/no, teams yes/no)
  • neev:download-geoip - Download MaxMind GeoLite2 database
  • neev:clean-login-attempts - Remove old login records
  • Tenant commands - create / list / show
  • Domain commands - add / verify / list
  • Member commands - add / remove / list
  • Auth settings commands - configure / show
  • Team command - activate

Middleware

  • neev:web - Web authentication with MFA (TenantMiddleware > ResolveTeamMiddleware > NeevMiddleware > EnsureTenantMembership > BindContextMiddleware)
  • neev:api - API token authentication (TenantMiddleware > ResolveTeamMiddleware > NeevAPIMiddleware > EnsureTenantMembership > BindContextMiddleware)
  • neev:login - MFA step-up JWT authentication (TenantMiddleware > ResolveTeamMiddleware > JwtLoginMiddleware > EnsureTenantMembership > BindContextMiddleware)
  • neev:tenant - Tenant resolution, required (TenantMiddleware:required > ResolveTeamMiddleware > BindContextMiddleware)
  • neev:active-team - Blocks inactive teams
  • neev:active-tenant - Blocks inactive tenants
  • neev:tenant-member - Verifies user belongs to tenant
  • neev:resolve-team - Resolves team from route parameter
  • neev:ensure-sso - Enforces SSO-only access for current context
  • neev:password-not-expired - Blocks users with expired passwords (opt-in)
  • neev:verified-email - Blocks users with unverified email (opt-in)

Configuration

  • Minimal config surface (~20 keys, two orthogonal identity flags tenant + team) after the v0.4.0 config overhaul; per-tenant/team auth behaviour lives in tenant_auth_settings/team_auth_settings DB tables

Documentation

  • Markdown docs in docs/ (README, installation, configuration, authentication, API reference, web routes, CLI commands, teams, MFA, multi-tenancy, security, architecture, architecture internals, db schema) plus design docs (docs/rfcs/, config-refactor.md, spa-cookie-mode.md)

In Progress

Events System

  • LoggedIn / LoggedOut (renamed from LoggedInEvent/LoggedOutEvent)
  • DomainVerified / DomainReverified / DomainVerificationFailed - Domain lifecycle events (v0.4.0)
  • Laravel-native events where semantics match: Registered, PasswordReset, Lockout
  • PasswordChanged, EmailVerified, MfaMethodAdded, MfaMethodRemoved, RecoveryCodesGenerated, TeamCreated, TeamDeleted, MemberAdded, MemberRemoved, TenantCreated, SsoUserProvisioned
  • Event listeners / subscribers for common use cases (e.g. security-event email notifications)

Production Readiness Audit — Pending Follow-ups (2026-03-01)

Items identified during the production readiness audit. All critical, high, and medium code issues have been fixed. These are remaining documentation and feature gaps.

Documentation Gaps

  • Events system expansion — Laravel-native events (Registered, PasswordReset, Lockout) plus Neev events for MFA changes, password changes, team/tenant lifecycle, membership, SSO provisioning, email verification, and domain verification. Documented in docs/README.md.
  • Identity mode decision matrix — four-mode matrix + "Four Questions to Decide" in docs/multi-tenancy.md, cross-linked from architecture.md.
  • SSO SPA flow documentation — covered in docs/spa-authentication.md (SSO → SPA section: discovery, redirect, cookie vs fragment callback).
  • Middleware usage and ordering documentation — authoritative "Middleware Usage & Ordering" section in docs/architecture-internals.md.
  • Queue/background job tenant context — documented in docs/multi-tenancy.md (Console & Queue Context) with a complete job example.
  • OAuth security bypass documentation — verified against the callback flows and prominently documented in docs/authentication.md + docs/security.md, with mitigations (provider allowlist, neev:ensure-sso).
  • CORS/SPA guidance — covered in docs/spa-authentication.md (backend setup: cors.php example, credentials, encryption caveats).

Code Cleanup

  • Remove unused MembershipService — removed (verified: never injected or referenced).
  • Extract isDomainVerified() — the four private copies (plus one inline variant) replaced by Domain::isVerifiedForEmail(). (The old note's EmailDomainValidator target no longer exists.)
  • Web/API registration feature parity — RegistrationService now owns validation rules, user creation, invitation acceptance, federated-domain team rules, OAuth registration, the transaction, and the Registered event; all four controllers delegate to it. Future hooks (email reputation, RFC-001 self-registration routing) plug in here.
  • Lint violations in demo/ directory — obsolete: demo/ is gitignored (local-only, not shipped).

TODO - Pending Work

Code TODOs

Testing

  • Test suite - Comprehensive test suite with 60%+ line coverage
    • Unit tests for Services, Middleware, Models, Traits, Scopes
    • Feature tests for Authentication flows, Tenant SSO, Tenant Domains
  • Expand test coverage - Additional tests needed:
    • Feature tests for MFA flows (TOTP setup/verify, Email OTP, recovery codes)
    • Feature tests for Team management (CRUD, invitations, membership, switching)
    • Feature tests for API token management
    • Integration tests for rate limiting and brute force protection

Security Enhancements

  • SAML 2.0 support - Currently only OAuth/Socialite-based SSO; SAML would unlock enterprise IdPs (ADFS, PingFederate, etc.)
  • SMS-based MFA - Only TOTP and email OTP supported currently
  • Suspicious login detection & alerts - Mentioned in docs but no dedicated implementation beyond GeoIP tracking
  • Session management - Active sessions listing (GET /neev/sessions, web views), remote logout of all sessions, and single-session revoke (DELETE /neev/sessions/{id})
  • Admin override for MFA recovery - Support-assisted account recovery when all MFA methods lost

Feature Enhancements

  • Webhook support - Allow apps to receive webhook callbacks on auth/team events
  • Audit logging - Comprehensive audit trail beyond login attempts (e.g., permission changes, team settings updates, token operations)
  • Account deletion / data export - GDPR compliance features (right to deletion, data portability)
  • Email notifications for security events - New device login, password changed, MFA disabled, etc.
  • Admin dashboard views - Team/user administration for app owners
  • IP allowlist/blocklist - Per-tenant or global IP access control
  • Rate limiting with Redis - Distributed rate limiting for multi-server deployments (currently cache-based)

Code Quality

  • Decompose large controllers - UserAuthController.php (27 methods) and TeamApiController.php (26 methods) could benefit from splitting into focused controllers. ⚠ BREAKING when done: apps that published routes/neev.php reference these controller class names — splitting/renaming breaks their published copies. Must ship with an UPGRADING entry (re-publish or update class references), not as casual housekeeping.
  • PHPStan / static analysis - Level 5 with Larastan, integrated in CI
  • PHP CS Fixer / Pint config - PSR-12 code style enforcement via Pint

DevOps & CI

  • CI/CD pipeline - GitHub Actions for tests, static analysis, code style, Codecov coverage
  • Automated GeoIP database updates - Scheduled workflow for monthly MaxMind DB refresh
  • Package publishing automation - Automated Packagist release on tag

Architecture Notes

  • Feature-flagged design: All major features (teams, tenancy, federation, MFA) are toggle-able via config
  • Extensible models: User and Team models are swappable via config
  • Laravel 12.x compatible, PHP 8.3+
  • Key dependencies: geoip2/geoip2, web-auth/webauthn-lib, laravel/socialite, spomky-labs/otphp, ssntpl/laravel-acl