Policy Management Module

Overview

The Policy Management module defines and enforces system-wide policies for access control, login restrictions, password requirements, PIN policies, and transaction limits. It provides flexible, configuration-driven policy enforcement across all channels.

API Prefix: /api/v1/user/policy/* (shared user router namespace)

Route Verification Status

• Source Router: app/api/v1/endpoints/policy.py
• Live Route Count: 9
• Verification State: Verified (2026-06-28)
• Canonical Tracking: docs/API_ROUTE_DOCUMENTATION_TODO.md
• Verification Method: Route decorators extracted from @r.<method>(...) in app/api/v1/endpoints/policy.py.

Key Features

1. Access Policies

• Multi-channel policies (Web, Mobile, USSD, Agent)
• Device-specific access rules
• IP-based access restrictions
• Geofence-based access control
• Time-based access windows
• Risk-based access restrictions

2. Login Attempt Controls

• Maximum failed login attempts
• Account lockout duration
• Lockout escalation (temporary → permanent)
• Bypass mechanisms for admins
• Attempt logging and monitoring

3. Password Policies

• Password complexity requirements (length, uppercase, numbers, symbols)
• Password expiration rules
• Password history (prevent reuse)
• Forced password change on first login
• Password reset requirements

4. PIN Policies

• PIN complexity rules
• PIN change frequency
• PIN history tracking
• PIN lockout on failed attempts
• Alternative PIN verification

5. Transaction Policies

• Per-channel transaction limits (daily, monthly, per-transaction)
• Velocity checks (transactions per hour/day)
• High-risk transaction flagging
• Approval thresholds
• Transaction type-specific rules

6. Geographic Policies

• Geofence boundaries for agents
• Country/region access restrictions
• Location-based transaction limits
• Travel alerts and velocity checks

7. Device Policies

• Device binding requirements
• New device verification
• Device-specific limits
• Device timeout policies
• Backup device rules

API Endpoints (Verified Against Live Router)

For the complete policy endpoint inventory (all 9 routes with method, effective path, and source line), use: - docs/API_ROUTE_LIVE_REFERENCE.md -> section policy.py (9 routes)

Database Models

Core Policy Models

• AccessPolicy: Channel and device-based access policies
• LoginAttemptControl: Failed login rules per user type
• PasswordRestriction: Password complexity and expiry
• PinPolicy: PIN requirements and controls
• TransactionPolicy: Per-channel transaction limits

Restriction Models

• LoginIPRestriction: IP whitelist/blacklist
• LoginDayRestriction: Time-based access windows
• GeofencingRestriction: Location-based policies
• UserTOTPSecret: TOTP configuration per user

Control Models

• OTPControl: OTP generation and validation rules
• DeviceControl: Device binding and trust rules
• VelocityControl: Transaction velocity limits

Policy Types

Access Policy

Channel-Based Policy

{
  "name": "Web Channel Access Policy",
  "channel": "web",
  "description": "Policy for web browser access",
  "rules": {
    "requires_mfa": true,
    "requires_device_binding": false,
    "max_login_failures": 5,
    "lockout_duration_minutes": 30,
    "session_timeout_minutes": 30,
    "ip_restrictions": {
      "enabled": false
    },
    "geofence_required": false,
    "daily_transaction_limit": 1000000,
    "high_risk_threshold": 500000
  },
  "status": "active"
}

Mobile Policy

{
  "name": "Mobile App Access Policy",
  "channel": "mobile",
  "description": "Policy for mobile app users",
  "rules": {
    "requires_mfa": true,
    "requires_device_binding": true,
    "device_binding_type": "fingerprint_or_pin",
    "max_login_failures": 3,
    "lockout_duration_minutes": 60,
    "session_timeout_minutes": 15,
    "high_risk_threshold": 250000,
    "requires_verification_above": 100000
  },
  "status": "active"
}

USSD Policy

{
  "name": "USSD Channel Policy",
  "channel": "ussd",
  "description": "Policy for USSD feature phone users",
  "rules": {
    "requires_mfa": false,
    "requires_pin": true,
    "max_login_failures": 3,
    "lockout_duration_minutes": 60,
    "daily_transaction_limit": 50000,
    "per_transaction_limit": 10000,
    "requires_otp_above": 5000
  },
  "status": "active"
}

Agent Policy

{
  "name": "Agent Device Policy",
  "channel": "agent",
  "description": "Policy for field agent devices",
  "rules": {
    "requires_device_binding": true,
    "geofence_required": true,
    "max_login_failures": 5,
    "lockout_duration_minutes": 30,
    "daily_float_limit": 5000000,
    "geofence_violation_alert": true,
    "requires_checkin": true,
    "checkin_frequency_hours": 24
  },
  "status": "active"
}

Password Policy

{
  "name": "Strong Password Policy",
  "description": "Strong password requirements",
  "requirements": {
    "min_length": 12,
    "require_uppercase": true,
    "require_lowercase": true,
    "require_numbers": true,
    "require_symbols": true,
    "forbidden_patterns": [
      "sequential",
      "repeated_chars",
      "username"
    ]
  },
  "expiry_days": 90,
  "history_count": 5,
  "reuse_prevention_months": 12,
  "force_change_on_first_login": true,
  "status": "active"
}

PIN Policy

{
  "name": "Transaction PIN Policy",
  "description": "PIN requirements for transactions",
  "requirements": {
    "length": 4,
    "numeric_only": true,
    "no_sequential": true,
    "no_repeated": true
  },
  "change_frequency_days": 90,
  "max_failed_attempts": 3,
  "lockout_duration_minutes": 30,
  "required_for_transactions_above": 5000,
  "status": "active"
}

Transaction Policy

{
  "name": "Standard User Transaction Policy",
  "description": "Daily transaction limits for standard users",
  "channel": "mobile",
  "limits": {
    "daily_limit": 500000,
    "per_transaction_limit": 250000,
    "daily_transaction_count": 20,
    "per_hour_count": 5
  },
  "high_risk_threshold": 100000,
  "requires_approval_above": 250000,
  "applies_to_segments": ["standard_users"],
  "status": "active"
}

Policy Application

Login Flow with Policies

1. User attempts login
   ├─ Fetch applicable policies (channel, user type)
   ├─ Check against IP restrictions
   ├─ Check against day/time restrictions
   ├─ Check if account is locked
   └─ Allow or deny login

2. Credential validation
   ├─ Verify password against policy requirements
   ├─ Check password expiry
   ├─ If expired: Force password change
   └─ Allow or require password update

3. MFA enforcement
   ├─ Check if MFA required by policy
   ├─ If required: Send OTP/TOTP challenge
   ├─ Validate MFA response
   └─ Grant session or deny

4. Device binding (if applicable)
   ├─ Check if device binding required
   ├─ Validate device fingerprint
   ├─ If first-time device: Require additional verification
   └─ Allow or deny access

5. Session created
   ├─ Set session timeout per policy
   ├─ Log login with all details
   └─ Grant access

Transaction with Policies

1. Transaction initiated
   ├─ Fetch applicable policies
   ├─ Validate transaction amount
   └─ Check against limits

2. Limit checking
   ├─ Check daily limit
   ├─ Check per-transaction limit
   ├─ Check velocity (transactions/hour)
   ├─ Check high-risk threshold
   └─ Flag for manual review if needed

3. Approval flow
   ├─ If within limits: Auto-approve
   ├─ If flagged: Route for manual review
   ├─ If exceeds limit: Reject
   └─ Apply conditional MFA if needed

4. Process or hold
   ├─ Process approved transaction
   ├─ Queue for review if flagged
   ├─ Reject if limit exceeded
   └─ Notify user of status

Controllers & Business Logic

Policy Controllers

• controller/policy.py: Policy management
• get_applicable_policies(): Get policies for user/channel
• validate_against_policy(): Check compliance
• enforce_policy(): Apply policy rules

• get_policy_limits(): Retrieve limit values

• controller/access_policy.py: Access control

• check_access_allowed(): Validate channel access
• check_ip_allowed(): Check IP restrictions

• check_time_allowed(): Check time windows

• controller/transaction_policy.py: Transaction limits

• check_transaction_limits(): Validate amount
• check_velocity_limits(): Validate frequency
• calculate_approval_needed(): Determine if approval required

Configuration Examples

Multi-Channel Policy Strategy

Standard User:
├─ Web: High daily limit, 30-min timeout, MFA required
├─ Mobile: Lower limits, device binding, 15-min timeout
├─ USSD: Very low limits, PIN only, no timeout
└─ Agent: Geofence required, high float limit

Premium User:
├─ Web: Highest limits, extended timeout
├─ Mobile: Standard limits, device binding
└─ USSD: Higher USSD limits

Restricted User:
├─ Web: Low limits, additional verification
├─ Mobile: Very low limits, device binding mandatory
└─ USSD: Disabled

Common Use Cases

1. Daily Transaction Limit Enforcement

User attempts P2P transfer of 600,000 ZMW
→ Policy check: Daily limit = 500,000
→ User already transferred 200,000 today
→ Remaining limit = 300,000
→ Transaction amount > remaining limit
→ Reject with "Daily limit exceeded" message

2. High-Risk Transaction Flagging

User attempts wire transfer of 400,000 ZMW
→ Policy: High-risk threshold = 100,000
→ Amount > threshold → Flag as high-risk
→ Route to compliance officer for review
→ Compliance approves after verification
→ Transaction proceeds

3. Device Binding Verification

User attempts login from new device
→ Policy: Device binding required for mobile
→ Device not in trusted list
→ Trigger additional verification (OTP, Security Question)
→ User completes verification
→ Device added to trusted list
→ Session granted

4. Geofence Compliance

Agent checks in outside geofence
→ Policy: Agent must operate within geofence
→ GPS shows agent is 2km outside store radius
→ Alert sent to supervisor
→ Transaction capabilities restricted until check-in
→ Agent notified to move to store location

Error Handling

Policy Errors

• POLICY_VIOLATION: Action violates policy
• LIMIT_EXCEEDED: Daily/monthly limit exceeded
• ACCOUNT_LOCKED: Account locked after failed attempts
• DEVICE_NOT_TRUSTED: Device not recognized
• OUTSIDE_GEOFENCE: Agent outside allowed area
• ACCESS_DENIED_TIME: Access not allowed at this time
• ACCESS_DENIED_IP: IP address not allowed
• APPROVAL_REQUIRED: Transaction requires manual approval

Testing

Test Categories

• Policy application across channels
• Limit enforcement (daily, per-transaction, velocity)
• Time-based access restrictions
• IP-based access control
• Device binding verification
• Geofence validation
• Password and PIN requirements

Test Files

• tests/test_policy.py: Policy enforcement
• conftest.py: Policy test fixtures

Performance Considerations

1. Policy Caching: Cache active policies per user type/channel
2. Limit Tracking: Use Redis for daily limit counters
3. Geofence Calculations: Cache geofence boundaries
4. Policy Lookup: Index by channel, user type, status
5. Batch Policy Updates: Deploy policies at off-peak hours

Security Features

1. Policy Versioning: Track policy changes
2. Audit Trail: Log all policy violations
3. Escalation: Automatic escalation for repeated violations
4. Override Tracking: Log all policy overrides
5. Compliance Reporting: Generate policy compliance reports

Integration Points

Internal Modules

• Authentication: Enforce at login
• Transaction Processing: Enforce on transactions
• Agent Management: Geofence enforcement
• Wallet System: Transaction limits
• User Management: User-specific policies

Related Documentation

• Authentication - Login Policies
• Transaction Processing - Transaction Limits
• Agent Management - Geofence Policies