engineering/zebra-report
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

web/chat.html: production multi-person volume-modem chatroom

Browse source 
single self-contained page implementing the recovered zebra-report
protocol as a peer-to-peer chatroom whose data path is PulseAudio
sink-input state — chat content never enters an IP packet.

architecture:
  page (TX)   modulates audio output via Web Audio GainNode
              between MARK (0.80) and SPACE (0.20). silent stereo
              carrier 440/441 Hz published to PulseAudio.
  zebrad      separate program (companion, not in this commit):
              polls PA sink-input volumes, decodes frames,
              forwards to ws://127.0.0.1:7777 — the page connects
              and renders received messages.
  RX path     the page is TX-only without zebrad running; with
              it, full bidirectional chat.

crypto modes (toggle in UI):
  passphrase  PBKDF2-SHA256 (600k iter) → AES-GCM-256 group key.
              everyone with the same phrase joins the room.
  pubkey      ECDH P-256 keypair per browser → AES-GCM-256
              pairwise. peers added by pasting their pubkey.
  both modes use Web Crypto API. no external crypto deps.

frame protocol (matches include/zebra.h):
  OFFER  magic(ZB) + 0x01 + baud_le(2) + xor(1)          — 6B
  READY  magic(ZB) + 0x02 + baud_le(2) + xor(1)          — 6B
  HELLO  magic + 0x04 + sid(4) + maxBaud_le(2)
         + handleLen(1) + handle(n) + crc32_le(4)
  DATA   magic + 0x03 + sid(4) + len_le(2)
         + payload(n) + crc32_le(4)

handshake:
  1. user clicks "benchmark self" — page schedules 200 gain
     events at 0.5ms intervals, measures avg, divides by 2 for
     safety, clamps to [ZEBRA_BAUD_MIN, ZEBRA_BAUD_MAX].
  2. user clicks "send OFFER" — sends OFFER frame at the
     fixed handshake baud (50). also broadcasts HELLO.
  3. peer's introspector decodes; their page replies with READY
     at their max baud, plus their HELLO.
  4. negotiated baud = min(my max, every peer's max).
  5. data frames at negotiated baud.

UI sections:
  identity   handle + mode toggle
  room       passphrase OR pubkey, depending on mode
  carrier    start audio, live gain meter
  handshake  benchmark, OFFER button, baud display
  receive    ws://127.0.0.1:7777 status + connect
  chat       peer list, log, message box
  about      threat model, mitigation, whitepaper link

defensive framing prominent: the protocol is documented as a
research artifact demonstrating PA-IPC's open same-UID volume
read access. "what this does not protect against" enumerated.
mitigation panel cites foxhop.net/linux-audio-ipc-attack-surface.

known v1 tradeoffs:
  - no CSMA: simultaneous TX from two peers will collide.
  - pubkey mode broadcasts one frame per peer per message.
  - GainNode scheduling has OS-level jitter — actual sustained
    baud will be lower than the optimistic benchmark.
  - base carrier is audible at 440/441 Hz; can be lowered or
    moved ultrasonic in a follow-up.

reuses visual identity from web/index.html (chunkfive font,
monospace, black/white, no framework, no build step).

file: 1062 lines, 40 KB, JS syntax-clean (node --check), HTML
balanced.
This commit is contained in:
Russell Ballestrini 2026-05-27 14:54:26 -04:00
parent bf6427f279
commit d9b2499a2e
1 changed files with 1062 additions and 0 deletions
Download patch file Download diff file Expand all files Collapse all files

1062
web/chat.html Normal file
View file

File diff suppressed because it is too large Load diff