domma-cms 1.8.32 → 1.8.34

package/plugins/docs/lib/store.js

@@ -0,0 +1,748 @@
+/**
+ * Docs storage and the rules around it: documents on disk, who may do what
+ * with one, per-user stars and recents, edit locks, the public-link index and
+ * the sanitiser every stored body goes through.
+ *
+ * Shared by plugin.js (the admin API) and plugin.public.js (the public link
+ * page). Both are loaded by the same process, so the module state here - the
+ * running settings, the lock table, the caches - is one copy between them.
+ *
+ * Files only: data/documents/<id>.json, data/versions/<id>/<n>.json,
+ * data/user-state.json - and, for a PDF document (2.13), its file at
+ * data/files/<id>.pdf with each earlier upload at data/versions/<id>/<n>.pdf.
+ * Writes are whole-file and single-process, as before.
+ *
+ * @module docs/lib/store
+ */
+
+import fs from 'fs/promises';
+import path from 'path';
+import crypto from 'crypto';
+import {fileURLToPath} from 'url';
+import sanitizeHtml from 'sanitize-html';
+import {countWords, preview} from '../admin/lib/convert.js';
+import {docsRegistry} from './extensions.js';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+// DOCS_DATA_DIR: tests point this at a temp dir so they never touch a real site's documents.
+export const DATA_DIR = process.env.DOCS_DATA_DIR || path.join(here, '..', 'data');
+const DOCS_DIR = path.join(DATA_DIR, 'documents');
+const VERSIONS_DIR = path.join(DATA_DIR, 'versions');
+const FILES_DIR = path.join(DATA_DIR, 'files');
+const USER_STATE = path.join(DATA_DIR, 'user-state.json');
+
+// ------------------------------------------------------------------ settings
+
+/**
+ * The running settings, shared by both halves of the plugin. plugin.js
+ * fills it at boot and on every PUT /settings; the public page reads it.
+ */
+export const runtime = {
+    config: {
+        scope: 'user',
+        autoSaveInterval: 30000,
+        maxVersions: 50,
+        publicLinks: true,
+        trashDays: 30
+    },
+    /**
+     * Bumped after every finished document or star write - through a route or not (Docs Pro writes
+     * through `services`). GET /count only caches an answer read within one generation (2.10).
+     */
+    writeGen: 0
+};
+
+/** A document or a star changed: answers cached before now are stale. */
+export function bumpWriteGen() { runtime.writeGen++; }
+
+// ----------------------------------------------------------------- sanitise
+
+const TAGS = ['p', 'div', 'span', 'br', 'hr', 'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'strong', 'b', 'em', 'i', 'u', 's',
+    'del', 'strike', 'ins', 'sub', 'sup', 'mark', 'code', 'pre', 'kbd', 'blockquote', 'ul', 'ol', 'li', 'a', 'img',
+    'table', 'thead', 'tbody', 'tfoot', 'tr', 'th', 'td', 'caption', 'colgroup', 'col', 'figure', 'figcaption'];
+
+const STYLE_VALUE = {
+    'text-align': [/^(left|right|center|justify)$/],
+    'background-color': [/^#[0-9a-f]{3,8}$/i, /^rgba?\([\d\s.,%]+\)$/i, /^transparent$/],
+    color: [/^#[0-9a-f]{3,8}$/i, /^rgba?\([\d\s.,%]+\)$/i],
+    width: [/^\d+(\.\d+)?(px|%|em|rem)$/],
+    'margin-left': [/^\d+(\.\d+)?(px|em|rem)$/],
+    'padding-left': [/^\d+(\.\d+)?(px|em|rem)$/]
+};
+
+/** Extra tags/attributes an add-on (Docs Pro) needs kept - comment anchors and the like. */
+const extraRules = {tags: new Set(), attributes: {}};
+
+/**
+ * Let an extension keep more markup through the sanitiser.
+ *
+ * @param {{tags?:string[], attributes?:Object<string,string[]>}} rules
+ */
+export function allowMarkup(rules = {}) {
+    for (const t of rules.tags || []) extraRules.tags.add(t);
+    for (const [tag, attrs] of Object.entries(rules.attributes || {})) {
+        extraRules.attributes[tag] = [...new Set([...(extraRules.attributes[tag] || []), ...attrs])];
+    }
+}
+
+/**
+ * What a document body may contain. Everything a document is written with,
+ * nothing that runs: no scripts, no event handlers, no javascript: links, no
+ * forms or frames, and only the few inline styles the editor itself writes.
+ *
+ * @param   {string} html
+ * @returns {string}
+ */
+/**
+ * A body as readers see it (2.5): pending suggestions shown as not made -
+ * suggested words out, suggested deletions kept as plain text. Docs does this
+ * itself, so a lapsed Docs Pro can never put unaccepted words on a public page.
+ *
+ * @param   {string} html  sanitised
+ * @returns {string}
+ */
+export function withoutSuggestions(html) {
+    const s = String(html ?? '');
+    if (!s.includes('data-sug')) return s;
+    return sanitizeHtml(s, {
+        // Already sanitised: the same tags, every attribute it kept.
+        allowedTags: [...TAGS, ...extraRules.tags],
+        allowedAttributes: false,
+        allowedSchemes: ['http', 'https', 'mailto', 'tel'],
+        allowedSchemesByTag: {img: ['http', 'https', 'data']},
+        exclusiveFilter: (frame) => frame.tag === 'ins' && frame.attribs?.['data-sug'] !== undefined,
+        transformTags: {del: (tag, attribs) => (attribs['data-sug'] !== undefined ? {tagName: 'span', attribs: {}} : {tagName: tag, attribs})}
+    });
+}
+
+export function sanitizeDoc(html) {
+    const attrs = {
+        a: ['href', 'title', 'target', 'rel'],
+        img: ['src', 'alt', 'title', 'width', 'height'],
+        td: ['colspan', 'rowspan'],
+        th: ['colspan', 'rowspan', 'scope'],
+        ol: ['start', 'type'],
+        ul: ['data-type'],
+        li: ['data-checked'],
+        code: ['class'],
+        pre: ['class'],
+        // Suggested edits (2.5, Docs Pro) keep their marks even while Pro is off - so they stay suggestions.
+        ins: ['data-sug', 'data-by', 'data-name', 'data-at'],
+        del: ['data-sug', 'data-by', 'data-name', 'data-at'],
+        '*': ['style']
+    };
+    for (const [tag, list] of Object.entries(extraRules.attributes)) attrs[tag] = [...(attrs[tag] || []), ...list];
+    return sanitizeHtml(String(html ?? ''), {
+        allowedTags: [...TAGS, ...extraRules.tags],
+        allowedAttributes: attrs,
+        allowedClasses: {code: [/^language-[\w-]+$/], pre: [/^language-[\w-]+$/]},
+        allowedStyles: {'*': STYLE_VALUE},
+        allowedSchemes: ['http', 'https', 'mailto', 'tel'],
+        allowedSchemesByTag: {img: ['http', 'https', 'data']},
+        allowProtocolRelative: false,
+        transformTags: {
+            // A link out of a document opens in a new tab and hands the
+            // target page nothing back.
+            a: (tagName, attribs) => {
+                const out = {...attribs};
+                if (out.href && /^https?:/i.test(out.href)) { out.target = '_blank'; out.rel = 'noopener noreferrer'; }
+                return {tagName, attribs: out};
+            },
+            font: 'span'
+        }
+    });
+}
+
+// ------------------------------------------------------------------- files
+
+/**
+ * @param   {string} id
+ * @returns {boolean}
+ */
+export function validId(id) {
+    return typeof id === 'string' && /^[A-Za-z0-9-]{8,64}$/.test(id);
+}
+
+/**
+ * What kind of document this is (2.13): 'pdf' - a file, shown as it is - or
+ * 'html' - a body written in the editor. Everything that renders, exports or
+ * edits a body asks this first.
+ *
+ * @param   {object} doc
+ * @returns {'html'|'pdf'}
+ */
+export function kindOf(doc) {
+    return doc?.format === 'pdf' ? 'pdf' : 'html';
+}
+
+/** Where a PDF document's file lives. */
+export function filePath(id) {
+    return path.join(FILES_DIR, `${id}.pdf`);
+}
+
+/** Where an earlier upload of a PDF document is kept, beside its version record. */
+export function versionFilePath(id, num) {
+    return path.join(VERSIONS_DIR, id, `${num}.pdf`);
+}
+
+/** A PDF document's bytes, or null. */
+export async function readFileBytes(id) {
+    if (!validId(id)) return null;
+    try { return await fs.readFile(filePath(id)); } catch { return null; }
+}
+
+/** Write a PDF document's file atomically (tmp + rename). The record is written separately. */
+export async function writeFileBytes(id, buf) {
+    if (!validId(id)) throw new Error('Bad document id');
+    await fs.mkdir(FILES_DIR, {recursive: true});
+    const file = filePath(id);
+    const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+    await fs.writeFile(tmp, buf);
+    await fs.rename(tmp, file);
+}
+
+/** Copy one PDF document's file to another document (a duplicate). */
+export async function copyFileBytes(fromId, toId) {
+    if (!validId(fromId) || !validId(toId)) return false;
+    await fs.mkdir(FILES_DIR, {recursive: true});
+    try { await fs.copyFile(filePath(fromId), filePath(toId)); return true; } catch { return false; }
+}
+
+export async function readDoc(id) {
+    if (!validId(id)) return null;
+    try {
+        return JSON.parse(await fs.readFile(path.join(DOCS_DIR, `${id}.json`), 'utf8'));
+    } catch {
+        return null;
+    }
+}
+
+/** Serialise writes per document - two saves racing must not interleave. */
+const writing = new Map();
+
+export async function writeDoc(doc) {
+    await fs.mkdir(DOCS_DIR, {recursive: true});
+    const file = path.join(DOCS_DIR, `${doc.id}.json`);
+    const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+    const prev = writing.get(doc.id) || Promise.resolve();
+    const job = prev.catch(() => {}).then(async () => {
+        await fs.writeFile(tmp, JSON.stringify(doc, null, 2));
+        await fs.rename(tmp, file);
+    });
+    writing.set(doc.id, job);
+    try { await job; } finally { if (writing.get(doc.id) === job) writing.delete(doc.id); bumpWriteGen(); }
+    linkIndex = null;
+    return doc;
+}
+
+/**
+ * Change one document safely: re-read it inside that document's write
+ * chain, let `fn` return the new version (or null for no change), write it.
+ * Every route that edits a document goes through here, so a share saved
+ * while an autosave lands can never write back a stale body.
+ *
+ * @param   {string}   id
+ * @param   {Function} fn  (doc) => newDoc | null   (may be async; keep it short)
+ * @returns {Promise<object|null>} the document as written, or as it was
+ */
+export async function mutateDoc(id, fn) {
+    if (!validId(id)) return null;
+    const prev = writing.get(id) || Promise.resolve();
+    let result = null;
+    const job = prev.catch(() => {}).then(async () => {
+        const doc = await readDoc(id);
+        if (!doc) return;
+        const next = await fn(doc);
+        if (!next) { result = doc; return; }
+        await fs.mkdir(DOCS_DIR, {recursive: true});
+        const file = path.join(DOCS_DIR, `${id}.json`);
+        const tmp = `${file}.${process.pid}.${crypto.randomBytes(4).toString('hex')}.tmp`;
+        await fs.writeFile(tmp, JSON.stringify(next, null, 2));
+        await fs.rename(tmp, file);
+        linkIndex = null;
+        result = next;
+    });
+    writing.set(id, job);
+    try { await job; } finally { if (writing.get(id) === job) writing.delete(id); bumpWriteGen(); }
+    return result;
+}
+
+export async function removeDoc(id) {
+    if (!validId(id)) return;
+    await fs.rm(path.join(DOCS_DIR, `${id}.json`), {force: true});
+    await fs.rm(path.join(VERSIONS_DIR, id), {recursive: true, force: true});
+    await fs.rm(filePath(id), {force: true});
+    linkIndex = null;
+    bumpWriteGen();
+}
+
+export async function listDocs() {
+    await fs.mkdir(DOCS_DIR, {recursive: true});
+    const files = (await fs.readdir(DOCS_DIR)).filter(f => f.endsWith('.json'));
+    const docs = await Promise.all(files.map(async (f) => {
+        try { return JSON.parse(await fs.readFile(path.join(DOCS_DIR, f), 'utf8')); } catch { return null; }
+    }));
+    return docs.filter(Boolean);
+}
+
+/**
+ * A new document, stamped. Bodies are sanitised on every way in. A PDF
+ * document (2.13) has `format: 'pdf'` and a `file` record {name, size, pages,
+ * sha256, uploadedAt, uploadedBy}; its `content` is the text read out of the
+ * file (for search and the excerpt), sanitised like any body.
+ *
+ * @param   {object} fields
+ * @param   {object} user   request.user
+ * @returns {object}
+ */
+export function newDoc({title, content = '', folderId = null, tags = [], format = 'html', file = null}, user) {
+    const now = new Date().toISOString();
+    const body = sanitizeDoc(content);
+    const pdf = format === 'pdf' && file;
+    return {
+        id: crypto.randomUUID(),
+        title: cleanTitle(title),
+        content: body,
+        format: pdf ? 'pdf' : 'html',
+        ...(pdf ? {file: fileRecord(file, user, now)} : {}),
+        folderId: folderId || null,
+        tags: Array.isArray(tags) ? tags.map(String).slice(0, 50) : [],
+        userId: user.id,
+        shares: [],
+        publicLink: null,
+        trashedAt: null,
+        wordCount: countWords(body),
+        createdAt: now,
+        updatedAt: now,
+        updatedBy: user.id
+    };
+}
+
+/** The file record a PDF document carries - whitelisted, never spread from a request. */
+export function fileRecord(file, user, at = new Date().toISOString()) {
+    return {
+        name: String(file?.name || 'document.pdf').slice(0, 160),
+        size: Math.max(0, Number(file?.size) || 0),
+        pages: Math.max(0, Math.round(Number(file?.pages) || 0)),
+        sha256: /^[a-f0-9]{64}$/.test(String(file?.sha256 || '')) ? file.sha256 : '',
+        encrypted: file?.encrypted === true,
+        uploadedAt: at,
+        uploadedBy: user?.id || null
+    };
+}
+
+export function cleanTitle(title) {
+    const t = String(title ?? '').replace(/\s+/g, ' ').trim().slice(0, 200);
+    return t || 'Untitled';
+}
+
+// ----------------------------------------------------------------- versions
+
+/**
+ * Keep the content a document is about to lose, then trim its history to
+ * the newest `keep`. Numbers keep climbing; only the oldest files go.
+ *
+ * @param {object} doc   the document BEFORE the change
+ * @param {number} keep
+ * @param {string} [by]  who made the change that replaced it
+ */
+export async function snapshotVersion(doc, keep, by = null) {
+    const dir = path.join(VERSIONS_DIR, doc.id);
+    await fs.mkdir(dir, {recursive: true});
+    const nums = [...new Set((await fs.readdir(dir).catch(() => [])).filter(f => f.endsWith('.json')).map(f => parseInt(f, 10)).filter(n => !isNaN(n)))].sort((a, b) => a - b);
+    const next = nums.length ? nums[nums.length - 1] + 1 : 1;
+    // A PDF document's version is the file it had (2.13): copied first, so a record never names a file that is not there.
+    const pdf = kindOf(doc) === 'pdf';
+    if (pdf) { try { await fs.copyFile(filePath(doc.id), versionFilePath(doc.id, next)); } catch { /* no file yet: the record alone */ } }
+    await fs.writeFile(path.join(dir, `${next}.json`), JSON.stringify({
+        num: next, title: doc.title, content: doc.content, createdAt: new Date().toISOString(),
+        ...(pdf ? {format: 'pdf', file: doc.file || null} : {}),
+        savedBy: doc.updatedBy || doc.userId || null, replacedBy: by,
+        // 2.12: a change credited by name (Wiki Pro's approved suggestion from a visitor) - only while it is that save's.
+        ...(doc.creditName && doc.creditAt && doc.creditAt === doc.updatedAt ? {savedByName: String(doc.creditName).slice(0, 80)} : {})
+    }, null, 2));
+    const all = [...nums, next];
+    for (const n of all.slice(0, Math.max(0, all.length - keep))) {
+        await fs.rm(path.join(dir, `${n}.json`), {force: true});
+        await fs.rm(path.join(dir, `${n}.pdf`), {force: true});
+    }
+}
+
+/**
+ * Put an earlier upload back as a PDF document's file (2.13) - a restore.
+ *
+ * @returns {Promise<boolean>} false when that version kept no file
+ */
+export async function restoreVersionFile(id, num) {
+    if (!validId(id) || !/^\d{1,7}$/.test(String(num))) return false;
+    await fs.mkdir(FILES_DIR, {recursive: true});
+    try { await fs.copyFile(versionFilePath(id, num), filePath(id)); return true; } catch { return false; }
+}
+
+/** An earlier upload's bytes, or null. */
+export async function readVersionFile(id, num) {
+    if (!validId(id) || !/^\d{1,7}$/.test(String(num))) return null;
+    try { return await fs.readFile(versionFilePath(id, num)); } catch { return null; }
+}
+
+/**
+ * Whether a save should keep what it replaces as a version. Not when the
+ * same person saved the document less than ten minutes ago: that text is
+ * their own work in progress (autosave), and keeping every one of those
+ * would push real history out of the retention limit.
+ */
+export function shouldSnapshot(doc, userId, now = Date.now()) {
+    if (doc.updatedBy !== userId) return true;
+    // 2.12: a save credited to someone else by name (an approved suggestion) is never folded into the next one.
+    if (doc.creditName && doc.creditAt && doc.creditAt === doc.updatedAt) return true;
+    const last = Date.parse(doc.updatedAt || '') || 0;
+    return now - last > 10 * 60 * 1000;
+}
+
+export async function listVersions(id) {
+    const dir = path.join(VERSIONS_DIR, id);
+    const files = (await fs.readdir(dir).catch(() => [])).filter(f => f.endsWith('.json'));
+    const out = [];
+    for (const f of files) {
+        try { out.push(JSON.parse(await fs.readFile(path.join(dir, f), 'utf8'))); } catch { /* skip */ }
+    }
+    return out.sort((a, b) => b.num - a.num);
+}
+
+export async function readVersion(id, num) {
+    if (!/^\d{1,7}$/.test(String(num))) return null;
+    try {
+        return JSON.parse(await fs.readFile(path.join(VERSIONS_DIR, id, `${num}.json`), 'utf8'));
+    } catch {
+        return null;
+    }
+}
+
+// ------------------------------------------------------------------- access
+
+/**
+ * What this user may do with a document.
+ *
+ * - `owner`   - everything, including trash, delete, move and transfer
+ * - `editor`  - edit, share, public link, send
+ * - `viewer`  - read, export, duplicate into their own documents
+ * - null      - nothing; the API answers 404 so a document's existence
+ *               does not leak
+ *
+ * `scope: 'all'` (the old site-wide setting) still reads for everybody and
+ * lets an admin change anything.
+ *
+ * @param   {object}  doc
+ * @param   {object}  user    request.user
+ * @param   {boolean} isAdmin
+ * @returns {'owner'|'editor'|'suggester'|'viewer'|null}  (a Suggester is a Viewer who may also suggest changes - 2.5)
+ */
+export function accessOf(doc, user, isAdmin = false) {
+    if (!doc || !user) return null;
+    if (doc.userId === user.id) return 'owner';
+    const share = (doc.shares || []).find(s => s.userId === user.id);
+    const siteWide = runtime.config.scope === 'all';
+    if (siteWide && isAdmin) return 'owner';
+    const own = share ? (share.role === 'editor' ? 'editor' : share.role === 'suggester' ? 'suggester' : 'viewer')
+        : siteWide ? 'viewer' : null;
+    // An add-on may give more (2.11): the Wiki makes its editors editors of its pages.
+    if (own === 'editor') return own;
+    const extra = extensionAccess(doc, user);
+    if (extra === 'editor') return 'editor';
+    return own || extra;
+}
+
+/**
+ * Why this person may not share, link or send this document (2.11), or ''.
+ * Access that comes only through an add-on is for editing and history - never
+ * for passing the document on (and a share would outlive the add-on's grant).
+ * A document an add-on restricts (a members-only wiki page) leaves Docs for nobody.
+ */
+export function outwardRefusal(doc, user) {
+    if (onlyThroughExtension(doc, user)) return 'You can edit this document through another tool, not share, link or send it.';
+    try { return docsRegistry().restrictionOf?.(doc) || ''; } catch { return 'This document cannot leave Docs right now.'; }
+}
+
+/**
+ * Why this person may not change this document now (2.12): an add-on's freeze (a
+ * protected wiki page), owner included - or ''. A failing registry freezes.
+ */
+export function frozenFor(doc, user) {
+    if (!doc || !user) return '';
+    try { return docsRegistry().frozenFor?.(doc, user) || ''; } catch { return 'This document cannot be changed right now.'; }
+}
+
+/** What add-ons give this user on this document (2.11) - 'editor', 'viewer' or null. */
+export function extensionAccess(doc, user) {
+    try { return docsRegistry().extraAccess?.(doc, user) || null; } catch { return null; }
+}
+
+/**
+ * Reached only through an add-on (2.11): not theirs, not shared with them, not
+ * site-wide. Such a document (a Wiki page) is in their Starred and Recent when
+ * they starred or opened it, and in no other place on Home - it was never shared
+ * with them.
+ */
+export function onlyThroughExtension(doc, user) {
+    if (!doc || !user || doc.userId === user.id || runtime.config.scope === 'all') return false;
+    if ((doc.shares || []).some(s => s.userId === user.id)) return false;
+    return Boolean(extensionAccess(doc, user));
+}
+
+export const canEdit = (a) => a === 'owner' || a === 'editor';
+
+// --------------------------------------------------------------- user state
+
+let userState = null;
+
+async function loadUserState() {
+    if (userState) return userState;
+    try { userState = JSON.parse(await fs.readFile(USER_STATE, 'utf8')); } catch { userState = {}; }
+    if (!userState || typeof userState !== 'object' || Array.isArray(userState)) userState = {};
+    return userState;
+}
+
+let stateWrite = Promise.resolve();
+async function saveUserState() {
+    const data = JSON.stringify(userState, null, 2);
+    stateWrite = stateWrite.catch(() => {}).then(async () => {
+        await fs.mkdir(DATA_DIR, {recursive: true});
+        const tmp = `${USER_STATE}.${process.pid}.tmp`;
+        await fs.writeFile(tmp, data);
+        await fs.rename(tmp, USER_STATE);
+    });
+    return stateWrite;
+}
+
+/**
+ * @param   {string} userId
+ * @returns {Promise<{starred:string[], recent:Array<{id:string, at:string}>}>}
+ */
+export async function stateFor(userId) {
+    const all = await loadUserState();
+    const s = all[userId] || {};
+    return {starred: Array.isArray(s.starred) ? s.starred : [], recent: Array.isArray(s.recent) ? s.recent : []};
+}
+
+export async function setStar(userId, docId, on) {
+    const all = await loadUserState();
+    const s = await stateFor(userId);
+    const starred = s.starred.filter(id => id !== docId);
+    if (on) starred.unshift(docId);
+    all[userId] = {...s, starred: starred.slice(0, 500)};
+    try { await saveUserState(); } finally { bumpWriteGen(); }
+    return on;
+}
+
+export async function touchRecent(userId, docId) {
+    const all = await loadUserState();
+    const s = await stateFor(userId);
+    const recent = [{id: docId, at: new Date().toISOString()}, ...s.recent.filter(r => r.id !== docId)].slice(0, 100);
+    all[userId] = {...s, recent};
+    await saveUserState();
+}
+
+/** Forget a document everywhere once it is gone for good. */
+export async function forgetDoc(docId) {
+    const all = await loadUserState();
+    let changed = false;
+    for (const [uid, s] of Object.entries(all)) {
+        const starred = (s.starred || []).filter(id => id !== docId);
+        const recent = (s.recent || []).filter(r => r.id !== docId);
+        if (starred.length !== (s.starred || []).length || recent.length !== (s.recent || []).length) {
+            all[uid] = {...s, starred, recent};
+            changed = true;
+        }
+    }
+    if (changed) await saveUserState();
+}
+
+// -------------------------------------------------------------------- locks
+
+/**
+ * Who is editing what. In memory: a lock outlives nothing but the process,
+ * and a restart letting everyone back in is the right way round to fail.
+ * Keyed by document; held by one editor session (a browser tab).
+ */
+const locks = new Map();
+export const LOCK_TTL_MS = 90 * 1000;
+
+export function lockOf(docId, now = Date.now()) {
+    const l = locks.get(docId);
+    if (!l) return null;
+    if (l.expires <= now) { locks.delete(docId); return null; }
+    return l;
+}
+
+/**
+ * Take or refresh the lock. Refused while another session holds it, unless
+ * `force` - the owner taking over, or the same person in another tab.
+ *
+ * @returns {{ok:boolean, lock:object}}
+ */
+export function acquireLock(docId, {userId, name, session, force = false, suggester = false}, now = Date.now()) {
+    const held = lockOf(docId, now);
+    if (held && held.session !== session && !force) return {ok: false, lock: held};
+    const lock = {userId, name: name || 'Someone', session, suggester: Boolean(suggester), since: held && held.session === session ? held.since : new Date(now).toISOString(), expires: now + LOCK_TTL_MS};
+    locks.set(docId, lock);
+    return {ok: true, lock, tookOver: Boolean(held && held.session !== session)};
+}
+
+export function releaseLock(docId, session) {
+    const held = locks.get(docId);
+    if (held && held.session === session) locks.delete(docId);
+}
+
+/** The lock as the API shows it - never the session of somebody else. */
+export function publicLock(lock, session) {
+    if (!lock) return null;
+    return {userId: lock.userId, name: lock.name, since: lock.since, mine: lock.session === session, suggester: Boolean(lock.suggester)};
+}
+
+export function clearLocks() { locks.clear(); }
+
+// ------------------------------------------------------------ public links
+
+let linkIndex = null;
+
+export function newLinkToken() {
+    return crypto.randomBytes(18).toString('base64url');
+}
+
+/**
+ * The document behind a public link, or null. Trashed documents and a site
+ * with public links switched off answer null.
+ *
+ * @param   {string} token
+ * @returns {Promise<object|null>}
+ */
+export async function docByToken(token) {
+    if (!runtime.config.publicLinks) return null;
+    if (typeof token !== 'string' || !/^[A-Za-z0-9_-]{16,64}$/.test(token)) return null;
+    if (!linkIndex) {
+        linkIndex = new Map();
+        for (const d of await listDocs()) if (d.publicLink?.token) linkIndex.set(d.publicLink.token, d.id);
+    }
+    const id = linkIndex.get(token);
+    if (!id) return null;
+    const doc = await readDoc(id);
+    if (!doc || doc.trashedAt || doc.publicLink?.token !== token) return null;
+    return doc;
+}
+
+// -------------------------------------------------------------------- rows
+
+/**
+ * A document as a list row: no body, an excerpt instead.
+ *
+ * @param {object} doc
+ * @param {object} ctx {user, isAdmin, state, names:Map, session}
+ */
+export function toRow(doc, {user, isAdmin, state, names}) {
+    const access = accessOf(doc, user, isAdmin);
+    const lock = lockOf(doc.id);
+    const opened = state.recent.find(r => r.id === doc.id)?.at || null;
+    return {
+        id: doc.id,
+        title: doc.title || 'Untitled',
+        excerpt: preview(doc.content, 400),
+        wordCount: Number(doc.wordCount) || 0,
+        // 2.13: a PDF document shows its pages and size where an HTML one shows words.
+        format: kindOf(doc),
+        ...(kindOf(doc) === 'pdf' ? {file: {pages: Number(doc.file?.pages) || 0, size: Number(doc.file?.size) || 0}} : {}),
+        folderId: doc.userId === user.id ? (doc.folderId || null) : null,
+        userId: doc.userId,
+        ownerName: names.get(doc.userId) || 'Unknown',
+        access,
+        starred: state.starred.includes(doc.id),
+        shared: (doc.shares || []).length > 0,
+        public: Boolean(doc.publicLink?.token),
+        // 2.11: no Share or Email on Home for these (see outwardRefusal).
+        outward: !outwardRefusal(doc, user),
+        locked: lock && lock.userId !== user.id ? {name: lock.name, since: lock.since} : null,
+        createdAt: doc.createdAt,
+        updatedAt: doc.updatedAt,
+        openedAt: opened,
+        trashedAt: doc.trashedAt || null
+    };
+}
+
+/**
+ * Pick and order the rows for one view of Home.
+ *
+ * @param {Array}  docs   every document on disk
+ * @param {object} q      {view, folder, q}
+ * @param {object} ctx    as toRow
+ * @returns {Array} rows
+ */
+/** Is `d` in this place (Home's rail) for this user? selectRows and placeCounts share it. */
+export function inView(d, view, {user, isAdmin, state}) {
+    if (!accessOf(d, user, isAdmin)) return false;
+    if (view === 'trash') return Boolean(d.trashedAt) && d.userId === user.id;
+    if (d.trashedAt) return false;
+    if (onlyThroughExtension(d, user)) {
+        if (view === 'starred') return state.starred.includes(d.id);
+        if (view === 'recent') return state.recent.some(r => r.id === d.id);
+        return false;
+    }
+    switch (view) {
+        case 'starred': return state.starred.includes(d.id);
+        case 'shared': return d.userId !== user.id;
+        case 'recent': return true;
+        case 'all': return true;
+        default: return d.userId === user.id;   // mine
+    }
+}
+
+/**
+ * How many documents each of Home's places shows when opened (2.10) - the
+ * numbers on the rail. "My documents" is its top level, as the list shows it
+ * (documents in folders are under their folder).
+ *
+ * @returns {{starred: number, shared: number, mine: number, trash: number}}
+ */
+export function placeCounts(docs, ctx) {
+    const n = (view, more = () => true) => docs.filter(d => inView(d, view, ctx) && more(d)).length;
+    return {starred: n('starred'), shared: n('shared'), mine: n('mine', d => !d.folderId), trash: n('trash')};
+}
+
+export function selectRows(docs, {view = 'mine', folder, q} = {}, ctx) {
+    const {user} = ctx;
+    const term = typeof q === 'string' ? q.trim().toLowerCase() : '';
+    const time = (iso) => Date.parse(iso || '') || 0;
+    let list = docs.filter(d => inView(d, view, ctx));
+    if (view === 'mine' && folder !== undefined) {
+        const f = folder === '' || folder === 'null' ? null : folder;
+        list = list.filter(d => (d.folderId || null) === f);
+    }
+    if (term) {
+        list = list.filter(d => (d.title || '').toLowerCase().includes(term)
+            || String(d.content || '').replace(/<[^>]+>/g, ' ').toLowerCase().includes(term));
+    }
+    const rows = list.map(d => toRow(d, ctx));
+    if (view === 'recent') {
+        rows.sort((a, b) => Math.max(time(b.openedAt), b.userId === user.id ? time(b.updatedAt) : 0)
+            - Math.max(time(a.openedAt), a.userId === user.id ? time(a.updatedAt) : 0));
+        return rows.slice(0, 60);
+    }
+    if (view === 'trash') return rows.sort((a, b) => time(b.trashedAt) - time(a.trashedAt));
+    return rows.sort((a, b) => time(b.updatedAt) - time(a.updatedAt));
+}
+
+/**
+ * Remove documents that have sat in Trash longer than the setting allows.
+ *
+ * @returns {Promise<number>} how many went
+ */
+export async function purgeTrash(now = Date.now()) {
+    const days = Math.max(1, Number(runtime.config.trashDays) || 30);
+    let n = 0;
+    for (const d of await listDocs()) {
+        if (d.trashedAt && now - Date.parse(d.trashedAt) > days * 86400000) {
+            await removeDoc(d.id);
+            await forgetDoc(d.id);
+            n++;
+        }
+    }
+    return n;
+}