Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
docs: vault as a capability broker, and the segment question re-argued (#173)
nyblnetf51795b8e714
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.mdindex 626b0bcd..5bdb19b3 100644--- a/docs/DECISIONS.md+++ b/docs/DECISIONS.md@@ -14,6 +14,55 @@ Decision. Why. Pointers.---+## 2026-07-28 — Vault is a capability broker; identity is multi-user from commit one++**Refines the 2026-07-27 vault entry rather than superseding it.** Three+capabilities arrived separately — AI, live data, key distribution — and are one+shape: **vault brokers what a travelling file structurally cannot hold** (a+secret, a private network, an authority). That definition is the test for what+belongs in vault and what does not.++Settled, with mechanism in `docs/vault-broker.md`:++- **Vault configuration lives in the SHELL, never the document** — a second+ plaintext `#bento-vault` block under the same splice contract. In the document+ it would travel with the content and leak an internal hostname to anyone+ emailed a deck. "Export for outside" strips it, visibly.+- **A minted shell points its update channel at the vault.** Not a choice:+ `serializeWith(shell, doc)` (`kernel/src/save.ts:322`) re-splices into a+ freshly fetched shell and discards everything else, so shell config survives an+ update only if the update comes from the vault. Needs a visible "return to+ upstream" escape so a defunct vault cannot freeze former employees' files.+- **Dual signatures.** Canonical runtime = the file minus `#bento-doc` and+ `#bento-vault`; its sha256 must match upstream's signed manifest, and the vault+ signs its config BOUND to that hash. A compromised vault can then redirect+ endpoints but cannot ship modified editor code. Build in v1 — unaddable later.+- **Documents carry a query NAME, never query text.** The vault maps names to+ parameterised statements defined by an admin. Otherwise every deck anyone opens+ is an exfiltration tool against the database.+- **A bound document always carries its last known values.** A vault connection+ refreshes data, never supplies it, or "works with no network" falls by another+ route.+- **A vault refresh is a COMMIT, not a derivation.** Linked charts derive+ identically on every replica today; a fetch does not (two replicas fetching at+ different moments get different rows). Extend `scripts/test-sync.ts` first.+- **Archival is reinstated; backup stays cut.** Different products. Copying bytes+ is solved; being able to OPEN them in ten years is not, and a Bento archive+ renders itself and stays machine-readable as plaintext JSON with no vendor in+ the loop. Vault produces the archive shape; restic moves it.++**Who it serves, re-argued and resolved.** Three of the capabilities (live data,+retention archive, private release channel) are properties of a DEPLOYMENT rather+than a person, so the org case got stronger; the case against did not weaken,+because it rests on maintenance surface — every org-shaped pillar implies+multi-user identity, and that is what a single maintainer carries indefinitely.+Resolution: this decides what we PROMISE, not what we build — broker, index and+archive serve one user and fifty identically. Ship single-user and promise+nothing organisational, **but design the identity model multi-user from the first+commit**: per-user query authorisation and spend attribution cannot be retrofitted+without migrating every deployed vault. The gate for building organisational+features is a real stated requirement, not a count of pillars.+## 2026-07-27 — Thumbnails: plain markup plus a parser-blocking remover, NOT `<noscript>`**Supersedes the 2026-07-26 entry below** on the one point of where the previewdiff --git a/docs/vault-broker.md b/docs/vault-broker.mdnew file mode 100644index 00000000..83d63fb5--- /dev/null+++ b/docs/vault-broker.md@@ -0,0 +1,256 @@+# bento/vault — the broker mechanism++*Design document, 2026-07-28. Status: **proposed** — nothing built. Companion to+`vault-design.md` (what vault is and who for). This document specifies the four+mechanisms that follow from one idea: **vault brokers the capabilities a+travelling file structurally cannot hold.***++Nothing here is required for a Bento document to work. A file with no vault+configuration behaves exactly as it does today, forever — that is invariant 2 of+`vault-design.md` and every mechanism below is designed around it.++---++## 1. Vault-minted shells: where configuration lives++A vault mints `.bento.html` shells carrying its own identity, so a document knows+which vault to ask without anyone typing a URL.++### Branding needs no new mechanism++"Customised for that vault" in the *visual* sense — the org's fonts, theme,+layouts, starter deck — is already expressible: `doc.theme`, `doc.fonts` and+`doc.layouts` exist in the format. A vault serves a starter document with the+org's layouts baked in and nothing new is required. **Only endpoint and trust are+new.**++### Configuration lives in the SHELL, not the document++The document must stay clean. Put vault configuration in `#bento-doc` and it+travels with the content: email a deck to a client and you have shipped your+internal vault hostname with it. Keep it in the shell and a document exported for+outside use is just a document.++A second plaintext block, sibling to `#bento-doc` and subject to the same splice+contract (`PLATFORM.md` §2 — plaintext, stable id, survives+DOMParser→splice→outerHTML, never contains `</script>`):++```html+<script type="application/bento+json" id="bento-vault">+{+ "v": 1,+ "url": "https://vault.example.internal",+ "pub": "<base64url SPKI of the vault's public key>",+ "name": "Example Ltd",+ "channel": "https://vault.example.internal/releases/slides/manifest.json",+ "sig": "<base64url signature, see §2>"+}+</script>+```++Rules:++- **Additive.** Absent block = today's behaviour exactly.+- **Never a secret.** This block is world-readable in every copy of the file. It+ carries a public key and a URL and nothing else, ever.+- **Strippable.** "Export for outside" removes the block. This must be a visible,+ named action, because the failure mode is silent.++### The update interaction, which is not optional to solve++`serializeWith(shell, doc)` (`kernel/src/save.ts:322`) re-splices the document+into a **freshly fetched shell** and discards everything the old shell carried.+So a vault-minted shell that checks `bento.page` loses its configuration on the+first update.++Therefore **a minted shell points `update.ts` at the vault's channel.** This is+self-consistent rather than a workaround: an org that mints shells wants to+control which build its people run.++Two consequences to design for:++- **Escape hatch.** If the vault goes away, the file still works — it is+ self-contained — but is pinned to that version. There must be a visible "return+ to the upstream channel" action. A company folding must not permanently freeze+ its former employees' documents.+- **Drift.** Org channels lag upstream, so upstream security fixes need a path+ that does not depend on an admin noticing. At minimum the client should surface+ "your channel is N releases behind" using upstream's manifest as a *read-only*+ reference, without switching channels on its own.++---++## 2. Dual signatures: verifying your employer shipped genuine Bento++Minting inverts the trust model. Today a user trusts an offline signing key held+by the project. In a minted shell they also trust their employer. That is normal+for managed software and unacceptable if it is invisible.++A reader must be able to verify two independent things:++1. **The runtime is genuine, unmodified Bento.**+2. **The configuration was authorised by the vault it names.**++### Canonicalisation++The minted file differs from upstream's bytes, so the whole-file hash in+upstream's manifest cannot match. Define a canonical form:++> **Canonical runtime** = the file with the `#bento-doc` and `#bento-vault`+> elements removed entirely, everything else byte-identical.++Then `sha256(canonical runtime)` must equal the `sha256` upstream published for+that version in its signed manifest. This reuses the existing manifest with no+new upstream machinery — `update.ts` already fetches and verifies it.++### What the vault signs++The vault signs over the config **bound to the runtime it was minted for**:++```+sig = ECDSA-P256( vaultPriv, "bento-vault-v1\n" ‖ runtimeHash ‖ "\n" ‖ canonicalJSON(config minus sig) )+```++Binding to `runtimeHash` is the point. Without it a vault's configuration block+could be lifted and replayed onto a modified runtime, and the signature would+still verify.++### Verification, and what it proves++| Check | Proves |+|---|---|+| canonical runtime hash ∈ upstream signed manifest | the editor is stock Bento, unmodified |+| vault signature verifies over (runtimeHash ‖ config) | the config is authorised *and* bound to this exact runtime |++Both must be surfaced in the UI — a named organisation and a key fingerprint,+visible before the document does anything on the network. "Managed by Example+Ltd" with a checkable fingerprint is honest; a silent redirect is not.++### Trust on first use++The vault's public key is pinned in the block itself, which alone proves nothing+— a hostile minter signs its own config happily. What the scheme *does*+guarantee is that the **runtime** is unmodified upstream Bento, which is the+property that actually protects the user. Recognising the *organisation* is+TOFU: record the fingerprint on first encounter and warn loudly if a later+document claims the same name with a different key.++### Supply chain, stated plainly++A compromised vault mints hostile configuration to everyone at once, and its+signing key is necessarily more online than the project's offline release key.+The runtime-hash binding contains the blast radius: a compromised vault can+redirect endpoints and exfiltrate what documents send, but **cannot ship modified+editor code without failing check 1**. That is the security argument for doing+the dual signature in v1 rather than adding it later.++---++## 3. Live data access++### Model++`TableElement` gains a source naming a query the vault holds:++```ts+source?: {+ query: string // a NAME, never query text+ params?: Record<string, string>+ fetchedAt?: string // ISO timestamp of the embedded values+}+```++The table's `rows` continue to hold real values at all times — the fetch+*replaces* them. Everything downstream is already built: `syncLinkedChart`+(`model.ts:628`) pushes labels and numeric columns into a bound chart's option in+place, and the editor re-derives on the `doc` event.++### Named queries only++A document carries a query *name*. The vault maps names to statements, defined by+an administrator, parameterised, with the parameter types declared. **A document+never carries SQL, a connection string, a URL, or anything else that determines+what runs.**++If documents could supply query text, every deck anyone opens becomes an+exfiltration tool against the database — including a deck emailed in from+outside. This is the single most important rule in the mechanism and it is free+at design time.++### Authorisation is per-user, from the first commit++The broker resolves *who is asking*, and the query runs with that identity's+permissions — never a shared service account. A sales deck bound to+`revenue_by_region` must return the asking user's regions.++v1 has one user and this looks like pointless ceremony. It is not: a+service-account-shaped broker has to be rewritten to become a per-user one, and+every deployed vault becomes a migration. This is the retrofit that+`vault-design.md` singles out as unaffordable to postpone.++### The offline rule++Invariant 7: **a bound document always carries its last known values.** The+connection refreshes; it never supplies. Rendering shows the embedded values+immediately and updates only if a refresh succeeds, with `fetchedAt` surfaced so+a reader knows how old the numbers are.++Stale-but-visible beats fresh-or-nothing for a document that might be presented+on a train.++### Collaboration: refresh is a commit, not a derivation++The existing pattern for linked charts is *derive-not-commit* — every replica+recomputes from the synced table, so no operations are needed and replicas agree+because the derivation is deterministic.++**A vault refresh is not deterministic.** Two replicas fetching at different+moments get different rows. So a refresh must be performed by one actor and+**committed as an ordinary edit**, replicating through the CRDT like any other+change to `rows`. Deriving independently on each replica is permanent divergence.++Extend `scripts/test-sync.ts` before this merges. The convergence rig has caught+this class repeatedly and will not catch it unless it is taught to.++---++## 4. The archive shape++Not a backup product. Backup is solved — restic, borg, ZFS, object storage — and+building it would be building a worse version of mature software.++What vault produces is an **archive that does not need us to exist**:++```+archive/+ manifest.jsonl # append-only, one JSON object per document version+ objects/+ <docId>/<sha256>.bento.html+```++- **One self-contained file per document version.** Each renders itself in a+ browser with nothing installed, and each carries its content as plaintext JSON+ in `#bento-doc` for machine reading without the runtime. That dual guarantee —+ human-readable *and* machine-readable, with no vendor in the loop — is the+ entire value proposition, and no competitor's export format has it.+- **Append-only, content-addressed.** A version is written once under its own+ hash and never mutated. Suits object-lock/WORM storage directly, which is what+ retention regimes actually ask for.+- **A plaintext manifest**: `docId`, content hash, title, timestamp, author,+ retention class. Greppable with no tooling, in twenty years, by someone who has+ never heard of Bento.+- **Backup is someone else's job.** Point restic or S3 lifecycle rules at the+ directory. Restore is copying files back — or just opening one.++### Open questions++- **Encrypted documents archive as ciphertext.** Retention of encrypted decks+ therefore implies key escrow, which is a real organisational decision with real+ consequences. It must be an explicit choice at configuration time and must+ never be defaulted silently in either direction.+- **What is a "version" worth keeping?** Every save is too many; every manual+ save may be too few. Probably a retention policy per class, but this needs a+ real requirement from a real organisation before being invented.+- **Deletion under retention.** GDPR erasure and WORM retention conflict by+ construction. Any system offering retention has to answer this; we do not yet+ have an answer, and inventing one without a real requirement would be guessing.diff --git a/docs/vault-design.md b/docs/vault-design.mdindex 2179479e..e6b703da 100644--- a/docs/vault-design.md+++ b/docs/vault-design.md@@ -36,19 +36,79 @@ structurally cannot make — while any document remains exportable as a standalo## Who it is for-The individual and the organisation are the same software at different scales —-same index, same owner→invite→member key chain, same broker — but they are not-the same problem, and solving one does not deliver the other.--**Build for the individual first.** One person, several devices, a machine that-is usually awake, who already runs Ollama and resents that their decks are-scattered across three laptops. That is the smallest deployment that exercises-every part of the design, and it is buildable by one maintainer.--**The organisation is the destination, not the first release.** Architecturally-this costs nothing: a single-user vault *is* the org vault with one user — same-index, same key chain, same broker. Build that, design toward multi-user,-promise neither.+*Re-argued 2026-07-27 after three org-shaped capabilities surfaced that the+first pass did not have in view. The earlier answer — "build for the individual,+the organisation is the destination" — was reached before them and is restated+here at full strength on both sides rather than quietly amended.*++### The case for the organisation++Four of the five things vault does are worth little to one person and a great+deal to a company:++- **Live data access.** A chart bound to the company's warehouse. An individual+ has no warehouse.+- **Retention archive.** Regulated retention is a compliance obligation, not a+ preference. Individuals use Time Machine.+- **Private release channel.** Controlling which build your people run is+ meaningless at one seat.+- **Central AI credential and spend control.** One person can put a key in an+ environment variable.++Only **search** is genuinely individual, and even there the value grows with the+number of documents *other people* wrote.++What these have in common is that they are properties of a *deployment*, not of+a person: retention is a compliance obligation on an organisation, and a data+connector is a platform capability. Both tend to arise where the documents+cannot go into SaaS at all — the same constraint that makes self-hosting a+requirement rather than a preference.++### The case against++The people actually using Bento today are individuals and very small groups, and+every org-shaped pillar above implies the expensive part — **multi-user+identity**: per-user query authorisation, per-user spend attribution, roles,+audit. That, not the broker, is the real cost of serving organisations, and it+is a maintenance surface a single maintainer carries indefinitely.++And the org case is currently reasoning, not evidence: it was derived from the+shape of the capabilities, not from a stated requirement.++### The resolution++The segment question does not decide what to *build* — it decides what to+**promise**, what to **name**, and when to take on multi-user identity. On the+build order these agree: the broker, the index and the archive are foundational+and serve one user and fifty identically.++So:++1. **Ship single-user.** Promise nothing organisational.+2. **But design the identity model multi-user from commit one.** Per-user query+ authorisation and per-user spend attribution cannot be retrofitted — a+ service-account-shaped broker has to be rewritten to become a+ per-user-shaped one, and every deployed vault becomes a migration. This is+ cheap now and brutal later, and it is the one place where "we'll do it when+ someone asks" is the wrong answer.+3. **The gate for building organisational features is a real stated+ requirement**, not a count of pillars. One concrete retention or data+ requirement from an actual deployment settles in a week what this document+ cannot settle by argument.++## What vault is, stated as a pattern++Three capabilities arrived separately and turned out to be one shape. AI needed a+credential the file cannot carry. Live data needs a credential *and* network reach+the file cannot have. Key distribution needs an authority the file cannot be.++**Vault is the broker for capabilities a travelling file structurally cannot+hold.** That definition predicts rather than accumulates: it says what belongs in+vault (anything requiring a secret, a private network, or an authority) and what+does not (anything a file can do alone — which is everything else, and must stay+that way).++The mechanism is specified in `vault-broker.md`.## The pillars, ranked on evidence@@ -137,12 +197,79 @@ first conversation, not the fifth.If identity ever ships, call it what it is: *key distribution and forwardrevocation*.-### 5. Backup and version history — cut it--The audience runs restic, borg, ZFS and git, and `kernel/src/autosave.ts`-already ships version history. The one genuine gap — autosave's history is-per-device IndexedDB and dies with the browser profile — is a feature of the-vault, not a reason for it.+### 5. Live data access — the same pattern as the broker, and what makes dash real++A chart bound to the company's warehouse. The credential and the network reach+are both things a travelling file cannot have, so this is pillar 1 again with a+different secret.++**The invariant decides the design.** `PLATFORM.md` §1 forbids requiring a+network to open, edit or present — so a bound document **must always carry its+last fetched values as ordinary static data**. The connection only ever+*refreshes*; it never *supplies*. Otherwise the VPN drops mid-presentation and+the charts are empty.++The consequence is worth choosing rather than discovering: if the file caches the+values, emailing the deck emails the data. That is usually correct — it is a+document, and documents contain their content — and it is what lets a bound+dashboard render for a recipient with no login and no account. For genuinely+sensitive sources a refresh-only mode is possible, at the cost of rendering+nothing offline. Default to embedding; make the other mode explicit and visible.++The seam already exists: `ChartElement.source?: { tableId }` (`model.ts:228`) with+`syncLinkedChart` re-deriving on every `doc` event (`editor/editor.ts`). Give+`TableElement` a `source` naming a vault query and the refresh path is built.++Two things that bite if not decided up front — **named queries only** (a document+references a query an admin registered; it never carries query text, or any deck+anyone opens becomes an exfiltration tool), and **a vault refresh must be+committed by one actor** under collab rather than derived per-replica, because+two replicas fetching at different moments get different rows and diverge.+Details in `vault-broker.md`.++### 6. The private release channel — a consequence of minting shells++If a vault mints shells carrying its own configuration, it is already an update+channel, because `serializeWith(shell, doc)` (`kernel/src/save.ts`) re-splices+the document into a *freshly fetched* shell and discards everything else. Shell+configuration survives an update only if the update comes from the vault.++That falls out as a feature rather than a cost: controlling which build your+people run, staging rollouts, and not shipping an untested version on a Friday+are ordinary organisational requirements. The machinery exists — `update.ts`+already verifies a signed manifest and already supports being pointed elsewhere.+What is new is a second trust anchor and the dual-signature scheme in+`vault-broker.md`, which exists so a user can verify their employer shipped+genuine unmodified Bento.++### 7. Retention archive — reinstated, and distinguished from backup++*This was previously cut outright. That was right about backup and wrong about+archival, and the two are not the same product.*++**Backup stays cut.** Copying bytes is solved by restic, borg, ZFS and object+storage, and building it would be building a worse version of mature software.++**Archival is different, and Bento is structurally better at it than anything+else in this market.** The hard problem in regulated retention is not storing+bytes for ten years — it is *being able to open them* in ten years. Every+competitor's answer requires their software to still exist and still be licensed:+a Confluence dump needs Confluence, a SharePoint archive needs SharePoint, a+Notion export loses fidelity on the way out.++A Bento archive renders itself, and carries a second guarantee underneath: even+if browsers change beyond recognition, `#bento-doc` is plaintext JSON, so the+content stays machine-readable without the runtime. Human-readable *and*+machine-readable, with no vendor in the loop.++This is cheap precisely because it is not a backup product: make the library a+well-formed self-describing archive — one self-contained file per document,+append-only, content-addressed, with a plaintext manifest — and let existing+tools move the bytes. Shape in `vault-broker.md`.++Unresolved: an encrypted deck archives as ciphertext, so retention of encrypted+documents implies key escrow. That is an organisational decision with real+consequences and must not be defaulted silently.## Licence@@ -163,6 +290,11 @@ relicense slides.visible endpoint indicator, and a readable log of what was sent where.5. **The relay only ever sees ciphertext**, in every deployment.6. **Never remove a capability a release has already shipped.**+7. **A bound document always carries its last known values.** A vault connection+ refreshes data; it never supplies it. A document whose charts are empty+ without a network has broken invariant 2 by another route.+8. **A document never carries query text, only a query name.** The vault decides+ what a name means. Anything else makes every deck an exfiltration tool.## Sequencing@@ -175,10 +307,20 @@ relicense slides.is indexed, so page one is already searchable with no server. The indexer'sjob is therefore slides 2..n, not the library.3. **The index**, local and rebuildable from the files.-4. **The broker**, off by default, framed as plumbing.-5. **Vault as an MCP server** over the library, so existing agents can search and+4. **The broker**, off by default, framed as plumbing — **with the per-user+ authorisation model in place from the first commit** even though v1 has one+ user. See "Who it is for": this is the single thing that cannot be retrofitted+ without a migration on every deployed vault.+5. **Live data access** on top of the broker, named queries only.+6. **The archive shape** — append-only, content-addressed, self-describing. Cheap+ once the index exists, and the pillar most likely to attract a real requirement.+7. **Shell minting and the private release channel**, with dual signatures.+8. **Vault as an MCP server** over the library, so existing agents can search andedit decks with no bespoke integration on either side.-**Defer:** multi-user, SSO, RBAC, audit, the dead-drop, NAT traversal.+**Defer:** SSO, RBAC, audit export, the dead-drop, NAT traversal.+Note that *multi-user identity* moves from "defer" to "design now, ship later" —+deferring the feature is fine, deferring the shape is not.+**Never build:** a feature gate inside a document file, a cloud-only relay, a-general RAG product, backups.+general RAG product, backups, or a query path that accepts document-supplied SQL.