Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

50.9 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// bento-sync online transport — E2EE WebSocket to the blind relay
// (server/sync-worker). Every session frame is AES-GCM encrypted with the
// room key from doc.collab.key; the relay sees ciphertext, fan-out routing,
// and nothing else. Auth is possession-proof: ?tok= is a hash of the key.
//
// Reconnects with backoff; frames queue while disconnected; op frames are
// persisted server-side (envelope {p:1}) and replayed to joiners from their
// last acked seq, with client-produced encrypted snapshots capping replay
// length. See docs/collab-design.md.

import type { Op, SyncStateJSON } from './crdt.ts'
import type { Frame, HostStore, RefusalCode, SyncDoc, SyncSession, Transport } from './session.ts'
import { lsGet, lsSet } from '../storage.ts'
import { docStore, getJSON, setJSON } from '../docstore.ts'
import { carryThroughRotation } from '../docfields.ts'
import { offlineEnabled } from '../update.ts'
// Every request in the app goes through the one chokepoint (kernel/src/net.ts)
// so the offline switch cannot be forgotten — see GHSA-5c3x-xqp6-g94r.
import { netWebSocket, SandboxedError, sharedStorageOrigin } from '../net.ts'
import { appConfig } from '../app.ts'

/** the app's store, structurally — see session.ts HostStore */
type Store = HostStore

export const DEFAULT_SYNC_HOST = 'wss://sync.bento.page'
const SNAP_EVERY = 200 // ops between encrypted snapshot uploads

const b64u = {
  enc(bytes: Uint8Array): string {
    let s = ''
    for (const b of bytes) s += String.fromCharCode(b)
    return btoa(s).replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '')
  },
  dec(s: string): Uint8Array {
    const b = atob(s.replace(/-/g, '+').replace(/_/g, '/'))
    const out = new Uint8Array(b.length)
    for (let i = 0; i < b.length; i++) out[i] = b.charCodeAt(i)
    return out
  },
}

export function mintRoomKey(): string {
  const bytes = new Uint8Array(32)
  crypto.getRandomValues(bytes)
  return b64u.enc(bytes)
}

const EC = { name: 'ECDSA', namedCurve: 'P-256' } as const
const SIGN_ALG = { name: 'ECDSA', hash: 'SHA-256' } as const

/** Import a writer private key (PKCS#8, base64url) for signing op frames. */
export async function importSignKey(privB64: string): Promise<CryptoKey> {
  return crypto.subtle.importKey('pkcs8', b64u.dec(privB64) as BufferSource, EC, false, ['sign'])
}

/** ECDSA-P256/SHA-256 signature over `${i}.${d}`, base64url. */
export async function signFrame(key: CryptoKey, i: string, d: string): Promise<string> {
  const sig = await crypto.subtle.sign(SIGN_ALG, key, new TextEncoder().encode(`${i}.${d}`))
  return b64u.enc(new Uint8Array(sig))
}

/** Sign an arbitrary string with an already-imported signing key. */
export async function signWith(key: CryptoKey, text: string): Promise<string> {
  const sig = await crypto.subtle.sign(SIGN_ALG, key, new TextEncoder().encode(text))
  return b64u.enc(new Uint8Array(sig))
}

/** Sign an arbitrary string with a b64url PKCS#8 private key (cert chains). */
export async function signText(privB64: string, text: string): Promise<string> {
  return signWith(await importSignKey(privB64), text)
}

async function mintKeypair(): Promise<{ pub: string; priv: string }> {
  const kp = (await crypto.subtle.generateKey(EC, true, ['sign', 'verify'])) as CryptoKeyPair
  return {
    pub: b64u.enc(new Uint8Array(await crypto.subtle.exportKey('raw', kp.publicKey))),
    priv: b64u.enc(new Uint8Array(await crypto.subtle.exportKey('pkcs8', kp.privateKey))),
  }
}

export type CollabInvite = { pub: string; priv: string; role: 'writer' | 'commenter' | 'audience'; exp?: number; sig: string }

/** Owner-signed invite: a delegation keypair whose private half rides in the
 *  shared copy. Chain: owner signs `inv.${pub}.${role}.${exp||0}`; a joining
 *  device later signs its own pubkey with the invite key (`dlg.${memberPub}`).
 *  The relay verifies both signatures and never sees private material — so a
 *  blind relay still cannot certify its own key. */
export async function mintInvite(ownerPrivB64: string, role: 'writer' | 'commenter' | 'audience' = 'writer', exp = 0): Promise<CollabInvite> {
  const kp = await mintKeypair()
  const sig = await signText(ownerPrivB64, `inv.${kp.pub}.${role}.${exp}`)
  return { pub: kp.pub, priv: kp.priv, role, ...(exp ? { exp } : {}), sig }
}

/** Member identities this page has resolved AND the store holds, by docId (one
 *  host round trip per document per page, not one per connect). */
const memberCache = new Map<string, { pub: string; priv: string }>()
/** Identities the host has not yet stored (it refused, or did not answer in
 *  time): used for this page, offered to the host again on the next call. */
const unstored = new Map<string, { pub: string; priv: string }>()

/** This device's member pubkey for a doc, as resolved in this page. The
 *  presence beat reads it synchronously. */
export function cachedMemberPub(docId: string): string | undefined {
  return (memberCache.get(docId) ?? unstored.get(docId))?.pub
}

/** This device's member identity for a doc — minted once, NEVER in the file
 *  (the file travels; a device key must not).
 *
 *  Under a host with a per-document store (docstore.ts), the PRIVATE key lives
 *  there, out of the storage origin every local file shares. localStorage keeps
 *  only the PUBLIC key under the same name, because the apps' People views read
 *  `bento-member-<docId>`.pub to recognise this device — and a pubkey is public
 *  anyway. The first time, a full key this browser already holds is ADOPTED
 *  (the device keeps its People entry) and its private half removed from that
 *  origin.
 *
 *  While that host is present NOTHING falls back to the shared origin:
 *  - a READ the host can't answer THROWS — it neither mints a key (that would
 *    change this device's identity) nor writes one; the caller retries;
 *  - a WRITE the host refuses or doesn't answer keeps the identity for this
 *    page and offers it to the host again on the next call; the private key is
 *    never written to localStorage.
 *  Without such a host, the whole key lives in localStorage as before. */
export async function deviceIdentity(docId: string): Promise<{ pub: string; priv: string }> {
  const hit = memberCache.get(docId)
  if (hit) return hit
  const k = `bento-member-${docId}`
  /** a FULL identity from localStorage — a pub-only mirror is not one */
  const saved = (): { pub: string; priv: string } | null => {
    try {
      const s = lsGet(k)
      const v = s ? JSON.parse(s) as { pub?: string; priv?: string } : null
      return v?.pub && v.priv ? { pub: v.pub, priv: v.priv } : null
    } catch { return null }
  }
  const ds = docStore()
  if (ds) {
    const kept = unstored.get(docId)
    let held: { docId?: string; pub?: string; priv?: string } | null
    try {
      held = await getJSON(ds, 'memberkey')
    } catch (e) {
      // can't read the host: an identity already in use this page carries on;
      // otherwise fail this attempt — never mint or write while blind
      if (kept) return kept
      throw e
    }
    // the entry is per FILE, so check it is this document's before using it
    if (held?.docId === docId && held.pub && held.priv) {
      const id = { pub: held.pub, priv: held.priv }
      unstored.delete(docId)
      memberCache.set(docId, id)
      lsSet(k, JSON.stringify({ pub: id.pub }))
      return id
    }
    const id = kept ?? saved() ?? await mintKeypair()
    if (await setJSON(ds, 'memberkey', { docId, pub: id.pub, priv: id.priv }) === 'stored') {
      unstored.delete(docId)
      memberCache.set(docId, id)
      lsSet(k, JSON.stringify({ pub: id.pub })) // the private half leaves this origin
      return id
    }
    unstored.set(docId, id) // this page only; the host is offered it again next time
    return id
  }
  const prior = saved()
  if (prior) { memberCache.set(docId, prior); return prior }
  const id = await mintKeypair()
  lsSet(k, JSON.stringify(id))
  memberCache.set(docId, id)
  return id
}

/** Auth material for the relay connection. Exactly one shape applies:
 *  direct (owner or legacy shared-writer key) or chain (member via invite). */
export type AuthSpec =
  | { kind: 'direct'; pub: string; priv?: string }
  | { kind: 'chain'; owner: string; invite: CollabInvite; docId: string }

export type CollabCreds = {
  room: string
  key: string
  on: boolean
  v: number
  owner: string
  ownerPriv: string
  role: 'writer'
}

/**
 * Fresh collaboration credentials, minted at DOCUMENT CREATION and LIVE by
 * default (on:true): the moment identity and keys exist, any copy of the
 * file joins the same room — "send first" needs no ceremony. "Stop sharing"
 * in the Live popover turns it off; Offline mode hard-blocks regardless.
 *
 * Signed-writes scheme (v0.9.18+): the room id is the COMMITMENT to a fresh
 * ECDSA writer pubkey — `w` + base64url(SHA-256(writerPubRaw)) — so the relay
 * can pin the writer key trustlessly (a viewer holds the room id but can't
 * substitute their own key). `key` is the separate symmetric READ capability.
 * Async because keypair generation is. See docs/collab-design.md.
 */
export async function mintCollab(): Promise<CollabCreds> {
  // v2 (fine-grained): the room id commits to the OWNER's pubkey. The creator's
  // copy holds ownerPriv; shared copies carry owner-signed INVITES instead, and
  // each joining device mints its own member key (see mintInvite/deviceIdentity).
  const kp = await mintKeypair()
  const commit = new Uint8Array(await crypto.subtle.digest('SHA-256', b64u.dec(kp.pub) as BufferSource))
  return {
    room: `${syncHost()}/d/w${b64u.enc(commit)}`,
    key: mintRoomKey(),
    on: true,
    v: 2,
    owner: kp.pub,
    ownerPriv: kp.priv,
    role: 'writer',
  }
}

/** The relay host: the localStorage dev override (e.g. ws://localhost:8787),
 *  else the host the app configured (a fork running its own relay), else the
 *  platform default. Rigs that never call configureApp() get the default.
 *
 *  A file's collab capability is complete only WITHIN the publisher that
 *  minted it. `CollabCreds` carries the room and the key and no host, which
 *  was total while every build had one relay; with per-publisher relays, the
 *  same file opened in another publisher's build joins that publisher's
 *  relay, where the room id is a valid commitment and is simply created
 *  fresh. Both sides are live, on two relays, and never meet — a silent
 *  split, not a leak (the relay is blind and the payloads are E2EE). This is
 *  accepted and consistent with the update channel refusing another
 *  publisher's manifests: a fork is its own trust domain. Cross-publisher
 *  collaboration would need the host stamped into `collab` — an additive
 *  format change, and its own serialized kernel PR. */
export function syncHost(): string {
  let configured: string | undefined
  try { configured = appConfig().syncHost } catch { /* not configured: platform default */ }
  try {
    // The localStorage dev override is honoured only from a real, isolated
    // origin: on file:// (shared storage) a malicious local deck could plant it
    // and steer this deck's collab at a hostile relay.
    const devOverride = sharedStorageOrigin() ? '' : lsGet('bento-sync-url')
    return devOverride || configured || DEFAULT_SYNC_HOST
  } catch {
    return configured || DEFAULT_SYNC_HOST
  }
}

export type OnlineStatus = 'connecting' | 'open' | 'closed'

/** A frame written to (or parked for) the relay. `ops` is set for persisted op
 *  batches — the only frames the relay acks, and the only ones whose refusal
 *  has to reach the session (an unsendable op must leave the resend log). */
type Outbound = { id: string; text: string; ops: Op[] | null; bytes: number; tries: number }

let frameSeq = 0
/** Short opaque per-frame id. Emitted FIRST in the envelope so the relay can
 *  recover it with a bounded regex from an OVERSIZE frame — one it refuses
 *  before parsing, since parsing an attacker-sized string is a CPU abuse
 *  vector. Relay contract: docs/relay-design.md. */
const nextFrameId = (): string => `f${(++frameSeq).toString(36)}${Math.random().toString(36).slice(2, 6)}`

/** `{ctl:'refused'}` from the relay. Modern relays echo our frame id (`k`),
 *  which is exact; older ones don't, and then the sizes are the only evidence
 *  of WHICH frame it names (see matchRefused). */
type RefusedEnv = {
  code?: string
  /** our frame id, echoed back — authoritative when present */
  k?: string
  /** too-large: the relay's ceiling and the frame length it measured */
  max?: number
  got?: number
  /** storage-failed: i.length + d.length of the frame it tried to store */
  bytes?: number
  /** rate-limited: how long until the socket's byte window rolls over */
  retryInMs?: number
}

export class OnlineTransport implements Transport {
  readonly kind = 'online'
  status: OnlineStatus = 'connecting'
  onStatus: ((s: OnlineStatus) => void) | null = null
  private ws: WebSocket | null = null
  private key: CryptoKey | null = null
  /** writer signing key — null for readers (they can decrypt but not author). */
  private signKey: CryptoKey | null = null
  private queue: Outbound[] = []
  /** persisted frames written but not yet acked. The relay handles one
   *  socket's frames in order and acks every stored one, so the head of this
   *  list is the frame a `refused` reply is talking about. Purely a
   *  correlation window — delivery is still guaranteed by the log + `need`. */
  private awaitingAck: Outbound[] = []
  /** rate-limit backoff deadline: sending into a refusing relay only burns the
   *  next window too, so frames park until it passes */
  private paused = false
  private pauseTimer: ReturnType<typeof setTimeout> | null = null
  private lastLimitNotice = 0
  private static readonly ACK_WINDOW = 64
  private static readonly MAX_RETRIES = 4
  private closed = false
  private backoff = 800
  private url = ''
  // heartbeat: ping the relay (which auto-responds "pong" without waking the DO)
  // so idle connections stay alive; if a pong doesn't come back before the next
  // tick, treat the socket as dead and reconnect instead of waiting for a TCP
  // timeout that can take minutes.
  private pingTimer: ReturnType<typeof setInterval> | null = null
  private awaitingPong = false
  private static readonly PING_MS = 25_000
  /** the key THIS socket signs with (owner / legacy writer / device) — used to
   *  recognise our own revocation and to attribute presence */
  myPub: string | null = null
  /**
   * Replay bookmark — MEMORY ONLY, deliberately: it is valid only alongside
   * the in-memory CRDT state it was earned with. A fresh join replays from
   * the room's snapshot (or 0); reconnects of THIS session resume from here.
   */
  private seq = 0

  constructor(
    room: string,
    private keyB64: string,
    docId: string,
    private onFrame: (f: Frame) => void,
    private hooks: {
      onSnap: (doc: SyncDoc, state: SyncStateJSON) => void
      getSnapshot: () => { doc: SyncDoc; state: SyncStateJSON }
      onOpen: () => void
      /** replay done: (actor,seq) pairs the room holds; return true to upload a snapshot */
      onReady: (seen: Set<string>, seq: number) => boolean
      /** the relay refused a frame; `ops` are the ones it will never accept
       *  (null when the refusal couldn't be pinned to a frame we sent). `opts.snapshot`
       *  = the refused frame was a whole-deck snapshot (no op of ours matched it). */
      onRefused?: (code: RefusalCode, ops: Op[] | null, opts?: { snapshot?: boolean }) => void
      // ——— broadcast reception (audience side, and the presenter's own
      // checkpoint/count signals). All optional: a session with no show wires
      // none of them and nothing below fires. ———
      /** an aud op batch (audience): apply through the reader path */
      onShowOps?: (ops: Op[]) => void
      /** an aud snapshot (audience): the whole show document under Ke */
      onShowSnap?: (doc: SyncDoc, state: SyncStateJSON) => void
      /** a control verb (audience): nav/black/laser with its decrypted payload */
      onShowVerb?: (kind: 'nav' | 'black' | 'laser', payload: unknown) => void
      /** the relay asks the presenter to checkpoint (soft cap or show-full) */
      onShowCheckpoint?: () => void
      /** coarse audience count, to the presenter */
      onShowCount?: (n: number) => void
      /** an audience socket was closed by the relay (4001 end/grace, 4002
       *  not-live, 4003 show-full, 1008 revoked) */
      onShowClosed?: (code: number) => void
    },
    private auth?: AuthSpec,
  ) {
    this.docId = docId
    this.writeReadyP = new Promise<void>((r) => { this.resolveWriteReady = r })
    // Known before init's async work: an audience socket is a chain whose
    // invite the owner signed with role 'audience'. Set here so startShow and
    // the send guards see it immediately.
    this.audienceMode = auth?.kind === 'chain' && auth.invite.role === 'audience'
    this.init(room)
  }

  private docId = ''

  /** (actor,seq) pairs seen in the current connection's replay */
  private replaySeen = new Set<string>()

  /** Credentials the blob layer needs: the relay origin, the room name, the
   *  possession-proof token, and the raw room key it encrypts blobs with.
   *  Null until init() has derived the token. */
  blobCreds(): { base: string; room: string; tok: string; rawKey: Uint8Array } | null {
    if (!this.roomName || !this.tokValue) return null
    // The write ticket (relay: Room.writeTicket) when this socket earned one,
    // else the read token. Uploads authorized by the token alone let any
    // read-only copy fill the room's blob quota, so the relay hands writers a
    // separate credential over the certified socket; reads accept either.
    return {
      base: this.originValue,
      room: this.roomName,
      tok: this.writeTicket || this.tokValue,
      rawKey: b64u.dec(this.keyB64),
    }
  }
  /** True once this socket can upload: it holds the write ticket, or the relay
   *  finished `ready` without offering one (an older relay, or a reader — either
   *  way the room token is what uploads take there). Callers that PUT before this
   *  resolves would send the token into a ticket-latched room and 403. */
  writeReady(): Promise<void> {
    return this.writeReadyP
  }
  private writeReadyP: Promise<void>
  private resolveWriteReady: () => void = () => {}
  private roomName = ''
  private tokValue = ''
  private originValue = ''
  /** relay-issued blob write ticket; null until a PROVEN socket is handed one */
  private writeTicket: string | null = null
  /** `w`-room: the relay verifies writer signatures, so its stamps mean
   *  something and unstamped content-bearing frames can be refused. Legacy
   *  `r` rooms sign nothing — gating there would drop every legitimate frame. */
  private signedRoom = false
  /** An audience socket: connects on the audience path (ivr=audience) and is
   *  RECEIVE-ONLY — it sends no protocol frame, only the transport keepalive.
   *  The relay drops anything else it sent, but a client that does not send it
   *  in the first place cannot leak presence or an op it should not have. */
  private audienceMode = false
  /** True when this transport is an audience socket — receive-only. The session
   *  refuses startShow on it, and every show sender below no-ops. */
  get audience(): boolean { return this.audienceMode }

  private async init(room: string) {
    const raw = b64u.dec(this.keyB64)
    this.key = await crypto.subtle.importKey('raw', raw as BufferSource, 'AES-GCM', false, [
      'encrypt',
      'decrypt',
    ])
    const tokDigest = new Uint8Array(await crypto.subtle.digest('SHA-256', raw as BufferSource))
    const tok = b64u.enc(tokDigest.slice(0, 18))
    // Blob endpoints live on the same origin as the socket and use the same
    // room + token, so derive them here rather than duplicating the rule.
    try {
      const u = new URL(room.replace(/^ws/, 'http'))
      this.originValue = u.origin
      this.roomName = u.pathname.replace(/^\/d\//, '')
      this.tokValue = tok
      this.signedRoom = this.roomName[0] === 'w'
    } catch { /* malformed room url — blobs simply stay unavailable */ }
    // Writers sign op frames; readers omit auth and the relay drops their
    // writes. Two writer shapes: DIRECT (the presented `w` key hash-matches the
    // room commitment — the owner, or a legacy shared-writer copy) and CHAIN
    // (a member: `w` = this device's key, plus the owner-signed invite and the
    // invite-signed delegation of the device key — verified by the relay).
    const a = this.auth
    if (a?.kind === 'direct') {
      if (a.priv) { try { this.signKey = await importSignKey(a.priv) } catch { this.signKey = null } }
      this.myPub = a.pub
      // bt=1: we understand the blob write ticket. The relay only starts
      // REQUIRING it for uploads once a PROVEN writer has said so, which is
      // what lets the relay ship ahead of clients without 403ing their asset
      // offload. Sent by every writer shape; honoured only after `prove`.
      this.url = `${room}?tok=${tok}&bt=1&w=${a.pub}`
    } else if (a?.kind === 'chain') {
      // Under a host with per-document storage, this device's key can't be
      // READ while the host is busy, and deviceIdentity then fails rather than
      // invent a new key (that would change this device's identity). Wait and
      // retry; init is not awaited, so a throw here would leave the socket
      // never connecting. Without such a host this never fails.
      let id: { pub: string; priv: string } | null = null
      for (let wait = 2000; !id; wait = Math.min(wait * 2, 30_000)) {
        if (this.closed) return
        try { id = await deviceIdentity(this.docId) } catch { await new Promise((r) => setTimeout(r, wait)) }
      }
      try { this.signKey = await importSignKey(id.priv) } catch { this.signKey = null }
      this.myPub = id.pub
      const iv = a.invite
      const dg = await signText(iv.priv, `dlg.${id.pub}`)
      // An audience member connects on the audience path: ivr=audience (which
      // the owner signed into the invite), no bt (it never proves, never gets a
      // ticket), and receive-only. audienceMode was set in the constructor.
      const bt = this.audienceMode ? '' : '&bt=1'
      this.url = `${room}?tok=${tok}${bt}&w=${id.pub}&o=${a.owner}` +
        `&ivp=${iv.pub}&ivr=${iv.role}&ive=${iv.exp ?? 0}&ivs=${iv.sig}&dg=${dg}`
    } else {
      this.url = `${room}?tok=${tok}`
    }
    this.connect()
  }

  private lastSeq(): number {
    return this.seq
  }

  private saveSeq(q: number) {
    if (q > this.seq) this.seq = q
  }

  private setStatus(s: OnlineStatus) {
    this.status = s
    this.onStatus?.(s)
  }

  private connect() {
    if (this.closed) return
    this.setStatus('connecting')
    let ws: WebSocket
    try {
      ws = netWebSocket(`${this.url}&since=${this.lastSeq()}`)
    } catch (e) {
      // A sandboxed embed (Teams/SharePoint preview) refuses every socket at
      // the net chokepoint, permanently and identically — retrying would only
      // flap 'connecting' forever. Treat it as TERMINAL, exactly as drop()
      // treats close codes 4001/1008: stop, schedule no reconnect. (The offline
      // switch is different — it can flip back off, so it stays retryable.)
      if (e instanceof SandboxedError) { this.closed = true; this.setStatus('closed'); return }
      this.retry()
      return
    }
    this.ws = ws
    ws.onopen = () => {
      this.backoff = 800
      this.inReplay = true
      this.replaySeen = new Set()
      // acks don't survive the socket: whatever was un-acked is unknowable now,
      // and a stale entry would mis-name a later refusal. Delivery of those ops
      // is the log's job anyway (session.onRelayReady re-sends what the room lacks).
      this.awaitingAck = []
      this.setStatus('open')
      for (const out of this.queue.splice(0)) this.write(out)
      this.startHeartbeat(ws)
      this.hooks.onOpen()
    }
    ws.onmessage = (ev) => {
      const data = String(ev.data)
      if (data === 'pong') { this.awaitingPong = false; return } // keepalive reply
      this.onEnvelope(data).catch(() => {})
    }
    const drop = (ev?: { code?: number }) => {
      if (this.ws !== ws) return
      this.stopHeartbeat()
      this.ws = null
      this.setStatus('closed')
      // Broadcast close codes carry meaning: the relay closed an audience
      // socket deliberately. 4001 end/grace and 1008 revoked are TERMINAL —
      // the show is over or access is gone, so do not reconnect into a wall;
      // 4002 not-live and 4003 show-full are transient (the presenter has not
      // gone live yet, or the show is momentarily full), so reconnect with
      // backoff — that IS the "waiting for the presenter" state.
      const code = ev?.code
      if (code && code >= 4001 && code <= 4003 || code === 1008) this.hooks.onShowClosed?.(code!)
      if (code === 4001 || code === 1008) { this.closed = true; return }
      this.retry()
    }
    ws.onclose = drop
    ws.onerror = () => drop()
  }

  private startHeartbeat(ws: WebSocket) {
    this.stopHeartbeat()
    this.awaitingPong = false
    this.pingTimer = setInterval(() => {
      if (this.ws !== ws || ws.readyState !== WebSocket.OPEN) return
      if (this.awaitingPong) {
        // no pong since the last ping → the socket is dead (half-open); force a
        // close so onclose fires and we reconnect, rather than hanging silently.
        try { ws.close() } catch { /* already gone */ }
        return
      }
      this.awaitingPong = true
      try { ws.send('ping') } catch { /* send failed → onclose will handle it */ }
    }, OnlineTransport.PING_MS)
  }

  private stopHeartbeat() {
    if (this.pingTimer) { clearInterval(this.pingTimer); this.pingTimer = null }
    this.awaitingPong = false
  }

  private retry() {
    if (this.closed) return
    setTimeout(() => this.connect(), this.backoff)
    this.backoff = Math.min(this.backoff * 1.8, 30000)
  }

  // --- refusals -------------------------------------------------------------

  /**
   * The relay refused a frame. Handling this is not optional politeness: when
   * the relay dropped oversize/over-quota frames SILENTLY, the sender got no
   * ack, the peer stayed behind, its `need`/vv catch-up asked for the very
   * same op, and the sender re-sent the identical doomed frame forever.
   *
   * 'rate-limited' is transient — back off and retry. Everything else is
   * permanent for that frame: it goes up to the session, which forgets the ops
   * so the loop cannot restart, and tells the user what they just lost.
   */
  private handleRefusal(env: RefusedEnv) {
    if (env.code === 'rate-limited') {
      this.throttle(typeof env.retryInMs === 'number' ? env.retryInMs : 10_000)
      return
    }
    // Not in RefusalCode on purpose: it never reaches SyncNotice (nothing was
    // lost, so there is nothing to tell the user), and widening the exported
    // union would make every app's notice switch non-exhaustive for a code it
    // will never see.
    if ((env.code as string) === 'snap-ahead') {
      // We uploaded a snapshot claiming to cover a seq the room has not reached.
      // The relay refused it rather than prune ops it still needs — nothing was
      // lost, the op log is intact, and the next snapshot cadence will retry
      // with a `q` the room agrees with. Loud, because it means this copy's
      // sequence counter drifted ahead of the room, which is a bug to find.
      console.warn('[bento-sync] relay refused a snapshot ahead of the room’s seq — nothing lost', env)
      return
    }
    if (env.code !== 'too-large' && env.code !== 'storage-failed' && env.code !== 'room-full') {
      // a code from a newer relay: no recovery we can invent is better than
      // leaving the op in the log, where `need` will retry it honestly
      console.warn('[bento-sync] relay refused a frame:', env.code)
      return
    }
    const culprit = this.matchRefused(env)
    if (culprit) this.awaitingAck = this.awaitingAck.filter((o) => o !== culprit)
    console.warn(`[bento-sync] relay refused a frame (${env.code})`, env)
    // No matched op for a whole-frame refusal = the frame was a snapshot (ops
    // are tracked and matched by id; snapshots are never acked). Lets the editor
    // word it "the deck is too large" rather than "that change is too large".
    this.hooks.onRefused?.(env.code, culprit?.ops ?? null, culprit ? undefined : { snapshot: true })
  }

  /**
   * Which frame does this refusal name? The relay quotes no id, so: head of
   * the ack queue by protocol order, CONFIRMED against the size it reported.
   * A mismatch means the refusal was for a frame we don't track — snapshots
   * are never acked, so they never enter the queue — and we must not hand the
   * session somebody else's ops to drop on a guess. Ambiguity → null → the
   * ops stay in the log (retried, at worst refused again and reported again),
   * because a wrong drop is silent permanent data divergence.
   */
  private matchRefused(env: RefusedEnv): Outbound | null {
    // Exact when the relay echoed our id. Everything below is the legacy
    // fallback for relays that don't (and a self-hoster's relay may be a year
    // old) — inferential, so it stays deliberately conservative.
    if (env.k) return this.awaitingAck.find((o) => o.id === env.k) ?? null
    // too-large measures the whole envelope; storage-failed measures i+d only
    const byText = typeof env.got === 'number'
    const want = byText ? env.got! : typeof env.bytes === 'number' ? env.bytes : null
    const size = (o: Outbound) => (byText ? o.text.length : o.bytes)
    const head = this.awaitingAck[0] ?? null
    if (want === null) return head // room-full carries no size — order is all we have
    if (head && size(head) === want) return head
    return this.awaitingAck.find((o) => size(o) === want) ?? null
  }

  /** Rate limited: hold everything for the window, then replay what we sent
   *  into it. Un-acked frames may or may not have landed — re-sending is safe
   *  (the CRDT dedups by actor:seq) and losing them silently is not. */
  private throttle(ms: number) {
    const wait = Math.min(Math.max(ms, 1000), 60_000)
    const retryable = this.awaitingAck.filter((o) => ++o.tries <= OnlineTransport.MAX_RETRIES)
    // past the retry cap we stop re-sending, but the op is NOT dropped: it
    // stays in the session log for the next `need`/reconnect to carry.
    this.awaitingAck = []
    this.queue = [...retryable, ...this.queue]
    if (this.pauseTimer) clearTimeout(this.pauseTimer)
    this.paused = true
    this.pauseTimer = setTimeout(() => {
      this.pauseTimer = null
      this.paused = false
      for (const out of this.queue.splice(0)) this.write(out)
    }, wait)
    // transient and self-healing, so say it at most once a minute
    const now = Date.now()
    if (now - this.lastLimitNotice > 60_000) {
      this.lastLimitNotice = now
      this.hooks.onRefused?.('rate-limited', null)
    }
  }

  /** write now, or park it (disconnected, or inside a rate-limit backoff) */
  private write(out: Outbound) {
    if (!this.paused && this.ws && this.ws.readyState === WebSocket.OPEN) {
      try {
        this.ws.send(out.text)
      } catch {
        this.park(out) // send threw → onclose will reconnect and flush
        return
      }
      if (out.ops) {
        this.awaitingAck.push(out)
        if (this.awaitingAck.length > OnlineTransport.ACK_WINDOW) this.awaitingAck.shift()
      }
      return
    }
    this.park(out)
  }

  private park(out: Outbound) {
    this.queue.push(out)
    if (this.queue.length > 500) this.queue.shift()
  }

  private async onEnvelope(text: string) {
    let env: {
      i?: string; d?: string; q?: number; snap?: number; ctl?: string; p?: string
      /** the writer signature the relay VERIFIED before fanning this out */
      g?: string
      /** blob write ticket — only ever sent to a socket that proved its key */
      wt?: string
      /** possession nonce on `ready`: sign it to prove the `?w=` key is ours */
      c?: string
      /** broadcast: the audience stream tag, the verb name, the count */
      s?: string
      n?: number
    } & RefusedEnv
    try {
      env = JSON.parse(text)
    } catch {
      return
    }
    // the owner revoked a key; if it's OURS, stand down for good (the relay
    // refuses our reconnects anyway — don't retry into a wall of 403s)
    if (env.ctl === 'revoked') {
      if (env.p && env.p === this.myPub) {
        console.info('[bento-sync] this copy’s access was revoked by the owner')
        this.close()
        return
      }
      // a removal re-mints the room's blob ticket (the removed copy still holds
      // the old one); the relay sends the replacement to PROVEN sockets only
      if (typeof env.wt === 'string') this.writeTicket = env.wt
      return
    }
    // The ticket arrives on its own frame, after `prove` — never on `ready`.
    // Presenting the owner's PUBLIC key hash-matches the room name, and every
    // reader copy carries that key; a ticket issued on the hash-match alone
    // would go to any reader. Only a socket that signed the relay's nonce with
    // the matching PRIVATE key is handed one.
    if (env.ctl === 'wt') {
      if (typeof env.wt === 'string') this.writeTicket = env.wt
      this.resolveWriteReady()
      return
    }
    // the relay would not take a frame and said so (v1.0.9 relay and later;
    // older relays never send this, which is why every path here is additive)
    if (env.ctl === 'refused') {
      this.handleRefusal(env)
      return
    }
    // ——— broadcast control, no encrypted body ———
    if (env.ctl === 'audckpt') { this.hooks.onShowCheckpoint?.(); return }
    if (env.ctl === 'audcount') { if (typeof env.n === 'number') this.hooks.onShowCount?.(env.n); return }
    if (env.ctl === 'ack' || env.ctl === 'ready') {
      // one ack = the oldest un-acked persisted frame landed
      if (env.ctl === 'ack') this.awaitingAck.shift()
      if (typeof env.q === 'number') {
        this.saveSeq(env.q)
        this.maybeSnapshot(env.q)
      }
      if (env.ctl === 'ready' && typeof env.q !== 'number') {
        // An AUDIENCE ready: `bc`/`v`, no `q`. The audience is receive-only and
        // has no op log to replay or snapshot — running the collab path below
        // would make it try to upload one. It is simply live now.
        this.inReplay = false
        this.resolveWriteReady()
        return
      }
      if (env.ctl === 'ready') {
        // `c` is the relay's possession challenge, present only for a socket
        // whose `?w=` hash-matched the room. Answer it and the ticket follows on
        // its own `wt` frame; a reader (no signing key) cannot answer and never
        // gets one. No `c` at all = an older relay, or we joined as a reader —
        // in both cases uploads take the room token and there is nothing to
        // wait for, so writes are released now.
        if (typeof env.c === 'string' && this.signKey && this.roomName) {
          void this.prove(env.c)
        } else {
          this.resolveWriteReady()
        }
        this.inReplay = false
        const wantSnap = this.hooks.onReady(this.replaySeen, env.q ?? 0)
        this.replaySeen = new Set()
        // fresh rooms and just-merged forks get a snapshot immediately so
        // late joiners converge without needing the full op log
        if (wantSnap || env.q === 0) void this.uploadSnapshot(env.q ?? 0)
      }
      return
    }
    if (!env.i || !env.d || !this.key) return
    let payload: unknown
    try {
      const pt = await crypto.subtle.decrypt(
        { name: 'AES-GCM', iv: b64u.dec(env.i) as BufferSource },
        this.key,
        b64u.dec(env.d) as BufferSource,
      )
      payload = JSON.parse(new TextDecoder().decode(pt))
    } catch {
      return // wrong key / corrupted — ignore
    }
    if (typeof env.q === 'number') this.saveSeq(env.q)
    // ——— broadcast reception (audience side). These arrive pre-routed by the
    // relay, which only fans them to audience sockets and verified every
    // signed one; the payload is under Ke, which only show participants hold.
    // So they do not go through vouched() — that is the ROOM's read-only
    // guarantee, a different trust path from the relay-routed show stream. ———
    if (env.s === 'aud' && !env.ctl) {
      const f = payload as { ops?: Op[] }
      if (f?.ops) this.hooks.onShowOps?.(f.ops)
      return
    }
    if (env.ctl === 'audsnap') {
      const sn = payload as { doc: SyncDoc; state: SyncStateJSON }
      if (sn?.doc && sn.state) this.hooks.onShowSnap?.(sn.doc, sn.state)
      return
    }
    if (env.ctl === 'nav' || env.ctl === 'black' || env.ctl === 'laser') {
      this.hooks.onShowVerb?.(env.ctl, payload)
      return
    }
    if (env.snap === 1) {
      if (!this.vouched(env)) return
      const s = payload as { doc: SyncDoc; state: SyncStateJSON }
      if (s && s.doc && s.state) this.hooks.onSnap(s.doc, s.state)
      return
    }
    const frame = payload as Frame
    // Decrypting a frame proves the sender holds the READ key — which every
    // copy carries, read-only ones included. Authorship is a separate question
    // and only the relay can answer it, so content-bearing frames are refused
    // without its stamp.
    if ((frame.t === 'ops' || frame.t === 'snap') && !this.vouched(env)) return
    if (this.inReplay && frame.t === 'ops') {
      for (const op of frame.ops) this.replaySeen.add(`${op.a}:${op.s}`)
    }
    this.onFrame(frame)
  }

  private inReplay = true

  /**
   * Did the relay vouch for this envelope? In a signed room it stamps exactly
   * what it checked: `q` on a frame it persisted (verified before storage) and
   * an echoed `g` on a signed frame it fanned out. An unstamped frame reached
   * us because someone encrypted it with the room key — a read-only copy can
   * do that, and a blind relay cannot tell the ciphertext of an op batch from
   * the ciphertext of a presence beat, so it forwards both. Refusing the
   * unstamped ones HERE is what makes read-only hold for live peers and not
   * just for the persisted log.
   *
   * Legacy `r` rooms have no signatures at all: gating them would drop every
   * frame, so they stay on the pre-signing trust model.
   */
  private vouched(env: { q?: number; g?: string }): boolean {
    return !this.signedRoom || typeof env.q === 'number' || typeof env.g === 'string'
  }

  /** Answer the relay's possession challenge: sign `prove.<nonce>.<room>` with
   *  the key we presented as `?w=`. The room name is in the signed text so a
   *  signature can never be replayed into another room, and the nonce is
   *  per-socket and single-use so it cannot be replayed into this one. */
  private async prove(nonce: string) {
    if (!this.signKey || !this.ws) return
    try {
      const g = await signWith(this.signKey, `prove.${nonce}.${this.roomName}`)
      this.ws.send(JSON.stringify({ ctl: 'prove', g }))
    } catch {
      // cannot sign → we are effectively a reader; do not hold writes forever
      this.resolveWriteReady()
    }
  }

  private snapInFlight = false

  /** every SNAP_EVERY persisted ops, upload a fresh encrypted snapshot */
  private maybeSnapshot(q: number) {
    if (q === 0 || q % SNAP_EVERY !== 0) return
    void this.uploadSnapshot(q)
  }

  /** encrypt + store the current (doc, state) as the room's snapshot */
  async uploadSnapshot(q: number) {
    if (this.snapInFlight) return
    this.snapInFlight = true
    try {
      const snap = this.hooks.getSnapshot()
      const text = await this.encrypt(JSON.stringify(snap))
      if (text && this.ws && this.ws.readyState === WebSocket.OPEN) {
        const env: Record<string, unknown> = { snap: 1, q, i: text.i, d: text.d }
        if (this.signKey) env.g = await signFrame(this.signKey, text.i, text.d)
        this.ws.send(JSON.stringify(env))
      }
    } finally {
      this.snapInFlight = false
    }
  }

  private async encrypt(plain: string, key: CryptoKey | null = this.key): Promise<{ i: string; d: string } | null> {
    if (!key) return null
    const iv = new Uint8Array(12)
    crypto.getRandomValues(iv)
    const ct = await crypto.subtle.encrypt(
      { name: 'AES-GCM', iv: iv as BufferSource },
      key,
      new TextEncoder().encode(plain),
    )
    return { i: b64u.enc(iv), d: b64u.enc(new Uint8Array(ct)) }
  }

  // ——— BROADCAST: the presenter's audience stream ———
  // The presenter's socket carries the room key (this.key). A show's audience
  // holds a SEPARATE show key Ke; the presenter encrypts a second copy of each
  // op batch and each control frame under Ke, tagged s:'aud', and the relay
  // routes those to audience sockets only. Only the presenter side needs this:
  // an audience copy's own this.key already IS Ke (its collab.key is the show
  // key), so it decrypts s:'aud' frames on the ordinary path below.
  private showKey: CryptoKey | null = null

  /** Install (or clear) the show key. Raw AES-GCM key, base64url. */
  async setShowKey(rawB64: string | null): Promise<void> {
    if (this.audienceMode) return
    this.showKey = rawB64
      ? await crypto.subtle.importKey('raw', b64u.dec(rawB64) as BufferSource, 'AES-GCM', false, ['encrypt'])
      : null
  }

  /** One op batch to the audience: sealed under Ke, tagged s:'aud'. NEVER
   *  persisted by the relay (it ignores p on this stream), so it does not join
   *  the resend log — a dropped aud batch is recovered by the next audsnap, not
   *  by replay. Silent no-op if there is no show key or the socket is gone. */
  async sendAud(ops: Op[]): Promise<void> {
    if (this.audienceMode) return
    const enc = await this.encrypt(JSON.stringify({ t: 'ops', a: 'show', ops }), this.showKey)
    if (!enc || !this.ws) return
    try { this.ws.send(JSON.stringify({ s: 'aud', i: enc.i, d: enc.d })) } catch { /* gone */ }
  }

  /** The whole (already app-projected) document to the audience, under Ke. */
  async sendAudSnap(doc: SyncDoc, state: SyncStateJSON): Promise<void> {
    if (this.audienceMode) return
    const enc = await this.encrypt(JSON.stringify({ doc, state }), this.showKey)
    if (!enc || !this.ws) return
    try { this.ws.send(JSON.stringify({ ctl: 'audsnap', i: enc.i, d: enc.d })) } catch { /* gone */ }
  }

  /** A control verb. live/end sign the literal; nav/black encrypt their payload
   *  under Ke and sign the ciphertext with the stream in the text (so a
   *  room-stream signature cannot be replayed as the audience's); laser is
   *  unsigned. The relay checks all of this against the socket's proven key. */
  async sendVerb(kind: 'live' | 'end' | 'nav' | 'black' | 'laser', payload?: unknown): Promise<void> {
    if (this.audienceMode || !this.ws) return
    try {
      if (kind === 'live' || kind === 'end') {
        const g = this.signKey ? await signWith(this.signKey, kind) : undefined
        this.ws.send(JSON.stringify({ ctl: kind, g }))
        return
      }
      const enc = await this.encrypt(JSON.stringify(payload ?? null), this.showKey)
      if (!enc) return
      if (kind === 'laser') {
        this.ws.send(JSON.stringify({ ctl: 'laser', s: 'aud', i: enc.i, d: enc.d }))
        return
      }
      const g = this.signKey ? await signFrame(this.signKey, `${kind}.aud.${enc.i}`, enc.d) : undefined
      this.ws.send(JSON.stringify({ ctl: kind, s: 'aud', i: enc.i, d: enc.d, g }))
    } catch { /* gone */ }
  }

  send(frame: Frame) {
    // An audience socket is receive-only: it never puts a protocol frame on the
    // wire (the relay would drop it, but not sending it is the guarantee). The
    // keepalive ping is not a protocol frame and is left alone.
    if (this.audienceMode) return
    void (async () => {
      const enc = await this.encrypt(JSON.stringify(frame))
      if (!enc) return
      let env: Record<string, unknown> = enc
      let ops: Op[] | null = null
      const id = nextFrameId()
      if (frame.t === 'ops') {
        env = { k: id, p: 1, ...enc }
        // sign the ciphertext so the relay verifies authorship while blind.
        if (this.signKey) env.g = await signFrame(this.signKey, enc.i, enc.d)
        ops = frame.ops
      } else if (frame.t === 'snap' && this.signKey) {
        // A rejoining fork's snapshot is ephemeral (never persisted) but it
        // REPLACES what every live peer holds — the same authority as an op
        // batch, and it used to travel unsigned. Sign it so the relay can
        // vouch for it; peers now refuse a `snap` it hasn't stamped.
        env = { ...enc, g: await signFrame(this.signKey, enc.i, enc.d) }
      }
      // remember what rode in the frame so a refusal can name it
      this.write({ id, text: JSON.stringify(env), ops, bytes: enc.i.length + enc.d.length, tries: 0 })
    })()
  }

  close() {
    this.closed = true
    if (this.pauseTimer) { clearTimeout(this.pauseTimer); this.pauseTimer = null }
    this.stopHeartbeat()
    this.ws?.close()
    this.ws = null
    this.setStatus('closed')
  }

  /** OWNER action: revoke one member key (or an invite key — cutting off every
   *  copy descended from that invite). Signed `rev.${pub}`; the relay stores it,
   *  drops that key's future writes/joins, and fans out a `revoked` note. */
  async revokeKey(pub: string, ownerPub: string, ownerPriv: string): Promise<boolean> {
    if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return false
    const g = await signText(ownerPriv, `rev.${pub}`)
    this.ws.send(JSON.stringify({ ctl: 'revoke', p: pub, o: ownerPub, g }))
    return true
  }
}

// --- share/join glue --------------------------------------------------------

let active: OnlineTransport | null = null

export function onlineTransport(): OnlineTransport | null {
  return active
}

/** inert stand-in when a re-keyed document has no collab config */
class NullTransport implements Transport {
  readonly kind = 'off'
  send() {}
  close() {}
}

/** does this document want its relay connected? (absent `on` = true: v0.8.0
 * files only carried collab while actively shared) */
export function sharingOn(store: Store): boolean {
  const c = store.doc.collab
  return !!c?.room && !!c.key && c.on !== false
}

/** connect the session to the relay in doc.collab (no-op unless sharing is on) */
export function joinFromDoc(session: SyncSession, store: Store): OnlineTransport | null {
  if (offlineEnabled()) return null // the hard no-network switch wins over everything
  if (active) return active
  if (!sharingOn(store)) return null
  session.addTransport((docId, onFrame) => {
    // re-invoked whenever the session re-keys (doc replaced): consult the
    // CURRENT document — its collab config may differ or be off
    const collab = store.doc.collab
    if (!collab?.room || !collab.key || collab.on === false || store.doc.docId !== docId) {
      active = null
      return new NullTransport()
    }
    active?.close()
    // Auth shape per copy: reader → none (unsigned, relay drops writes);
    // v2 owner → direct with ownerPriv; v2 member → invite chain (device key
    // minted per-machine); legacy → the shared writer key pair.
    let auth: AuthSpec | undefined
    if (collab.role === 'audience') {
      // An AUDIENCE copy: its collab.key is the show key Ke, its invite is the
      // owner-signed `audience` ticket. It joins on the chain (ivr=audience,
      // set from the invite role) and the transport makes it receive-only. No
      // audience invite, no join — there is nothing to fall back to.
      if (collab.owner && collab.invite) {
        auth = { kind: 'chain', owner: collab.owner, invite: collab.invite, docId }
      }
    } else if (collab.role !== 'reader') {
      if (collab.v === 2 && collab.owner && collab.ownerPriv) {
        auth = { kind: 'direct', pub: collab.owner, priv: collab.ownerPriv }
      } else if (collab.v === 2 && collab.owner && collab.invite) {
        auth = { kind: 'chain', owner: collab.owner, invite: collab.invite, docId }
      } else if (collab.writerPub) {
        auth = { kind: 'direct', pub: collab.writerPub, priv: collab.writerPriv }
      }
    }
    active = new OnlineTransport(collab.room, collab.key, docId, onFrame, {
      onSnap: (doc, state) => session.applySnapshot(doc, state),
      getSnapshot: () => session.snapshot(),
      onOpen: () => session.hello(),
      onReady: (seen) => session.onRelayReady(seen),
      onRefused: (code, ops, opts) => {
        // show-full is a broadcast refusal: it means "checkpoint now", handled
        // by the show path, not the collab resend log.
        if ((code as string) === 'show-full') { session.showCheckpoint(); return }
        session.refused(code, ops, opts)
      },
      onShowOps: (ops) => session.applyShowOps(ops),
      onShowSnap: (doc, state) => session.applyShowSnap(doc, state),
      onShowVerb: (kind, payload) => session.showVerb(kind, payload),
      onShowCheckpoint: () => session.showCheckpoint(),
      onShowCount: (n) => session.showCount(n),
      onShowClosed: (code) => session.showClosed(code),
    }, auth)
    return active
  })
  return active
}

/** Apply a sharing/collab change WITHOUT an undo step. collab is per-copy
 *  capability + config, never document content, so a user's Cmd-Z must not
 *  toggle it: an undone "Stop sharing" left the flag ON with no connection (UI
 *  and session disagreeing), and an undone key rotation would restore a revoked
 *  key. The doc is still marked dirty so the change saves, and 'doc' is emitted
 *  so the Live UI refreshes, but it never goes through store.commit (which pushes
 *  undo). collab is excluded from the sync diff, so emitting 'doc' sends no op. */
function markShared(store: Store, fn: () => void) {
  fn()
  store.setDirty(true)
  store.emit('doc')
}

/** flip sharing on and connect — the "Start live session" action.
 * Credentials already exist (minted at creation); this only arms them. */
export async function startSharing(session: SyncSession, store: Store): Promise<OnlineTransport | null> {
  if (offlineEnabled()) return null
  if (active) return active
  if (!store.doc.collab) {
    const creds = await mintCollab()
    markShared(store, () => { store.doc.collab = creds })
  }
  markShared(store, () => { store.doc.collab!.on = true })
  return joinFromDoc(session, store)
}

/**
 * Offline-mode disconnect: drop the relay WITHOUT touching doc.collab.on —
 * the document's sharing intent is unchanged; this viewer just won't
 * network. Turning offline mode off re-joins via the normal path.
 */
export function disconnectOnline(session: SyncSession) {
  if (active) {
    session.removeTransport(active)
    active = null
  }
}

/** flip sharing off and disconnect. Credentials stay — copies saved during
 * the session can rejoin if sharing is turned back on. */
export function stopSharing(session: SyncSession, store: Store) {
  if (active) {
    session.removeTransport(active)
    active = null
  }
  if (store.doc.collab && store.doc.collab.on !== false) {
    markShared(store, () => { store.doc.collab!.on = false })
  }
}

/** revocation: mint a fresh room + key. Every previously sent copy loses
 * access; only copies saved AFTER this can join future sessions. */
export async function rotateKeys(session: SyncSession, store: Store) {
  stopSharing(session, store)
  const fresh = await mintCollab()
  markShared(store, () => {
    // fresh keys = the revocation; carry the rotate-survivors (sync, links) from
    // the old block (kernel/src/docfields.ts COLLAB_ROTATE_KEEP). Not a commit —
    // a key reset is connection state, not an undoable edit (#605).
    store.doc.collab = carryThroughRotation(fresh, store.doc.collab)
  })
}