PHPackages                             azaharizaman/nexus-identity - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Authentication & Authorization](/categories/authentication)
4. /
5. azaharizaman/nexus-identity

ActiveLibrary[Authentication & Authorization](/categories/authentication)

azaharizaman/nexus-identity
===========================

Domain layer: Framework-agnostic Identity and Access Management package for Nexus ERP

v0.1.0-alpha1(1mo ago)02↓100%2MITPHPPHP ^8.3

Since May 5Pushed 1mo agoCompare

[ Source](https://github.com/azaharizaman/nexus-identity)[ Packagist](https://packagist.org/packages/azaharizaman/nexus-identity)[ RSS](/packages/azaharizaman-nexus-identity/feed)WikiDiscussions main Synced 1w ago

READMEChangelogDependencies (7)Versions (2)Used By (2)

Nexus\\Identity
===============

[](#nexusidentity)

**Framework-agnostic Identity and Access Management package for Nexus ERP**

The Identity package provides a comprehensive, pure PHP solution for authentication, authorization, session management, and user identity management. It follows strict contract-driven design principles and integrates seamlessly with the Nexus monorepo architecture.

Features
--------

[](#features)

- ✅ **Pure PHP 8.3+** - No framework dependencies in core logic
- ✅ **CQRS Architecture** - Separate Query and Persist interfaces for clean separation
- ✅ **Contract-Driven** - All data structures and operations defined via interfaces
- ✅ **Role-Based Access Control (RBAC)** - Flexible permission management with role hierarchy
- ✅ **Direct Permission Assignment** - Bypass roles for fine-grained control
- ✅ **Wildcard Permissions** - `users.*` grants all user permissions
- ✅ **Session Management** - Secure token-based authentication
- ✅ **API Token Authentication** - Scoped tokens for programmatic access
- ✅ **Multi-Factor Authentication (MFA)** - TOTP, WebAuthn/Passkeys, Backup Codes
- ✅ **Single Sign-On (SSO)** - SAML, OAuth2, OIDC support (pluggable)
- ✅ **Password Security** - Argon2id hashing, breach detection, history tracking
- ✅ **Account Lifecycle** - Registration, activation, suspension, locking
- ✅ **Security Events** - Integration with AuditLogger
- ✅ **Multi-Tenant** - Tenant-scoped users and roles

Installation
------------

[](#installation)

```
composer require azaharizaman/nexus-identity:"*@dev"
```

Architecture
------------

[](#architecture)

### CQRS Pattern (v1.1.0+)

[](#cqrs-pattern-v110)

The package follows CQRS (Command Query Responsibility Segregation) pattern. Each repository domain has separate interfaces:

DomainQuery Interface (Read)Persist Interface (Write)User`UserQueryInterface``UserPersistInterface`Role`RoleQueryInterface``RolePersistInterface`Permission`PermissionQueryInterface``PermissionPersistInterface`MFA Enrollment`MfaEnrollmentQueryInterface``MfaEnrollmentPersistInterface`Trusted Device`TrustedDeviceQueryInterface``TrustedDevicePersistInterface`WebAuthn Credential`WebAuthnCredentialQueryInterface``WebAuthnCredentialPersistInterface`Backup Code`BackupCodeQueryInterface``BackupCodePersistInterface`**Best Practice:** Inject the specific Query or Persist interface based on your needs:

```
// For read-only operations
public function __construct(
    private readonly UserQueryInterface $userQuery
) {}

// For write operations
public function __construct(
    private readonly UserPersistInterface $userPersist
) {}
```

### Package Structure

[](#package-structure)

```
packages/domain/identity-security/
├── src/
│   ├── Contracts/              # Interfaces (CQRS Split)
│   │   ├── UserInterface.php
│   │   ├── UserQueryInterface.php      # Read operations
│   │   ├── UserPersistInterface.php    # Write operations
│   │   ├── UserRepositoryInterface.php # Combined (deprecated)
│   │   ├── RoleQueryInterface.php
│   │   ├── RolePersistInterface.php
│   │   ├── PermissionQueryInterface.php
│   │   ├── PermissionPersistInterface.php
│   │   └── ... (40+ interfaces)
│   ├── Services/               # Business Logic
│   │   ├── UserManager.php
│   │   ├── AuthenticationService.php
│   │   ├── MfaEnrollmentService.php
│   │   ├── MfaVerificationService.php
│   │   └── ... (10 services)
│   ├── ValueObjects/           # Immutable Data Structures
│   │   ├── UserStatus.php
│   │   ├── Credentials.php
│   │   ├── WebAuthnCredential.php
│   │   └── ... (20 value objects)
│   └── Exceptions/             # Domain Exceptions
│       ├── UserNotFoundException.php
│       ├── MfaRequiredException.php
│       └── ... (19 exceptions)
├── docs/
│   ├── getting-started.md
│   ├── api-reference.md
│   ├── integration-guide.md
│   └── examples/
├── tests/
├── composer.json
├── LICENSE
└── README.md

```

### Core Principles

[](#core-principles)

1. **Logic in Packages, Implementation in Applications**

    - Package defines **what** (interfaces, services, value objects)
    - Application defines **how** (Eloquent models, repositories, migrations)
2. **Framework Agnostic**

    - Zero Laravel dependencies in `src/`
    - No `Illuminate\*` classes
    - No Eloquent models
    - No database queries
3. **Dependency Injection**

    - Constructor injection for all dependencies
    - Interface-based dependencies only
4. **CQRS Separation**

    - Query interfaces for read operations
    - Persist interfaces for write operations
    - Clear command/query responsibility

Usage Examples
--------------

[](#usage-examples)

### User Management

[](#user-management)

```
use Nexus\Identity\Services\UserManager;
use Nexus\Identity\ValueObjects\Credentials;

// Create a new user
$user = $userManager->createUser([
    'email' => 'john@example.com',
    'password' => 'SecureP@ssw0rd!',
    'name' => 'John Doe',
    'tenant_id' => 'tenant_ulid',
]);

// Change password
$userManager->changePassword($user->getId(), 'NewSecureP@ssw0rd!');

// Activate user
$userManager->activateUser($user->getId());

// Lock user
$userManager->lockUser($user->getId(), 'Suspicious activity detected');
```

### Authentication

[](#authentication)

```
use Nexus\Identity\Services\AuthenticationService;
use Nexus\Identity\ValueObjects\Credentials;

$credentials = new Credentials('john@example.com', 'SecureP@ssw0rd!');

// Login
$result = $authService->login($credentials, [
    'ip' => '192.168.1.1',
    'user_agent' => 'Mozilla/5.0...',
]);

$user = $result['user'];
$session = $result['session'];

// Validate session
$authenticatedUser = $authService->validateSession($session->token);

// Logout
$authService->logout($session->token);
```

### Authorization

[](#authorization)

#### Basic Permission Checking (RBAC)

[](#basic-permission-checking-rbac)

```
use Nexus\Identity\Services\PermissionChecker;

// Check permission
if ($permissionChecker->hasPermission($user, 'users.create')) {
    // User can create users
}

// Check multiple permissions
if ($permissionChecker->hasAllPermissions($user, ['users.create', 'users.update'])) {
    // User has all permissions
}

// Check role
if ($permissionChecker->hasRole($user, 'admin')) {
    // User is an admin
}

// Wildcard permission matching
// If user has "users.*", they have "users.create", "users.update", etc.
```

#### Policy-Based Authorization (ABAC)

[](#policy-based-authorization-abac)

For complex authorization that requires context, relationships, or business rules:

```
use Nexus\Identity\Contracts\PolicyEvaluatorInterface;
use Nexus\Identity\ValueObjects\Policy;

// Register a custom policy
$leavePolicy = Policy::define('hrm.leave.apply_on_behalf')
    ->description('User can apply leave on behalf of employees in same department or as their manager')
    ->check(function(UserInterface $user, string $action, mixed $resource, array $context) use ($employeeQuery) {
        // Extract target employee from context
        $targetEmployeeId = $context['target_employee_id'] ?? null;
        if (!$targetEmployeeId) {
            return false;
        }

        $userEmployee = $employeeQuery->findByUserId($user->getId());
        $targetEmployee = $employeeQuery->findById($targetEmployeeId);

        // Check if same department OR user is manager
        return $userEmployee?->getDepartmentId() === $targetEmployee?->getDepartmentId()
            || $userEmployee?->getId() === $targetEmployee?->getManagerId();
    });

$policyEvaluator->registerPolicy(
    $leavePolicy->getName(),
    $leavePolicy->getEvaluator()
);

// Evaluate policy with context
$canApply = $policyEvaluator->evaluate(
    user: $user,
    action: 'hrm.leave.apply_on_behalf',
    resource: null,
    context: ['target_employee_id' => $employeeId]
);

if ($canApply) {
    // User can apply leave on behalf of this employee
}
```

**When to use Policy-Based Authorization:**

- ✅ Authorization depends on relationships (e.g., manager, same department)
- ✅ Authorization requires resource state (e.g., invoice status, case ownership)
- ✅ Complex multi-condition rules
- ✅ Context-dependent decisions

**When to use Basic Permission Checking:**

- ✅ Simple "can user perform action" checks
- ✅ Role-based access (admin, manager, user)
- ✅ Static permissions that don't change based on context

```

### Role Management

```php
use Nexus\Identity\Services\RoleManager;

// Create a role
$role = $roleManager->createRole([
    'name' => 'manager',
    'description' => 'Department Manager',
    'tenant_id' => 'tenant_ulid',
]);

// Assign permission to role
$roleManager->assignPermission($role->getId(), $permission->getId());

// Assign role to user
$userManager->assignRole($user->getId(), $role->getId());

```

### Permission Management

[](#permission-management)

```
use Nexus\Identity\Services\PermissionManager;

// Create a permission
$permission = $permissionManager->createPermission([
    'name' => 'users.create',
    'resource' => 'users',
    'action' => 'create',
    'description' => 'Create new users',
]);

// Create wildcard permission
$wildcardPermission = $permissionManager->createPermission([
    'name' => 'users.*',
    'resource' => 'users',
    'action' => '*',
    'description' => 'All user operations',
]);
```

### API Token Management

[](#api-token-management)

```
use Nexus\Identity\Contracts\TokenManagerInterface;

// Generate API token
$token = $tokenManager->generateToken(
    userId: $user->getId(),
    name: 'Production API',
    scopes: ['users.read', 'invoices.read'],
    expiresAt: new \DateTimeImmutable('+1 year')
);

// Validate token
$tokenUser = $tokenManager->validateToken($token->token);

// Revoke token
$tokenManager->revokeToken($token->id);
```

Value Objects
-------------

[](#value-objects)

Value objects are immutable and enforce business rules:

### UserStatus

[](#userstatus)

```
use Nexus\Identity\ValueObjects\UserStatus;

$status = UserStatus::ACTIVE;
$status->canAuthenticate(); // true

$locked = UserStatus::LOCKED;
$locked->requiresAdminIntervention(); // true
```

### Credentials

[](#credentials)

```
use Nexus\Identity\ValueObjects\Credentials;

$credentials = new Credentials('user@example.com', 'password');
// Validates email format on construction
```

### Permission

[](#permission)

```
use Nexus\Identity\ValueObjects\Permission;

$permission = Permission::fromName('users.create');
$permission->resource; // 'users'
$permission->action; // 'create'
$permission->isWildcard(); // false

$wildcard = Permission::fromName('users.*');
$wildcard->matches('users.create'); // true
$wildcard->matches('users.update'); // true
$wildcard->matches('roles.create'); // false
```

Exception Handling
------------------

[](#exception-handling)

All domain exceptions extend PHP's base `Exception`:

```
use Nexus\Identity\Exceptions\UserNotFoundException;
use Nexus\Identity\Exceptions\InvalidCredentialsException;
use Nexus\Identity\Exceptions\InsufficientPermissionsException;

try {
    $user = $userManager->findUser($userId);
} catch (UserNotFoundException $e) {
    // Handle user not found
}

try {
    $authService->login($credentials);
} catch (InvalidCredentialsException $e) {
    // Handle invalid credentials
} catch (AccountLockedException $e) {
    // Handle locked account
}
```

Integration with Application Layer
----------------------------------

[](#integration-with-application-layer)

The application layer (`apps/Atomy`) must provide implementations for all contracts:

1. **Eloquent Models** implementing entity interfaces
2. **Repositories** implementing repository interfaces
3. **Service Implementations** (password hashing, validation, etc.)
4. **Database Migrations**
5. **Service Provider Bindings**

Example binding in `AppServiceProvider`:

```
// Repository bindings
$this->app->singleton(UserRepositoryInterface::class, DbUserRepository::class);
$this->app->singleton(RoleRepositoryInterface::class, DbRoleRepository::class);
$this->app->singleton(PermissionRepositoryInterface::class, DbPermissionRepository::class);

// Service implementations
$this->app->singleton(PasswordHasherInterface::class, LaravelPasswordHasher::class);
$this->app->singleton(PasswordValidatorInterface::class, LaravelPasswordValidator::class);
$this->app->singleton(UserAuthenticatorInterface::class, LaravelUserAuthenticator::class);
$this->app->singleton(SessionManagerInterface::class, LaravelSessionManager::class);
$this->app->singleton(TokenManagerInterface::class, LaravelTokenManager::class);

// Permission checker (uses base implementation)
$this->app->singleton(PermissionCheckerInterface::class, PermissionChecker::class);
```

Security Considerations
-----------------------

[](#security-considerations)

1. **Password Hashing**: Use Argon2id or bcrypt (minimum cost 12)
2. **Session Tokens**: Cryptographically secure random tokens (256 bits minimum)
3. **API Tokens**: One-way hashed in database, only shown once on generation
4. **Failed Login Tracking**: Lock account after configurable threshold (default 5)
5. **Password History**: Prevent reuse of last N passwords (default 5)
6. **Session Fingerprinting**: Bind sessions to IP/User-Agent
7. **MFA Enforcement**: Can be required per role
8. **Audit Logging**: All authentication/authorization events logged

Requirements Addressed
----------------------

[](#requirements-addressed)

This package addresses all requirements listed in REQUIREMENTS.csv for `Nexus\Identity`:

- ✅ ARC-IDE-1300 to ARC-IDE-1310: Architectural requirements
- ✅ BUS-IDE-1311 to BUS-IDE-1360: Business requirements
- ✅ FUN-IDE-1361 to FUN-IDE-1410: Functional requirements
- ✅ PERF-IDE-1411 to PERF-IDE-1416: Performance requirements
- ✅ REL-IDE-1417 to REL-IDE-1423: Reliability requirements
- ✅ SCL-IDE-1424 to SCL-IDE-1428: Scalability requirements
- ✅ MAINT-IDE-1429 to MAINT-IDE-1435: Maintainability requirements
- ✅ COMP-IDE-1436 to COMP-IDE-1444: Compliance requirements (GDPR, PCI-DSS, NIST)
- ✅ USE-IDE-1445 to USE-IDE-1500: User stories

Testing
-------

[](#testing)

Package tests should use mocks for all repository implementations:

```
use Nexus\Identity\Services\UserManager;
use Nexus\Identity\Contracts\UserRepositoryInterface;
use PHPUnit\Framework\TestCase;

class UserManagerTest extends TestCase
{
    public function test_create_user()
    {
        $mockRepo = $this->createMock(UserRepositoryInterface::class);
        $mockRepo->expects($this->once())
            ->method('emailExists')
            ->willReturn(false);

        $userManager = new UserManager($mockRepo, $hasher, $validator);
        // ... test logic
    }
}
```

📖 Documentation
---------------

[](#-documentation)

### Package Documentation

[](#package-documentation)

- **[Getting Started Guide](docs/getting-started.md)** - Quick start guide with prerequisites, core concepts, and first integration
- **[API Reference](docs/api-reference.md)** - Complete documentation of all 28 interfaces, 10 services, 20 value objects, and 19 exceptions
- **[Integration Guide](docs/integration-guide.md)** - Laravel and Symfony integration examples with complete setup instructions
- **[Basic Usage Example](docs/examples/basic-usage.php)** - Simple usage patterns for authentication, authorization, and MFA
- **[Advanced Usage Example](docs/examples/advanced-usage.php)** - Advanced scenarios including WebAuthn, passwordless auth, and complex workflows

### Additional Resources

[](#additional-resources)

- `IMPLEMENTATION_SUMMARY.md` - Implementation progress, metrics, and key design decisions
- `REQUIREMENTS.md` - All 401 requirements with status tracking
- `TEST_SUITE_SUMMARY.md` - Test coverage metrics and test inventory (331+ tests, 95%+ coverage)
- `VALUATION_MATRIX.md` - Package valuation metrics for funding assessment ($300K+ estimated value)
- See root `../../ARCHITECTURE.md` for overall system architecture
- See `../../docs/NEXUS_PACKAGES_REFERENCE.md` for package ecosystem reference

License
-------

[](#license)

MIT License. See [LICENSE](LICENSE) file for details.

###  Health Score

36

—

LowBetter than 79% of packages

Maintenance93

Actively maintained with recent releases

Popularity3

Limited adoption so far

Community13

Small or concentrated contributor base

Maturity34

Early-stage or recently created project

 Bus Factor1

Top contributor holds 77.1% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Unknown

Total

1

Last Release

36d ago

### Community

Maintainers

![](https://avatars.githubusercontent.com/u/117408?v=4)[Azahari Zaman](/maintainers/azaharizaman)[@azaharizaman](https://github.com/azaharizaman)

---

Top Contributors

[![azaharizaman](https://avatars.githubusercontent.com/u/117408?v=4)](https://github.com/azaharizaman "azaharizaman (475 commits)")[![Copilot](https://avatars.githubusercontent.com/in/1143301?v=4)](https://github.com/Copilot "Copilot (139 commits)")[![dependabot[bot]](https://avatars.githubusercontent.com/in/29110?v=4)](https://github.com/dependabot[bot] "dependabot[bot] (2 commits)")

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/azaharizaman-nexus-identity/health.svg)

```
[![Health](https://phpackages.com/badges/azaharizaman-nexus-identity/health.svg)](https://phpackages.com/packages/azaharizaman-nexus-identity)
```

###  Alternatives

[web-auth/webauthn-lib

FIDO2/Webauthn Support For PHP

1237.8M117](/packages/web-auth-webauthn-lib)[web-auth/webauthn-framework

FIDO2/Webauthn library for PHP and Symfony Bundle.

51090.8k2](/packages/web-auth-webauthn-framework)[matomo/matomo

Matomo is the leading Free/Libre open analytics platform

21.6k38.2k](/packages/matomo-matomo)[simplesamlphp/saml2

SAML2 PHP library from SimpleSAMLphp

30417.8M41](/packages/simplesamlphp-saml2)[kimai/kimai

Kimai - Time Tracking

4.7k8.7k1](/packages/kimai-kimai)[contao/core-bundle

Contao Open Source CMS

1231.6M2.6k](/packages/contao-core-bundle)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)