Bento, the office suite that fits in a file
TypeScript mit-licenseofficeoffice-365office-suiteoffice-toolsoffice365open-sourcepowerpointself-hostedsingle-page-appslidesslideshareslideshowslideshow-galleryslideshow-makerslideshows
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
// What a copy of this space is allowed to carry.
//
// Sharing a space IS sending a file — there is no server that holds the
// document and no link that grants access to it. So every question about
// permission is really a question about which fields survive the copy, and
// this module is the one place that answers it.
//
// THE FIELD THAT MATTERS. `doc.collab` is minted at CREATION for every space,
// and every field under it is a bearer capability:
//
// room + key the READ capability — decrypts every frame and every blob the
// relay has ever held for this room
// ownerPriv the OWNER key — writes, and REVOKES anyone else, including
// the person who sent the file
// writerPriv the pre-v2 room-wide write key
// invite.priv a delegation key: every device that opens a copy carrying it
// mints its own member key and joins through it
//
// "Invite someone…" used to be `saveAs('copy')`, which serializes
// `store.doc` — the WHOLE document, `collab` included. Everyone invited to a
// space therefore received `ownerPriv`: they could write (intended) and they
// could revoke the person who had invited them (not intended, and not
// recoverable — the owner key is the root of trust for the room and the file
// is already on someone else's disk). The button's hint said "Saves a copy
// that joins this session", which is true and is not the whole truth.
//
// bento/slides mints a SCOPED invite instead, and this module is that same
// answer bound to a space. The two apps deliberately produce the same shapes:
// the relay verifies one wire format (docs/collab-design.md, "Phase 1 wire
// format"), and a second local description of what an invite is would be how a
// client and the deployed worker drift apart.
import { mintInvite } from '../../kernel/src/sync/online.ts'
import { projectForCopy, type FieldsOfClass } from '../../kernel/src/docfields.ts'
import type { SpacesDoc } from './model.ts'
import { SPACES_FIELDS } from './docclass.ts'
/**
* A share export's filename suffix — also what the UI calls the copy.
*
* `reading` is the SEALED one and is built in reading.ts, not here: it keeps no
* room (the kernel's `package` tier), so it is not a question about which
* collaboration fields survive. It is named in this union because the three of
* them are one menu and one write path, and a fourth kind added elsewhere would
* type-check against neither.
*/
export type ShareKind = 'invite' | 'viewonly' | 'reading'
/** A deep clone, so nothing done to a copy can reach the open document. */
const clone = (doc: SpacesDoc): SpacesDoc => JSON.parse(JSON.stringify(doc)) as SpacesDoc
/** Is this copy the room's owner — the only role that can mint or revoke? */
export function isOwner(doc: SpacesDoc): boolean {
const c = doc.collab
return !!(c && c.v === 2 && c.owner && c.ownerPriv)
}
/**
* May THIS COPY write to its room? The one answer every gate in spaces asks.
*
* An ALLOWLIST, and the shape is the point. This used to be
* `role !== 'reader'`, which answers "yes" for every role invented after it —
* so when the kernel added 'audience' (a live-show member whose transport is
* receive-only), an audience copy opened in spaces got writer chrome and made
* local commits the relay then refused. Failing CLOSED is the safe direction:
* a future role that can write shows view-only until it is taught here, a
* visible and harmless bug; the old shape's failure was invisible.
*
* Absent means writer because every file older than the role field is one —
* the owner copy included, which is marked by `ownerPriv`, not by a role.
* Read as an OWN property, so nothing inherited can answer for the file.
* Same shape and name as type's (type/src/model.ts).
*/
export function copyCanWrite(collab: SpacesDoc['collab'] | undefined): boolean {
if (!collab || typeof collab !== 'object') return false
if (!Object.prototype.hasOwnProperty.call(collab, 'role')) return true
return collab.role === undefined || collab.role === 'writer'
}
/** Can this copy write at all? A reader copy holds no signing key. */
export function canWrite(doc: SpacesDoc): boolean {
return copyCanWrite(doc.collab)
}
/**
* A copy that edits this space live — WITHOUT becoming its owner.
*
* The copy carries an owner-signed INVITE (a delegation keypair) in place of
* the owner's private key. Every device that opens it mints its own member
* key and joins through the owner → invite → member signature chain, which the
* relay verifies while the owner is offline. Two consequences the owner keeps:
* one device can be removed from the People list without disturbing anyone
* else, and revoking the invite cuts off every copy descended from it.
*
* Strip FIRST, then delegate. The invite is the only private material an
* editor copy may carry, and a stray `writerPriv` left over from a pre-v2 mint
* would be a second, UNREVOKABLE way into the room.
*
* Returns null when this copy is not the owner: a member copy cannot mint an
* invite, because it does not hold the key the chain is rooted in.
*/
/** The fields the map classes 'history' (`revisions`, `trail`), READ from
* SPACES_FIELDS — never a hand list, so a history field added later is
* covered by the invite's "Leave version history out" the day it is declared. */
export type HistoryField = FieldsOfClass<typeof SPACES_FIELDS, 'history'>
export const HISTORY_CLASS: readonly HistoryField[] = (Object.keys(SPACES_FIELDS) as Array<keyof typeof SPACES_FIELDS>)
.filter((k): k is HistoryField => SPACES_FIELDS[k] === 'history')
/** Does this space carry any history an invite would hand over? */
export function hasHistory(doc: SpacesDoc): boolean {
return HISTORY_CLASS.some((k) => (doc as Record<string, unknown>)[k] !== undefined)
}
export interface InviteOpts {
/**
* Keep the history class in the copy — the kernel's invite rule, and the
* default. `false` is the inviter's "Leave version history out": the copy is
* the invite tier exactly, minus every field classed 'history'. History
* remembers text that was deleted, and an invite is a file for someone else.
*/
withHistory?: boolean
}
export async function inviteCopy(doc: SpacesDoc, opts: InviteOpts = {}): Promise<SpacesDoc | null> {
const c = doc.collab
if (!c?.room || !c.key || !isOwner(doc)) return null
const invite = await mintInvite(c.ownerPriv!, 'writer')
// Built FROM EMPTY by the kernel's copy table, tier 'invite' (docfields.ts):
// collab goes through collabForInvite — room/read-key/public keys + sync, the
// FRESH invite and the role from it, never the source's private halves or
// anything unknown under it. The modes are dropped (template:true would make
// the invitee's open a roomless new space), the history travels, and any
// top-level key this build does not declare stays behind.
const out = projectForCopy(clone(doc), SPACES_FIELDS, 'invite', { invite })
// the one thing a space adds: the copy is live from the moment it opens
if (out.collab) out.collab.on = true
// the inviter chose to leave history out: drop it by CLASS, not by name
if (opts.withHistory === false) for (const k of HISTORY_CLASS) delete (out as Record<string, unknown>)[k]
return out
}
/**
* A copy that FOLLOWS this space and can never change it.
*
* It keeps the room, the read key and the public keys, and drops every private
* half — so it decrypts everything the room holds and can sign nothing. That
* is what makes this a real boundary rather than a hidden button: the relay
* pins a verified key per socket, a socket that presents no key is read-only,
* and any op batch it sends is dropped before it is stored or fanned out
* (docs/collab-design.md, "Signed writes"). The editor lock this copy opens
* with is a courtesy to the reader, not the enforcement.
*
* `sync` goes too: the stamped CRDT state is this replica's, and a viewer
* rejoining as a fork of it would be a fork nobody can merge back.
*/
export function readerCopy(doc: SpacesDoc): SpacesDoc | null {
const c = doc.collab
if (!c?.room || !c.key) return null
// Built FROM EMPTY by the kernel's copy table, tier 'reader' (docfields.ts):
// collab goes through collabForReader — room/read-key/public keys, role
// forced to 'reader', every private half, the sync stamp and anything
// unknown under it dropped. `readonly` is SET (the copy is a reading copy
// even to a build that knows no roles), `template` is dropped (it would
// fork the copy out of its room on open), and the in-file history and any
// top-level key this build does not declare stay behind.
const out = projectForCopy(clone(doc), SPACES_FIELDS, 'reader')
// the one thing a space adds: the copy is live from the moment it opens
if (out.collab) out.collab.on = true
return out
}
/**
* Write this replica's CRDT state into `doc.collab.sync`, immediately before
* the document is taken for a write of THIS space — ⌘S, Save a copy, the
* invite, and both self-update writes.
*
* Why it matters: a saved file that carries the state rejoins its live session
* as a true FORK. Its registers defend the edits made while it was offline,
* relay replay is deduplicated by version vector instead of re-applied over
* them, and the kernel session sends a `snap` frame on rejoin that merges the
* fork into every peer, both ways. A file saved WITHOUT it reopens as a fresh
* adopt: its offline edits are already in the shadow, so no op is ever minted
* for them and no peer ever sees them (scripts/test-sync-spaces-session.ts,
* "a saved file rejoins as a fork", measures exactly that under sabotage).
*
* The kernel's `stampInto` already refuses a document with no session
* (`collab` absent or `on: false`). This adds the one rule a space needs on
* top: a store opened READ-ONLY never stamps. All three ways to get there
* mean the file's `sync` is not ours to rewrite —
*
* · frozen written by a newer build: whatever `sync` it carries may be
* a SYNC_V this build cannot read, and the format promise is
* that an unknown field survives a round trip untouched
* · reader copy `readerCopy()` removed `sync` on purpose; a viewer that
* rejoined as a fork of itself would be a fork nobody can merge
* · `readonly` a sealed reading copy has no session to rejoin
*
* and a read-only store has made no edits of its own to defend.
*
* Copies that are NOT this replica never reach here and carry no state: the
* page extract and "Copy document JSON" drop `collab` whole, "Duplicate as a
* new space…" is a new identity (`duplicateAsNew`), and the view-only copy
* clears `sync` in `readerCopy()`.
*/
export function stampSync(
store: { readonly readOnly: boolean; readonly doc: SpacesDoc },
session: { stampInto(doc: SpacesDoc): void } | null | undefined,
): void {
if (!session || store.readOnly) return
session.stampInto(store.doc)
}
/**
* "Duplicate as a new space…": the same pages under a NEW identity.
*
* A fresh `docId` and no `collab` at all — not even the stamped `sync`. The
* duplicate must never meet the space it came from: the docId keys the
* same-machine channel, the room keys the relay, and the stamped state would
* make it rejoin the ancestor's room as a fork of it. It mints credentials of
* its own when it is first opened, exactly as a new space does.
*/
export function duplicateAsNew(doc: SpacesDoc, docId: string, now = new Date().toISOString()): SpacesDoc {
// the kernel's copy table, tier 'duplicate': docId and collab are RESET
// (omitted) and everything else — modes, history, undeclared keys — is the
// owner's own and travels. The caller mints the new identity.
const out = projectForCopy(clone(doc), SPACES_FIELDS, 'duplicate')
out.docId = docId
out.modified = now
return out
}
/**
* Is this copy a live viewer — one that follows the session read-only?
*
* Distinct from `doc.readonly` alone, which is a SEALED reading copy with no
* session at all. Both lock the editor; only this one keeps receiving. (A
* view-only copy carries `readonly: true` too — the kernel's copy table sets
* it — so a role this decides on is asked before the mode is.)
*/
export function isReaderCopy(doc: SpacesDoc): boolean {
// Every collab copy that is not an allowlisted writer — 'reader', 'audience',
// and any role not yet invented. No collab at all is a plain file: editable.
return !!doc.collab && !copyCanWrite(doc.collab)
}
/**
* A short, readable fingerprint of a public key.
*
* Rendered identically in both apps on purpose: two people comparing codes
* over a call are verifying an identity out-of-band, and a code that is
* grouped differently in each app is a code they cannot compare.
*/
export const fingerprint = (pub?: string): string =>
pub ? `${pub.slice(0, 4)}·${pub.slice(4, 8)}·${pub.slice(8, 12)}` : ''