Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

Docs: record the blob-offload decision and changelog entry

nyblnet9c4b3e11ee38
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 8a8edc89..bf974c68 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,22 @@ pre-1.0.
## [Unreleased]
+- **Photos and video now work in live collaboration.** This finishes what
+ 1.0.9 could only warn you about: previously anything past about half a
+ megabyte was simply too big to send to your collaborators. Now a large image
+ is uploaded once, encrypted, and everyone else pulls it down in the
+ background — so you can drop a full-resolution photo into a shared deck the
+ same way you would in a deck you're editing alone. A 3MB photo used to
+ produce a message the relay refused outright; it now travels as a reference
+ of about a hundred bytes.
+
+ As always the server never sees the picture: it is encrypted before it
+ leaves your machine, and the relay stores bytes it cannot read. Collaborators
+ on the same computer don't involve the relay at all. Small images are still
+ carried inside the document exactly as before, so nothing changes for
+ ordinary decks, and a self-hosted relay without blob storage keeps working —
+ it just falls back to the old inline-only behaviour.
+
## [1.0.9] — 2026-07-25
- **Fix: large text could silently kill live collaboration.** A text box of
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md
index ce061870..440f20e2 100644
--- a/docs/DECISIONS.md
+++ b/docs/DECISIONS.md
@@ -181,3 +181,31 @@ One HTML file = document + viewer + editor, working offline from file://.
The splice contract on `#bento-doc` is frozen forever (shipped updaters
depend on it). Everything else is negotiable; this isn't. See
docs/PLATFORM.md §1–2.
+
+## 2026-07-25 — Large assets travel out-of-band; the relay stays blind
+
+Assets over 64KB (`BLOB_INLINE_MAX`) no longer ride inside CRDT ops. They are
+encrypted client-side, uploaded once to the relay's R2 bucket, and referenced
+from the document by a content-addressed key; peers fetch and decrypt on
+receipt. This was forced by measurement, not preference: Durable Object storage
+values cap at ~2MB, so the previous inline path produced frames the relay
+accepted-then-dropped, and the client re-sent forever. Details and threat model
+in `docs/blob-offload.md`.
+
+Three properties are load-bearing and must not be traded away:
+
+- **The relay cannot read a blob.** It pipes ciphertext without buffering. The
+ key is `HMAC(roomKey, sha256(plaintext))`, so identical bytes dedupe *within*
+ a room and are unlinkable *across* rooms — a plain content hash would have
+ let the relay confirm two rooms hold the same file.
+- **R2 is optional.** Absent binding = `/b/` answers 501, clients inline small
+ assets and same-origin tabs still resolve from the local cache. A
+ self-hoster without a bucket degrades; they are not broken. This follows
+ from the relay being dumb infrastructure (see the vault entry).
+- **Failures are visible, never silent-but-wrong.** An unresolved blob leaves
+ the asset absent and renders empty rather than blank-looking-fine. The whole
+ change set exists because the old failure mode was invisible.
+
+Operational consequence: the relay must be deployed **before** a client that
+depends on the blob endpoints — the standing rule for this split, same as the
+keepalive and access-verification changes.