Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

Say that a deck carries its own keys, before an agent reads it (#280)

nyblnetf9ef450d7e09
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 44556043..3511c8a8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,20 @@ pre-1.0.
## [Unreleased]
+- **A deck that is being shared now says so before an agent reads it.** A file
+ with live collaboration switched on carries the keys to its own session —
+ that is what makes sharing work without accounts, and it means anything
+ receiving the file receives the room: a chat, a ticket, an agent harness.
+ Nothing about a document looks like a credential, so this was easy to do by
+ accident.
+
+ The agent guide and the packaged skill now open by checking for it and
+ saying so, and `window.bento.validate()` reports it as
+ `collab-secrets-present` — only when private key material is actually there,
+ so a read-only copy stays quiet. Removing the keys afterwards does not
+ retract them; if a shared deck has already gone somewhere, *Share → Rotate
+ keys* is the remedy.
+
- **Hide a slide from the show.** Toggle *Hide slide* in the Slide panel and it
stays in the deck, fully editable, but drops out of the walk: arrow keys pass
over it, PDF export leaves it out, and it is never picked as the file's
diff --git a/docs/agents.md b/docs/agents.md
index cec99c20..62688ffb 100644
--- a/docs/agents.md
+++ b/docs/agents.md
@@ -57,6 +57,34 @@ lives in ONE plaintext block near the top:
</script>
```
+> ### Before you read a deck: it may carry its own keys
+>
+> If a deck has live collaboration switched on, its `#bento-doc` block contains
+> the credentials to that session — the room key, and depending on the copy, a
+> writer or owner private key. That is deliberate and it is what makes sharing
+> work without accounts: **the file is the invitation**, so opening a copy joins
+> the room.
+>
+> The consequence is easy to miss, because nothing about a document looks like a
+> credential. Anything that receives the file receives the room: a chat, a
+> ticket, a harness, a model provider's logs. Not because anything is broken —
+> that is simply what the file is.
+>
+> **So, before you take a deck into your context:**
+>
+> 1. Look for a `"collab"` key in the document. No `collab`, or a `collab` with
+> no `ownerPriv` / `writerPriv` / `invite`, and there is nothing to leak.
+> 2. If those are present, **say so before continuing.** The person may not know
+> their deck is live, and they are the only one who can decide.
+> 3. Prefer a copy that carries no keys: *Save ▾ → Save read-only copy…* or
+> *Share → Stop sharing* on a duplicate. In the browser,
+> `window.bento.validate()` reports this as `collab-secrets-present`.
+>
+> Editing the JSON in place is fine and does not change any of this — the
+> exposure is in *reading* the file, not writing it. And note that removing the
+> keys after the fact does not retract them: if a shared deck has already gone
+> somewhere, the remedy is *Share → Rotate keys*, which revokes the old room.
+
Two ways to work with it:
1. **File harness** (Claude Code, agent sandboxes): edit the JSON inside the
diff --git a/plugins/bento-slides/skills/bento-slides/SKILL.md b/plugins/bento-slides/skills/bento-slides/SKILL.md
index e61577b5..fbe033ff 100644
--- a/plugins/bento-slides/skills/bento-slides/SKILL.md
+++ b/plugins/bento-slides/skills/bento-slides/SKILL.md
@@ -67,6 +67,15 @@ looked at is not finished.
1. **Find the document.** Locate the `#bento-doc` block; parse its JSON. Note
`doc.size` (canonical 1280×720), `doc.theme`, existing element `id`s, and
whether `doc.template`/`doc.readonly` are set.
+
+ **Check `doc.collab` first.** If it carries `ownerPriv`, `writerPriv` or
+ `invite`, this deck's live-session keys are in the file you are about to read
+ — and anything that receives the file or its JSON can join that session and
+ write to it. That is by design: the file is the invitation. **Tell the user
+ before you continue**, because only they can decide, and they may not know
+ the deck is shared. Offer the alternative: a read-only copy, or *Share → Stop
+ sharing* on a duplicate. If it has already gone somewhere, the remedy is
+ *Share → Rotate keys* — removing the keys afterwards does not retract them.
2. **Read the source material the user gave you** and classify each piece —
is it a stat? a table? a process? a definition to expand? a photo?
3. **Map material → feature (do NOT default to bullet text).** This is the
diff --git a/scripts/test-validate.ts b/scripts/test-validate.ts
index ad19229d..2bfc93d8 100644
--- a/scripts/test-validate.ts
+++ b/scripts/test-validate.ts
@@ -217,5 +217,25 @@ ok(unreachable(clean).length === 0, 'an ordinary deck reports nothing')
ok(validateDoc(hiddenDoc('s2'), { measure: false }).ok,
'hiding a slide is never an error')
+// ------------------------------------------------- live-session keys in a file
+// The capability nobody can see. A shared deck's file grants write access to
+// whoever holds it, which is the design — but it is invisible in the JSON's
+// shape, so the one place it can be surfaced is a check an agent runs.
+const withCollab = (collab: unknown): BentoDoc => ({ ...clean, collab } as any)
+const secretsFound = (d: BentoDoc) => validateDoc(d, { measure: false })
+ .findings.filter((f) => f.code === 'collab-secrets-present')
+
+ok(secretsFound(withCollab({ room: 'r1', key: 'k', ownerPriv: 'X' })).length === 1,
+ 'an owner private key in the document is reported')
+ok(secretsFound(withCollab({ room: 'r1', key: 'k', writerPriv: 'X' })).length === 1,
+ 'a writer private key is reported')
+ok(secretsFound(withCollab({ room: 'r1', key: 'k', invite: { pub: 'a', priv: 'b' } })).length === 1,
+ 'invite delegation material is reported')
+ok(secretsFound(withCollab({ room: 'r1', key: 'k', role: 'reader' })).length === 0,
+ 'a reader copy — room and read key, no private material — is NOT reported')
+ok(secretsFound(clean).length === 0, 'a deck that was never shared is not reported')
+ok(validateDoc(withCollab({ room: 'r1', key: 'k', ownerPriv: 'X' }), { measure: false }).ok,
+ 'carrying your own room keys is never an error — it is how a working file works')
+
console.log(`\n${checks - failures}/${checks} checks passed`)
if (failures) process.exit(1)
diff --git a/slides/src/validate.ts b/slides/src/validate.ts
index 255280b0..7f63a3bb 100644
--- a/slides/src/validate.ts
+++ b/slides/src/validate.ts
@@ -156,6 +156,25 @@ export function validateDoc(doc: BentoDoc, opts: ValidateOpts = {}): ValidateRes
message: `Font "${f.family}" points at asset "${f.asset}", which is not in doc.assets — the face will not load and text falls back silently.` })
}
}
+ // A live-shared deck carries the keys to its own room — that is how opening a
+ // copy joins a session with no account and nothing to configure. The file IS
+ // the invitation, and that is deliberate.
+ //
+ // It is also invisible. Nothing on screen and nothing in the JSON's shape says
+ // "this document grants write access to whoever holds it", so anyone handing
+ // the file to a chat, a ticket or an agent harness is transferring a
+ // capability while believing they are sharing a document.
+ //
+ // Reported only when PRIVATE material is present: a reader or invite copy has
+ // `collab` and no secrets, and flagging that would be noise. Info, not a
+ // warning — carrying these keys in your own working file is correct.
+ const secrets = (['writerPriv', 'ownerPriv', 'invite'] as const)
+ .filter((k) => (doc.collab as Record<string, unknown> | undefined)?.[k])
+ if (secrets.length) {
+ add({ code: 'collab-secrets-present', severity: 'info', path: 'collab',
+ message: `This deck carries live-session private keys (${secrets.join(', ')}) — anything that receives this file or its JSON can join the room and write to it. Expected in your own working file; strip it (Save → a share copy, or Stop sharing) before handing the deck to a chat, a ticket or an agent.` })
+ }
+
const embedded = new Set((doc.fonts ?? []).map((f) => f.family.trim().toLowerCase()))
const seenFallback = new Set<string>()
const checkFamily = (stack: string | undefined, where: Omit<Finding, 'code' | 'severity' | 'message'>) => {