Emergency Controls

Document ID: ACP-001.4 Version: 1.0 Classification: Internal / Regulator-Shareable Effective Date: March 2026 Next Review: September 2026 Parent Document: ACP-001 — Access Control & Permissions

---

1. Overview

Keshless implements 8 emergency controls (kill switches) that allow authorized administrators to rapidly restrict or shut down system operations in response to security incidents, fraud detection, or regulatory orders. These controls execute before authentication in the middleware chain, ensuring they cannot be bypassed.

2. Emergency Control Types

2.1 Control Matrix

Control	Severity	Effect	Key Parameters
SYSTEM_SHUTDOWN	Critical	All API requests blocked except health/emergency endpoints	allowedEndpoints, maintenanceMessage
DISABLE_ALL_TRANSACTIONS	Critical	All financial operations blocked	exceptionUserIds (exempt users)
READ_ONLY_MODE	High	All write operations (POST/PUT/PATCH/DELETE) blocked	allowedOperations (exempt methods)
DISABLE_WITHDRAWALS	High	Withdrawal operations blocked	reason
DISABLE_P2P_TRANSFERS	Medium	Peer-to-peer transfer operations blocked	reason
DISABLE_BILL_PAYMENTS	Medium	Bill payment operations blocked	reason
DISABLE_TOPUPS	Medium	Deposit/topup operations blocked	reason
RATE_LIMIT_EXTREME	Medium	Dynamic rate limiting activated	maxRequestsPerMinute, maxRequestsPerHour, throttleDelay

2.2 Always-Allowed Endpoints

Even during SYSTEM_SHUTDOWN, the following endpoints remain accessible:

Endpoint	Purpose
/health	Health check for load balancer
/api/health	API health check
/status	System status
/api/status	API status
/api/admin/emergency	Emergency control management

This ensures administrators can always access the system to deactivate emergency controls.

3. Activation & Authorization

3.1 Who Can Activate

Action	Required Permission
View emergency controls	MANAGE_EMERGENCY_CONTROLS
Activate a control	MANAGE_EMERGENCY_CONTROLS
Deactivate a control	MANAGE_EMERGENCY_CONTROLS
Modify control parameters	MANAGE_EMERGENCY_CONTROLS
Manage system emergency page	MANAGE_SYSTEM_EMERGENCY

Default assignment: Only SUPER_ADMIN and ADMIN roles have the MANAGE_EMERGENCY_CONTROLS permission by default. No other role template includes this permission.

3.2 Activation Flow

Admin activates emergency control via Dashboard
    │
    ├── Permission check: MANAGE_EMERGENCY_CONTROLS
    │
    ├── Control record created/updated in database
    │   ├── controlType: e.g. DISABLE_WITHDRAWALS
    │   ├── isActive: true
    │   ├── parameters: { reason: "..." }
    │   ├── activatedBy: admin employee ID
    │   └── activatedAt: timestamp
    │
    ├── Audit log entry created (SHA-256 hash-chained)
    │
    └── Control takes effect within 5 minutes (cache TTL)

3.3 Cache Behavior

Emergency controls are cached for performance:

Parameter	Value
Cache TTL	5 minutes
Refresh trigger	Automatic on cache expiry
Storage	In-memory (application-level)
Worst-case delay	Up to 5 minutes from activation to enforcement

4. Rate Limiting

4.1 Standard Rate Limits

Rate limiting is configured per endpoint category:

Category	Limit	Window	Scope
General API	100 requests	15 minutes	Per IP
Authentication	10 requests	15 minutes	Per IP
OTP requests	5 requests	15 minutes	Per IP + phone
Transactions	50 requests	15 minutes	Per user
Password reset	5 requests	15 minutes	Per IP + email
OTP verification	3 attempts	5 minutes	Per IP + email
Recovery key	3 attempts	30 minutes	Per IP + email

4.2 USSD Rate Limiting

Parameter	Value
Limit	10 requests per 60 seconds
Scope	Per phone number
Tracking	In-memory Map
Cleanup	Every 5 minutes
Response	HTTP 429

4.3 Dynamic Rate Limiting (RATE_LIMIT_EXTREME)

When the RATE_LIMIT_EXTREME emergency control is activated, the system applies configurable rate limits:

Parameter	Description
maxRequestsPerMinute	Maximum requests per user/IP per minute
maxRequestsPerHour	Maximum requests per user/IP per hour
throttleDelay	Artificial delay added to requests (milliseconds)

Rate Limit Response Headers:

Header	Description
X-RateLimit-Limit	Maximum allowed requests
X-RateLimit-Remaining	Remaining requests in window
X-RateLimit-Reset	Unix timestamp when limit resets
Retry-After	Seconds to wait before retrying

4.4 Rate Limit Implementation

Standard rate limits use in-memory Maps with automatic cleanup:

• Password reset limiter: Cleanup every 60 seconds
• USSD limiter: Cleanup every 5 minutes
• Keying strategy: IP address + identifier (email, phone, or user ID)

5. Incident Response Integration

5.1 Emergency Control Scenarios

Scenario	Recommended Control	Rationale
Active fraud detected	DISABLE_ALL_TRANSACTIONS	Stop all financial operations while investigating
Withdrawal fraud pattern	DISABLE_WITHDRAWALS	Block withdrawals specifically while allowing deposits
DDoS attack	RATE_LIMIT_EXTREME	Throttle requests without full shutdown
Data breach suspected	SYSTEM_SHUTDOWN	Full lockdown for investigation
Regulatory order	READ_ONLY_MODE	Preserve data for regulators; prevent modifications
P2P transfer abuse	DISABLE_P2P_TRANSFERS	Block transfers while allowing commerce
Payment processor issue	DISABLE_BILL_PAYMENTS	Block bills if processor is compromised
Deposit anomaly	DISABLE_TOPUPS	Block deposits if source is suspicious

5.2 Activation Decision Tree

Security incident detected
    │
    ├── Is it affecting all operations?
    │   ├── Yes → SYSTEM_SHUTDOWN (Critical)
    │   └── No ↓
    │
    ├── Is it financial in nature?
    │   ├── All financial ops? → DISABLE_ALL_TRANSACTIONS
    │   ├── Withdrawals only? → DISABLE_WITHDRAWALS
    │   ├── Transfers only? → DISABLE_P2P_TRANSFERS
    │   ├── Bill payments? → DISABLE_BILL_PAYMENTS
    │   └── Deposits? → DISABLE_TOPUPS
    │
    ├── Is it a volume/availability issue?
    │   └── Yes → RATE_LIMIT_EXTREME
    │
    └── Need to preserve data integrity?
        └── Yes → READ_ONLY_MODE

5.3 Deactivation

Emergency controls are deactivated through the same dashboard interface. Deactivation:

1. Requires MANAGE_EMERGENCY_CONTROLS permission
2. Updates the control record (isActive: false)
3. Creates an audit log entry
4. Takes effect within 5 minutes (cache TTL)

6. Database Availability Control

6.1 Database Check Middleware

The databaseCheckMiddleware runs before all routes and rejects requests if the database connection is unavailable:

• Check: Tests Prisma client connectivity
• Failure response: HTTP 503 Service temporarily unavailable
• Purpose: Prevents partial/corrupted operations when the database is down
• Behavior: Fail closed — no database = no service

6.2 Interaction with Emergency Controls

Emergency controls are stored in the database. If the database is unavailable:

1. databaseCheckMiddleware rejects all requests (step 5 in middleware chain)
2. Emergency check middleware (step 6) never executes
3. Net effect: System is effectively in SYSTEM_SHUTDOWN mode

This is a safe default — database unavailability results in full service denial rather than uncontrolled access.