Skip to main content

​
Overview

Device management tracks which browsers and devices have accessed your PassAgent vault. Each device is identified by a privacy-respecting fingerprint, assigned a trust level, and monitored for activity. When an unrecognized device signs in, PassAgent can trigger step-up authentication — requiring the user to re-verify their identity before accessing sensitive vault operations.

​
Device fingerprinting

The generateDeviceFingerprint() function in lib/device-fingerprint.ts produces a SHA-256 hash from a set of stable browser and OS signals. This fingerprint is deterministic for the same device/browser combination but varies across different setups. Collected signals:
SignalSourceExample
Platformnavigator.platformMacIntel
Languagenavigator.languageen-US
CPU coresnavigator.hardwareConcurrency8
Screen resolutionscreen.width x screen.height2560x1440
Color depthscreen.colorDepth24
TimezoneIntl.DateTimeFormat().resolvedOptions().timeZoneAmerica/New_York
Touch pointsnavigator.maxTouchPoints0
GPU rendererWebGL UNMASKED_RENDERER_WEBGLANGLE (Apple, ANGLE Metal..., ...)
The raw signals are joined with | separators and hashed with SHA-256 via crypto.subtle.digest(). The resulting hex string is the device fingerprint.
This is NOT a tracking fingerprint. PassAgent does not use canvas fingerprinting, audio fingerprinting, font enumeration, or any invasive tracking technique. The signals collected are limited to what is necessary for device identification and are never shared with third parties.

​
Device type detection

getDeviceType() classifies the device into three categories based on the user agent string:
TypeDetection pattern
tablet/iPad|Android(?!.*Mobile)/i
mobile/Mobile|iPhone|iPod|Android|webOS|BlackBerry|IEMobile|Opera Mini/i
desktopEverything else

​
Registration flow

1

Generate fingerprint

On login or vault unlock, the client calls generateDeviceFingerprint() to produce the device hash. The client also collects deviceName (derived from the user agent), deviceType, os, and browser metadata.
2

Register device

The client sends POST /api/devices with the fingerprint and metadata. The server checks if a device with this fingerprint already exists for the user.
3

Existing device: update activity

If the fingerprint matches an existing record, the server updates last_active_at, sets is_current: true (and clears is_current from all other devices), and refreshes the OS/browser metadata.
4

New device: create record

If the fingerprint is new, a trusted_devices row is created with trust_level: "trusted", the client’s IP address, and is_current: true. All other devices for this user have their is_current flag cleared.

​
Trust levels

LevelDescriptionVault access
trustedRecognized device, explicitly approvedFull access
recognizedPreviously seen but not yet trustedRequires step-up auth for sensitive operations
unknownBrand new device, never seen beforeRequires full re-authentication
New devices are automatically assigned trusted status on successful login. You can downgrade a device to recognized from the Settings page if you want to require step-up auth on that device going forward.

​
Device record schema

Each trusted device record in the trusted_devices table contains:
FieldTypeDescription
idUUIDPrimary key
user_idstringOwner’s user ID
device_fingerprintstringSHA-256 hash of collected signals
device_namestringHuman-readable name (e.g., “Chrome on macOS”)
device_typestringdesktop, mobile, or tablet
osstringOperating system (e.g., “macOS 14.2”)
browserstringBrowser name and version (e.g., “Chrome 120”)
ip_addressstringLast known IP address
trust_levelstringtrusted, recognized, or unknown
is_currentbooleanWhether this is the active device
last_active_attimestampLast activity time
trusted_attimestampWhen the device was first trusted

​
Managing devices

​
Rename a device

PATCH /api/devices/{id} with { deviceName: "Work Laptop" } updates the display name. This is purely cosmetic and does not affect the fingerprint or trust level.

​
Change trust level

PATCH /api/devices/{id} with { trustLevel: "recognized" } downgrades a device. This is useful if you lent your laptop to someone and want to require step-up auth the next time it accesses your vault.

​
Revoke a device

DELETE /api/devices/{id} permanently removes the device from your trusted list. The next time that device accesses your vault, it will appear as a new, unknown device and trigger the new-device flow.
Revoking a device does not terminate active sessions on that device. It only affects future authentication attempts. To immediately invalidate a session, use the session management feature to sign out all devices.

​
Step-up authentication

When a sensitive operation is attempted (password export, emergency access, session sharing), PassAgent checks the device’s trust level. If the device is recognized or unknown, or if the last authentication was too long ago, the user is prompted to re-verify their identity with their master password or biometric.

​
Audit logging

All device management actions are recorded in the audit log:
ActionTrigger
device.updatedDevice renamed or trust level changed
device.revokedDevice removed from trusted list
Each audit event includes the acting user’s IP address, user agent, and the specific changes made (device name, trust level).

​
Rate limiting

EndpointLimitWindow
POST /api/devices (register)30 requests60 seconds
PATCH /api/devices/{id} (update)30 requests60 seconds
DELETE /api/devices/{id} (revoke)30 requests60 seconds

​
API endpoints

MethodEndpointDescription
GET/api/devicesList all trusted devices for the authenticated user
POST/api/devicesRegister or re-register the current device
PATCH/api/devices/[id]Update device name or trust level
DELETE/api/devices/[id]Revoke a trusted device
The is_current flag is automatically managed by the server. Only one device per user can be marked as current at any time. This flag is used by the UI to highlight which device you are currently using.