@vibelord/lanes 1.2.0 → 1.3.0

package/payload/lanes/libexec/docs_store.py

@@ -0,0 +1,995 @@
+"""lanes docs store — documents an agent publishes from a lane or a person uploads, kept per login with a sha256
+receipt (W10 docs cockpit W1, LNS-102).
+
+Layout, all under L.STATE (directories 0700, files 0600):
+
+    docs/<stem(login)>/<ws>/<lane>/<id>/<name>          the document, byte for byte as it arrived
+    docs/<stem(login)>/<ws>/<lane>/<id>/meta.json       {v, id, ws, lane, kind, title, name, mime, bytes, sha256,
+                                                         at, by, for, source}
+    docs/<stem(login)>/<ws>/<lane>/<id>/receipt.json    {v, id, sha256, bytes, url, at}
+    docs/counts.json                                    {<lane id>: {n, at}} — every login's documents per lane
+    docs/.lock                                          the store lock (flock) every change holds
+    docs.log                                            append-only: `<at> <login> <event> <id> <lane> <bytes> <sha256>
+                                                        <outcome>` — never content, a title or a name; at
+                                                        LOG_ROTATE_BYTES (8 MiB) it becomes docs.log.1, one generation
+
+  * `stem(login)` is users.stem (the login percent-quoted with nothing safe, as the profile store names its files),
+    refused here when it is no directory name of its own: `.`, `..` or any other stem that starts with a dot (a
+    login may be `..`, and quote() keeps dots), or `counts.json`. `ws` is users.check_workspace's id and `lane`
+    users.check_lane's lane id (at most 255 characters here: one directory name). Every component is validated
+    before anything is written, and an existing directory on the way that is a symbolic link is refused.
+  * An id is `new_id()`: base36 epoch seconds (padded to 6) and 6 random base32 characters, ID_RE; ids are minted
+    with an exclusive mkdir, so an id dir is never reused. `name` is clean_name(original): the basename (after the
+    last `/` or `\\`), only `[A-Za-z0-9._-]`, dot runs collapsed, a leading dot behind `file` (`.bashrc` ->
+    `file.bashrc`), no trailing dot, at most MAX_NAME characters (the extension kept), never empty (`file`); one
+    already used by a document of the same login, workspace and lane, or `meta.json` / `receipt.json`, gains
+    `-1`, `-2` … before its suffix, exactly as bin/lanes cmd_upload names a file in `uploads/`.
+  * `intake()` streams the reader into a temporary file in a new id dir, at most `limit` bytes (one byte more is a
+    TooLarge refusal; it never reads past it), hashing as it goes on the host — a claimed hash is never taken. Under
+    the store lock (LOCK_S, else Busy) it names the file, renames it into place, writes receipt.json and then
+    meta.json (the document exists for readers once meta.json does) and the lane's entry of counts.json. Any
+    failure removes the id dir: nothing is left behind. `mime` is Python's built-in table for the name (never the
+    host's mime.types, so it does not differ between machines), `application/octet-stream` when it has none or the
+    name says the bytes are encoded (`.tar.gz` is gzip, not tar). `at` is UTC ISO seconds; `for` the logins the
+    document is for, unique and sorted (empty: every member); `by` who put it there, or null.
+  * Visibility (load, list_for, remove): a document is visible to the login whose store holds it, to every login when
+    `for` is empty, else to the logins `for` names (compared casefolded, as enrold compares member logins). The
+    caller has already established that `login` is a member (docsd's Serve-header gate); the store never reads
+    members/. remove() is for the store's login or a login `for` names — a document for everyone is removable only
+    by its owner (Forbidden); one the login cannot see is NotFound, like one that does not exist.
+  * Readers never follow a symbolic link and skip what does not validate: an id dir without a valid meta.json (an
+    intake in flight, a crash), a meta whose id/ws/lane do not match its path, a document file that is not a regular
+    file of the recorded size. counts.json is derived: recount() rebuilds it from the documents on disk.
+  * Callers: docsd (W3, libexec/docsd.py: list_for and load for its pages, intake for POST /up, audit for its reads
+    and refusals — it narrows the visibility rule above for a document whose `for` is empty to a member whose record
+    grants the workspace); docsd's publish pick-up (W4, docsd.Pickup: intake with `source` `publish` and `by` the lane
+    id it came from, a reader that refuses a sha256 other than the request's inside intake, so a mismatch leaves
+    nothing); both upload paths — POST /up and the SSH droplet `lanes upload` — which reach intake through
+    libexec/uploads.py (W5), landing the same bytes in the workspace's `uploads/` in one pass (`source` web | ssh);
+    statusd's lane counts (W7); `lanes docs push <id>` (W9: operator_receipt, the operator's read of one receipt).
+    Content, titles and names never reach docs.log; counts expose a per-lane number to every member.
+  * Encryption at rest (W5, LNS-106; operator decision 2026-10-08: designed in, default off). When
+    LANES_DOCS_AGE_RECIPIENT is set (age_settings: the environment when it names either age setting — lanes-docsd's
+    unit gives it its drop-in's —, else lanes-docsd.service's drop-in files themselves, which is how `lanes upload`
+    over SSH sees the same switch), intake pipes the bytes through `age -r <recipient>` as it hashes them and stores
+    `<name>.age` instead of `<name>`; meta.json then ends with `enc: {alg: "age", file: "<name>.age", bytes: <stored
+    size>, recipient}` and `name`, `mime`, `bytes` and `sha256` stay the PLAINTEXT's, computed before encryption, so
+    the receipt attests what arrived and what a decrypting reader gets back (age output is randomised: a hash of it
+    would match nothing anyone holds). decrypt() runs `age -d -i <identity>` (LANES_DOCS_AGE_IDENTITY) and checks
+    the plaintext against both. Readers of an older release find no `<name>` and skip the document. No `age` binary
+    with the recipient set: intake refuses (EncryptError, outcome `encrypt-failed`); host-install.sh refuses the
+    setting first (`python3 docs_store.py check-age`).
+"""
+import fcntl
+import hashlib
+import json
+import mimetypes
+import os
+import re
+import secrets
+import shlex
+import shutil
+import stat
+import subprocess
+import sys
+import tempfile
+import time
+from contextlib import contextmanager
+from pathlib import Path, PurePosixPath
+
+import lanes_lib as L
+import members
+import users
+
+VERSION = 1
+ID_RE = re.compile(r'^[a-z0-9]{10,20}$')
+BASE36 = '0123456789abcdefghijklmnopqrstuvwxyz'
+BASE32 = 'abcdefghijklmnopqrstuvwxyz234567'
+ID_TIME_CHARS = 6                  # base36 epoch seconds, zero-padded (6 characters until 2038-12-24)
+ID_RANDOM_CHARS = 6                # 30 random bits per second
+MAX_NAME = 128                     # a cleaned name; a collision suffix may add up to NAME_SLACK more
+NAME_SLACK = 8
+MAX_EXTENSION = 16                 # an extension clean_name keeps when it shortens a name
+MAX_TITLE = 200
+MAX_FOR = 64
+MAX_COMPONENT = 255                # NAME_MAX: one directory name
+MAX_META = 64 * 1024
+MAX_COUNTS = 4 * 1024 * 1024
+CHUNK = 64 * 1024
+LOCK_S = 2.0                       # seconds a change waits for docs/.lock before it is refused as Busy
+LOG_ROTATE_BYTES = 8 * 1024 * 1024  # docs.log at this size becomes docs.log.1 (one generation) before the next line
+META, RECEIPT, COUNTS, LOCK = 'meta.json', 'receipt.json', 'counts.json', '.lock'
+RESERVED_NAMES = frozenset((META, RECEIPT))
+RESERVED_STEMS = frozenset((COUNTS,))
+KINDS = ('upload', 'md', 'html', 'svg', 'file')
+URL = '/lanes-docs/d/{}'
+_NAME_DROP = re.compile(r'[^A-Za-z0-9._-]')
+_NAME = re.compile(r'[A-Za-z0-9_-][A-Za-z0-9._-]*\Z')
+_SOURCE = re.compile(r'[a-z][a-z0-9-]{0,31}\Z')
+_SHA256 = re.compile(r'[0-9a-f]{64}\Z')
+_AT = re.compile(r'\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ\Z', re.ASCII)
+_LOG_UNSAFE = re.compile(r'[^A-Za-z0-9_.@:+=/-]')       # enrold's enrol.log field alphabet
+_MIME = mimetypes.MimeTypes()                             # the built-in table only: no host mime.types
+# Deterministic across interpreters (container/lane_core.py carries the same table for the publish request).
+MIME_BY_SUFFIX = {'.md': 'text/markdown', '.markdown': 'text/markdown', '.html': 'text/html', '.htm': 'text/html',
+                  '.svg': 'image/svg+xml', '.txt': 'text/plain', '.json': 'application/json', '.csv': 'text/csv',
+                  '.pdf': 'application/pdf', '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+                  '.gif': 'image/gif', '.webp': 'image/webp'}
+AGE_RECIPIENT, AGE_IDENTITY = 'LANES_DOCS_AGE_RECIPIENT', 'LANES_DOCS_AGE_IDENTITY'
+AGE_SUFFIX = '.age'
+AGE_S = 120                        # seconds `age` may take for one document
+MAX_RECIPIENT = 4096               # an age1… key is 62 characters, an ssh-rsa line a few hundred
+MAX_UNIT_FILE = 64 * 1024          # a drop-in file larger than this is not read
+DOCSD_UNIT = 'lanes-docsd.service'
+_RECIPIENT = re.compile(r'[\x21-\x2c\x2e-\x7e][\x20-\x7e]*\Z')   # printable ASCII; never a leading blank or `-`
+
+
+class DocsError(L.LanesError):
+    """A refusal of the docs store; the message never echoes the refused value."""
+
+
+class EncryptError(DocsError):
+    """`age` is configured but absent, failed, or gave back other bytes than the meta records."""
+
+
+class TooLarge(DocsError):
+    def __init__(self, limit, received):
+        self.limit, self.received = limit, received
+        super().__init__(f'the document is larger than {limit} bytes')
+
+
+class Busy(DocsError):
+    pass
+
+
+class NotFound(DocsError):
+    pass
+
+
+class Forbidden(DocsError):
+    pass
+
+
+def _now():
+    return time.time()
+
+
+def stamp(t):
+    """UTC ISO seconds, the `at` of every store document and docs.log line."""
+    return time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime(t))
+
+
+def root():
+    return L.STATE / 'docs'
+
+
+def counts_path():
+    return root() / COUNTS
+
+
+def log_path():
+    return L.STATE / 'docs.log'
+
+
+def rotated_log_path():
+    return L.STATE / 'docs.log.1'
+
+
+# ------------------------------------------------------------------------------------------------------ identities
+
+def new_id(now=None):
+    """A document id: base36 epoch seconds (zero-padded to ID_TIME_CHARS) + ID_RANDOM_CHARS random base32."""
+    seconds, digits = int(_now() if now is None else now), ''
+    while True:
+        seconds, rest = divmod(seconds, 36)
+        digits = BASE36[rest] + digits
+        if not seconds:
+            break
+    return digits.rjust(ID_TIME_CHARS, '0') + ''.join(secrets.choice(BASE32) for _ in range(ID_RANDOM_CHARS))
+
+
+def check_id(value):
+    if not isinstance(value, str) or not ID_RE.fullmatch(value):
+        raise DocsError('a document id is 10 to 20 lowercase letters and digits')
+    return value
+
+
+def login_stem(login):
+    """users.stem(login), refused when it is no directory name of its own (see the module docstring)."""
+    stem = users.stem(login)
+    if stem.startswith('.') or stem in RESERVED_STEMS:
+        raise DocsError('this login cannot name a docs store directory')
+    return stem
+
+
+def check_workspace(value):
+    return users.check_workspace(value)
+
+
+def check_lane(value):
+    users.check_lane(value)
+    if len(value) > MAX_COMPONENT:
+        raise DocsError(f'a lane id longer than {MAX_COMPONENT} characters cannot name a docs directory')
+    return value
+
+
+def _tidy(text):
+    text = re.sub(r'\.{2,}', '.', text)
+    if text.startswith('.'):
+        text = 'file' + text
+    return text.rstrip('.')
+
+
+def clean_name(original):
+    """The stored name for an original file name (see the module docstring): never empty, never a path."""
+    base = re.split(r'[/\\]', original if isinstance(original, str) else '')[-1]
+    name = _tidy(_NAME_DROP.sub('', base))
+    if len(name) > MAX_NAME:
+        suffix = PurePosixPath(name).suffix
+        suffix = suffix if len(suffix) <= MAX_EXTENSION else ''
+        name = _tidy(name[:MAX_NAME - len(suffix)].rstrip('.') + suffix)
+    return name or 'file'
+
+
+def check_name(value):
+    """A name a store document may have: what clean_name makes, plus a collision suffix; never a store file."""
+    if (not isinstance(value, str) or not _NAME.match(value) or '..' in value
+            or len(value) > MAX_NAME + NAME_SLACK or value in RESERVED_NAMES):
+        raise DocsError('a document name is a plain file name of letters, digits, ".", "_" and "-"')
+    return value
+
+
+def _title(value):
+    """None (also for an empty title), or one printable line of at most MAX_TITLE characters (members' rule)."""
+    if value is None or value == '':
+        return None
+    return members._text(value, 'a title', MAX_TITLE, blanks=True)
+
+
+def _for(values):
+    if values is None:
+        return []
+    if isinstance(values, (str, bytes)) or not isinstance(values, (list, tuple)):
+        raise DocsError('for_logins is a list of logins')
+    logins = sorted({members.check_login(value, 'a login in for_logins') for value in values})
+    if len(logins) > MAX_FOR:
+        raise DocsError(f'a document is for at most {MAX_FOR} logins')
+    return logins
+
+
+def _limit(value):
+    if isinstance(value, bool) or not isinstance(value, int) or value < 0:
+        raise DocsError('limit is a non-negative whole number of bytes')
+    return value
+
+
+def _source(value):
+    if not isinstance(value, str) or not _SOURCE.match(value):
+        raise DocsError('source is a lowercase word of at most 32 characters')
+    return value
+
+
+def _kind(value):
+    if value not in KINDS:
+        raise DocsError('kind is one of ' + ', '.join(KINDS))
+    return value
+
+
+def _mime(name):
+    # The document kinds the cockpit renders carry their own types: Python's built-in table gained `.md` only in
+    # 3.12, so on an older interpreter (CI's runner) `plan.md` was `application/octet-stream` while the dev box said
+    # `text/markdown`. The host table is the fallback for everything else; an encoded name (`.tar.gz`) stays opaque.
+    mime = MIME_BY_SUFFIX.get(os.path.splitext(name)[1].lower())
+    if mime:
+        return mime
+    kind, encoding = _MIME.guess_type(name)
+    return kind if kind and not encoding else 'application/octet-stream'
+
+
+# ------------------------------------------------------------------------------------------- encryption at rest
+
+def dropin_dir(environ=None):
+    """lanes-docsd.service's drop-in directory: $XDG_CONFIG_HOME (when absolute) or ~/.config, then
+    systemd/user/lanes-docsd.service.d — where `systemctl --user edit lanes-docsd.service` writes override.conf."""
+    environ = os.environ if environ is None else environ
+    config = environ.get('XDG_CONFIG_HOME') or ''
+    base = Path(config) if config.startswith('/') else Path(environ.get('HOME') or Path.home()) / '.config'
+    return base / 'systemd' / 'user' / f'{DOCSD_UNIT}.d'
+
+
+def unit_environment(directory=None):
+    """The variables the `Environment=` lines of the drop-in files (`*.conf` in `directory`, default dropin_dir(), in
+    name order as systemd applies them) set in their [Service] section -> {name: value}. Words are split as a shell
+    splits them (systemd's quoting for the cases that matter here); an empty `Environment=` clears what came before, as
+    in systemd. A file that is a link, not regular or over MAX_UNIT_FILE is skipped. Never raises."""
+    found = {}
+    directory = Path(directory) if directory is not None else dropin_dir()
+    try:
+        names = sorted(entry.name for entry in os.scandir(directory) if entry.name.endswith('.conf'))
+        dir_fd = os.open(directory, os.O_RDONLY | os.O_DIRECTORY | getattr(os, 'O_CLOEXEC', 0))
+    except OSError:
+        return found
+    try:
+        for name in names:
+            raw = L.read_regular_at(dir_fd, name, MAX_UNIT_FILE)
+            if raw is None:
+                continue
+            section = None
+            for line in raw.decode('utf-8', 'replace').splitlines():
+                line = line.strip()
+                if line.startswith('[') and line.endswith(']'):
+                    section = line[1:-1]
+                elif section == 'Service' and line.startswith('Environment='):
+                    value = line[len('Environment='):].strip()
+                    if not value:
+                        found.clear()
+                        continue
+                    try:
+                        words = shlex.split(value)
+                    except ValueError:
+                        continue
+                    found.update(word.split('=', 1) for word in words if '=' in word)
+    finally:
+        os.close(dir_fd)
+    return found
+
+
+def age_settings(environ=None):
+    """(recipient or None, identity path or None) of the `age` switch: from `environ` (default os.environ) when it names
+    LANES_DOCS_AGE_RECIPIENT or LANES_DOCS_AGE_IDENTITY (docsd's unit puts its drop-in there), else from the drop-in
+    files themselves (unit_environment: `lanes upload` over SSH runs outside the unit). An empty value is unset. Raises
+    DocsError for a recipient that is not one printable line (never echoed)."""
+    environ = os.environ if environ is None else environ
+    if AGE_RECIPIENT not in environ and AGE_IDENTITY not in environ:
+        environ = unit_environment(dropin_dir(environ))
+    recipient = environ.get(AGE_RECIPIENT) or None
+    identity = environ.get(AGE_IDENTITY) or None
+    if recipient is not None and (len(recipient) > MAX_RECIPIENT or not _RECIPIENT.match(recipient)):
+        raise DocsError('LANES_DOCS_AGE_RECIPIENT is not an age recipient (one printable line, not an option)')
+    return recipient, identity
+
+
+def age_binary():
+    return shutil.which('age')
+
+
+def check_age(environ=None):
+    """None when the `age` switch can work here (off, or on with an `age` on PATH), else the reason it cannot."""
+    try:
+        recipient, _identity = age_settings(environ)
+    except DocsError as error:
+        return str(error)
+    if recipient is not None and age_binary() is None:
+        return (f'LANES_DOCS_AGE_RECIPIENT is set ({dropin_dir(environ)} or the environment) but there is no age '
+                'binary on PATH: install age (https://age-encryption.org) or remove the setting')
+    return None
+
+
+def stored_file(meta):
+    """(file name, size) of what lies on disk for a document: `<name>` and `bytes`, or for an encrypted one `enc.file`
+    (`<name>.age`) and `enc.bytes`."""
+    enc = meta.get('enc')
+    return (enc['file'], enc['bytes']) if enc else (meta['name'], meta['bytes'])
+
+
+def _valid_enc(meta):
+    enc = meta.get('enc')
+    if enc is None:
+        return 'enc' not in meta
+    return (isinstance(enc, dict) and set(enc) == {'alg', 'file', 'bytes', 'recipient'} and enc['alg'] == 'age'
+            and enc['file'] == f'{meta["name"]}{AGE_SUFFIX}' and isinstance(enc['bytes'], int)
+            and not isinstance(enc['bytes'], bool) and enc['bytes'] >= 0 and isinstance(enc['recipient'], str))
+
+
+def _age_error(process, errors, what):
+    errors.seek(0)
+    said = errors.read(2048).decode('utf-8', 'replace').strip().splitlines()
+    if said:                                                    # the journal hears age; the caller only a word
+        print(f'lanes docs: age {what}: {said[-1]}', file=sys.stderr, flush=True)
+    return EncryptError(f'age could not {what} the document (exit {process.returncode})')
+
+
+def decrypt(meta, fd, identity):
+    """The plaintext of the encrypted document `meta` whose stored file is open as `fd`, by `age -d -i <identity>` ->
+    bytes, exactly meta['bytes'] long with meta['sha256'] (else EncryptError). Holds the plaintext in memory: the
+    caller bounds meta['bytes']."""
+    age = age_binary()
+    if age is None or not identity:
+        raise EncryptError('no age binary or identity to decrypt with')
+    with tempfile.TemporaryFile() as errors:
+        process = subprocess.Popen([age, '-d', '-i', identity], stdin=fd, stdout=subprocess.PIPE, stderr=errors,
+                                   close_fds=True)
+        chunks, size = [], 0
+        try:
+            while size <= meta['bytes']:
+                chunk = process.stdout.read(CHUNK)
+                if not chunk:
+                    break
+                chunks.append(chunk)
+                size += len(chunk)
+        finally:
+            process.stdout.close()
+            try:
+                process.wait(AGE_S)
+            except subprocess.TimeoutExpired:
+                process.kill()
+                process.wait()
+        if process.returncode != 0:
+            raise _age_error(process, errors, 'decrypt')
+    data = b''.join(chunks)
+    if len(data) != meta['bytes'] or hashlib.sha256(data).hexdigest() != meta['sha256']:
+        raise EncryptError('the decrypted document is not the one its receipt names')
+    return data
+
+
+# -------------------------------------------------------------------------------------------------------- the tree
+
+def _real_dir(path):
+    try:
+        info = os.lstat(path)
+    except OSError:
+        return False
+    return stat.S_ISDIR(info.st_mode)
+
+
+def _private_dir(path):
+    """`path` as a real 0700 directory, created when absent; a symbolic link or a non-directory is refused."""
+    try:
+        os.mkdir(path, 0o700)
+    except FileExistsError:
+        pass
+    if not _real_dir(path):
+        raise DocsError('the docs store holds something that is not a directory where a directory belongs')
+    if stat.S_IMODE(os.lstat(path).st_mode) != 0o700:
+        os.chmod(path, 0o700)
+    return path
+
+
+def _lane_dir(stem, ws, lane):
+    """STATE/docs/<stem>/<ws>/<lane>, created as needed, every component a real 0700 directory."""
+    L.STATE.mkdir(parents=True, exist_ok=True)
+    path = _private_dir(root())
+    for part in (stem, ws, lane):
+        path = _private_dir(path / part)
+    return path
+
+
+def _subdirs(path):
+    """The real (never symlinked) subdirectories of `path` whose names do not start with a dot, sorted."""
+    try:
+        with os.scandir(path) as entries:
+            return sorted(entry.name for entry in entries
+                          if not entry.name.startswith('.') and entry.is_dir(follow_symlinks=False))
+    except OSError:
+        return []
+
+
+def _doc_dirs(ws=None, lane=None, doc_id=None):
+    """(stem, ws, lane, id) of every candidate id dir, optionally of one workspace, lane and/or id. A directory the
+    walk lists is never a symbolic link; a named ws/lane/id is taken as given and _read_doc refuses a link."""
+    if not _real_dir(root()):
+        return
+    for stem in _subdirs(root()):
+        if stem in RESERVED_STEMS:
+            continue
+        for ws_name in ([ws] if ws is not None else _subdirs(root() / stem)):
+            for lane_name in ([lane] if lane is not None else _subdirs(root() / stem / ws_name)):
+                lane_path = root() / stem / ws_name / lane_name
+                if doc_id is not None:
+                    if _real_dir(lane_path / doc_id):
+                        yield stem, ws_name, lane_name, doc_id
+                    continue
+                for name in _subdirs(lane_path):
+                    if ID_RE.fullmatch(name):
+                        yield stem, ws_name, lane_name, name
+
+
+def _read_doc(stem, ws, lane, doc_id):
+    """The meta of one stored document when it is complete and consistent, else None. Every directory component is
+    opened without following a link; meta.json is read only when it is a regular file of at most MAX_META bytes;
+    the document file must be a regular file of the recorded size."""
+    try:
+        fd = L.open_real_dir(root(), (stem, ws, lane, doc_id))
+    except (OSError, L.LanesError):
+        return None
+    try:
+        raw = L.read_regular_at(fd, META, MAX_META)
+        meta = json.loads(raw.decode('utf-8')) if raw is not None else None
+        if not _valid_meta(meta, ws, lane, doc_id):
+            return None
+        name, size = stored_file(meta)
+        info = os.stat(name, dir_fd=fd, follow_symlinks=False)
+        if not stat.S_ISREG(info.st_mode) or info.st_size != size:
+            return None
+        return meta
+    except (OSError, ValueError):
+        return None
+    finally:
+        os.close(fd)
+
+
+def _valid_meta(meta, ws, lane, doc_id):
+    if not isinstance(meta, dict) or meta.get('v') != VERSION:
+        return False
+    if (meta.get('id'), meta.get('ws'), meta.get('lane')) != (doc_id, ws, lane):
+        return False
+    size, fors, title, by = meta.get('bytes'), meta.get('for'), meta.get('title'), meta.get('by')
+    try:
+        check_name(meta.get('name'))
+    except DocsError:
+        return False
+    return (meta.get('kind') in KINDS and isinstance(size, int) and not isinstance(size, bool) and size >= 0
+            and isinstance(meta.get('sha256'), str) and bool(_SHA256.match(meta['sha256']))
+            and isinstance(meta.get('at'), str) and bool(_AT.match(meta['at']))
+            and isinstance(fors, list) and all(isinstance(login, str) for login in fors)
+            and (title is None or isinstance(title, str)) and (by is None or isinstance(by, str))
+            and isinstance(meta.get('mime'), str) and isinstance(meta.get('source'), str) and _valid_enc(meta))
+
+
+def _encode(document, sort_keys=False):
+    return (json.dumps(document, indent=2, ensure_ascii=False, sort_keys=sort_keys) + '\n').encode('utf-8')
+
+
+@contextmanager
+def _locked():
+    """Hold docs/.lock (an exclusive flock) for at most LOCK_S seconds of waiting, else Busy."""
+    L.STATE.mkdir(parents=True, exist_ok=True)
+    _private_dir(root())
+    fd = users._acquire(root() / LOCK, LOCK_S)
+    if fd is None:
+        raise Busy('the docs store is busy; try again')
+    try:
+        yield
+    finally:
+        os.close(fd)                                              # closing the descriptor releases the flock
+
+
+def _taken_names(lane_path):
+    """Every document name already in one lane dir of one login, plus the store's own file names. An encrypted
+    document's `<name>.age` takes `<name>` too, so the collision rule is the same with the `age` switch on or off."""
+    taken = set(RESERVED_NAMES)
+    for doc_id in _subdirs(lane_path):
+        try:
+            with os.scandir(lane_path / doc_id) as entries:
+                for entry in entries:
+                    if not entry.name.startswith('.'):
+                        taken.add(entry.name)
+                        if entry.name.endswith(AGE_SUFFIX):
+                            taken.add(entry.name[:-len(AGE_SUFFIX)])
+        except OSError:
+            continue
+    return taken
+
+
+def _unique_name(name, taken):
+    """bin/lanes cmd_upload's rule: `<stem>-<n><suffix>`, n from 1, until the name is free."""
+    final, n = name, 1
+    path = PurePosixPath(name)
+    while final in taken:
+        final = f'{path.stem}-{n}{path.suffix}'
+        n += 1
+    return final
+
+
+# ---------------------------------------------------------------------------------------------------------- counts
+
+def _lane_count(lane):
+    n, newest = 0, None
+    for stem, ws, lane_name, doc_id in _doc_dirs(lane=lane):
+        meta = _read_doc(stem, ws, lane_name, doc_id)
+        if meta is not None:
+            n += 1
+            newest = meta['at'] if newest is None or meta['at'] > newest else newest
+    return {'n': n, 'at': newest} if n else None
+
+
+def _scan_counts():
+    counts = {}
+    for stem, ws, lane, doc_id in _doc_dirs():
+        meta = _read_doc(stem, ws, lane, doc_id)
+        if meta is None:
+            continue
+        entry = counts.setdefault(lane, {'n': 0, 'at': meta['at']})
+        entry['n'] += 1
+        entry['at'] = max(entry['at'], meta['at'])
+    return counts
+
+
+def _stored_counts():
+    """counts.json when it is a valid {lane id: {n, at}} object, else None (absent, corrupt: rebuild it). Read
+    without following a link or blocking on a FIFO."""
+    try:
+        fd = L.open_real_dir(root(), ())
+    except OSError:
+        return None
+    try:
+        raw = L.read_regular_at(fd, COUNTS, MAX_COUNTS)
+        counts = json.loads(raw.decode('utf-8')) if raw is not None else None
+    except ValueError:
+        return None
+    finally:
+        os.close(fd)
+    if not isinstance(counts, dict):
+        return None
+    for lane, entry in counts.items():
+        if not (isinstance(entry, dict) and set(entry) == {'n', 'at'} and isinstance(entry['n'], int)
+                and not isinstance(entry['n'], bool) and entry['n'] > 0 and isinstance(entry['at'], str)
+                and _AT.match(entry['at']) and isinstance(lane, str) and L.IDENT.match(lane)):
+            return None
+    return counts
+
+
+def _write_counts(counts):
+    L.atomic_write_if_changed(counts_path(), _encode(counts, sort_keys=True), 0o600)
+
+
+def _update_counts(lane):
+    """Under the lock: the lane's entry recounted from disk (absent at 0); a corrupt file is rebuilt whole."""
+    counts = _stored_counts()
+    if counts is None:
+        counts = _scan_counts()
+    else:
+        entry = _lane_count(lane)
+        if entry is None:
+            counts.pop(lane, None)
+        else:
+            counts[lane] = entry
+    _write_counts(counts)
+    return counts
+
+
+def recount():
+    """Rebuild counts.json from the documents on disk (under the lock) -> the counts. Writes only on a change."""
+    with _locked():
+        counts = _scan_counts()
+        _write_counts(counts)
+    return counts
+
+
+def read_counts():
+    """counts.json for readers ({} when absent or not valid); never raises."""
+    return _stored_counts() or {}
+
+
+# ------------------------------------------------------------------------------------------------------------- log
+
+def _log_field(value):
+    if value is None or value == '':
+        return '-'
+    return _LOG_UNSAFE.sub('?', str(value))[:MAX_COMPONENT + 1]
+
+
+def audit(event, login, doc_id, lane, size, sha256, outcome, now=None):
+    """Append one docs.log line (0600): `<at> <login> <event> <id> <lane> <bytes> <sha256> <outcome>`, `-` for a
+    field not known; never content, a title or a name. Never raises: a log that cannot be written is said on
+    stderr. -> True when the line was written. A docs.log that has reached LOG_ROTATE_BYTES is first renamed to
+    docs.log.1 (replacing the one generation kept) and a new one begun — under an exclusive flock of the full file, and
+    only while the name still holds that file, so of several writers (docsd's threads, `lanes upload`) exactly one
+    rotates it (security review 2026-10-08, F4: before, refusals anyone on the tailnet could cause grew it without
+    bound)."""
+    line = ' '.join((stamp(_now() if now is None else now), _log_field(login), _log_field(event),
+                     _log_field(doc_id), _log_field(lane), _log_field(size), _log_field(sha256),
+                     _log_field(outcome)))
+    try:
+        L.STATE.mkdir(parents=True, exist_ok=True)
+        fd = _open_log()
+        try:
+            if os.fstat(fd).st_size >= LOG_ROTATE_BYTES:
+                _rotate_log(fd)
+                os.close(fd)
+                fd = None
+                fd = _open_log()
+            os.write(fd, (line + '\n').encode('ascii', 'replace'))
+        finally:
+            if fd is not None:
+                os.close(fd)
+        return True
+    except OSError as error:
+        print(f'lanes docs: cannot append to {log_path()}: {error.strerror or error}', file=sys.stderr, flush=True)
+        return False
+
+
+def _open_log():
+    return os.open(log_path(), os.O_WRONLY | os.O_APPEND | os.O_CREAT | os.O_NOFOLLOW | getattr(os, 'O_CLOEXEC', 0),
+                   0o600)
+
+
+def _rotate_log(fd):
+    """Rename docs.log (open as `fd`, at least LOG_ROTATE_BYTES) to docs.log.1. Another writer that rotated first (the
+    name no longer holds `fd`'s file) is left alone. The caller closes `fd` and opens docs.log again."""
+    fcntl.flock(fd, fcntl.LOCK_EX)
+    try:
+        held, named = os.fstat(fd), os.stat(log_path(), follow_symlinks=False)
+        if (held.st_dev, held.st_ino) == (named.st_dev, named.st_ino) and held.st_size >= LOG_ROTATE_BYTES:
+            os.replace(log_path(), rotated_log_path())
+    except FileNotFoundError:
+        pass                                                      # renamed away by another writer meanwhile
+    finally:
+        fcntl.flock(fd, fcntl.LOCK_UN)
+
+
+# ---------------------------------------------------------------------------------------------------------- intake
+
+def intake(login, ws, lane, name, reader, *, limit, source, kind='upload', title=None, for_logins=None, by=None):
+    """Store the bytes `reader` (a binary file-like: read(n) -> bytes) yields as a new document of `login` in `ws` /
+    `lane` -> its meta dict. Refuses (DocsError, nothing written) an invalid argument, TooLarge past `limit` bytes,
+    Busy when the store lock is not free within LOCK_S, EncryptError when the `age` switch is on and age is absent or
+    fails; any failure removes what it wrote. One docs.log line either way (outcome `ok`, `invalid`, `too-large`,
+    `busy`, `unsafe`, `encrypt-failed` or `error`)."""
+    known = {}
+    try:
+        stem = login_stem(login)
+        known['login'] = login
+        check_workspace(ws)
+        check_lane(lane)
+        known['lane'] = lane
+        clean = clean_name(name)
+        limit, source, kind = _limit(limit), _source(source), _kind(kind)
+        title, fors = _title(title), _for(for_logins)
+        if by is not None:
+            members.check_login(by, 'by')
+        recipient, _identity = age_settings()
+    except L.LanesError as error:
+        audit('intake', known.get('login'), None, known.get('lane'), None, None, 'invalid')
+        raise (error if isinstance(error, DocsError) else DocsError(str(error))) from None
+    try:
+        lane_path = _lane_dir(stem, ws, lane)
+    except (DocsError, OSError) as error:
+        audit('intake', login, None, lane, None, None, 'unsafe')
+        raise (error if isinstance(error, DocsError) else DocsError('the docs store cannot be written')) from None
+    now = _now()
+    doc_dir = doc_id = size = sha256 = None
+    outcome = 'error'
+    try:
+        doc_dir, doc_id = _new_doc_dir(lane_path, now)
+        temporary = doc_dir / f'.incoming-{secrets.token_hex(6)}'
+        size, sha256, stored = _stream(reader, temporary, limit, recipient)
+        with _locked():
+            final = _unique_name(clean, _taken_names(lane_path))
+            os.replace(temporary, doc_dir / (final + AGE_SUFFIX if recipient else final))
+            at = stamp(now)
+            meta = {'v': VERSION, 'id': doc_id, 'ws': ws, 'lane': lane, 'kind': kind, 'title': title, 'name': final,
+                    'mime': _mime(final), 'bytes': size, 'sha256': sha256, 'at': at, 'by': by, 'for': fors,
+                    'source': source}
+            if recipient:
+                meta['enc'] = {'alg': 'age', 'file': final + AGE_SUFFIX, 'bytes': stored, 'recipient': recipient}
+            receipt = {'v': VERSION, 'id': doc_id, 'sha256': sha256, 'bytes': size, 'url': URL.format(doc_id),
+                       'at': at}
+            L.atomic_write(doc_dir / RECEIPT, _encode(receipt), 0o600)
+            L.atomic_write(doc_dir / META, _encode(meta), 0o600)
+            _update_counts(lane)
+        outcome = 'ok'
+        return meta
+    except TooLarge as error:
+        outcome, size = 'too-large', error.received
+        raise
+    except Busy:
+        outcome = 'busy'
+        raise
+    except EncryptError:
+        outcome = 'encrypt-failed'
+        raise
+    finally:
+        if outcome != 'ok' and doc_dir is not None:
+            shutil.rmtree(doc_dir, ignore_errors=True)
+        audit('intake', login, doc_id, lane, size, sha256 if outcome == 'ok' else None, outcome)
+
+
+def _new_doc_dir(lane_path, now):
+    """A new id dir (0700) in `lane_path`, made with an exclusive mkdir -> (path, id)."""
+    for _ in range(16):
+        doc_id = new_id(now)
+        path = lane_path / doc_id
+        try:
+            os.mkdir(path, 0o700)
+        except FileExistsError:
+            continue
+        os.chmod(path, 0o700)
+        return path, doc_id
+    raise DocsError('could not mint a free document id')
+
+
+def _stream(reader, path, limit, recipient=None):
+    """Copy `reader` into a new 0600 file at `path` (O_EXCL, never through a link), at most `limit` bytes, hashing
+    on the way -> (bytes, sha256 hex, bytes on disk). Reads at most limit + 1 bytes: one more is TooLarge. With an age
+    `recipient` the bytes are hashed as they come and piped through `age -r <recipient>` into the file, so the hash is
+    the plaintext's and the plaintext never touches the disk."""
+    digest, size = hashlib.sha256(), 0
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_EXCL | os.O_NOFOLLOW | getattr(os, 'O_CLOEXEC', 0), 0o600)
+    with os.fdopen(fd, 'wb') as out:
+        sink, process, errors = out, None, None
+        if recipient is not None:
+            age = age_binary()
+            if age is None:
+                raise EncryptError('LANES_DOCS_AGE_RECIPIENT is set, but there is no age binary on PATH')
+            errors = tempfile.TemporaryFile()
+            process = subprocess.Popen([age, '-r', recipient], stdin=subprocess.PIPE, stdout=out.fileno(),
+                                       stderr=errors, close_fds=True)
+            sink = process.stdin
+        try:
+            while True:
+                chunk = reader.read(min(CHUNK, limit + 1 - size))
+                if not chunk:
+                    break
+                if not isinstance(chunk, (bytes, bytearray)):
+                    raise DocsError('a document reader yields bytes')
+                size += len(chunk)
+                if size > limit:
+                    raise TooLarge(limit, size)
+                digest.update(chunk)
+                sink.write(chunk)
+            if process is not None:
+                sink.close()
+                process.wait(AGE_S)
+                if process.returncode != 0:
+                    raise _age_error(process, errors, 'encrypt')
+        except BrokenPipeError:
+            if process is None:
+                raise
+            process.wait(AGE_S)
+            raise _age_error(process, errors, 'encrypt') from None
+        except subprocess.TimeoutExpired:
+            raise EncryptError('age did not finish in time') from None
+        finally:
+            if process is not None:
+                if process.poll() is None:
+                    process.kill()
+                    process.wait()
+                if not process.stdin.closed:
+                    try:
+                        process.stdin.close()
+                    except OSError:
+                        pass
+                errors.close()
+        out.flush()
+        os.fchmod(out.fileno(), 0o600)
+        stored = os.fstat(out.fileno()).st_size
+    return size, digest.hexdigest(), stored
+
+
+# ---------------------------------------------------------------------------------------------------------- readers
+
+def _owner(stem, login):
+    try:
+        return login_stem(login) == stem
+    except L.LanesError:
+        return False
+
+
+def _visible(meta, stem, login):
+    folded = login.casefold()
+    return _owner(stem, login) or not meta['for'] or any(entry.casefold() == folded for entry in meta['for'])
+
+
+def _check_reader(login):
+    try:
+        return members.check_login(login)
+    except L.LanesError:
+        raise DocsError('the login is not valid') from None
+
+
+def list_for(login, ws=None, lane=None):
+    """The metas of every document visible to `login` (optionally of one workspace and/or lane), newest first (by
+    `at`, then id). Reads every matching meta.json: O(documents)."""
+    _check_reader(login)
+    try:
+        ws = check_workspace(ws) if ws is not None else None
+        lane = check_lane(lane) if lane is not None else None
+    except L.LanesError as error:
+        raise error if isinstance(error, DocsError) else DocsError(str(error)) from None
+    found = []
+    for stem, ws_name, lane_name, doc_id in _doc_dirs(ws, lane):
+        meta = _read_doc(stem, ws_name, lane_name, doc_id)
+        if meta is not None and _visible(meta, stem, login):
+            found.append(meta)
+    return sorted(found, key=lambda meta: (meta['at'], meta['id']), reverse=True)
+
+
+def _find(doc_id, login):
+    """(stem, meta) of the document `doc_id` when `login` may see it, else None."""
+    for stem, ws, lane, found in _doc_dirs(doc_id=doc_id):
+        meta = _read_doc(stem, ws, lane, found)
+        if meta is not None and _visible(meta, stem, login):
+            return stem, meta
+    return None
+
+
+def load(doc_id, login):
+    """(meta, path of the document file) when the document exists and is visible to `login`, else None. Raises
+    DocsError for an id or login that is not valid (never a path). For an encrypted document the path is its stored
+    `<name>.age` (stored_file)."""
+    check_id(doc_id)
+    _check_reader(login)
+    found = _find(doc_id, login)
+    if found is None:
+        return None
+    stem, meta = found
+    return meta, root() / stem / meta['ws'] / meta['lane'] / doc_id / stored_file(meta)[0]
+
+
+def remove(doc_id, login):
+    """Remove a document -> its meta. NotFound when it does not exist or `login` cannot see it, Forbidden when it can
+    see it but the document is neither in its store nor for it by name (see the module docstring), Busy when the
+    lock is not free. The id dir is renamed aside (readers skip dot names) and deleted; the lane's count follows."""
+    try:
+        _check_reader(login)
+    except DocsError:
+        audit('remove', None, None, None, None, None, 'invalid')
+        raise
+    try:
+        check_id(doc_id)
+    except DocsError:
+        audit('remove', login, None, None, None, None, 'invalid')
+        raise
+    meta, outcome = None, 'error'
+    try:
+        with _locked():
+            found = _find(doc_id, login)
+            if found is None:
+                outcome = 'not-found'
+                raise NotFound('no such document')
+            stem, meta = found
+            folded = login.casefold()
+            if not (_owner(stem, login) or any(entry.casefold() == folded for entry in meta['for'])):
+                outcome = 'forbidden'
+                raise Forbidden('only the document\'s owner or a login it is for may remove it')
+            lane_path = root() / stem / meta['ws'] / meta['lane']
+            aside = lane_path / f'.removing-{doc_id}-{secrets.token_hex(4)}'
+            os.rename(lane_path / doc_id, aside)
+            shutil.rmtree(aside, ignore_errors=True)
+            _update_counts(meta['lane'])
+        outcome = 'ok'
+        return meta
+    except Busy:
+        outcome = 'busy'
+        raise
+    finally:
+        audit('remove', login, doc_id, meta['lane'] if meta else None, meta['bytes'] if meta else None,
+              meta['sha256'] if meta else None, outcome)
+
+
+def operator_receipt(doc_id):
+    """(meta, receipt) of the stored document `doc_id`, whichever login's store holds it, else None. For the operator
+    — the account the store belongs to — so no login's visibility applies: `lanes docs push <id>` (plan W10 W9, the
+    stub of the data service's publication hook) prints the receipt. The document must read as complete (_read_doc)
+    and its receipt.json must be a regular file of at most MAX_META bytes, opened without following a link, holding a
+    `v` 1 object whose `id` is `doc_id`. Reads only; no docs.log line (no content is read). DocsError for an id that
+    is not valid (never a path)."""
+    check_id(doc_id)
+    for stem, ws, lane, found in _doc_dirs(doc_id=doc_id):
+        meta = _read_doc(stem, ws, lane, found)
+        if meta is None:
+            continue
+        try:
+            fd = L.open_real_dir(root(), (stem, ws, lane, found))
+        except (OSError, L.LanesError):
+            continue
+        try:
+            raw = L.read_regular_at(fd, RECEIPT, MAX_META)
+        finally:
+            os.close(fd)
+        try:
+            receipt = json.loads(raw.decode('utf-8')) if raw is not None else None
+        except ValueError:
+            receipt = None
+        if isinstance(receipt, dict) and receipt.get('v') == VERSION and receipt.get('id') == doc_id:
+            return meta, receipt
+    return None
+
+
+def main(argv=None):
+    """`python3 docs_store.py check-age` (install/host-install.sh check_docs_age): exit 0 when the `age` switch can work
+    here, else 1 with the reason on stderr."""
+    argv = sys.argv[1:] if argv is None else argv
+    if argv != ['check-age']:
+        print('usage: docs_store.py check-age', file=sys.stderr)
+        return 2
+    problem = check_age()
+    if problem:
+        print(f'lanes docs: {problem}', file=sys.stderr)
+        return 1
+    return 0
+
+
+if __name__ == '__main__':
+    sys.exit(main())