Add identity strategy system with tenant isolation architecture

Introduce dual identity strategies (shared/isolated) backed by entity-agnostic
contracts. In shared mode, users are global and teams serve as collaboration
boundaries. In isolated mode, users are scoped to tenants, which are resolved
before authentication.

New models: Tenant, TenantAuthSettings
New services: ContextManager, MembershipService, IdentityProviderService
New contracts: ContextContainerInterface, ResolvableContextInterface,
  IdentityProviderOwnerInterface, HasMembersInterface
New middleware: BindContextMiddleware, EnsureContextSSO, ResolveTeamMiddleware
New traits: BelongsToTeam, TeamScope

Rewrite documentation as organized hub with architecture guides, fix stale
references, and add cross-links throughout all docs.

996 tests pass, PHPStan clean, Pint clean.

Author: sambhav-aggarwal

CHANGELOG.md

@@ -7,6 +7,90 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.2.0] - 2025-02-20
+
+### Added
+- **Identity strategy system** — choose between `shared` (users global, teams as collaboration) and `isolated` (users scoped to tenant, tenant resolved before auth) via `config('neev.identity_strategy')`
+- **Tenant model** (`Ssntpl\Neev\Models\Tenant`) — dedicated identity boundary for isolated mode with slug-based resolution, managed-by hierarchy, and SSO ownership
+- **TenantAuthSettings model** — per-tenant SSO configuration (mirrors TeamAuthSettings for isolated mode)
+- **ContextManager service** — request-scoped singleton holding resolved tenant, team, and user; immutable after binding
+- **Entity-agnostic contracts** — `ContextContainerInterface`, `ResolvableContextInterface`, `IdentityProviderOwnerInterface`, `HasMembersInterface` — same service code works for both Team and Tenant
+- **MembershipService** — entity-agnostic membership checks via `HasMembersInterface`
+- **IdentityProviderService** — entity-agnostic SSO/auth queries via `IdentityProviderOwnerInterface`
+- **BindContextMiddleware** — locks ContextManager after middleware pipeline, clears after response
+- **EnsureContextSSO middleware** (`neev:ensure-sso`) — enforces SSO-only access for teams/tenants with SSO configured
+- **ResolveTeamMiddleware** (`neev:resolve-team`) — resolves team from route parameter (numeric ID or slug)
+- **TeamScope** global scope and `BelongsToTeam` trait — team-level model scoping (complements existing `BelongsToTenant`)
+- **`tenants` migration** — `id`, `name`, `slug` (unique), `managed_by_tenant_id` (self-reference for reseller model)
+- **`tenant_auth_settings` migration** — SSO config for tenants in isolated mode
+- **TenantFactory and TenantAuthSettingsFactory** for testing
+- **Install wizard stubs** — published migration stubs for hard user isolation (`tenant_id` on users table)
+- **Architecture documentation** — `docs/architecture.md` (identity strategy, tenant vs team concepts, context lifecycle) and `docs/architecture-internals.md` (interfaces, patterns, coding standards)
+- Comprehensive test suite — 996 tests, 1886 assertions
+
+### Changed
+- **TenantResolver** now resolves `Tenant` in isolated mode and `Team` in shared mode via the `ContextContainerInterface` abstraction. Backward-compatible `current()` method still returns Team
+- **TenantResolver** populates `ContextManager` automatically on resolution
+- **Middleware pipeline** reordered: TenantMiddleware → ResolveTeamMiddleware → Auth → EnsureTenantMembership → BindContextMiddleware
+- **TenantMiddleware** now uses `TenantResolver::resolve()` which handles X-Tenant header, subdomain, and custom domain resolution in a unified flow
+- **EnsureTenantMembership** updated to work with `ContextManager` and `MembershipService`
+- **TenantSSOManager** refactored to accept `IdentityProviderOwnerInterface` — works with both Team and Tenant
+- **TenantSSOController** updated to use `ContextManager` for tenant resolution and `IdentityProviderOwnerInterface` for SSO
+- **Team model** now implements `ContextContainerInterface`, `ResolvableContextInterface`, `IdentityProviderOwnerInterface`, `HasMembersInterface`
+- **Domain model** gains `tenant_id` foreign key and `tenant()` relationship for isolated mode
+- **AccessToken model** gains tracking fields (`last_used_ip`, `user_agent`, etc.)
+- **BelongsToTenant trait** updated to be identity-strategy-aware — resolves to `teams` or `tenants` table depending on config
+- **NeevServiceProvider** registers `ContextManager` as scoped singleton, registers new middleware aliases
+- **TenantScope** updated to read from `ContextManager` instead of `TenantResolver` directly
+- Minimum PHP version bumped to 8.3
+- Dropped Laravel 10 support (Laravel 11.x and 12.x only)
+- CI workflows updated for PHP 8.3
+
+### Fixed
+- Fixed copy-paste error in API reference docs — "Send Verification Email" response now correctly says "Verification email has been sent"
+- Fixed duplicated "Customizing Routes" section in web routes documentation
+
+### Documentation
+- **docs/README.md** rewritten as organized documentation hub (Guides / Reference / Architecture)
+- **docs/multi-tenancy.md** — added Identity Strategy section, ContextManager section, fixed TenantResolver method signatures, added BelongsToTeam docs, updated database schema
+- **docs/configuration.md** — added `identity_strategy` and `tenant_model` options
+- **docs/installation.md** — added multi-tenancy and architecture links
+- **README.md** — added `identity_strategy` to feature toggles, middleware aliases table, updated database schema, added architecture docs link, added Contributing/Security links
+- **CLAUDE.md** — updated with all new directories, models, middleware, services, traits, and patterns
+- **TODO.md** — updated stale items (tests, PHPStan, Pint, CI now marked complete)
+- Cross-links added between all documentation files
+
+## [0.1.2] - 2025-02-11
+
+### Added
+- Comprehensive test suite with 60%+ line coverage
+- Codecov coverage integration
+- CI badges (code style, static analysis, tests, coverage)
+
+### Changed
+- Minimum PHP version bumped to 8.3
+- Dropped Laravel 10 support
+- CI workflows updated for PHP 8.3
+
+## [0.1.1] - 2025-12-16
+
+### Added
+- Code quality tooling (PHPStan level 5, Pint PSR-12)
+- GitHub Actions CI workflows (tests, static analysis, code style)
+- Community files (CONTRIBUTING.md, CODE_OF_CONDUCT.md, SECURITY.md, CHANGELOG.md)
+- Database factories
+
+### Changed
+- Simplified and refined codebase for clarity and consistency
+- Hash OTPs at rest, fix model casts, clean up token handling
+
+### Fixed
+- Security vulnerabilities and bugs for public release
+- MFA setup bug fix
+- Recovery codes stored as hashed values
+
+## [0.1.0] - 2025-11-26
+
 ### Added
 - Initial public release
 - Password-based authentication with strong validation
@@ -28,3 +112,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - API token authentication with permissions
 - Comprehensive Blade views and email templates
 - Artisan commands for installation, GeoIP download, and cleanup
+
+[Unreleased]: https://github.com/ssntpl/neev/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/ssntpl/neev/compare/v0.1.2...v0.2.0
+[0.1.2]: https://github.com/ssntpl/neev/compare/v0.1.1...v0.1.2
+[0.1.1]: https://github.com/ssntpl/neev/compare/v0.1.0...v0.1.1
+[0.1.0]: https://github.com/ssntpl/neev/releases/tag/v0.1.0

README.md

@@ -528,11 +528,18 @@ Response:
 
 | Middleware | Description |
 |------------|-------------|
-| `neev:web` | Web authentication with MFA |
-| `neev:api` | API token authentication |
-| `neev:tenant` | Tenant resolution from domain |
-| `neev:tenant-web` | Tenant + web auth |
-| `neev:tenant-api` | Tenant + API auth |
+| `neev:web` | Web authentication (includes tenant resolution when enabled) |
+| `neev:api` | API authentication (includes tenant resolution when enabled) |
+| `neev:tenant` | Tenant resolution from domain (no auth) |
+
+### Middleware Aliases
+
+| Alias | Description |
+|-------|-------------|
+| `neev:active-team` | Blocks access when team is inactive/waitlisted |
+| `neev:tenant-member` | Ensures user is a member of the current tenant |
+| `neev:resolve-team` | Resolves team from route parameter |
+| `neev:ensure-sso` | Enforces SSO-only access for the current context |
 
 ---
 
@@ -594,6 +601,7 @@ php artisan neev:download-geoip
 'email_verified' => true,          // Require verification
 'require_company_email' => false,  // Waitlist free emails
 'domain_federation' => true,       // Domain-based joining
+'identity_strategy' => 'shared',   // 'shared' or 'isolated'
 'tenant_isolation' => false,       // Multi-tenancy
 'tenant_auth' => false,            // Per-tenant auth
 'support_username' => false,       // Username login
@@ -695,8 +703,10 @@ protected function schedule(Schedule $schedule)
 
 | Table | Description |
 |-------|-------------|
+| `tenants` | Tenant organizations (isolated identity mode) |
 | `domains` | Custom tenant domains and domain federation |
-| `team_auth_settings` | Per-tenant auth config |
+| `team_auth_settings` | Per-team auth/SSO config |
+| `tenant_auth_settings` | Per-tenant auth/SSO config (isolated mode) |
 
 ---
 
@@ -715,6 +725,8 @@ For comprehensive documentation, see the [docs folder](./docs/):
 | [Teams](./docs/teams.md) | Team management guide |
 | [Multi-Tenancy](./docs/multi-tenancy.md) | SaaS multi-tenant setup |
 | [Security](./docs/security.md) | Security features & best practices |
+| [Architecture](./docs/architecture.md) | Identity strategy, tenancy & team design |
+| [Architecture Internals](./docs/architecture-internals.md) | Interfaces, patterns & coding standards |
 
 ---
 
@@ -726,6 +738,14 @@ For comprehensive documentation, see the [docs folder](./docs/):
 
 ---
 
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for setup instructions, coding standards, and how to submit pull requests.
+
+Report security vulnerabilities following the process in [SECURITY.md](SECURITY.md).
+
+---
+
 ## License
 
 MIT License. See [LICENSE](LICENSE) for details.

config/neev.php

@@ -74,14 +74,24 @@
     */
     'domain_federation' => false,
 
+    /*
+    | Identity Strategy
+    | -----------------
+    | 'shared'   — Users are global. Same user may belong to multiple teams.
+    |              Tenant concept is hidden. (Default, backward compatible)
+    | 'isolated' — Users are scoped inside a tenant. Same email may exist
+    |              in multiple tenants. Tenant resolved before authentication.
+    */
+    'identity_strategy' => 'shared',
+
     /*
     | Tenant Isolation (Multi-Tenancy)
     | ---------------------------------
     | When enabled: Teams are isolated by domain/subdomain. Each tenant runs on
     | their own domain (tenant1.yourapp.com) or custom domain (tenant1.com).
     | Requires: 'team' feature to be enabled
     | Database: Requires domains table
-    | Middleware: Adds 'neev:tenant' and 'neev:tenant-api' middleware groups
+    | Middleware: Activates tenant resolution in 'neev:web' and 'neev:api' middleware groups
     | Use case: SaaS applications with isolated tenants
     | Default: false (no domain-based tenant isolation)
     */
@@ -161,19 +171,19 @@
     | Tenant-Driven Authentication
     |--------------------------------------------------------------------------
     |
-    | When enabled, each tenant can configure their own authentication method.
-    | Tenants choose between password authentication (default) or SSO via
+    | When enabled, each tenant or team can configure their own authentication method.
+    | They choose between password authentication (default) or SSO via
     | external identity providers (Microsoft Entra ID, Google, Okta, etc.).
-    | Requires: 'tenant_isolation' feature to be enabled.
+    | In shared mode, teams own SSO config. In isolated mode, tenants own SSO config.
     |
     */
 
     /*
     | Enable Tenant-Driven Authentication
     | ------------------------------------
-    | When true: Tenants can configure their authentication method (password or SSO).
+    | When true: Tenants/teams can configure their authentication method (password or SSO).
     | The auth method is checked on login and users are routed accordingly.
-    | Requires: 'tenant_isolation' = true
+    | Works in both shared mode (team-level SSO) and isolated mode (tenant-level SSO).
     | Default: false
     */
     'tenant_auth' => false,
@@ -263,6 +273,17 @@
     |
     */
 
+    /*
+    | Tenant Model Class
+    | ------------------
+    | The Eloquent model used for tenant management in isolated identity mode.
+    | Custom model requirements:
+    | - Must extend Ssntpl\Neev\Models\Tenant or implement same interfaces
+    | - Must implement: ContextContainerInterface, IdentityProviderOwnerInterface, HasMembersInterface
+    | Example: App\Models\Tenant::class
+    */
+    'tenant_model' => Ssntpl\Neev\Models\Tenant::class,
+
     /*
     | Team Model Class
     | ----------------

database/factories/TenantAuthSettingsFactory.php

@@ -0,0 +1,38 @@
+<?php
+
+namespace Ssntpl\Neev\Database\Factories;
+
+use Illuminate\Database\Eloquent\Factories\Factory;
+use Ssntpl\Neev\Models\TenantAuthSettings;
+
+class TenantAuthSettingsFactory extends Factory
+{
+    protected $model = TenantAuthSettings::class;
+
+    public function definition(): array
+    {
+        return [
+            'tenant_id' => TenantFactory::new(),
+            'auth_method' => 'password',
+        ];
+    }
+
+    public function sso(string $provider = 'entra'): static
+    {
+        return $this->state([
+            'auth_method' => 'sso',
+            'sso_provider' => $provider,
+            'sso_client_id' => 'test-client-id',
+            'sso_client_secret' => 'test-client-secret',
+            'sso_tenant_id' => 'test-tenant-id',
+        ]);
+    }
+
+    public function autoProvision(string $role = 'member'): static
+    {
+        return $this->state([
+            'auto_provision' => true,
+            'auto_provision_role' => $role,
+        ]);
+    }
+}

database/factories/TenantFactory.php

@@ -0,0 +1,19 @@
+<?php
+
+namespace Ssntpl\Neev\Database\Factories;
+
+use Illuminate\Database\Eloquent\Factories\Factory;
+use Ssntpl\Neev\Models\Tenant;
+
+class TenantFactory extends Factory
+{
+    protected $model = Tenant::class;
+
+    public function definition(): array
+    {
+        return [
+            'name' => fake()->company(),
+            'slug' => fake()->unique()->slug(2),
+        ];
+    }
+}

database/migrations/2025_01_01_000005a_create_tenants_table.php

@@ -0,0 +1,29 @@
+<?php
+
+use Illuminate\Database\Migrations\Migration;
+use Illuminate\Database\Schema\Blueprint;
+use Illuminate\Support\Facades\Schema;
+
+return new class () extends Migration {
+    /**
+     * Run the migrations.
+     */
+    public function up(): void
+    {
+        Schema::create('tenants', function (Blueprint $table) {
+            $table->id();
+            $table->string('name');
+            $table->string('slug')->unique();
+            $table->foreignId('managed_by_tenant_id')->nullable()->constrained('tenants')->nullOnDelete();
+            $table->timestamps();
+        });
+    }
+
+    /**
+     * Reverse the migrations.
+     */
+    public function down(): void
+    {
+        Schema::dropIfExists('tenants');
+    }
+};

database/migrations/2025_01_01_000006_create_access_tokens_table.php

@@ -13,6 +13,7 @@ public function up(): void
         Schema::create('access_tokens', function (Blueprint $table) {
             $table->id();
             $table->foreignId('user_id')->constrained()->onDelete('cascade');
+            $table->foreignId('tenant_id')->nullable()->constrained('tenants')->nullOnDelete();
             $table->unsignedBigInteger('attempt_id')->nullable();
             $table->string('name');
             $table->string('token')->unique();

database/migrations/2025_01_01_000007_create_teams_table.php

@@ -12,6 +12,7 @@ public function up(): void
     {
         Schema::create('teams', function (Blueprint $table) {
             $table->id();
+            $table->foreignId('tenant_id')->nullable()->constrained('tenants')->nullOnDelete();
             $table->foreignId('user_id')->constrained()->onDelete('cascade');
             $table->string('name');
             $table->string('slug')->unique()->nullable();
@@ -20,13 +21,18 @@ public function up(): void
             $table->string('inactive_reason')->nullable();
             $table->timestamps();
             $table->unique(['name', 'user_id']);
+            $table->unique(['tenant_id', 'slug']);
             $table->index('slug');
         });
 
         Schema::table('users', function (Blueprint $table) {
             $table->foreignId('current_team_id')->nullable()->constrained('teams')->nullOnDelete();
         });
 
+        Schema::table('tenants', function (Blueprint $table) {
+            $table->foreignId('platform_team_id')->nullable()->constrained('teams')->nullOnDelete();
+        });
+
         Schema::create('team_user', function (Blueprint $table) {
             $table->id();
             $table->foreignId('team_id')->constrained()->onDelete('cascade');
@@ -48,6 +54,11 @@ public function down(): void
         Schema::table('users', function (Blueprint $table) {
             $table->dropConstrainedForeignId('current_team_id');
         });
+        if (Schema::hasColumn('tenants', 'platform_team_id')) {
+            Schema::table('tenants', function (Blueprint $table) {
+                $table->dropConstrainedForeignId('platform_team_id');
+            });
+        }
         Schema::dropIfExists('teams');
     }
 };

database/migrations/2025_01_01_000009_create_domains_table.php

@@ -13,6 +13,7 @@ public function up(): void
         Schema::create('domains', function (Blueprint $table) {
             $table->id();
             $table->foreignId('team_id')->constrained()->onDelete('cascade');
+            $table->foreignId('tenant_id')->nullable()->constrained('tenants')->nullOnDelete();
             $table->boolean('enforce')->default(false);
             $table->string('domain')->index();
             $table->string('verification_token')->nullable();