@lifi/perps-sdk 2.0.0 → 2.2.0

package/src/storage/encryptedStorage.ts

@@ -0,0 +1,190 @@
+import type { StorageAdapter } from './types.js'
+
+const DB_NAME = 'lifi-perps-sdk'
+const OBJECT_STORE = 'keys'
+const MASTER_KEY_ID = 'storage-master-key'
+const IV_BYTE_LENGTH = 12
+const AES_KEY_PARAMS = { name: 'AES-GCM', length: 256 } as const
+
+let masterKeyPromise: Promise<CryptoKey | null> | undefined
+let warnedDegraded = false
+
+// Silent in SSR (no `window`), where missing browser storage is expected.
+function warnDegraded(reason: string): void {
+  if (warnedDegraded || typeof window === 'undefined') {
+    return
+  }
+  warnedDegraded = true
+  console.warn(
+    `[perps-sdk] Persistent session storage disabled: ${reason}. Session keys will not survive a page reload.`
+  )
+}
+
+function openDb(): Promise<IDBDatabase> {
+  return new Promise((resolve, reject) => {
+    const request = indexedDB.open(DB_NAME, 1)
+    request.onupgradeneeded = () => {
+      request.result.createObjectStore(OBJECT_STORE)
+    }
+    request.onsuccess = () => resolve(request.result)
+    request.onerror = () => reject(request.error)
+  })
+}
+
+function requestToPromise<T>(request: IDBRequest<T>): Promise<T> {
+  return new Promise((resolve, reject) => {
+    request.onsuccess = () => resolve(request.result)
+    request.onerror = () => reject(request.error)
+  })
+}
+
+/**
+ * Resolve the AES-GCM master key, generating and persisting one on first use.
+ * The key is non-extractable and lives as a structured-cloned handle in
+ * IndexedDB — the raw bytes never leave the browser's crypto layer. Resolves
+ * `null` when IndexedDB or WebCrypto is unavailable so callers degrade to
+ * no-op writes / null reads rather than persisting plaintext.
+ */
+async function loadMasterKey(): Promise<CryptoKey | null> {
+  if (typeof crypto === 'undefined' || !crypto.subtle) {
+    warnDegraded('crypto.subtle is unavailable (non-HTTPS context?)')
+    return null
+  }
+  if (typeof indexedDB === 'undefined') {
+    warnDegraded('indexedDB is unavailable')
+    return null
+  }
+  try {
+    // Generated before the transaction: awaiting a non-IDB promise inside an
+    // IDB transaction auto-commits it, breaking the atomic get-or-adopt below.
+    const candidate = await crypto.subtle.generateKey(AES_KEY_PARAMS, false, [
+      'encrypt',
+      'decrypt',
+    ])
+    const db = await openDb()
+    try {
+      // Single readwrite transaction so concurrent tabs can't interleave the
+      // check and the write: the loser's get sees the winner's key and adopts
+      // it instead of clobbering, discarding its own candidate.
+      const store = db
+        .transaction(OBJECT_STORE, 'readwrite')
+        .objectStore(OBJECT_STORE)
+      const existing = await requestToPromise(store.get(MASTER_KEY_ID))
+      if (existing instanceof CryptoKey) {
+        return existing
+      }
+      await requestToPromise(store.put(candidate, MASTER_KEY_ID))
+      return candidate
+    } finally {
+      db.close()
+    }
+  } catch {
+    warnDegraded('indexedDB failed to open or store the master key')
+    return null
+  }
+}
+
+function getMasterKey(): Promise<CryptoKey | null> {
+  masterKeyPromise ??= loadMasterKey()
+  return masterKeyPromise
+}
+
+function bytesToBase64(bytes: Uint8Array): string {
+  let binary = ''
+  for (const byte of bytes) {
+    binary += String.fromCharCode(byte)
+  }
+  return btoa(binary)
+}
+
+function base64ToBytes(value: string): Uint8Array {
+  const binary = atob(value)
+  const bytes = new Uint8Array(binary.length)
+  for (let i = 0; i < binary.length; i += 1) {
+    bytes[i] = binary.charCodeAt(i)
+  }
+  return bytes
+}
+
+/**
+ * Default storage adapter: persists AES-GCM-256 ciphertext to browser
+ * `localStorage`, keyed by a non-extractable master {@link CryptoKey} held in
+ * IndexedDB. Each `set` uses a fresh 12-byte IV and
+ * stores `base64(iv ‖ ciphertext)`. Falls back to a no-op / `null` when
+ * `localStorage`, `indexedDB`, or `crypto.subtle` is unavailable (e.g. SSR) —
+ * never writing plaintext. In browser contexts the degradation logs a one-time
+ * `console.warn` naming the missing capability.
+ *
+ * `get` resolves `null` on any failure (missing master key, tampered or
+ * truncated ciphertext, malformed value), matching the poisoned-record
+ * eviction philosophy so callers treat undecryptable data as absent.
+ *
+ * @security Encryption at rest defeats generic browser-storage/disk scanning
+ * and raw key exfiltration, not malware targeting this SDK or a fully
+ * compromised page — a same-origin script can still drive this adapter to
+ * decrypt.
+ *
+ * @public
+ */
+export const localStorageAdapter: StorageAdapter = {
+  async get(key: string): Promise<string | null> {
+    try {
+      const raw = localStorage.getItem(key)
+      if (raw === null) {
+        return null
+      }
+      const masterKey = await getMasterKey()
+      if (!masterKey) {
+        return null
+      }
+      const combined = base64ToBytes(raw)
+      const iv = combined.slice(0, IV_BYTE_LENGTH)
+      const ciphertext = combined.slice(IV_BYTE_LENGTH)
+      const plaintext = await crypto.subtle.decrypt(
+        { name: 'AES-GCM', iv },
+        masterKey,
+        ciphertext
+      )
+      return new TextDecoder().decode(plaintext)
+    } catch {
+      if (typeof localStorage === 'undefined') {
+        warnDegraded('localStorage is unavailable')
+      }
+      return null
+    }
+  },
+
+  async set(key: string, value: string): Promise<void> {
+    try {
+      const masterKey = await getMasterKey()
+      if (!masterKey) {
+        return
+      }
+      const iv = crypto.getRandomValues(new Uint8Array(IV_BYTE_LENGTH))
+      const ciphertext = new Uint8Array(
+        await crypto.subtle.encrypt(
+          { name: 'AES-GCM', iv },
+          masterKey,
+          new TextEncoder().encode(value)
+        )
+      )
+      const combined = new Uint8Array(iv.length + ciphertext.length)
+      combined.set(iv, 0)
+      combined.set(ciphertext, iv.length)
+      localStorage.setItem(key, bytesToBase64(combined))
+    } catch {
+      // Encryption failed or localStorage unavailable — never persist plaintext
+      if (typeof localStorage === 'undefined') {
+        warnDegraded('localStorage is unavailable')
+      }
+    }
+  },
+
+  async remove(key: string): Promise<void> {
+    try {
+      localStorage.removeItem(key)
+    } catch {
+      // localStorage not available
+    }
+  },
+}

package/src/storage/storage.ts

@@ -1,39 +1,5 @@
 import type { StorageAdapter } from './types.js'
 
-/**
- * localStorage adapter for browser environments. Falls back to a no-op when
- * `localStorage` is unavailable (e.g. SSR).
- *
- * @public
- */
-export const localStorageAdapter: StorageAdapter = {
-  get: (key: string): Promise<string | null> => {
-    try {
-      return Promise.resolve(localStorage.getItem(key))
-    } catch {
-      return Promise.resolve(null)
-    }
-  },
-
-  set: (key: string, value: string): Promise<void> => {
-    try {
-      localStorage.setItem(key, value)
-    } catch {
-      // localStorage not available
-    }
-    return Promise.resolve()
-  },
-
-  remove: (key: string): Promise<void> => {
-    try {
-      localStorage.removeItem(key)
-    } catch {
-      // localStorage not available
-    }
-    return Promise.resolve()
-  },
-}
-
 /**
  * In-memory storage adapter for testing or server-side use.
  *

package/src/types/api.ts

@@ -179,7 +179,11 @@ export interface SendAssetActionParams {
 export interface CancelOrdersParams {
   provider: string
   address: Address
+  /** Venue order ids. Venues whose ids are scoped per market (e.g. Lighter's
+   * `order_index`) also accept the composite `"<market_id>:<order_id>"`. */
   ids: string[]
+  /** Market context for per-market order ids; the order's `market.id`. */
+  assetId?: string
 }
 
 /**

package/src/utils/accountSummary.ts

@@ -15,6 +15,9 @@ const sumValueUsd = (balances: AccountResponse['balances']): number =>
  * - `'free'` — free collateral only; locked margin and unrealized PnL are
  *   both carried by the positions. Available margin is the free collateral
  *   as-is; unrealized PnL is not counted toward it.
+ * - `'net'` — free collateral with unrealized PnL already marked in; only
+ *   the locked margin is carried by the positions (e.g. a venue-reported
+ *   available balance).
  * - `'gross'` — locked margin included, unrealized PnL carried by the
  *   positions (e.g. spot holdings backing a unified account). The venue
  *   counts unrealized PnL toward buying power, so it is added to available
@@ -25,7 +28,7 @@ const sumValueUsd = (balances: AccountResponse['balances']): number =>
  *
  * @public
  */
-export type CollateralSemantics = 'free' | 'gross' | 'equity'
+export type CollateralSemantics = 'free' | 'net' | 'gross' | 'equity'
 
 /**
  * Roll an {@link AccountResponse} and its open positions up into an
@@ -51,9 +54,13 @@ export function summarizeAccount(
   const balances = sumValueUsd(account.balances)
 
   const grossCollateral =
-    semantics === 'free' ? collateral + marginUsed : collateral
+    semantics === 'free' || semantics === 'net'
+      ? collateral + marginUsed
+      : collateral
   const equity =
-    semantics === 'equity' ? grossCollateral : grossCollateral + unrealizedPnl
+    semantics === 'equity' || semantics === 'net'
+      ? grossCollateral
+      : grossCollateral + unrealizedPnl
 
   // Buying power is equity net of locked margin, so unrealized PnL counts
   // toward it. The `'free'` rows exclude uPnL from available margin, holding

package/src/version.ts

@@ -1,2 +1,2 @@
 export const name = '@lifi/perps-sdk'
-export const version = '2.0.0'
+export const version = '2.2.0'