@paramms/chat-widget 0.1.0

package/src/__tests__/store.test.ts

@@ -0,0 +1,86 @@
+import { describe, it, expect } from 'vitest'
+import {
+  asUserId, asConversationId, asMessageId,
+  type ServerFrame, type Message,
+} from '../protocol/index.js'
+import { ChatStore } from '../store.js'
+
+const me = asUserId('alice')
+const cid = asConversationId('c1')
+
+function srvMsg(seq: number, from: string, text: string): Message {
+  return { id: asMessageId(`s${seq}`), conversationId: cid, seq, senderId: asUserId(from), senderRole: from === 'alice' ? 'guest' : 'agent', content: { kind: 'text', text }, ts: seq }
+}
+
+describe('ChatStore', () => {
+  it('reconciles an optimistic send on ack (rekey, seq, status)', () => {
+    const s = new ChatStore(me)
+    s.apply({ type: 'opened', conversation: { id: cid, tenantId: 't' as never, profileId: 'p' as never, guestId: me, participants: [me], state: 'open', lastSeq: 0, createdAt: 0, updatedAt: 0 } })
+    s.addOptimistic('cm1', { kind: 'text', text: 'hi' })
+    expect(s.messages()[0]!.status).toBe('pending')
+    s.apply({ type: 'ack', clientMsgId: 'cm1', messageId: asMessageId('s1'), seq: 1, ts: 10 })
+    const m = s.messages()[0]!
+    expect(m.id).toBe('s1')
+    expect(m.seq).toBe(1)
+    expect(m.status).toBe('sent')
+    expect(s.messages()).toHaveLength(1)   // not duplicated
+  })
+
+  it('dedups the same message arriving live and via sync', () => {
+    const s = new ChatStore(me)
+    s.apply({ type: 'message', message: srvMsg(2, 'bob', 'yo') })
+    s.apply({ type: 'sync', conversationId: cid, messages: [srvMsg(1, 'bob', 'first'), srvMsg(2, 'bob', 'yo')] })
+    expect(s.messages().map(m => m.seq)).toEqual([1, 2])   // seq-ordered, no dup of seq 2
+  })
+
+  it('progresses own-message status delivered → read', () => {
+    const s = new ChatStore(me)
+    s.addOptimistic('cm1', { kind: 'text', text: 'hi' })
+    s.apply({ type: 'ack', clientMsgId: 'cm1', messageId: asMessageId('s1'), seq: 1, ts: 1 })
+    s.apply({ type: 'delivered', conversationId: cid, seq: 1, to: me })
+    expect(s.messages()[0]!.status).toBe('delivered')
+    s.apply({ type: 'read', conversationId: cid, seq: 1, by: asUserId('bob') })
+    expect(s.messages()[0]!.status).toBe('read')
+    expect(s.lastReadByOthers).toBe(1)
+  })
+
+  it('tracks typing from others only', () => {
+    const s = new ChatStore(me)
+    s.apply({ type: 'typing', conversationId: cid, userId: asUserId('bob'), isTyping: true })
+    s.apply({ type: 'typing', conversationId: cid, userId: me, isTyping: true })   // self ignored
+    expect([...s.typing]).toEqual(['bob'])
+    s.apply({ type: 'typing', conversationId: cid, userId: asUserId('bob'), isTyping: false })
+    expect(s.typing.size).toBe(0)
+  })
+
+  it('toggles reactions and applies edit/delete', () => {
+    const s = new ChatStore(me)
+    s.apply({ type: 'message', message: srvMsg(1, 'bob', 'hi') })
+    s.apply({ type: 'reaction', conversationId: cid, messageId: asMessageId('s1'), emoji: '👍', by: me, removed: false })
+    expect(s.messages()[0]!.reactions).toEqual({ '👍': [me] })
+    s.apply({ type: 'reaction', conversationId: cid, messageId: asMessageId('s1'), emoji: '👍', by: me, removed: true })
+    expect(s.messages()[0]!.reactions).toEqual({})
+    s.apply({ type: 'edited', conversationId: cid, messageId: asMessageId('s1'), content: { kind: 'text', text: 'edited' }, editedAt: 5 })
+    expect(s.messages()[0]!.content).toEqual({ kind: 'text', text: 'edited' })
+    s.apply({ type: 'deleted', conversationId: cid, messageId: asMessageId('s1'), ts: 6 })
+    expect(s.messages()[0]!.deletedAt).toBe(6)
+  })
+
+  it('filters visible actions by conversation state', () => {
+    const s = new ChatStore(me)
+    s.apply({ type: 'manifest', conversationId: cid, version: 1, actions: [
+      { id: asMessageId('a1') as never, label: 'Always', audience: 'guest', surface: 'toolbar' },
+      { id: asMessageId('a2') as never, label: 'Closed only', audience: 'guest', surface: 'toolbar', availableInStates: ['closed'] },
+    ] })
+    s.apply({ type: 'opened', conversation: { id: cid, tenantId: 't' as never, profileId: 'p' as never, guestId: me, participants: [me], state: 'open', lastSeq: 0, createdAt: 0, updatedAt: 0 } })
+    expect(s.visibleActions().map(a => a.label)).toEqual(['Always'])
+    s.apply({ type: 'state', conversationId: cid, state: 'closed' })
+    expect(s.visibleActions().map(a => a.label)).toEqual(['Always', 'Closed only'])
+  })
+
+  it('reports highest seq for the sync cursor', () => {
+    const s = new ChatStore(me)
+    s.apply({ type: 'sync', conversationId: cid, messages: [srvMsg(3, 'bob', 'c'), srvMsg(7, 'bob', 'g')] })
+    expect(s.highestSeq()).toBe(7)
+  })
+})

package/src/__tests__/x3dh.test.ts

@@ -0,0 +1,204 @@
+import { describe, it, expect } from 'vitest'
+import {
+  generateKeyPair, exportPublicKey, encrypt, decrypt,
+  signPrekey, verifyPrekeySignature,
+  x3dhSend, x3dhReceive,
+  generateIdentityKeyPair,
+} from '../crypto.js'
+import { E2ESession, extractX3DHInit } from '../e2e.js'
+
+// ── X3DH crypto primitives ────────────────────────────────────────────────────
+
+describe('X3DH crypto primitives', () => {
+  it('sender and recipient derive the same shared key', async () => {
+    // Recipient has: identity keypair (ECDH + ECDSA), a signed prekey, one OPK
+    const recipientIKP = await generateIdentityKeyPair()
+    const recipientSPK = await generateKeyPair()
+    const recipientOPK = await generateKeyPair()
+
+    const senderIKP = await generateIdentityKeyPair()
+
+    const bundle = {
+      identityKey:    recipientIKP.publicKeyB64,
+      signedPrekey:   await exportPublicKey(recipientSPK.publicKey),
+      signedPrekeyId: 'spk-001',
+      signature:      await signPrekey(recipientIKP.ecdsaKP.privateKey, recipientSPK.publicKey),
+      oneTimePrekey:  await exportPublicKey(recipientOPK.publicKey),
+    }
+
+    // Sender does X3DH
+    const { sharedKey: senderKey, ephemeralPublicKey } = await x3dhSend(senderIKP.ecdhKP, bundle)
+
+    // Recipient does X3DH
+    const recipientKey = await x3dhReceive(
+      recipientIKP.ecdhKP, recipientSPK,
+      senderIKP.publicKeyB64, ephemeralPublicKey,
+      recipientOPK,
+    )
+
+    // Both keys encrypt/decrypt to the same plaintext
+    const { ct, iv } = await encrypt(senderKey, 'async hello from offline sender')
+    const plain = await decrypt(recipientKey, ct, iv)
+    expect(plain).toBe('async hello from offline sender')
+  })
+
+  it('works without a one-time prekey (OPK optional)', async () => {
+    const recipientIKP = await generateIdentityKeyPair()
+    const recipientSPK = await generateKeyPair()
+    const senderIKP    = await generateIdentityKeyPair()
+
+    const bundle = {
+      identityKey:    recipientIKP.publicKeyB64,
+      signedPrekey:   await exportPublicKey(recipientSPK.publicKey),
+      signedPrekeyId: 'spk-002',
+      signature:      await signPrekey(recipientIKP.ecdsaKP.privateKey, recipientSPK.publicKey),
+      // no oneTimePrekey
+    }
+
+    const { sharedKey: senderKey, ephemeralPublicKey } = await x3dhSend(senderIKP.ecdhKP, bundle)
+    const recipientKey = await x3dhReceive(
+      recipientIKP.ecdhKP, recipientSPK,
+      senderIKP.publicKeyB64, ephemeralPublicKey,
+      undefined,
+    )
+
+    const { ct, iv } = await encrypt(senderKey, 'no-opk message')
+    expect(await decrypt(recipientKey, ct, iv)).toBe('no-opk message')
+  })
+
+  it('different ephemeral keys produce different shared secrets (no key reuse)', async () => {
+    const recipientIKP = await generateIdentityKeyPair()
+    const recipientSPK = await generateKeyPair()
+    const senderIKP    = await generateIdentityKeyPair()
+
+    const bundle = {
+      identityKey:    recipientIKP.publicKeyB64,
+      signedPrekey:   await exportPublicKey(recipientSPK.publicKey),
+      signedPrekeyId: 'spk-003',
+      signature:      await signPrekey(recipientIKP.ecdsaKP.privateKey, recipientSPK.publicKey),
+    }
+
+    const r1 = await x3dhSend(senderIKP.ecdhKP, bundle)
+    const r2 = await x3dhSend(senderIKP.ecdhKP, bundle)
+    // Different ephemeral keys → different shared secrets
+    expect(r1.ephemeralPublicKey).not.toBe(r2.ephemeralPublicKey)
+    const { ct, iv } = await encrypt(r1.sharedKey, 'msg1')
+    await expect(decrypt(r2.sharedKey, ct, iv)).rejects.toBeTruthy()
+  })
+
+  it('wrong sender IK on recipient side fails decryption', async () => {
+    const recipientIKP = await generateIdentityKeyPair()
+    const recipientSPK = await generateKeyPair()
+    const senderIKP    = await generateIdentityKeyPair()
+    const wrongIKP     = await generateIdentityKeyPair()
+
+    const bundle = {
+      identityKey:    recipientIKP.publicKeyB64,
+      signedPrekey:   await exportPublicKey(recipientSPK.publicKey),
+      signedPrekeyId: 'spk-004',
+      signature:      await signPrekey(recipientIKP.ecdsaKP.privateKey, recipientSPK.publicKey),
+    }
+
+    const { sharedKey: senderKey, ephemeralPublicKey } = await x3dhSend(senderIKP.ecdhKP, bundle)
+    // Recipient rederives with WRONG sender IK
+    const wrongKey = await x3dhReceive(
+      recipientIKP.ecdhKP, recipientSPK,
+      wrongIKP.publicKeyB64,  // wrong
+      ephemeralPublicKey,
+    )
+    const { ct, iv } = await encrypt(senderKey, 'secret')
+    await expect(decrypt(wrongKey, ct, iv)).rejects.toBeTruthy()
+  })
+
+  it('signPrekey and verifyPrekeySignature are consistent', async () => {
+    const ikp    = await generateIdentityKeyPair()
+    const spkKP  = await generateKeyPair()
+    const sig = await signPrekey(ikp.ecdsaKP.privateKey, spkKP.publicKey)
+    const spkPub = await exportPublicKey(spkKP.publicKey)
+    expect(await verifyPrekeySignature(ikp.sigPublicKeyB64, spkPub, sig)).toBe(true)
+  })
+
+  it('rejects tampered signature', async () => {
+    const ikp    = await generateIdentityKeyPair()
+    const spkKP  = await generateKeyPair()
+    const sig = await signPrekey(ikp.ecdsaKP.privateKey, spkKP.publicKey)
+    const spkPub = await exportPublicKey(spkKP.publicKey)
+    const tampered = sig.slice(0, -4) + 'AAAA'
+    expect(await verifyPrekeySignature(ikp.sigPublicKeyB64, spkPub, tampered)).toBe(false)
+  })
+})
+
+// ── E2ESession X3DH integration ───────────────────────────────────────────────
+
+describe('E2ESession — X3DH async mode', () => {
+  it('sender and recipient derive the same key and round-trip a message', async () => {
+    const sender    = new E2ESession('test-sender')
+    const recipient = new E2ESession('test-recipient')
+
+    // Recipient initialises X3DH (uploads prekeys in prod)
+    const recipientUpload = await recipient.initX3DH()
+
+    // Sender fetches the bundle and does X3DH
+    const x3dhInit = await sender.x3dhSendTo({
+      identityKey:    recipientUpload.identityKey,
+      signedPrekey:   recipientUpload.signedPrekey,
+      signedPrekeyId: recipientUpload.signedPrekeyId,
+      signature:      recipientUpload.signature,
+      oneTimePrekey:  recipientUpload.oneTimePrekeys[0],
+    })
+    expect(sender.ready).toBe(true)
+    // x3dhSendTo now returns senderIK so it can be embedded in the init message
+    expect(x3dhInit.senderIK).toBeTruthy()
+
+    // Seal with X3DH init fields (senderIK embedded so recipient can rederive)
+    const sealed = await sender.sealText('hello offline world', x3dhInit)
+    expect(sealed.kind).toBe('text')
+    expect((sealed as { enc?: boolean }).enc).toBe(true)
+    expect((sealed as { text: string }).text).not.toContain('offline world')
+
+    const fields = extractX3DHInit(sealed)
+    expect(fields).not.toBeNull()
+    expect(fields!.x3dhEK).toBe(x3dhInit.ephemeralKey)
+    expect(fields!.x3dhIK).toBe(x3dhInit.senderIK)
+
+    // Recipient rederives using the sender's IK embedded in the init message
+    await recipient.x3dhReceiveFrom(fields!.x3dhIK, fields!.x3dhEK, fields!.x3dhSPK)
+    expect(recipient.ready).toBe(true)
+
+    const frame = {
+      type: 'message' as const,
+      message: { id: 'm1' as never, conversationId: 'c1' as never, seq: 1, senderId: 'u1' as never, senderRole: 'guest' as const, content: sealed, ts: 1 },
+    }
+    await recipient.openFrame(frame)
+    expect((frame.message.content as { text: string }).text).toBe('hello offline world')
+  })
+
+  it('live ECDH mode still works independently', async () => {
+    const guest = new E2ESession('guest-live')
+    const agent = new E2ESession('agent-live')
+
+    const guestPub = await guest.begin()
+    const agentPub = await agent.begin()
+
+    await guest.onPeerKey(agentPub)
+    await agent.onPeerKey(guestPub)
+
+    expect(guest.ready).toBe(true)
+    expect(agent.ready).toBe(true)
+
+    const sealed = await guest.sealText('live message')
+    const frame = {
+      type: 'message' as const,
+      message: { id: 'm1' as never, conversationId: 'c1' as never, seq: 1, senderId: 'u2' as never, senderRole: 'agent' as const, content: sealed, ts: 1 },
+    }
+    await agent.openFrame(frame)
+    expect((frame.message.content as { text: string }).text).toBe('live message')
+  })
+
+  it('extractX3DHInit returns null for non-E2E content', () => {
+    expect(extractX3DHInit({ kind: 'text', text: 'plain' })).toBeNull()
+    expect(extractX3DHInit({ kind: 'text', text: 'ct', enc: true, iv: 'iv' })).toBeNull()
+    expect(extractX3DHInit({ kind: 'card', title: 'x' })).toBeNull()
+  })
+})
+

package/src/connection.ts

@@ -0,0 +1,133 @@
+import {
+  encodeFrame, decodeFrame, isClientFrame,
+  type ClientFrame, type ServerFrame,
+} from './protocol/index.js'
+
+// Minimal socket surface so tests can inject a fake without a real WebSocket.
+export interface SocketLike {
+  binaryType: string
+  send(data: Uint8Array): void
+  close(): void
+  onopen:    (() => void) | null
+  onclose:   (() => void) | null
+  onerror:   (() => void) | null
+  onmessage: ((ev: { data: ArrayBuffer }) => void) | null
+}
+export type SocketFactory = (url: string) => SocketLike
+
+export interface ConnectionOptions {
+  url:        string
+  token:      string
+  open:       Extract<ClientFrame, { type: 'open' }>  // what to (re)open on connect
+  onFrame:    (frame: ServerFrame) => void
+  getCursor:  () => number          // highest seq seen (for sync on reconnect)
+  onStatusChange?: (status: 'connecting' | 'open' | 'reconnecting') => void
+  socketFactory?: SocketFactory
+  backoffBaseMs?: number
+  backoffMaxMs?:  number
+  maxOutbox?:     number
+}
+
+type State = 'idle' | 'connecting' | 'open' | 'closed'
+
+export class ConnectionManager {
+  private socket: SocketLike | null = null
+  private state: State = 'idle'
+  private authed = false
+  private attempt = 0
+  private outbox: ClientFrame[] = []
+  private stopped = false
+  private timer: ReturnType<typeof setTimeout> | null = null
+
+  constructor(private readonly opts: ConnectionOptions) {}
+
+  connect(): void {
+    if (this.state === 'connecting' || this.state === 'open') return
+    this.stopped = false
+    this.state = 'connecting'
+    this.authed = false
+    this.opts.onStatusChange?.(this.attempt > 0 ? 'reconnecting' : 'connecting')
+    const make = this.opts.socketFactory ?? defaultFactory
+    const sock = make(this.opts.url)
+    sock.binaryType = 'arraybuffer'
+    this.socket = sock
+
+    sock.onopen = () => {
+      this.attempt = 0
+      // Auth first; the rest is sent once 'authed' arrives.
+      this.raw({ type: 'auth', token: this.opts.token })
+    }
+    sock.onmessage = (ev) => {
+      const frame = decodeFrame(new Uint8Array(ev.data))
+      if (!frame || isClientFrame(frame)) return   // ignore non-server frames
+      this.handle(frame)
+    }
+    sock.onclose = () => this.onClosed()
+    sock.onerror = () => { try { sock.close() } catch { /* */ } }
+  }
+
+  /** Queue a frame; sent immediately if open, else flushed on (re)connect.
+   *  The outbox is bounded so a prolonged outage can't grow memory without limit
+   *  — oldest queued frames are dropped past the cap. */
+  send(frame: ClientFrame): void {
+    if (this.state === 'open' && this.authed) { this.raw(frame); return }
+    const cap = this.opts.maxOutbox ?? 1_000
+    if (this.outbox.length >= cap) {
+      // Evict oldest half when full to amortise the O(n) cost of overflow.
+      this.outbox = this.outbox.slice(this.outbox.length - (cap >> 1))
+    }
+    this.outbox.push(frame)
+  }
+
+  close(): void {
+    this.stopped = true
+    if (this.timer) clearTimeout(this.timer)
+    this.state = 'closed'
+    try { this.socket?.close() } catch { /* */ }
+  }
+
+  private handle(frame: ServerFrame): void {
+    if (frame.type === 'authed') {
+      this.state = 'open'
+      this.authed = true
+      this.opts.onStatusChange?.('open')
+      // Open/resolve the conversation. The catch-up `sync` is sent on 'opened'
+      // (below), i.e. only after the server has joined us to the room — sending
+      // it here would race the async open and be rejected as "not joined".
+      this.raw(this.opts.open)
+      this.flush()
+    }
+    // 'opened' confirms we're joined — now catch up from our cursor.
+    if (frame.type === 'opened') {
+      this.raw({ type: 'sync', conversationId: frame.conversation.id, sinceSeq: this.opts.getCursor() })
+    }
+    this.opts.onFrame(frame)
+  }
+
+  private flush(): void {
+    const pending = this.outbox
+    this.outbox = []
+    for (const f of pending) this.raw(f)
+  }
+
+  private raw(frame: ClientFrame): void {
+    try { this.socket?.send(encodeFrame(frame)) } catch { this.outbox.push(frame) }
+  }
+
+  private onClosed(): void {
+    this.authed = false
+    this.socket = null
+    if (this.stopped) { this.state = 'closed'; return }
+    this.state = 'idle'
+    // Exponential backoff with jitter; reconnect re-auths, re-opens, re-syncs.
+    const base = this.opts.backoffBaseMs ?? 500
+    const max  = this.opts.backoffMaxMs ?? 15_000
+    const delay = Math.min(max, base * 2 ** this.attempt) * (0.5 + Math.random() * 0.5)
+    this.attempt++
+    this.timer = setTimeout(() => this.connect(), delay)
+  }
+}
+
+function defaultFactory(url: string): SocketLike {
+  return new WebSocket(url) as unknown as SocketLike
+}

package/src/crypto.ts

@@ -0,0 +1,252 @@
+/**
+ * End-to-end encryption primitives (Web Crypto): ECDH P-256 for key agreement
+ * + AES-GCM for message content. The server only ever relays public keys and
+ * stores ciphertext — it cannot read messages.
+ *
+ * Scope/limitations (honest): this secures a *live 1:1* session — the guest and
+ * one agent exchange public keys while both are connected, then messages between
+ * them are encrypted. True asynchronous E2E (encrypting to an offline party)
+ * needs a prekey/X3DH scheme, which is out of scope here. When E2E is on, the
+ * AI assistant cannot read the room (by design).
+ */
+
+const subtle = (): SubtleCrypto => globalThis.crypto.subtle
+
+function b64encode(buf: ArrayBuffer | Uint8Array): string {
+  const bytes = buf instanceof Uint8Array ? buf : new Uint8Array(buf)
+  let s = ''
+  for (const b of bytes) s += String.fromCharCode(b)
+  return btoa(s)
+}
+function b64decode(s: string): Uint8Array<ArrayBuffer> {
+  const bin = atob(s)
+  const buf = new ArrayBuffer(bin.length)
+  const out = new Uint8Array(buf)
+  for (let i = 0; i < bin.length; i++) out[i] = bin.charCodeAt(i)
+  return out
+}
+
+export interface KeyPair { publicKey: CryptoKey; privateKey: CryptoKey }
+
+export async function generateKeyPair(): Promise<KeyPair> {
+  const kp = await subtle().generateKey({ name: 'ECDH', namedCurve: 'P-256' }, true, ['deriveKey', 'deriveBits'])
+  return { publicKey: kp.publicKey, privateKey: kp.privateKey }
+}
+
+/** Export a public key to a compact base64 string (raw, 65 bytes for P-256). */
+export async function exportPublicKey(key: CryptoKey): Promise<string> {
+  return b64encode(await subtle().exportKey('raw', key))
+}
+
+async function importPeerPublicKey(b64: string): Promise<CryptoKey> {
+  return subtle().importKey('raw', b64decode(b64), { name: 'ECDH', namedCurve: 'P-256' }, false, [])
+}
+
+/** Derive the shared AES-GCM key from our private key + the peer's public key. */
+export async function deriveSharedKey(privateKey: CryptoKey, peerPublicKeyB64: string): Promise<CryptoKey> {
+  const peer = await importPeerPublicKey(peerPublicKeyB64)
+  return subtle().deriveKey(
+    { name: 'ECDH', public: peer },
+    privateKey,
+    { name: 'AES-GCM', length: 256 },
+    false,
+    ['encrypt', 'decrypt'],
+  )
+}
+
+export interface Ciphertext { ct: string; iv: string }
+
+export async function encrypt(key: CryptoKey, plaintext: string): Promise<Ciphertext> {
+  const iv = globalThis.crypto.getRandomValues(new Uint8Array(12))
+  const data = new TextEncoder().encode(plaintext)
+  const ct = await subtle().encrypt({ name: 'AES-GCM', iv }, key, data)
+  return { ct: b64encode(ct), iv: b64encode(iv) }
+}
+
+export async function decrypt(key: CryptoKey, ct: string, iv: string): Promise<string> {
+  const plain = await subtle().decrypt({ name: 'AES-GCM', iv: b64decode(iv) }, key, b64decode(ct))
+  return new TextDecoder().decode(plain)
+}
+
+/** Persist/restore our keypair across reloads (so prior ciphertext stays readable). */
+export async function loadOrCreateKeyPair(storageKey: string): Promise<KeyPair> {
+  try {
+    const raw = globalThis.localStorage?.getItem(storageKey)
+    if (raw) {
+      const { pub, priv } = JSON.parse(raw) as { pub: JsonWebKey; priv: JsonWebKey }
+      const publicKey = await subtle().importKey('jwk', pub, { name: 'ECDH', namedCurve: 'P-256' }, true, [])
+      const privateKey = await subtle().importKey('jwk', priv, { name: 'ECDH', namedCurve: 'P-256' }, true, ['deriveKey', 'deriveBits'])
+      return { publicKey, privateKey }
+    }
+  } catch { /* fall through to fresh keys */ }
+  const kp = await generateKeyPair()
+  try {
+    const pub = await subtle().exportKey('jwk', kp.publicKey)
+    const priv = await subtle().exportKey('jwk', kp.privateKey)
+    globalThis.localStorage?.setItem(storageKey, JSON.stringify({ pub, priv }))
+  } catch { /* non-persistent environment is fine */ }
+  return kp
+}
+
+// ── X3DH async E2E ────────────────────────────────────────────────────────────
+// Extended Triple Diffie-Hellman (X3DH) allows encrypting to an *offline* peer
+// using their published prekey bundle. This enables asynchronous E2E: the sender
+// can encrypt before the recipient connects.
+//
+// Key roles:
+//   IK  = long-term identity key (ECDH P-256, persistent in localStorage)
+//   SPK = signed prekey (ECDH P-256, rotated periodically, server-stored)
+//   OPK = one-time prekey (ECDH P-256, single-use pool, server-stored)
+//   EK  = ephemeral key (ECDH P-256, generated per-message, discarded after)
+//
+// X3DH shared secret = KDF(DH(IK_s, SPK_r) || DH(EK, IK_r) || DH(EK, SPK_r) || DH(EK, OPK_r))
+// Where _s = sender, _r = recipient.
+
+/** Sign a prekey public key bytes using ECDSA P-256 SHA-256.
+ *  The signingKey must be an ECDSA P-256 private key (not ECDH).
+ *  In the full X3DH setup the identity key pair contains both an ECDH key
+ *  (for DH) and an ECDSA key (for signing). We keep them separate here. */
+export async function signPrekey(signingPrivateKey: CryptoKey, spkPublicKey: CryptoKey): Promise<string> {
+  const spkRaw = await subtle().exportKey('raw', spkPublicKey)
+  const sig = await subtle().sign({ name: 'ECDSA', hash: 'SHA-256' }, signingPrivateKey, spkRaw)
+  return b64encode(sig)
+}
+
+/** Verify an SPK signature. verifyPublicKey must be an ECDSA P-256 public key. */
+export async function verifyPrekeySignature(verifyPublicKeyB64: string, spkPublicKeyB64: string, signatureB64: string): Promise<boolean> {
+  try {
+    const verKey = await subtle().importKey('raw', b64decode(verifyPublicKeyB64), { name: 'ECDSA', namedCurve: 'P-256' }, false, ['verify'])
+    return await subtle().verify({ name: 'ECDSA', hash: 'SHA-256' }, verKey, b64decode(signatureB64), b64decode(spkPublicKeyB64))
+  } catch { return false }
+}
+
+/** A full identity keypair for X3DH: ECDH key for DH computations + ECDSA key
+ *  for signing prekeys. The two key objects share the same P-256 curve but have
+ *  different usages, so Web Crypto treats them separately. */
+export interface IdentityKeyPair {
+  ecdhKP:   KeyPair   // for DH in X3DH
+  ecdsaKP:  { publicKey: CryptoKey; privateKey: CryptoKey }  // for signing SPKs
+  /** The ECDH public key exported as base64 — used as the X3DH identity key. */
+  publicKeyB64: string
+  /** The ECDSA public key exported as base64 — used for SPK signature verification. */
+  sigPublicKeyB64: string
+}
+
+/** Generate a full X3DH identity keypair (ECDH + ECDSA on the same P-256 curve). */
+export async function generateIdentityKeyPair(): Promise<IdentityKeyPair> {
+  const ecdhKP  = await generateKeyPair()
+  const ecdsaKP = await subtle().generateKey({ name: 'ECDSA', namedCurve: 'P-256' }, true, ['sign', 'verify'])
+  return {
+    ecdhKP,
+    ecdsaKP: { publicKey: ecdsaKP.publicKey, privateKey: ecdsaKP.privateKey },
+    publicKeyB64:    await exportPublicKey(ecdhKP.publicKey),
+    sigPublicKeyB64: await exportPublicKey(ecdsaKP.publicKey),
+  }
+}
+
+/** Load or generate an identity keypair, persisting both components. */
+export async function loadOrCreateIdentityKeyPair(storageKey: string): Promise<IdentityKeyPair> {
+  try {
+    const raw = globalThis.localStorage?.getItem(`${storageKey}-identity`)
+    if (raw) {
+      const d = JSON.parse(raw) as { ecdhPub: JsonWebKey; ecdhPriv: JsonWebKey; ecdsaPub: JsonWebKey; ecdsaPriv: JsonWebKey }
+      const ecdhPub   = await subtle().importKey('jwk', d.ecdhPub, { name: 'ECDH', namedCurve: 'P-256' }, true, [])
+      const ecdhPriv  = await subtle().importKey('jwk', d.ecdhPriv, { name: 'ECDH', namedCurve: 'P-256' }, true, ['deriveKey', 'deriveBits'])
+      const ecdsaPub  = await subtle().importKey('jwk', d.ecdsaPub, { name: 'ECDSA', namedCurve: 'P-256' }, true, ['verify'])
+      const ecdsaPriv = await subtle().importKey('jwk', d.ecdsaPriv, { name: 'ECDSA', namedCurve: 'P-256' }, true, ['sign'])
+      return {
+        ecdhKP: { publicKey: ecdhPub, privateKey: ecdhPriv },
+        ecdsaKP: { publicKey: ecdsaPub, privateKey: ecdsaPriv },
+        publicKeyB64:    await exportPublicKey(ecdhPub),
+        sigPublicKeyB64: await exportPublicKey(ecdsaPub),
+      }
+    }
+  } catch { /* generate fresh */ }
+  const ikp = await generateIdentityKeyPair()
+  try {
+    const ecdhPub   = await subtle().exportKey('jwk', ikp.ecdhKP.publicKey)
+    const ecdhPriv  = await subtle().exportKey('jwk', ikp.ecdhKP.privateKey)
+    const ecdsaPub  = await subtle().exportKey('jwk', ikp.ecdsaKP.publicKey)
+    const ecdsaPriv = await subtle().exportKey('jwk', ikp.ecdsaKP.privateKey)
+    globalThis.localStorage?.setItem(`${storageKey}-identity`, JSON.stringify({ ecdhPub, ecdhPriv, ecdsaPub, ecdsaPriv }))
+  } catch { /* non-persistent ok */ }
+  return ikp
+}
+
+export interface X3DHBundle {
+  identityKey:    string  // base64 raw P-256 public key
+  signedPrekey:   string  // base64 raw P-256 public key
+  signedPrekeyId: string  // opaque ID for key rotation tracking
+  signature:      string  // base64 ECDSA signature of SPK by IK
+  oneTimePrekey?: string  // base64 raw P-256 public key (optional)
+}
+
+/** X3DH sender side: derive a shared key from the recipient's prekey bundle.
+ *  Returns the shared AES-GCM key and the ephemeral public key to transmit. */
+export async function x3dhSend(
+  senderIK: KeyPair,
+  recipientBundle: X3DHBundle,
+): Promise<{ sharedKey: CryptoKey; ephemeralPublicKey: string }> {
+  const ek = await generateKeyPair()
+  const epkB64 = await exportPublicKey(ek.publicKey)
+
+  // Import recipient keys for DH.
+  const ik_r = await importPeerPublicKey(recipientBundle.identityKey)
+  const spk_r = await importPeerPublicKey(recipientBundle.signedPrekey)
+  const opk_r = recipientBundle.oneTimePrekey ? await importPeerPublicKey(recipientBundle.oneTimePrekey) : null
+
+  // Four DH computations per spec (three if no OPK).
+  const dh1 = await rawDH(senderIK.privateKey, spk_r)   // DH(IK_s, SPK_r)
+  const dh2 = await rawDH(ek.privateKey, ik_r)           // DH(EK, IK_r)
+  const dh3 = await rawDH(ek.privateKey, spk_r)          // DH(EK, SPK_r)
+  const dh4 = opk_r ? await rawDH(ek.privateKey, opk_r) : null  // DH(EK, OPK_r)
+
+  const ikm = concatBuffers(dh1, dh2, dh3, ...(dh4 ? [dh4] : []))
+  const sharedKey = await hkdfDeriveKey(ikm)
+
+  return { sharedKey, ephemeralPublicKey: epkB64 }
+}
+
+/** X3DH recipient side: rederive the shared key from an init message.
+ *  Returns the shared AES-GCM key. */
+export async function x3dhReceive(
+  recipientIK: KeyPair,
+  recipientSPK: KeyPair,
+  senderIKb64: string,
+  ephemeralKeyB64: string,
+  recipientOPK?: KeyPair,
+): Promise<CryptoKey> {
+  const ik_s = await importPeerPublicKey(senderIKb64)
+  const ek_s = await importPeerPublicKey(ephemeralKeyB64)
+
+  const dh1 = await rawDH(recipientSPK.privateKey, ik_s)       // DH(SPK_r, IK_s)
+  const dh2 = await rawDH(recipientIK.privateKey, ek_s)        // DH(IK_r, EK)
+  const dh3 = await rawDH(recipientSPK.privateKey, ek_s)       // DH(SPK_r, EK)
+  const dh4 = recipientOPK ? await rawDH(recipientOPK.privateKey, ek_s) : null
+
+  const ikm = concatBuffers(dh1, dh2, dh3, ...(dh4 ? [dh4] : []))
+  return hkdfDeriveKey(ikm)
+}
+
+async function rawDH(privateKey: CryptoKey, publicKey: CryptoKey): Promise<ArrayBuffer> {
+  return subtle().deriveBits({ name: 'ECDH', public: publicKey }, privateKey, 256)
+}
+
+function concatBuffers(...bufs: ArrayBuffer[]): ArrayBuffer {
+  const total = bufs.reduce((n, b) => n + b.byteLength, 0)
+  const out = new Uint8Array(total)
+  let offset = 0
+  for (const b of bufs) { out.set(new Uint8Array(b), offset); offset += b.byteLength }
+  return out.buffer
+}
+
+async function hkdfDeriveKey(ikm: ArrayBuffer): Promise<CryptoKey> {
+  const ikmKey = await subtle().importKey('raw', ikm, 'HKDF', false, ['deriveKey'])
+  return subtle().deriveKey(
+    { name: 'HKDF', hash: 'SHA-256', salt: new Uint8Array(32), info: new TextEncoder().encode('ObjectChat X3DH v1') },
+    ikmKey,
+    { name: 'AES-GCM', length: 256 },
+    false,
+    ['encrypt', 'decrypt'],
+  )
+}