Skip to content

armgit / bento

Public Imported from GitHub
0

Bento, the office suite that fits in a file

24.7 KB
Raw Blame
// SPDX-License-Identifier: MIT
// Copyright (c) 2026 The Bento authors
//
// Your documents — the thing the extension is actually for.
//
// The popup used to be a permissions control panel: "local file access is on,
// folder: documents". True, and nobody wants it. home/ios is a
// UIDocumentBrowserViewController — you see your documents and tap one — and
// that is the right shape here too. Permissions are plumbing and belong at the
// bottom, speaking only when broken.
//
// ENUMERATION IS FINE HERE, and that is worth saying because `background.js`
// went to some trouble to stop enumerating. The difference is who is waiting:
// resolving a SAVE must not walk a folder, because the user is mid-⌘S and a
// granted home directory would hang it. Listing is user-initiated, happens when
// the popup opens, is bounded, and its results are cached. Different job,
// different rules.

import { CACHE, GRANT, get, put, prefixes } from './db.js'
import { getGrants } from './status.js'
import { verifyManifest, fetchPinned, ACCEPT_BYTES } from './release.js'
// Not a third implementation: `update.js` already has the dotted-numeric
// compare, and it behaves the same as the kernel's — an unparsable component
// coerces to 0 rather than throwing, because `NaN || 0` is 0. A strange version
// string should be able to fail to RAISE the floor, never to block a release.
import { compareVersions } from './update.js'

/** How deep to look, and how many documents to show. A folder of documents is
 *  not a filesystem; someone who granted a home directory should get a useful
 *  list quickly rather than a complete one slowly. */
const MAX_DEPTH = 4
const MAX_DOCS = 300
/** How many unrecognised .html files to open and look inside, per listing. */
const MAX_SNIFFS = 400

/** Enough to reach the title, which sits in the `#bento-doc` block that starts
 *  a few KB in. Measured on a real deck: block at 5.8KB, title inside it. The
 *  block itself runs to megabytes when a document carries images, which is the
 *  trap an earlier metadata reader fell into — it looked for the CLOSING tag
 *  and so found nothing in any document with a picture in it. Reading a fixed
 *  head and matching the field directly avoids needing the end at all. */
const HEAD_BYTES = 300 * 1024

/** Named like one of ours. Free to decide — no read at all. */
const namedDoc = (name) => /\.bento\.html$/i.test(name)

/** Any other local page, which MIGHT be one of ours under a different name. */
const maybeDoc = (name) => /\.html?$/i.test(name) && !namedDoc(name)

/**
 * How much of a file to read before deciding whether it is a Bento document.
 *
 * The marker is `id="bento-doc"` — the splice contract every Bento app honours
 * (docs/PLATFORM.md §2), frozen because old updaters depend on it. Measured on
 * a real shell it sits 5.8KB in, after the chrome and the notice, so 64KB is
 * generous. It is deliberately NOT the 300KB head used for titles: this runs
 * against every stray .html in a granted folder, and most of them are not ours.
 */
const SNIFF_BYTES = 64 * 1024
const MARKER = 'id="bento-doc"'

/**
 * Is this actually a Bento document, whatever it is called?
 *
 * A Bento document is a Bento document because of what is INSIDE it. The name
 * is a convention, and conventions get broken by people: renamed to `deck.html`
 * to email it, saved by a browser that appended `(1)`, downloaded as
 * `Q3.html`. Those are still documents this extension can open, and until now
 * they were invisible because the filter was a regular expression on the name.
 *
 * Cheap enough to do honestly: the marker is in the first few KB, the verdict
 * is cached by size and mtime like everything else read here, and a file that
 * is not ours is rejected after one 64KB read that never happens again.
 */
async function sniff(handle, cacheGet, cachePut) {
  const file = await handle.getFile()
  const key = `sniff:${handle.name}:${file.size}:${file.lastModified}`
  const hit = await cacheGet(key)
  if (hit !== null && hit !== undefined) return hit.isDoc
  const head = await file.slice(0, SNIFF_BYTES).text()
  const isDoc = head.includes(MARKER)
  try { await cachePut(key, { isDoc }) } catch { /* best effort */ }
  return isDoc
}

/**
 * Every Bento document in the granted folders.
 *
 * Returns descriptors, not contents: name, folder, route, size, mtime. Reading
 * the documents themselves is a separate, cached step (`describe`), because a
 * folder of twenty decks is twenty megabytes and the list has to appear now.
 */
export async function listDocuments(deps = {}) {
  const grants = await (deps.getGrants ?? getGrants)()
  const known = await (deps.prefixes ?? prefixes)()
  const cacheGet = deps.get ?? ((k) => get(CACHE, k))
  const cachePut = deps.put ?? ((k, v) => put(CACHE, k, v))
  const out = []

  // Reading is only free the first time. A granted home directory can hold
  // thousands of unrelated .html files, and sniffing every one on every popup
  // open would be a real cost for a rare case — so the budget is per listing,
  // and named documents never spend from it.
  let sniffs = MAX_SNIFFS

  const walk = async (dir, root, rel, depth) => {
    if (depth > MAX_DEPTH || out.length >= MAX_DOCS) return
    for await (const [name, handle] of dir.entries()) {
      if (out.length >= MAX_DOCS) return
      if (handle.kind === 'file') {
        let named = namedDoc(name)
        if (!named) {
          // Not named like ours — but a document is a document because of what
          // is inside it, and names get changed by people. Look, once, cheaply.
          if (!maybeDoc(name) || sniffs <= 0) continue
          sniffs--
          let is = false
          try { is = await sniff(handle, cacheGet, cachePut) } catch { continue }
          if (!is) continue
        }
        out.push({
          name,
          named,
          base: name.replace(/\.bento\.html$/i, '').replace(/\.html?$/i, ''),
          folder: root.name,
          rel: [...rel, name],
          // Absolute path only if this folder has taught us where it lives.
          // Without it the row still renders — it just cannot be opened, and
          // says so, rather than silently doing nothing when clicked.
          path: known[root.name] ? `${known[root.name]}/${[...rel, name].join('/')}` : null,
          handle,
          // The directory the document actually sits in, so the page can act on
          // it — duplicate beside it, rename within it — without walking again.
          parent: dir,
        })
      } else if (handle.kind === 'directory' && !name.startsWith('.')) {
        await walk(handle, root, [...rel, name], depth + 1)
      }
    }
  }

  for (const dir of grants) {
    // A lapsed folder cannot be read at all; skipping it beats throwing, since
    // the other folders are still perfectly listable.
    if (await dir.queryPermission({ mode: 'readwrite' }) !== 'granted') continue
    try { await walk(dir, dir, [], 0) } catch { /* unreadable folder: skip */ }
  }
  return out
}

/** Cache key. Includes size and mtime so an edited document re-reads itself,
 *  and nothing has to be invalidated by hand. */
// `v2`: the meta gained `card` (the drawn title card); an entry cached before
// that would be served without one forever, since the file has not changed.
const keyFor = (doc, file) => `v2:${doc.folder}/${doc.rel.join('/')}:${file.size}:${file.lastModified}`

/**
 * What a document is called, and what its first page looks like.
 *
 * TITLE. Documents are named `Q3-board.bento.html`; the document knows it is
 * "Q3 Board Review". Showing the filename when the title is right there is the
 * difference between a file list and a document list.
 *
 * PREVIEW. Every save already writes a still render of page one into the shell
 * (`kernel/src/preview.ts`) so that file managers can thumbnail it. This IS a
 * file manager. The block is self-contained and scales itself to whatever
 * viewport it lands in, so it drops straight into a small sandboxed iframe with
 * no work — which is precisely what it was designed for.
 *
 * An ENCRYPTED document deliberately carries no preview: a plaintext title page
 * beside the ciphertext is the leak the password exists to prevent. So a
 * missing preview is not a failure here, it is a signal, and the caller shows a
 * lock rather than a blank.
 */
export async function describe(doc, deps = {}) {
  const cacheGet = deps.get ?? ((k) => get(CACHE, k))
  const cachePut = deps.put ?? ((k, v) => put(CACHE, k, v))
  const file = await doc.handle.getFile()
  const key = keyFor(doc, file)
  const hit = await cacheGet(key)
  if (hit) return hit

  const head = await file.slice(0, HEAD_BYTES).text()
  const title = head.match(/"title"\s*:\s*"((?:[^"\\]|\\.){0,200})"/)?.[1]
  // Which Bento this is. The format field is the document's own answer — the
  // extension supports three apps now and the UI never said which one a
  // document was, so a folder of decks and sheets looked like one undifferentiated
  // pile. A pristine shell has no document yet, so no format: that is not a
  // failure, it is a document nobody has saved.
  const app = head.match(/"format"\s*:\s*"bento\/([a-z]+)"/)?.[1] ?? null
  const encrypted = /"format"\s*:\s*"bento\/enc"/.test(head) || /data-bento-enc/.test(head)

  // The preview sits AFTER the document block — a quarter of the way into a
  // 900KB file, measured — so unlike the title it cannot be had from the head.
  // This is the expensive read, and the only reason the cache exists.
  // ONE read, two answers. The preview and the searchable text both come out of
  // the same bytes, so an encrypted document costs nothing extra and everything
  // else costs exactly one pass.
  let preview = null
  let text = null
  if (!encrypted) {
    const whole = await file.text()
    const start = whole.indexOf('<div data-bento-preview')
    const end = start === -1 ? -1 : whole.indexOf('<script data-bento-preview', start)
    if (start !== -1 && end > start) preview = whole.slice(start, end)
    text = extractText(whole)
  }

  // A shell that has never been saved has no preview render, and so did
  // every fixture on the maintainer's screen: 28 identical grey cards. The
  // document itself is right there, though — so a still card is drawn from
  // its first slide: background, a few lines of its words, the theme's ink.
  const card = !encrypted && !preview ? cardFrom(await file.text()) : null

  const meta = {
    title: title ? title.replace(/\\(.)/g, '$1') : doc.base,
    card,
    app,
    // What the document SAYS, so search can find a deck by a phrase on a slide
    // rather than only by what somebody happened to call the file. Free in I/O:
    // the same read that produced the preview.
    text,
    encrypted,
    preview,
    size: file.size,
    modified: file.lastModified,
  }
  // Best effort: a cache that cannot be written costs a re-read, nothing more.
  try { await cachePut(key, meta) } catch { /* quota, private mode */ }
  return meta
}

/**
 * A title card out of the document block, for a card with no preview: the
 * first (non-state) slide's background, the theme's text colour and accent,
 * and the first few pieces of text on that slide, tags stripped. Null when
 * the block is not a deck we can read — a card without a picture is still a
 * card. Read from the JSON, not from any markup the file carries.
 */
export function cardFrom(whole) {
  try {
    const i = whole.indexOf(MARKER)
    if (i === -1) return null
    const open = whole.indexOf('>', i)
    const close = whole.indexOf('</script', open)
    if (open === -1 || close === -1) return null
    const doc = JSON.parse(whole.slice(open + 1, close))
    const slides = Array.isArray(doc?.slides) ? doc.slides : []
    const first = slides.find((sl) => sl && typeof sl === 'object' && !sl.stateOf) ?? slides[0]
    if (!first) return null
    const colour = (v, fallback) => (typeof v === 'string' && /^(#[0-9a-f]{3,8}|rgba?\(|hsla?\(|[a-z]{3,20}$)/i.test(v.trim()) ? v.trim() : fallback)
    const theme = doc.theme && typeof doc.theme === 'object' ? doc.theme : {}
    const lines = []
    const strip = (h) => String(h).replace(/<[^>]*>/g, ' ').replace(/&nbsp;/g, ' ').replace(/&amp;/g, '&').replace(/&lt;/g, '<').replace(/&gt;/g, '>').replace(/\s+/g, ' ').trim()
    const visit = (v) => {
      if (lines.length >= 4) return
      if (Array.isArray(v)) { for (const x of v) visit(x); return }
      if (!v || typeof v !== 'object') return
      if (v.type === 'text' && !v.placeholder) {
        const w = strip(v.md ?? v.html ?? '')
        if (w) lines.push({ text: w.slice(0, 120), role: typeof v.role === 'string' ? v.role : '', size: typeof v.fontSize === 'number' ? v.fontSize : 0 })
      }
    }
    visit(first.elements)
    // Absent colours are left null: the card falls back to the UI palette
    // (ui.css), never to a literal of its own.
    return {
      bg: colour(first.background, colour(theme.background, null)),
      ink: colour(theme.color, null),
      accent: colour(theme.accent, null),
      lines,
    }
  } catch { return null }
}

/** How much extracted prose to keep per document. Enough for any phrase
 *  somebody would search for; far short of storing the document twice. */
const TEXT_BUDGET = 40 * 1024

/**
 * The words a document actually contains.
 *
 * Search used to cover the title, the file name and the folder — which finds a
 * deck you can already name. What you usually remember is a phrase ON a slide,
 * and the bytes to answer that were already read for the thumbnail and then
 * thrown away.
 *
 * Deliberately NOT a JSON parse. The document block runs to megabytes with
 * images inline, every app shapes it differently (slides put prose in
 * `element.html`, spaces in blocks, dash in cells), and a parser that has to
 * know the format is a parser that breaks when the format moves. Pulling string
 * VALUES out — `:"…"`, never keys — is format-agnostic and degrades to "finds
 * less" rather than "throws".
 *
 * Data URIs go first: one embedded image is bigger than every word in the
 * document, and they would dominate both the work and the budget.
 */
function extractText(html) {
  const start = html.indexOf(MARKER)
  if (start === -1) return null
  const end = html.indexOf('</script>', start)
  if (end === -1) return null

  let block = html.slice(start, end)
  block = block.replace(/data:[^"\\]{200,}/g, ' ')      // embedded media
  const out = []
  let size = 0
  for (const m of block.matchAll(/:"((?:[^"\\]|\\.){1,400})"/g)) {
    const v = m[1]
    if (!/[A-Za-z]{3,}/.test(v)) continue               // ids, colours, numbers
    out.push(v)
    size += v.length
    if (size > TEXT_BUDGET) break
  }
  return out.join(' ')
    .replace(/<[^>]{1,200}>/g, ' ')                     // element html
    .replace(/&[a-z]+;|&#\d+;/gi, ' ')
    .replace(/\s+/g, ' ')
    .trim()
    .slice(0, TEXT_BUDGET) || null
}

/**
 * The `+` from home/ios, which mints a new document from a seed.
 *
 * iOS bundles that seed. We deliberately do not: bundling an app shell would
 * put a copy of Bento inside the extension, to drift from the real release and
 * to be re-reviewed on every update — the same trap home/ios avoided by letting
 * documents carry their own runtime. Fetching the current signed release
 * instead means a document created here is the same version everyone else has,
 * the same day.
 *
 * Bundling is settled policy across all three hosts now (2026-08-16), which
 * makes this the ONLY way any of them creates a document — so the download is
 * verified, not trusted: signature, then digest, then the file handle. See
 * `release.js` for the chain and why it is mirrored from the kernel.
 *
 * Create-only, and the name is derived here rather than taken from anywhere —
 * the same rule as `backup`. Nothing existing is ever replaced.
 */
/**
 * The Bento apps, each with its own signed release channel.
 *
 * They all write `.bento.html`, all carry their own runtime, and all save
 * through the same kernel — so listing, opening, thumbnails and in-place saving
 * never needed to know which app a document belongs to, and still do not. This
 * list exists for ONE thing: creating a new document means choosing what it
 * should be.
 *
 * Adding an app here is the whole integration; nothing else in the extension
 * asks which app it is looking at.
 */
// `appId` is the name the app calls ITSELF inside its signed manifest
// (scripts/apps.mjs, and the shell's own `configureApp({appId})`), and it is
// checked against the payload — the channels are sibling paths on one origin,
// so without that check a genuine manifest served from the wrong path hands
// somebody the wrong application. It is spelled out rather than derived from
// `id` so that adding an app cannot silently opt out of the check.
export const APPS = [
  { id: 'slides', name: 'Slides', blurb: 'Presentations', appId: 'bento-slides',
    manifest: 'https://bento.page/releases/slides/manifest.json' },
  { id: 'spaces', name: 'Spaces', blurb: 'Notes and pages', appId: 'bento-spaces',
    manifest: 'https://bento.page/releases/spaces/manifest.json' },
  { id: 'dash', name: 'Dash', blurb: 'Data and sheets', appId: 'bento-dash',
    manifest: 'https://bento.page/releases/dash/manifest.json' },
]

/**
 * A free name in `dir`, counting on the BASE.
 *
 * `Untitled 2.bento.html`, never `Untitled.bento 2.html`. A double extension
 * defeats naive counters — including UIKit's, which reads `.bento.html` as the
 * name "Untitled.bento" plus extension "html" and inserts before the last
 * extension only. home/ios had to write its own for exactly this.
 */
export async function freeName(dir, wantedBase) {
  let base = wantedBase
  for (let n = 2; n < 999; n++) {
    let taken = true
    try { await dir.getFileHandle(`${base}.bento.html`) } catch (e) { taken = e?.name !== 'NotFoundError' }
    if (!taken) return { base, name: `${base}.bento.html` }
    base = `${wantedBase} ${n}`
  }
  throw new Error('too many documents with that name')
}

/**
 * Copy a document beside itself.
 *
 * Byte-for-byte, deliberately: a Bento document carries its own runtime, its
 * own collaboration keys and its own identity, and re-deriving any of that here
 * would make a copy that is subtly not the original. Whether a duplicate should
 * get a fresh `docId` is the DOCUMENT's business — Bento's own "Duplicate as
 * new deck" exists for that — and a file manager has no standing to decide it.
 */
export async function duplicate(doc) {
  const { name, base } = await freeName(doc.parent, `${doc.base} copy`)
  const bytes = await (await doc.handle.getFile()).arrayBuffer()
  const out = await doc.parent.getFileHandle(name, { create: true })
  const w = await out.createWritable()
  await w.write(bytes)
  await w.close()
  return { name, base }
}

/**
 * Rename a document.
 *
 * The File System Access API has no rename, so this is write-then-remove — in
 * that ORDER, and never the reverse. If the write fails the original is
 * untouched; if the remove fails the worst case is two copies, which is a
 * nuisance rather than a loss. Removing first would put the only copy of
 * somebody's document in a variable.
 */
export async function rename(doc, wantedBase) {
  // This string came from a prompt box and is about to become a filename.
  // Separators go first, so nothing can escape the folder; then the extension,
  // so typing it does not double it; then leading dots, because a document
  // called `.something` is invisible in every file manager including this one
  // — it would vanish from the list the moment it was renamed.
  const clean = wantedBase.trim()
    .replace(/[/\\:\0]/g, '')
    .replace(/\.bento\.html$/i, '')
    .replace(/\.{2,}/g, '.')
    .replace(/^\.+/, '')
    .trim()
  if (!clean) throw new Error('a document needs a name')
  if (clean === doc.base) return { name: doc.name, base: doc.base }

  const { name, base } = await freeName(doc.parent, clean)
  const bytes = await (await doc.handle.getFile()).arrayBuffer()
  const out = await doc.parent.getFileHandle(name, { create: true })
  const w = await out.createWritable()
  await w.write(bytes)
  await w.close()
  await doc.parent.removeEntry(doc.name)
  return { name, base }
}

/**
 * The highest release version of an app this browser has ever accepted.
 *
 * Per app, in the extension's own store — a document carries no version of its
 * own to compare against, so unlike the shell's self-update (which has its
 * running build to measure from) creating a document has nothing to be
 * monotonic ABOUT unless the host remembers.
 *
 * An unreadable store reads as NO floor rather than as a refusal: private mode,
 * quota, a migration mid-flight. That is a deliberate choice of availability
 * over protection in a case that is not an attack — being unable to remember
 * must not mean being unable to create a document.
 */
const floorKey = (app) => `release-floor:${app.id}`

async function readFloor(app, deps) {
  const read = deps.getFloor ?? (() => get(GRANT, floorKey(app)))
  try { return (await read()) || null } catch { return null }
}

async function raiseFloor(app, version, floor, deps) {
  // EQUAL is not a downgrade. Re-fetching the version already seen is the
  // normal case — the second document somebody creates — and treating it as a
  // rollback would break the `+` button on its second use rather than at some
  // exotic edge.
  if (floor && compareVersions(version, floor) <= 0) return
  const write = deps.putFloor ?? ((v) => put(GRANT, floorKey(app), v))
  // Best effort: a floor that cannot be written costs protection next time, not
  // this document.
  try { await write(version) } catch { /* quota, private mode */ }
}

export async function newDocument(dir, wantedBase = 'Untitled', deps = {}) {
  const net = deps.fetch ?? fetch
  const app = APPS.find((a) => a.id === deps.app) ?? APPS[0]

  // The manifest is a SIGNED ENVELOPE — `{payload, sig}`, the fields inside the
  // payload STRING — and it is read as text for that reason: the bytes the
  // signature covers are the bytes that arrived, so anything that parses and
  // re-serialises on the way past has verified something else.
  //
  // This was the bug, and it is worth naming because it was invisible. The code
  // here read `manifest.url` off the ENVELOPE, where there is no `url`, so every
  // attempt threw "the release server did not offer a build" — the `+` button
  // had never once worked. The rig agreed with it, because the fixture was
  // hand-written to the shape the code expected rather than to the shape the
  // server sends. It is checked against a real captured manifest now
  // (scripts/test-webext-release.ts).
  // ACCEPT_BYTES on the manifest too. The edge injection measured on the shell
  // targets things it reads as pages, so a JSON manifest is not today's victim
  // — but "ask for bytes on the one request we remembered" is a rule that only
  // holds until somebody adds a third fetch.
  const res = await net(app.manifest, { cache: 'no-store', headers: ACCEPT_BYTES })
  // Only Slides has a published channel today, so a 404 here is an EXPECTED
  // answer rather than a fault, and an HTTP status is the wrong way to say it.
  // The wording matches home/ios (and home/android is following): the app list
  // is aspirational on all three hosts, so all three phrase this identically.
  if (res.status === 404) throw new Error(`${app.name} has not been released yet`)
  if (!res.ok) throw new Error(`could not reach the ${app.name} release server (${res.status})`)
  const release = await verifyManifest(await res.text(), app.appId, deps.jwk)

  // NO DOWNGRADES. Everything above passes for a replayed OLD release: it is
  // genuinely signed, it names the right app, and its shell really does hash to
  // its pin. Every byte is authentic — it is just last month's. That is what
  // survives an origin or CDN compromise where the attacker can re-serve but
  // cannot forge, so the only thing that catches it is remembering.
  const floor = await readFloor(app, deps)
  if (floor && compareVersions(release.version, floor) < 0)
    throw new Error(
      `the ${app.name} channel offered ${release.version}, older than the ${floor} `
      + 'already seen — refusing it')

  // Signature over the pin, pin over the bytes. Both, or the shell being written
  // to somebody's disk is whatever the network felt like returning.
  const bytes = await fetchPinned(net, release.url, release.sha256)

  // Raised only NOW, after the bytes passed their digest. Raising it on a
  // merely-verified manifest would let one forged-but-unfetchable release lock
  // this browser out of every real release below it — turning a failed attack
  // into a permanent one. (home/ios hit this reasoning first, on PR #315.)
  await raiseFloor(app, release.version, floor, deps)

  const { name, base } = await freeName(dir, wantedBase)
  const handle = await dir.getFileHandle(name, { create: true })
  const w = await handle.createWritable()
  await w.write(bytes)
  await w.close()
  return { name, base, version: release.version, app: app.name }
}