Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

docs: add public security explainer; refresh announcement deck builder

nyblnetcf729b3641d0
diff --git a/docs/security.md b/docs/security.md
new file mode 100644
index 00000000..db8dd124
--- /dev/null
+++ b/docs/security.md
@@ -0,0 +1,180 @@
+# Bento security, plainly
+
+*How live collaboration is encrypted, exactly what the relay can and cannot
+see, how keys live and die, and how to prove no bytes ever leave your machine.
+Written for the skeptic. Everything here matches the code; links point at it.*
+
+Bento is a slide app where **one HTML file is the whole document** — viewer,
+editor, and content in a single file you own. Live collaboration is an
+**optional layer beside that file**, not a cloud it depends on. This page
+explains the security of that layer without hand-waving.
+
+## The model in one line
+
+**The file is the security boundary.** Live collaboration is an optional,
+end-to-end-encrypted layer beside it, and every saved copy still opens
+standalone, forever, with zero knowledge of a server. If you never turn on
+sharing, nothing about your document ever touches the network.
+
+## What the relay sees — and doesn't
+
+When you do share live, frames travel through a relay (a single Cloudflare
+Durable Object per room). It is **blind by construction**: your browser
+encrypts every frame with AES-GCM *before* it leaves, using a key the relay
+never receives.
+
+**The relay SEES:**
+
+- **Ciphertext frames only** — AES-GCM blobs it stores and fans out to the
+ other people in the room. It cannot decrypt them; it has no key.
+- **A hash of the room key** — the `?tok=` connection token is the first 18
+ bytes of `SHA-256(roomKey)`. It proves you hold the key without revealing
+ it, so the relay won't fan ciphertext to a stranger who lacks the file.
+- **Unavoidable network metadata** — connection timing, frame sizes and
+ counts, and your IP (as any web server sees). It enforces per-socket rate
+ limits (200 frames / 10s) and expires idle rooms after ~30 days.
+- **For signed rooms, the writer's public key** — public by definition, and
+ already in every copy of the file (see *Signed writes* below).
+
+**The relay does NOT see:**
+
+- **Your slides.** Text, images, charts, notes — all inside the ciphertext.
+- **Your name or presence.** Names live in encrypted frames; the relay never
+ sees who is in a room, only opaque sockets.
+- **The room key itself.** It is minted in your browser and never sent — only
+ a one-way hash of it is.
+- **Document structure or metadata of any kind.** There is no title, no
+ filename, no schema on the wire — just `{i, d}` (an IV and a ciphertext).
+
+There is **no database of your slides to breach.** The relay's storage is an
+append-only list of encrypted op frames plus the latest client-produced
+encrypted snapshot — ciphertext end to end, verified in
+[`server/sync-worker/src/worker.js`](../server/sync-worker/src/worker.js). The
+server cannot produce a snapshot itself; it literally can't read one. A
+subpoena of the relay gets noise.
+
+## Key lifecycle
+
+**Keys are born in the file, at creation — never fetched from a server.** When
+a document is created it mints two independent things
+([`mintCollab`](../slides/src/sync/online.ts)):
+
+1. **A symmetric AES-GCM content key** — the *read capability*. It lives in
+ `doc.collab.key`, inside the file, and every copy carries it. This is what
+ encrypts and decrypts frames.
+2. **A separate ECDSA P-256 writer keypair** — the *write capability* (details
+ in *Signed writes*). The public half rides in every copy; the private half
+ only in writer copies.
+
+Both are generated with WebCrypto in your browser. **Neither ever leaves the
+file or your machine.** The relay only ever sees the *hash* of the content key
+and the *public* half of the writer key.
+
+- **"Rotate keys" = revocation.** It mints a fresh room and fresh keys. Every
+ copy handed out before the rotation can no longer follow the new session —
+ the old key opens the old file, not the live room.
+- **Possession of the file is membership.** Anyone you give the file to holds
+ the read key and can read the live session. That is the intended design, and
+ it's stated plainly under *Limitations*.
+
+### Password encryption is a separate layer
+
+Independently of collaboration, a document can be **password-encrypted at
+rest**: the on-disk `#bento-doc` block holds a `bento/enc` envelope —
+AES-GCM-256 over the document JSON, with the key derived from your password via
+**PBKDF2-SHA-256, 300,000 iterations**
+([`slides/src/save.ts`](../slides/src/save.ts)). The password is held only in
+memory so autosave and self-update keep writing encrypted. This protects the
+file itself; it is orthogonal to the room key that protects live frames.
+
+## Signed writes — read-only that the relay enforces (v0.9.18)
+
+A subtle problem: if read-only were just a flag, it would be a lie. Anyone who
+can *decrypt* frames holds the key, and holding the key means being able to
+*encrypt and send* too. So Bento splits the single capability in two.
+
+- The **content key** is the read capability (everyone in the room has it).
+- The **ECDSA writer keypair** is the write capability. A **read-only copy is
+ simply a writer copy with the private key stripped out.**
+
+The room id **commits to the writer's public key**: the room name is
+`w` + `base64url(SHA-256(writerPubRaw))`. On connect, a client presents the raw
+public key as `?w=`, and the relay checks that its hash equals the room name
+before pinning it — so a viewer (who legitimately holds the public key and the
+room id) still **cannot substitute their own key** and promote themselves to
+writer. This is trustless: no first-writer-wins, no server-side roster.
+
+Thereafter the relay **verifies an ECDSA signature on every mutating frame**
+(op batches and snapshots) over the ciphertext, and **drops any that lack a
+valid signature** — no persist, no fan-out. Readers have no private key, so
+their writes never land. The signature covers the *ciphertext*
+(encrypt-then-sign), so the relay authorizes writes **without decrypting
+anything** — still blind. Client side is in
+[`online.ts`](../slides/src/sync/online.ts) (`signFrame`), enforcement in
+[`worker.js`](../server/sync-worker/src/worker.js) (`verifySig`).
+
+Read-only is therefore **cryptographic, enforced at the edge — not an
+honour-system flag and not a permissions table someone can misconfigure.**
+
+> **Legacy rooms are permissive.** Rooms created before v0.9.18 have `r`-prefixed
+> ids (random, not a key commitment) and are not signature-gated — existing
+> shared files keep working unchanged. Rotating keys upgrades a deck to an
+> enforced `w`-room.
+
+## Offline mode — nothing leaves this computer
+
+An **Offline switch** (in the About dialog) hard-blocks every network touch:
+the update check *and* the relay transport are refused before they open a
+socket ([`joinFromDoc`](../slides/src/sync/online.ts) returns early;
+same-machine tab sync over BroadcastChannel is not networking and stays on).
+
+There is no telemetry, no analytics, no phone-home. Even with offline mode
+*off*, the update check is a bare GET for a signed release manifest — it
+carries **no identifier about you or your document**. Offline mode is the "no
+cloud, provably" story: flip it on and you can watch the network tab stay
+silent.
+
+## Limitations, stated up front
+
+These are deliberate design trade-offs, not oversights. Disclosing them is the
+point.
+
+- **Presence names are claims, not proofs.** Within a shared-key room, the name
+ shown next to a cursor is self-asserted. Binding names to identities
+ (per-user signing keys + an SSO roster) is designed and on the roadmap; it is
+ **not shipped**. Share room keys with people you'd trust with the file.
+- **The room key is a read capability.** Anyone you give the file to can read
+ the live session and the document. That's the model — the file *is* the
+ invitation.
+- **Undo under live collaboration is snapshot-based (LWW).** If two people edit
+ the same property at once, last-writer-wins; an undo can revert a
+ collaborator's concurrent same-property edit. They redo, and the CRDT keeps
+ everyone converged — but it is not per-user isolated undo.
+- **Same-machine tab sync is cooperative.** Two tabs on one computer sync over
+ BroadcastChannel — same trust domain, *not* relay-enforced. Read-only is
+ enforced over the network, disabled-in-UI locally.
+- **The relay sees metadata.** Timing, frame sizes, counts, and IP are visible
+ to the relay (and its host) even though content is not. E2EE hides *what*,
+ not *that* you're collaborating or roughly how much.
+- **A malicious relay can withhold or reorder** frames, or serve a stale
+ snapshot. It **cannot** forge writer ops (no private key) or read content.
+ Optional client-side signature verification against a hostile relay is
+ additive future hardening, not required for the read-only guarantee.
+
+## Read the source
+
+None of the above asks for trust. The relevant code is small and public:
+
+- [`server/sync-worker/src/worker.js`](../server/sync-worker/src/worker.js) —
+ the entire relay (~250 lines): ciphertext storage, token check, signature
+ verification.
+- [`slides/src/sync/online.ts`](../slides/src/sync/online.ts) — client E2EE,
+ key minting, frame signing.
+- [`docs/collab-design.md`](collab-design.md) — the full design and threat
+ model this page summarizes.
+
+## Reporting a vulnerability
+
+Found something? Please report it privately — see
+[`SECURITY.md`](../SECURITY.md) for the disclosure process and scope. Don't
+open a public issue for a security bug.
diff --git a/scripts/build-announcement-deck.mjs b/scripts/build-announcement-deck.mjs
index 4f75de10..2e2bf7a8 100644
--- a/scripts/build-announcement-deck.mjs
+++ b/scripts/build-announcement-deck.mjs
@@ -67,9 +67,10 @@ const s1 = slide({
elements: [
...tiles({ x: 950, y: 110, w: 200, h: 200 }, { x: 1064, y: 340, w: 120, h: 180 }, { x: 900, y: 380, w: 120, h: 120 }),
kick(96, 96, 'SHOW HN — BENTO/SUITE'),
- text({ x: 88, y: 150, w: 880, h: 340, html: 'This announcement<br>is the product.', fontSize: 96, fontFamily: FR, fontWeight: 900, color: '#fff', lineHeight: 1.02 }),
- text({ x: 96, y: 470, w: 700, h: 90, html: 'You are inside a <b>.bento.html</b> file — a presentation that carries its own editor, presenter and format. One file. No install. No account.', fontSize: 20, color: MIST, lineHeight: 1.6, fx: { enter: 'fade-up', order: 1 } }),
- text({ x: 96, y: 640, w: 1000, h: 24, html: '→ ADVANCE · ESC OPENS THE EDITOR ON THIS VERY FILE', fontSize: 12, fontWeight: 700, letterSpacing: 3, color: 'rgba(255,158,138,0.85)', fx: { enter: 'fade-up', order: 2 } }),
+ text({ x: 88, y: 150, w: 880, h: 300, html: 'This announcement<br>is the product.', fontSize: 96, fontFamily: FR, fontWeight: 900, color: '#fff', lineHeight: 1.02 }),
+ text({ x: 96, y: 402, w: 1040, h: 48, html: 'The boring deck is dead. One file killed it.', fontSize: 27, fontFamily: FR, fontWeight: 900, color: PEACH, lineHeight: 1.1, fx: { enter: 'fade-up', order: 1 } }),
+ text({ x: 96, y: 476, w: 760, h: 90, html: 'You are inside a <b>.bento.html</b> file — a presentation that carries its own editor, presenter and format. One file. No install. No account.', fontSize: 20, color: MIST, lineHeight: 1.6, fx: { enter: 'fade-up', order: 2 } }),
+ text({ x: 96, y: 644, w: 1000, h: 24, html: '→ ADVANCE · ESC OPENS THE EDITOR ON THIS VERY FILE', fontSize: 12, fontWeight: 700, letterSpacing: 3, color: 'rgba(255,158,138,0.85)', fx: { enter: 'fade-up', order: 3 } }),
],
})
@@ -79,7 +80,7 @@ const s2 = slide({
elements: [
...tiles({ x: 96, y: 120, w: 110, h: 110 }, { x: 226, y: 120, w: 70, h: 110 }, { x: 316, y: 120, w: 64, h: 64 }),
text({ x: 90, y: 280, w: 1100, h: 160, html: 'One file is the app.', fontSize: 84, fontFamily: FR, fontWeight: 900, color: '#fff', lineHeight: 1 }),
- text({ x: 96, y: 440, w: 1000, h: 130, html: 'Deck, viewer, presenter, editor, fonts, images, charts — all inside one ~400 KB HTML file that <b>saves itself</b>. Email it, AirDrop it, archive it for a decade. Every copy is the complete product.', fontSize: 21, color: MIST, lineHeight: 1.65, fx: { enter: 'fade-up' } }),
+ text({ x: 96, y: 440, w: 1000, h: 130, html: 'Deck, viewer, presenter, editor, fonts, images, charts — all inside one ~470 KB HTML file that <b>saves itself</b>. Email it, AirDrop it, archive it for a decade. Every copy is the complete product.', fontSize: 21, color: MIST, lineHeight: 1.65, fx: { enter: 'fade-up' } }),
text({ x: 96, y: 640, w: 900, h: 24, html: 'NOTHING TO INSTALL · NOTHING TO EXPIRE · WORKS FROM file://', fontSize: 12, fontWeight: 700, letterSpacing: 3, color: MIST_DIM, fx: { enter: 'fade-up', order: 2 } }),
],
})
@@ -103,15 +104,20 @@ const s3 = slide({
const s4 = slide({
id: 'an-collab', background: INK, transition: 'fade',
- notes: 'Collaboration without accounts: keys are minted client-side at document creation and live in the file. The relay stores ciphertext and learns nothing — its source is about one file, read it. Offline edits merge back through our own CRDT (character-level text merging included), verified by a convergence rig across hundreds of thousands of checks.',
+ notes: 'Collaboration without accounts: keys are minted client-side at document creation and live in the file. The relay stores ciphertext and learns nothing. Read-only copies are CRYPTOGRAPHICALLY signed to read-not-write — the room id commits to an ECDSA writer public key, and the blind relay drops any unsigned mutating frame at the edge. Enforced, not an honour-system flag; no permissions table to misconfigure. Offline edits merge back through our own CRDT (character-level text merging), verified by a convergence rig across hundreds of thousands of checks.',
elements: [
kick(96, 96, 'TOGETHER, LIVE'),
- text({ x: 90, y: 140, w: 1100, h: 200, html: 'The file is<br>the invitation.', fontSize: 76, fontFamily: FR, fontWeight: 900, color: '#fff', lineHeight: 1.02 }),
- text({ x: 96, y: 360, w: 1000, h: 90, html: 'Start a live session and send the file — anyone who opens a copy joins. <b>E2EE</b>, keys never leave the file, and offline edits merge back both ways when people return.', fontSize: 20, color: MIST, lineHeight: 1.6, fx: { enter: 'fade-up' } }),
- ...[['E2EE', 'AES-GCM, keys in your file'], ['BLIND RELAY', 'stores ciphertext, learns nothing'], ['OWN CRDT', 'char-level merges, fuzz-tested']].map(([h, b], i) => [
- rect({ x: 96 + i * 372, y: 490, w: 340, h: 120, fill: PANEL, radius: 16, fx: { enter: 'fade-up', order: i + 1 } }),
- text({ x: 120 + i * 372, y: 512, w: 292, h: 30, html: h, fontSize: 14, fontWeight: 800, letterSpacing: 3, color: PEACH, fx: { enter: 'fade-up', order: i + 1 } }),
- text({ x: 120 + i * 372, y: 546, w: 292, h: 50, html: b, fontSize: 15, color: MIST, lineHeight: 1.45, fx: { enter: 'fade-up', order: i + 1 } }),
+ text({ x: 90, y: 140, w: 1100, h: 180, html: 'The file is<br>the invitation.', fontSize: 76, fontFamily: FR, fontWeight: 900, color: '#fff', lineHeight: 1.02 }),
+ text({ x: 96, y: 350, w: 1080, h: 120, html: 'Start a live session and send the file — anyone who opens a copy joins. <b>E2EE</b>, keys never leave the file, offline edits merge both ways — and read-only copies are <b>cryptographically</b> signed to read-not-write, enforced at the relay, not by courtesy.', fontSize: 20, color: MIST, lineHeight: 1.55, fx: { enter: 'fade-up' } }),
+ ...[
+ ['E2EE', 'AES-GCM; keys live in your file'],
+ ['BLIND RELAY', 'stores ciphertext, learns nothing'],
+ ['SIGNED WRITES', 'read-only enforced by ECDSA'],
+ ['OWN CRDT', 'char-level merges, fuzz-tested'],
+ ].map(([h, b], i) => [
+ rect({ x: 96 + i * 278, y: 500, w: 254, h: 118, fill: PANEL, radius: 16, fx: { enter: 'fade-up', order: i + 1 } }),
+ text({ x: 120 + i * 278, y: 522, w: 206, h: 28, html: h, fontSize: 13, fontWeight: 800, letterSpacing: 2, color: PEACH, fx: { enter: 'fade-up', order: i + 1 } }),
+ text({ x: 120 + i * 278, y: 552, w: 206, h: 56, html: b, fontSize: 14, color: MIST, lineHeight: 1.4, fx: { enter: 'fade-up', order: i + 1 } }),
]).flat(),
],
})
@@ -141,15 +147,16 @@ const s6 = slide({
const s7 = slide({
id: 'an-honest', background: PANEL, transition: 'fade',
- notes: 'The honest slide. Undo during live collab is snapshot-based and can revert a collaborator’s concurrent edit to the same property (documented LWW compromise). Editing is desktop-first; phones view and present well. Fullscreen needs a user gesture. Files grow with embedded images. We would rather you hear it from us.',
+ notes: 'The honest slide. Undo during live collab is snapshot-based (LWW) and can revert a collaborator’s concurrent same-property edit — the CRDT still keeps everyone converged. Editing is desktop-first; phones view and present beautifully. Morph only animates elements that share an id across slides — a deliberate idiom, not automatic magic-move. Presence names are claims, not proofs; a named-identity SSO roster is roadmap (the read/write RBAC IS cryptographic, the identity layer is not yet). We would rather you hear it from us.',
elements: [
kick(96, 96, 'WHAT IT DOESN’T DO (YET)'),
text({ x: 90, y: 140, w: 1000, h: 110, html: 'The honest slide.', fontSize: 64, fontFamily: FR, fontWeight: 900, color: '#fff', lineHeight: 1 }),
- text({ x: 96, y: 280, w: 1040, h: 300, fontSize: 20, color: MIST, lineHeight: 1.9, fx: { enter: 'fade-up' }, html:
- '· Undo during live collab is snapshot-based — it can revert a peer’s concurrent edit<br>' +
- '· Editing is desktop-first; phones are for viewing and presenting<br>' +
- '· Fullscreen needs a user gesture; some embeds deny it (we degrade to tab mode)<br>' +
- '· Files grow with embedded images — no optimizer yet<br>' +
+ text({ x: 96, y: 280, w: 1060, h: 320, fontSize: 20, color: MIST, lineHeight: 1.85, fx: { enter: 'fade-up' }, html:
+ '· Undo under live collab is snapshot-based (LWW) — it can revert a peer’s concurrent edit<br>' +
+ '· Editing is desktop-first; phones view and present beautifully<br>' +
+ '· Morph only animates elements that <b>share an id</b> across slides — not automatic “magic move”<br>' +
+ '· Presence names are claims, not proofs — named-identity SSO is on the roadmap<br>' +
+ '· Files grow with embedded images and video — no optimizer yet<br>' +
'· Docs and Sheets don’t exist yet. Slides came first.' }),
text({ x: 96, y: 620, w: 1000, h: 30, html: 'TRADE-OFFS ARE DESIGN. WE’D RATHER DISCLOSE THAN DISAPPOINT.', fontSize: 12, fontWeight: 700, letterSpacing: 3, color: 'rgba(255,158,138,0.7)', fx: { enter: 'fade-up', order: 2 } }),
],
@@ -161,7 +168,7 @@ const s8 = slide({
elements: [
...tiles({ x: 540, y: 90, w: 200, h: 200 }, { x: 464, y: 210, w: 120, h: 180 }, { x: 700, y: 230, w: 120, h: 120 }),
text({ x: 140, y: 360, w: 1000, h: 130, html: 'One file. Yours. Forever.', fontSize: 74, fontFamily: FR, fontWeight: 900, color: '#fff', align: 'center', lineHeight: 1 }),
- text({ x: 140, y: 500, w: 1000, h: 60, html: '<b>bento.page</b> — the site &nbsp;·&nbsp; <b>bento.page/slides</b> — the app &nbsp;·&nbsp; the gallery — decks to steal', fontSize: 19, color: MIST, align: 'center', lineHeight: 1.6, fx: { enter: 'fade-up' } }),
+ text({ x: 140, y: 494, w: 1000, h: 60, html: '<b>bento.page</b> — site + gallery &nbsp;·&nbsp; <b>bento.page/slides</b> — the app &nbsp;·&nbsp; <b>MIT</b> — github.com/nyblnet/bento', fontSize: 18, color: MIST, align: 'center', lineHeight: 1.6, fx: { enter: 'fade-up' } }),
text({ x: 140, y: 600, w: 1000, h: 30, html: 'PRESS ESC AND SAVE A COPY — THIS ANNOUNCEMENT IS NOW YOUR DECK. FRESH IDENTITY INCLUDED.', fontSize: 12, fontWeight: 700, letterSpacing: 2.5, color: 'rgba(255,158,138,0.85)', align: 'center', fx: { enter: 'fade-up', order: 2 } }),
],
})