@vibelord/lanes 1.0.3 → 1.1.0

package/payload/lanes/libexec/lanes_lib.py

@@ -38,9 +38,11 @@ CONTAINER_HOME = '/home/coder'
 CONTAINER_UID = 1000
 
 LANE_OPEN = '/.lz/bin/lane open '   # the uniform Cursor-facing entry point written by `lanes cursor-sync`
-IDENT = re.compile(r'^[A-Za-z0-9_][A-Za-z0-9_.-]*$')
-TMUX_SESSION = re.compile(r'^[A-Za-z0-9_][A-Za-z0-9_. -]*$')
-SAFE_PATH = re.compile(r'^/[A-Za-z0-9_./-]+$')
+# `\Z`, never `$`: every caller uses .match (or _require), and `$` also matches before a final newline, so
+# "anna-mbp\n" from a JSON body passed as a device name (DEF-1642).
+IDENT = re.compile(r'^[A-Za-z0-9_][A-Za-z0-9_.-]*\Z')
+TMUX_SESSION = re.compile(r'^[A-Za-z0-9_][A-Za-z0-9_. -]*\Z')
+SAFE_PATH = re.compile(r'^/[A-Za-z0-9_./-]+\Z')
 
 # The Throttle Studio Host's OWN grouped session names, mirroring `studio_host::tmux::WebSession::channel_of`
 # exactly: `view-<studio token>-<channel>` as `for_channel` mints it (the token is `[A-Za-z0-9_-]` and may
@@ -103,11 +105,14 @@ class LanesError(Exception):
 
 
 def atomic_write(path, text, mode=0o600):
+    """Replace `path` with `text` atomically (temp file in the same directory, chmod, rename). `text` may be bytes:
+    then it is written byte for byte, never through the locale's encoding (keys.py keeps foreign authorized_keys
+    lines exactly)."""
     path = Path(path)
     path.parent.mkdir(parents=True, exist_ok=True)
     fd, tmp = tempfile.mkstemp(prefix='.' + path.name + '.', dir=str(path.parent))
     try:
-        with os.fdopen(fd, 'w') as handle:
+        with os.fdopen(fd, 'wb' if isinstance(text, bytes) else 'w') as handle:
             handle.write(text)
         os.chmod(tmp, mode)
         os.replace(tmp, path)
@@ -122,9 +127,10 @@ def atomic_write(path, text, mode=0o600):
 def atomic_write_if_changed(path, text, mode=0o600):
     """atomic_write, skipped when the file already holds exactly `text` -> True when it wrote. Readers that reload
     on mtime (statusd and notify on registry.json, every sidebar) then do not wake for a projection that did not
-    change, and the timer-driven sync stops rewriting the container volumes every two minutes."""
+    change, and the timer-driven sync stops rewriting the container volumes every two minutes. Bytes compare and
+    write as bytes."""
     try:
-        if Path(path).read_text() == text:
+        if (Path(path).read_bytes() if isinstance(text, bytes) else Path(path).read_text()) == text:
             return False
     except (OSError, ValueError):
         pass
@@ -661,6 +667,8 @@ SITE_SCHEMA = 1   # catalog.json / workspaces.<board>.json / commit-targets.json
 
 def read_site_json(path):
     data = json.loads(Path(path).read_text())
+    if not isinstance(data, dict):   # every site file is an object; `.get` on an array was an AttributeError (DEF-1718)
+        raise LanesError(f'{path}: not a JSON object')
     if int(data.get('version', 1)) > SITE_SCHEMA:
         raise LanesError(f'{path} is version {data["version"]}; this server understands {SITE_SCHEMA} — update the lanes checkout')
     return data

package/payload/lanes/libexec/members.py

@@ -0,0 +1,297 @@
+"""lanes members — the members/<device>.json store: which machine key belongs to whom (W8 A2, LNS-41).
+
+One JSON file per enrolled device under ~/.local/state/lanes/members/ (directory 0700, files 0600):
+
+    {"device": "anna-mbp", "pubkey": "ssh-ed25519 AAAA...", "pubkey_sha256": "SHA256:...",
+     "owner": {"login": "anna@example.com", "name": "Anna Berg", "email": "anna@example.com"},
+     "enrolled_at": "2026-10-05T12:00:00Z", "via": "invite", "approved_by": "admin@example.com",
+     "invite_id": "7q4k", "workspaces": ["bw-tools", "throttle"]}
+
+  * This module owns the file I/O and the IDENTITY fields, and is their one definition of valid: keys.load_members
+    (the authorized_keys projection, fail closed), enrolment (W8 A3/A4) and create_session (bin/lanes) all use it.
+    The KEY fields (`pubkey`, `pubkey_sha256`) are keys.py's: it checks them on every load and before every write it
+    makes. A change to who may log in goes through keys.py under its `members.lock`, never through write() alone.
+  * `owner` is null for a key added by hand (`lanes keys add|adopt`, via `manual`) until `lanes keys owner` names one,
+    and {login, name, email} from enrolment: `login` is the tailnet login Tailscale Serve hands the enrol service
+    (`Tailscale-User-Login`; outside request mode the invite's email, or its name when that is a handle), `name`
+    and `email` may be null. `via` is invite|request|manual; an invite record carries its `invite_id`, a request
+    record its `request_id`, a manual one neither. `approved_by` is a login or null; `workspaces` lists board ids.
+  * `invited_as` (optional, additive; an invite record only) is the invite's own {name, email} when a TRUSTED tailnet
+    caller redeemed it (request mode): the owner is then the caller, whoever the invite was minted for, and this keeps
+    who it was minted for beside it. Absent when no trusted caller redeemed (the owner then came from the invite).
+  * Every text field can reach a terminal (`lanes device list`, `lanes keys list`) and the file is UTF-8: a character
+    of Unicode category Cc (C0, DEL, C1), Cf (format: the bidi marks, embeddings and isolates, zero-width characters,
+    the BOM, the soft hyphen), Cs (a lone surrogate — what json.loads makes of a body's "\\ud800"), Co (private use),
+    Cn (unassigned or a noncharacter) or Zl/Zp (line/paragraph separator) is refused (DEF-1703); logins and ids carry
+    no blanks, a name may carry inner ones (U+3000 included); a refusal never echoes the value. A display name the
+    store refuses can be stored as null by its writer: `name` is optional.
+  * Readers are tolerant (unknown keys pass, optional fields may be absent: what `lanes keys` wrote before A2 still
+    loads); record() emits exactly the schema, in its order. write() refuses a document it cannot encode as UTF-8 (an
+    unknown key the tolerant check passed), writing nothing.
+  * Writing a member never creates devices/<device>.json. Only a view session does (create_session); `lanes ensure`
+    builds a view session for every devices/*.json, so a member write that made one would resurrect a view nobody
+    opened. Which owner a device file records is owner_for(): the member record decides whenever one exists.
+"""
+import json
+import os
+import re
+import time
+import unicodedata
+from pathlib import Path
+
+import lanes_lib as L
+
+VIA = ('invite', 'request', 'manual')
+SOURCE_ID = {'invite': 'invite_id', 'request': 'request_id'}
+MAX_DEVICE = 32                 # bin/lanes device_name()
+MAX_LOGIN = 254
+MAX_NAME = 128
+MAX_ID = 64
+REFUSED_CATEGORIES = frozenset(('Cc', 'Cf', 'Cs', 'Co', 'Cn', 'Zl', 'Zp'))
+_EMAIL = re.compile(r'[^@\s]+@[^@\s]+')
+_STAMP = re.compile(r'\d{4}-\d\d-\d\dT\d\d:\d\d:\d\dZ', re.ASCII)
+
+
+def members_dir():
+    return L.STATE / 'members'
+
+
+def device_name(value):
+    if not isinstance(value, str) or not L.IDENT.match(value) or len(value) > MAX_DEVICE:
+        raise L.LanesError(f'Invalid device name: {value!r}')
+    return value
+
+
+def unsafe(value):
+    """Whether `value` holds a character no terminal line may carry (REFUSED_CATEGORIES; see the module docstring)."""
+    return any(unicodedata.category(char) in REFUSED_CATEGORIES for char in value)
+
+
+def _text(value, what, limit, blanks=False):
+    """A one-line, printable string of at most `limit` characters (`blanks`: inner spaces allowed, as in a name)."""
+    if (not isinstance(value, str) or not value or len(value) > limit or unsafe(value)
+            or value != value.strip() or (not blanks and any(c.isspace() for c in value))):
+        raise L.LanesError(f'{what} is not valid (a one-line printable value of at most {limit} characters'
+                           + (')' if blanks else ' without blanks)'))
+    return value
+
+
+def _ident(value, what, limit):
+    if not isinstance(value, str) or not L.IDENT.match(value) or len(value) > limit:
+        raise L.LanesError(f'{what} is not an identifier of at most {limit} characters')
+    return value
+
+
+def check_login(value, what='login'):
+    """A tailnet login (`anna@example.com`, `anna@github`): printable, no blanks, at most 254 characters."""
+    return _text(value, what, MAX_LOGIN)
+
+
+def validate_owner(value):
+    """None, or the owner normalized to exactly {login, name, email} (name/email null when absent or empty — a tailnet
+    identity may carry no display name; other keys are not carried). Raises on anything else."""
+    if value is None:
+        return None
+    if not isinstance(value, dict):
+        raise L.LanesError('owner must be an object {login, name, email} or null')
+    owner = {'login': check_login(value.get('login'), 'owner login'), 'name': None, 'email': None}
+    if value.get('name') not in (None, ''):
+        owner['name'] = _text(value['name'], 'owner name', MAX_NAME, blanks=True)
+    if value.get('email') not in (None, ''):
+        owner['email'] = _text(value['email'], 'owner email', MAX_LOGIN)
+        if not _EMAIL.fullmatch(owner['email']):
+            raise L.LanesError('owner email is not an address')
+    return owner
+
+
+def valid_owner(value):
+    """validate_owner for readers of files lanes does not trust to be well formed (devices/*.json): the normalized
+    owner, or None — never raises."""
+    try:
+        return validate_owner(value)
+    except L.LanesError:
+        return None
+
+
+def validate_invited_as(value):
+    """None, or an invite's own {name, email} normalized to exactly those keys (each null when absent or empty; the
+    owner's text rules). Raises on anything else."""
+    if value is None:
+        return None
+    if not isinstance(value, dict):
+        raise L.LanesError('invited_as must be an object {name, email} or null')
+    invited = {'name': None, 'email': None}
+    if value.get('name') not in (None, ''):
+        invited['name'] = _text(value['name'], 'invited_as name', MAX_NAME, blanks=True)
+    if value.get('email') not in (None, ''):
+        invited['email'] = _text(value['email'], 'invited_as email', MAX_LOGIN)
+        if not _EMAIL.fullmatch(invited['email']):
+            raise L.LanesError('invited_as email is not an address')
+    return invited
+
+
+def validate(document, stem=None):
+    """`document` when its identity fields are valid (see the module docstring); `stem` is its file's name without
+    .json, which `device` must equal. Raises L.LanesError naming the first problem, never echoing a value."""
+    if not isinstance(document, dict):
+        raise L.LanesError('not a JSON object')
+    if stem is not None and document.get('device') != stem:
+        raise L.LanesError('its device does not match the file name')
+    device_name(document.get('device'))
+    via = document.get('via')
+    if via is not None and via not in VIA:
+        raise L.LanesError('via must be one of ' + ', '.join(VIA))
+    validate_owner(document.get('owner'))
+    if document.get('approved_by') is not None:
+        check_login(document['approved_by'], 'approved_by')
+    for source, field in SOURCE_ID.items():
+        if document.get(field) is not None:
+            if via != source:
+                raise L.LanesError(f'{field} on a record enrolled via {via or "nothing"}')
+            _ident(document[field], field, MAX_ID)
+    if document.get('invited_as') is not None:
+        if via != 'invite':
+            raise L.LanesError(f'invited_as on a record enrolled via {via or "nothing"}')
+        validate_invited_as(document['invited_as'])
+    workspaces = document.get('workspaces')
+    if workspaces is not None:
+        if not isinstance(workspaces, list):
+            raise L.LanesError('workspaces must be a list of workspace ids')
+        for workspace in workspaces:
+            _ident(workspace, 'a workspace id', MAX_ID)
+        if len(set(workspaces)) != len(workspaces):
+            raise L.LanesError('workspaces lists an id twice')
+    stamp = document.get('enrolled_at')
+    if stamp is not None and not (isinstance(stamp, str) and _STAMP.fullmatch(stamp)):
+        raise L.LanesError('enrolled_at is not a UTC YYYY-MM-DDTHH:MM:SSZ time')
+    return document
+
+
+def record(device, pubkey, pubkey_sha256, via='manual', owner=None, approved_by=None, invite_id=None,
+           request_id=None, workspaces=(), now=None, invited_as=None):
+    """A members/<device>.json document, exactly the schema in its order. The caller supplies the key fields (keys.py
+    computes the fingerprint and checks the key); an invite needs its invite_id, a request its request_id. `invited_as`
+    (an invite redeemed by a trusted caller only) is appended last when given."""
+    ids = {'invite_id': invite_id, 'request_id': request_id}
+    if via not in VIA:
+        raise L.LanesError('via must be one of ' + ', '.join(VIA))
+    for field, value in ids.items():
+        if value is not None and SOURCE_ID.get(via) != field:
+            raise L.LanesError(f'{field} on a record enrolled via {via}')
+    if invited_as is not None and via != 'invite':
+        raise L.LanesError(f'invited_as on a record enrolled via {via}')
+    document = {'device': device_name(device), 'pubkey': pubkey, 'pubkey_sha256': pubkey_sha256,
+                'owner': validate_owner(owner), 'enrolled_at': time.strftime('%Y-%m-%dT%H:%M:%SZ', time.gmtime(now)),
+                'via': via, 'approved_by': approved_by}
+    if via in SOURCE_ID:
+        field = SOURCE_ID[via]
+        if ids[field] is None:
+            raise L.LanesError(f'a record enrolled via {via} needs its {field}')
+        document[field] = ids[field]
+    document['workspaces'] = ([] if workspaces is None else
+                              list(workspaces) if isinstance(workspaces, (list, tuple)) else workspaces)
+    if invited_as is not None:
+        document['invited_as'] = validate_invited_as(invited_as)
+    return validate(document)
+
+
+def _private_dir(directory):
+    directory.mkdir(mode=0o700, parents=True, exist_ok=True)
+    if directory.stat().st_mode & 0o777 != 0o700:
+        os.chmod(directory, 0o700)
+
+
+def write(document, directory=None):
+    """Validate, then replace members/<device>.json atomically (0600, directory 0700) with its UTF-8 JSON -> its path.
+    Writes nothing on a refusal (a document that does not validate or cannot be encoded), and never touches devices/."""
+    validate(document)
+    try:
+        data = (json.dumps(document, indent=2, ensure_ascii=False) + '\n').encode('utf-8')
+    except UnicodeEncodeError:
+        raise L.LanesError(f"member {document['device']}: a field holds text that is not valid Unicode "
+                           '(a lone surrogate)') from None
+    directory = Path(directory or members_dir())
+    _private_dir(directory)
+    path = directory / f"{document['device']}.json"
+    L.atomic_write(path, data, mode=0o600)
+    return path
+
+
+def _parse(path):
+    """The JSON document in `path` (UTF-8, whatever the locale). Raises FileNotFoundError when there is none and
+    L.LanesError for a file that cannot be read or is not JSON."""
+    try:
+        text = path.read_bytes().decode('utf-8')
+    except FileNotFoundError:
+        raise
+    except (OSError, UnicodeDecodeError) as error:
+        raise L.LanesError(getattr(error, 'strerror', None) or error.__class__.__name__) from None
+    try:
+        return json.loads(text)
+    except ValueError:
+        raise L.LanesError('not JSON') from None
+
+
+def read(device, directory=None):
+    """members/<device>.json validated, or None when there is none. Raises L.LanesError for an invalid device name or
+    a file that is unreadable, not JSON, or does not validate."""
+    path = Path(directory or members_dir()) / f'{device_name(device)}.json'
+    try:
+        return validate(_parse(path), device)
+    except FileNotFoundError:
+        return None
+    except L.LanesError as error:
+        raise L.LanesError(f'members/{path.name}: {error}') from None
+
+
+def load(directory=None):
+    """(valid records sorted by file name, [(file name, reason)] for every other *.json) — the identity part only;
+    keys.load_members adds its key checks on top."""
+    documents, problems = [], []
+    for path in sorted(Path(directory or members_dir()).glob('*.json')):
+        try:
+            documents.append(validate(_parse(path), path.stem))
+        except FileNotFoundError:
+            continue                                    # removed between the listing and the read
+        except L.LanesError as error:
+            problems.append((path.name, str(error)))
+    return documents, problems
+
+
+def owner(device, directory=None):
+    """The normalized owner members/<device>.json names, or None (no file, owner null, or anything invalid — the
+    device name included). Never raises."""
+    try:
+        document = read(device, directory)
+    except L.LanesError:
+        return None
+    return validate_owner(document.get('owner')) if document else None
+
+
+def owner_for(names, recorded=None, directory=None):
+    """The owner a view session's devices/<device>.json records (DM-LANES-DEVICE-OWNER): `names` are the device, then
+    the machine it is a window of (its `base`); `recorded` is the owner the file holds now. The first name that has a
+    member file decides — its normalized owner, None when that record names nobody (a key added by hand) — so a
+    device revoked and enrolled again by another person follows its new record, and `lanes device list` agrees with
+    `lanes keys list` (DEF-1702). While none of them has a member file (revoked, or never enrolled) the valid
+    `recorded` owner is kept, like `base`. A member file that exists but cannot be read or does not validate is no
+    evidence of another owner: the recorded one is kept and the later names are not consulted. A name no member file
+    can carry (not a device name: a corrupt base) is skipped. Never raises: create_session runs it for `lanes ensure`
+    every minute, and a broken member file must not stop a view session."""
+    kept = valid_owner(recorded)
+    seen = set()
+    for name in names:
+        if not isinstance(name, str) or name in seen:
+            continue
+        seen.add(name)
+        try:
+            device_name(name)
+        except L.LanesError:
+            continue
+        try:
+            document = read(name, directory)
+        except L.LanesError:
+            return kept
+        if document is not None:
+            return validate_owner(document.get('owner'))
+    return kept

package/payload/lanes/libexec/notify.py

@@ -25,12 +25,30 @@ NEEDS_YOU set. The six-word `state` is never read: the agent status is the only
   * A failed send is one journal line (lane id and the failure class — never the topic or the bearer) and is not
     retried; it never stops the service.
 
-Config `~/.config/lanes/notify.conf` (`LANES_NOTIFY_CONF` overrides the path), `key=value` lines, `#` comments,
-re-read when its mtime changes: `url` (ntfy server, http/https, required), `topic` (`[A-Za-z0-9_-]{1,64}`,
-required), `token_file` (a file holding an ntfy access token, optional — sent as a bearer, never logged; an
-unreadable one disables sending rather than sending unauthenticated), `quiet_when_device_active_s` (default 120;
-0 never suppresses), `action_url` (optional template, e.g. `https://lanes.example/?lane={lane}`). Without a valid
-`url` and `topic` the service only tracks transitions and sends nothing.
+Enrolment requests (W8 A5, LNS-44): the same service also watches `STATE/enrol-requests/` (lanes-enrold's store;
+read through `enrold.load_requests`, so a request announced is one `lanes enrol list` shows). A request that is
+pending — not approved, denied or past `expires_at` — and has not been announced yet yields ONE push:
+`{title: 'Enrol request', message: '<name or login> · <device>\\nlanes enrol approve <id>', priority: 4}`.
+  * No presence suppression: someone is waiting at an installer for a member to approve them, so a desk device in
+    use never mutes it. Nothing about it is retried: a failed send is one journal line naming the request id.
+  * Once per request id, across restarts: the ids announced are kept in `STATE/notify.enrol-seen.json`
+    (`{version: 1, announced: [...]}`, 0600), pruned to the requests still on disk. An id is recorded before its
+    push is sent (at most once). A missing or damaged file is no record: requests still pending are announced again.
+  * Without a valid `url` and `topic` (or with a `token_file` that cannot be read) nothing is announced and nothing
+    is recorded, so the requests still pending when the config becomes valid are announced then — whichever of
+    notify.conf and the token file is written last (see the config paragraph below).
+  * The directory is re-read when its mtime changes, when the config changes, and on the tick after one that saw a
+    directory changed within SETTLE_S seconds (a write in the same kernel clock tick as the read leaves the mtime
+    unchanged).
+
+Config `~/.config/lanes/notify.conf` (`LANES_NOTIFY_CONF` overrides the path), `key=value` lines, `#` comments:
+`url` (ntfy server, http/https, required), `topic` (`[A-Za-z0-9_-]{1,64}`, required), `token_file` (a file holding
+an ntfy access token, optional — sent as a bearer, never logged; an unreadable one disables sending rather than
+sending unauthenticated), `quiet_when_device_active_s` (default 120; 0 never suppresses), `action_url` (optional
+template, e.g. `https://lanes.example/?lane={lane}`). Without a valid `url` and `topic` the service only tracks
+transitions and sends nothing. The config is re-read when notify.conf OR its `token_file` changes (inode, size,
+mtime or ctime, so a token written, rotated, removed or chmod-ed after notify.conf counts), and on every tick while
+sending is disabled, so a token that becomes readable switches the pushes on within one interval.
 
 Answering a `PermissionRequest`-held approval FROM the phone needs a request/response channel back into the hook;
 that is a follow-up design, not part of this module.
@@ -48,6 +66,7 @@ import urllib.request
 from pathlib import Path
 
 sys.path.insert(0, str(Path(__file__).resolve().parent))
+import enrold as E  # noqa: E402
 import lanes_lib as L  # noqa: E402
 import tokens  # noqa: E402
 
@@ -64,12 +83,22 @@ TIMEOUT = 5
 PRESENCE = '*.pid'                                        # clients/ files only `lanes attach` writes
 SEEN = '.seen.json'                                       # a sidebar's opened-lane record; desk devices only
                                                           # (a .pid of any age, devices/<device>.json not mobile)
+ENROL_DIR = 'enrol-requests'                              # STATE/<this>/<id>.json: lanes-enrold's requests
+ENROL_SEEN = 'notify.enrol-seen.json'                     # STATE/<this>: the request ids already announced
+ENROL_TITLE = 'Enrol request'
+ENROL_PRIORITY = 4
+SETTLE_S = 2                                              # a directory changed this recently is read again
 
 
 def _text(value):
     return UNSAFE.sub('', str(value or ''))
 
 
+def _line(text):
+    """One payload line, at most TEXT_MAX characters."""
+    return text if len(text) <= TEXT_MAX else text[:TEXT_MAX - 1] + '…'
+
+
 def read_config(path):
     """notify.conf -> {url, topic, token_file, token, quiet_when_device_active_s, action_url, enabled}. Never raises."""
     raw = {}
@@ -171,9 +200,7 @@ def _note(lane_id, status, agent, names, config):
     label = LABELS.get(status, status)
     name = _text(names.get(lane_id) or lane_id)
     task = _text(agent.get('name'))
-    first = f'{name}: {task} — {label}' if task else f'{name} — {label}'
-    if len(first) > TEXT_MAX:
-        first = first[:TEXT_MAX - 1] + '…'
+    first = _line(f'{name}: {task} — {label}' if task else f'{name} — {label}')
     note = {'lane': lane_id, 'status': status, 'title': label,
             'message': f'{first}\nlanes-launch lane {lane_id}', 'priority': PRIORITY.get(status, 3)}
     template = config.get('action_url') or ''
@@ -203,6 +230,29 @@ def notify_changes(prev_status, new_status, config, names=None, now=None, client
     return [_note(lane_id, status, lanes[lane_id]['agent'], names, config) for lane_id, status in sorted(changed)]
 
 
+def enrol_notes(requests, announced, now):
+    """The pushes for enrolment requests that are pending at `now` (not approved, denied or expired) and whose id is
+    not in `announced`, in `requests` order (enrold.load_requests: oldest first). Never presence-suppressed."""
+    notes = []
+    for request in requests:
+        if request['id'] in announced or E.request_state(request, now) != 'pending':
+            continue
+        who = _text(request.get('name') or request.get('login'))
+        first = _line(f"{who} · {_text(request.get('device'))}")
+        notes.append({'request': request['id'], 'title': ENROL_TITLE,
+                      'message': f"{first}\nlanes enrol approve {request['id']}", 'priority': ENROL_PRIORITY})
+    return notes
+
+
+def read_announced(path):
+    """notify.enrol-seen.json -> the set of request ids already announced; missing or damaged = none."""
+    document = L.read_json(path)
+    ids = document.get('announced') if isinstance(document, dict) else None
+    if not isinstance(ids, list):
+        return set()
+    return {value for value in ids if isinstance(value, str) and E._REQUEST_ID.fullmatch(value)}
+
+
 class _NoRedirect(urllib.request.HTTPRedirectHandler):
     def redirect_request(self, *_args, **_kwargs):   # a redirect would carry the bearer elsewhere: refuse it
         return None
@@ -214,7 +264,8 @@ def default_opener():
 
 def send(note, config, opener=None):
     """POST one notification as ntfy JSON to `config['url']`. True when the server accepted it. Any failure is one
-    stderr (journal) line naming the lane and the failure class — never the topic or the bearer — and False."""
+    stderr (journal) line naming the lane (or the enrolment request id) and the failure class — never the topic or
+    the bearer — and False."""
     body = {'topic': config['topic'], 'title': note['title'], 'message': note['message'],
             'priority': note.get('priority', 3)}
     for key in ('click', 'actions'):
@@ -240,13 +291,38 @@ def send(note, config, opener=None):
         why = type(error).__name__
     except Exception as error:   # a push must never stop the service
         why = type(error).__name__
-    print(f'notify: send failed for {note.get("lane")}: {why}', file=sys.stderr, flush=True)
+    what = note.get('lane') or f"enrol request {note.get('request')}"
+    print(f'notify: send failed for {what}: {why}', file=sys.stderr, flush=True)
     return False
 
 
+def _settling(path, now):
+    """True when `path` changed within SETTLE_S seconds of `now` (its mtime may still move within this clock tick)."""
+    try:
+        return now - path.stat().st_mtime < SETTLE_S
+    except OSError:
+        return False
+
+
+def _stamp(path):
+    """What the watcher compares to decide a file changed: the path, device, inode, size, mtime and ctime. A
+    replacement moves the inode, an in-place rewrite within one clock tick moves the size, and a chmod, chown or ACL
+    change (which can make a file readable) moves only the ctime. None for no path; (path,) when it cannot be
+    stat'ed."""
+    if path is None:
+        return None
+    try:
+        info = os.stat(path)
+    except OSError:
+        return (str(path),)
+    return (str(path), info.st_dev, info.st_ino, info.st_size, info.st_mtime_ns, info.st_ctime_ns)
+
+
 class Watcher:
-    """Tails status.json by mtime; sends what notify_changes returns. The config and registry are re-read when
-    their mtime changes. The first readable document seeds the previous one."""
+    """Tails status.json (re-read when its _stamp changes); sends what notify_changes returns. The registry is re-read
+    when it changes; the config when notify.conf or its token_file changes, and on every tick while it is disabled.
+    The first readable document seeds the previous one. Also announces each new pending enrolment request once
+    (enrol_notes; the ids announced persist in STATE/notify.enrol-seen.json)."""
 
     def __init__(self, state, conf_path, opener=None, clock=time.time):
         self.state = Path(state)
@@ -254,24 +330,45 @@ class Watcher:
         self.opener, self.clock = opener, clock
         self.prev = None
         self.stamps = {}
-        self.config = read_config(self.conf_path)
+        self.config = None
         self.names = {}
+        self.enrol_due = True
+        self.announced = read_announced(self.state / ENROL_SEEN)
+        self._config_tick()
 
     def _changed(self, key, path):
-        try:
-            stamp = path.stat().st_mtime_ns
-        except OSError:
-            stamp = None
+        stamp = _stamp(path)
         if self.stamps.get(key, 'unset') == stamp:
             return False
         self.stamps[key] = stamp
         return True
 
+    def _token_path(self):
+        name = (self.config or {}).get('token_file')
+        return Path(os.path.expanduser(name)) if name else None
+
+    def _config_tick(self):
+        """Re-read the config when notify.conf or the token_file it names changed (both are stamped BEFORE the
+        read, so a change during it is seen next tick; a token_file path that changes is stamped next tick and
+        read once more), and on every tick while sending is disabled: a token that becomes readable need not move
+        any stamp (a security policy, a mount). A config that reads differently makes the enrolment directory
+        due, so the requests still pending when it becomes valid are announced then."""
+        conf_changed = self._changed('conf', self.conf_path)
+        token_changed = self._changed('token', self._token_path())
+        if self.config is not None and self.config['enabled'] and not (conf_changed or token_changed):
+            return
+        config = read_config(self.conf_path)
+        if config != self.config:
+            self.config = config
+            self.enrol_due = True
+
     def tick(self):
-        if self._changed('conf', self.conf_path):
-            self.config = read_config(self.conf_path)
+        self._config_tick()
         if self._changed('registry', self.state / 'registry.json'):
             self.names = lane_names(L.read_json(self.state / 'registry.json'))
+        return self._status_tick() + self._enrol_tick()
+
+    def _status_tick(self):
         if not self._changed('status', self.state / 'status.json'):
             return []
         document = L.read_json(self.state / 'status.json')
@@ -286,9 +383,37 @@ class Watcher:
             send(note, self.config, self.opener)
         return notes
 
+    def _enrol_tick(self):
+        directory = self.state / ENROL_DIR
+        if not (self._changed('enrol', directory) or self.enrol_due):
+            return []
+        now = self.clock()
+        self.enrol_due = _settling(directory, now)
+        if not self.config['enabled']:
+            return []                   # nothing announced, nothing recorded
+        requests = E.load_requests(directory)
+        notes = enrol_notes(requests, self.announced, now)
+        self._record((self.announced | {note['request'] for note in notes}) & {r['id'] for r in requests})
+        for note in notes:
+            send(note, self.config, self.opener)
+        return notes
+
+    def _record(self, announced):
+        """Keep `announced` (in memory first, so a file that cannot be written never causes a repeat here)."""
+        if announced == self.announced:
+            return
+        self.announced = announced
+        text = json.dumps({'version': 1, 'announced': sorted(announced)}) + '\n'
+        try:
+            L.atomic_write_if_changed(self.state / ENROL_SEEN, text, mode=0o600)
+        except OSError as error:
+            print(f'notify: cannot record announced enrolment requests in {ENROL_SEEN}: '
+                  f'{error.strerror or type(error).__name__}', file=sys.stderr, flush=True)
+
 
 def main(argv=None):
-    parser = argparse.ArgumentParser(prog='notify', description='push needs-you transitions to an ntfy topic')
+    parser = argparse.ArgumentParser(prog='notify', description='push needs-you transitions and new enrolment '
+                                                                'requests to an ntfy topic')
     parser.add_argument('--interval', type=float, default=3.0, help='seconds between status.json checks')
     parser.add_argument('--test', action='store_true', help='send one test notification and exit (1 = not sent)')
     args = parser.parse_args(argv)