# Runbook: Device Revocation

**Service:** WalletWeb Customer Portal + Admin Console
**Owner:** Operations Team / Customer Support
**Escalation:** Ops Supervisor → SRE

---

## Overview
Procedure for revoking a customer's registered device due to device loss, theft, or suspicious activity.

## Prerequisites
- Admin console access with `ops_agent`, `ops_supervisor`, or `admin` role
- Customer account ID or device ID
- Reason for revocation (security incident, customer request, etc.)

## Procedure

### Via Admin Console (Ops Team)

1. **Navigate to Device Management**
   - Log in to `/admin/login`
   - Navigate to `/admin/devices`

2. **Locate Device**
   - Search by:
     - User ID (shows all devices for that user)
     - Device ID (direct lookup)
     - Device fingerprint (partial match)

3. **Review Device Details**
   - Check last activity timestamp
   - Verify device info matches report (OS, browser, location)

4. **Revoke Device**
   - Click "Revoke Device" button
   - Enter revocation reason in modal
   - Confirm with MFA re-auth
   - System will:
     - Set device status to `revoked`
     - Terminate all active sessions for that device
     - Emit `DeviceRevoked` audit event
     - Send notification to customer (if notify checkbox enabled)

5. **Verify Revocation**
   - Device status should show "Revoked"
   - Customer will be prompted to re-register device on next login

###  Via Customer Self-Service (Profile Page)

Customers can revoke their own devices from `/app/profile`:

1. Click "My Devices" tab
2. Select device to revoke
3. Click "Remove Device"
4. Confirm in modal (MFA challenge will be presented)

This is the preferred method for customer-initiated device removal.

---

## Troubleshooting

### Revocation Fails
- **Error**: "Device not found"
  - **Fix**: Verify device ID or search by user ID instead
- **Error**: "Cannot revoke: device is only registered device"
  - **Fix**: Customer must add a new device before revoking the last one (platform policy)

### Customer Cannot Log In After Revocation
- **Expected Behavior**: Customer will be required to register a new device
- **Procedure**: Instruct customer to:
  1. Log in with email + password
  2. Complete OTP/MFA challenge
  3. Register new device when prompted

---

## Audit and Compliance
- All device revocations emit privileged audit events
- Tracked metrics:
  - Revocations per day (alert threshold: >100)
  - Revocation reasons distribution
- Monthly review by Security team for anomaly detection

---

## Related Runbooks
- [User Account Block and Unblock](./user-block-unblock.md)
- [Session Termination](./session-termination.md)