4.3 Warrant Lifecycle - Complete State Machine and Approval Process

Version: 1.0
Created: July 16, 2025
Status: Comprehensive documentation based on source code analysis

Overview

The KMP Warrant System provides temporal validation for Role-Based Access Control (RBAC) permissions through a sophisticated state machine and multi-level approval process. Warrants serve as time-bounded authorization that determines when role-based permissions are actually active and enforceable in the system.

Table of Contents

  1. Warrant Architecture
  2. Entity Status Definitions
  3. Warrant Lifecycle States
  4. Approval Workflow Process
  5. RBAC Integration
  6. State Transitions
  7. Administrative Operations
  8. Security Architecture
  9. Performance Considerations
  10. Integration Examples

4.1 Warrant Architecture

Core Components

The warrant system consists of four primary entities that work together to provide temporal validation:

graph LR
    WP[WarrantPeriod<br/>Template for<br/>time boundaries] --> WR[WarrantRoster<br/>Batch approval<br/>container]
    WR --> W[Warrant<br/>Individual<br/>warrant entity]
    W --> MR[MemberRole<br/>Role assignment<br/>being validated]
    WRA[WarrantRoster<br/>Approvals<br/><br/>Multi-level<br/>approval track] --> WR

RBAC Integration Flow

graph TD
    M[Members] --> MR[MemberRoles]
    MR --> R[Roles]
    R --> P[Permissions]
    MR --> W[Warrants<br/>Temporal Validation]
    W --> AP[Active Permissions]
    
    style W fill:#e1f5fe
    style AP fill:#c8e6c9

When KMP.RequireActiveWarrantForSecurity is enabled, the PermissionsLoader validates permissions only when:

4.2 Entity Status Definitions

Warrant Entity Statuses

Based on ActiveWindowBaseEntity and Warrant entity constants:

Status Source Description Permission Impact
Pending Warrant::PENDING_STATUS Awaiting approval through warrant roster system No permissions granted
Current ActiveWindowBaseEntity::CURRENT_STATUS Active and providing temporal validation Permissions granted if within time period
Upcoming ActiveWindowBaseEntity::UPCOMING_STATUS Scheduled for future activation No permissions granted yet
Expired ActiveWindowBaseEntity::EXPIRED_STATUS Past expiration date No permissions granted
Deactivated ActiveWindowBaseEntity::DEACTIVATED_STATUS Administratively terminated before expiration No permissions granted
Cancelled ActiveWindowBaseEntity::CANCELLED_STATUS Cancelled during pending state before activation No permissions granted
Declined Warrant::DECLINED_STATUS Rejected during approval process No permissions granted
Replaced ActiveWindowBaseEntity::REPLACED_STATUS Superseded by newer warrant for same entity/member No permissions granted
Released ActiveWindowBaseEntity::RELEASED_STATUS Explicitly released/terminated No permissions granted

Warrant Roster Statuses

Based on WarrantRoster entity constants:

Status Constant Description Workflow State
Pending WarrantRoster::STATUS_PENDING Awaiting required approvals Active approval workflow
Approved WarrantRoster::STATUS_APPROVED Has received required approvals Warrants activated
Declined WarrantRoster::STATUS_DECLINED Rejected during approval process Warrants cancelled

4.3 Warrant Lifecycle States

1. Request Phase

Initial State: None (warrants don’t exist yet)

Process: WarrantManager creates warrant roster and individual warrants

// From DefaultWarrantManager::request()
$warrantRoster->status = WarrantRoster::STATUS_PENDING;
$warrantRequestEntity->status = Warrant::PENDING_STATUS;

Validation Checks:

Database Transaction: Ensures atomicity of roster and warrant creation

2. Pending Approval Phase

State: Warrant::PENDING_STATUS

Characteristics:

Approval Requirements:

3. Approval Transition

Trigger: WarrantManager::approve() when required approvals met

Process from DefaultWarrantManager:

if ($warrantRoster->hasRequiredApprovals()) {
    $warrantRoster->status = WarrantRoster::STATUS_APPROVED;
    foreach ($warrants as $warrant) {
        $warrant->status = Warrant::CURRENT_STATUS;
        $warrant->approved_date = new DateTime();
        
        // Adjust start date if period already began
        if ($warrant->start_on == null || $warrantStart < $now) {
            $warrant->start_on = $now;
        }
        
        // Expire conflicting warrants
        $warrantTable->updateAll([
            'expires_on' => $warrant->start_on,
            'revoked_reason' => 'New Warrant Approved',
            'revoker_id' => $approver_id,
        ], [/* matching criteria */]);
    }
}

Automatic Actions:

4. Active Phase

State: ActiveWindowBaseEntity::CURRENT_STATUS

Characteristics:

Permission Validation Query Pattern:

$warrantSubquery = $warrantsTable->find()
    ->select(['Warrants.member_role_id'])
    ->where([
        'Warrants.start_on <' => $now,      // Warrant has started
        'Warrants.expires_on >' => $now,    // Warrant hasn't expired
        'Warrants.status' => Warrant::CURRENT_STATUS,  // Warrant is active
    ]);

5. Expiration and Termination States

Natural Expiration:

Administrative Termination:

Replacement:

4.4 Approval Workflow Process

Multi-Level Approval System

flowchart TD
    A[Administrator Creates<br/>Warrant Roster] --> B[Roster Status: PENDING<br/>Warrants Status: PENDING]
    B --> C[Authorized User<br/>Provides Approval]
    C --> D{Required<br/>Approvals Met?}
    D -->|No| E[Record Approval<br/>Increment Counter]
    E --> F[Wait for More<br/>Approvals]
    F --> C
    D -->|Yes| G[Roster Status: APPROVED<br/>Warrants Status: CURRENT]
    G --> H[Expire Conflicting<br/>Warrants]
    H --> I[Queue Email<br/>Notifications]
    I --> J[Warrants Active<br/>Permissions Granted]
    
    style A fill:#e3f2fd
    style G fill:#c8e6c9
    style J fill:#a5d6a7
  1. Warrant Roster Creation
    • Administrator creates roster with multiple warrant requests
    • Roster status: STATUS_PENDING
    • Individual warrants status: PENDING_STATUS
    • Approval requirement set from configuration
  2. Approval Collection
    • Authorized users provide approvals via WarrantRostersController::approve()
    • Each approval recorded in WarrantRosterApprovals table
    • Approval count incremented on roster
  3. Threshold Validation
    • WarrantRoster::hasRequiredApprovals() checks approval count
    • When threshold met, roster status becomes STATUS_APPROVED
  4. Warrant Activation
    • All pending warrants transition to CURRENT_STATUS
    • Automatic conflict resolution expires overlapping warrants
    • Email notifications sent to warrant recipients

Approval Tracking

Database Schema:

erDiagram
    WARRANT_ROSTERS {
        int id PK
        string name
        text description
        string status
        int approval_count
        datetime created
        datetime modified
    }
    
    WARRANT_ROSTER_APPROVALS {
        int id PK
        int warrant_roster_id FK
        int approver_id FK
        datetime approved_on
    }
    
    WARRANTS {
        int id PK
        int warrant_roster_id FK
        int member_id FK
        int member_role_id FK
        string status
        datetime start_on
        datetime expires_on
        datetime approved_date
        string revoked_reason
        int revoker_id FK
    }
    
    MEMBERS {
        int id PK
        string first_name
        string last_name
    }
    
    WARRANT_ROSTERS ||--o{ WARRANT_ROSTER_APPROVALS : "has approvals"
    WARRANT_ROSTERS ||--o{ WARRANTS : "contains warrants"
    MEMBERS ||--o{ WARRANT_ROSTER_APPROVALS : "provides approval"
    MEMBERS ||--o{ WARRANTS : "receives warrant"

Business Rules:

4.5 RBAC Integration

Permission Validation Chain

When warrant-secured permissions are checked:

  1. Role Assignment Check: Verify member has role through MemberRole
  2. Permission Check: Verify role has required permission
  3. Warrant Validation: If permission requires warrant, validate:
    • Active warrant exists for the member role assignment
    • Warrant status is CURRENT_STATUS
    • Current time within warrant’s start_on and expires_on range
  4. Additional Validation: Membership status, age requirements, etc.

Configuration Control

Warrant Requirement Toggle:

Security Enforcement

PermissionsLoader Integration:

// Warrant validation subquery integrated into permission checking
$warrantSubquery = $warrantsTable->find()
    ->select(['member_role_id'])
    ->where([
        'start_on <' => $now,
        'expires_on >' => $now,
        'status' => Warrant::CURRENT_STATUS
    ]);

// Only member roles with valid warrants grant permissions
$memberRolesQuery->where(['MemberRoles.id IN' => $warrantSubquery]);

4.6 State Transitions

Valid State Transitions

stateDiagram-v2
    [*] --> PENDING : request()
    
    PENDING --> CURRENT : approve()
    PENDING --> CANCELLED : decline()
    PENDING --> CANCELLED : cancel()
    
    CURRENT --> EXPIRED : expire()
    CURRENT --> DEACTIVATED : cancel()
    CURRENT --> REPLACED : replace()
    
    UPCOMING --> CURRENT : activate()
    
    CURRENT --> [*]
    EXPIRED --> [*]
    DEACTIVATED --> [*]
    CANCELLED --> [*]
    REPLACED --> [*]
    DECLINED --> [*]
    RELEASED --> [*]
    
    note right of PENDING
        Awaiting approval
        No permissions granted
    end note
    
    note right of CURRENT
        Active warrant
        Permissions granted
    end note
    
    note right of EXPIRED
        Natural expiration
        No permissions granted
    end note

Transition Triggers

Transition Method Actor Validation
None → Pending request() Administrator Member warrantability, period validity
Pending → Current approve() Approver Required approvals met
Pending → Cancelled decline() or cancel() Administrator Roster status validation
Current → Expired Automatic System Date-based expiration
Current → Deactivated cancel() Administrator Manual termination
Current → Replaced approve() new warrant System Conflict resolution

4.7 Administrative Operations

WarrantManager Service Methods

Request Creation:

public function request($request_name, $desc, $warrantRequests): ServiceResult

Approval Processing:

public function approve($warrant_roster_id, $approver_id): ServiceResult

Decline Operations:

public function decline($warrant_roster_id, $rejecter_id, $reason): ServiceResult

Individual Warrant Management:

public function cancel($warrant_id, $reason, $rejecter_id, $expiresOn): ServiceResult
public function cancelByEntity($entityType, $entityId, $reason, $rejecter_id, $expiresOn): ServiceResult

Controller Operations

WarrantRostersController methods:

4.8 Security Architecture

Authorization Controls

Policy-Based Access:

Request Security:

Audit Trail

Complete Tracking:

Database Audit Fields:

Data Integrity

Transactional Operations:

Validation Rules:

4.9 Performance Considerations

Database Optimization

Indexing Strategy:

Query Optimization:

Caching Integration

Security Cache:

Performance Monitoring:

4.10 Integration Examples

Creating Warrant Requests

// Create warrant roster with multiple requests
$requests = [
    new WarrantRequest(
        'Branch Officer',           // name
        'Branches',                // entity_type
        $branchId,                 // entity_id
        $requesterId,              // requester_id
        $memberId,                 // member_id
        $startDate,                // start_on
        $endDate,                  // expires_on
        $memberRoleId              // member_role_id
    ),
];

$result = $warrantManager->request(
    'Q2 Officer Appointments',     // roster name
    'Quarterly officer appointments', // description
    $requests                      // warrant requests array
);

Processing Approvals

// Approve warrant roster
$result = $warrantManager->approve($rosterId, $approverId);

if ($result->success) {
    // Check if roster now has required approvals
    $roster = $warrantsTable->get($rosterId);
    if ($roster->hasRequiredApprovals()) {
        // All warrants are now active
    }
}

Permission Validation

// Check warrant-secured permission
$hasPermission = $member->checkCan('manage.events', 'Activities');

// This internally validates:
// 1. Member has role with 'manage.events' permission
// 2. Valid warrant exists for the role assignment (if required)
// 3. Warrant is in CURRENT_STATUS and within time bounds
// 4. All other permission requirements met

Administrative Operations

// Cancel specific warrant
$result = $warrantManager->cancel(
    $warrantId,                    // warrant ID
    'Officer resigned',            // reason
    $revokerId,                    // revoker ID
    new DateTime('+1 day')         // expiration date
);

// Decline entire roster
$result = $warrantManager->decline(
    $rosterId,                     // roster ID
    $rejectorId,                   // rejector ID
    'Insufficient qualifications'  // reason
);

Summary

The KMP Warrant System provides a comprehensive temporal validation layer for RBAC permissions through:

  1. Multi-State Lifecycle: Nine distinct states managing warrant progression from request through termination
  2. Approval Workflows: Configurable multi-level approval system with complete audit trail
  3. RBAC Integration: Seamless integration with permission validation for temporal security
  4. Administrative Control: Comprehensive management interface with batch operations
  5. Security Architecture: Policy-based authorization with complete audit trail and data integrity
  6. Performance Optimization: Efficient database queries and caching integration

This system ensures that role-based permissions are only active when explicitly warranted and approved, providing temporal bounds and administrative oversight for sensitive system operations.

Source Documentation: This document is based entirely on analysis of the KMP source code, including entity definitions, service implementations, controller operations, and database schema as documented in the warrant system components.