Session Management

The Nero MPC SDK handles the complete lifecycle of authenticated sessions: token storage, automatic refresh, session status tracking, and device identification.

Token Structure

The SDK manages three token types:

An expiresAt timestamp (in milliseconds) indicates access token expiration.

Token Storage and Encryption

Tokens are encrypted using the device key via AES-256-GCM before storage. The default storage key is nero:tokens, customizable through the storagePrefix configuration option.

Token Management Methods

Automatic Token Refresh

The SDK automatically refreshes access tokens before expiration to maintain uninterrupted sessions.

Token expiry checking occurs on every authenticated request with a 60-second trigger threshold before expiration. The SDK uses a refreshPromise member to prevent concurrent refresh attempts. If refresh fails, tokens are cleared and the SDK transitions to an unauthenticated state.

The refresh endpoint is POST /api/v2/session/refresh via SessionAPI.refresh().

const sdk = new NeroMpcSDK({ backendUrl: "..." });
await sdk.init();

if (sdk.isAuthenticated) {
  // Session restored and tokens will auto-refresh
}

Session Status and Reconnection

Checking Status

The getSessionStatus() method queries the backend via SessionAPI.status(), returning a SessionStatus object containing active session information including expiration and associated devices.

Session Reconnection

Session reconnection restores a session using the dappShare token. This is useful for cross-device scenarios or storage migration.

Parameters:

• dappShare (optional): The dApp share token; uses stored token if not provided

Returns SessionReconnectResult containing:

• tokens: New access and refresh tokens
• user: User information
• sessionLifetime: Session duration in seconds

Device Key Lifecycle

Device keys serve as persistent device identifiers and encryption keys for local token storage.

Key properties:

• Generated via crypto.getRandomValues() producing random hex strings
• Storage priority: IndexedDB > localStorage > in-memory (ephemeral)
• Automatic migration from localStorage to IndexedDB when available
• Storage key: nero:device_key (customizable via storagePrefix)

Resolution Sequence

On initialization, the SDK loads or generates a stable per-device encryption key:

1. IndexedDB under key "device_key"
2. Legacy localStorage fallback under "{storagePrefix}:device_key"
3. New cryptographically random key generation if neither exists

The device key is registered with APIClient via setDeviceId() and passed to ClientKeyManager.

Device Fingerprinting

A DeviceFingerprint object is created during authentication containing navigator.userAgent for browser/platform identification. This fingerprint is sent as deviceId for security tracking.

Session Initialization Sequence

During sdk.init(), the SDK performs:

1. Load or generate device key
2. Initialize ClientKeyManager with device key
3. Load stored tokens from encrypted storage
4. If tokens exist, validate by fetching current user via getCurrentUser()
5. If valid, initialize wallet and emit 'initialized'
6. If invalid, clear tokens and emit 'initialized'

Session Termination

Logout Process

The logout() method terminates sessions with comprehensive cleanup:

1. Revoke dApp share session via SessionAPI.revoke()
2. Call backend logout endpoint via AuthAPI.logout() (POST /api/v2/auth/logout)
3. Clear all in-memory state variables
4. Reset connection state machine
5. Clear tokens from memory and storage
6. Disconnect EIP-1193 provider
7. Disconnect WebSocket client
8. Emit 'logout' event

Key shares stored by ClientKeyManager are preserved during logout, allowing future recovery and reconnection.

Disconnect vs Logout

The disconnect() method internally calls logout() for consistent cleanup.

Session Events

The SDK emits events throughout the session lifecycle:

sdk.on('login', ({ user }) => {
  console.log(`User logged in: ${user.id}`);
});

sdk.on('logout', () => {
  console.log('Session terminated');
});

sdk.on('initialized', () => {
  console.log('SDK ready');
});

Session State Properties

The SDK exposes session state through computed properties: