witbitz-code 1.2.0__py3-none-any.whl

witbitz_code/devicelink.py

@@ -0,0 +1,159 @@
+"""Bring this computer into a Spaces account by QR, without a secret in the QR — spaces/public/deviceLink.js, plus the
+pieces of spaces/public/recovery.js the link needs.
+
+  THIS computer (empty)          draws a QR: an ephemeral P-256 PUBLIC key + a random ref. Nothing secret.
+  A signed-in device             scans it, confirms, seals the account to that public key, posts it to the ref.
+  THIS computer                  polls the ref and opens it with the private half, which never leaves this process.
+
+The relay in between sees two ECDH public keys and AES-GCM output; it cannot combine them.
+"""
+
+from __future__ import annotations
+
+import os
+import re
+from dataclasses import dataclass, field
+from typing import Any
+
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives.ciphers.aead import AESGCM
+from cryptography.hazmat.primitives.kdf.hkdf import HKDF
+from cryptography.hazmat.primitives.serialization import Encoding, PublicFormat
+
+from . import _js
+from ._js import b64u, truthy, unb64u_loose
+
+LINK_PREFIX = "wbzlink1:"
+_LINK_INFO = b"witbitz-device-link-v1"
+_BACKUP_SALT = b"witbitz-spaces-backup-v1"
+
+
+@dataclass(frozen=True)
+class LinkChallenge:
+    ref: str
+    pub: str
+    text: str
+    priv: ec.EllipticCurvePrivateKey = field(repr=False)
+
+
+def _export_pub(key: ec.EllipticCurvePublicKey) -> str:
+    """Compressed point (33 bytes), so the QR stays sparse enough to scan in poor light."""
+    return b64u(key.public_bytes(Encoding.X962, PublicFormat.CompressedPoint))
+
+
+def _import_pub(b64: Any) -> ec.EllipticCurvePublicKey:
+    raw = unb64u_loose(b64)
+    if len(raw) != 33 or raw[0] not in (2, 3):
+        raise ValueError("bad_point")
+    try:  # rejects an x that is ≥ p or not on the curve, as the JS decompression does
+        return ec.EllipticCurvePublicKey.from_encoded_point(ec.SECP256R1(), raw)
+    except ValueError as e:
+        raise ValueError("bad_point") from e
+
+
+def _shared_key(priv: ec.EllipticCurvePrivateKey, pub: ec.EllipticCurvePublicKey, ref: Any) -> AESGCM:
+    """Both sides derive the same AES-GCM key from the shared point, bound to the ref so a blob can't be replayed at another."""
+    bits = priv.exchange(ec.ECDH(), pub)
+    salt = _js.js_string(ref).encode("utf-8")
+    return AESGCM(HKDF(algorithm=hashes.SHA256(), length=32, salt=salt, info=_LINK_INFO).derive(bits))
+
+
+def new_link_challenge() -> LinkChallenge:
+    """Mint the challenge to draw as a QR. `priv` never leaves this process."""
+    priv = ec.generate_private_key(ec.SECP256R1())
+    ref = os.urandom(16).hex()
+    pub = _export_pub(priv.public_key())
+    return LinkChallenge(ref=ref, pub=pub, text=LINK_PREFIX + ref + "." + pub, priv=priv)
+
+
+def parse_challenge(text: Any) -> dict | None:
+    """What a camera saw → {ref, pub}, or None for anything else."""
+    s = "" if text is None or text is _js.UNDEFINED else _js.js_string(text)
+    if not s.startswith(LINK_PREFIX):
+        return None
+    pieces = s[len(LINK_PREFIX):].split(".")
+    ref = pieces[0]
+    pub = pieces[1] if len(pieces) > 1 else ""
+    if len(pieces) > 2 or not re.fullmatch(r"[0-9a-f]{32}", ref) or not re.fullmatch(r"[A-Za-z0-9_-]{44}", pub):
+        return None
+    return {"ref": ref, "pub": pub}
+
+
+def seal_to_challenge(challenge: dict, payload: Any) -> dict:
+    """The GIVING side (a signed-in device): seal a payload to a scanned challenge → what it POSTs to /api/link."""
+    theirs = _import_pub(challenge["pub"])
+    mine = ec.generate_private_key(ec.SECP256R1())
+    key = _shared_key(mine, theirs, challenge["ref"])
+    iv = os.urandom(12)
+    ct = key.encrypt(iv, _js.stringify(payload).encode("utf-8"), None)
+    return {"ref": challenge["ref"], "epk": _export_pub(mine.public_key()), "blob": b64u(iv + ct)}
+
+
+def open_link_reply(priv: ec.EllipticCurvePrivateKey, reply: dict) -> Any:
+    """Open what the ref handed back. Raises on anything that isn't ours and intact."""
+    key = _shared_key(priv, _import_pub(reply.get("epk")), reply.get("ref"))
+    raw = unb64u_loose(reply.get("blob"))
+    pt = key.decrypt(raw[:12], raw[12:], None)
+    return _js.parse(pt.decode("utf-8-sig", "replace"))
+
+
+def _ptr(x: Any) -> dict | None:
+    if isinstance(x, dict) and isinstance(x.get("room"), str) and isinstance(x.get("mk"), str) and x["room"] and x["mk"]:
+        return {"room": x["room"], "mk": x["mk"]}
+    return None
+
+
+def read_link_payload(p: Any) -> dict | None:
+    """What the receiving device applies, or None if there is no usable key in it."""
+    if not isinstance(p, dict) or not isinstance(p.get("master"), str) or not p["master"]:
+        return None
+    a = p.get("anchor")
+    anchor = None
+    if isinstance(a, dict) and a.get("method") in ("google", "email") and isinstance(a.get("email"), str) and a["email"]:
+        token = a.get("token")
+        if a["method"] != "email" or (isinstance(token, str) and token):
+            anchor = {"method": a["method"], "email": a["email"]}
+            if isinstance(token, str) and token:
+                anchor["token"] = token
+            if truthy(a.get("exp")):
+                anchor["exp"] = a["exp"]
+    rel = p.get("rel")
+    return {
+        "master": p["master"],
+        "code": p["code"] if isinstance(p.get("code"), str) else "",
+        "email": p["email"] if isinstance(p.get("email"), str) else "",
+        # Half a release is no release: a token-less rel must not look like one and skip the gated read.
+        "rel": {"gid": _js.js_string(rel.get("gid") if truthy(rel.get("gid")) else ""), "token": rel["token"]}
+        if isinstance(rel, dict) and isinstance(rel.get("token"), str) and rel["token"] else None,
+        "idx": _ptr(p.get("idx")),
+        "pipes": _ptr(p.get("pipes")),
+        "anchor": anchor,
+    }
+
+
+# ── recovery.js: where the account backup lives and how it opens ─────────────────────────────────────────────────────
+def _backup_hkdf(secret: bytes, info: str, n: int) -> bytes:
+    return HKDF(algorithm=hashes.SHA256(), length=n, salt=_BACKUP_SALT, info=info.encode()).derive(secret)
+
+
+def derive_keys_from_secret(secret: bytes) -> dict:
+    """{id (hex storage key), key (AES-GCM), wt (hex write token)} — separate HKDF labels, so the id can't reveal the key."""
+    if not secret or len(secret) < 16:
+        raise ValueError("bad_secret")
+    return {
+        "id": _backup_hkdf(secret, "id", 16).hex(),
+        "key": AESGCM(_backup_hkdf(secret, "enc", 32)),
+        "wt": _backup_hkdf(secret, "bak-write", 32).hex(),
+    }
+
+
+def seal(key: AESGCM, obj: Any) -> str:
+    iv = os.urandom(12)
+    return b64u(iv + key.encrypt(iv, _js.stringify(obj).encode("utf-8"), None))
+
+
+def unseal(key: AESGCM, blob: Any) -> Any:
+    """base64url(iv‖ciphertext) → object. Raises on a wrong key or any tamper."""
+    buf = unb64u_loose(blob)
+    return _js.parse(key.decrypt(buf[:12], buf[12:], None).decode("utf-8-sig", "replace"))

witbitz_code/folders.py

@@ -0,0 +1,250 @@
+""""Allow this folder": ONE card for a folder outside the project, for the whole conversation — spaces/public/codeFolders.js.
+
+OpenCode asks `external_directory` for the folder of EACH file it reaches and for each folder a command touches, so every
+new subfolder asked again. The card names the folder the ask belongs to (its git root, or the top folder under home), and
+allowing it adds `external_directory <folder>/* allow` to the session (connector.py), which covers everything inside.
+Held to the JS answers by tools/code-folders.vectors.json.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Callable
+from typing import Any
+
+FOLDER_ROUTE = "/witbitz/folder"
+
+_SYSTEM = ("/bin", "/boot", "/dev", "/etc", "/lib", "/lib32", "/lib64", "/libx32", "/proc", "/root", "/run", "/sbin", "/sys",
+           "/usr", "/var")
+_SECRET_PARTS = {".ssh", ".aws", ".gnupg", ".kube", ".docker", ".git"}
+_GLOB = re.compile(r"[*?\[\]{}]")
+
+
+def norm_abs(p: Any) -> str:
+    """posix.normalize for absolute paths; '' when not absolute."""
+    if not isinstance(p, str) or not p.startswith("/") or "\0" in p:
+        return ""
+    out: list[str] = []
+    for part in p.split("/"):
+        if not part or part == ".":
+            continue
+        if part == "..":
+            if out:
+                out.pop()
+        else:
+            out.append(part)
+    return "/" + "/".join(out)
+
+
+def _under(p: str, root: str) -> bool:
+    return p.startswith("/") if root == "/" else (p == root or p.startswith(root + "/"))
+
+
+def _parent(p: str) -> str:
+    return p[: p.rfind("/")] or "/"
+
+
+def folder_root(directory: Any, *, home: str = "", has_git: Callable[[str], bool] = lambda p: False) -> str | None:
+    """The folder an outside path belongs to; None when it must not be widened (home itself, "/", a system folder, a
+    secret store, a hidden folder right under home)."""
+    d = norm_abs(directory)
+    h = "" if norm_abs(home) == "/" else norm_abs(home)  # a home of "/" is no home to go by
+    if not d or d == "/" or (h and d == h) or _GLOB.search(d):
+        return None
+    if any(part in _SECRET_PARTS for part in d.split("/")):
+        return None
+    if any(_under(d, s) for s in _SYSTEM):
+        return None
+    if h and _under(h, d):
+        return None
+    in_home = bool(h) and _under(d, h)
+    if in_home and d[len(h) + 1:].startswith("."):
+        return None
+    p = d
+    while p != "/" and not (h and p == h) and p != "/tmp":  # never home or /tmp themselves, or above them
+        if in_home and not _under(p, h):
+            break
+        try:
+            git = bool(has_git(p))
+        except Exception:
+            git = False
+        if git:
+            return p
+        p = _parent(p)
+    if in_home:
+        return h + "/" + d[len(h) + 1:].split("/")[0]
+    if _under(d, "/tmp"):
+        return "/tmp" if d == "/tmp" else "/tmp/" + d[5:].split("/")[0]
+    return d
+
+
+def ask_dirs(ask: Any) -> list[str] | None:
+    pats = ask.get("patterns") if isinstance(ask, dict) and isinstance(ask.get("patterns"), list) else []
+    if not pats:
+        return None
+    dirs = []
+    for p in pats:
+        if not isinstance(p, str) or not p.endswith("/*"):
+            return None
+        d = norm_abs(p[:-2])
+        if not d or _GLOB.search(p[:-2]):
+            return None
+        dirs.append(d)
+    return dirs
+
+
+def folders_for_ask(ask: Any, *, home: str = "", has_git: Callable[[str], bool] = lambda p: False) -> list[str] | None:
+    if not isinstance(ask, dict) or ask.get("permission") != "external_directory":
+        return None
+    dirs = ask_dirs(ask)
+    if dirs is None:
+        return None
+    roots: list[str] = []
+    for d in dirs:
+        r = folder_root(d, home=home, has_git=has_git)
+        if not r:
+            return None
+        if r not in roots:
+            roots.append(r)
+    return roots
+
+
+def folder_rule(root: str) -> dict:
+    return {"permission": "external_directory", "pattern": root + "/*", "action": "allow"}
+
+
+def allowed_folders(rules: Any) -> list[str]:
+    last: dict[str, Any] = {}
+    for r in rules if isinstance(rules, list) else []:
+        if not isinstance(r, dict) or r.get("permission") != "external_directory":
+            continue
+        pattern = r.get("pattern")
+        if not isinstance(pattern, str) or not pattern.endswith("/*"):
+            continue
+        last[pattern] = r.get("action")
+    out: list[str] = []
+    for pattern, action in last.items():
+        d = norm_abs(pattern[:-2])
+        if action == "allow" and d and d != "/" and not _GLOB.search(pattern[:-2]) and d not in out:
+            out.append(d)
+    return out
+
+
+def inside_folders(path: Any, folders: Any) -> bool:
+    a = norm_abs(path)
+    return bool(a) and any(bool(r) and r != "/" and _under(a, r) for r in (norm_abs(f) for f in (folders if isinstance(folders, list) else [])))
+
+
+def folders_cover(ask: Any, folders: Any) -> bool:
+    dirs = ask_dirs(ask)
+    return dirs is not None and all(inside_folders(d, folders) for d in dirs)
+
+
+def display_path(p: str, home: str) -> str:
+    h = norm_abs(home)
+    return "~" + p[len(h):] if h and h != "/" and _under(p, h) else p
+
+
+# ── the route (tools/code-folders.mjs) ────────────────────────────────────────────────────────────────────────────────
+_MAX_DEPTH = 4  # sessions above the asking one
+_ASK_ID = re.compile(r"per[A-Za-z0-9_-]{1,80}")
+
+
+def _uri_component(s: str) -> str:
+    from urllib.parse import quote
+    return quote(s, safe="-_.!~*'()")  # encodeURIComponent
+
+
+def has_git_on_disk(p: str) -> bool:
+    import os
+    return os.path.exists(p + "/.git")  # a directory, or a file (a worktree or submodule)
+
+
+async def folder_route(*, method: Any, query: str, body: Any, pending: Callable[[str], Any], call: Callable[..., Any],
+                       home: str | None = None, has_git: Callable[[str], bool] = has_git_on_disk,
+                       log: Callable[[str], Any] = lambda m: None) -> tuple[int, str]:
+    """GET /witbitz/folder?directory=D&ask=ID → the folder(s) the card offers; POST {ask} → allow them for the conversation.
+    `pending(directory)` → waiting asks or None; `call(method, path, directory, body=None)` → (ok, status, json)."""
+    import os
+    from urllib.parse import parse_qs
+
+    from . import _js
+
+    home = home if home is not None else os.path.expanduser("~")
+
+    def out(st: int, o: Any) -> tuple[int, str]:
+        return st, _js.stringify(o)
+
+    def offer(folders: list[str]) -> list[dict]:
+        return [{"path": p, "display": display_path(p, home)} for p in folders]
+
+    q = parse_qs(query or "", keep_blank_values=True)
+    directory = (q.get("directory") or [""])[0]
+    if not directory.startswith("/"):
+        return out(400, {"error": "no project folder"})
+    ask_id = (q.get("ask") or [""])[0]
+    if method == "POST":
+        try:
+            parsed = _js.parse(body) if isinstance(body, str) and body else None
+        except ValueError:
+            parsed = None
+        ask_id = parsed.get("ask") if isinstance(parsed, dict) and isinstance(parsed.get("ask"), str) else ""
+    elif method != "GET":
+        return out(405, {"error": "GET or POST"})
+    if not _ASK_ID.fullmatch(ask_id):
+        return out(400, {"error": "not an approval id"})
+    lst = await pending(directory)
+    if lst is None:
+        return out(502, {"error": "OpenCode cannot say what is waiting right now"})
+    ask = next((a for a in lst if isinstance(a, dict) and a.get("id") == ask_id), None)
+    if ask is None:
+        return out(404, {"error": "that approval is no longer waiting"})
+    folders = folders_for_ask(ask, home=home, has_git=has_git)
+    if method == "GET":
+        return out(200, {"folders": offer(folders or [])})
+    if not folders:
+        return out(409, {"error": "this is not a folder to allow whole — allow it once instead"})
+
+    chain: list[str] = []
+    sessions: dict[str, Any] = {}
+    sid = ask.get("sessionID")
+    while isinstance(sid, str) and sid and sid not in chain and len(chain) <= _MAX_DEPTH:
+        try:
+            ok, _, data = await call("GET", f"/session/{_uri_component(sid)}", directory)
+        except Exception:
+            ok, data = False, None
+        if not ok or not data:
+            if not chain:
+                return out(502, {"error": "OpenCode did not return the session"})
+            break
+        chain.append(sid)
+        sessions[sid] = data
+        sid = data.get("parentID") if isinstance(data, dict) and isinstance(data.get("parentID"), str) else ""
+    for i, s_id in enumerate(chain):
+        s = sessions.get(s_id)
+        have = allowed_folders(s.get("permission") if isinstance(s, dict) else None)
+        missing = [folder_rule(f) for f in folders if f not in have]
+        if not missing:
+            continue
+        try:
+            ok, status, _ = await call("PATCH", f"/session/{_uri_component(s_id)}", directory, {"permission": missing})
+        except Exception:
+            ok, status = False, None
+        if not ok:
+            if i == 0:
+                return out(502, {"error": "OpenCode did not take the folder rule"})
+            log(f"code-folders: could not allow {', '.join(folders)} on {s_id} ({status if status is not None else 'no answer'})")
+    answered: list[str] = []
+    others = [x for x in lst if isinstance(x, dict) and x is not ask and x.get("permission") == "external_directory"
+              and x.get("sessionID") in chain and folders_cover(x, folders)]
+    for a in [ask, *others]:
+        try:
+            ok, _, _ = await call("POST", f"/permission/{_uri_component(a['id'])}/reply", directory, {"reply": "once"})
+        except Exception:
+            ok = False
+        if ok:
+            answered.append(a["id"])
+    if ask["id"] not in answered:
+        return out(502, {"error": "the folder is allowed, but OpenCode did not take the answer — allow it again"})
+    log(f"code-folders: allowed {', '.join(folders)} for {chain[0]}")
+    return out(200, {"folders": offer(folders), "answered": answered})

witbitz_code/link.py

@@ -0,0 +1,205 @@
+"""Make this computer an ADDED DEVICE of a Spaces account by device-link — tools/rc-link.mjs.
+
+It shows a QR carrying an ephemeral PUBLIC key (no secret); a signed-in phone or desktop scans it (Settings → Back up &
+recovery → Add a device) and seals the account to that key; this process opens the reply. The reply is relayed
+content-blind through /api/link between two public keys the server cannot combine.
+
+Unlike rc-link.mjs this never writes the account to disk: the pairing flow needs it only long enough to publish the
+computer, so it stays in memory.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import math
+import os
+import re
+import sys
+import time
+from collections.abc import Callable
+from pathlib import Path
+from typing import Any
+
+from . import _js, devicelink, net, qr
+from ._js import truthy
+
+DEFAULT_ORIGINS = "https://spaces.witbitz.chat,https://witbitz-spaces.pages.dev"
+POLL_S = 2.5
+LIFE_MS = 300_000  # the ref stays valid until a seal is posted, so a slow (Google-failed → email-code) verification fits
+
+
+def parse_origins(env: Any) -> list[str]:
+    """Poll EVERY origin whose /api/link relay is live — the node connects whichever one the phone sealed the reply to."""
+    s = _js.js_string(env if truthy(env) else DEFAULT_ORIGINS)
+    return [o for o in (re.sub(r"/\Z", "", _js.trim(x)) for x in s.split(",")) if o]
+
+
+def _now_ms() -> int:
+    return int(time.time() * 1000)
+
+
+def account_from_payload(pay: Any) -> dict | None:
+    """The account this computer now belongs to, from an opened link payload: the master + the index-room pointer."""
+    if not isinstance(pay, dict) or not isinstance(pay.get("master"), str) or not pay["master"]:
+        return None
+    anchor = pay.get("anchor")
+    email = pay.get("email") if truthy(pay.get("email")) else (anchor.get("email") if isinstance(anchor, dict) else None)
+
+    def orelse(v: Any, dflt: Any) -> Any:
+        return v if truthy(v) else dflt
+
+    return {
+        "v": 1,
+        "linkedAt": _now_ms(),
+        "master": pay["master"],
+        "code": orelse(pay.get("code"), ""),
+        "email": orelse(email, ""),
+        "idx": orelse(pay.get("idx"), None),
+        "rel": orelse(pay.get("rel"), None),
+        "pipes": orelse(pay.get("pipes"), None),
+        "anchor": orelse(anchor, None),
+    }
+
+
+def _node_base64(s: str) -> bytes:
+    """Buffer.from(s, 'base64'): lenient — stops at '=', skips anything outside the alphabet."""
+    body = re.sub(r"[^A-Za-z0-9+/]", "", s.split("=", 1)[0])
+    body = body[: len(body) - (len(body) % 4 == 1)]
+    return _js.atob(body)
+
+
+async def pull_index_room(account: Any, origins: list[str], post_json: net.PostJson) -> dict | None:
+    """GAP-CLOSER: the link carried no index-room pointer → derive the backup location from the master, read the gated
+    backup with the release token, and take its indexRoom {room, mk}. Tries each origin; the pointer or None."""
+    if not isinstance(account, dict) or not truthy(account.get("master")):
+        return None
+    try:
+        master = _node_base64(_js.js_string(account["master"]).replace("-", "+").replace("_", "/"))
+    except ValueError:
+        return None
+    if len(master) != 32:
+        return None
+    loc = devicelink.derive_keys_from_secret(master)
+    rel = account.get("rel")
+    token = rel.get("token") if isinstance(rel, dict) else None
+    for origin in origins:
+        blob = None
+        if truthy(token):
+            try:
+                r = await post_json(f"{origin}/api/backup/release", {"token": token, "id": loc["id"]})
+                if isinstance(r, dict) and truthy(r.get("ok")) and truthy(r.get("blob")):
+                    blob = r["blob"]
+            except Exception:
+                pass  # try the next origin
+        if not blob:
+            continue
+        try:
+            payload = devicelink.unseal(loc["key"], blob)
+            ir = payload.get("indexRoom") if isinstance(payload, dict) else None
+            if isinstance(ir, dict) and truthy(ir.get("room")) and truthy(ir.get("mk")):
+                return ir
+        except Exception:
+            pass  # wrong key / tamper
+    return None
+
+
+def _write_private(path: Path, text: str) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    fd = os.open(path, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o600)
+    with os.fdopen(fd, "w", encoding="utf-8") as f:
+        f.write(text)
+    os.chmod(path, 0o600)
+
+
+def _out(*a: Any, **kw: Any) -> None:
+    print(*a, flush=True, **kw)
+
+
+def _err(*a: Any) -> None:
+    print(*a, file=sys.stderr, flush=True)
+
+
+async def link_node(*, life_ms: float | None = None, poll_s: float = POLL_S, origins: list[str] | None = None,
+                    get_json: net.GetJson | None = None, post_json: net.PostJson | None = None,
+                    challenge: devicelink.LinkChallenge | None = None, svg_path: Path | None = None,
+                    out: Callable = _out, err: Callable = _err) -> dict | None:
+    """Show the device-link QR and wait for a signed-in device to seal the account to this computer. Returns the account,
+    or None when it did not complete (expired, or a reply that would not open) — never exits the process."""
+    if origins is None:
+        origins = parse_origins(os.environ.get("RC_LINK_ORIGIN"))
+    if life_ms is None:
+        raw = os.environ.get("RC_LINK_WAIT_MS")
+        life_ms = _js.to_number(raw) if raw else LIFE_MS
+    client = None
+    if get_json is None or post_json is None:
+        client = net.new_client()
+        get_json = get_json or net.make_get_json(client)
+        post_json = post_json or net.make_post_json(client)
+    try:
+        return await _link(life_ms, poll_s, origins, get_json, post_json, challenge, svg_path, out, err)
+    finally:
+        if client is not None:
+            await client.aclose()
+
+
+async def _link(life_ms, poll_s, origins, get_json, post_json, challenge, svg_path, out, err) -> dict | None:
+    ch = challenge or devicelink.new_link_challenge()
+    out(f"witbitz-code: pairing this computer with your account · polling {', '.join(origins)}\n")
+    out(qr.qr_ansi(ch.text) + "\n")
+    svg = svg_path or Path.home() / ".witbitz-rc.link.svg"
+    try:
+        _write_private(svg, qr.qr_svg(ch.text) + "\n")
+        out(f"  (QR also saved to {svg} · raw: {ch.text})")
+    except OSError:
+        out(f"  (raw: {ch.text})")
+    wait_s = life_ms / 1000 if math.isfinite(life_ms) else 0
+    out(f"  waiting up to {round(wait_s)}s for your device to seal the account to this computer…\n")
+    until = time.monotonic() + wait_s
+    warned = False
+    while time.monotonic() < until:
+        await asyncio.sleep(poll_s)
+        r = None
+        for origin in origins:
+            try:
+                rr = await get_json(f"{origin}/api/link?ref={ch.ref}")
+            except Exception:
+                continue
+            if isinstance(rr, dict) and rr.get("reason") == "unavailable" and not warned:
+                err(f"witbitz-code: note — {origin} has no device-link relay; ignoring it.")
+                warned = True
+            if isinstance(rr, dict) and truthy(rr.get("ok")):
+                r = rr
+                break
+        if r is None:
+            continue  # 404 on all = not sealed yet
+        pay = None
+        try:
+            pay = devicelink.read_link_payload(devicelink.open_link_reply(ch.priv, {"ref": ch.ref, "epk": r.get("epk"), "blob": r.get("blob")}))
+        except Exception:
+            pass  # not ours / tampered
+        if not pay:
+            err("witbitz-code: a reply arrived but did not open — start again on both devices.")
+            return None
+        account = account_from_payload(pay)
+        if not account:
+            err("witbitz-code: the reply carried no account key.")
+            return None
+        via = "link" if account["idx"] else ""
+        if not account["idx"]:
+            out("witbitz-code: no index pointer in the link — recovering it from your account backup… ", end="")
+            idx = None
+            try:
+                idx = await pull_index_room(account, origins, post_json)
+            except Exception:
+                pass
+            if idx:
+                account["idx"], via = idx, "backup"
+                out("✓")
+            else:
+                out("not found (the release token may have expired — pair again)")
+        out(f"witbitz-code: ✓ linked as a device of {account['email'] or '(your account)'}")
+        room = account["idx"].get("room") if isinstance(account["idx"], dict) else None
+        out(f"  index room → {room} (via {via})" if account["idx"] else "  index room → (none)")
+        return account
+    err("witbitz-code: the code expired before your device sealed to it. Run it again for a fresh QR.")
+    return None

witbitz_code/net.py

@@ -0,0 +1,67 @@
+"""The few HTTP calls the pairing flow makes, behind small injectable functions (tests replace them; nothing here is
+retried or cached)."""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass
+from typing import Any
+
+import httpx
+
+from . import _js
+
+API = "https://api.witbitz.chat/v1/space"
+ORIGIN = "https://witbitz-spaces.pages.dev"
+
+
+@dataclass(frozen=True)
+class ApiReply:
+    status: int
+    j: Any  # the parsed JSON body, or None when it was not JSON
+
+
+ApiCall = Callable[[dict], Awaitable[ApiReply]]
+GetJson = Callable[[str], Awaitable[Any]]
+PostJson = Callable[[str, dict], Awaitable[Any]]
+
+
+def _json_of(r: httpx.Response) -> Any:
+    return _js.parse(r.content.decode("utf-8-sig", "replace"))  # fetch's r.json(): BOM dropped, then JSON.parse
+
+
+def make_api_call(client: httpx.AsyncClient) -> ApiCall:
+    """POST {op:'state', …} to the account API, as the Spaces app would (same Origin)."""
+    api = os.environ.get("RC_BASE") or API
+    origin = os.environ.get("RC_ORIGIN") or ORIGIN
+
+    async def call(body: dict) -> ApiReply:
+        r = await client.post(api, content=_js.stringify(body).encode("utf-8"),
+                              headers={"content-type": "application/json", "origin": origin})
+        try:
+            j = _json_of(r)
+        except ValueError:
+            j = None
+        return ApiReply(r.status_code, j)
+
+    return call
+
+
+def make_get_json(client: httpx.AsyncClient) -> GetJson:
+    async def get_json(url: str) -> Any:
+        return _json_of(await client.get(url, headers={"cache-control": "no-store"}))
+
+    return get_json
+
+
+def make_post_json(client: httpx.AsyncClient) -> PostJson:
+    async def post_json(url: str, body: dict) -> Any:
+        r = await client.post(url, content=_js.stringify(body).encode("utf-8"), headers={"content-type": "application/json"})
+        return _json_of(r)
+
+    return post_json
+
+
+def new_client() -> httpx.AsyncClient:
+    return httpx.AsyncClient(timeout=httpx.Timeout(30.0), follow_redirects=True)