6.4 KiB

Raw Blame History

Device Management Implementation - Changelog

Summary

Enhanced the auth service to properly support multi-device login with device management capabilities. One phone number = One account, but that account can be logged in from multiple devices simultaneously.

Changes Made

1. Enhanced Verify OTP Endpoint (`/auth/verify-otp`)

Added:

New device detection logic
Audit logging for all login attempts
Response fields: is_new_device, is_new_account, active_devices_count

Response now includes:

{
  "user": { ... },
  "access_token": "...",
  "refresh_token": "...",
  "needs_profile": true,
  "is_new_device": false,          // NEW
  "is_new_account": false,         // NEW
  "active_devices_count": 2        // NEW
}

Benefits:

Mobile app can show security notifications for new devices
Track account creation vs. existing account login
Display active device count in UI

2. Enhanced Refresh Token Endpoint (`/auth/refresh`)

Added:

Updates user_devices.last_seen_at on token refresh
Tracks device activity for monitoring

Benefits:

Identify active vs. inactive devices
Better device management insights

3. New User Endpoints (`/users/me/*`)

GET `/users/me`

Returns user info with active_devices_count
Includes account creation date and last login time

GET `/users/me/devices`

Lists all active devices for the user
Shows device metadata (platform, model, OS, etc.)
Includes first_seen_at and last_seen_at timestamps

DELETE `/users/me/devices/:device_id`

Revokes/logs out a specific device
Revokes all refresh tokens for that device
Logs the action in audit table

POST `/users/me/logout-all-other-devices`

Logs out all devices except the current one
Requires current_device_id in header or body
Returns count of revoked devices

4. Audit Logging

Added comprehensive logging:

Login attempts (success/failure)
Device revocations
Logout actions
All events logged to auth_audit table with metadata

Audit fields:

action: 'login', 'device_revoked', 'logout_all_other_devices'
status: 'success', 'failed'
device_id: Device identifier
ip_address: Client IP
user_agent: Client user agent
meta: JSONB with additional context (is_new_device, platform, etc.)

Database Changes

No Schema Changes Required

All features use existing tables:
- users (already has UNIQUE constraint on phone_number)
- user_devices (already tracks devices per user)
- auth_audit (already exists for logging)
- refresh_tokens (already tracks tokens per device)

Existing Constraints Work Perfectly

phone_number UNIQUE → One account per phone number ✅
(user_id, device_identifier) UNIQUE → One device record per user-device combo ✅

Security Improvements

✅ New Device Detection

Automatically flags new device logins
Mobile app can show security alerts
Logged in audit table

✅ Device Activity Tracking

last_seen_at updated on token refresh
Helps identify abandoned devices
Better security monitoring

✅ Device Management

Users can see all active devices
Users can revoke specific devices
Users can logout all other devices (security feature)

✅ Audit Trail

All authentication events logged
Can track suspicious activity
Compliance and security auditing

API Usage Examples

POST /auth/verify-otp
{
  "phone_number": "+919876543210",
  "code": "123456",
  "device_id": "new-device-123",
  "device_info": { "platform": "android" }
}

Response:
{
  "is_new_device": true,
  "is_new_account": false,
  "active_devices_count": 2
}

List Active Devices

GET /users/me/devices
Authorization: Bearer <access_token>

Response:
{
  "devices": [
    {
      "device_identifier": "device-1",
      "device_platform": "android",
      "last_seen_at": "2024-01-15T10:30:00Z",
      "is_active": true
    }
  ]
}

Revoke Device

DELETE /users/me/devices/device-1
Authorization: Bearer <access_token>

Response:
{
  "ok": true,
  "message": "Device logged out successfully"
}

Mobile App Integration

New Response Fields to Handle

is_new_device → Show security notification
is_new_account → Show welcome flow
active_devices_count → Display in settings

New Endpoints to Implement

Device List Screen → Show all active devices
Revoke Device → Allow users to logout specific devices
Security Settings → Show active device count

Example Flow

// After login
if (response.is_new_device && !response.is_new_account) {
    showSecurityAlert("New device logged in: ${deviceModel}")
}

// In settings screen
val devices = apiClient.getDevices(accessToken)
devices.forEach { device ->
    showDeviceCard(
        model = device.device_model,
        lastSeen = device.last_seen_at,
        onRevoke = { revokeDevice(device.device_identifier) }
    )
}

Testing Checklist

Same phone number can log in from multiple devices
Each device gets its own refresh token
Devices can be active simultaneously
Revoking one device doesn't affect others
New device detection works correctly
Audit logging captures all events
Device activity tracking works
Logout all other devices works

Backward Compatibility

✅ Fully backward compatible

All existing endpoints work as before
New response fields are additions (optional to use)
New endpoints are additions (don't break existing code)

Next Steps

Update Mobile App
- Handle new response fields
- Implement device management UI
- Show security notifications
Monitoring
- Query auth_audit for suspicious activity
- Monitor device counts per user
- Alert on unusual patterns
Future Enhancements
- Device name/labeling (let users name devices)
- Push notifications on new device login
- Device location tracking (optional)
- Session limits (max devices per user)

Files Modified

src/routes/authRoutes.js - Enhanced verify-otp and refresh endpoints
src/routes/userRoutes.js - Added device management endpoints
DEVICE_MANAGEMENT.md - New documentation
CHANGELOG_DEVICE_MANAGEMENT.md - This file

Questions?

See DEVICE_MANAGEMENT.md for detailed API documentation and examples.

6.4 KiB Raw Blame History