@devchitchat/chat 0.0.0

package/src/services/PresenceService.js

@@ -0,0 +1,55 @@
+export class PresenceService {
+  constructor() {
+    this.userToConnections = new Map()
+    this.connectionToChannels = new Map()
+  }
+
+  addConnection(connectionId, userId) {
+    if (!this.userToConnections.has(userId)) this.userToConnections.set(userId, new Set())
+    this.userToConnections.get(userId).add(connectionId)
+    this.connectionToChannels.set(connectionId, new Set())
+  }
+
+  removeConnection(connectionId, userId) {
+    if (userId && this.userToConnections.has(userId)) {
+      const set = this.userToConnections.get(userId)
+      set.delete(connectionId)
+      if (set.size === 0) this.userToConnections.delete(userId)
+    }
+    this.connectionToChannels.delete(connectionId)
+  }
+
+  joinChannel(connectionId, channelId) {
+    this.connectionToChannels.get(connectionId)?.add(channelId)
+  }
+
+  leaveChannel(connectionId, channelId) {
+    this.connectionToChannels.get(connectionId)?.delete(channelId)
+  }
+
+  listOnlineUsers() {
+    return Array.from(this.userToConnections.entries()).map(([userId, connections]) => ({
+      user_id: userId,
+      online: connections.size > 0
+    }))
+  }
+
+  /** Return online users who are subscribed to at least one of the given channels. */
+  listOnlineUsersInChannels(channelIds) {
+    const channelSet = new Set(channelIds)
+    const result = []
+    for (const [userId, connections] of this.userToConnections) {
+      if (connections.size === 0) continue
+      let visible = false
+      for (const connectionId of connections) {
+        const channels = this.connectionToChannels.get(connectionId) ?? new Set()
+        for (const channelId of channels) {
+          if (channelSet.has(channelId)) { visible = true; break }
+        }
+        if (visible) break
+      }
+      if (visible) result.push({ user_id: userId, online: true })
+    }
+    return result
+  }
+}

package/src/services/ReactionService.js

@@ -0,0 +1,57 @@
+import { newId } from '../util/ids.js'
+import { ServiceError } from '../util/errors.js'
+import { validateEmoji } from '../core/reactions.js'
+
+const MAX_DISTINCT_EMOJI = 20
+
+export class ReactionService {
+  constructor({ reactionRepo, channelService, nowFn = () => Date.now() }) {
+    this.reactionRepo = reactionRepo
+    this.channelService = channelService
+    this.nowFn = nowFn
+  }
+
+  addReaction({ msgId, channelId, userId, emoji }) {
+    validateEmoji(emoji)
+    if (!this.channelService.isMember(channelId, userId)) {
+      throw new ServiceError('FORBIDDEN', 'Not a member')
+    }
+
+    // Enforce cap of 20 distinct emoji per message
+    const current = this.reactionRepo.listReactionsForMsgs({ msgIds: [msgId], requestingUserId: userId })
+    const existing = current.get(msgId) ?? []
+    const alreadyHasEmoji = existing.some(r => r.emoji === emoji)
+    if (!alreadyHasEmoji && existing.length >= MAX_DISTINCT_EMOJI) {
+      throw new ServiceError('BAD_REQUEST', 'Reaction limit reached')
+    }
+
+    const reactionId = newId('rx')
+    const ts = this.nowFn()
+    this.reactionRepo.upsertReaction({ reactionId, msgId, channelId, userId, emoji, ts })
+    return this.#summaryFor(msgId, userId)
+  }
+
+  removeReaction({ msgId, channelId, userId, emoji }) {
+    validateEmoji(emoji)
+    if (!this.channelService.isMember(channelId, userId)) {
+      throw new ServiceError('FORBIDDEN', 'Not a member')
+    }
+    this.reactionRepo.removeReaction({ msgId, userId, emoji })
+    return this.#summaryFor(msgId, userId)
+  }
+
+  /** Enriches a messages array with reactions — called by MessageService after list queries. */
+  enrichWithReactions({ messages, requestingUserId }) {
+    if (messages.length === 0) return messages
+    const map = this.reactionRepo.listReactionsForMsgs({
+      msgIds: messages.map(m => m.msg_id),
+      requestingUserId,
+    })
+    return messages.map(m => ({ ...m, reactions: map.get(m.msg_id) ?? [] }))
+  }
+
+  #summaryFor(msgId, requestingUserId) {
+    const map = this.reactionRepo.listReactionsForMsgs({ msgIds: [msgId], requestingUserId })
+    return map.get(msgId) ?? []
+  }
+}

package/src/services/SearchService.js

@@ -0,0 +1,21 @@
+export class SearchService {
+  constructor({ searchRepo }) {
+    this.searchRepo = searchRepo
+    this.useFts = searchRepo.isFtsEnabled()
+  }
+
+  indexMessage({ msg_id, channel_id, seq, user_id, ts, text }) {
+    this.searchRepo.indexMessage({ msg_id, channel_id, seq, user_id, ts, text })
+  }
+
+  removeMessage({ msgId }) {
+    this.searchRepo.removeMessage({ msgId })
+  }
+
+  searchMessages({ channelId, query, limit = 50 }) {
+    if (this.useFts) {
+      return this.searchRepo.searchFts({ channelId, query, limit })
+    }
+    return this.searchRepo.searchLike({ channelId, query, limit })
+  }
+}

package/src/services/SignalingService.js

@@ -0,0 +1,177 @@
+import { EventEmitter } from 'node:events'
+import { newId } from '../util/ids.js'
+import { ServiceError } from '../util/errors.js'
+
+export class SignalingService {
+  constructor({ signalingRepo, nowFn = () => Date.now() } = {}) {
+    this.nowFn = nowFn
+    this.signalingRepo = signalingRepo ?? null
+    this.calls = new Map()   // callId → { call_id, room_id, created_by_user_id, topology, peers: Map }
+    this.emitter = new EventEmitter()
+
+    if (this.signalingRepo) {
+      this.#loadActiveCallsFromDb()
+    }
+  }
+
+  // On startup: restore active calls into in-memory map so signaling can
+  // continue for calls that were in progress when the server last stopped.
+  // Peers reconnect via normal WS hello → channel.join → rtc.call_create flow.
+  #loadActiveCallsFromDb() {
+    const rows = this.signalingRepo.findActiveCalls()
+    for (const row of rows) {
+      this.calls.set(row.call_id, {
+        call_id: row.call_id,
+        room_id: row.channel_id,
+        created_by_user_id: row.created_by_user_id,
+        topology: row.topology,
+        peers: new Map()  // peers reconnect fresh; previous peer_ids are gone
+      })
+    }
+  }
+
+  onEvent(handler) {
+    this.emitter.on('event', handler)
+  }
+
+  createCall({ roomId, createdByUserId, topology = 'mesh' }) {
+    // Check in-memory first (fast path)
+    for (const call of this.calls.values()) {
+      if (call.room_id === roomId) {
+        return { call_id: call.call_id, room_id: call.room_id, topology: call.topology }
+      }
+    }
+
+    // Check DB (covers calls restored from a previous server run that may not
+    // have been re-hydrated into memory yet)
+    if (this.signalingRepo) {
+      const existing = this.signalingRepo.findActiveByChannel({ channelId: roomId })
+      if (existing) {
+        if (!this.calls.has(existing.call_id)) {
+          this.calls.set(existing.call_id, {
+            call_id: existing.call_id,
+            room_id: existing.channel_id,
+            created_by_user_id: existing.created_by_user_id,
+            topology: existing.topology,
+            peers: new Map()
+          })
+        }
+        return { call_id: existing.call_id, room_id: existing.channel_id, topology: existing.topology }
+      }
+    }
+
+    const callId = newId('call')
+    const now = Math.floor(this.nowFn() / 1000)
+    this.calls.set(callId, { call_id: callId, room_id: roomId, created_by_user_id: createdByUserId, topology, peers: new Map() })
+    this.signalingRepo?.insertCall({ callId, channelId: roomId, createdByUserId, topology, startedAt: now })
+    return { call_id: callId, room_id: roomId, topology }
+  }
+
+  joinCall({ callId, userId, displayName }) {
+    const call = this.calls.get(callId)
+    if (!call) throw new ServiceError('NOT_FOUND', 'Call not found')
+    const peerId = newId('peer')
+    const now = Math.floor(this.nowFn() / 1000)
+    call.peers.set(peerId, { peer_id: peerId, user_id: userId, display_name: displayName ?? null, joined_at: now })
+    this.signalingRepo?.insertParticipant({ callId, userId, peerId, joinedAt: now })
+    const peers = Array.from(call.peers.values()).map(p => ({ peer_id: p.peer_id, user_id: p.user_id, display_name: p.display_name }))
+    return { peerId, peers }
+  }
+
+  leaveCall({ callId, peerId }) {
+    const call = this.calls.get(callId)
+    if (!call) return { removed: false, peers: [], ended: false, room_id: null }
+    const now = Math.floor(this.nowFn() / 1000)
+    this.signalingRepo?.leaveParticipant({ callId, peerId, leftAt: now })
+    const removed = call.peers.delete(peerId)
+    const peers = Array.from(call.peers.values()).map(p => ({ peer_id: p.peer_id, user_id: p.user_id }))
+    const roomId = call.room_id
+    const ended = call.peers.size === 0
+    if (ended) {
+      this.calls.delete(callId)
+      this.signalingRepo?.endCall({ callId, endedAt: now })
+    }
+    return { removed, peers, ended, room_id: roomId }
+  }
+
+  endCall({ callId }) {
+    const call = this.calls.get(callId)
+    if (!call) return null
+    const now = Math.floor(this.nowFn() / 1000)
+    this.calls.delete(callId)
+    this.signalingRepo?.endCall({ callId, endedAt: now })
+    return { call_id: call.call_id, room_id: call.room_id, peers: Array.from(call.peers.values()).map(p => ({ peer_id: p.peer_id, user_id: p.user_id })) }
+  }
+
+  /**
+   * Join a call, handling two state machine cases so the transport handler
+   * does not need to make these decisions:
+   *
+   *   - already_in_call: peer is already in this exact call — idempotent, no change
+   *   - switched:        peer was in a different call — leave it first, then join
+   *   - joined:          peer had no prior call — plain join
+   *
+   * @returns {{ status, peerId, peers, previousLeft? }}
+   *   previousLeft is only present when status === 'switched':
+   *   { call_id, room_id, peerId, removed, ended }
+   */
+  joinOrSwitch({ callId, userId, displayName, currentPeerId, currentCallId }) {
+    // Already in this exact call — return current state, no side effects
+    if (currentPeerId && currentCallId === callId) {
+      const call = this.calls.get(callId)
+      if (call?.peers.has(currentPeerId)) {
+        const peers = Array.from(call.peers.values()).map(p => ({ peer_id: p.peer_id, user_id: p.user_id }))
+        return { status: 'already_in_call', peerId: currentPeerId, peers }
+      }
+    }
+
+    // In a different call — leave it first
+    let previousLeft
+    if (currentPeerId && currentCallId && currentCallId !== callId) {
+      const leaveResult = this.leaveCall({ callId: currentCallId, peerId: currentPeerId })
+      previousLeft = {
+        call_id: currentCallId,
+        room_id:  leaveResult.room_id,
+        peerId:   currentPeerId,
+        removed:  leaveResult.removed,
+        ended:    leaveResult.ended,
+      }
+    }
+
+    const result = this.joinCall({ callId, userId, displayName })
+    return {
+      status: previousLeft ? 'switched' : 'joined',
+      peerId: result.peerId,
+      peers:  result.peers,
+      ...(previousLeft && { previousLeft }),
+    }
+  }
+
+  getCall(callId) { return this.calls.get(callId) }
+
+  getActiveCallForChannel(channelId) {
+    for (const call of this.calls.values()) {
+      if (call.room_id === channelId) return call
+    }
+    return null
+  }
+
+  routeOffer({ callId, fromPeerId, toPeerId, sdp }) {
+    this.#route({ callId, fromPeerId, toPeerId, payload: { sdp }, type: 'rtc.offer_event' })
+  }
+
+  routeAnswer({ callId, fromPeerId, toPeerId, sdp }) {
+    this.#route({ callId, fromPeerId, toPeerId, payload: { sdp }, type: 'rtc.answer_event' })
+  }
+
+  routeIce({ callId, fromPeerId, toPeerId, candidate }) {
+    this.#route({ callId, fromPeerId, toPeerId, payload: { candidate }, type: 'rtc.ice_event' })
+  }
+
+  #route({ callId, fromPeerId, toPeerId, payload, type }) {
+    const call = this.calls.get(callId)
+    if (!call) throw new ServiceError('NOT_FOUND', 'Call not found')
+    if (!call.peers.has(fromPeerId) || !call.peers.has(toPeerId)) throw new ServiceError('BAD_REQUEST', 'Peer not in call')
+    this.emitter.emit('event', { t: type, body: { call_id: callId, from_peer_id: fromPeerId, to_peer_id: toPeerId, ...payload } })
+  }
+}

package/src/services/UploadService.js

@@ -0,0 +1,111 @@
+import { newId } from '../util/ids.js'
+import { randomToken } from '../util/crypto.js'
+import { validateMimeType, isForcedDownload } from '../core/uploads.js'
+import { ServiceError } from '../util/errors.js'
+
+const DEFAULT_MAX_BYTES = Number(process.env.MAX_UPLOAD_BYTES ?? 26_214_400) // 25 MB
+
+export class UploadService {
+  constructor({ uploadRepo, fileStore, channelService, nowFn = () => Date.now(), maxBytes = DEFAULT_MAX_BYTES }) {
+    this.uploadRepo = uploadRepo
+    this.fileStore = fileStore
+    this.channelService = channelService
+    this.nowFn = nowFn
+    this.maxBytes = maxBytes
+  }
+
+  /**
+   * Validate, store, and record an uploaded file.
+   *
+   * @param {{ userId, channelId, userRoles, filename, stream, sizeBytes, magicBuf }} params
+   *   magicBuf  — first ≥16 bytes of the file (already read for MIME detection)
+   *   stream    — ReadableStream of the full file (including the bytes in magicBuf)
+   * @returns {{ upload_id, url, original_name, mime_type, size_bytes }}
+   */
+  async upload({ userId, channelId, userRoles, filename, stream, sizeBytes, magicBuf }) {
+    if (!this.channelService.isMember(channelId, userId)) {
+      throw new ServiceError('FORBIDDEN', 'Not a member of channel')
+    }
+
+    if (sizeBytes > this.maxBytes) {
+      throw new ServiceError('BAD_REQUEST', `File exceeds maximum size of ${this.maxBytes} bytes`)
+    }
+
+    const mimeType = validateMimeType(magicBuf, filename) // throws UNSUPPORTED_TYPE with code
+
+    const uploadId = newId('up')
+    const storedName = randomToken(24) // opaque — never derived from filename
+    const now = this.nowFn()
+
+    await this.fileStore.write({ uploadId, storedName, stream })
+
+    this.uploadRepo.insert({
+      uploadId,
+      uploaderUserId: userId,
+      channelId,
+      originalName: filename,
+      storedName,
+      mimeType,
+      sizeBytes,
+      now,
+    })
+
+    const url = `/uploads/${uploadId}/${encodeURIComponent(filename)}`
+    return { upload_id: uploadId, url, original_name: filename, mime_type: mimeType, size_bytes: sizeBytes }
+  }
+
+  /**
+   * Link a list of upload_ids to a sent message.
+   * Validates that each upload belongs to the channel and was uploaded by this user.
+   */
+  linkToMessage({ uploadIds, msgId, userId, channelId }) {
+    for (const uploadId of uploadIds) {
+      const row = this.uploadRepo.findById({ uploadId })
+      if (!row) throw new ServiceError('NOT_FOUND', `Upload not found: ${uploadId}`)
+      if (row.uploader_user_id !== userId) throw new ServiceError('FORBIDDEN', 'Upload belongs to another user')
+      if (row.channel_id !== channelId) throw new ServiceError('FORBIDDEN', 'Upload is not in this channel')
+      this.uploadRepo.linkToMessage({ uploadId, msgId })
+    }
+  }
+
+  getUpload({ uploadId }) {
+    return this.uploadRepo.findById({ uploadId })
+  }
+
+  /**
+   * Validate access and return a stream plus metadata for serving a file.
+   */
+  async streamFile({ uploadId, requestingUserId, userRoles }) {
+    const row = this.uploadRepo.findById({ uploadId })
+    if (!row) throw new ServiceError('NOT_FOUND', 'File not found')
+
+    if (!this.channelService.canAccessChannel(row.channel_id, requestingUserId, userRoles)) {
+      throw new ServiceError('FORBIDDEN', 'Access denied')
+    }
+
+    const stream = await this.fileStore.read({ uploadId, storedName: row.stored_name })
+    const contentDisposition = isForcedDownload(row.mime_type)
+      ? `attachment; filename="${encodeURIComponent(row.original_name)}"`
+      : `inline; filename="${encodeURIComponent(row.original_name)}"`
+
+    return {
+      stream,
+      mimeType: row.mime_type,
+      originalName: row.original_name,
+      contentDisposition,
+    }
+  }
+
+  /**
+   * Delete orphan uploads (msg_id IS NULL) older than olderThanMs milliseconds.
+   */
+  async deleteOrphans({ olderThanMs }) {
+    const threshold = this.nowFn() - olderThanMs
+    const orphans = this.uploadRepo.findOrphansOlderThan({ thresholdTs: threshold })
+    for (const row of orphans) {
+      await this.fileStore.delete({ uploadId: row.upload_id, storedName: row.stored_name })
+      this.uploadRepo.delete({ uploadId: row.upload_id })
+    }
+    return orphans.length
+  }
+}

package/src/services/UserSettingsService.js

@@ -0,0 +1,30 @@
+const ALLOWED_KEYS = new Set(['last_channel_id', 'mobile_chat_open'])
+
+export class UserSettingsService {
+  constructor({ userSettingsRepo }) {
+    this.userSettingsRepo = userSettingsRepo
+  }
+
+  // Returns { settings, updated_at }
+  getSettings(userId) {
+    const row = this.userSettingsRepo.findByUserId({ userId })
+    if (!row) return { settings: {}, updated_at: 0 }
+    try {
+      return { settings: JSON.parse(row.settings_json), updated_at: row.updated_at }
+    } catch {
+      return { settings: {}, updated_at: 0 }
+    }
+  }
+
+  // Merges patch into stored settings. Only allow-listed keys are persisted.
+  // updatedAt is a Unix timestamp (seconds); last-write-wins enforced by the repo.
+  putSettings(userId, patch, updatedAt) {
+    const existing = this.getSettings(userId)
+    const merged = { ...existing.settings }
+    for (const [k, v] of Object.entries(patch)) {
+      if (ALLOWED_KEYS.has(k)) merged[k] = v
+    }
+    this.userSettingsRepo.upsert({ userId, settingsJson: JSON.stringify(merged), updatedAt })
+    return this.getSettings(userId)
+  }
+}

package/src/services/WebPushService.js

@@ -0,0 +1,217 @@
+/**
+ * WebPushService — sends Web Push notifications without any third-party library.
+ *
+ * Implements:
+ *   • VAPID authentication (RFC 8292) — ES256 JWT signed with the application
+ *     server's ECDSA P-256 private key.
+ *   • Payload encryption (RFC 8291 / RFC 8188 aes128gcm content-encoding) —
+ *     ECDH key agreement, HKDF key derivation, AES-128-GCM encryption, all via
+ *     the standard Web Crypto API (crypto.subtle), available in Bun natively.
+ *
+ * Required env vars (set via `bun scripts/generate-vapid.js`):
+ *   VAPID_PUBLIC_KEY   base64url-encoded raw P-256 public key (65 bytes)
+ *   VAPID_PRIVATE_KEY  base64url-encoded P-256 private scalar d (32 bytes)
+ *   VAPID_SUBJECT      contact URI, e.g. mailto:admin@example.com
+ */
+
+// ── Helpers ─────────────────────────────────────────────────────────────────
+
+function b64url_encode(bytes) {
+  let bin = ''
+  for (let i = 0; i < bytes.length; i++) bin += String.fromCharCode(bytes[i])
+  return btoa(bin).replace(/\+/g, '-').replace(/\//g, '_').replace(/=/g, '')
+}
+
+function b64url_decode(str) {
+  const padded = str + '==='.slice((str.length + 3) % 4)
+  return Uint8Array.from(atob(padded.replace(/-/g, '+').replace(/_/g, '/')), c => c.charCodeAt(0))
+}
+
+function concat(arrays) {
+  const total = arrays.reduce((n, a) => n + a.length, 0)
+  const out = new Uint8Array(total)
+  let off = 0
+  for (const a of arrays) { out.set(a, off); off += a.length }
+  return out
+}
+
+// ── Service ──────────────────────────────────────────────────────────────────
+
+export class WebPushService {
+  #publicKey   // base64url string — raw uncompressed P-256 (65 bytes)
+  #privateKey  // base64url string — P-256 scalar d (32 bytes)
+  #subject     // mailto: or https: contact URI
+  #pushRepo
+
+  constructor({ vapidPublicKey, vapidPrivateKey, vapidSubject, pushRepo }) {
+    this.#publicKey  = vapidPublicKey  ?? null
+    this.#privateKey = vapidPrivateKey ?? null
+    this.#subject    = vapidSubject    ?? null
+    this.#pushRepo   = pushRepo
+  }
+
+  isConfigured() {
+    return !!(this.#publicKey && this.#privateKey && this.#subject)
+  }
+
+  /** Send a push notification to every registered subscription for userId. */
+  async sendToUser({ userId, title, body, url, channelId }) {
+    if (!this.isConfigured()) return
+    const subs = this.#pushRepo.getSubscriptionsForUser(userId)
+    if (subs.length === 0) return
+    await Promise.allSettled(
+      subs.map(sub => this.#sendOne(sub, { title, body, url, channel_id: channelId }))
+    )
+  }
+
+  // ── Private ─────────────────────────────────────────────────────────────────
+
+  async #sendOne(sub, payload) {
+    let encrypted
+    try {
+      encrypted = await this.#encrypt(sub, JSON.stringify(payload))
+    } catch (err) {
+      // Encryption failure is a bug — re-throw so the caller can log it
+      throw new Error(`WebPush encrypt failed: ${err?.message}`)
+    }
+
+    const audience = new URL(sub.endpoint).origin
+    const jwt = await this.#buildJwt(audience)
+
+    const res = await fetch(sub.endpoint, {
+      method: 'POST',
+      headers: {
+        Authorization:      `vapid t=${jwt},k=${this.#publicKey}`,
+        'Content-Type':     'application/octet-stream',
+        'Content-Encoding': 'aes128gcm',
+        TTL:                '86400',
+      },
+      body: encrypted,
+    })
+
+    if (res.status === 404 || res.status === 410) {
+      // Subscription has expired or was removed — clean up
+      this.#pushRepo.removeSubscription(sub.endpoint)
+    }
+  }
+
+  /**
+   * Build an ES256 VAPID JWT for the given push service origin.
+   *
+   * JWT header: { typ: "JWT", alg: "ES256" }
+   * JWT claims: { aud, exp, sub }
+   * Signature:  ECDSA P-256 / SHA-256 (IEEE P1363 format — raw r||s, 64 bytes)
+   */
+  async #buildJwt(audience) {
+    const enc = new TextEncoder()
+
+    // Reconstruct JWK from raw public key bytes + private scalar d
+    const pub = b64url_decode(this.#publicKey) // 65-byte uncompressed: 0x04 || x(32) || y(32)
+    const jwk = {
+      kty: 'EC', crv: 'P-256',
+      x:   b64url_encode(pub.slice(1, 33)),
+      y:   b64url_encode(pub.slice(33, 65)),
+      d:   this.#privateKey,
+      ext: true,
+    }
+    const sigKey = await crypto.subtle.importKey(
+      'jwk', jwk,
+      { name: 'ECDSA', namedCurve: 'P-256' },
+      false, ['sign']
+    )
+
+    const header  = b64url_encode(enc.encode(JSON.stringify({ typ: 'JWT', alg: 'ES256' })))
+    const claims  = b64url_encode(enc.encode(JSON.stringify({
+      aud: audience,
+      exp: Math.floor(Date.now() / 1000) + 43_200, // 12 h
+      sub: this.#subject,
+    })))
+
+    const sigInput = enc.encode(`${header}.${claims}`)
+    const sigRaw   = new Uint8Array(
+      await crypto.subtle.sign({ name: 'ECDSA', hash: 'SHA-256' }, sigKey, sigInput)
+    ) // 64 bytes: r(32) || s(32) in IEEE P1363 format — correct for JWT ES256
+
+    return `${header}.${claims}.${b64url_encode(sigRaw)}`
+  }
+
+  /**
+   * Encrypt a plaintext string for delivery to a push subscription.
+   *
+   * Follows RFC 8291 (Message Encryption for Web Push) which layers on top of
+   * RFC 8188 (Encrypted Content-Encoding for HTTP, aes128gcm variant).
+   *
+   * Key derivation chain:
+   *   ecdh_secret = ECDH(as_private_ephemeral, ua_public)
+   *   IKM         = HKDF(salt=auth, IKM=ecdh_secret, info="WebPush: info\0"||ua_pub||as_pub, 32)
+   *   CEK         = HKDF(salt=random_salt, IKM=IKM, info="Content-Encoding: aes128gcm\0", 16)
+   *   NONCE       = HKDF(salt=random_salt, IKM=IKM, info="Content-Encoding: nonce\0",      12)
+   *
+   * Ciphertext format (RFC 8188):
+   *   random_salt(16) || rs(4 BE) || keyid_len(1) || as_pub(65) || AES-128-GCM(padded_plaintext)
+   */
+  async #encrypt(sub, plaintext) {
+    const enc = new TextEncoder()
+
+    // ── Subscription keys ────────────────────────────────────────────────────
+    const ua_public   = b64url_decode(sub.p256dh)  // 65-byte uncompressed P-256 point
+    const auth_secret = b64url_decode(sub.auth)    // 16 bytes
+
+    // ── Ephemeral application-server key pair ────────────────────────────────
+    const as_kp = await crypto.subtle.generateKey(
+      { name: 'ECDH', namedCurve: 'P-256' }, true, ['deriveBits']
+    )
+    const as_public_raw = new Uint8Array(await crypto.subtle.exportKey('raw', as_kp.publicKey)) // 65 bytes
+
+    // ── ECDH shared secret ───────────────────────────────────────────────────
+    const ua_key = await crypto.subtle.importKey(
+      'raw', ua_public, { name: 'ECDH', namedCurve: 'P-256' }, false, []
+    )
+    const ecdh_secret = new Uint8Array(
+      await crypto.subtle.deriveBits({ name: 'ECDH', public: ua_key }, as_kp.privateKey, 256)
+    )
+
+    // ── RFC 8291: derive IKM ─────────────────────────────────────────────────
+    // key_info = "WebPush: info\0" || ua_public || as_public
+    const key_info = concat([enc.encode('WebPush: info\0'), ua_public, as_public_raw])
+    const ecdh_key = await crypto.subtle.importKey('raw', ecdh_secret, 'HKDF', false, ['deriveBits'])
+    const ikm = new Uint8Array(await crypto.subtle.deriveBits(
+      { name: 'HKDF', hash: 'SHA-256', salt: auth_secret, info: key_info },
+      ecdh_key, 256
+    ))
+
+    // ── RFC 8188 aes128gcm: derive CEK and NONCE ─────────────────────────────
+    const random_salt = crypto.getRandomValues(new Uint8Array(16))
+    const ikm_key = await crypto.subtle.importKey('raw', ikm, 'HKDF', false, ['deriveBits'])
+    const [cek_bits, nonce_bits] = await Promise.all([
+      crypto.subtle.deriveBits(
+        { name: 'HKDF', hash: 'SHA-256', salt: random_salt, info: enc.encode('Content-Encoding: aes128gcm\0') },
+        ikm_key, 128
+      ),
+      crypto.subtle.deriveBits(
+        { name: 'HKDF', hash: 'SHA-256', salt: random_salt, info: enc.encode('Content-Encoding: nonce\0') },
+        ikm_key, 96
+      ),
+    ])
+    const cek   = new Uint8Array(cek_bits)
+    const nonce = new Uint8Array(nonce_bits)
+
+    // ── Encrypt with AES-128-GCM ─────────────────────────────────────────────
+    // Pad with delimiter byte 0x02 (marks the last record in aes128gcm)
+    const padded = concat([enc.encode(plaintext), new Uint8Array([2])])
+    const aes_key = await crypto.subtle.importKey('raw', cek, { name: 'AES-GCM' }, false, ['encrypt'])
+    const ciphertext = new Uint8Array(
+      await crypto.subtle.encrypt({ name: 'AES-GCM', iv: nonce }, aes_key, padded)
+    )
+
+    // ── RFC 8188 content-encoding header ─────────────────────────────────────
+    // salt(16) || rs(4 big-endian) || keyid_len(1) || keyid(65)
+    const hdr = new Uint8Array(16 + 4 + 1 + as_public_raw.length)
+    hdr.set(random_salt, 0)
+    new DataView(hdr.buffer).setUint32(16, 4096, false) // record size = 4096
+    hdr[20] = as_public_raw.length                      // keyid length = 65
+    hdr.set(as_public_raw, 21)
+
+    return concat([hdr, ciphertext])
+  }
+}