real-browser-cli 0.14.2__py3-none-any.whl

browser_cli/__init__.py

@@ -0,0 +1,164 @@
+"""
+browser_cli — Python SDK for controlling your running browser.
+
+Usage:
+  from browser_cli import BrowserCLI
+  b = BrowserCLI()
+
+  tabs = b.tabs.list()      # list[Tab]
+  tabs[0].close()
+  tabs[0].move(forward=True)
+
+  groups = b.groups.list()    # list[Group]
+  groups[0].tabs()
+  groups[0].add_tab("https://example.com")
+
+  b.nav.open("https://example.com")
+  b.dom.click("#submit")
+  b.session.save("work")
+
+  # When multiple browser instances are active, pass the alias:
+  b = BrowserCLI(browser="brave")
+
+Commands are grouped into namespaces on the client:
+  b.nav    navigation (open, reload, back, forward, focus, search)
+  b.tabs     tabs (list, open, close, move, status, mute, sort, ...)
+  b.groups   tab groups (list, create, add_tab, move, close)
+  b.windows  browser windows (list, open, close, rename)
+  b.dom    page elements (query, click, type, wait_for, eval, ...)
+  b.extract  content extraction (links, images, text, json, markdown)
+  b.page     page info
+  b.storage  localStorage / sessionStorage
+  b.session  sessions (save, load, list, diff, ...)
+  b.perf     performance profile + background jobs
+  b.extension  control the extension itself
+  b.decorators workflow decorators for scripts
+"""
+from collections.abc import Callable
+
+from browser_cli.client import active_browser_targets, remote_browser_targets, send_command, send_command_async
+from browser_cli.errors import BrowserNotConnected
+from browser_cli.models import BrowserCounts, Group, Tab
+from browser_cli.sdk import (
+  DecoratorsNS,
+  DomNS,
+  ExtensionNS,
+  ExtractNS,
+  GroupsNS,
+  NAMESPACE_SPECS,
+  NavigationNS,
+  PageNS,
+  PerfNS,
+  SessionNS,
+  StorageNS,
+  TabsNS,
+  WindowsNS,
+)
+from browser_cli.sdk.factories import FactoryMixin
+from browser_cli.sdk.routing import RoutingMixin
+
+from browser_cli.async_sdk import AsyncBrowserCLI
+
+__all__ = ["BrowserCLI", "AsyncBrowserCLI", "BrowserCounts", "BrowserNotConnected", "Tab", "Group"]
+
+class BrowserCLI(FactoryMixin, RoutingMixin):
+  """Client for a running browser, with commands grouped into namespaces.
+
+  The client itself holds the connection target (browser/remote/key) and the
+  shared machinery; the actual commands live on namespace accessors such as
+  :attr:`tabs`, :attr:`dom`, and :attr:`session`. Object construction
+  (``Tab``/``Group``) comes from :class:`~browser_cli.sdk.factories.FactoryMixin`
+  and multi-browser fan-out from :class:`~browser_cli.sdk.routing.RoutingMixin`.
+  """
+
+  _browser: str | None
+  _remote: str | None
+  _key: str | None
+  _command_sender: Callable
+  nav: NavigationNS
+  tabs: TabsNS
+  groups: GroupsNS
+  windows: WindowsNS
+  dom: DomNS
+  extract: ExtractNS
+  page: PageNS
+  storage: StorageNS
+  session: SessionNS
+  perf: PerfNS
+  extension: ExtensionNS
+  decorators: DecoratorsNS
+
+  def __init__(
+    self,
+    browser: str | None = None,
+    remote: str | None = None,
+    key: str | None = None,
+    *,
+    _command_sender=None,
+  ):
+    """
+    Args:
+      browser: Profile alias to target. Required when multiple browser
+           instances are active. Equivalent to ``--browser`` on the CLI.
+      remote: Connect to a remote browser exposed via ``browser-cli serve``.
+          Format: ``"host:port"`` (e.g. ``"browser-host.example:8765"``).
+          Can be combined with ``browser`` to route to a specific
+          remote profile.
+      key: Path to Ed25519 private key PEM for pubkey auth, or ``"agent"``
+         to use a key from the SSH agent (YubiKey, gpg-agent, etc.).
+         Defaults to ``~/.config/browser-cli/client.key.pem`` if that file exists.
+    """
+    self._browser = browser
+    self._remote = remote
+    self._key = key if key else None
+    self._command_sender = _command_sender or send_command
+
+    for name, namespace_type in NAMESPACE_SPECS:
+      setattr(self, name, namespace_type(self))
+    self.decorators = DecoratorsNS(self)
+
+  @property
+  def browser(self) -> str | None:
+    """Target browser/profile alias, equivalent to ``--browser``."""
+    return self._browser
+
+  @property
+  def remote(self) -> str | None:
+    """Remote endpoint used by this client, if any."""
+    return self._remote
+
+  @property
+  def key(self) -> str | None:
+    """Ed25519 key spec used for remote auth, if explicitly configured."""
+    return self._key
+
+  def dispatch(self, command: str, args: dict | None = None):
+    """Dispatch one browser command using this client's target settings."""
+    return self._command_sender(command, args, profile=self._browser, remote=self._remote, key=self._key)
+
+  def require_tab(self, data, error: str):
+    """Convert a tab-like command response into a bound Tab."""
+    return self.require_tab_response(data, error)
+
+  _FIELD_MISSING = object()
+
+  def field(self, result, key, default=None, *, fallback=_FIELD_MISSING):
+    """Read a named field from command output."""
+    if fallback is self._FIELD_MISSING:
+      return self._field(result, key, default)
+    return self._field(result, key, default, fallback=fallback)
+
+  def _cmd(self, command: str, args: dict | None = None):
+    return self.dispatch(command, args)
+
+  def command(self, command: str, args: dict | None = None):
+    """Send a raw browser-cli command and return its response.
+
+    This is the SDK escape hatch for commands that do not have a dedicated
+    namespace method yet.
+    """
+    return self._cmd(command, args or {})
+
+  def clients(self) -> list[dict]:
+    """Return the active browser clients known to this connection."""
+    return self._cmd("clients.list", {})

browser_cli/async_sdk.py

@@ -0,0 +1,237 @@
+"""Async browser-cli Python SDK.
+
+The async SDK intentionally reuses the synchronous SDK namespaces instead of
+copying every command method. Each async namespace is a thin adapter that runs
+the corresponding sync SDK method in a worker thread, while a private command
+sender dispatches commands through ``send_command_async``. That keeps command
+strings, argument shapes, result mapping, and bound model creation in one place:
+``browser_cli.sdk``.
+"""
+from __future__ import annotations
+
+import asyncio
+import functools
+from collections.abc import Callable
+from typing import TypeVar
+
+from browser_cli.models import Group, Tab
+from browser_cli.sdk import NAMESPACE_NAMES
+from browser_cli.sdk.workflow_decorators import WorkflowDecoratorsMixin, _NO_INJECT
+
+F = TypeVar("F", bound=Callable)
+
+class AsyncNamespaceAdapter:
+  """Async wrapper around one synchronous SDK namespace."""
+
+  def __init__(self, sync_namespace):
+    self._sync = sync_namespace
+
+  def __getattr__(self, name: str):
+    value = getattr(self._sync, name)
+    if not callable(value):
+      return value
+
+    @functools.wraps(value)
+    async def wrapper(*args, **kwargs):
+      return await asyncio.to_thread(value, *args, **kwargs)
+
+    return wrapper
+
+class AsyncDecoratorsNS(WorkflowDecoratorsMixin):
+  """Async workflow decorators for :class:`AsyncBrowserCLI`.
+
+  The public decorator methods are inherited from ``WorkflowDecoratorsMixin``;
+  only the execution strategy differs: every wrapper is async and awaits both
+  browser calls and async user functions.
+  """
+
+  def __init__(self, client: "AsyncBrowserCLI"):
+    self._c = client
+
+  @staticmethod
+  async def _maybe_await(value):
+    if hasattr(value, "__await__"):
+      return await value
+    return value
+
+  def _value_decorator(
+    self,
+    func: F | None,
+    get_value: Callable,
+    *,
+    keyword: str | None | object = "tab",
+    cleanup: Callable | None = None,
+  ):
+    def decorator(fn: F) -> F:
+      @functools.wraps(fn)
+      async def wrapper(*args, **kwargs):
+        value = await get_value()
+        try:
+          extra_args = ()
+          if keyword is not _NO_INJECT:
+            extra_args, kwargs = self._inject(kwargs, keyword, value)
+          return await self._maybe_await(fn(*extra_args, *args, **kwargs))
+        finally:
+          if cleanup is not None:
+            await self._maybe_await(cleanup(value))
+      return wrapper  # type: ignore[return-value]
+    return decorator(func) if func is not None else decorator
+
+  def new_tab(
+    self,
+    url: str,
+    *,
+    wait: bool = False,
+    timeout: float = 30.0,
+    background: bool = False,
+    focus: bool = False,
+    window: str | None = None,
+    group: str | None = None,
+    close: bool = False,
+    keyword: str | None = "tab",
+  ):
+    def open_tab():
+      return self._c.tabs.open(
+        url,
+        wait=wait,
+        timeout=timeout,
+        background=background,
+        focus=focus,
+        window=window,
+        group=group,
+      )
+
+    async def close_tab(tab):
+      await self._c.tabs.close(tab.id)
+
+    return self._value_decorator(None, open_tab, keyword=keyword, cleanup=close_tab if close else None)
+
+  def performance_profile(self, profile: str, *, restore: bool = True):
+    def decorator(fn: F) -> F:
+      @functools.wraps(fn)
+      async def wrapper(*args, **kwargs):
+        previous = (await self._c.perf.status()).get("performanceProfile") if restore else None
+        await self._c.perf.set_profile(profile)
+        try:
+          return await self._maybe_await(fn(*args, **kwargs))
+        finally:
+          if previous:
+            await self._c.perf.set_profile(previous)
+      return wrapper  # type: ignore[return-value]
+    return decorator
+
+  def retry(
+    self,
+    *,
+    times: int = 3,
+    delay: float = 0.0,
+    exceptions: tuple[type[BaseException], ...] = (Exception,),
+  ):
+    attempts = max(1, times)
+
+    def decorator(fn: F) -> F:
+      @functools.wraps(fn)
+      async def wrapper(*args, **kwargs):
+        last_error = None
+        for attempt in range(attempts):
+          try:
+            return await self._maybe_await(fn(*args, **kwargs))
+          except exceptions as exc:
+            last_error = exc
+            if attempt == attempts - 1:
+              raise
+            if delay > 0:
+              await asyncio.sleep(delay)
+        raise last_error  # type: ignore[misc]
+      return wrapper  # type: ignore[return-value]
+    return decorator
+
+class AsyncBrowserCLI:
+  """Async client for a running browser.
+
+  Namespace methods are awaitable mirrors of :class:`browser_cli.BrowserCLI`.
+  """
+
+  _NAMESPACES = NAMESPACE_NAMES
+
+  def __init__(self, browser: str | None = None, remote: str | None = None, key: str | None = None):
+    from browser_cli import BrowserCLI
+
+    self._browser = browser
+    self._remote = remote
+    self._key = key if key else None
+    self._sync = BrowserCLI(browser=browser, remote=remote, key=key, _command_sender=self._blocking_async_cmd)
+
+    for name in self._NAMESPACES:
+      setattr(self, name, AsyncNamespaceAdapter(getattr(self._sync, name)))
+    self.decorators = AsyncDecoratorsNS(self)
+
+  @property
+  def browser(self) -> str | None:
+    return self._browser
+
+  @property
+  def remote(self) -> str | None:
+    return self._remote
+
+  @property
+  def key(self) -> str | None:
+    return self._key
+
+  def _blocking_async_cmd(
+    self,
+    command: str,
+    args: dict | None = None,
+    *,
+    profile: str | None = None,
+    remote: str | None = None,
+    key: str | None = None,
+  ):
+    """Run the native async transport from a worker thread.
+
+    Async namespace methods execute sync SDK logic in ``asyncio.to_thread``.
+    Inside that worker thread, the sync SDK's injected command sender lands
+    here and uses the async transport implementation without blocking the
+    caller's event loop.
+    """
+    return asyncio.run(self._cmd(command, args, profile=profile, remote=remote, key=key))
+
+  async def _cmd(
+    self,
+    command: str,
+    args: dict | None = None,
+    *,
+    profile: str | None = None,
+    remote: str | None = None,
+    key: str | None = None,
+  ):
+    from browser_cli.client import send_command_async
+    return await send_command_async(
+      command,
+      args,
+      profile=self._browser if profile is None else profile,
+      remote=self._remote if remote is None else remote,
+      key=self._key if key is None else key,
+    )
+
+  async def command(self, command: str, args: dict | None = None):
+    return await self._cmd(command, args or {})
+
+  async def clients(self) -> list[dict]:
+    return await self._cmd("clients.list", {})
+
+  def tab_from(self, data: dict, *, browser_profile: str | None = None, browser_name: str | None = None, browser_remote: str | None = None) -> Tab:
+    return self._sync.tab_from(
+      data,
+      browser_profile=browser_profile,
+      browser_name=browser_name,
+      browser_remote=browser_remote,
+    )
+
+  def group_from(self, data: dict, *, browser_profile: str | None = None, browser_name: str | None = None, browser_remote: str | None = None) -> Group:
+    return self._sync.group_from(
+      data,
+      browser_profile=browser_profile,
+      browser_name=browser_name,
+      browser_remote=browser_remote,
+    )

browser_cli/auth.py

@@ -0,0 +1,263 @@
+"""Ed25519 keypair management, ML-KEM key exchange, and auth helpers."""
+import hashlib
+import json
+import os
+import secrets
+import socket
+import struct
+from dataclasses import dataclass
+from pathlib import Path
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+from cryptography.hazmat.primitives.serialization import (
+  Encoding,
+  NoEncryption,
+  PrivateFormat,
+  PublicFormat,
+  load_pem_private_key,
+)
+
+from browser_cli.constants import (
+  DEFAULT_AUTHORIZED_KEYS_PATH,
+  DEFAULT_KEY_PATH,
+  PQ_KEX_ALG,
+  PQ_TRANSPORT_ALG,
+  SSH_AGENT_IDENTITIES_ANSWER,
+  SSH_AGENT_SIGN_RESPONSE,
+  SSH_AGENTC_REQUEST_IDENTITIES,
+  SSH_AGENTC_SIGN_REQUEST,
+)
+
+def _pack_str(s: bytes) -> bytes:
+  return struct.pack(">I", len(s)) + s
+
+def _unpack_str(data: bytes, off: int) -> tuple[bytes, int]:
+  n = struct.unpack_from(">I", data, off)[0]
+  return data[off + 4 : off + 4 + n], off + 4 + n
+
+def _agent_roundtrip(msg: bytes) -> bytes:
+  sock_path = os.environ.get("SSH_AUTH_SOCK")
+  if not sock_path:
+    raise RuntimeError("SSH_AUTH_SOCK not set — is gpg-agent / ssh-agent running?")
+  with socket.socket(socket.AF_UNIX, socket.SOCK_STREAM) as sock:
+    sock.settimeout(10)
+    sock.connect(sock_path)
+    sock.sendall(struct.pack(">I", len(msg)) + msg)
+    raw_len = b""
+    while len(raw_len) < 4:
+      chunk = sock.recv(4 - len(raw_len))
+      if not chunk:
+        raise RuntimeError("SSH agent closed connection")
+      raw_len += chunk
+    n = struct.unpack(">I", raw_len)[0]
+    resp = b""
+    while len(resp) < n:
+      chunk = sock.recv(n - len(resp))
+      if not chunk:
+        raise RuntimeError("SSH agent closed connection mid-response")
+      resp += chunk
+    return resp
+
+# ── AgentKey ───────────────────────────────────────────────────────────────────
+
+@dataclass
+class AgentKey:
+  """Ed25519 key backed by an SSH agent (YubiKey, TPM, ssh-agent, gpg-agent …)."""
+  blob: bytes
+  comment: str
+
+  @property
+  def pubkey_bytes(self) -> bytes:
+    _algo, off = _unpack_str(self.blob, 0)
+    key_bytes, _ = _unpack_str(self.blob, off)
+    return key_bytes
+
+# ── Agent helpers ──────────────────────────────────────────────────────────────
+
+def agent_list_keys() -> list[AgentKey]:
+  """Return all Ed25519 keys currently held by the SSH agent."""
+  resp = _agent_roundtrip(bytes([SSH_AGENTC_REQUEST_IDENTITIES]))
+  if resp[0] != SSH_AGENT_IDENTITIES_ANSWER:
+    raise RuntimeError(f"Unexpected agent response: {resp[0]}")
+  n_keys = struct.unpack_from(">I", resp, 1)[0]
+  keys: list[AgentKey] = []
+  off = 5
+  for _ in range(n_keys):
+    blob, off = _unpack_str(resp, off)
+    comment, off = _unpack_str(resp, off)
+    algo, _ = _unpack_str(blob, 0)
+    if algo == b"ssh-ed25519":
+      keys.append(AgentKey(blob=blob, comment=comment.decode("utf-8", errors="replace")))
+  return keys
+
+def agent_find_key(selector: str | None = None) -> AgentKey | None:
+  """Return the first agent Ed25519 key whose comment contains selector (or any if None)."""
+  try:
+    keys = agent_list_keys()
+  except Exception:
+    return None
+  for key in keys:
+    if key.comment == "(none)":
+      continue
+    if selector is None or selector in key.comment:
+      return key
+  return None
+
+def agent_sign_raw(key: AgentKey, data: bytes) -> bytes:
+  """Ask the SSH agent to sign data and return the raw 64-byte Ed25519 signature."""
+  msg = (
+    bytes([SSH_AGENTC_SIGN_REQUEST])
+    + _pack_str(key.blob)
+    + _pack_str(data)
+    + struct.pack(">I", 0)
+  )
+  resp = _agent_roundtrip(msg)
+  if resp[0] != SSH_AGENT_SIGN_RESPONSE:
+    raise RuntimeError(f"SSH agent refused to sign (response code {resp[0]})")
+  sig_blob, _ = _unpack_str(resp, 1)
+  _algo, soff = _unpack_str(sig_blob, 0)
+  raw_sig, _ = _unpack_str(sig_blob, soff)
+  if len(raw_sig) != 64:
+    raise RuntimeError(f"Unexpected signature length {len(raw_sig)}")
+  return raw_sig
+
+# ── File-based key helpers ─────────────────────────────────────────────────────
+
+def generate_keypair() -> tuple[bytes, str]:
+  """Return (private_key_pem_bytes, public_key_hex)."""
+  priv = Ed25519PrivateKey.generate()
+  pem = priv.private_bytes(Encoding.PEM, PrivateFormat.PKCS8, NoEncryption())
+  pub_hex = priv.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw).hex()
+  return pem, pub_hex
+
+def load_private_key(path: Path) -> Ed25519PrivateKey:
+  return load_pem_private_key(path.read_bytes(), password=None)
+
+def public_key_hex(key: Ed25519PrivateKey | AgentKey) -> str:
+  if isinstance(key, AgentKey):
+    return key.pubkey_bytes.hex()
+  return key.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw).hex()
+
+# ── Canonical payload + sign/verify ───────────────────────────────────────────
+
+def canonical_payload(msg: dict) -> bytes:
+  """Deterministic JSON encoding of msg without auth protocol fields."""
+  return json.dumps(
+    {k: v for k, v in msg.items() if k not in {"pubkey", "sig", "pq_kex"}},
+    sort_keys=True,
+    separators=(",", ":"),
+  ).encode("utf-8")
+
+def _auth_message(nonce: bytes, msg: dict, pq_shared_secret: bytes | None = None) -> bytes:
+  """Bytes signed for auth; optionally binds a post-quantum KEX secret."""
+  data = nonce + hashlib.sha256(canonical_payload(msg)).digest()
+  if pq_shared_secret is not None:
+    data += hashlib.sha256(b"browser-cli ml-kem-768 v1" + pq_shared_secret).digest()
+  return data
+
+def sign(key: Ed25519PrivateKey | AgentKey, nonce: bytes, msg: dict, pq_shared_secret: bytes | None = None) -> bytes:
+  """Sign nonce + payload hash, optionally bound to an ML-KEM shared secret."""
+  data = _auth_message(nonce, msg, pq_shared_secret)
+  if isinstance(key, AgentKey):
+    return agent_sign_raw(key, data)
+  return key.sign(data)
+
+def verify(pub_hex: str, nonce: bytes, msg: dict, sig_hex: str, pq_shared_secret: bytes | None = None) -> bool:
+  """Return True if sig_hex is a valid signature over the canonical payload/auth secret."""
+  try:
+    pub_bytes = bytes.fromhex(pub_hex)
+    pub_key = Ed25519PublicKey.from_public_bytes(pub_bytes)
+    pub_key.verify(bytes.fromhex(sig_hex), _auth_message(nonce, msg, pq_shared_secret))
+    return True
+  except (InvalidSignature, ValueError):
+    return False
+
+# ── Post-quantum key exchange (ML-KEM / Kyber) ────────────────────────────────
+
+def pq_kex_server_keypair():
+  """Return an ephemeral ML-KEM-768 private key and raw public key bytes.
+
+  Returns ``None`` when the installed cryptography/OpenSSL backend does not
+  support ML-KEM yet. The serve/client protocol treats this as graceful
+  downgrade instead of breaking local installs on older OpenSSL builds.
+  """
+  try:
+    from cryptography.hazmat.primitives.asymmetric import mlkem
+    priv = mlkem.MLKEM768PrivateKey.generate()
+    pub = priv.public_key().public_bytes_raw()
+    return priv, pub
+  except Exception:
+    return None
+
+def pq_kex_client_encapsulate(public_key_hex: str) -> tuple[str, bytes]:
+  """Encapsulate to a server ML-KEM public key. Returns (ciphertext_hex, secret)."""
+  from cryptography.hazmat.primitives.asymmetric import mlkem
+  pub = mlkem.MLKEM768PublicKey.from_public_bytes(bytes.fromhex(public_key_hex))
+  shared_secret, ciphertext = pub.encapsulate()
+  return ciphertext.hex(), shared_secret
+
+def pq_kex_server_decapsulate(private_key, ciphertext_hex: str) -> bytes:
+  """Decapsulate a client ML-KEM ciphertext and return the shared secret."""
+  return private_key.decapsulate(bytes.fromhex(ciphertext_hex))
+
+def _pq_transport_key(shared_secret: bytes, direction: str) -> bytes:
+  return HKDF(
+    algorithm=hashes.SHA256(),
+    length=32,
+    salt=None,
+    info=f"browser-cli pq transport v1 {direction}".encode("ascii"),
+  ).derive(shared_secret)
+
+def pq_encrypt(shared_secret: bytes, direction: str, plaintext: bytes) -> dict:
+  """Encrypt an app-layer frame with a key derived from the ML-KEM secret."""
+  nonce = secrets.token_bytes(12)
+  key = _pq_transport_key(shared_secret, direction)
+  ciphertext = ChaCha20Poly1305(key).encrypt(nonce, plaintext, None)
+  return {"alg": PQ_TRANSPORT_ALG, "nonce": nonce.hex(), "ciphertext": ciphertext.hex()}
+
+def pq_decrypt(shared_secret: bytes, direction: str, envelope: dict) -> bytes:
+  """Decrypt an app-layer frame produced by pq_encrypt()."""
+  if not isinstance(envelope, dict) or envelope.get("alg") != PQ_TRANSPORT_ALG:
+    raise ValueError("unsupported encrypted transport envelope")
+  key = _pq_transport_key(shared_secret, direction)
+  return ChaCha20Poly1305(key).decrypt(
+    bytes.fromhex(str(envelope["nonce"])),
+    bytes.fromhex(str(envelope["ciphertext"])),
+    None,
+  )
+
+def new_nonce() -> str:
+  return secrets.token_hex(32)
+
+def load_authorized_keys_with_names(path: Path) -> list[tuple[str, str]]:
+  """Return list of (pubkey_hex, name) pairs. Name is empty string if not set."""
+  if not path.exists():
+    return []
+  result = []
+  for line in path.read_text(encoding="utf-8").splitlines():
+    line = line.strip()
+    if not line or line.startswith("#"):
+      continue
+    parts = line.split(None, 1)
+    pubkey = parts[0]
+    name = parts[1].strip() if len(parts) > 1 else ""
+    result.append((pubkey, name))
+  return result
+
+def load_authorized_keys(path: Path) -> list[str]:
+  return [pk for pk, _ in load_authorized_keys_with_names(path)]
+
+def add_authorized_key(path: Path, pub_hex: str, name: str = "") -> bool:
+  """Append pub_hex to authorized_keys. Returns False if already present."""
+  path.parent.mkdir(parents=True, exist_ok=True)
+  existing = {pk for pk, _ in load_authorized_keys_with_names(path)}
+  if pub_hex in existing:
+    return False
+  line = (f"{pub_hex} {name}".rstrip()) + "\n"
+  with open(path, "a", encoding="utf-8") as f:
+    f.write(line)
+  return True