Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
docs: add public security explainer; refresh announcement deck builder
nyblnetcf729b3641d0
diff --git a/docs/security.md b/docs/security.mdnew file mode 100644index 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.mjsindex 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 · <b>bento.page/slides</b> — the app · 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 · <b>bento.page/slides</b> — the app · <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 } }),],})