@vibelord/lanes 1.2.0 → 1.3.0

package/payload/lanes/libexec/uploads.py

@@ -0,0 +1,538 @@
+"""lanes uploads — one way in for a file a person uploads (docs cockpit W10 task W5, LNS-106).
+
+Both upload paths land the file where the agents have always found it AND record it in the docs store:
+  * the SSH droplet `lanes upload` (bin/lanes cmd_upload: a tar stream on stdin from the client's `lanes-upload`, the
+    sidebar's upload strip through the upload helper, the watch folder, the macOS droplet) — receive_tar, source `ssh`;
+  * the Docs page's `POST /up` (libexec/docsd.py: a multipart form from the phone or laptop) — receive, source `web`.
+
+Landing, as cmd_upload always did it: `<folder>/uploads/<name>` in the workspace's container, reached through the
+container's home volume (lanes_lib.host_path), where `<folder>` is the workspace's first lane folder, else its working
+directory (landing). An existing name is never overwritten: the next is `<stem>-1<suffix>`, `-2` … (link_free, the
+rule docs_store names documents by). `uploads/` is created on first use (0755) and, when the folder is a git
+repository (`.git` a directory), `.git/info/exclude` gains the `uploads/` line unless a line already names it, so an
+upload is never committed (ensure_excluded). A file appears under its name only once it is complete (written as
+`.incoming-…`, then linked or renamed into place).
+
+Safety (DEF-1890, DEF-1891). The folder and everything in it are the container's to change, and the host writes there
+as the account the agents run as (bin/lanes uid_split: the same uid). So every directory is opened component by
+component without following a link (lanes_lib.open_real_dir: an absolute link would resolve against the HOST's root),
+every file is created O_EXCL|O_NOFOLLOW, a tar stream is unpacked here member by member (unpack; never
+tarfile.extractall, which follows a link an agent plants while it runs), and no git process runs in the repository:
+`git check-ignore` runs the repository's `core.fsmonitor`, a command the container chose, on the host.
+
+Recording. Each file's bytes pass through a Tee: every chunk read from the upload is written to the landing file and
+handed to docs_store.intake in the same pass, so the store's sha256 receipt is of exactly the bytes that arrived — never
+of a file an agent could rewrite before it was read. The store document is a COPY, never a hard link to the landed
+file: a link shares one inode with a file the container may write, and an edit there would change the receipt-bound
+bytes under an unchanged receipt (test_uploads.Ownership measures that, and that a link cannot even cross to another
+filesystem). Store facts (record): `kind` by extension (kind_for: md, html, svg, else file), `for` and `by` the
+uploader's login, at most UPLOAD_LIMIT bytes a file — a larger file lands without a store document (intake logs
+`too-large`). An SSH upload from a device that no member record owns lands as before, with a docs.log
+`upload - - <lane> <bytes> <sha256> no-owner` line and no store document. LANES_DOCS_AGE_RECIPIENT encrypts the store
+copy only (docs_store), never the landed file.
+"""
+import hashlib
+import os
+import secrets
+import stat
+import tarfile
+from pathlib import PurePosixPath
+
+import lanes_lib as L
+import docs_store as D
+
+UPLOAD_LIMIT = 32 * 1024 * 1024      # bytes of ONE file the store keeps from an upload (docsd's POST /up body cap)
+MAX_RECORDS = 64                     # store documents one SSH upload makes at most (docsd's MAX_PARTS for a form)
+MAX_EXCLUDE = 64 * 1024              # a .git/info/exclude larger than this is not read (nor appended to)
+MAX_LINKS = 4096                     # names link_free tries before it gives up
+CHUNK = 64 * 1024
+UPLOADS = 'uploads'
+FILE_MODE, DIR_MODE = 0o644, 0o755   # what a web upload and a new uploads/ get, whatever the caller's umask
+EXCLUDE_BLOCK = b'\n# lanes upload: local intake folder, never committed\nuploads/\n'   # cmd_upload's, byte for byte
+EXCLUDES = frozenset(('uploads', 'uploads/', '/uploads', '/uploads/', 'uploads/*', '/uploads/*', 'uploads/**',
+                      '/uploads/**'))
+KINDS = {'.md': 'md', '.markdown': 'md', '.html': 'html', '.htm': 'html', '.svg': 'svg'}
+_CLOEXEC = getattr(os, 'O_CLOEXEC', 0)
+_DIR = os.O_RDONLY | os.O_DIRECTORY | os.O_NOFOLLOW | _CLOEXEC
+_NEW = os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW | _CLOEXEC
+
+
+class UploadError(L.LanesError):
+    """A file that could not be stored (both-or-neither, `receive`): `word` is the refusal (busy, too-large,
+    encrypt-failed, invalid, no-owner)."""
+
+    def __init__(self, word):
+        super().__init__(f'the upload could not be stored ({word})')
+        self.word = word
+
+
+def kind_for(name):
+    """The store kind of an uploaded file: md, html or svg by its extension (case-insensitive), else file."""
+    return KINDS.get(PurePosixPath(name or '').suffix.lower(), 'file')
+
+
+# ----------------------------------------------------------------------------------------------------- the landing
+
+def landing(registry, workspace):
+    """(folder, home, parts) of `workspace`'s uploads: the container folder they land under (`<folder>/uploads/`) —
+    the first lane folder, else the workspace's working directory —, the container's home volume on the host, and the
+    folder's components below it. Raises LanesError exactly as lanes_lib.host_path does (an unsafe path, one outside the
+    home volume, a container whose home volume is unknown: not running at the last `lanes sync`)."""
+    folder = next((lane.get('folder') for lane in workspace.get('lanes') or [] if lane.get('folder')), None) \
+        or workspace.get('cwd') or ''
+    info = (registry.get('containers') or {}).get(workspace.get('container')) or {}
+    L.host_path(info, folder)
+    rest = folder[len(L.CONTAINER_HOME) + 1:]
+    return folder, info['home'], [part for part in rest.split('/') if part]
+
+
+def _mkdir(dir_fd, name, mode):
+    """mkdir `name` in dir_fd -> True when it made it (an existing entry is left as it is)."""
+    try:
+        os.mkdir(name, mode, dir_fd=dir_fd)
+        return True
+    except FileExistsError:
+        return False
+
+
+def open_uploads(home, parts):
+    """fd of <home>/<parts…>/uploads, made (0755) when absent; every component a real directory — a symbolic link
+    anywhere is refused, never followed —, and the repository's exclude file kept naming it (ensure_excluded). The
+    caller closes it. Raises LanesError."""
+    try:
+        root = L.open_real_dir(home, parts)
+    except (OSError, L.LanesError):
+        raise L.LanesError('the workspace folder cannot be opened without following a symbolic link') from None
+    try:
+        try:
+            created = _mkdir(root, UPLOADS, 0o700)
+        except OSError as error:
+            raise L.LanesError(f'uploads/ cannot be made in the workspace folder: {error.strerror or error}') from None
+        try:
+            fd = os.open(UPLOADS, _DIR, dir_fd=root)
+        except OSError:
+            raise L.LanesError('uploads/ in the workspace folder is not a directory (a symbolic link is refused)') \
+                from None
+        if created:
+            os.fchmod(fd, DIR_MODE)
+        try:
+            ensure_excluded(root)
+        except BaseException:
+            os.close(fd)
+            raise
+        return fd
+    finally:
+        os.close(root)
+
+
+def _ignores_uploads(data):
+    return any(line.strip() in EXCLUDES for line in data.decode('utf-8', 'replace').splitlines())
+
+
+def ensure_excluded(root):
+    """Keep the repository folder `root` (an fd) from committing uploads/ -> True when it appended. Only when `.git` is a
+    real directory (absent, a linked worktree's `.git` file or a link: nothing, as before): `.git/info/exclude` (made
+    when absent) gains EXCLUDE_BLOCK unless a line of it already names uploads/ (EXCLUDES). No git process runs here
+    (DEF-1890). Raises LanesError when the exclude file is no regular file or cannot be written: an upload that could be
+    committed is not made."""
+    try:
+        git = os.open('.git', _DIR, dir_fd=root)
+    except OSError:
+        return False
+    try:
+        try:
+            _mkdir(git, 'info', 0o755)
+            info = os.open('info', _DIR, dir_fd=git)
+        except OSError:
+            raise L.LanesError('.git/info in the workspace folder is not a directory') from None
+        try:
+            try:
+                fd = os.open('exclude', os.O_RDWR | os.O_APPEND | os.O_CREAT | os.O_NOFOLLOW | os.O_NONBLOCK | _CLOEXEC,
+                             0o644, dir_fd=info)
+            except OSError:
+                raise L.LanesError('.git/info/exclude cannot be opened without following a link') from None
+            try:
+                info_stat = os.fstat(fd)
+                if not stat.S_ISREG(info_stat.st_mode) or info_stat.st_size > MAX_EXCLUDE:
+                    raise L.LanesError('.git/info/exclude is not a plain file of at most 64 KiB')
+                data, size = [], 0
+                while size <= MAX_EXCLUDE:
+                    chunk = os.read(fd, CHUNK)
+                    if not chunk:
+                        break
+                    data.append(chunk)
+                    size += len(chunk)
+                if _ignores_uploads(b''.join(data)):
+                    return False
+                os.write(fd, EXCLUDE_BLOCK)
+                return True
+            except OSError as error:
+                raise L.LanesError(f'.git/info/exclude cannot be written: {error.strerror or error}') from None
+            finally:
+                os.close(fd)
+        finally:
+            os.close(info)
+    finally:
+        os.close(git)
+
+
+def _next(name, n):
+    path = PurePosixPath(name)
+    return f'{path.stem}-{n}{path.suffix}'
+
+
+def _exists(dir_fd, name):
+    try:
+        os.stat(name, dir_fd=dir_fd, follow_symlinks=False)
+        return True
+    except FileNotFoundError:
+        return False
+
+
+def free_name(dir_fd, name):
+    """The first name of `name`'s collision sequence (`name`, `<stem>-1<suffix>`, `-2` …) nothing in dir_fd has."""
+    final, n = name, 1
+    while _exists(dir_fd, final):
+        final, n = _next(name, n), n + 1
+        if n > MAX_LINKS:
+            raise L.LanesError('no free name in uploads/')
+    return final
+
+
+def link_free(dir_fd, source, name, source_dir=None):
+    """Hard-link `source` (an entry of source_dir, default dir_fd; never followed when it is a link) to the first free
+    name of `name`'s collision sequence in dir_fd -> the name used. link(2) never replaces an existing name, so a name
+    taken in the meantime moves on to the next one: an earlier upload is never overwritten."""
+    final, n = name, 1
+    while True:
+        try:
+            os.link(source, final, src_dir_fd=dir_fd if source_dir is None else source_dir, dst_dir_fd=dir_fd,
+                    follow_symlinks=False)
+            return final
+        except FileExistsError:
+            final, n = _next(name, n), n + 1
+            if n > MAX_LINKS:
+                raise L.LanesError('no free name in uploads/') from None
+
+
+def rename_free(source_dir, source, dir_fd, name):
+    """Rename the directory `source` (in source_dir) to the first free name of `name`'s sequence in dir_fd -> the name
+    used. A name some entry has is skipped (rename would replace an empty directory)."""
+    final, n = name, 1
+    while True:
+        if not _exists(dir_fd, final):
+            try:
+                os.rename(source, final, src_dir_fd=source_dir, dst_dir_fd=dir_fd)
+                return final
+            except OSError as error:
+                if error.errno not in (17, 39):          # EEXIST, ENOTEMPTY: taken meanwhile
+                    raise
+        final, n = _next(name, n), n + 1
+        if n > MAX_LINKS:
+            raise L.LanesError('no free name in uploads/')
+
+
+def remove_tree(dir_fd, name):
+    """Remove the entry `name` of dir_fd and, for a directory, everything in it — never through a link."""
+    try:
+        info = os.stat(name, dir_fd=dir_fd, follow_symlinks=False)
+    except FileNotFoundError:
+        return
+    if not stat.S_ISDIR(info.st_mode):
+        os.unlink(name, dir_fd=dir_fd)
+        return
+    fd = os.open(name, _DIR, dir_fd=dir_fd)
+    try:
+        for entry in list(os.scandir(fd)):
+            remove_tree(fd, entry.name)
+    finally:
+        os.close(fd)
+    os.rmdir(name, dir_fd=dir_fd)
+
+
+# ------------------------------------------------------------------------------------------------------- recording
+
+class Tee:
+    """A reader over `source` that writes every chunk it hands out to the fd `out` and hashes it on the way."""
+
+    def __init__(self, source, out):
+        self.source, self.out, self.size, self.digest = source, out, 0, hashlib.sha256()
+
+    def read(self, size=-1):
+        chunk = self.source.read(size if size and size > 0 else CHUNK)
+        if chunk:
+            view = memoryview(chunk)
+            while view:
+                view = view[os.write(self.out, view):]
+            self.digest.update(chunk)
+            self.size += len(chunk)
+        return chunk
+
+    def drain(self):
+        """Read the rest (written to `out` too) -> (bytes, sha256 hex) of everything that passed."""
+        while self.read(CHUNK):
+            pass
+        return self.size, self.digest.hexdigest()
+
+
+def record(tee, *, login, ws, lane, name, source):
+    """Hand the bytes `tee` yields to docs_store.intake as a document of `login` in `ws`/`lane` named `name` — kind
+    by extension, for and by the login, at most UPLOAD_LIMIT bytes — then drain `tee`, so the landed file is complete
+    whatever the store said -> (meta or None, problem word or None): too-large, busy, encrypt-failed, invalid (intake
+    logged each), no-owner (no login: a docs.log `upload` line with the bytes and sha256 only), no-lane."""
+    meta, problem = None, None
+    if login is None or lane is None:
+        problem = 'no-owner' if login is None else 'no-lane'
+    else:
+        try:
+            meta = D.intake(login, ws, lane, name, tee, limit=UPLOAD_LIMIT, source=source, kind=kind_for(name),
+                            for_logins=[login], by=login)
+        except D.TooLarge:
+            problem = 'too-large'
+        except D.Busy:
+            problem = 'busy'
+        except D.EncryptError:
+            problem = 'encrypt-failed'
+        except D.DocsError:
+            problem = 'invalid'
+    size, sha256 = tee.drain()
+    if meta is None and problem in ('no-owner', 'no-lane'):
+        D.audit('upload', login, None, lane, size, sha256, problem)
+    return meta, problem
+
+
+def receive(uploads, name, reader, *, login, ws, lane, source):
+    """One file into the uploads/ directory `uploads` (an fd) AND the store, both or neither (POST /up) -> (meta, the
+    name it landed under). Written as `.incoming-<hex>` while the store takes the same bytes, then linked to `name`'s
+    first free name. Raises UploadError(word) when the store refused it (nothing lands), OSError when it could not land
+    (the store document is removed again)."""
+    temporary = f'.incoming-{secrets.token_hex(8)}'
+    fd = os.open(temporary, _NEW, 0o600, dir_fd=uploads)
+    try:
+        meta, problem = record(Tee(reader, fd), login=login, ws=ws, lane=lane, name=name, source=source)
+        if meta is None:
+            raise UploadError(problem)
+        try:
+            os.fchmod(fd, FILE_MODE)
+            final = link_free(uploads, temporary, name)
+        except BaseException:
+            try:
+                D.remove(meta['id'], login)
+            except D.DocsError:
+                pass
+            raise
+        return meta, final
+    finally:
+        os.close(fd)
+        try:
+            os.unlink(temporary, dir_fd=uploads)
+        except OSError:
+            pass
+
+
+# --------------------------------------------------------------------------------------------- the SSH tar stream
+
+def member_parts(name):
+    """The path components of a tar member name below the upload: leading `/` and `.` components dropped (as tar's
+    data filter strips a leading slash), None for a name with `..` or a NUL (refused)."""
+    if not isinstance(name, str) or '\0' in name:
+        return None
+    parts = [part for part in name.split('/') if part not in ('', '.')]
+    return None if '..' in parts else parts
+
+
+def _file_mode(mode):
+    return (mode & 0o755) | 0o600      # tar's data filter: no setuid/setgid/sticky, no group/other write, owner rw
+
+
+def _dir_mode(mode):
+    return (mode & 0o755) | 0o700
+
+
+def _dirs(base, parts, create=True):
+    """fd of base/<parts…>, each a real directory (made 0755 when absent and `create`); never through a link."""
+    fd = os.dup(base)
+    try:
+        for part in parts:
+            if create and _mkdir(fd, part, 0o700):
+                made = os.open(part, _DIR, dir_fd=fd)
+                os.fchmod(made, DIR_MODE)
+                os.close(fd)
+                fd = made
+                continue
+            child = os.open(part, _DIR, dir_fd=fd)
+            os.close(fd)
+            fd = child
+    except BaseException:
+        os.close(fd)
+        raise
+    return fd
+
+
+def _create(parent, name, make):
+    """make(parent, name) for a new entry; an entry of that name an earlier member made is replaced (a tar stream may
+    carry a path twice, and extraction keeps the last)."""
+    try:
+        return make(parent, name)
+    except FileExistsError:
+        os.unlink(name, dir_fd=parent)
+        return make(parent, name)
+
+
+def _link_inside(parts, target):
+    """Whether a symbolic link at `parts` pointing at `target` stays inside the upload (relative, never above it)."""
+    if not target or target.startswith('/') or '\0' in target:
+        return False
+    depth = len(parts) - 1
+    for part in target.split('/'):
+        if part == '..':
+            depth -= 1
+            if depth < 0:
+                return False
+        elif part not in ('', '.'):
+            depth += 1
+    return True
+
+
+def unpack(stream, staging, on_file):
+    """Unpack the tar stream `stream` into the directory `staging` (an fd) member by member -> the top-level names in
+    the order they came. Directories and regular files are made without following a link; a regular file's bytes go
+    through a Tee into it, and on_file(parts, tee) is called while they stream (it must drain the tee); a symbolic
+    link is kept only when it stays inside the upload and a hard link only to a file of it; a device, FIFO or any other
+    member is refused (LanesError), as tar's data filter refuses it. An empty stream is no member."""
+    tops = []
+    try:
+        archive = tarfile.open(fileobj=stream, mode='r|')
+    except tarfile.ReadError as error:
+        if 'empty' in str(error):
+            return tops
+        raise L.LanesError('the upload is not a tar stream') from None
+    with archive:
+        try:
+            for member in archive:
+                parts = member_parts(member.name)
+                if parts is None:
+                    raise L.LanesError('refused: an archive member climbs out of the upload')
+                if not parts:
+                    continue
+                if parts[0] not in tops:
+                    tops.append(parts[0])
+                if member.isdir():
+                    fd = _dirs(staging, parts)
+                    os.fchmod(fd, _dir_mode(member.mode))
+                    os.close(fd)
+                    continue
+                parent = _dirs(staging, parts[:-1])
+                try:
+                    if member.isreg():
+                        fd = _create(parent, parts[-1], lambda p, n: os.open(n, _NEW, 0o600, dir_fd=p))
+                        try:
+                            on_file(parts, Tee(archive.extractfile(member), fd))
+                            os.fchmod(fd, _file_mode(member.mode))
+                            os.utime(fd, (member.mtime, member.mtime))
+                        finally:
+                            os.close(fd)
+                    elif member.issym():
+                        if not _link_inside(parts, member.linkname):
+                            raise L.LanesError('refused: an archive link points outside the upload')
+                        _create(parent, parts[-1], lambda p, n: os.symlink(member.linkname, n, dir_fd=p))
+                    elif member.islnk():
+                        target = member_parts(member.linkname)
+                        if not target:
+                            raise L.LanesError('refused: an archive hard link points outside the upload')
+                        source = _dirs(staging, target[:-1], create=False)
+                        try:
+                            _create(parent, parts[-1], lambda p, n: os.link(target[-1], n, src_dir_fd=source,
+                                                                            dst_dir_fd=p, follow_symlinks=False))
+                        finally:
+                            os.close(source)
+                    else:
+                        raise L.LanesError('refused: the archive holds a device, a FIFO or another special file')
+                finally:
+                    os.close(parent)
+        except (tarfile.TarError, EOFError):
+            raise L.LanesError('the upload is not a whole tar stream') from None
+        except OSError as error:
+            raise L.LanesError(f'the upload could not be unpacked: {error.strerror or error}') from None
+    return tops
+
+
+def place(staging, name, uploads):
+    """Move the top-level entry `name` of `staging` into `uploads` under its first free name -> that name: a file (or
+    a link) by link(2) — the same inode, no copy —, a directory by rename. Both directories are on the volume."""
+    info = os.stat(name, dir_fd=staging, follow_symlinks=False)
+    if stat.S_ISDIR(info.st_mode):
+        return rename_free(staging, name, uploads, name)
+    final = link_free(uploads, name, name, source_dir=staging)
+    os.unlink(name, dir_fd=staging)
+    return final
+
+
+def upload_lane(workspace, device=None):
+    """The lane an SSH upload to `workspace` is recorded under: the lane `device`'s first viewport shows on this board
+    (views/<device>/<ws>.main.target, the lane `--paste` types into), else the board's default lane (defaults/<ws>),
+    else its first lane; None for a board without lanes."""
+    ids = [lane['id'] for lane in workspace.get('lanes') or [] if isinstance(lane, dict)
+           and isinstance(lane.get('id'), str)]
+    paths = [L.STATE / 'views' / device / f"{workspace['id']}.main.target"] if device else []
+    for path in paths + [L.STATE / 'defaults' / workspace['id']]:
+        try:
+            first = path.read_text().split('\n')[0].strip()
+        except (OSError, UnicodeDecodeError):
+            continue
+        if first in ids:
+            return first
+    return ids[0] if ids else None
+
+
+def receive_tar(stream, uploads, *, login, ws, lane, say=None):
+    """An SSH upload: the tar stream `stream` into the uploads/ directory `uploads` (an fd) and the store -> the names
+    that landed in uploads/, sorted (cmd_upload's order). Unpacked into a fresh `.incoming-<pid>-<hex>` there, each
+    regular file recorded while it streams — a top-level file under the name it is about to land as, a file of a
+    folder under its own name; at most MAX_RECORDS documents, the rest land with a docs.log `too-many` line —, then
+    every top-level entry placed. A stream that fails part-way lands nothing, as before, and the documents it had
+    already recorded are removed again. say(text) hears one line per file (its receipt, or why the store has none)."""
+    staging = f'.incoming-{os.getpid()}-{secrets.token_hex(4)}'
+    try:
+        os.mkdir(staging, 0o700, dir_fd=uploads)
+    except OSError as error:
+        raise L.LanesError(f'uploads/ cannot be written: {error.strerror or error}') from None
+    landed, recorded = [], []
+    try:
+        staging_fd = os.open(staging, _DIR, dir_fd=uploads)
+        try:
+            def on_file(parts, tee):
+                name = free_name(uploads, parts[0]) if len(parts) == 1 else parts[-1]
+                if len(recorded) >= MAX_RECORDS:
+                    size, sha256 = tee.drain()
+                    D.audit('upload', login, None, lane, size, sha256, 'too-many')
+                    problem, meta = 'too-many', None
+                else:
+                    meta, problem = record(tee, login=login, ws=ws, lane=lane, name=name, source='ssh')
+                    if meta is not None:
+                        recorded.append(meta)
+                if say:
+                    say(f'# docs: {meta["name"]} {meta["bytes"]} B sha256 {meta["sha256"]} {meta["id"]}' if meta
+                        else f'# docs: {name}: no receipt ({problem})')
+            try:
+                tops = unpack(stream, staging_fd, on_file)
+            except BaseException:
+                for meta in recorded:
+                    try:
+                        D.remove(meta['id'], login)
+                    except D.DocsError:
+                        pass
+                raise
+            for name in sorted(tops):
+                try:
+                    landed.append(place(staging_fd, name, uploads))
+                except OSError as error:
+                    raise L.LanesError(f'{name} could not be moved into uploads/: {error.strerror or error}') from None
+        finally:
+            os.close(staging_fd)
+    finally:
+        try:
+            remove_tree(uploads, staging)
+        except OSError:
+            pass
+    return landed

package/payload/lanes/systemd/lanes-docsd.service

@@ -0,0 +1,29 @@
+[Unit]
+Description=lanes docs service (login-bound docs, artifacts and uploads) on loopback 127.0.0.1:8185
+
+# Enabled and restarted by every server install (install/host-install.sh). lanes-mobile's Caddy forwards
+# https://<host>:8443/lanes-docs/* here (web/Caddyfile `handle_path /lanes-docs/*`). It reads and writes the docs store
+# ~/.local/state/lanes/docs/ and docs.log and reads members/, enrol-mode and registry.json; its publish pick-up (W4)
+# reads each workspace container's ~/.lz/state/publish/ through /proc/<pid>/root, as lanes-statusd does, and writes the
+# receipts back there; and (W5) it lands uploads in a workspace's uploads/ through the container's home volume. Hence
+# it has no ProtectHome.
+# It answers nothing until the operator pins the Serve header check (`lanes enrol mode request`, read on every
+# request). Optional settings (LANES_DOCS_DOMAINS, LANES_DOCS_PORT, and the default-off encryption at rest
+# LANES_DOCS_AGE_RECIPIENT / LANES_DOCS_AGE_IDENTITY, which `lanes upload` reads from the same drop-in) go in a drop-in,
+# `systemctl --user edit lanes-docsd.service`, which a re-install keeps (RUNBOOK "Docs service").
+# Memory: docsd holds at most two 32 MiB buffers at once (UPLOAD_SLOTS, shared by uploads and decryptions, one per
+# login), two Markdown renders and an 8 MiB render cache, and its publish pick-up reads at most 4,096 directory entries
+# of a container per cycle, so what a container plants or a member sends stays under MemoryMax (RUNBOOK "Docs service",
+# Limits; the composed peak is not measured: DEF-1917).
+[Service]
+ExecStart=/usr/bin/python3 -S -E "@REPO@/libexec/docsd.py"
+Restart=on-failure
+RestartSec=10
+NoNewPrivileges=true
+UMask=0077
+MemoryHigh=128M
+MemoryMax=192M
+Slice=lanes.slice
+
+[Install]
+WantedBy=default.target

package/payload/lanes/web/Caddyfile

@@ -8,12 +8,35 @@
 http://:8083 {
 	bind 127.0.0.1
 	root * "{$LANES_REPO}/web"
-	header {
+	# lanes-docsd answers /lanes-docs/* with its own security headers per route (an agent's HTML or SVG artifact is a
+	# sandboxed top-level document), so the site-wide set below skips that prefix: docsd's are the only ones it sends.
+	@notdocs not path /lanes-docs/*
+	header @notdocs {
 		X-Content-Type-Options nosniff
 		X-Frame-Options DENY
 		Referrer-Policy strict-origin-when-cross-origin
 		Content-Security-Policy "default-src 'self'; style-src 'self' 'unsafe-inline' https://fonts.googleapis.com; font-src 'self' https://fonts.gstatic.com; connect-src 'self' ws: wss:; img-src 'self' data:"
 	}
+	# lanes-docsd.service (libexec/docsd.py): the docs cockpit, login-bound pages, downloads, artifacts and uploads.
+	# handle_path strips /lanes-docs. It stays the FIRST handle of the site: Caddy never reaches a block declared after
+	# a handle with a named matcher (the Zellij routes below).
+	handle_path /lanes-docs/* {
+		reverse_proxy 127.0.0.1:8185 {
+			# As on /enrol/*: keep the X-Forwarded-For Tailscale Serve sets (the client's tailnet address): docsd
+			# answers only a request that carries one, and only with Serve's identity headers. Caddy >= 2.5.
+			trusted_proxies 127.0.0.0/8
+		}
+	}
+	# The docs page's pinned Mermaid (plan W10 W6, LNS-107): install/enable-docs.sh puts holders.lock's pin into
+	# $LANES_SHARE/vendor (services.py sets LANES_SHARE in lanes-mobile.service). Immutable: a page names a VERSIONED
+	# file, so a new pin is a new URL (DEF-1870). Caddy sorts a single-path route ahead of /lanes-assets/* only past
+	# routes that also have a single path (Caddy issue #5037; DEF-1872): keep this block with the single-path routes
+	# above the named-matcher ones (/lanes-docs/* does not overlap it, so their order between themselves is free).
+	handle_path /lanes-assets/vendor/* {
+		root * "{$LANES_SHARE}/vendor"
+		header Cache-Control "public, max-age=31536000, immutable"
+		file_server
+	}
 	handle_path /lanes-assets/* {
 		header Cache-Control "no-cache"
 		file_server