Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

docs: vault as a capability broker, and the segment question re-argued (#173)

nyblnetf51795b8e714
diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md
index 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 preview
diff --git a/docs/vault-broker.md b/docs/vault-broker.md
new file mode 100644
index 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.md
index 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 forward
revocation*.
-### 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's
job 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 and
edit 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.