Device and Session Management

Current: “Stay Logged In” controls master key persistence and browser session lifetime.

Why This Exists

Users access OpenMates from personal devices and browser sessions. Session lifetime and key persistence are controlled separately so users can choose between convenience and short-lived local key storage.

How It Works

Personal Device Sessions

Stay Logged In = false (default):

• Master key stored in memory only.
• Auto-cleared when page/tab closes.

Stay Logged In = true:

• Master key stored in IndexedDB as a CryptoKey object.
• Persists across browser sessions via Web Crypto API isolation.

Session Token Security

• Storage: HTTP-only secure cookies.
• TTL: 30 days (with “Stay logged in”) or 24 hours (default).
• Refresh: Automatic background refresh.
• Revocation: On user logout or security event.

Each refresh-token chain is one logical session. Its server-only security metadata—including the last validated country—is stored with that token’s entry in user_tokens:{user_id}. Token rotation moves the complete metadata record to the new token hash. A browser session, CLI session, and native app session therefore keep independent risk baselines even when they belong to the same account.

The display metadata shown in Active Sessions is client-encrypted. Replacing plaintext display fields must preserve server-only security metadata. Targeted logout and revocation remove only the selected token entry; logout-all remains the explicit account-wide operation.

Paired Sessions

Pairing v2 uses a client-to-client PAKE and a receiver-bound one-use login grant. The API relays PAKE messages and encrypted account-key material; the short PIN, ephemeral OPAQUE registration, and transfer key stay on the clients. The approving client must remain active until it verifies the receiver and releases the bundle. It reports success only after the receiver stores its session/key state and acknowledges completion.

Every new v2 paired session has a durable record in pair_session_deadlines, indexed by a hash of its refresh token. Pending acknowledgement denies ordinary REST/WebSocket access. A selected numeric lifetime gives the record an absolute deadline. Rotation creates a mapping for the replacement token and retires the previous mapping; losing Redis state cannot remove the deadline. A null lifetime keeps the ordinary session policy but still requires acknowledgement. Active WebSocket connections with a numeric deadline close when it is reached.

The approving session needs server-verified strong authentication from the last five minutes. Refreshing the cookie does not refresh that assurance. The implementation contract records wire fields and state transitions; the hardening roadmap distinguishes this implementation from wider session and credential repairs.

Device, Session, and Connection Identity

• A device hash uses stable client characteristics and the user ID; country is deliberately excluded.
• Country is a separate, session-local risk signal. A real country change may require 2FA or passkey verification for that session only.
• A connection hash combines the stable device hash with a tab/session ID for targeted WebSocket delivery.
• Existing location-coupled device hashes are accepted during migration and replaced by the stable hash after successful validation.
• A legacy token with no country baseline initializes its own baseline after a successful session check; it never copies one from shared account state.

Threat Mitigations

Related Docs

• Signup & Auth – authentication flows
• Encryption Architecture – master key encryption
• Developer Settings – API key management