@vibelord/lanes 1.0.4 → 1.1.0

package/payload/lanes/libexec/keys.py

@@ -0,0 +1,644 @@
+"""lanes keys — who may log in to the workspace account, as a projection of members/<device>.json (W8 A1, LNS-40).
+
+The account's ~/.ssh/authorized_keys carries ONE managed block, re-rendered whole from
+~/.local/state/lanes/members/<device>.json on every change:
+
+    # lanes-managed BEGIN
+    # generated by `lanes keys` from ~/.local/state/lanes/members/ - change it with lanes keys, never by hand
+    restrict,pty ssh-ed25519 AAAA... lanes:<device>
+    # lanes-managed END
+
+  * Every byte outside the two marker lines is kept exactly: the file is read and written as bytes. Only
+    `lanes keys adopt` removes lines outside the block — the plain `lanes:<device>` ed25519 lines it moves in, after
+    keeping a `authorized_keys.bak-<UTC>Z` copy of the file (first time only, the rename_registered idiom).
+  * A write happens only when the bytes change (L.atomic_write_if_changed: temp file + rename, so sshd never reads a
+    half-written file); the file is kept 0600 and ~/.ssh 0700 (sshd's StrictModes).
+  * The options come from what the client does over this key (client/ssh.stanza.in, client/lanes-launch,
+    client/lanes-upload, install.sh): a forced TTY for attach/open (`RequestTTY force`), plain commands with stdin
+    pipes and no TTY (the upload tar stream, terminfo, hello, client-config, upload-requests), and no agent, X11 or
+    port forwarding (`ForwardAgent no`, `ForwardX11 no`, no -L/-R/-W anywhere). So `restrict,pty`: `restrict` turns
+    off port, agent and X11 forwarding and ~/.ssh/rc (and every restriction OpenSSH adds to it later), `pty` gives the
+    TTY back; commands and stdin are untouched. No `command=` (the client runs a dozen different `lanes` verbs) and no
+    `from=` (the `lanes-public` fallback reaches the same sshd from the public internet with the same key).
+  * Only ssh-ed25519 keys — what the installer makes (`ssh-keygen -t ed25519 -C lanes:<device>`). The key blob is
+    checked byte for byte and the device is an identifier, so nothing but a type, a key and `lanes:<device>` can
+    reach a line (a newline or an option in a member file would otherwise be a new authorization).
+  * A member file that is unreadable or invalid is NOT rendered (fail closed) and is named on stderr: its identity
+    fields (owner, via, approver, ids, workspaces) as members.py defines them (W8 A2), its key fields as this module
+    does. The store's file I/O is members.py's; save_member checks the key before it writes.
+  * Malformed markers (one without the other, twice, END before BEGIN) refuse every write before anything — members/
+    included — is touched: fix the file by hand.
+  * The block never names a device members/ does not hold (DEF-1700): add and adopt write the record before its line,
+    revoke takes the line out of the block before it removes the record, so a failure at any step leaves at most a
+    record without a line (shut), the refusal says what it left, and the same verb run again finishes the job. revoke
+    also removes a `lanes:<device>` line it finds in the block without a valid record.
+  * Writers hold `members.lock` (flock) across the member files and the authorized_keys write; enrolment (W8 A3)
+    uses the same functions under the same lock.
+  * `lanes keys owner <device> <login> [--name NAME] [--email ADDR]` names the person behind a member (`add`/`adopt`
+    write owner null): the one change to a record's owner, and how a key added by hand makes its person an
+    `/enrol/pending` approver. It writes only the member file — the block carries no owner.
+
+`pubkey_sha256` is OpenSSH's own fingerprint form (`SHA256:` + unpadded base64 of the blob's SHA-256): what
+`ssh-keygen -lf` prints and what sshd logs on `Accepted publickey`, so a log line names its device.
+"""
+import base64
+import binascii
+import contextlib
+import fcntl
+import hashlib
+import os
+import re
+import struct
+import sys
+import time
+from pathlib import Path
+
+import lanes_lib as L
+import members as M
+
+BEGIN = '# lanes-managed BEGIN'
+END = '# lanes-managed END'
+NOTE = '# generated by `lanes keys` from ~/.local/state/lanes/members/ - change it with lanes keys, never by hand'
+OPTIONS = 'restrict,pty'
+KEY_TYPE = 'ssh-ed25519'
+MAX_DEVICE = M.MAX_DEVICE       # bin/lanes device_name()
+MAX_PUBKEY_FILE = 8192
+LOCK_TIMEOUT = 5
+USAGE = ('usage: lanes keys list | lanes keys add <device> <pubkey-file|-> | lanes keys revoke <device> | '
+         'lanes keys adopt [--dry-run] | lanes keys owner <device> <login> [--name NAME] [--email ADDR]')
+_ED25519_HEAD = struct.pack('>I', len(KEY_TYPE)) + KEY_TYPE.encode() + struct.pack('>I', 32)
+_BASE64 = re.compile(r'[A-Za-z0-9+/]+={0,2}')
+_KEY_TYPE_WORD = re.compile(r'(?:ssh-|ecdsa-|sk-)[A-Za-z0-9@._-]+')
+_LANES_COMMENT = re.compile(r'lanes:(\S+)')
+
+
+# ------------------------------------------------------------------------------------------------- keys and lines
+
+device_name = M.device_name
+
+
+def _ed25519_blob(text):
+    """The decoded key blob when `text` is the canonical base64 of an ssh-ed25519 public key (string "ssh-ed25519",
+    then a string of exactly 32 bytes, nothing after), else None."""
+    if not isinstance(text, str) or not _BASE64.fullmatch(text):
+        return None
+    try:
+        blob = base64.b64decode(text, validate=True)
+    except (binascii.Error, ValueError):
+        return None
+    if len(blob) != len(_ED25519_HEAD) + 32 or not blob.startswith(_ED25519_HEAD):
+        return None
+    return blob if base64.b64encode(blob).decode() == text else None
+
+
+def parse_pubkey(text):
+    """One OpenSSH public key line (a .pub file: type, key, optional comment) -> its canonical `ssh-ed25519 <base64>`.
+    Refuses options, every other key type, a malformed key and more than one line — without echoing the input: a
+    private key pasted by mistake must reach neither a terminal nor a log."""
+    lines = [line for line in (text if isinstance(text, str) else '').splitlines()
+             if line.strip() and not line.lstrip().startswith('#')]
+    if len(lines) != 1:
+        raise L.LanesError('expected exactly one ssh-ed25519 public key line (the .pub file, never the private key)')
+    fields = lines[0].split()
+    if len(fields) < 2 or fields[0] != KEY_TYPE or _ed25519_blob(fields[1]) is None:
+        raise L.LanesError('not an ssh-ed25519 public key: only ed25519 keys are accepted (ssh-keygen -t ed25519)')
+    return f'{KEY_TYPE} {fields[1]}'
+
+
+def fingerprint(pubkey):
+    """OpenSSH's fingerprint of a canonical key: `SHA256:` + unpadded base64 (what `ssh-keygen -lf` prints)."""
+    blob = base64.b64decode(pubkey.split()[1])
+    return 'SHA256:' + base64.b64encode(hashlib.sha256(blob).digest()).decode().rstrip('=')
+
+
+def parse_line(text):
+    """One authorized_keys line -> {options, type, key, comment}, or None for a blank, comment or unparsable line.
+    Options are everything before the first unquoted blank (sshd's own rule; `\\"` escapes inside quotes)."""
+    rest = text.strip()
+    if not rest or rest.startswith('#'):
+        return None
+    options = ''
+    if not _KEY_TYPE_WORD.fullmatch(rest.split(None, 1)[0]):
+        i, quoted = 0, False
+        while i < len(rest) and (quoted or rest[i] not in ' \t'):
+            if rest[i] == '\\' and quoted and i + 1 < len(rest):
+                i += 2
+                continue
+            if rest[i] == '"':
+                quoted = not quoted
+            i += 1
+        options, rest = rest[:i], rest[i:].strip()
+    fields = rest.split(None, 2)
+    if len(fields) < 2:
+        return None
+    return {'options': options, 'type': fields[0], 'key': fields[1],
+            'comment': fields[2].strip() if len(fields) > 2 else ''}
+
+
+def _member_line(member):
+    if not isinstance(member, dict):
+        raise L.LanesError('a member must be an object')
+    device = device_name(member.get('device'))
+    pubkey = member.get('pubkey')
+    if not isinstance(pubkey, str) or '\n' in pubkey or parse_pubkey(pubkey) != pubkey:
+        raise L.LanesError(f'member {device}: pubkey is not a canonical ssh-ed25519 key')
+    return device, f'{OPTIONS} {pubkey} lanes:{device}'
+
+
+def render_block(members):
+    """The managed block as lines (no newlines), markers included: one `restrict,pty ssh-ed25519 <key> lanes:<device>`
+    per member, sorted by device. Pure; raises on any member that could put more than that on a line."""
+    return [BEGIN, NOTE, *(line for _, line in sorted(_member_line(m) for m in members)), END]
+
+
+# --------------------------------------------------------------------------------------------- the authorized_keys file
+
+def authorized_keys_path():
+    return Path.home() / '.ssh' / 'authorized_keys'
+
+
+def split_block(data):
+    """bytes -> (before, block lines with their line ends | None, after). A marker is a line that is exactly the marker
+    once surrounding blanks are stripped. Anything but no markers or one BEGIN followed by one END is refused."""
+    lines = data.splitlines(keepends=True)
+    marks = [(i, line.strip().decode('ascii', 'replace')) for i, line in enumerate(lines)
+             if line.strip() in (BEGIN.encode(), END.encode())]
+    if not marks:
+        return data, None, b''
+    if [kind for _, kind in marks] != [BEGIN, END]:
+        found = ', '.join(f'line {i + 1}: {kind}' for i, kind in marks)
+        raise L.LanesError(f'authorized_keys: the lanes-managed markers are malformed ({found}); fix the file by hand '
+                           '— nothing was written')
+    (first, _), (last, _) = marks
+    return b''.join(lines[:first]), lines[first:last + 1], b''.join(lines[last + 1:])
+
+
+def outside_entries(data):
+    """(line number, raw line bytes, parsed line) for every key line OUTSIDE the managed block."""
+    before, block, after = split_block(data)
+    entries, number = [], 0
+    for chunk, skip in ((before, 0), (after, len(block or ()))):
+        number += skip
+        for raw in chunk.splitlines(keepends=True):
+            number += 1
+            parsed = parse_line(raw.decode('utf-8', 'surrogateescape'))
+            if parsed:
+                entries.append((number, raw, parsed))
+    return entries
+
+
+def _lanes_device(parsed):
+    found = _LANES_COMMENT.fullmatch(parsed['comment'])
+    return found.group(1) if found else None
+
+
+def block_entries(data, device):
+    """The parsed key lines INSIDE the managed block whose comment is `lanes:<device>` (malformed markers raise)."""
+    _, block, _ = split_block(data)
+    parsed = (parse_line(raw.decode('utf-8', 'surrogateescape')) for raw in block or ())
+    return [entry for entry in parsed if entry and _lanes_device(entry) == device]
+
+
+def _without(chunk, drop):
+    kept, dropped = [], 0
+    for raw in chunk.splitlines(keepends=True):
+        if drop(raw):
+            dropped += 1
+        else:
+            kept.append(raw)
+    return b''.join(kept), dropped
+
+
+def compose(data, members, drop=None):
+    """(new bytes, number of outside lines dropped): `data` with its managed block re-rendered from `members` (appended
+    at the end when there is none and `members` is not empty). `drop(raw line) -> bool` removes outside lines (adopt
+    only); every other byte outside the block is kept."""
+    before, block, after = split_block(data)
+    dropped = 0
+    if drop:
+        before, d1 = _without(before, drop)
+        after, d2 = _without(after, drop)
+        dropped = d1 + d2
+    if block is None and not members:
+        return before + after, dropped
+    if block is None and before and not before.endswith((b'\n', b'\r')):
+        before += b'\n'       # the BEGIN marker never joins a foreign line
+    return before + ('\n'.join(render_block(members)) + '\n').encode() + after, dropped
+
+
+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_authorized_keys(path, members, drop=None):
+    """Re-render the managed block of `path` from `members` -> True when the file's bytes changed. Byte-exact outside
+    the markers, atomic, and only on a change; ~/.ssh is made 0700 and the file 0600 (also when nothing else changes).
+    A symlinked file is written through, the link stays. With `drop` (adopt), a backup of the previous bytes is kept
+    first, once, beside the file."""
+    path = Path(path)
+    target = Path(os.path.realpath(path))
+    try:
+        data = target.read_bytes()
+    except FileNotFoundError:
+        data = None
+    new, dropped = compose(data or b'', members, drop)    # malformed markers raise here, before anything is touched
+    if data is None and not new:
+        return False
+    _private_dir(path.parent)
+    if dropped and new != data and not any(path.parent.glob(path.name + '.bak-*')):
+        L.atomic_write(path.parent / (path.name + '.bak-' + time.strftime('%Y%m%dT%H%M%SZ', time.gmtime())),
+                       data, mode=0o600)
+    wrote = L.atomic_write_if_changed(target, new, mode=0o600)
+    if target.stat().st_mode & 0o777 != 0o600:
+        os.chmod(target, 0o600)
+    return wrote
+
+
+def _read(path):
+    try:
+        return Path(path).read_bytes()
+    except FileNotFoundError:
+        return b''
+
+
+def _reason(error):
+    return error.strerror or error.__class__.__name__
+
+
+def _project(path, members, left, drop=None):
+    """write_authorized_keys, with an OSError (a read-only mount, a full disk) turned into a refusal that says what
+    the failure `left` behind and how to finish — the caller has already changed members/ only in the direction that
+    keeps the block a subset of it."""
+    try:
+        return write_authorized_keys(path, members, drop=drop)
+    except OSError as error:
+        raise L.LanesError(f'cannot write {path} ({_reason(error)}): {left()}') from None
+
+
+# ----------------------------------------------------------------------------------------------------- members store
+
+members_dir = M.members_dir
+
+
+@contextlib.contextmanager
+def members_lock(timeout=None):
+    """Serialize every change to members/ and the managed block (CLI and enrolment)."""
+    timeout = LOCK_TIMEOUT if timeout is None else timeout
+    L.STATE.mkdir(parents=True, exist_ok=True)
+    with (L.STATE / 'members.lock').open('a') as handle:
+        deadline = time.monotonic() + timeout
+        while True:
+            try:
+                fcntl.flock(handle, fcntl.LOCK_EX | fcntl.LOCK_NB)
+                break
+            except BlockingIOError:
+                if time.monotonic() >= deadline:
+                    raise L.LanesError('another change to members/ or authorized_keys is running; try again shortly')
+                time.sleep(0.05)
+        try:
+            yield
+        finally:
+            fcntl.flock(handle, fcntl.LOCK_UN)
+
+
+def load_members(directory=None):
+    """(members sorted by device, [(file name, reason)] for each file NOT rendered). A member is a record whose identity
+    fields members.validate accepts (a JSON object whose `device` is its file's stem and a device name, whose owner,
+    via, approver, ids and workspaces are well formed), whose `pubkey` is a canonical ssh-ed25519 key, whose
+    `pubkey_sha256` (when set) is that key's fingerprint, and whose key no earlier member holds."""
+    documents, problems = M.load(directory or members_dir())
+    members, holders = [], {}
+    for document in documents:
+        try:
+            _member_line(document)
+            if document.get('pubkey_sha256') not in (None, fingerprint(document['pubkey'])):
+                raise L.LanesError('pubkey_sha256 is not the fingerprint of its key')
+            if document['pubkey'] in holders:
+                raise L.LanesError(f"the same key as member {holders[document['pubkey']]}")
+        except L.LanesError as error:
+            problems.append((f"{document['device']}.json", str(error)))
+            continue
+        holders[document['pubkey']] = document['device']
+        members.append(document)
+    return members, sorted(problems)
+
+
+def member_record(device, pubkey, via='manual', now=None, **identity):
+    """A members/<device>.json document (members.record) with the key's fingerprint: `lanes keys add|adopt` write
+    via manual, owner null; enrolment passes owner, approved_by, its invite_id|request_id and workspaces."""
+    return M.record(device, pubkey, fingerprint(pubkey), via=via, now=now, **identity)
+
+
+def save_member(record):
+    """members.write after the key checks a load would make, so a record this module writes is one it renders."""
+    _member_line(record)
+    if record.get('pubkey_sha256') != fingerprint(record['pubkey']):
+        raise L.LanesError(f"member {record['device']}: pubkey_sha256 is not the fingerprint of its key")
+    M.write(record, members_dir())
+
+
+# ---------------------------------------------------------------------------------------------------------- verbs
+
+def _warn(text):
+    print(text, file=sys.stderr)
+
+
+def _warn_problems(problems):
+    for name, reason in problems:
+        _warn(f'⚠ members/{name}: {reason} — NOT authorized (fix or remove the file)')
+
+
+def _read_pubkey_file(name):
+    try:
+        if name == '-':
+            text = sys.stdin.read(MAX_PUBKEY_FILE + 1)
+        else:
+            with open(name) as handle:
+                text = handle.read(MAX_PUBKEY_FILE + 1)
+    except (OSError, UnicodeDecodeError) as error:
+        raise L.LanesError(f'cannot read {name}: {getattr(error, "strerror", None) or error.__class__.__name__}')
+    if len(text) > MAX_PUBKEY_FILE:
+        raise L.LanesError(f'{name} is too large to be a public key')
+    return text
+
+
+def _outside_holders(data, pubkey=None, device=None):
+    """Key lines outside the block that let `pubkey` (any comment) or `lanes:<device>` in."""
+    blob = pubkey.split()[1] if pubkey else None
+    return [(number, parsed) for number, _, parsed in outside_entries(data)
+            if (blob and parsed['type'] == KEY_TYPE and parsed['key'] == blob)
+            or (device and _lanes_device(parsed) == device)]
+
+
+def cmd_list(path):
+    members, problems = load_members()
+    data = _read(path)
+    for record in members:
+        owner = record.get('owner')
+        login = owner.get('login') if isinstance(owner, dict) else None
+        print(f"{record['device']:<16} {fingerprint(record['pubkey']):<51} {login or '-':<24} "
+              f"{record.get('via') or '-':<8} {record.get('enrolled_at') or '-'}")
+    if not members:
+        print(f'no members ({members_dir()} holds none)')
+    _warn_problems(problems)
+    try:
+        _, block, _ = split_block(data)
+        entries = outside_entries(data)
+    except L.LanesError as error:
+        print(f'⚠ {error}')
+        return 1
+    expected = render_block(members)
+    if block is None:
+        print(f'block: none in {path}' + (' — `lanes keys adopt` writes it' if members else ''))
+    elif [raw.decode('utf-8', 'replace').rstrip('\r\n') for raw in block] == expected:
+        print(f'block: {len(members)} key(s) in {path}, in sync with members/')
+    else:
+        print(f'block: out of date in {path} — `lanes keys adopt` re-renders it from members/')
+    hand = [(number, _lanes_device(parsed)) for number, _, parsed in entries if _lanes_device(parsed)]
+    if hand:
+        print(f'outside the block: {len(hand)} hand-added lanes: line(s) — '
+              + ', '.join(f'{device} (line {number})' for number, device in hand)
+              + ' — `lanes keys adopt` moves them in')
+    blobs = {record['pubkey'].split()[1]: record['device'] for record in members}
+    for number, _, parsed in entries:
+        if parsed['type'] == KEY_TYPE and parsed['key'] in blobs and not _lanes_device(parsed):
+            print(f"⚠ line {number}: {blobs[parsed['key']]}'s key also authorizes outside the block "
+                  f"({parsed['comment'] or 'no comment'}); sshd uses the first matching line")
+    return 0
+
+
+def _listed(path, device):
+    """Whether the block on disk carries a `lanes:<device>` line now: True/False, None when it cannot be read back."""
+    try:
+        return bool(block_entries(_read(path), device))
+    except (L.LanesError, OSError):
+        return None
+
+
+def cmd_add(path, device, name):
+    device = device_name(device)
+    pubkey = parse_pubkey(_read_pubkey_file(name))
+    with members_lock():
+        members, problems = load_members()
+        _warn_problems(problems)
+        split_block(_read(path))      # malformed markers refuse HERE, before members/ changes: nothing was written
+        current = next((m for m in members if m['device'] == device), None)
+        holder = next((m['device'] for m in members if m['pubkey'] == pubkey), None)
+        if current is not None and current['pubkey'] != pubkey:
+            raise L.LanesError(f"{device} is already enrolled with another key ({fingerprint(current['pubkey'])}); "
+                               f'`lanes keys revoke {device}` first')
+        if current is None and holder is not None:
+            raise L.LanesError(f'that key is already enrolled as {holder} (one key, one device)')
+        if current is None:
+            save_member(member_record(device, pubkey))     # the record before its line (see cmd_revoke)
+            members, _ = load_members()
+
+        def left():
+            state = {True: f'the block already has a line for {device}', False: f'{device} is NOT authorized',
+                     None: 'the block could not be read back'}[_listed(path, device)]
+            return (f'{state}; members/{device}.json is kept, so `lanes keys add {device}` with the same key (or '
+                    '`lanes keys adopt`) renders its line once that is fixed')
+
+        wrote = _project(path, members, left)
+    if current is None:
+        print(f'authorized {device} ({fingerprint(pubkey)}): `{OPTIONS}` line in the lanes-managed block of {path}')
+    elif wrote:
+        print(f'{device} was already a member with that key ({fingerprint(pubkey)}); the lanes-managed block of {path} '
+              f'did not match members/ and was re-rendered: it authorizes {device} now')
+    else:
+        print(f'{device} is already authorized with that key ({fingerprint(pubkey)}); nothing changed')
+    for number, parsed in _outside_holders(_read(path), pubkey=pubkey):
+        _warn(f"⚠ line {number} outside the lanes-managed block also authorizes the same key "
+              f"({parsed['comment'] or 'no comment'}) with its own options; sshd uses the first matching line — "
+              '`lanes keys adopt` moves a plain `lanes:<device>` line in, any other remove by hand')
+    return 0
+
+
+def cmd_revoke(path, device):
+    """Take `device` out of the block, then out of members/ — in that order, so a failure in between leaves a record
+    without a line (shut, named, and finished by running revoke again), never a line without a record (open, and
+    invisible to every later revoke). A `lanes:<device>` line in the block without a valid record is revoked too."""
+    device = device_name(device)
+    with members_lock():
+        members, problems = load_members()
+        _warn_problems(problems)
+        member_file = members_dir() / f'{device}.json'
+        had_file = member_file.exists()
+        target = next((m for m in members if m['device'] == device), None)
+        stale = block_entries(_read(path), device)      # malformed markers refuse HERE: nothing was written
+        pubkey = target['pubkey'] if target else next(
+            (f"{KEY_TYPE} {entry['key']}" for entry in stale
+             if entry['type'] == KEY_TYPE and _ed25519_blob(entry['key']) is not None), None)
+        if target is None and not had_file and not stale:
+            print(f'no member {device}: nothing to revoke')
+        else:
+            def left():
+                state = {True: f'the block still lets {device} in', False: f'the block has no line for {device}',
+                         None: 'the block could not be read back'}[_listed(path, device)]
+                kept = f'members/{device}.json is kept; ' if member_file.exists() else ''
+                return f'{state}; {kept}`lanes keys revoke {device}` finishes the revoke once that is fixed'
+
+            _project(path, [m for m in members if m['device'] != device], left)
+            try:
+                member_file.unlink(missing_ok=True)
+            except OSError as error:
+                raise L.LanesError(f'{device} has no line in the lanes-managed block of {path} any more, but '
+                                   f'members/{device}.json could not be removed ({_reason(error)}): remove it by hand '
+                                   f'— while it exists, the next `lanes keys` change authorizes {device} again') from None
+            if pubkey:
+                what = fingerprint(pubkey)
+            else:
+                what = 'its file was invalid and never rendered' if not stale else 'not an ed25519 key'
+            print(f'revoked {device} ({what}): no line for it in the lanes-managed block of {path}')
+            if target is None and stale:
+                print('its line was still in the block ' + (f'beside an invalid members/{device}.json' if had_file
+                                                            else f'without members/{device}.json'))
+            print('an ssh session already open with that key keeps running until it ends')
+    leftovers = _outside_holders(_read(path), pubkey=pubkey, device=device)
+    for number, parsed in leftovers:
+        _warn(f"⚠ line {number} outside the lanes-managed block still lets {device}'s key or `lanes:{device}` in "
+              f"({parsed['comment'] or 'no comment'}); `lanes keys` never edits lines outside the block on revoke — "
+              'remove it by hand')
+    return 1 if leftovers else 0
+
+
+def plan_adopt(data, members):
+    """(new member records by device, [(pubkey, device)] whose plain outside lines go, [report lines]) for the
+    `lanes:<device>` lines outside the block. Taken: a plain (no options) ssh-ed25519 line whose device holds no other
+    key and whose key no other device holds; a line for an existing member with the same key is a duplicate and goes.
+    Everything else stays byte for byte and is named."""
+    by_device = {m['device']: m for m in members}
+    holders = {m['pubkey']: m['device'] for m in members}
+    new, drop, report = {}, set(), []
+    for number, _, parsed in outside_entries(data):
+        device = _lanes_device(parsed)
+        if device is None:
+            continue
+        where = f'line {number} (lanes:{device})'
+        if not L.IDENT.match(device) or len(device) > MAX_DEVICE:
+            report.append(f'kept {where}: not a device name')
+            continue
+        if parsed['options']:
+            report.append(f"kept {where}: it has options ({parsed['options']}) — adopting would change what it may "
+                          'do; review it by hand')
+            continue
+        if parsed['type'] != KEY_TYPE or _ed25519_blob(parsed['key']) is None:
+            report.append(f"kept {where}: not an ssh-ed25519 key ({parsed['type']})")
+            continue
+        pubkey = f"{KEY_TYPE} {parsed['key']}"
+        current = by_device.get(device) or new.get(device)
+        if current is not None:
+            if current['pubkey'] == pubkey:
+                drop.add((pubkey, device))
+                report.append(f'{where}: duplicate of member {device}, removed')
+            else:
+                report.append(f'kept {where}: {device} already holds another key ({fingerprint(current["pubkey"])})')
+            continue
+        if pubkey in holders:
+            report.append(f'kept {where}: that key is already enrolled as {holders[pubkey]}')
+            continue
+        new[device] = member_record(device, pubkey)
+        holders[pubkey] = device
+        drop.add((pubkey, device))
+        report.append(f'adopted {device} ({fingerprint(pubkey)}) from line {number}')
+    return new, drop, report
+
+
+def cmd_adopt(path, dry_run=False):
+    with members_lock():
+        members, problems = load_members()
+        _warn_problems(problems)
+        data = _read(path)
+        new, drop, report = plan_adopt(data, members)
+
+        def goes(raw):
+            parsed = parse_line(raw.decode('utf-8', 'surrogateescape'))
+            return bool(parsed) and not parsed['options'] and parsed['type'] == KEY_TYPE and \
+                (f"{KEY_TYPE} {parsed['key']}", _lanes_device(parsed)) in drop
+
+        if dry_run:
+            for line in report:
+                print('would: ' + line if not line.startswith('adopted') else 'would adopt ' + line[len('adopted '):])
+            if not drop:
+                print('nothing to adopt')
+            return 0
+        for record in new.values():
+            save_member(record)                            # the records before their lines (see cmd_revoke)
+        kept = f'the {len(new)} member file(s) it adopted are kept in members/; ' if new else ''
+        changed = _project(path, members + list(new.values()),
+                           lambda: f'{kept}run `lanes keys adopt` again once that is fixed: it finishes from members/',
+                           drop=goes if drop else None)
+    for line in report:
+        print(line)
+    if not drop:
+        print('nothing to adopt' + ('; the block was re-rendered from members/' if changed else ''))
+    else:
+        print(f'{len(new)} adopted; the lanes-managed block of {path} holds {len(members) + len(new)} key(s); '
+              'the file before the first adopt is kept as authorized_keys.bak-<UTC>')
+    return 0
+
+
+def cmd_owner(device, login, name=None, email=None):
+    """Name the person behind member `device`: its owner becomes {login, name, email}. The only change to who owns a key
+    added by hand (`add`/`adopt` write owner null), and so how its person becomes a `/enrol/pending` approver, which
+    matches the tailnet login a member record's owner names (DEF-1643). The record keeps every other field and its
+    order; the block carries no owner, so authorized_keys is not touched. Refuses an owner members.py would not store,
+    a device with no record, and a record that does not load (fix it first) — never echoing a value."""
+    device = device_name(device)
+    owner = M.validate_owner({'login': login, 'name': name, 'email': email})
+    with members_lock():
+        members, problems = load_members()
+        current = next((m for m in members if m['device'] == device), None)
+        if current is None:
+            reason = next((why for file, why in problems if file == f'{device}.json'), None)
+            if reason is not None:
+                raise L.LanesError(f'members/{device}.json: {reason} — fix or remove the file first; nothing changed')
+            raise L.LanesError(f'no member {device} (`lanes keys list` shows the members); nothing changed')
+        before = M.valid_owner(current.get('owner'))
+        if before == owner:
+            print(f"{device} is already owned by {owner['login']}; nothing changed")
+            return 0
+        record = dict(current, owner=owner)
+        if record.get('pubkey_sha256') is None:            # a record written before A2 carries no fingerprint
+            record['pubkey_sha256'] = fingerprint(record['pubkey'])
+        save_member(record)
+    print(f"owner of {device}: {before['login'] if before else 'none'} -> {owner['login']}"
+          + (f" ({owner['name']})" if owner['name'] else ''))
+    return 0
+
+
+def _owner_args(rest):
+    """[device, login, (--name NAME | --email ADDR)...] -> (device, login, name, email), each option at most once."""
+    if len(rest) < 2 or len(rest) % 2:
+        raise L.LanesError(USAGE)
+    options = {}
+    for flag, value in zip(rest[2::2], rest[3::2]):
+        if flag not in ('--name', '--email') or flag in options:
+            raise L.LanesError(USAGE)
+        options[flag] = value
+    return rest[0], rest[1], options.get('--name'), options.get('--email')
+
+
+def main(args):
+    path = authorized_keys_path()
+    verb, rest = (args[0], args[1:]) if args else (None, [])
+    if verb == 'list' and not rest:
+        return cmd_list(path)
+    if verb == 'add' and len(rest) == 2:
+        return cmd_add(path, *rest)
+    if verb == 'revoke' and len(rest) == 1:
+        return cmd_revoke(path, rest[0])
+    if verb == 'adopt' and rest in ([], ['--dry-run']):
+        return cmd_adopt(path, dry_run=bool(rest))
+    if verb == 'owner':
+        return cmd_owner(*_owner_args(rest))
+    raise L.LanesError(USAGE)
+
+
+if __name__ == '__main__':
+    try:
+        sys.exit(main(sys.argv[1:]))
+    except L.LanesError as error:
+        sys.exit(f'lanes keys: {error}')