refactor: modularize auth transport and markdown

- Split auth into focused package modules for agent keys, file keys,
  signing, and post-quantum transport helpers while keeping the public
  browser_cli.auth import surface intact.
- Move transport encoding internals into a package with separate codec and
  binary-hoisting helpers, preserving browser_cli.transport compatibility.
- Extract remote TCP auth/socket helpers and serve challenge setup out of the
  runtime paths to make connection handling easier to reason about.
- Move the extension markdown extractor into a dedicated content/markdown
  folder with separate root selection, code normalization, renderer, and utils.
- Centralize CLI Rich rendering helpers for tab/window tree and table output,
  and add rendering tests for the shared builders.
- Remove local typing ignores in SDK/decorator/script plumbing and bump the
  package and extension version to 0.15.3.

browser_cli/auth/__init__.py

@@ -0,0 +1,67 @@
+"""Public auth API for browser-cli.
+
+Implementation lives in focused modules:
+- ``auth.agent``: SSH-agent/YubiKey helpers
+- ``auth.keys``: file keys and authorized_keys management
+- ``auth.signing``: canonical payload signing/verification
+- ``auth.pq``: ML-KEM KEX and encrypted transport helpers
+"""
+from browser_cli.auth.agent import (
+  AgentKey,
+  agent_find_key,
+  agent_list_keys,
+  agent_roundtrip as _agent_roundtrip,
+  agent_sign_raw,
+  pack_ssh_string as _pack_str,
+  unpack_ssh_string as _unpack_str,
+)
+from browser_cli.auth.keys import (
+  add_authorized_key,
+  generate_keypair,
+  load_authorized_keys,
+  load_authorized_keys_with_names,
+  load_private_key,
+  public_key_hex,
+)
+from browser_cli.auth.pq import (
+  new_nonce,
+  pq_decrypt,
+  pq_encrypt,
+  pq_kex_client_encapsulate,
+  pq_kex_server_decapsulate,
+  pq_kex_server_keypair,
+  pq_transport_key as _pq_transport_key,
+)
+from browser_cli.auth.signing import (
+  auth_message as _auth_message,
+  canonical_payload,
+  sign,
+  verify,
+)
+from browser_cli.constants import DEFAULT_AUTHORIZED_KEYS_PATH, DEFAULT_KEY_PATH, PQ_KEX_ALG, PQ_TRANSPORT_ALG
+
+__all__ = [
+  "AgentKey",
+  "DEFAULT_AUTHORIZED_KEYS_PATH",
+  "DEFAULT_KEY_PATH",
+  "PQ_KEX_ALG",
+  "PQ_TRANSPORT_ALG",
+  "add_authorized_key",
+  "agent_find_key",
+  "agent_list_keys",
+  "agent_sign_raw",
+  "canonical_payload",
+  "generate_keypair",
+  "load_authorized_keys",
+  "load_authorized_keys_with_names",
+  "load_private_key",
+  "new_nonce",
+  "pq_decrypt",
+  "pq_encrypt",
+  "pq_kex_client_encapsulate",
+  "pq_kex_server_decapsulate",
+  "pq_kex_server_keypair",
+  "public_key_hex",
+  "sign",
+  "verify",
+]

browser_cli/auth/agent.py

@@ -0,0 +1,103 @@
+"""SSH-agent backed Ed25519 key helpers."""
+from __future__ import annotations
+
+import os
+import socket
+import struct
+from dataclasses import dataclass
+
+from browser_cli.constants import (
+  SSH_AGENT_IDENTITIES_ANSWER,
+  SSH_AGENT_SIGN_RESPONSE,
+  SSH_AGENTC_REQUEST_IDENTITIES,
+  SSH_AGENTC_SIGN_REQUEST,
+)
+
+def pack_ssh_string(value: bytes) -> bytes:
+  return struct.pack(">I", len(value)) + value
+
+def unpack_ssh_string(data: bytes, offset: int) -> tuple[bytes, int]:
+  length = struct.unpack_from(">I", data, offset)[0]
+  return data[offset + 4 : offset + 4 + length], offset + 4 + length
+
+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
+    length = struct.unpack(">I", raw_len)[0]
+    response = b""
+    while len(response) < length:
+      chunk = sock.recv(length - len(response))
+      if not chunk:
+        raise RuntimeError("SSH agent closed connection mid-response")
+      response += chunk
+    return response
+
+@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, offset = unpack_ssh_string(self.blob, 0)
+    key_bytes, _ = unpack_ssh_string(self.blob, offset)
+    return key_bytes
+
+def agent_list_keys() -> list[AgentKey]:
+  """Return all Ed25519 keys currently held by the SSH agent."""
+  response = agent_roundtrip(bytes([SSH_AGENTC_REQUEST_IDENTITIES]))
+  if response[0] != SSH_AGENT_IDENTITIES_ANSWER:
+    raise RuntimeError(f"Unexpected agent response: {response[0]}")
+  key_count = struct.unpack_from(">I", response, 1)[0]
+  keys: list[AgentKey] = []
+  offset = 5
+  for _ in range(key_count):
+    blob, offset = unpack_ssh_string(response, offset)
+    comment, offset = unpack_ssh_string(response, offset)
+    algo, _ = unpack_ssh_string(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_ssh_string(key.blob)
+    + pack_ssh_string(data)
+    + struct.pack(">I", 0)
+  )
+  response = agent_roundtrip(msg)
+  if response[0] != SSH_AGENT_SIGN_RESPONSE:
+    raise RuntimeError(f"SSH agent refused to sign (response code {response[0]})")
+  sig_blob, _ = unpack_ssh_string(response, 1)
+  _algo, sig_offset = unpack_ssh_string(sig_blob, 0)
+  raw_sig, _ = unpack_ssh_string(sig_blob, sig_offset)
+  if len(raw_sig) != 64:
+    raise RuntimeError(f"Unexpected signature length {len(raw_sig)}")
+  return raw_sig

browser_cli/auth/keys.py

@@ -0,0 +1,59 @@
+"""File-based Ed25519 keys and authorized_keys helpers."""
+from __future__ import annotations
+
+from pathlib import Path
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+from cryptography.hazmat.primitives.serialization import (
+  Encoding,
+  NoEncryption,
+  PrivateFormat,
+  PublicFormat,
+  load_pem_private_key,
+)
+
+from browser_cli.auth.agent import AgentKey
+
+def generate_keypair() -> tuple[bytes, str]:
+  """Return (private_key_pem_bytes, public_key_hex)."""
+  private_key = Ed25519PrivateKey.generate()
+  pem = private_key.private_bytes(Encoding.PEM, PrivateFormat.PKCS8, NoEncryption())
+  public_hex = private_key.public_key().public_bytes(Encoding.Raw, PublicFormat.Raw).hex()
+  return pem, public_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()
+
+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 [pubkey for pubkey, _name 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 = {pubkey for pubkey, _name 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 file:
+    file.write(line)
+  return True

browser_cli/auth/pq.py

@@ -0,0 +1,65 @@
+"""Post-quantum ML-KEM key exchange and app-layer transport encryption."""
+from __future__ import annotations
+
+import secrets
+
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.ciphers.aead import ChaCha20Poly1305
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+
+from browser_cli.constants import PQ_TRANSPORT_ALG
+
+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
+    private_key = mlkem.MLKEM768PrivateKey.generate()
+    public_key = private_key.public_key().public_bytes_raw()
+    return private_key, public_key
+  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
+  public_key = mlkem.MLKEM768PublicKey.from_public_bytes(bytes.fromhex(public_key_hex))
+  shared_secret, ciphertext = public_key.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)

browser_cli/auth/signing.py

@@ -0,0 +1,42 @@
+"""Canonical browser-cli auth payload signing and verification."""
+from __future__ import annotations
+
+import hashlib
+import json
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey, Ed25519PublicKey
+
+from browser_cli.auth.agent import AgentKey, agent_sign_raw
+
+def canonical_payload(msg: dict) -> bytes:
+  """Deterministic JSON encoding of msg without auth protocol fields."""
+  return json.dumps(
+    {key: value for key, value in msg.items() if key 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