@vibelord/lanes 1.0.4 → 1.1.0

package/payload/lanes/libexec/enrol.py

@@ -0,0 +1,695 @@
+"""lanes invite | enrol | offboard — the operator's half of W8 enrolment (A4, LNS-43). bin/lanes loads this module
+through libexec_module('enrol'); the enrolment service itself is enrold.py (A3), whose store helpers, code hash and
+decide() this module calls, so the CLI and the service agree on one definition of each.
+
+  lanes invite <name> [--email ADDR] [--expires 7d] [--workspaces a,b] [--tailscale-link URL] [--md]
+      mints a one-time code `LN-<id4>-<secret12>` over enrold.CODE_ALPHABET (31 characters, no 0/1/i/l/o; ~59 bits of
+      secret from the `secrets` module; case-insensitive) and stores ONLY its hash in invites/<id>.json:
+          {id, code_sha256, minted_at, minted_by {device, login, unix_user}, expires_at, name, email, workspaces,
+           redeemed_by: null, revoked_at: null}
+      `minted_by.device` is $LANES_DEVICE when it is a device name (a claim: nothing sets it today), `login` is null —
+      over SSH the one Unix account names nobody, so the CLI never claims a tailnet login — and `unix_user` the
+      account. The code is shown once, in the welcome kit, and only when stdin AND stdout are terminals (otherwise
+      exit 2 and nothing is minted). `--md` prints the kit as Markdown. Two opt-in extras, each behind its OWN
+      Lanes key file (never another tool's key, never the environment):
+        --email ADDR   the invitee's address (recorded: on an invite-only server it is the member's owner login),
+                       and, with ~/.config/lanes/resend.key, the kit is sent through Resend (key on the first line;
+                       a `from=Name <addr>` line on a Resend-verified domain names the sender — without it Resend's
+                       test sender is used, which delivers only to the Resend account's own address, and Resend's
+                       403 for anyone else becomes a note naming the missing from= line)
+        step 1's link  --tailscale-link URL, else with ~/.config/lanes/tailscale-api.key (a user-owned API access
+                       token) a Tailscale user invite is minted WITHOUT the email, so Tailscale returns the link and
+                       sends nothing itself: the kit stays the one message
+      Every request is bounded (HTTP_TIMEOUT for the whole exchange); a failure is a sentence, never a lost kit.
+  lanes invite list | revoke <id>
+      every invite with its state (live, redeemed, revoked, expired); revoke sets revoked_at, after which enrold
+      answers that code like an unknown one. A redeemed invite is not revoked: `lanes offboard` removes the machine.
+  lanes enrol mode [request|invite|auto]
+      pins whether lanes-enrold takes access requests (enrold.write_mode: STATE/enrol-mode {version: 1, mode, set_at,
+      set_by}; auto removes it), read by the service on every request — no restart, and it survives restarts and
+      reinstalls, so request mode no longer rests on which request arrives first after a start (DEF-1725). Without a
+      word it says the pin. A unit drop-in's LANES_ENROL_REQUEST_MODE wins over the pin: said when systemd reports one.
+  lanes enrol list [--all] | approve <id> [--as <device>] | deny <id> [--as <device>]
+      the requests enrold's POST /request filed; approve/deny call enrold.decide() exactly as /enrol/pending does
+      (approve writes the member and its line through keys.py). The approver recorded is `cli[:<device>]@<address>`:
+      the SSH client address from $SSH_CLIENT (`local` without one, `unknown` when it is not an address) and the
+      member device `--as` claims. That is where the approval came from, not who made it — every SSH login is the
+      same account — and it is never a tailnet login, so it grants nothing on /enrol/pending.
+  lanes offboard <device> --yes
+      in your own terminal only: 1. keys revoke (the managed block, then members/<device>.json), 2. device forget
+      (devices/<device>.json, so `lanes ensure` does not bring the view back), 3. its browsers and phones signed out:
+      the web login tokens web-tokens.json attributes to <device>, to its windows (devices/<view>.json `base`) or to
+      a view minted with <device> as its machine (`lanes-launch web phone|laptop`), revoked through web_tokens.offboard
+      in the pinned token environment (zellij 0.45.1 names every token token_<n>: the record says whose it is),
+      4. the view session ends (no lane is touched). A failed step 1 or 2 stops there; a failed step 3 or a view that
+      cannot be ended makes the offboard incomplete (exit 1), and running it again finishes it. Steps 2-4 are
+      bin/lanes's (the zellij helpers and `lanes device forget`), handed in as callables.
+
+Every change to invites/ holds keys.members_lock() — the lock enrold and `lanes keys` hold — so a revoke and a
+redemption never interleave. enrol.log (enrold.audit) gains `invite`, `invite-revoke` and `offboard` lines; a code is
+never written anywhere.
+"""
+import ipaddress
+import json
+import os
+import pwd
+import re
+import secrets
+import shutil
+import sys
+import threading
+import time
+import urllib.error
+import urllib.request
+from pathlib import Path
+
+import lanes_lib as L
+import keys as K
+import members as M
+import enrold as E
+
+CODE_PREFIX = 'LN'
+ID_LENGTH = 4
+SECRET_LENGTH = 12
+DEFAULT_EXPIRES = 7 * 86400
+MIN_EXPIRES = 3600
+MAX_EXPIRES = 30 * 86400
+HTTP_TIMEOUT = 10                 # seconds for a whole Resend or Tailscale exchange
+MAX_RESPONSE = 64 * 1024
+MAX_KEY_FILE = 4096
+NOT_A_TERMINAL = 2
+RESEND_URL = 'https://api.resend.com/emails'
+RESEND_SENDER = 'Lanes <onboarding@resend.dev>'     # Resend's test sender: delivers to the Resend account's own address
+RESEND_SUBJECT = 'Your Lanes invite'
+TAILSCALE_INVITES_URL = 'https://api.tailscale.com/api/v2/tailnet/-/user-invites'
+NO_LINK = 'ask your admin for the Tailscale invite'
+INVITE_USAGE = ('usage: lanes invite <name> [--email ADDR] [--expires 7d] [--workspaces a,b] [--tailscale-link URL] '
+                '[--md] | lanes invite list | lanes invite revoke <id>')
+ENROL_USAGE = ('usage: lanes enrol list [--all] | lanes enrol approve <id> [--as <device>] | '
+               'lanes enrol deny <id> [--as <device>] | lanes enrol mode [request|invite|auto]')
+UNIT_ENVIRONMENT = ['systemctl', '--user', 'show', '-p', 'Environment', 'lanes-enrold.service']
+OFFBOARD_USAGE = 'usage: lanes offboard <device> --yes'
+VALUE_OPTIONS = ('--email', '--expires', '--workspaces', '--tailscale-link')
+_EXPIRES = re.compile(r'([1-9][0-9]{0,3})([dh])', re.ASCII)
+_LINK = re.compile(r'https://[A-Za-z0-9._~:/?#@!$&+,;=%-]{1,500}', re.ASCII)
+_KEY = re.compile(r'[\x21-\x7e]{8,512}', re.ASCII)
+_MARKDOWN = re.compile(r'([\\`*_\[\]<>|])')
+
+
+# ------------------------------------------------------------------------------------------------------- basics
+
+def _on_terminal():
+    try:
+        return sys.stdin.isatty() and sys.stdout.isatty()
+    except (AttributeError, ValueError):
+        return False
+
+
+def _note(text):
+    print(text, file=sys.stderr, flush=True)
+
+
+def _pick(length):
+    return ''.join(secrets.choice(E.CODE_ALPHABET) for _ in range(length))
+
+
+def _shown(value, check):
+    """`value` as check() normalizes it for a terminal, '-' for none, '?' for anything check refuses."""
+    if value is None:
+        return '-'
+    try:
+        return check(value) or '-'
+    except (L.LanesError, TypeError, AttributeError):
+        return '?'
+
+
+def _name(value):
+    return M.validate_owner({'login': 'x', 'name': value})['name']
+
+
+def _email(value):
+    return M.validate_owner({'login': 'x', 'email': value})['email']
+
+
+def _stamp_shown(value):
+    return value if E.parse_stamp(value) is not None else '?'
+
+
+# ------------------------------------------------------------------------------------------------------- invites
+
+def parse_expires(text):
+    """`7d` / `12h` -> seconds, between MIN_EXPIRES and MAX_EXPIRES."""
+    found = _EXPIRES.fullmatch(text or '')
+    seconds = int(found.group(1)) * (86400 if found.group(2) == 'd' else 3600) if found else 0
+    if not MIN_EXPIRES <= seconds <= MAX_EXPIRES:
+        raise L.LanesError('--expires takes <n>d or <n>h, from 1h to 30d')
+    return seconds
+
+
+def valid_for(seconds):
+    return f'{seconds // 86400} d' if seconds % 86400 == 0 else f'{seconds // 3600} h'
+
+
+def check_name(value):
+    try:
+        name = _name(L._title(value))
+    except L.LanesError:
+        name = None
+    if not name:
+        raise L.LanesError('the invitee name is not valid (one printable line of at most 128 characters)')
+    return name
+
+
+def check_email(value):
+    try:
+        email = _email(value)
+    except L.LanesError:
+        email = None
+    if not email or not E._address(email):
+        raise L.LanesError('--email is not an address')
+    return email
+
+
+def check_workspaces(value):
+    kept = []
+    for part in (value or '').split(','):
+        part = part.strip()
+        if not part:
+            continue
+        if not L.IDENT.match(part) or len(part) > M.MAX_ID:
+            raise L.LanesError('--workspaces takes board ids separated by commas (`lanes workspaces` lists them)')
+        if part not in kept:
+            kept.append(part)
+    return kept
+
+
+def check_link(value):
+    if not isinstance(value, str) or not _LINK.fullmatch(value):
+        raise L.LanesError('--tailscale-link takes the https:// invite link from the Tailscale admin console')
+    return value
+
+
+def minted_by():
+    device = os.environ.get('LANES_DEVICE')
+    try:
+        device = M.device_name(device) if device else None
+    except L.LanesError:
+        device = None
+    try:
+        user = pwd.getpwuid(os.getuid()).pw_name
+    except KeyError:
+        user = None
+    return {'device': device, 'login': None, 'unix_user': user}
+
+
+def mint(name, email=None, workspaces=(), expires=DEFAULT_EXPIRES, now=None):
+    """Store a new invite -> (code, document). The code exists only in the return value: the file holds its hash."""
+    now = time.time() if now is None else now
+    with K.members_lock():
+        E._private_dir(E.invites_dir())
+        for _ in range(1000):
+            invite_id = _pick(ID_LENGTH)
+            if not (E.invites_dir() / f'{invite_id}.json').exists():
+                break
+        else:
+            raise L.LanesError('no free invite id: clear out old invites/ files')
+        code = f'{CODE_PREFIX}-{invite_id}-{_pick(SECRET_LENGTH)}'
+        document = {'id': invite_id, 'code_sha256': E.code_sha256(code), 'minted_at': E.stamp(now),
+                    'minted_by': minted_by(), 'expires_at': E.stamp(now + expires), 'name': name, 'email': email,
+                    'workspaces': list(workspaces), 'redeemed_by': None, 'revoked_at': None}
+        L.atomic_write(E.invites_dir() / f'{invite_id}.json', E._json_bytes(document), mode=0o600)
+    E.audit('invite', invite_id, None, None, None, 'minted', now)
+    return code, document
+
+
+def kit_text(name, valid, code, link):
+    return (f'Invite for {name} — valid {valid}, one redemption\n'
+            f' 1. Join the tailnet (laptop and phone):  {link or NO_LINK}\n'
+            f' 2. On your Mac/Linux:  npx @vibelord/lanes --invite {code}\n'
+            ' 3. Then:  lanes-launch · lanes-launch web phone · lanes-launch web laptop\n'
+            'Takes ~5 min.\n')
+
+
+def kit_markdown(name, valid, code, link):
+    escaped = _MARKDOWN.sub(r'\\\1', name)           # Markdown's own characters in a name show as written
+    step = f'<{link}>' if link else NO_LINK
+    return (f'**Invite for {escaped}** — valid {valid}, one redemption\n\n'
+            f'1. Join the tailnet (laptop and phone): {step}\n'
+            f'2. On your Mac/Linux: `npx @vibelord/lanes --invite {code}`\n'
+            '3. Then: `lanes-launch` · `lanes-launch web phone` · `lanes-launch web laptop`\n\n'
+            'Takes ~5 min.\n')
+
+
+# --------------------------------------------------------------------------------------------- opt-in extras
+
+def read_key_file(path):
+    """(key, settings) from a Lanes-owned key file — the key on the first line that is neither blank, a `#` comment
+    nor `name=value`; `from=…` and other settings beside it — or (None, {}) when there is no file. Raises
+    L.LanesError, never echoing the file, when it holds no usable key. Warns when others can read it."""
+    try:
+        mode = path.stat().st_mode
+        with open(path, encoding='utf-8') as handle:
+            text = handle.read(MAX_KEY_FILE)
+    except FileNotFoundError:
+        return None, {}
+    except (OSError, UnicodeDecodeError) as error:
+        raise L.LanesError(f'cannot read {path} ({getattr(error, "strerror", None) or error.__class__.__name__})')
+    if mode & 0o077:
+        _note(f'⚠ {path} can be read by other accounts: chmod 600 {path}')
+    key, settings = None, {}
+    for line in text.splitlines():
+        line = line.strip()
+        if not line or line.startswith('#'):
+            continue
+        if re.match(r'[a-z_]+=', line):
+            settings[line.split('=', 1)[0]] = line.split('=', 1)[1].strip()
+        elif key is None:
+            key = line
+    if key is None or not _KEY.fullmatch(key):
+        raise L.LanesError(f'{path} holds no usable key (one line, no blanks)')
+    return key, settings
+
+
+def post_json(url, key, payload):
+    """POST `payload` as JSON with `Authorization: Bearer <key>` -> (status | None, document | None, reason). The
+    whole exchange runs in a daemon thread that is waited for HTTP_TIMEOUT seconds at most (urlopen's own timeout
+    bounds each socket operation, not the total). Never raises; `reason` never holds the key or the response body."""
+    timeout = HTTP_TIMEOUT
+    request = urllib.request.Request(url, data=json.dumps(payload).encode('utf-8'), method='POST', headers={
+        'Authorization': f'Bearer {key}', 'Content-Type': 'application/json', 'Accept': 'application/json',
+        'User-Agent': f'lanes/{E.version()}'})
+    result = {}
+
+    def exchange():
+        try:
+            with urllib.request.urlopen(request, timeout=timeout) as response:
+                result['status'] = response.status
+                result['body'] = response.read(MAX_RESPONSE)
+        except urllib.error.HTTPError as error:
+            result['status'] = error.code
+            error.close()
+        except urllib.error.URLError as error:
+            result['reason'] = f'connection failed: {E._log_field(getattr(error, "reason", error))[:80]}'
+        except Exception as error:                  # noqa: BLE001 — an optional extra never costs the kit
+            result['reason'] = f'connection failed: {error.__class__.__name__}'
+
+    worker = threading.Thread(target=exchange, name='lanes-invite-http', daemon=True)
+    worker.start()
+    worker.join(timeout)
+    if worker.is_alive():
+        return None, None, f'no answer in {timeout:g} s'
+    status = result.get('status')
+    if status is None:
+        return None, None, result.get('reason', 'connection failed')
+    try:
+        document = json.loads(result.get('body', b'').decode('utf-8'))
+    except (UnicodeDecodeError, ValueError):
+        document = None
+    return status, document, f'HTTP {status}'
+
+
+def tailscale_link():
+    """(link | None, note): a Tailscale user invite minted with ~/.config/lanes/tailscale-api.key, without the
+    invitee's email (Tailscale then returns `inviteUrl` and sends nothing; it omits the URL for an address in the
+    tailnet's own domain), so the kit is the one message."""
+    path = Path.home() / '.config/lanes/tailscale-api.key'
+    try:
+        key, _settings = read_key_file(path)
+    except L.LanesError as error:
+        return None, f'Tailscale invite: not minted ({error}) — step 1 asks the admin'
+    if key is None:
+        return None, (f'Tailscale invite: no {path} — step 1 asks the admin; paste a console invite with '
+                      '--tailscale-link, or put a user-owned API access token there')
+    status, document, reason = post_json(TAILSCALE_INVITES_URL, key, [{'role': 'member'}])
+    first = document[0] if status == 200 and isinstance(document, list) and document else None
+    link = first.get('inviteUrl') if isinstance(first, dict) else None
+    if isinstance(link, str) and _LINK.fullmatch(link):
+        return link, 'Tailscale invite: minted (api.tailscale.com) — the link is step 1'
+    why = reason if status != 200 else 'no invite link in the answer'
+    return None, f'Tailscale invite: not minted ({why}) — step 1 asks the admin'
+
+
+def email_kit(address, text):
+    """-> note: the kit sent to `address` through Resend with ~/.config/lanes/resend.key, or why it was not. Resend
+    answers 403 both when its test sender (no from= line) writes to anyone but the account's own address and when a
+    from= sender's domain is not verified (resend.com/docs/api-reference/errors), so a 403 note names the from= line
+    that decides it; the response body is never read or echoed."""
+    path = Path.home() / '.config/lanes/resend.key'
+    try:
+        key, settings = read_key_file(path)
+    except L.LanesError as error:
+        return f'email: not emailed ({error}) — send the kit yourself'
+    if key is None:
+        return f'email: not emailed — no {path}; send the kit yourself'
+    sender = settings.get('from') or RESEND_SENDER
+    if len(sender) > M.MAX_LOGIN or M.unsafe(sender) or '@' not in sender:
+        return f'email: not emailed — the from= line in {path} is not a sender; send the kit yourself'
+    status, _document, reason = post_json(RESEND_URL, key, {'from': sender, 'to': [address],
+                                                            'subject': RESEND_SUBJECT, 'text': text})
+    if status in (200, 201, 202):
+        return f'email: emailed to {address} (Resend)'
+    if status == 403 and not settings.get('from'):
+        return (f"email: not emailed ({reason}) — with no from= line the kit goes from Resend's test sender, which "
+                f"delivers only to the Resend account's own address: add a `from=Name <addr>` line on a domain "
+                f'verified in Resend to {path} (or check the key is active); send the kit yourself')
+    if status == 403:
+        return (f'email: not emailed ({reason}) — the from= sender in {path} must be on a domain verified in Resend '
+                '(or check the key is active); send the kit yourself')
+    return f'email: not emailed ({reason}) — send the kit yourself'
+
+
+# ----------------------------------------------------------------------------------------------- `lanes invite`
+
+def parse_invite(args):
+    options, words, i = {}, [], 0
+    while i < len(args):
+        arg = args[i]
+        if arg in VALUE_OPTIONS:
+            if arg in options or i + 1 >= len(args):
+                raise L.LanesError(INVITE_USAGE)
+            options[arg] = args[i + 1]
+            i += 2
+            continue
+        if arg == '--md':
+            if arg in options:
+                raise L.LanesError(INVITE_USAGE)
+            options[arg] = True
+        elif arg.startswith('-'):
+            raise L.LanesError(INVITE_USAGE)
+        else:
+            words.append(arg)
+        i += 1
+    if len(words) != 1:
+        raise L.LanesError(INVITE_USAGE)
+    return {'name': check_name(words[0]),
+            'email': check_email(options['--email']) if '--email' in options else None,
+            'expires': parse_expires(options['--expires']) if '--expires' in options else DEFAULT_EXPIRES,
+            'workspaces': check_workspaces(options.get('--workspaces')),
+            'link': check_link(options['--tailscale-link']) if '--tailscale-link' in options else None,
+            'md': '--md' in options}
+
+
+def unknown_workspaces(workspaces):
+    """The ids the site catalog does not list ([] when there is no readable catalog to compare with)."""
+    try:
+        listed = {w.get('id') for w in L.read_site_json(L.workspaces_dir() / 'catalog.json')['workspaces']}
+    except (OSError, ValueError, KeyError, TypeError, AttributeError, L.LanesError):
+        return []
+    return [workspace for workspace in workspaces if workspace not in listed]
+
+
+def cmd_invite(args, now=None):
+    options = parse_invite(args)
+    if not _on_terminal():
+        _note('lanes invite: run it in your own terminal — the invite code is shown once, on a terminal only; '
+              'nothing was minted')
+        return NOT_A_TERMINAL
+    code, document = mint(options['name'], options['email'], options['workspaces'], options['expires'], now)
+    notes = [f"invite {document['id']}: stored as invites/{document['id']}.json (its hash, never the code); expires "
+             f"{document['expires_at']}; the code is shown once, here — `lanes invite revoke {document['id']}` "
+             'cancels it']
+    link = options['link']
+    if link is None:
+        link, note = tailscale_link()
+        notes.append(note)
+    valid = valid_for(options['expires'])
+    plain = kit_text(options['name'], valid, code, link)
+    print(kit_markdown(options['name'], valid, code, link) if options['md'] else plain, end='', flush=True)
+    if options['email']:
+        notes.append(email_kit(options['email'], plain))
+    elif not E._valid_login(options['name']):
+        notes.append(f"no --email, and {options['name']!r} is not a login: on an invite-only server the member is "
+                     'recorded without an owner — `lanes keys owner <device> <login>` names one later')
+    for workspace in unknown_workspaces(options['workspaces']):
+        notes.append(f'⚠ workspace {workspace} is not in the site catalog (`lanes workspaces`); recorded anyway')
+    for note in notes:
+        _note(note)
+    return 0
+
+
+def invite_state(document, now):
+    if document.get('redeemed_by') is not None:
+        return 'redeemed'
+    if document.get('revoked_at') is not None:
+        return 'revoked'
+    if E.invite_live(document, now):
+        return 'live'
+    return 'expired' if E.parse_stamp(document.get('expires_at')) is not None else 'invalid'
+
+
+def cmd_invite_list(now=None):
+    now = time.time() if now is None else now
+    invites = E.load_invites()
+    for invite_id, _path, document in invites:
+        state = invite_state(document, now)
+        line = (f"{invite_id:<6} {state:<9} {_shown(document.get('name'), _name):<24} "
+                f"{_shown(document.get('email'), _email):<28} expires {_stamp_shown(document.get('expires_at'))}")
+        if state == 'redeemed':
+            redeemed = document['redeemed_by'] if isinstance(document['redeemed_by'], dict) else {}
+            line += (f"  redeemed by {_shown(redeemed.get('device'), M.device_name)} "
+                     f"{_stamp_shown(document.get('redeemed_at'))}")
+        elif state == 'revoked':
+            line += f"  revoked {_stamp_shown(document.get('revoked_at'))}"
+        print(line)
+    if not invites:
+        print('no invites')
+    return 0
+
+
+def cmd_invite_revoke(invite_id, now=None):
+    now = time.time() if now is None else now
+    shown = invite_id.lower() if isinstance(invite_id, str) and L.IDENT.match(invite_id) else '?'
+    if shown == '?' or len(shown) > M.MAX_ID:
+        raise L.LanesError(f'no invite {shown[:M.MAX_ID]} (`lanes invite list` shows them)')
+    with K.members_lock():
+        path = E.invites_dir() / f'{shown}.json'
+        document = E._read_doc(path)
+        if document is None:
+            raise L.LanesError(f'no invite {shown} (`lanes invite list` shows them)')
+        if document.get('redeemed_by') is not None:
+            redeemed = document['redeemed_by'] if isinstance(document['redeemed_by'], dict) else {}
+            device = _shown(redeemed.get('device'), M.device_name)
+            print(f'invite {shown} was already redeemed by {device}: revoking it changes nothing — '
+                  f'`lanes offboard {device} --yes` removes that machine')
+            return 1
+        if document.get('revoked_at') is not None:
+            print(f"invite {shown} is already revoked ({_stamp_shown(document['revoked_at'])}); nothing changed")
+            return 0
+        L.atomic_write(path, E._json_bytes(dict(document, revoked_at=E.stamp(now))), mode=0o600)
+    E.audit('invite-revoke', shown, None, None, None, 'ok', now)
+    print(f'revoked invite {shown}: its code is refused from now on, like an unknown one')
+    return 0
+
+
+def invite_main(args, now=None):
+    if args[:1] == ['list']:
+        if len(args) != 1:
+            raise L.LanesError(INVITE_USAGE)
+        return cmd_invite_list(now)
+    if args[:1] == ['revoke']:
+        if len(args) != 2:
+            raise L.LanesError(INVITE_USAGE)
+        return cmd_invite_revoke(args[1], now)
+    return cmd_invite(args, now)
+
+
+# ------------------------------------------------------------------------------------------------ `lanes enrol`
+
+def ssh_source(value):
+    """The client address of an SSH session's $SSH_CLIENT (`<address> <port> <port>`), `local` without one,
+    `unknown` when it does not start with an address."""
+    if not value or not value.strip():
+        return 'local'
+    try:
+        return str(ipaddress.ip_address(value.split()[0]))
+    except ValueError:
+        return 'unknown'
+
+
+def cli_approver(as_device=None, environ=None):
+    """The `approved_by` / `decided_by` a CLI decision records: `cli[:<device>]@<address>` (see the module docstring)."""
+    environ = os.environ if environ is None else environ
+    who = f'cli:{M.device_name(as_device)}' if as_device else 'cli'
+    return f"{who}@{ssh_source(environ.get('SSH_CLIENT'))}"
+
+
+def cmd_enrol_list(show_all, now=None):
+    now = time.time() if now is None else now
+    shown = 0
+    for request in E.load_requests():
+        state = E.request_state(request, now)
+        if state != 'pending' and not show_all:
+            continue
+        shown += 1
+        print(f"{request['id']:<9} {state:<8} {request['device']:<16} {request['login']:<28} "
+              f"{K.fingerprint(request['pubkey'])}  asked {_stamp_shown(request.get('created_at'))}  expires "
+              f"{_stamp_shown(request['expires_at'])}" + (f"  {request['name']}" if request.get('name') else '')
+              + (f"  by {_shown(request.get('decided_by'), M.check_login)}" if state in ('approved', 'denied')
+                 else ''))
+    if not shown:
+        print('no pending enrolment requests' + ('' if show_all else
+                                                 ' (`lanes enrol list --all` shows the others)'))
+    return 0
+
+
+def cmd_decide(action, request_id, as_device, now=None):
+    if as_device is not None:
+        device = M.device_name(as_device)
+        members, _problems = K.load_members()
+        if device not in {member['device'] for member in members}:
+            raise L.LanesError(f'--as {device}: no member {device} (`lanes keys list` shows them); nothing changed')
+    approver = cli_approver(as_device)
+    document = E.decide(request_id, action, approver, now)
+    if action == 'approve':
+        print(f"approved {document['id']}: {document['device']} for {document['login']} "
+              f"({K.fingerprint(document['pubkey'])}) — its key is in the lanes-managed block of "
+              f'{K.authorized_keys_path()}; recorded as approved by {approver}')
+    else:
+        print(f"denied {document['id']}: {document['device']} for {document['login']}; nothing was authorized "
+              f'(recorded as denied by {approver})')
+    return 0
+
+
+def unit_forced():
+    """The LANES_ENROL_REQUEST_MODE lanes-enrold.service runs with ('0' | '1'), from `systemctl --user show -p
+    Environment` (bounded); None when it sets none or systemd cannot say. Read-only."""
+    if not shutil.which('systemctl'):
+        return None
+    rc, out, _err = L.run_bounded(UNIT_ENVIRONMENT, 10)
+    if rc != 0:
+        return None
+    found = re.search(r'(?:^Environment=|\s)LANES_ENROL_REQUEST_MODE=(\S*)', out, re.M)
+    value = found.group(1).strip().strip('"') if found else ''
+    return value if value in ('0', '1') else None
+
+
+def cmd_mode(mode, now=None):
+    """`lanes enrol mode [request|invite|auto]`: pin (or show) whether lanes-enrold takes access requests (DEF-1725)."""
+    if mode is not None:
+        setter = cli_approver()
+        document = E.write_mode(mode, setter, now)
+        E.audit('mode', None, None, setter, None, mode, now)
+        print({'request': 'pinned: request mode — lanes-enrold takes access requests (tailnet logins in its domains) '
+                          'whatever request arrives first after a start, across restarts and reinstalls',
+               'invite': 'pinned: invite only — lanes-enrold refuses every access request, whatever arrives first',
+               'auto': 'unpinned: auto — after each start, the first request through Tailscale Serve decides (a '
+                       'loopback probe does not)'}[mode]
+              + (f" ({E.mode_path()}, by {document['set_by']}); the running service reads it at its next request"
+                 if document else '; the running service reads that at its next request'))
+    else:
+        pinned, problem = E.read_mode()
+        if problem:
+            print(f'mode: invite only — {problem}; `lanes enrol mode request|invite|auto` writes it again')
+        elif pinned:
+            print(f"mode: {'request' if pinned == 'request' else 'invite only'} (pinned in {E.mode_path()})")
+        else:
+            print('mode: auto — after each start, the first request through Tailscale Serve decides; pin it once the '
+                  'Serve header check passes: lanes enrol mode request (RUNBOOK "Operator verification")')
+    forced = unit_forced()
+    if forced is not None:
+        _note(f"⚠ lanes-enrold.service sets LANES_ENROL_REQUEST_MODE={forced} (a unit drop-in), which wins over this "
+              f"pin: request mode is {'on' if forced == '1' else 'off'} — `systemctl --user edit lanes-enrold.service` "
+              'removes it, then `systemctl --user restart lanes-enrold.service`')
+    return 0
+
+
+def enrol_main(args, now=None):
+    verb, rest = (args[0], args[1:]) if args else (None, [])
+    if verb == 'list' and rest in ([], ['--all']):
+        return cmd_enrol_list(bool(rest), now)
+    if verb == 'mode' and len(rest) <= 1 and all(word in ('request', 'invite', 'auto') for word in rest):
+        return cmd_mode(rest[0] if rest else None, now)
+    if verb in E.ACTIONS:
+        if len(rest) == 1 and not rest[0].startswith('-'):
+            return cmd_decide(verb, rest[0], None, now)
+        if len(rest) == 3 and not rest[0].startswith('-') and rest[1] == '--as':
+            return cmd_decide(verb, rest[0], rest[2], now)
+    raise L.LanesError(ENROL_USAGE)
+
+
+# --------------------------------------------------------------------------------------------- `lanes offboard`
+
+def _windows_of(device):
+    """Other known devices that are windows of `device` (devices/<d>.json `base`), sorted."""
+    found = []
+    for path in sorted((L.STATE / 'devices').glob('*.json')):
+        meta = L.read_json(path)
+        if path.stem != device and isinstance(meta, dict) and meta.get('base') == device:
+            found.append(path.stem)
+    return found
+
+
+def offboard_main(args, forget, revoke_token, end_view, now=None):
+    """`lanes offboard <device> --yes`. `forget(device)` is `lanes device forget`; `revoke_token(device, windows)` and
+    `end_view(device)` -> (status, sentence) are bin/lanes's zellij steps: 'done' or 'none' is said, 'warn' is said as
+    a warning, 'failed' is a warning that leaves the offboard incomplete (exit 1; the next run finishes it)."""
+    words = [arg for arg in args if not arg.startswith('-')]
+    flags = [arg for arg in args if arg.startswith('-')]
+    if len(words) != 1 or any(flag != '--yes' for flag in flags) or len(flags) > 1:
+        raise L.LanesError(OFFBOARD_USAGE)
+    device = M.device_name(words[0])
+    if not flags or not _on_terminal():
+        _note(f'lanes offboard {device}: run it in your own terminal with --yes; it\n'
+              f'  1. revokes its key (`lanes keys revoke {device}`: the lanes-managed block of ~/.ssh/authorized_keys, '
+              f'then members/{device}.json)\n'
+              f'  2. forgets the device (`lanes device forget {device}`): `lanes ensure` stops recreating its view\n'
+              f'  3. signs its browsers and phones out: revokes the web login tokens `lanes web --token` recorded for '
+              f'{device}, its windows and the views `lanes-launch web` opened for it (`lanes token list`)\n'
+              f'  4. ends its view session {device} (no lane is touched)\n'
+              'nothing changed')
+        return NOT_A_TERMINAL
+    now = time.time() if now is None else now
+    members, _problems = K.load_members()
+    fingerprint = next((K.fingerprint(m['pubkey']) for m in members if m['device'] == device), None)
+    windows = _windows_of(device)
+    incomplete = []
+
+    print(f'1/4 key: {device}')
+    try:
+        if K.cmd_revoke(K.authorized_keys_path(), device):
+            incomplete.append('a line outside the lanes-managed block still lets the key in (above)')
+    except L.LanesError as error:
+        E.audit('offboard', None, device, None, fingerprint, 'stopped-key', now)
+        raise L.LanesError(f'offboard of {device} stopped at step 1 (its key): {error} — nothing after it ran; '
+                           f'`lanes offboard {device} --yes` again finishes it') from None
+
+    print(f'2/4 device: {device}')
+    if (L.STATE / 'devices' / f'{device}.json').exists():
+        try:
+            forget(device)
+        except (L.LanesError, OSError) as error:
+            E.audit('offboard', None, device, None, fingerprint, 'stopped-device', now)
+            raise L.LanesError(f'offboard of {device} stopped at step 2 (devices/{device}.json): '
+                               f'{getattr(error, "strerror", None) or error} — the key is revoked; '
+                               f'`lanes offboard {device} --yes` again finishes it') from None
+    else:
+        print(f'no devices/{device}.json: `lanes ensure` keeps no view for it')
+
+    print(f'3/4 web tokens: {device}' + (f" and its views {', '.join(windows)}" if windows else ''))
+    status, sentence = revoke_token(device, windows)
+    if status in ('done', 'none'):
+        print(sentence)
+    else:
+        _note(f'⚠ {sentence}')
+        if status == 'failed':
+            incomplete.append(sentence)
+
+    print(f'4/4 view: {device}')
+    status, sentence = end_view(device)
+    if status == 'failed':
+        _note(f'⚠ {sentence}')
+        incomplete.append(sentence)
+    else:
+        print(sentence)
+
+    if windows:
+        print(f"still known: {', '.join(windows)} (window{'s' if len(windows) > 1 else ''} of {device}, sharing its "
+              f'key, now revoked, and signed out above) — ' + '; '.join(f'`lanes offboard {name} --yes`'
+                                                                        for name in windows)
+              + ' ends each view')
+    E.audit('offboard', None, device, None, fingerprint, 'incomplete' if incomplete else 'ok', now)
+    if incomplete:
+        print(f'offboard of {device} incomplete: ' + '; '.join(incomplete))
+        return 1
+    print(f'offboarded {device}')
+    return 0