feat(rbac): Phase 2 - Temporal Logic & Auto-Expiration (#106)

[kevalyq]

Summary

Implements RBAC Phase 2: Temporal Logic & Auto-Expiration with automatic expiration of time-limited role assignments, comprehensive audit trail, and scheduled execution.

Changes

Core Features

• ✅ roles:expire command runs every minute via Laravel scheduler
• ✅ Only processes roles with auto_revoke=true flag
• ✅ Logs all expirations to role_assignments_log before deletion
• ✅ Transaction-based processing ensures data integrity
• ✅ Timezone-aware (UTC storage)

Implementation Details

• Command: app/Console/Commands/ExpireRoles.php
• Scheduler: routes/console.php (everyMinute)
• Query-based deletion: Pivot table has no primary key
• Scope filtering: Uses TemporalRoleUser::expired() scope

Bug Fixes

• Migration: assigned_by changed from uuid() to foreignId() (matches User table)
• TemporalRoleUser: Added PHPDoc for pivot properties (PHPStan compliance)
• Migration: Fixed .after() method placement for foreign key constraint

Tests

• ✅ 10 new tests (31 assertions) in ExpireRolesCommandTest
• Covers: expiration logic, audit logging, auto_revoke flag
• Tests: active/future role preservation, timezone handling
• Validates: batch processing, mixed scenarios

Quality Gates

• ✅ All 179 tests pass (513 assertions)
• ✅ PHPStan Level 9: No errors
• ✅ Laravel Pint: Code style compliant
• ✅ REUSE 3.3: Compliant
• ✅ Pre-push checks: All passed (350 changed lines)

Database Changes

Migration Required: Yes

php artisan migrate

Scheduler Setup: Required (if not already configured)

* * * * * cd /path/to/project && php artisan schedule:run >> /dev/null 2>&1

Related

• Fixes: RBAC Phase 2: Temporal Logic & Auto-Expiration #106 (RBAC Phase 2)
• Part of: 🔐 Implement RBAC System (Role-Based Access Control) #5 (RBAC System Epic)
• Architecture: ADR-004 (RBAC Architecture Decision)
• Depends on: Phase 1 ✅ (merged)
• Blocks: RBAC Phase 3: API Endpoints & Authorization Policies #107 (Phase 3 - API Endpoints)

Breaking Changes

None

Checklist

• Tests written (TDD approach)
• All tests pass
• PHPStan Level 9 passes
• Laravel Pint passes
• REUSE 3.3 compliant
• CHANGELOG.md updated
• Migration tested (fresh + rollback)
• Scheduler command tested manually
• Documentation inline (PHPDoc)
• No security issues
• No performance concerns

[github-actions]

💡 Tip: Consider Using Draft PRs

Benefits of opening PRs as drafts initially:

• 💰 Saves CI runtime and Copilot review credits
• 🎯 Automatically sets linked issues to "🚧 In Progress" status
• 🚀 Mark "Ready for review" when done to trigger full CI pipeline

How to convert:

1. Click "Still in progress? Convert to draft" in the sidebar, OR
2. Use gh pr ready when ready for review

This is just a friendly reminder - feel free to continue as is! 😊

[github-actions]

💡 Tip: Consider Using Draft PRs

Benefits of opening PRs as drafts initially:

• 💰 Saves CI runtime and Copilot review credits
• 🎯 Automatically sets linked issues to "🚧 In Progress" status
• 🚀 Mark "Ready for review" when done to trigger full CI pipeline

How to convert:

1. Click "Still in progress? Convert to draft" in the sidebar, OR
2. Use gh pr ready when ready for review

This is just a friendly reminder - feel free to continue as is! 😊

[Copilot]

Pull Request Overview

This PR implements automatic expiration of time-limited role assignments (RBAC Phase 2). A scheduled console command roles:expire runs every minute to identify and revoke expired roles where auto_revoke=true, logging each expiration to an immutable audit trail before deletion. The PR also includes a database schema fix, changing the assigned_by column from UUID to bigInteger to properly reference the users table.

Key Changes:

• New roles:expire command scheduled to run every minute via Laravel scheduler
• Transaction-based processing ensures audit logs are created before role deletion
• Comprehensive test suite with 10 tests covering expiration logic, audit logging, timezone handling, and batch processing

Reviewed Changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
app/Console/Commands/ExpireRoles.php	New scheduled command to expire and revoke temporal role assignments with auto_revoke flag
tests/Feature/Console/ExpireRolesCommandTest.php	Comprehensive test suite with 10 tests covering various expiration scenarios
routes/console.php	Scheduler configuration to run roles:expire command every minute
database/migrations/2025_11_08_143609_add_temporal_columns_to_model_has_roles_table.php	Fixed assigned_by column type from UUID to foreignId (bigInteger) to match users table
app/Models/TemporalRoleUser.php	Updated PHPDoc to reflect assigned_by as int instead of string
CHANGELOG.md	Documented RBAC Phase 2 temporal logic and auto-expiration feature

[Copilot]

[nitpick] The declare(strict_types=1); directive is inconsistent with other console commands in the codebase. Other commands like GenerateTenantCommand, RotateDekCommand, and RotateKekCommand don't include this directive. For consistency, consider removing it to match the existing command pattern.

Suggested change

declare(strict_types=1);

[Copilot]

Using a separate transaction for each expired role could be inefficient when processing many expired roles. Consider wrapping the entire foreach loop in a single transaction, or batch process the deletions. This would improve performance and reduce database overhead when multiple roles expire simultaneously.

DB::transaction(function () use ($expired, &$count) {
    foreach ($expired as $assignment) {
        // Log and delete operations here
        $count++;
    }
});

[Copilot]

Loading all expired roles into memory with get() could cause memory issues if there are many expired roles to process. Consider using chunk() or cursor() to process expired roles in batches:

TemporalRoleUser::expired()->chunk(100, function ($expired) use (&$count) {
    foreach ($expired as $assignment) {
        DB::transaction(function () use ($assignment, &$count) {
            // ... existing logic
        });
    }
});

Suggested change

	// Find expired roles using the expired() scope
	$expired = TemporalRoleUser::expired()->get();
	if ($expired->isEmpty()) {
	$this->info('No expired roles found.');
	return self::SUCCESS;
	}
	$count = 0;
	// Process each expired assignment in a transaction for safety
	foreach ($expired as $assignment) {
	DB::transaction(function () use ($assignment, &$count) {
	// 1. Log to immutable audit trail
	RoleAssignmentLog::create([
	'user_id' => $assignment->model_id,
	'role_id' => $assignment->role_id,
	'action' => 'expired',
	'valid_from' => $assignment->valid_from,
	'valid_until' => $assignment->valid_until,
	'assigned_by' => $assignment->assigned_by,
	'reason' => $assignment->reason,
	]);
	// 2. Delete expired assignment using query (pivot has no primary key)
	DB::table('model_has_roles')
	->where('model_type', $assignment->model_type)
	->where('model_id', $assignment->model_id)
	->where('role_id', $assignment->role_id)
	->where('tenant_id', $assignment->tenant_id)
	->delete();
	$count++;
	});
	// Process expired roles in batches to avoid memory issues
	$count = 0;
	$found = false;
	TemporalRoleUser::expired()->chunk(100, function ($expired) use (&$count, &$found) {
	$found = true;
	foreach ($expired as $assignment) {
	DB::transaction(function () use ($assignment, &$count) {
	// 1. Log to immutable audit trail
	RoleAssignmentLog::create([
	'user_id' => $assignment->model_id,
	'role_id' => $assignment->role_id,
	'action' => 'expired',
	'valid_from' => $assignment->valid_from,
	'valid_until' => $assignment->valid_until,
	'assigned_by' => $assignment->assigned_by,
	'reason' => $assignment->reason,
	]);
	// 2. Delete expired assignment using query (pivot has no primary key)
	DB::table('model_has_roles')
	->where('model_type', $assignment->model_type)
	->where('model_id', $assignment->model_id)
	->where('role_id', $assignment->role_id)
	->where('tenant_id', $assignment->tenant_id)
	->delete();
	$count++;
	});
	}
	});
	if (! $found) {
	$this->info('No expired roles found.');
	return self::SUCCESS;

[Copilot]

There's a potential race condition if multiple scheduler instances run simultaneously (though Laravel's scheduler should prevent this). If two processes fetch the same expired roles, both will create audit log entries before deletion, resulting in duplicate audit logs.

Consider using a database lock or checking the delete result:

DB::transaction(function () use ($assignment, &$count) {
    $deleted = DB::table('model_has_roles')
        ->where('model_type', $assignment->model_type)
        ->where('model_id', $assignment->model_id)
        ->where('role_id', $assignment->role_id)
        ->where('tenant_id', $assignment->tenant_id)
        ->delete();
    
    // Only log if we actually deleted something
    if ($deleted > 0) {
        RoleAssignmentLog::create([...]);
        $count++;
    }
});

Or reverse the order and use lockForUpdate() on the query.

Suggested change

	// 1. Log to immutable audit trail
	RoleAssignmentLog::create([
	'user_id' => $assignment->model_id,
	'role_id' => $assignment->role_id,
	'action' => 'expired',
	'valid_from' => $assignment->valid_from,
	'valid_until' => $assignment->valid_until,
	'assigned_by' => $assignment->assigned_by,
	'reason' => $assignment->reason,
	]);
	// 2. Delete expired assignment using query (pivot has no primary key)
	DB::table('model_has_roles')
	->where('model_type', $assignment->model_type)
	->where('model_id', $assignment->model_id)
	->where('role_id', $assignment->role_id)
	->where('tenant_id', $assignment->tenant_id)
	->delete();
	$count++;
	// 1. Delete expired assignment using query (pivot has no primary key)
	$deleted = DB::table('model_has_roles')
	->where('model_type', $assignment->model_type)
	->where('model_id', $assignment->model_id)
	->where('role_id', $assignment->role_id)
	->where('tenant_id', $assignment->tenant_id)
	->delete();
	// 2. Only log to immutable audit trail if we actually deleted something
	if ($deleted > 0) {
	RoleAssignmentLog::create([
	'user_id' => $assignment->model_id,
	'role_id' => $assignment->role_id,
	'action' => 'expired',
	'valid_from' => $assignment->valid_from,
	'valid_until' => $assignment->valid_until,
	'assigned_by' => $assignment->assigned_by,
	'reason' => $assignment->reason,
	]);
	$count++;
	}