domma-cms 1.8.32 → 1.8.34

package/plugins/docs/plugin.js

@@ -0,0 +1,1108 @@
+/**
+ * Docs - the admin API (`/api/plugins/docs`).
+ *
+ * Storage, access rules, locks and the sanitiser live in lib/store.js, shared
+ * with plugin.public.js (the public link page). See CLAUDE.md for the model.
+ *
+ * @module docs/plugin
+ */
+
+import {createStore} from '../_lib/dataStore.js';
+import {savePluginState} from '../../server/services/plugins.js';
+import {getEffectiveLevel, getEffectiveRoles} from '../../server/services/userRoles.js';
+import {listUsers} from '../../server/services/users.js';
+import {getPermissionsFor, getRoleLevel} from '../../server/services/roles.js';
+import {getConfig} from '../../server/config.js';
+import {originOf, trustedOrigin} from '../../server/services/passwordReset.js';
+import {createTransport, sendEmail} from '../../server/services/email.js';
+import {marked} from 'marked';
+import defaultConfig from './config.js';
+import {randomUUID, randomBytes, createHmac, timingSafeEqual} from 'crypto';
+import fs from 'fs/promises';
+import path from 'path';
+import {
+    runtime, sanitizeDoc, withoutSuggestions, allowMarkup, readDoc, writeDoc, mutateDoc, removeDoc, listDocs, newDoc, cleanTitle, shouldSnapshot,
+    snapshotVersion, listVersions, readVersion, accessOf, canEdit, stateFor, setStar, touchRecent, forgetDoc,
+    lockOf, acquireLock, releaseLock, publicLock, newLinkToken, selectRows, placeCounts, purgeTrash, validId, DATA_DIR,
+    outwardRefusal, onlyThroughExtension, frozenFor,
+    kindOf, readFileBytes, writeFileBytes, copyFileBytes, restoreVersionFile, readVersionFile, fileRecord
+} from './lib/store.js';
+import {importFile, kindOf as importKind} from './lib/importer.js';
+import {inspectPdf, extractPdfText, extractToHtml, extractCapability, contentDisposition, cleanFileName, MAX_PDF_BYTES} from './lib/pdf.js';
+import {docsRegistry} from './lib/extensions.js';
+import {countWords, escapeHtml, htmlToText, htmlToMarkdown, standaloneHtml, fileName, startsWithTitle, parseHtml} from './admin/lib/convert.js';
+
+const foldersStore = createStore(path.join(DATA_DIR, 'folders.json'));
+const templatesStore = createStore(path.join(DATA_DIR, 'templates.json'));
+
+const MIN_VERSIONS = 5;
+const MAX_VERSIONS = 500;
+const EMAIL_RE = /^[^\s@<>(),;:"]+@[^\s@<>(),;:"]+\.[^\s@<>(),;:"]+$/;
+const MAX_RECIPIENTS = 10;
+const DAILY_RECIPIENTS = 50;
+
+/** Addresses each person has emailed today, by user id. In memory: a restart forgives. */
+const sentToday = new Map();
+function allowance(userId, n, now = Date.now()) {
+    const day = new Date(now).toISOString().slice(0, 10);
+    const cur = sentToday.get(userId);
+    const used = cur && cur.day === day ? cur.n : 0;
+    if (used + n > DAILY_RECIPIENTS) return false;
+    sentToday.set(userId, {day, n: used + n});
+    return true;
+}
+
+/** 'https://example.com' from a configured address, or '' when it is not one. */
+function origin(value) {
+    const v = String(value ?? '').trim().replace(/\/+$/, '');
+    return /^https?:\/\/[^\s/?#]+$/i.test(v) ? v : '';
+}
+
+/** The Site URL setting (or the old `site.url`) as an origin, else ''. Sync; links for emails: `linkBase`. */
+export function siteBase() {
+    const site = getConfig('site') || {};
+    return origin(site.baseUrl) || origin(site.url);
+}
+
+/**
+ * Where links in emails point: the Site URL, else - as core does for password
+ * resets - an address someone has really signed in on. Never the Host header
+ * of the request: anyone can send any Host, and a share notification would
+ * then carry a lookalike address to colleagues. '' when the site knows none.
+ */
+export async function linkBase(req) {
+    return siteBase() || await trustedOrigin(originOf(req)).catch(() => '');
+}
+
+/** Text with no HTML tags at all: written in the old Markdown editor (or plain text). */
+export function looksLikeMarkdown(content) {
+    const c = String(content ?? '');
+    return c.trim() !== '' && !/<\/?[a-z][a-z0-9]*[\s>/]/i.test(c);
+}
+
+/** HTML from a pre-2.0 body: Markdown converted, HTML sanitised. */
+export function upgradeBody(content) {
+    const c = String(content ?? '');
+    return sanitizeDoc(looksLikeMarkdown(c) ? marked.parse(c, {gfm: true, async: false}) : c);
+}
+
+/**
+ * Bring pre-2.0 documents and templates up to 2.0, once: bodies with no HTML
+ * at all were written in the old Markdown editor (the mode was site-wide
+ * and switchable, so it is decided per document, not by the setting) and
+ * are converted; everything else is sanitised - 1.x stored bodies raw.
+ * Originals go to data/.backup-markdown/ first. Versions are upgraded when
+ * restored.
+ */
+export async function migrateLegacy(log) {
+    const todo = (await listDocs()).filter(d => !d.format);
+    const templates = await templatesStore.readArray().catch(() => []);
+    const oldTemplates = templates.filter(t => !t.format);
+    if (!todo.length && !oldTemplates.length) return 0;
+    const backup = path.join(DATA_DIR, '.backup-markdown');
+    await fs.mkdir(backup, {recursive: true});
+    for (const d of todo) {
+        await fs.writeFile(path.join(backup, `${d.id}.json`), JSON.stringify(d, null, 2));
+        await mutateDoc(d.id, (cur) => {
+            if (cur.format) return null;
+            const html = upgradeBody(cur.content);
+            return {...cur, content: html, format: 'html', shares: cur.shares || [], publicLink: cur.publicLink || null,
+                trashedAt: cur.trashedAt || null, wordCount: countWords(html)};
+        });
+    }
+    if (oldTemplates.length) {
+        await fs.writeFile(path.join(backup, 'templates.json'), JSON.stringify(templates, null, 2));
+        for (const t of oldTemplates) await templatesStore.updateItem(t.id, {content: upgradeBody(t.content), format: 'html'});
+    }
+    log?.info?.(`[docs] upgraded ${todo.length} document(s) and ${oldTemplates.length} template(s) to 2.0 (originals in data/.backup-markdown)`);
+    return todo.length;
+}
+
+export default async function docsPlugin(fastify, options) {
+    const {authenticate, requireAdmin, requirePermission} = options.auth;
+    const config = runtime.config;
+    Object.assign(config, defaultConfig, options.settings || {});
+    delete config.editorMode;
+
+    const registry = docsRegistry();
+    // Injectable for tests: the user list and the mail transport (core's
+    // createTransport always does network I/O).
+    const listPeople = typeof options.listUsers === 'function' ? options.listUsers : listUsers;
+    const mailer = options.mailer || {createTransport, sendEmail};
+
+    // The Docs permission: granted to admin and user; take it from a role
+    // under Roles and that role has no Docs. An older core without
+    // requirePermission keeps the old rule (any signed-in account).
+    const need = (action) => (typeof requirePermission === 'function' ? requirePermission('docs', action) : async () => {});
+    const read = [authenticate, need('read')];
+    const make = [authenticate, need('create')];
+    const edit = [authenticate, need('update')];
+    const drop = [authenticate, need('delete')];
+    const isAdmin = (req) => { try { return getEffectiveLevel(req.user) <= 1; } catch { return false; } };
+
+    /** Names by user id, for owners and share lists. Cached briefly - listUsers reads every user file. */
+    let names = null;
+    let namesAt = 0;
+    let usersCache = [];
+    async function people() {
+        if (!names || Date.now() - namesAt > 30000) {
+            usersCache = await Promise.resolve().then(listPeople).catch(() => []);
+            names = new Map(usersCache.map(u => [u.id, String(u.name || '').trim() || u.email || 'Unnamed']));
+            namesAt = Date.now();
+        }
+        return {names, users: usersCache};
+    }
+    const nameOf = (req) => String(req.user?.name || '').trim() || req.user?.email || 'Someone';
+
+    /**
+     * The document and what this user may do with it, or a 404 already sent.
+     * `want`: 'read' | 'edit' | 'suggest' (edit, or a Suggester while an add-on
+     * offers suggestions - 2.5) | 'owner'.
+     */
+    async function load(req, reply, want = 'read') {
+        const doc = await readDoc(req.params.id);
+        const access = accessOf(doc, req.user, isAdmin(req));
+        const mayWrite = canEdit(access) || (want === 'suggest' && access === 'suggester' && registry.hasSuggest());
+        let ok = access && (want === 'read' || (want === 'edit' || want === 'suggest' ? mayWrite : access === 'owner'));
+        // In Trash a document belongs to its owner alone until it is restored.
+        if (ok && doc.trashedAt && doc.userId !== req.user.id) ok = false;
+        if (!ok) {
+            if (access && doc?.trashedAt && doc.userId !== req.user.id) { reply.code(404).send({error: 'Document not found'}); return null; }
+            // A viewer asking to edit gets told why; anyone else learns nothing.
+            if (access && want !== 'read') reply.code(403).send({error: want === 'owner' ? 'Only the owner can do that.' : 'You can view this document but not edit it.'});
+            else reply.code(404).send({error: 'Document not found'});
+            return null;
+        }
+        return {doc, access};
+    }
+
+    /** A folder a document may be filed in: one of this user's own. */
+    async function usableFolder(req, folderId) {
+        if (!folderId) return true;
+        const f = (await foldersStore.readArray()).find(x => x.id === folderId);
+        return Boolean(f && (f.userId === req.user.id || config.scope === 'all'));
+    }
+
+    /** The whole document as the editor sees it: body, access, lock, star, people. */
+    async function full(req, doc, access) {
+        const {names} = await people();
+        const state = await stateFor(req.user.id);
+        const session = String(req.headers['x-docs-session'] || '');
+        return {
+            ...doc,
+            // Sanitised on the way out too: a body written before 2.0 was stored as it came. A PDF's content is its text extract (2.13).
+            content: doc.format === 'html' || kindOf(doc) === 'pdf' ? doc.content : upgradeBody(doc.content),
+            format: kindOf(doc),
+            access,
+            ownerName: names.get(doc.userId) || 'Unknown',
+            starred: state.starred.includes(doc.id),
+            lock: publicLock(lockOf(doc.id), session),
+            shares: (doc.shares || []).map(s => ({...s, name: names.get(s.userId) || 'Unknown'})),
+            publicLink: doc.publicLink ? {...doc.publicLink, ...registry.linkInfo(doc)} : null,
+            publicLinksAllowed: config.publicLinks !== false,
+            // 2.11: why it may not be shared, linked or sent by this person ('' = it may).
+            outwardRefusal: outwardRefusal(doc, req.user),
+            // 2.11: an add-on's restriction - no NEW people either (existing shares keep working; removing is allowed).
+            restricted: registry.restrictionOf?.(doc) || '',
+            // 2.12: why this person may not change it now (a protected wiki page) - the editor opens read only.
+            frozen: frozenFor(doc, req.user),
+            // 2.13: a PDF's viewer address for this person, good for twenty minutes (refreshed with every poll).
+            ...(kindOf(doc) === 'pdf' ? {fileTicket: viewTicket(doc, req)} : {})
+        };
+    }
+
+    // Services an extension (Docs Pro) works through.
+    registry.services = {
+        // 2.12: why this person may not share, link, send - or publish - this document ('' = they may).
+        outwardRefusal: (doc, user) => outwardRefusal(doc, user),
+        readDoc, writeDoc, listDocs, accessOf: (doc, user) => accessOf(doc, user, (() => { try { return getEffectiveLevel(user) <= 1; } catch { return false; } })()),
+        sanitizeDoc, allowMarkup, siteBase, linkBase, people, config: () => ({...config}), htmlToText,
+        // Folders (2.1) - Docs Pro's Spaces are folders.
+        listFolders: () => foldersStore.readArray(),
+        /** Mark a document's public link as protected by an add-on (2.3): Docs then refuses it when no gate is there. */
+        setLinkGuard: (docId, on) => mutateDoc(docId, (cur) => (Boolean(cur.linkGuarded) === Boolean(on) ? null : {...cur, linkGuarded: Boolean(on)})),
+        // Conversions (2.2) - Docs Pro's cloud copies write the same files Download does.
+        convert: {standaloneHtml, htmlToMarkdown, htmlToText, fileName, startsWithTitle, parseHtml},
+        /**
+         * Make a document for a user, as POST /documents does (2.4): the body is
+         * sanitised, the folder must be one they may file in, it goes in their Recent.
+         */
+        createDoc: async ({title, content = '', folderId = null}, user) => {
+            const req = {user};
+            if (folderId && !(await usableFolder(req, folderId))) throw new Error('No such folder');
+            const doc = await writeDoc(newDoc({title, content, folderId}, user));
+            await touchRecent(user.id, doc.id);
+            return doc;
+        },
+        isAdmin: (user) => { try { return getEffectiveLevel(user) <= 1; } catch { return false; } },
+        // 2.11 (the Wiki): change a document inside its write chain, as every Docs route does; a body as the
+        // public sees it (sanitised, pending suggestions not made, add-ons' filters); who is editing it now.
+        mutateDoc: (id, fn) => mutateDoc(id, fn),
+        publicHtml: (html) => registry.publicHtml(withoutSuggestions(sanitizeDoc(html))),
+        lockOf: (id) => publicLock(lockOf(id), ''),
+        // 2.12 (Wiki Pro's approved suggestions): keep what a change replaces as a version, as a save does.
+        // A document's `creditName` + `creditAt` (= its updatedAt) names who that save is credited to.
+        snapshotVersion: (doc, by = null) => snapshotVersion(doc, Number(config.maxVersions) || 50, by),
+        // 2.13: PDF documents. kindOf says which a document is; readFile is its bytes; writeFile replaces them
+        // (checked, extracted, versioned - as PUT .../file does) and answers the document as written.
+        kindOf,
+        readFile: (docId) => readFileBytes(docId),
+        writeFile: (docId, buf, user, {name} = {}) => replacePdf(docId, buf, {name, user}),
+        pdfCapability: () => extractCapability(),
+        /**
+         * Make a PDF document from bytes for a user (2.13.1 - Docs Pro's "take pages out"): checked and read
+         * as an upload is, filed where they may file, into their Recent. Throws {status, message}.
+         */
+        createPdfDoc: async ({title, buf, name = 'document.pdf', folderId = null}, user) => {
+            const req = {user};
+            if (folderId && !(await usableFolder(req, folderId))) throw Object.assign(new Error('No such folder'), {status: 400});
+            const prepared = await preparePdf(buf, name, user);
+            const doc = newDoc({title: String(title || '').trim() || cleanFileName(name).replace(/\.pdf$/i, '') || 'Untitled', content: prepared.content, folderId, format: 'pdf', file: prepared.file}, user);
+            await writeFileBytes(doc.id, buf);
+            await writeDoc(doc);
+            await touchRecent(user.id, doc.id);
+            return doc;
+        }
+    };
+
+    // ------------------------------------------------------------- PDF files (2.13)
+
+    /**
+     * Check a PDF and read its text. {content, file} for the record, or an
+     * Error with the plain reason the person sees.
+     */
+    async function preparePdf(buf, name, user) {
+        const checked = inspectPdf(buf, {maxBytes: MAX_PDF_BYTES});
+        if (!checked.ok) throw Object.assign(new Error(checked.reason), {status: 400});
+        const read = checked.encrypted ? null : await extractPdfText(buf);
+        const content = read?.text ? sanitizeDoc(extractToHtml(read.text)) : '';
+        return {content, file: fileRecord({name: cleanFileName(name), size: buf.length, pages: read?.pages || checked.pages, sha256: checked.sha256, encrypted: checked.encrypted}, user)};
+    }
+
+    /**
+     * Replace a PDF document's file (an upload of a new version). The record's
+     * text extract and file facts follow; what it had is kept as a version
+     * (always - a new upload is a real change, not an autosave). Refused in Trash
+     * (409), while another session holds the edit lock (423), frozen (403).
+     */
+    async function replacePdf(docId, buf, {name, user, session = ''}) {
+        const before = await readDoc(docId);
+        if (!before) throw Object.assign(new Error('Document not found'), {status: 404});
+        if (kindOf(before) !== 'pdf') throw Object.assign(new Error('Only a PDF document takes a file.'), {status: 400});
+        const prepared = await preparePdf(buf, name || before.file?.name, user);
+        let refused = null;
+        const updated = await mutateDoc(docId, async (doc) => {
+            if (doc.trashedAt) { refused = [409, {error: 'This document is in Trash. Restore it to replace its file.'}]; return null; }
+            const frozen = frozenFor(doc, user);
+            if (frozen) { refused = [403, {error: frozen, frozen: true}]; return null; }
+            const held = lockOf(doc.id);
+            if (held && held.session !== session) { refused = [423, {error: `${held.name} has this document open.`, lock: publicLock(held, session)}]; return null; }
+            await snapshotVersion(doc, Number(config.maxVersions) || 50, user.id);
+            await writeFileBytes(doc.id, buf);
+            return {...doc, content: prepared.content, file: prepared.file, wordCount: countWords(prepared.content), updatedAt: new Date().toISOString(), updatedBy: user.id};
+        });
+        if (refused) throw Object.assign(new Error(refused[1].error), {status: refused[0], body: refused[1]});
+        if (!updated) throw Object.assign(new Error('Document not found'), {status: 404});
+        registry.emit('saved', updated, user);
+        return updated;
+    }
+
+    /**
+     * View tickets (2.13). The admin shows a PDF in an <iframe>, which can carry no bearer
+     * header, and the admin's CSP frames only 'self' - so the frame's address is the file
+     * route with a short-lived ticket: HMAC of document, person and expiry under a key made
+     * at boot (a restart ends every ticket; the screen gets a fresh one with each poll). The
+     * ticket says who asked and what they could do then; the route checks the document again.
+     */
+    const VIEW_TTL_MS = 20 * 60 * 1000;
+    const viewKey = randomBytes(32);
+    function viewTicket(doc, req) {
+        const body = Buffer.from(JSON.stringify({d: doc.id, u: req.user.id, a: isAdmin(req) ? 1 : 0, e: Date.now() + VIEW_TTL_MS})).toString('base64url');
+        return `${body}.${createHmac('sha256', viewKey).update(body).digest('base64url')}`;
+    }
+    function readViewTicket(ticket, docId) {
+        const [body, sig] = String(ticket || '').split('.');
+        if (!body || !sig || body.length > 400) return null;
+        const want = createHmac('sha256', viewKey).update(body).digest();
+        let got;
+        try { got = Buffer.from(sig, 'base64url'); } catch { return null; }
+        if (got.length !== want.length || !timingSafeEqual(got, want)) return null;
+        let claims;
+        try { claims = JSON.parse(Buffer.from(body, 'base64url').toString('utf8')); } catch { return null; }
+        if (!claims || claims.d !== docId || typeof claims.u !== 'string' || !(claims.e > Date.now())) return null;
+        return {userId: claims.u, admin: claims.a === 1};
+    }
+
+    /** The headers a PDF goes out with: never sniffed, never cached, never scripted, never indexed. */
+    function sendPdf(reply, buf, title, {inline = false} = {}) {
+        return reply.type('application/pdf')
+            .header('Content-Disposition', contentDisposition(fileName(title, 'pdf'), inline))
+            .header('X-Content-Type-Options', 'nosniff')
+            .header('Cache-Control', 'private, no-store')
+            .header('Content-Security-Policy', "default-src 'none'; sandbox")
+            .header('X-Robots-Tag', 'noindex')
+            .send(buf);
+    }
+
+    /** A base64 upload body {name, data}: the bytes, or a 400 already sent. */
+    function bytesOf(req, reply) {
+        const b = req.body || {};
+        if (typeof b.data !== 'string' || !b.data) { reply.code(400).send({error: 'No file was uploaded.'}); return null; }
+        let buf;
+        try { buf = Buffer.from(b.data.replace(/^data:[^,]*,/, ''), 'base64'); } catch { buf = null; }
+        if (!buf || !buf.length) { reply.code(400).send({error: 'The file could not be read.'}); return null; }
+        if (buf.length > MAX_PDF_BYTES) { reply.code(400).send({error: `The file is over ${Math.round(MAX_PDF_BYTES / 1024 / 1024)} MB.`}); return null; }
+        return buf;
+    }
+    const UPLOAD_BODY = Math.ceil(MAX_PDF_BYTES * 1.4) + 4096;
+
+    fastify.addHook('onReady', async () => {
+        await migrateLegacy(fastify.log).catch(err => fastify.log.error({err}, '[docs] 2.0 upgrade of old documents failed'));
+        await purgeTrash().catch(() => {});
+    });
+
+    // ------------------------------------------------------------- settings
+
+    /*
+     * What the admin screen may know about its own configuration -
+     * whitelisted, never spread, so a secret added to the settings object is
+     * not handed to the browser.
+     */
+    fastify.get('/settings', {preHandler: read}, async (req) => ({
+        autoSaveInterval: Number(config.autoSaveInterval) || 0,
+        maxVersions: Number(config.maxVersions) || 50,
+        publicLinks: config.publicLinks !== false,
+        allowSend: config.allowSend !== false,
+        trashDays: Number(config.trashDays) || 30,
+        // Shown, never edited here: flipping 'user' to 'all' would hand every
+        // user everybody else's documents - a decision for config.
+        scope: config.scope === 'all' ? 'all' : 'user',
+        canEdit: isAdmin(req),
+        extensions: registry.adminModules(),
+        suggestions: registry.hasSuggest(),
+        // 2.13: PDF documents - uploads always; the text inside them is searchable when pdfjs-dist is on this server.
+        pdf: {maxBytes: MAX_PDF_BYTES, search: extractCapability().available, reason: extractCapability().reason}
+    }));
+
+    fastify.put('/settings', {preHandler: [authenticate, requireAdmin]}, async (req, reply) => {
+        const body = req.body || {};
+        const next = {};
+        if (body.autoSaveInterval !== undefined) {
+            const ms = Number(body.autoSaveInterval);
+            if (!Number.isFinite(ms) || ms < 0) return reply.code(400).send({error: 'autoSaveInterval must be 0 or more'});
+            // Under five seconds is a save per keystroke burst, not an autosave.
+            next.autoSaveInterval = ms === 0 ? 0 : Math.min(600000, Math.max(5000, Math.round(ms)));
+        }
+        if (body.maxVersions !== undefined) {
+            const n = Math.round(Number(body.maxVersions));
+            if (!Number.isFinite(n)) return reply.code(400).send({error: 'maxVersions must be a number'});
+            next.maxVersions = Math.min(MAX_VERSIONS, Math.max(MIN_VERSIONS, n));
+        }
+        if (body.publicLinks !== undefined) next.publicLinks = body.publicLinks === true;
+        if (body.allowSend !== undefined) next.allowSend = body.allowSend === true;
+        if (body.trashDays !== undefined) {
+            const n = Math.round(Number(body.trashDays));
+            if (!Number.isFinite(n)) return reply.code(400).send({error: 'trashDays must be a number'});
+            next.trashDays = Math.min(365, Math.max(1, n));
+        }
+        Object.assign(config, next);
+        const saved = {...(options.settings || {}), ...next};
+        delete saved.editorMode;
+        savePluginState('docs', {settings: saved});
+        options.settings = saved;
+        return reply.send({ok: true, ...next});
+    });
+
+    // --------------------------------------------------------------- people
+
+    /**
+     * Who a document can be shared with: people whose role holds Docs. Id and
+     * name; an admin also sees the email, to tell two Sams apart.
+     */
+    fastify.get('/people', {preHandler: read}, async (req) => {
+        const {users} = await people();
+        let roles = null;
+        try { roles = new Set(getPermissionsFor('docs', 'read')); } catch { roles = null; }
+        // Only the root role listed means the permission is not registered
+        // (an older core, a harness) - then nobody can be told apart by it.
+        if (roles && [...roles].every(r => { try { return getRoleLevel(r) === 0; } catch { return true; } })) roles = null;
+        const admin = isAdmin(req);
+        return users
+            .filter(u => u.id !== req.user.id && u.disabled !== true && u.isActive !== false && u.active !== false)
+            .filter(u => !roles || !roles.size || getEffectiveRoles(u).some(r => roles.has(r)))
+            .map(u => ({id: u.id, name: String(u.name || '').trim() || 'Unnamed', ...(admin ? {email: u.email || ''} : {})}));
+    });
+
+    // ------------------------------------------------------------ sidebar badge
+
+    /**
+     * GET /count - the sidebar badge (core countUrl contract): how many documents this person owns
+     * (Trash left out), an inventory a closed folder leaves out of its total. Docs has nothing that
+     * waits on anyone, so there is no attention case. Polled every minute from every open tab and
+     * listDocs reads every file, so it is cached for a minute per person. Every finished write bumps
+     * a generation; a count only keeps its answer if no write finished while it was reading, so the
+     * refresh straight after a save is never an older read stored after the clear.
+     */
+    const BADGE_TTL = 60_000;
+    const badgeCache = new Map();   // uid -> {at, gen, value}
+    // The generation lives in the store (2.10): every document/star write bumps it, Docs Pro's
+    // writes through `services` included. Finished non-GET requests still bump it too.
+    fastify.addHook('onResponse', async (req) => { if (req.method !== 'GET' && req.method !== 'HEAD') runtime.writeGen++; });
+    fastify.get('/count', {preHandler: read}, async (req) => {
+        const uid = req.user.id;
+        const now = Date.now();
+        for (const [k, v] of badgeCache) if (now - v.at >= BADGE_TTL) badgeCache.delete(k);
+        const hit = badgeCache.get(uid);
+        if (hit && hit.gen === runtime.writeGen) return hit.value;
+        const gen = runtime.writeGen;
+        const admin = isAdmin(req);
+        const all = await listDocs();
+        const visible = all.filter(d => accessOf(d, req.user, admin));
+        const mine = visible.filter(d => d.userId === uid && !d.trashedAt)
+            .sort((a, b) => (Date.parse(b.updatedAt || '') || 0) - (Date.parse(a.updatedAt || '') || 0));
+        const shared = visible.filter(d => d.userId !== uid && !d.trashedAt && (d.shares || []).some(x => x.userId === uid)).length;
+        const trashed = visible.filter(d => d.userId === uid && d.trashedAt).length;
+        const live = new Set(visible.filter(d => !d.trashedAt).map(d => d.id));
+        const state = await stateFor(uid);
+        const starred = state.starred.filter(id => live.has(id)).length;
+        const plural = (n, word) => `${n} ${word}${n === 1 ? '' : 's'}`;
+        const value = {
+            count: mine.length,
+            label: `${plural(mine.length, 'document')}${shared ? ` - ${shared} shared with you` : ''}`,
+            tone: 'info',
+            inventory: true,
+            // What each of Home's places shows when opened - the numbers on its rail (2.10).
+            places: placeCounts(all, {user: req.user, isAdmin: admin, state}),
+            details: {
+                title: 'Docs',
+                rows: [{label: 'Yours', value: String(mine.length)}, {label: 'Shared with you', value: String(shared)},
+                    {label: 'Starred', value: String(starred)}, {label: 'In Trash', value: String(trashed)}],
+                items: mine.slice(0, 5).map(d => ({text: d.title || 'Untitled'})),
+                empty: 'No documents yet.'
+            }
+        };
+        if (gen === runtime.writeGen) badgeCache.set(uid, {at: now, gen, value});
+        return value;
+    });
+
+    // ------------------------------------------------------------ documents
+
+    /**
+     * GET /documents?view=mine|recent|starred|shared|all|trash&folder=&q=
+     * Rows, not bodies: an excerpt instead of the content.
+     */
+    fastify.get('/documents', {preHandler: read}, async (req) => {
+        const {view = 'mine', folder, q} = req.query || {};
+        if (view === 'trash') await purgeTrash().catch(() => {});
+        const {names} = await people();
+        const ctx = {user: req.user, isAdmin: isAdmin(req), state: await stateFor(req.user.id), names};
+        return selectRows(await listDocs(), {view: String(view), folder, q}, ctx);
+    });
+
+    // A document with pictures built in (an import, a paste) is larger than Fastify's 1 MB default (2.4).
+    const DOC_BODY = 5 * 1024 * 1024;
+
+    fastify.post('/documents', {preHandler: make, bodyLimit: DOC_BODY}, async (req, reply) => {
+        const body = req.body || {};
+        if (!(await usableFolder(req, body.folderId))) return reply.code(400).send({error: 'No such folder'});
+        // Only an upload makes a PDF document: a record saying 'pdf' with no file behind it is never made here.
+        const doc = await writeDoc(newDoc({title: body.title, content: body.content, folderId: body.folderId, tags: body.tags}, req.user));
+        await touchRecent(req.user.id, doc.id);
+        return reply.code(201).send(await full(req, doc, 'owner'));
+    });
+
+    /** POST /documents/import {name, text, folderId} - a .md, .html or .txt file as a new document. */
+    fastify.post('/documents/import', {preHandler: make, bodyLimit: 5 * 1024 * 1024}, async (req, reply) => {
+        const {name, text, folderId = null} = req.body || {};
+        if (typeof text !== 'string') return reply.code(400).send({error: 'No file content'});
+        if (!importKind(name)) return reply.code(400).send({error: /\.pdf$/i.test(String(name || '')) ? 'A PDF is uploaded as a file, not imported: drop it on the list or choose New > Upload a PDF.' : 'Docs can import .md, .html and .txt files.'});
+        if (!(await usableFolder(req, folderId))) return reply.code(400).send({error: 'No such folder'});
+        const imported = importFile({name, text});
+        const doc = await writeDoc(newDoc({...imported, folderId}, req.user));
+        await touchRecent(req.user.id, doc.id);
+        return reply.code(201).send(await full(req, doc, 'owner'));
+    });
+
+    /**
+     * POST /documents/upload {name, data (base64), folderId, title?} - a PDF
+     * as a new document (2.13). The file is checked (lib/pdf.js), its text
+     * read for search, and it is kept as it is: Docs never rewrites a PDF.
+     */
+    fastify.post('/documents/upload', {preHandler: make, bodyLimit: UPLOAD_BODY, config: {rateLimit: {max: 30, timeWindow: '1 minute'}}}, async (req, reply) => {
+        const {name, folderId = null, title} = req.body || {};
+        const buf = bytesOf(req, reply);
+        if (!buf) return;
+        if (!/\.pdf$/i.test(String(name || '')) && buf.subarray(0, 1024).toString('latin1').indexOf('%PDF-') === -1) return reply.code(400).send({error: 'Docs takes PDF files here.'});
+        if (!(await usableFolder(req, folderId))) return reply.code(400).send({error: 'No such folder'});
+        let prepared;
+        try { prepared = await preparePdf(buf, name, req.user); } catch (err) { return reply.code(err.status || 400).send({error: err.message}); }
+        const base = cleanFileName(name).replace(/\.pdf$/i, '').trim();
+        const doc = newDoc({title: typeof title === 'string' && title.trim() ? title : (base || 'Untitled'), content: prepared.content, folderId, format: 'pdf', file: prepared.file}, req.user);
+        await writeFileBytes(doc.id, buf);
+        await writeDoc(doc);
+        await touchRecent(req.user.id, doc.id);
+        return reply.code(201).send(await full(req, doc, 'owner'));
+    });
+
+    /** GET /documents/:id/file - the PDF itself, inline; ?download=1 saves it. Anyone who may read the document. */
+    fastify.get('/documents/:id/file', {preHandler: read}, async (req, reply) => {
+        const hit = await load(req, reply);
+        if (!hit) return;
+        if (kindOf(hit.doc) !== 'pdf') return reply.code(404).send({error: 'This document has no file.'});
+        const buf = await readFileBytes(hit.doc.id);
+        if (!buf) return reply.code(404).send({error: 'The file is missing.'});
+        return sendPdf(reply, buf, hit.doc.title || 'Untitled', {inline: req.query?.download !== '1'});
+    });
+
+    /**
+     * GET /documents/:id/view?t=<ticket> - the PDF for the admin's frame (2.13). No bearer
+     * header here: the ticket (from GET /documents/:id) is the credential, and the document's
+     * access is checked again for the person it names.
+     */
+    fastify.get('/documents/:id/view', {config: {rateLimit: {max: 120, timeWindow: '1 minute'}}}, async (req, reply) => {
+        const claims = validId(req.params.id) ? readViewTicket(req.query?.t, req.params.id) : null;
+        if (!claims) return reply.code(403).send({error: 'This viewer link has expired. Reload the document.'});
+        // The person must still be here with a role that holds Docs: a ticket outlives neither.
+        const viewer = (await people()).users.find(u => String(u.id) === claims.userId);
+        if (!viewer || viewer.disabled === true || viewer.isActive === false || viewer.active === false) return reply.code(403).send({error: 'This viewer link no longer works.'});
+        try {
+            const allowed = getPermissionsFor('docs', 'read');
+            if (Array.isArray(allowed) && allowed.length && !getEffectiveRoles(viewer).some(r => allowed.includes(r) || (() => { try { return getRoleLevel(r) === 0; } catch { return false; } })())) return reply.code(403).send({error: 'This viewer link no longer works.'});
+        } catch { /* an older core without the permission: the ticket stands */ }
+        const doc = await readDoc(req.params.id);
+        const access = accessOf(doc, {id: claims.userId}, claims.admin);
+        if (!doc || !access || (doc.trashedAt && doc.userId !== claims.userId) || kindOf(doc) !== 'pdf') return reply.code(404).send({error: 'Document not found'});
+        const buf = await readFileBytes(doc.id);
+        if (!buf) return reply.code(404).send({error: 'The file is missing.'});
+        return sendPdf(reply, buf, doc.title || 'Untitled', {inline: true});
+    });
+
+    /** PUT /documents/:id/file {name, data} - a new upload replaces the file; the old one becomes a version. Editors. */
+    fastify.put('/documents/:id/file', {preHandler: edit, bodyLimit: UPLOAD_BODY, config: {rateLimit: {max: 30, timeWindow: '1 minute'}}}, async (req, reply) => {
+        const hit = await load(req, reply, 'edit');
+        if (!hit) return;
+        if (kindOf(hit.doc) !== 'pdf') return reply.code(400).send({error: 'Only a PDF document takes a file.'});
+        const buf = bytesOf(req, reply);
+        if (!buf) return;
+        const session = String(req.headers['x-docs-session'] || req.body?.session || '');
+        try {
+            const updated = await replacePdf(hit.doc.id, buf, {name: req.body?.name, user: req.user, session});
+            return full(req, updated, hit.access);
+        } catch (err) {
+            return reply.code(err.status || 500).send(err.body || {error: err.message || 'The file could not be replaced.'});
+        }
+    });
+
+    fastify.get('/documents/:id', {preHandler: read}, async (req, reply) => {
+        const hit = await load(req, reply);
+        if (!hit) return;
+        // A reader's screen polls with ?poll=1: that is not "opening" it.
+        if (req.query?.poll !== '1') await touchRecent(req.user.id, hit.doc.id);
+        return full(req, hit.doc, hit.access);
+    });
+
+    /**
+     * PUT /documents/:id {title?, content?, folderId?, tags?, baseUpdatedAt?}
+     *
+     * `baseUpdatedAt` is the version the editor started from. When the
+     * document has been saved by anyone since, the save is refused (409)
+     * rather than written over their work - the editor keeps its text as a
+     * copy. Refused too (423) while another session holds the edit lock.
+     */
+    fastify.put('/documents/:id', {preHandler: edit, bodyLimit: DOC_BODY}, async (req, reply) => {
+        const hit = await load(req, reply, 'suggest');
+        if (!hit) return;
+        const {access} = hit;
+        const body = {...(req.body || {})};
+        // A Suggester changes the body only - and only by suggesting (checked below, against the stored body).
+        const suggester = access === 'suggester';
+        if (suggester) {
+            if (body.folderId !== undefined) return reply.code(403).send({error: 'Only the owner can move a document.'});
+            delete body.title;
+            delete body.tags;
+        }
+        // 2.13: a PDF document's body is its file - replaced through PUT .../file, never written as text.
+        if (body.content !== undefined && kindOf(hit.doc) === 'pdf') return reply.code(400).send({error: 'A PDF document has no text to edit. Upload a new file to replace it.'});
+        const touchesText = body.content !== undefined || body.title !== undefined;
+        // 2.12: an add-on's freeze (a protected wiki page) - no text or title, for anyone.
+        const frozen = touchesText ? frozenFor(hit.doc, req.user) : '';
+        if (frozen) return reply.code(403).send({error: frozen, frozen: true});
+        const session = String(req.headers['x-docs-session'] || body.session || '');
+        if (body.folderId !== undefined) {
+            if (access !== 'owner') return reply.code(403).send({error: 'Only the owner can move a document.'});
+            if (!(await usableFolder(req, body.folderId))) return reply.code(400).send({error: 'No such folder'});
+        }
+        const content = body.content !== undefined ? sanitizeDoc(body.content) : undefined;
+        let refused = null;
+        const updated = await mutateDoc(hit.doc.id, async (doc) => {
+            if (doc.trashedAt) { refused = [409, {error: 'This document is in Trash. Restore it to edit it.'}]; return null; }
+            const held = lockOf(doc.id);
+            if (held && held.session !== session && touchesText) {
+                refused = [423, {error: `${held.name} is editing this document.`, lock: publicLock(held, session)}];
+                return null;
+            }
+            if (suggester && touchesText && !held) {
+                refused = [423, {error: 'Start editing again to suggest changes.'}];
+                return null;
+            }
+            if (typeof body.baseUpdatedAt === 'string' && body.baseUpdatedAt && body.baseUpdatedAt !== doc.updatedAt && touchesText) {
+                refused = [409, {error: 'This document was saved by someone else since you opened it.', conflict: true, updatedAt: doc.updatedAt}];
+                return null;
+            }
+            let nextContent = content !== undefined ? content : doc.content;
+            if (suggester && content !== undefined && content !== doc.content) {
+                const checked = registry.checkSuggestion(doc.content, content, req.user);
+                if (checked === null) {
+                    refused = [403, {error: 'You can suggest changes to this document, not edit it. Your changes were not saved.', suggestOnly: true}];
+                    return null;
+                }
+                nextContent = sanitizeDoc(checked);
+            }
+            if (content !== undefined && nextContent !== doc.content && shouldSnapshot(doc, req.user.id)) {
+                await snapshotVersion(doc, Number(config.maxVersions) || 50, req.user.id);
+            }
+            return {
+                ...doc,
+                title: body.title !== undefined ? cleanTitle(body.title) : doc.title,
+                content: nextContent,
+                format: kindOf(doc) === 'pdf' ? 'pdf' : 'html',
+                folderId: body.folderId !== undefined ? (body.folderId || null) : doc.folderId,
+                tags: Array.isArray(body.tags) ? body.tags.map(String).slice(0, 50) : doc.tags,
+                wordCount: countWords(nextContent),
+                updatedAt: new Date().toISOString(),
+                updatedBy: req.user.id
+            };
+        });
+        if (refused) return reply.code(refused[0]).send(refused[1]);
+        if (!updated) return reply.code(404).send({error: 'Document not found'});
+        registry.emit('saved', updated, req.user);
+        return full(req, updated, access);
+    });
+
+    /**
+     * DELETE /documents/:id - to Trash. With ?permanent=1, and only from
+     * Trash, gone for good with its history.
+     */
+    fastify.delete('/documents/:id', {preHandler: drop}, async (req, reply) => {
+        const hit = await load(req, reply, 'owner');
+        if (!hit) return;
+        const {doc} = hit;
+        const frozen = frozenFor(doc, req.user);
+        if (frozen) return reply.code(403).send({error: frozen, frozen: true});
+        const permanent = req.query?.permanent === '1' || req.query?.permanent === 'true';
+        if (permanent) {
+            if (!doc.trashedAt) return reply.code(409).send({error: 'Move it to Trash first.'});
+            await removeDoc(doc.id);
+            await forgetDoc(doc.id);
+            registry.emit('deleted', doc, req.user);
+            return {ok: true, deleted: true};
+        }
+        const trashed = await mutateDoc(doc.id, (cur) => ({...cur, trashedAt: new Date().toISOString(), trashedBy: req.user.id}));
+        releaseLock(doc.id, lockOf(doc.id)?.session);
+        registry.emit('trashed', trashed, req.user);
+        return {ok: true, trashed: true};
+    });
+
+    fastify.post('/documents/:id/restore', {preHandler: drop}, async (req, reply) => {
+        const hit = await load(req, reply, 'owner');
+        if (!hit) return;
+        // 2.12: a frozen document (a protected wiki page) stays where it is.
+        const frozen = frozenFor(hit.doc, req.user);
+        if (frozen) return reply.code(403).send({error: frozen, frozen: true});
+        // A folder deleted while the document sat in Trash: back to the top.
+        const folderGone = hit.doc.folderId && !(await usableFolder(req, hit.doc.folderId));
+        const back = await mutateDoc(hit.doc.id, (cur) => ({...cur, trashedAt: null, trashedBy: null, folderId: folderGone ? null : cur.folderId}));
+        if (back) registry.emit('untrashed', back, req.user);
+        return {ok: true};
+    });
+
+    /** POST /trash/empty - everything in this user's own Trash, gone. */
+    fastify.post('/trash/empty', {preHandler: drop}, async (req) => {
+        let n = 0;
+        for (const d of await listDocs()) {
+            // Their own only - even an admin on a site-wide install empties nobody else's Trash.
+            // 2.12: a frozen one (a protected wiki page) is kept.
+            if (d.trashedAt && d.userId === req.user.id && !frozenFor(d, req.user)) {
+                await removeDoc(d.id);
+                await forgetDoc(d.id);
+                registry.emit('deleted', d, req.user);
+                n++;
+            }
+        }
+        return {ok: true, deleted: n};
+    });
+
+    /** A copy is always the copier's own: private, unshared, no public link. */
+    fastify.post('/documents/:id/duplicate', {preHandler: make}, async (req, reply) => {
+        const hit = await load(req, reply);
+        if (!hit) return;
+        const {doc} = hit;
+        const title = typeof req.body?.title === 'string' && req.body.title.trim() ? req.body.title : `${doc.title} (copy)`;
+        const pdf = kindOf(doc) === 'pdf';
+        const content = typeof req.body?.content === 'string' && !pdf ? req.body.content : doc.content;
+        const copy = newDoc({title, content, folderId: doc.userId === req.user.id ? doc.folderId : null, tags: doc.tags,
+            ...(pdf ? {format: 'pdf', file: {...doc.file, name: doc.file?.name}} : {})}, req.user);
+        // 2.13: a PDF copy is the file too - copied before the record exists, so no record ever points at nothing.
+        if (pdf && !(await copyFileBytes(doc.id, copy.id))) return reply.code(409).send({error: 'The file is missing, so it cannot be copied.'});
+        await writeDoc(copy);
+        await touchRecent(req.user.id, copy.id);
+        return reply.code(201).send(await full(req, copy, 'owner'));
+    });
+
+    fastify.post('/documents/:id/star', {preHandler: read}, async (req, reply) => {
+        const hit = await load(req, reply);
+        if (!hit) return;
+        const on = req.body?.on !== false;
+        await setStar(req.user.id, hit.doc.id, on);
+        return {ok: true, starred: on};
+    });
+
+    // ---------------------------------------------------------------- locks
+
+    /**
+     * POST /documents/:id/lock {session, force} - take or keep the edit lock.
+     * The editor calls this on open and every 30 seconds. {ok:false, lock}
+     * while somebody else holds it; `force` takes it over (the owner, or
+     * yourself in another tab).
+     */
+    fastify.post('/documents/:id/lock', {preHandler: read}, async (req, reply) => {
+        const hit = await load(req, reply);
+        if (!hit) return;
+        const {doc, access} = hit;
+        const session = String(req.body?.session || '');
+        if (!/^[A-Za-z0-9-]{8,64}$/.test(session)) return reply.code(400).send({error: 'A session id is required'});
+        const suggests = access === 'suggester' && registry.hasSuggest();
+        if ((!canEdit(access) && !suggests) || doc.trashedAt) return {ok: false, readOnly: true, lock: publicLock(lockOf(doc.id), session)};
+        // 2.12: frozen by an add-on - read only, with the reason.
+        const frozen = frozenFor(doc, req.user);
+        if (frozen) return {ok: false, readOnly: true, frozen, lock: publicLock(lockOf(doc.id), session)};
+        const held = lockOf(doc.id);
+        // Editors may take over from a Suggester (2.5) - suggesting must never keep an editor out.
+        const mayForce = access === 'owner' || held?.userId === req.user.id || (canEdit(access) && Boolean(held?.suggester));
+        if (req.body?.force && !mayForce) return reply.code(403).send({error: 'Only the owner can take over editing.'});
+        const r = acquireLock(doc.id, {userId: req.user.id, name: nameOf(req), session, force: Boolean(req.body?.force) && mayForce, suggester: !canEdit(access)});
+        // 200 either way: a lock held elsewhere is an answer, not an error (the admin's H hides error bodies).
+        if (!r.ok) return {ok: false, lock: publicLock(r.lock, session), canTakeOver: mayForce};
+        return {ok: true, lock: publicLock(r.lock, session), updatedAt: doc.updatedAt};
+    });
+
+    fastify.delete('/documents/:id/lock', {preHandler: read}, async (req) => {
+        if (validId(req.params.id)) releaseLock(req.params.id, String(req.query?.session || ''));
+        return {ok: true};
+    });
+
+    // -------------------------------------------------------------- sharing
+
+    /**
+     * PUT /documents/:id/shares {shares:[{userId, role}], notify, message}
+     * Replaces the list. The owner and editors may share; notifying emails
+     * the people newly added.
+     */
+    fastify.put('/documents/:id/shares', {preHandler: edit, config: {rateLimit: {max: 30, timeWindow: '1 minute'}}}, async (req, reply) => {
+        const hit = await load(req, reply, 'edit');
+        if (!hit) return;
+        const {doc, access} = hit;
+        if (doc.trashedAt) return reply.code(409).send({error: 'This document is in Trash.'});
+        // Only add-on access (2.11): editing, not passing it on. A restricted document takes nobody new (below).
+        if (onlyThroughExtension(doc, req.user)) return reply.code(403).send({error: outwardRefusal(doc, req.user)});
+        const {users} = await people();
+        const known = new Map(users.map(u => [u.id, u]));
+        const incoming = Array.isArray(req.body?.shares) ? req.body.shares : [];
+        const seen = new Set();
+        const shares = [];
+        for (const s of incoming.slice(0, 200)) {
+            const uid = String(s?.userId || '');
+            if (!known.has(uid) || uid === doc.userId || seen.has(uid)) continue;
+            seen.add(uid);
+            const prev = (doc.shares || []).find(x => x.userId === uid);
+            // Suggester (2.5) while an add-on offers suggestions - or kept as it was when one lapsed.
+            const role = s.role === 'editor' ? 'editor'
+                : s.role === 'suggester' && (registry.hasSuggest() || prev?.role === 'suggester') ? 'suggester' : 'viewer';
+            shares.push({userId: uid, role, addedAt: prev?.addedAt || new Date().toISOString(), addedBy: prev?.addedBy || req.user.id});
+        }
+        // An editor cannot take the owner's rights away from another editor - only the owner removes editors.
+        if (access !== 'owner') {
+            for (const p of doc.shares || []) {
+                if (p.role === 'editor' && !shares.some(s => s.userId === p.userId && s.role === 'editor')) {
+                    return reply.code(403).send({error: 'Only the owner can remove an editor.'});
+                }
+            }
+        }
+        // A restricted document (a members-only wiki page, 2.11) takes nobody new - owner included.
+        const restricted = registry.restrictionOf?.(doc) || '';
+        let added = [];
+        const updated = await mutateDoc(doc.id, (cur) => {
+            // Against the list as it is now, not as it was read above.
+            added = shares.filter(s => !(cur.shares || []).some(p => p.userId === s.userId));
+            if (restricted && added.length) return null;
+            return {...cur, shares};
+        });
+        if (restricted && added.length) return reply.code(403).send({error: `${restricted} No one new can be given access.`});
+
+        let notified = 0;
+        if (req.body?.notify && added.length) {
+            notified = await notifyShared(req, updated, added.map(s => known.get(s.userId)).filter(u => u?.email), String(req.body.message || '').slice(0, 2000));
+        }
+        return {...(await full(req, updated, access)), notified};
+    });
+
+    async function notifyShared(req, doc, recipients, message) {
+        const smtp = getConfig('site').smtp || {};
+        const transport = await mailer.createTransport(smtp);
+        // No trusted address: the path alone, with a word, rather than a link built from a Host header.
+        const base = await linkBase(req);
+        const where = `/admin/#/plugins/docs/d/${doc.id}`;
+        const link = base ? `${base}${where}` : where;
+        if (!base) req.log.warn('[docs] Site URL is not set: the share email names the path, not a link');
+        const who = nameOf(req);
+        let n = 0;
+        for (const u of recipients) {
+            const html = `<p>${escapeHtml(who)} shared a document with you: <strong>${escapeHtml(doc.title)}</strong>.</p>`
+                + (message ? `<blockquote style="border-left:3px solid #ccc;margin:0;padding:.25em 1em">${escapeHtml(message).replace(/\n/g, '<br>')}</blockquote>` : '')
+                + (base ? `<p><a href="${escapeHtml(link)}">Open it in Docs</a></p>` : `<p>Open it in Docs on the site, at <code>${escapeHtml(where)}</code>.</p>`);
+            try {
+                await mailer.sendEmail(transport, {from: smtp.fromAddress, fromName: smtp.fromName, to: u.email,
+                    subject: `${who} shared "${doc.title}" with you`, html,
+                    text: `${who} shared a document with you: ${doc.title}\n${message ? `\n${message}\n` : ''}\n${link}`});
+                n++;
+            } catch (err) {
+                req.log.warn({err}, '[docs] share notification failed');
+            }
+        }
+        return n;
+    }
+
+    /** POST /documents/:id/link - turn the public link on (idempotent). */
+    fastify.post('/documents/:id/link', {preHandler: edit}, async (req, reply) => {
+        if (config.publicLinks === false) return reply.code(403).send({error: 'Public links are switched off on this site.'});
+        const hit = await load(req, reply, 'edit');
+        if (!hit) return;
+        const {doc, access} = hit;
+        if (doc.trashedAt) return reply.code(409).send({error: 'This document is in Trash.'});
+        const refusal = outwardRefusal(doc, req.user);
+        if (refusal) return reply.code(403).send({error: refusal});
+        const updated = await mutateDoc(doc.id, (cur) => (cur.publicLink?.token ? null
+            : {...cur, publicLink: {token: newLinkToken(), createdAt: new Date().toISOString(), createdBy: req.user.id}}));
+        return {...(await full(req, updated, access)), url: `${await linkBase(req)}/docs/s/${updated.publicLink.token}`};
+    });
+
+    /** DELETE /documents/:id/link - the link stops working at once. */
+    fastify.delete('/documents/:id/link', {preHandler: edit}, async (req, reply) => {
+        const hit = await load(req, reply, 'edit');
+        if (!hit) return;
+        if (onlyThroughExtension(hit.doc, req.user)) return reply.code(403).send({error: outwardRefusal(hit.doc, req.user)});
+        const updated = await mutateDoc(hit.doc.id, (cur) => ({...cur, publicLink: null}));
+        registry.emit('linkRemoved', updated, req.user);
+        return full(req, updated, hit.access);
+    });
+
+    /**
+     * POST /documents/:id/send {to, message, mode:'inline'|'link'}
+     * Email the document - its body, or a public link to it - to up to ten
+     * addresses. The owner and editors only: sending is publishing.
+     */
+    fastify.post('/documents/:id/send', {preHandler: edit, config: {rateLimit: {max: 10, timeWindow: '10 minutes'}}}, async (req, reply) => {
+        if (config.allowSend === false) return reply.code(403).send({error: 'Sending documents by email is switched off on this site.'});
+        const hit = await load(req, reply, 'edit');
+        if (!hit) return;
+        let {doc} = hit;
+        if (doc.trashedAt) return reply.code(409).send({error: 'This document is in Trash.'});
+        const refusal = outwardRefusal(doc, req.user);
+        if (refusal) return reply.code(403).send({error: refusal});
+        const to = (Array.isArray(req.body?.to) ? req.body.to : String(req.body?.to || '').split(/[,;\s]+/))
+            .map(s => String(s).trim()).filter(Boolean);
+        if (!to.length) return reply.code(400).send({error: 'Add at least one email address.'});
+        if (to.length > MAX_RECIPIENTS) return reply.code(400).send({error: `Up to ${MAX_RECIPIENTS} addresses at a time.`});
+        const bad = to.find(a => !EMAIL_RE.test(a));
+        if (bad) return reply.code(400).send({error: `"${bad.slice(0, 80)}" is not an email address.`});
+        // A daily allowance per person, so the site's mail cannot be used as a relay.
+        if (!allowance(req.user.id, to.length)) {
+            return reply.code(429).send({error: `You can email up to ${DAILY_RECIPIENTS} addresses a day from Docs. Try again tomorrow.`});
+        }
+        const mode = req.body?.mode === 'link' ? 'link' : 'inline';
+        const message = String(req.body?.message || '').slice(0, 2000);
+        const who = nameOf(req);
+
+        let url = '';
+        if (mode === 'link') {
+            if (config.publicLinks === false) return reply.code(403).send({error: 'Public links are switched off on this site.'});
+            if (!doc.publicLink?.token) {
+                doc = await mutateDoc(doc.id, (cur) => (cur.publicLink?.token ? null
+                    : {...cur, publicLink: {token: newLinkToken(), createdAt: new Date().toISOString(), createdBy: req.user.id}}));
+            }
+            const base = await linkBase(req);
+            url = `${base}/docs/s/${doc.publicLink.token}`;
+            if (!base) req.log.warn('[docs] Site URL is not set: the sent link is a path, not an address');
+        }
+        const note = message ? `<p>${escapeHtml(message).replace(/\n/g, '<br>')}</p><hr>` : '';
+        // 2.13: a PDF document "in the email" is the file, attached.
+        const pdf = kindOf(doc) === 'pdf';
+        let attachments;
+        if (pdf && mode === 'inline') {
+            const buf = await readFileBytes(doc.id);
+            if (!buf) return reply.code(409).send({error: 'The file is missing, so it cannot be sent.'});
+            attachments = [{filename: fileName(doc.title, 'pdf'), content: buf, contentType: 'application/pdf'}];
+        }
+        const html = mode === 'link'
+            ? `${note}<p>${escapeHtml(who)} sent you a document: <strong>${escapeHtml(doc.title)}</strong>.</p><p><a href="${escapeHtml(url)}">Read it here</a></p>`
+            : pdf ? `${note}<p>${escapeHtml(who)} sent you a document: <strong>${escapeHtml(doc.title)}</strong>. It is attached as a PDF.</p>`
+                : `${note}<h1>${escapeHtml(doc.title)}</h1>${registry.publicHtml(withoutSuggestions(sanitizeDoc(doc.content)))}`;
+        const text = mode === 'link'
+            ? `${message ? message + '\n\n' : ''}${who} sent you a document: ${doc.title}\n${url}`
+            : pdf ? `${message ? message + '\n\n' : ''}${who} sent you a document: ${doc.title}. It is attached as a PDF.`
+                : `${message ? message + '\n\n---\n\n' : ''}${doc.title}\n\n${htmlToText(registry.publicHtml(withoutSuggestions(sanitizeDoc(doc.content))))}`;
+
+        const smtp = getConfig('site').smtp || {};
+        const transport = await mailer.createTransport(smtp);
+        const failed = [];
+        for (const address of to) {
+            try {
+                await mailer.sendEmail(transport, {from: smtp.fromAddress, fromName: smtp.fromName, to: address,
+                    subject: mode === 'link' ? `${who} sent you "${doc.title}"` : doc.title, html, text, ...(attachments ? {attachments} : {})});
+            } catch (err) {
+                req.log.warn({err}, '[docs] send failed');
+                failed.push(address);
+            }
+        }
+        if (failed.length === to.length) return reply.code(502).send({error: 'The email could not be sent. Check the site\'s email settings.'});
+        return {ok: true, sent: to.length - failed.length, failed, url: url || undefined};
+    });
+
+    // ------------------------------------------------------------- versions
+
+    // History is for people who can change the document: a viewer should not read what the owner removed before sharing.
+    const noHistory = (reply) => reply.code(403).send({error: 'Only people who can edit this document can see its history.'});
+
+    fastify.get('/documents/:id/versions', {preHandler: read}, async (req, reply) => {
+        const hit = await load(req, reply);
+        if (!hit) return;
+        if (!canEdit(hit.access)) return noHistory(reply);
+        const {names} = await people();
+        return (await listVersions(hit.doc.id)).map(v => ({...v, savedByName: v.savedByName || (v.savedBy ? names.get(v.savedBy) || 'Unknown' : null)}));
+    });
+
+    fastify.get('/documents/:id/versions/:num', {preHandler: read}, async (req, reply) => {
+        const hit = await load(req, reply);
+        if (!hit) return;
+        if (!canEdit(hit.access)) return noHistory(reply);
+        const v = await readVersion(hit.doc.id, req.params.num);
+        if (!v) return reply.code(404).send({error: 'Version not found'});
+        return v;
+    });
+
+    /** GET /documents/:id/versions/:num/file - the PDF an earlier version was (2.13). Editors, as history is. */
+    fastify.get('/documents/:id/versions/:num/file', {preHandler: read}, async (req, reply) => {
+        const hit = await load(req, reply);
+        if (!hit) return;
+        if (!canEdit(hit.access)) return noHistory(reply);
+        const v = await readVersion(hit.doc.id, req.params.num);
+        if (!v || v.format !== 'pdf') return reply.code(404).send({error: 'Version not found'});
+        const buf = await readVersionFile(hit.doc.id, v.num);
+        if (!buf) return reply.code(404).send({error: 'That version kept no file.'});
+        return sendPdf(reply, buf, `${hit.doc.title || 'Untitled'} (version ${v.num})`, {inline: req.query?.download !== '1'});
+    });
+
+    fastify.post('/documents/:id/versions/:num/restore', {preHandler: edit}, async (req, reply) => {
+        const hit = await load(req, reply, 'edit');
+        if (!hit) return;
+        const {doc, access} = hit;
+        if (doc.trashedAt) return reply.code(409).send({error: 'This document is in Trash.'});
+        const frozen = frozenFor(doc, req.user);
+        if (frozen) return reply.code(403).send({error: frozen, frozen: true});
+        const session = String(req.headers['x-docs-session'] || '');
+        const v = await readVersion(doc.id, req.params.num);
+        if (!v) return reply.code(404).send({error: 'Version not found'});
+        const versionBytes = kindOf(doc) === 'pdf' && v.format === 'pdf' ? await readVersionFile(doc.id, v.num) : null;
+        let refused = null;
+        const restored = await mutateDoc(doc.id, async (cur) => {
+            const held = lockOf(cur.id);
+            if (held && held.session !== session) { refused = {error: `${held.name} is editing this document.`}; return null; }
+            // Always kept: a restore must itself be undoable.
+            await snapshotVersion(cur, Number(config.maxVersions) || 50, req.user.id);
+            // 2.13: a PDF document's version is a file - put back as the file, with the facts it had. Its bytes are read
+            // BEFORE the snapshot above trims history: restoring the oldest version at the cap used to delete that very file.
+            if (kindOf(cur) === 'pdf') {
+                if (v.format !== 'pdf' || !versionBytes) { refused = {error: 'That version kept no file to restore.', status: 409}; return null; }
+                await writeFileBytes(cur.id, versionBytes);
+                return {...cur, content: sanitizeDoc(v.content || ''), file: v.file || cur.file, wordCount: countWords(v.content || ''), updatedAt: new Date().toISOString(), updatedBy: req.user.id};
+            }
+            // A version from before 2.0 may be Markdown.
+            const content = upgradeBody(v.content);
+            return {...cur, content, wordCount: countWords(content), updatedAt: new Date().toISOString(), updatedBy: req.user.id};
+        });
+        if (refused) return reply.code(refused.status || 423).send({error: refused.error});
+        registry.emit('restored', restored, req.user, v.num);
+        return full(req, restored, access);
+    });
+
+    // -------------------------------------------------------------- folders
+
+    fastify.get('/folders', {preHandler: read}, async (req) => {
+        const folders = await foldersStore.readArray();
+        return config.scope === 'user' ? folders.filter(f => f.userId === req.user.id) : folders;
+    });
+
+    fastify.post('/folders', {preHandler: make}, async (req, reply) => {
+        const {name, parentId = null} = req.body || {};
+        if (!name || !String(name).trim()) return reply.code(400).send({error: 'Name is required'});
+        if (parentId && !(await usableFolder(req, parentId))) return reply.code(400).send({error: 'No such folder'});
+        const folder = {id: randomUUID(), name: String(name).trim().slice(0, 120), parentId: parentId || null, userId: req.user.id, createdAt: new Date().toISOString()};
+        await foldersStore.appendItem(folder);
+        return reply.code(201).send(folder);
+    });
+
+    const mayChangeFolder = (req, f) => f.userId === req.user.id || (config.scope === 'all' && isAdmin(req));
+
+    fastify.put('/folders/:id', {preHandler: edit}, async (req, reply) => {
+        const folder = (await foldersStore.readArray()).find(f => f.id === req.params.id);
+        if (!folder || !mayChangeFolder(req, folder)) return reply.code(404).send({error: 'Folder not found'});
+        const {name} = req.body || {};
+        if (!name || !String(name).trim()) return reply.code(400).send({error: 'Name is required'});
+        return foldersStore.updateItem(req.params.id, {name: String(name).trim().slice(0, 120)});
+    });
+
+    fastify.delete('/folders/:id', {preHandler: drop}, async (req, reply) => {
+        const folders = await foldersStore.readArray();
+        const folder = folders.find(f => f.id === req.params.id);
+        if (!folder || !mayChangeFolder(req, folder)) return reply.code(404).send({error: 'Folder not found'});
+        // Its documents and subfolders move up a level; nothing is deleted with it.
+        for (const d of await listDocs()) {
+            if (d.folderId === folder.id) await mutateDoc(d.id, (cur) => (cur.folderId === folder.id ? {...cur, folderId: folder.parentId || null} : null));
+        }
+        for (const f of folders.filter(x => x.parentId === folder.id)) {
+            await foldersStore.updateItem(f.id, {parentId: folder.parentId || null});
+        }
+        await foldersStore.deleteItem(folder.id);
+        return {ok: true};
+    });
+
+    // ------------------------------------------------------------ templates
+
+    fastify.get('/templates', {preHandler: read}, async (req) => {
+        const templates = await templatesStore.readArray();
+        const own = config.scope === 'user' ? templates.filter(t => t.userId === req.user.id) : templates;
+        // Add-ons' ready-made templates (2.6), after the user's own: read only, sanitised like any body.
+        const builtIn = registry.builtInTemplates().map(t => ({
+            id: `x-${t.owner}-${t.id}`, name: String(t.name || 'Template').slice(0, 120), description: String(t.description || '').slice(0, 300),
+            category: String(t.category || '').slice(0, 60), content: sanitizeDoc(t.content || ''), builtIn: true, source: t.label, userId: null, format: 'html'
+        }));
+        return [...own, ...builtIn];
+    });
+
+    fastify.post('/templates', {preHandler: make}, async (req, reply) => {
+        const {name, content = ''} = req.body || {};
+        if (!name || !String(name).trim()) return reply.code(400).send({error: 'Name is required'});
+        const template = {id: randomUUID(), name: String(name).trim().slice(0, 120), content: sanitizeDoc(content), userId: req.user.id, createdAt: new Date().toISOString()};
+        await templatesStore.appendItem(template);
+        return reply.code(201).send(template);
+    });
+
+    fastify.delete('/templates/:id', {preHandler: drop}, async (req, reply) => {
+        const template = (await templatesStore.readArray()).find(t => t.id === req.params.id);
+        if (!template || !(template.userId === req.user.id || (config.scope === 'all' && isAdmin(req)))) {
+            return reply.code(404).send({error: 'Template not found'});
+        }
+        await templatesStore.deleteItem(req.params.id);
+        return {ok: true};
+    });
+}