@makerclay/core 1.0.0

package/src/admin/routes.js

@@ -0,0 +1,362 @@
+import express from 'express';
+import path from 'upath';
+import { can } from '../auth/can.js';
+import { HostError } from '../spec/codes.js';
+import { readMultipart } from '../util/multipart.js';
+import { jsonError } from '../json-errors.js';
+import { rawDocumentPath, documentUrlHeader, resolveDocumentHref } from '../spec/wire.js';
+import { readFileTextIfExists } from '../util/fsx.js';
+
+// The admin surface: the JSON API the dashboard is written against, and the one
+// the `hackable-dashboard.html` template calls with the owner's own session. It
+// is deliberately a plain API rather than a template's private plumbing, so the
+// UI has a second, user-authored consumer from day one.
+//
+// Everything here is owner-only. The individual ops re-check `can()` for the
+// exact node anyway; this guard is the coarse one that keeps a tenant out of the
+// file manager entirely.
+
+const asArray = (value) => (Array.isArray(value) ? value : value == null ? [] : [value]);
+
+// v1 has one file manager, the owner's. Tenant trees are moderated read-only
+// through the Tenants view, never through this surface. It was a realmOf(req)
+// function that ignored its argument and returned this, which read as though the
+// realm were derived per request.
+const OWNER_REALM = '';
+
+export function mountAdminRoutes(ctx) {
+  const {
+    router, config, paths, ops, listing, attic, templates, events,
+    gateCtx, wrap, track, clock, logger = console,
+  } = ctx;
+
+  const json = express.json({ limit: '2mb' });
+
+  function requireOwner(req, res, next) {
+    if (!can(req.actor, 'admin', null, gateCtx)) {
+      return jsonError(res, 'not-found', 'Not found');
+    }
+    return next();
+  }
+
+  function relPathFrom(value, field = 'path') {
+    const raw = String(value ?? '').replace(/^\/+/, '');
+    if (!raw) throw new HostError('bad-request', `${field} is required.`);
+    return raw;
+  }
+
+  // ---- listing -----------------------------------------------------------
+
+  router.get('/nodes', requireOwner, wrap(async (req, res) => {
+    const found = await listing.list({
+      owner: OWNER_REALM,
+      dir: String(req.query.dir || req.query.path || '').replace(/^\/+|\/+$/g, ''),
+      q: req.query.q || '',
+      sort: req.query.sort || 'name',
+      direction: req.query.direction === 'desc' ? 'desc' : 'asc',
+    });
+    if (!found) return jsonError(res, 'not-found', 'No such folder.');
+    return res.json({ ok: true, ...found });
+  }));
+
+  router.get('/trash', requireOwner, wrap(async (req, res) => {
+    res.json({ ok: true, ...(await listing.trash()) });
+  }));
+
+  router.get('/templates', requireOwner, wrap(async (req, res) => {
+    res.json({ ok: true, templates: await templates.list() });
+  }));
+
+  // ---- create ------------------------------------------------------------
+
+  router.post('/new', requireOwner, json, wrap(async (req, res) => {
+    const { dir = '', name, template = 'blank' } = req.body || {};
+    const html = await templates.read(template);
+    const created = await ops.createDocument({
+      actor: req.actor, owner: OWNER_REALM, dir: String(dir).replace(/^\/+|\/+$/g, ''),
+      name: String(name || 'untitled.html'), html, ctx: gateCtx,
+    });
+    if (created.derived) track(created.derived());
+    return res.json({ ok: true, node: created.node, path: created.path, url: `/${created.path}` });
+  }));
+
+  router.post('/mkdir', requireOwner, json, wrap(async (req, res) => {
+    const { dir = '', name } = req.body || {};
+    const node = await ops.mkdir({
+      actor: req.actor, owner: OWNER_REALM,
+      dir: String(dir).replace(/^\/+|\/+$/g, ''), name: String(name || ''), ctx: gateCtx,
+    });
+    return res.json({ ok: true, node });
+  }));
+
+  // ---- move / copy -------------------------------------------------------
+
+  router.post('/rename', requireOwner, json, wrap(async (req, res) => {
+    const from = relPathFrom(req.body?.path);
+    const name = String(req.body?.name || '');
+    const dir = path.dirname(from);
+    const to = dir === '.' ? name : `${dir}/${name}`;
+    const node = await ops.move({ actor: req.actor, owner: OWNER_REALM, from, to, ctx: gateCtx });
+    return res.json({ ok: true, node });
+  }));
+
+  router.post('/move', requireOwner, json, wrap(async (req, res) => {
+    const targets = asArray(req.body?.paths ?? req.body?.path).map((value) => relPathFrom(value, 'paths'));
+    const toDir = String(req.body?.to ?? '').replace(/^\/+|\/+$/g, '');
+    const moved = [];
+    for (const from of targets) {
+      const to = toDir ? `${toDir}/${path.basename(from)}` : path.basename(from);
+      moved.push(await ops.move({ actor: req.actor, owner: OWNER_REALM, from, to, ctx: gateCtx }));
+    }
+    return res.json({ ok: true, moved });
+  }));
+
+  router.post('/copy', requireOwner, json, wrap(async (req, res) => {
+    const from = relPathFrom(req.body?.path);
+    const node = await ops.copy({
+      actor: req.actor, owner: OWNER_REALM, from, to: req.body?.to || null, ctx: gateCtx,
+    });
+    return res.json({ ok: true, node, path: node.path, url: `/${node.path}` });
+  }));
+
+  // ---- trash -------------------------------------------------------------
+
+  router.post('/delete', requireOwner, json, wrap(async (req, res) => {
+    const targets = asArray(req.body?.paths ?? req.body?.path).map((value) => relPathFrom(value, 'paths'));
+    const trashed = [];
+    for (const relPath of targets) {
+      trashed.push(await ops.trash({ actor: req.actor, owner: OWNER_REALM, relPath, ctx: gateCtx }));
+    }
+    return res.json({ ok: true, trashed });
+  }));
+
+  router.post('/trash/restore', requireOwner, json, wrap(async (req, res) => {
+    const ids = asArray(req.body?.ids ?? req.body?.id);
+    const restored = [];
+    for (const id of ids) {
+      restored.push(await ops.restoreFromTrash({ actor: req.actor, nodeId: String(id), ctx: gateCtx }));
+    }
+    return res.json({ ok: true, restored });
+  }));
+
+  router.post('/trash/purge', requireOwner, json, wrap(async (req, res) => {
+    const ids = asArray(req.body?.ids ?? req.body?.id);
+    const purged = [];
+    for (const id of ids) {
+      purged.push(await ops.purge({ actor: req.actor, nodeId: String(id), ctx: gateCtx }));
+    }
+    return res.json({ ok: true, purged });
+  }));
+
+  router.post('/trash/empty', requireOwner, json, wrap(async (req, res) => {
+    const result = await ops.emptyTrash({ actor: req.actor, ctx: gateCtx });
+    res.json({ ok: result.failed.length === 0, ...result });
+  }));
+
+  // ---- the attic ---------------------------------------------------------
+
+  router.get('/attic', requireOwner, wrap(async (req, res) => {
+    res.json({ ok: true, entries: await attic.list() });
+  }));
+
+  // One row's versions, fetched when the row is opened. Deliberately not folded
+  // into `GET /attic`, so that listing stays one directory walk however many
+  // orphans a host has accumulated.
+  router.get('/attic/:id', requireOwner, wrap(async (req, res) => {
+    const found = await attic.history(String(req.params.id));
+    if (!found) return jsonError(res, 'not-found', 'There is no history here with that id.');
+    return res.json({ ok: true, versions: found });
+  }));
+
+  // A tenant's orphaned version full of script, opened at the real origin, is a
+  // full escape, so this lane never renders: octet-stream, an attachment, and a
+  // CSP that permits nothing. Same posture as the recovery download lane.
+  router.get('/attic/:id/:name', requireOwner, wrap(async (req, res) => {
+    const file = await attic.versionPath({ id: req.params.id, name: req.params.name });
+    if (!file) return jsonError(res, 'not-found', 'Not found');
+    res.setHeader('Content-Type', 'application/octet-stream');
+    res.setHeader('Content-Security-Policy', "default-src 'none'; sandbox");
+    // A filename is whatever the filesystem allowed, including a newline, and a
+    // newline in a header value throws rather than being escaped.
+    res.setHeader('Content-Disposition',
+      `attachment; filename="${path.basename(file).replace(/[^\w.-]+/g, '_')}"`);
+    res.sendFile(file);
+    return undefined;
+  }));
+
+  router.post('/attic/put-back', requireOwner, json, wrap(async (req, res) => {
+    const result = await attic.putBack({
+      id: String(req.body?.id ?? ''),
+      toPath: req.body?.path,
+      actor: req.actor,
+      ctx: gateCtx,
+    });
+    return res.json({ ok: true, ...result });
+  }));
+
+  router.post('/attic/forget', requireOwner, json, wrap(async (req, res) => {
+    const forgotten = await attic.forget({ id: String(req.body?.id ?? '') });
+    if (!forgotten) return jsonError(res, 'not-found', 'There is no history here with that id.');
+    return res.json({ ok: true });
+  }));
+
+  // ---- flags -------------------------------------------------------------
+
+  const STORAGE_APIS = /\b(localStorage|sessionStorage|indexedDB|document\.cookie|navigator\.serviceWorker)\b/;
+
+  async function storageWarning(owner, relPath) {
+    try {
+      const real = await paths.resolveRead(owner, relPath);
+      const source = await readFileTextIfExists(real);
+      if (!source) return null;
+      const found = source.match(STORAGE_APIS);
+      if (!found) return null;
+      return `This file uses ${found[1]}, which a sandboxed document cannot reach. `
+        + 'Keep its state in the DOM instead, or leave the sandbox off.';
+    } catch {
+      return null;
+    }
+  }
+
+  for (const [route, flag] of [['private', 'private'], ['isolate', 'isolated'], ['signups', 'signups']]) {
+    router.post(`/${route}`, requireOwner, json, wrap(async (req, res) => {
+      const relPath = relPathFrom(req.body?.path);
+      const raw = req.body?.value;
+      const value = raw === null || raw === 'inherit' ? null : !!raw;
+      const node = await ops.setFlag({
+        actor: req.actor, owner: OWNER_REALM, relPath, flag, value, ctx: gateCtx,
+      });
+      // §16.4. A sandbox costs the document localStorage, sessionStorage,
+      // IndexedDB and cookies. A conforming malleable document keeps its state
+      // in the DOM and loses nothing, so the warning is only worth raising for
+      // a document that is actually reaching for browser storage.
+      const warning = flag === 'isolated' && value === true
+        ? await storageWarning(OWNER_REALM, relPath)
+        : null;
+      return res.json({ ok: true, node, warning });
+    }));
+  }
+
+  // ---- upload ------------------------------------------------------------
+  //
+  // Uploads are just files: one tree, one rename, one delete, one trash. The
+  // platform's parallel uploads/ universe existed for nginx routing and quotas,
+  // and both reasons are gone.
+
+  function defaultDir(req) {
+    const explicit = req.query.dir;
+    if (typeof explicit === 'string') return explicit.replace(/^\/+|\/+$/g, '');
+    const href = documentUrlHeader(req);
+    if (!href) return '';
+    const dir = path.dirname(resolveDocumentHref(rawDocumentPath(href)));
+    return dir === '.' ? '' : dir;
+  }
+
+  // `/add-files`, not `/upload`: the spec claims `/_/upload` for a document's own
+  // uploads, and that lane has stricter rules than this one (it refuses anything
+  // that can run, and never lets one file replace another). Sharing one address
+  // would make those rules something a caller opts into by shaping the request
+  // rather than a property of the address, so the two lanes stay two addresses.
+  // This one is the file manager: the owner's own tool, on the owner's own tree,
+  // where uploading the .js and .css a site loads is the point.
+  router.post('/add-files', requireOwner, wrap(async (req, res) => {
+    if (config.features?.uploads === false) return jsonError(res, 'not-found', 'Not found');
+    const limit = config.limits.uploadBytes;
+    const contentType = String(req.headers['content-type'] || '');
+    let incoming = [];
+    let dir = defaultDir(req);
+
+    if (contentType.startsWith('multipart/form-data')) {
+      const { fields, files } = await readMultipart(req, { limit, files: 20 });
+      if (typeof fields.dir === 'string' && req.query.dir === undefined) {
+        dir = fields.dir.replace(/^\/+|\/+$/g, '');
+      }
+      incoming = files.map((file) => ({ name: file.filename, content: file.content }));
+    } else {
+      await new Promise((resolve, reject) => {
+        express.json({ limit: limit * 1.4 })(req, res, (error) => (error ? reject(error) : resolve()));
+      });
+      const body = req.body || {};
+      if (typeof body.dir === 'string' && req.query.dir === undefined) {
+        dir = body.dir.replace(/^\/+|\/+$/g, '');
+      }
+      const items = Array.isArray(body.files) ? body.files : [body];
+      incoming = items
+        .filter((item) => item && typeof item.name === 'string' && typeof item.data === 'string')
+        .map((item) => ({
+          name: item.name,
+          content: Buffer.from(item.data.replace(/^data:[^;,]*;base64,/, ''), 'base64'),
+        }));
+    }
+
+    if (!incoming.length) return jsonError(res, 'bad-request', 'No files in this upload.');
+
+    const written = [];
+    for (const file of incoming) {
+      if (file.content.length > limit) {
+        return jsonError(res, 'too-large', `${file.name} is larger than the ${limit}-byte limit.`);
+      }
+      const saved = await ops.putFile({
+        actor: req.actor, owner: OWNER_REALM, dir,
+        name: path.basename(file.name), content: file.content, ctx: gateCtx,
+      });
+      written.push({ name: path.basename(saved.path), path: saved.path, url: `/${saved.path}`, bytes: file.content.length });
+    }
+    return res.json({ ok: true, files: written, uploads: written });
+  }));
+
+  // ---- the events feed ---------------------------------------------------
+  //
+  // The dashboard morphs off this rather than polling, which is what makes a
+  // rename in a terminal show up in an open browser tab.
+
+  const FEED = [
+    'node-saved', 'node-created', 'node-moved', 'node-trashed', 'node-restored',
+    'node-purged', 'node-updated', 'node-changed', 'node-renamed', 'node-missing', 'node-appeared',
+    // A signup arrives while the owner is looking at something else, which is
+    // the whole reason this feed exists.
+    'tenant-created', 'tenant-approved', 'tenant-updated', 'tenant-removed',
+  ];
+
+  router.get('/events', requireOwner, (req, res) => {
+    res.writeHead(200, {
+      'Content-Type': 'text/event-stream',
+      'Cache-Control': 'no-cache, no-transform',
+      Connection: 'keep-alive',
+      'X-Accel-Buffering': 'no',
+    });
+    res.write(`retry: 3000\n\n`);
+
+    const send = (name) => (payload) => {
+      try {
+        const node = payload?.node || null;
+        res.write(`event: ${name}\ndata: ${JSON.stringify({
+          name,
+          at: clock.now(),
+          path: node?.path ?? payload?.path ?? null,
+          owner: node?.owner ?? payload?.owner ?? '',
+          id: node?.id ?? null,
+          from: payload?.from ?? null,
+        })}\n\n`);
+      } catch (error) {
+        logger.error?.('[makerclay] events feed write failed:', error?.message || error);
+      }
+    };
+
+    const bound = FEED.map((name) => {
+      const handler = send(name);
+      events.on(name, handler);
+      return [name, handler];
+    });
+
+    const keepalive = setInterval(() => res.write(': keepalive\n\n'), config.limits.sseKeepaliveMs);
+    keepalive.unref?.();
+
+    const stop = () => {
+      clearInterval(keepalive);
+      for (const [name, handler] of bound) events.off(name, handler);
+    };
+    req.on('close', stop);
+    res.on('close', stop);
+  });
+}

package/src/attic.js

@@ -0,0 +1,168 @@
+import path from 'upath';
+import { HostError } from './spec/codes.js';
+import { statIfExists, rmrf } from './util/fsx.js';
+import { VERSION_NAME } from './versions/naming.js';
+
+// The attic: history whose document is gone.
+//
+// Identity follows a file by inode and, when that fails, by content digest.
+// Both can miss at once (a move across a filesystem boundary, in one action,
+// while the host was down), and the file is then a new document with no history
+// while the old history sits under versions/ with nothing pointing at it. That
+// is the honest failure mode of matching files without writing anything into
+// them, and what makes it acceptable is that the history never disappears. This
+// is the room you walk into to find it.
+
+export function createAttic({
+  paths, store, nodes, versions, recovery, replace, locks, logger = console,
+}) {
+  const rowFor = (id) => (store ? store.getNodeById(id) : null);
+
+  async function find(id) {
+    const wanted = String(id ?? '');
+    if (!wanted) return null;
+    return (await recovery.readAllMeta()).find((record) => record.id === wanted) || null;
+  }
+
+  // Membership is "no live row whose path currently resolves to a file", NOT the
+  // simpler "no live row". A row whose file the scanner cannot find is
+  // deliberately left alone rather than tombstoned, because the file may be
+  // coming back. That is exactly the cross-filesystem move this room exists for,
+  // so filtering on the row alone would hide the main case.
+  async function list() {
+    const entries = [];
+    for (const record of await recovery.readAllMeta()) {
+      const row = rowFor(record.id);
+      // A trashed document has its own room and its bytes are in trash/.
+      if (row?.deletedAt) continue;
+
+      const relPath = row?.path ?? record.path;
+      const owner = (row?.owner ?? record.owner) || '';
+      if (row) {
+        const real = path.join(paths.realmRoot(owner), relPath);
+        const stat = await statIfExists(real);
+        if (stat?.isFile()) continue;
+      }
+
+      const history = await versions.list({ id: record.id, path: relPath });
+      if (!history.length) continue;
+
+      entries.push({
+        id: record.id,
+        path: relPath,
+        owner,
+        kind: record.kind ?? null,
+        private: !!record.private,
+        versions: history.length,
+        newest: history[0].name,
+        lastSeen: record.updatedAt ?? null,
+        stranded: !!row,
+      });
+    }
+    return entries;
+  }
+
+  // One history's versions, read when its row is opened rather than folded into
+  // list(). The room is a walk over every orphan on the host, and reading every
+  // version of every one of them to render one table is the cost that walk
+  // cannot afford.
+  async function history(id) {
+    const record = await find(id);
+    if (!record) return null;
+    const row = rowFor(record.id);
+    return await versions.list({ id: record.id, path: row?.path ?? record.path });
+  }
+
+  // One action covers both cases, because from the owner's point of view they
+  // are one thing: put this history back on a file.
+  //
+  // Adopt FIRST, then write. Creating the document first would give it a history
+  // of its own and leave adopt with two directories and no honest way to merge
+  // them. This order also tells the truth about what happened: the restore is a
+  // save, so it publishes its own version on top of the recovered ones.
+  async function putBack({ id, toPath, actor, ctx = {} }) {
+    const record = await find(id);
+    if (!record) throw new HostError('not-found', 'There is no history here with that id.');
+    // versions/ is one flat directory shared by every realm and only
+    // meta.json.owner separates them, so binding a tenant's orphaned history to
+    // an owner document is a realm crossing.
+    if ((record.owner || '') !== '') {
+      throw new HostError(
+        'forbidden',
+        'This history belongs to a tenant, so it can only go back onto one of their files.',
+      );
+    }
+
+    const relPath = String(toPath ?? '').replace(/^\/+/, '');
+    if (!relPath) throw new HostError('bad-request', 'Say where this history should go.');
+
+    return await locks.withLock(`attic:${record.id}`, async () => {
+      // Re-stat inside the lock: the target can appear, move or be replaced
+      // between the page rendering and the click.
+      const real = await paths.resolveWrite('', relPath);
+      const already = await statIfExists(real);
+
+      const existing = nodes.get('', relPath);
+      if (already && existing && (await versions.list(existing)).length) {
+        throw new HostError('conflict', 'That file already has its own history.');
+      }
+
+      let node = nodes.materialize(nodes.resolve('', relPath));
+      if (!(await versions.adopt(record.id, node))) {
+        throw new HostError('conflict', 'That file already has its own history.');
+      }
+
+      // After adopt, never before. A refusal has to leave the target exactly as
+      // it was, and adopt is the only thing that knows whether it will refuse:
+      // setting the flags first means a conflict hands an unrelated document
+      // someone else's signups flag. The record adopt just wrote describes the
+      // target's own defaults, which are public, so the row and the record are
+      // corrected together right here, still before any bytes are written.
+      node = nodes.update(node, {
+        private: !!record.private,
+        isolated: record.isolated === undefined ? null : record.isolated,
+        signups: !!record.signups,
+      });
+      await versions.patchMeta(node, {});
+
+      if (already) return { id: record.id, path: relPath, restored: null };
+
+      const history = await versions.list(node);
+      const newest = history[0];
+      if (!newest) throw new HostError('not-found', 'That history has no versions left.');
+      const bytes = await versions.read(node, newest.name);
+      if (bytes == null) throw new HostError('not-found', 'That version could not be read.');
+
+      // Through the kernel, never straight to disk: it is the only writer of
+      // managed documents.
+      const result = await replace({
+        actor, owner: '', relPath, bytes, trigger: 'user', source: 'restore', ctx,
+      });
+      return { id: record.id, path: relPath, restored: newest.name, etag: result.etag };
+    });
+  }
+
+  // Owner-only and irreversible, so the confirmation lives in the UI.
+  async function forget({ id }) {
+    const record = await find(id);
+    if (!record) return false;
+    const dir = await versions.findDirById(record.id);
+    if (!dir) return false;
+    await rmrf(dir);
+    logger.warn?.(`[makerclay] forgot the orphaned history of ${record.path}`);
+    return true;
+  }
+
+  // The absolute path of one version file, or null. No reading here: the route
+  // streams it.
+  async function versionPath({ id, name }) {
+    if (!VERSION_NAME.test(String(name ?? ''))) return null;
+    const dir = await versions.findDirById(id);
+    if (!dir) return null;
+    const full = path.join(dir, String(name));
+    const stat = await statIfExists(full);
+    return stat?.isFile() ? full : null;
+  }
+
+  return { list, history, putBack, forget, versionPath };
+}

package/src/auth/can.js

@@ -0,0 +1,79 @@
+// The capability gate. One pure function, no I/O, called by every route
+// including the static document handler.
+//
+//   can(actor, action, node, ctx) -> boolean
+//   actor:  {kind:'owner'|'tenant'|'guest', username?, grants:{share?, saveToken?}}
+//   action: 'read'|'write'|'edit-source'|'admin'|'version-read'|'version-write'
+//
+// A share link grants a capability set for one node; it never promotes an
+// identity. That is the whole difference from the platform's no_auth -> app_user
+// elevation, which set isOwner unconditionally.
+
+export const ACTIONS = ['read', 'write', 'edit-source', 'admin', 'version-read', 'version-write'];
+
+export const GUEST = { kind: 'guest', grants: {} };
+
+// A visitor can hold several share links at once (one cookie per node), so the
+// grants are a list and the matching one is picked per node. `share` stays
+// accepted as the single-grant spelling.
+function heldShares(actor) {
+  const grants = actor?.grants;
+  if (!grants) return [];
+  const held = Array.isArray(grants.shares) ? [...grants.shares] : [];
+  if (grants.share) held.push(grants.share);
+  return held;
+}
+
+export function shareFor(actor, node, kinds = ['view', 'edit']) {
+  if (!node) return null;
+  return heldShares(actor).find(
+    (grant) => grant?.nodeId === node.id && kinds.includes(grant.grantKind),
+  ) || null;
+}
+
+function grantFor(actor, node, kinds) {
+  if (!node || !actor?.grants) return false;
+  if (shareFor(actor, node, kinds)) return true;
+  const { saveToken } = actor.grants;
+  if (saveToken && saveToken.nodeId === node.id && kinds.includes(saveToken.grantKind)) return true;
+  return false;
+}
+
+export function can(actor, action, node = null, ctx = {}) {
+  const kind = actor?.kind || 'guest';
+  const owner = node?.owner ?? '';
+  const isTenantRealm = owner !== '';
+
+  if (action === 'admin') return kind === 'owner';
+
+  // The source editor is the owner's tool on the owner's own realm. A tenant
+  // never gets it, and neither does a share link: an edit grant is permission to
+  // change one document through the save lane, not to open its source.
+  if (action === 'edit-source') return kind === 'owner' && !isTenantRealm;
+
+  if (action === 'read') {
+    if (kind === 'owner') return true;
+    if (grantFor(actor, node, ['view', 'edit'])) return true;
+    if (kind === 'tenant' && owner === actor.username) return true;
+    if (ctx.requireAuthToRead) return false;
+    if (isTenantRealm) return false;
+    return !node?.private;
+  }
+
+  if (action === 'write') {
+    if (grantFor(actor, node, ['edit'])) return true;
+    // The owner moderates tenant trees read-only. There is deliberately no
+    // owner-edits-instance lane: someone else's instance is their document.
+    if (kind === 'owner') return !isTenantRealm;
+    if (kind === 'tenant') return owner === actor.username;
+    return false;
+  }
+
+  // History is the edit surface's undo, so it follows write, not read: a
+  // view-grant holder can see the current document and no earlier state of it.
+  if (action === 'version-read' || action === 'version-write') {
+    return can(actor, 'write', node, ctx);
+  }
+
+  return false;
+}

package/src/auth/csrf.js

@@ -0,0 +1,74 @@
+import { jsonError } from '../json-errors.js';
+
+// Spec §8: validate the origin of every save. A cross-origin POST with a
+// text/plain body is a CORS "simple request", so without this any page a person
+// visits could silently save garbage into a document on their host.
+//
+// The rules, in order:
+//
+//   - Safe methods and exempt lanes pass untouched.
+//   - No Origin header at all passes: curl, a webhook and a shell script send
+//     none, and none of them carry ambient browser authority. This is the same
+//     reasoning that makes CSRF a cookie-auth problem in the first place.
+//   - `Origin: null` (a sandboxed document, a data: URL, a redirect chain) is
+//     forgeable and therefore carries no authority, so it passes only when the
+//     request's credential is a per-document token. The token is the whole
+//     credential there, which is exactly why isolated documents use one.
+//     Most lanes carry it in the path; the sync lane carries it in `?token=`,
+//     which is the same credential in a different place, so the lanes that do
+//     that say so explicitly rather than the rule going loose for everyone.
+//   - Any other Origin must name this host.
+
+const UNSAFE = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+
+export function createCsrfGuard({
+  exempt = [], publicUrl = null, tokenLanes = null, queryTokenLanes = null,
+} = {}) {
+  const exemptPatterns = exempt.map((entry) => (entry instanceof RegExp ? entry : new RegExp(entry)));
+
+  function expectedHosts(req) {
+    const hosts = new Set();
+    const header = req.get('host');
+    if (header) hosts.add(header.toLowerCase());
+    if (publicUrl) {
+      try {
+        hosts.add(new URL(publicUrl).host.toLowerCase());
+      } catch {
+        // A malformed publicUrl simply contributes no host.
+      }
+    }
+    return hosts;
+  }
+
+  return function csrfGuard(req, res, next) {
+    if (!UNSAFE.has(req.method)) return next();
+    if (exemptPatterns.some((pattern) => pattern.test(req.path))) return next();
+
+    const origin = req.get('origin');
+    if (!origin) return next();
+
+    // The caller passes the same list the CORS headers are built from, so a new
+    // token lane cannot arrive here unrecognised.
+    const hasPathToken = !!req.params?.token
+      || (tokenLanes ? tokenLanes.test(req.path) : /^\/(?:save|restore|versions|meta)\/[^/]+/.test(req.path));
+    // A lane that takes its token as a query parameter has to say so, and the
+    // token has to actually be there: the path alone proves nothing.
+    const hasQueryToken = !!queryTokenLanes
+      && queryTokenLanes.test(req.path)
+      && typeof req.query?.token === 'string'
+      && req.query.token.length > 0;
+    if (origin === 'null') {
+      if (hasPathToken || hasQueryToken) return next();
+      return jsonError(res, 'forbidden', 'Cross-origin save refused.');
+    }
+
+    let host = null;
+    try {
+      host = new URL(origin).host.toLowerCase();
+    } catch {
+      host = null;
+    }
+    if (host && expectedHosts(req).has(host)) return next();
+    return jsonError(res, 'forbidden', 'Cross-origin save refused.');
+  };
+}