tan-cli 0.7.0__py3-none-any.whl

tan/core/probe.py

@@ -0,0 +1,155 @@
+# SPDX-License-Identifier: Apache-2.0
+"""The two subprocess primitives every host/tool probe in `tan doctor` (and
+its git-provenance/build-side counterparts, `tan.core.doctor_git`) is built
+on. Extracted out of `tan.commands.doctor_cmd` (tan-cli#797 module-size
+budget) so `tan.core.doctor_git` can depend on them without an import cycle
+back into `doctor_cmd` -- `tan/core` is the layer BELOW `tan/commands`, never
+the reverse.
+
+Neither function can raise: every subprocess failure mode a fresh, possibly
+broken host can produce (missing binary, permission error, a probe that hangs
+forever, garbage output) is swallowed and turned into "no answer", never a
+traceback that would misrepresent a fixable environment problem as a tan bug.
+"""
+from __future__ import annotations
+
+import contextlib
+import os
+import re
+import subprocess
+import tempfile
+
+from tan.core.subprocess_env import spawn_env
+
+#: Every probe in this module gets the same ceiling: long enough for a slow
+#: but genuinely-answering tool, short enough that a hung one does not stall
+#: /a build's provenance read indefinitely.
+PROBE_TIMEOUT_S = 15
+
+
+_PYTHON_NAME = re.compile(r"^(py|python[\d.]*[tw]?)(\.exe)?$", re.IGNORECASE)
+#: `-c`, or a bundle ending in it (`-Ic`, `-Sc`, `-Bsc`).
+_DASH_C = re.compile(r"^-[A-Za-z]*c$")
+
+
+def isolated_cwd() -> "tempfile.TemporaryDirectory[str]":
+    """A fresh EMPTY directory to use as a child's cwd. `python -m <mod>` and
+    `python -c` put the cwd on `sys.path`, so a project directory can shadow
+    `pip`/`venv`/a stdlib module; every spawn that must not be hijackable runs
+    from here, with absolute path arguments (tan-cli#1317, #1331). The one
+    helper both the probes and `bootstrap_cmd.Runner.run(isolated=True)` use."""
+    return tempfile.TemporaryDirectory(prefix="tan-spawn-", ignore_cleanup_errors=True)
+
+
+def is_python_dash_c(argv: list[str]) -> bool:
+    """`<python> ... -c <code>`. With `-c`, `sys.path[0]` is the CWD, so a
+    `west.py`/`json.py` planted in the user's project or SDK dir would run
+    during a probe. Such probes run from a fresh EMPTY directory instead."""
+    return (
+        bool(argv)
+        and any(_DASH_C.match(a) for a in argv[1:])
+        and bool(_PYTHON_NAME.match(os.path.basename(argv[0])))
+    )
+
+
+def _absolute_for_new_cwd(argv: list[str], executable: str | None):
+    """The probe runs from a different cwd, so a RELATIVE program path (one with
+    a separator) must be made absolute first or it would stop resolving."""
+    def fix(p: str) -> str:
+        return os.path.abspath(p) if (os.sep in p or (os.altsep and os.altsep in p)) else p
+
+    return [fix(argv[0]), *argv[1:]], (fix(executable) if executable else executable)
+
+
+def probe_status(
+    argv: list[str], timeout: int = PROBE_TIMEOUT_S, executable: str | None = None
+) -> tuple[bool, str | None]:
+    """Run `argv` and return `(ran, stdout)`.
+
+    `executable`, when given, is `lpApplicationName`/POSIX `execve`'s own
+    program path -- the PATH-RESOLVED absolute location `tool_lookup.resolve_tool`
+    found, threaded through by a caller that needs `argv[0]` to stay the bare
+    identity (so a tool's own diagnostics keep printing the short name) while
+    the OS loads the hardened path instead of re-searching for the bare one
+    itself (tan-cli#797, the same `executable=` shape tan-cli#567 established
+    for the flash/size spawns).
+
+    `ran` is `True` exactly when the process was actually spawned AND exited
+    zero -- the one predicate that answers "could a build slice run this
+    binary at all". `stdout` is the captured text only when `ran` is `True`,
+    else always `None`. `probe()` below collapses both into a single `None`,
+    which is right for most callers (an unparseable version banner and a
+    binary that could not be spawned are both just "no answer") but wrong for
+    a caller that needs to tell "spawned fine, printed garbage" apart from
+    "never ran at all" -- `doctor_cmd.west_resolved_check` is exactly that
+    caller (tan-cli#488 defect 1): a `west` launcher whose file survives but
+    whose interpreter does not (a relocated workspace, a deleted
+    `.venv/bin/python`) is `is_file()`-true and therefore reaches this probe,
+    but every real invocation of it fails with `OSError`/a non-zero exit --
+    `probe()` alone cannot distinguish that from a `west` that ran and printed
+    something this command's regex could not parse, and reporting the former
+    as `pass` is the false green this function exists to close.
+
+    See `probe()` for why each failure mode below is swallowed rather than
+    raised.
+
+    `env=spawn_env()` (tan-cli#992): every probe in this module IS the
+    "does tan think this tool works" verdict, so a probe that leaked tan's
+    own bundled `LD_LIBRARY_PATH` into the child would report a perfectly
+    fine host tool as broken the moment its own bundled copy of some shared
+    library disagreed with the host's -- exactly the failure mode
+    `spawn_env` exists to close.
+    """
+    isolate = is_python_dash_c(argv)
+    if isolate:
+        argv, executable = _absolute_for_new_cwd(argv, executable)
+    scratch = (
+        isolated_cwd()
+        if isolate
+        else contextlib.nullcontext(None)
+    )
+    try:
+        with scratch as cwd:
+            out = subprocess.run(
+                argv,
+                executable=executable,
+                cwd=cwd,
+                capture_output=True,
+                text=True,
+                encoding="utf-8",
+                errors="replace",
+                stdin=subprocess.DEVNULL,
+                timeout=timeout,
+                env=spawn_env(),
+                check=False,
+            )
+    except (OSError, ValueError, subprocess.SubprocessError):
+        # SubprocessError covers TimeoutExpired (the child is already killed by
+        # `run`); ValueError catches an empty/garbage argv rather than letting
+        # it escape as a traceback.
+        return False, None
+    return (out.returncode == 0), (out.stdout if out.returncode == 0 else None)
+
+
+def probe(
+    argv: list[str], timeout: int = PROBE_TIMEOUT_S, executable: str | None = None
+) -> str | None:
+    """Run `argv` and return its stdout, or `None` for every way that can fail.
+
+    `None` means "no answer", never "the answer is bad" -- callers must not read
+    it as a verdict. The failure modes this swallows are all real on a fresh
+    host: the binary is absent (`FileNotFoundError`), it is a directory or not
+    executable (`OSError`/`PermissionError`), it waits forever on a probe that is
+    not plugged in (`TimeoutExpired`), or it exits non-zero.
+
+    `stdin` is closed, not inherited: a tool that decides to prompt then reads
+    EOF and dies instead of blocking until the timeout. `errors="replace"` is
+    the same reason `tests/conformance` uses it -- a tool answering in the
+    platform code page must not turn into a `UnicodeDecodeError` crash that
+    masquerades as a host problem.
+
+    A thin wrapper over `probe_status` (above) for every caller that only ever
+    wanted "the answer, or nothing" and has no use for the ran/did-not-run
+    split.
+    """
+    return probe_status(argv, timeout, executable=executable)[1]

tan/core/probe_plan.py

@@ -0,0 +1,237 @@
+# SPDX-License-Identifier: Apache-2.0
+"""tan-cli#1406: the pure half of `tan probe` -- argument parsing, the region
+safety rule and the read-only J-Link Commander scripts.
+
+`tan probe` exists so the bench never needs raw `JLinkExe` for two READ-ONLY
+questions: "which SW-DP / core is attached?" and "what do these words read?".
+Every script built here is `connect` plus `mem32` reads and `exit`; nothing in
+this module can emit a write, erase, `loadbin`, `setpc`, `go`, reset or
+`w1`/`w2`/`w4` command, and `FORBIDDEN_VERBS` is what the tests hold the
+generated scripts to.
+"""
+from __future__ import annotations
+
+import re
+from typing import Sequence
+
+from tan.core.ram_run import core_check_script, preamble
+
+CODE_BAD_ARGUMENT = "probe.bad-argument"
+CODE_READ_TOO_LARGE = "probe.read-too-large"
+CODE_READ_UNSAFE_REGION = "probe.read-unsafe-region"
+CODE_READ_FAILED = "probe.read-failed"
+CODE_FAILED = "probe.failed"
+
+#: Most words one `probe read` returns.
+MAX_WORDS = 256
+DEFAULT_WORDS = 4
+#: The generic Cortex-M55 attach profile (the --ram attach check's own).
+DEFAULT_DEVICE = "Cortex-M55"
+CORES = ("m55_he", "m55_hp")
+
+#: The window a session attached to the M55-HE must never touch: reading the HP
+#: ITCM global alias from an HE attach leaves the core unhaltable until a PIN reset
+#: (bench round 8, tan-cli#1354).
+UNSAFE_WINDOW = (0x50000000, 0x5FFFFFFF)
+
+#: Commander verbs a `probe` script must never contain (the tests scan for them).
+FORBIDDEN_VERBS = (
+    "w1", "w2", "w4", "w8", "write", "erase", "loadbin", "loadfile", "setpc", "go", "g",
+    "reset", "r", "rx", "halt", "h", "unlock", "wreg", "savebin", "setbp", "step", "s",
+)
+
+_HEX = re.compile(r"^0[xX][0-9A-Fa-f]{1,8}$")
+_DEC = re.compile(r"^[0-9]{1,10}$")
+
+
+class ProbeArgError(ValueError):
+    def __init__(self, code: str, message: str) -> None:
+        super().__init__(message)
+        self.code = code
+
+
+def parse_number(text: str, what: str) -> int:
+    """Plain hex (`0x...`) or decimal only -- no signs, underscores, expressions."""
+    text = text.strip() if isinstance(text, str) else ""
+    if _HEX.match(text):
+        return int(text, 16)
+    if _DEC.match(text):
+        return int(text, 10)
+    raise ProbeArgError(
+        CODE_BAD_ARGUMENT, f"{what} {text!r} is not a plain hex (0x...) or decimal number"
+    )
+
+
+def parse_read(address: str, count: str | int | None) -> tuple[int, int]:
+    """`(address, words)` for a `probe read`, or `ProbeArgError`."""
+    addr = parse_number(address, "the address")
+    if addr % 4:
+        raise ProbeArgError(CODE_BAD_ARGUMENT, f"address 0x{addr:X} is not 4-byte aligned")
+    if count is None:
+        words = DEFAULT_WORDS
+    else:
+        words = parse_number(str(count), "the word count")
+    if words < 1:
+        raise ProbeArgError(CODE_BAD_ARGUMENT, "the word count must be at least 1")
+    if words > MAX_WORDS:
+        raise ProbeArgError(
+            CODE_READ_TOO_LARGE,
+            f"{words} words requested; `tan probe read` returns at most {MAX_WORDS} "
+            "(1 KiB) per call",
+        )
+    if addr + 4 * words > 0x100000000:
+        raise ProbeArgError(CODE_BAD_ARGUMENT, "the read would run past the 32-bit address space")
+    return addr, words
+
+
+def normalise_core(core: str | None) -> str | None:
+    if core is None:
+        return None
+    value = core.strip().lower().replace("-", "_")
+    if value not in CORES:
+        raise ProbeArgError(CODE_BAD_ARGUMENT, f"--core {core!r} is not one of {', '.join(CORES)}")
+    return value
+
+
+def touches_unsafe_window(address: int, words: int) -> bool:
+    lo, hi = UNSAFE_WINDOW
+    return address <= hi and address + 4 * words - 1 >= lo
+
+
+def window_refusal(address: int, words: int) -> str | None:
+    """The refusal for ANY overlap with 0x50000000-0x5FFFFFFF, on every core -- there is
+    no HP exception: a bench-proven-safe HP read is not something an attach check can
+    establish (a multiple-AP banner or `conflict-hp` still looks HP-ish), so the window
+    is simply not readable through `tan probe`."""
+    if not touches_unsafe_window(address, words):
+        return None
+    return (
+        f"refusing to read 0x{address:08X}..0x{address + 4 * words - 1:08X}: `tan probe read` "
+        "refuses 0x50000000-0x5FFFFFFF on every core. From the HE that window is the HP ITCM "
+        "alias (reading it leaves the core unhaltable until a PIN reset), and tan does not "
+        "read it from any attach."
+    )
+
+
+def _slice_ambiguity(distinct: dict[str, set[str]]) -> str | None:
+    for key, values in distinct.items():
+        if len(values) > 1:
+            return (
+                f"the manifest's slices pin different {key} values ({', '.join(sorted(values))}); "
+                "pass --core to pick one, as `tan flash` requires"
+            )
+    return None
+
+
+def select_slice(
+    slices: Sequence[tuple[str, dict]], core: str | None
+) -> tuple[dict, str | None, str | None, str | None]:
+    """`(flash_args, selected core id, ambiguity message, note)` from `(core_id, flash_args)` pairs.
+
+    The args are taken whether or not `expect_dpidr` is armed (`jlink_serial`,
+    `jlink_speed`, `jlink_device` apply either way). With `--core` the matching slice
+    wins (no match: `{}` plus a `note`); without it one slice is used as is, and several
+    are acceptable only when they do not disagree on `jlink_serial` / `expect_dpidr`
+    (then the selected id is unknown). A `jlink_serial` pinned by exactly one of them is
+    carried onto the chosen args."""
+    pool = [(c, a) for c, a in slices if isinstance(a, dict)]
+    if core is not None:
+        matched = [(c, a) for c, a in pool if c.lower() == core]
+        if pool and not matched:
+            return {}, None, None, f"the manifest has no slice for --core {core}; its settings were not used"
+        pool = matched
+    if not pool:
+        return {}, None, None, None
+    if len(pool) == 1:
+        return dict(pool[0][1]), pool[0][0].lower(), None, None
+    distinct = {
+        key: {str(a[key]) for _c, a in pool if a.get(key) is not None}
+        for key in ("jlink_serial", "expect_dpidr")
+    }
+    problem = _slice_ambiguity(distinct)
+    if problem:
+        return {}, None, problem, None
+    armed = [a for _c, a in pool if a.get("expect_dpidr")]
+    chosen = dict((armed or [a for _c, a in pool])[0])
+    if chosen.get("jlink_serial") is None and distinct["jlink_serial"]:
+        chosen["jlink_serial"] = next(iter(distinct["jlink_serial"]))
+    return chosen, None, None, None
+
+
+def is_he_target(core: str | None, selected_id: str | None) -> bool:
+    """The target is the M55-HE: `--core m55_he`, or no `--core` and the manifest's
+    selected slice is the HE."""
+    return core == "m55_he" or (core is None and selected_id == "m55_he")
+
+
+def itcm_check_allowed(target_he: bool, attach_verdict: str) -> bool:
+    """The `mem32 0x0` / `mem32 0x58000000` session is bench-proven only from an HE attach:
+    send it only when the target is the HE AND session 1's banner placed the attach on
+    the HE access port (exactly `he`), never on the claim alone."""
+    return target_he and attach_verdict == "he"
+
+
+def itcm_skip_reason(core: str | None, selected_id: str | None, verdict: str) -> str:
+    """Why the ITCM corroboration was not run, and the fix, for the info issue."""
+    if core is None and selected_id is None:
+        return ("the target core is ambiguous (several manifest slices, or none, and no --core); "
+                "pass --core m55_he to corroborate an HE attach")
+    if not is_he_target(core, selected_id):
+        return (f"the target is {core or selected_id}, and the ITCM read is bench-proven only "
+                "from an HE attach; pass --core m55_he to corroborate an HE attach")
+    return (f"the connect banner placed the attach on '{verdict}', not the M55-HE access port, "
+            "so the HE-window read was not sent")
+
+
+def claimed_core(core: str | None, selected_id: str | None) -> str | None:
+    """`--core`, else the manifest's selected slice when that is one of the known cores."""
+    return core or (selected_id if selected_id in CORES else None)
+
+
+def core_contradiction(core: str | None, verdict: str) -> str | None:
+    """A message when the attach `verdict` (`ram_run` vocabulary, or the bare AP verdict)
+    contradicts the claimed `--core`; `None` when it agrees or says nothing."""
+    if core == "m55_he" and verdict == "conflict":
+        return f"--core m55_he, but the attach verdict is contradictory ({verdict})"
+    if core == "m55_he" and verdict in ("hp", "conflict-hp"):
+        return f"--core m55_he, but the probe attached to the M55-HP ({verdict})"
+    if core == "m55_hp" and verdict in ("he", "conflict"):
+        return f"--core m55_hp, but the probe attached to the M55-HE ({verdict})"
+    return None
+
+
+def dpidr_state(expected: str | None, actual: str | None) -> str | None:
+    """`None` when no `expect_dpidr` is armed or it matches; `"unread"` / `"mismatch"` else."""
+    if not expected:
+        return None
+    if actual is None:
+        return "unread"
+    try:
+        return None if int(actual, 16) == int(expected, 16) else "mismatch"
+    except ValueError:
+        return "mismatch"
+
+
+def identity_script(pre: Sequence[str]) -> str:
+    """The DP IDR read: exactly the Flow D / --ram DPIDR preflight --
+    `[SelectEmuBySN], si SWD, speed, device, connect, exit`."""
+    return "\n".join([*pre, "exit"]) + "\n"
+
+
+def core_script(pre: Sequence[str]) -> str:
+    """The --ram attach check, verbatim (`connect` + two read-only `mem32`)."""
+    return core_check_script(pre)
+
+
+def read_script(pre: Sequence[str], address: int, words: int) -> str:
+    """`connect`, ONE `mem32`, `exit`. Address and count are ints rendered with `0x%X`."""
+    return "\n".join([*pre, f"mem32 0x{address:X}, 0x{words:X}", "exit"]) + "\n"
+
+
+def make_preamble(serial: str | None, speed: int, device: str = DEFAULT_DEVICE) -> list[str]:
+    return preamble(serial, speed, device)
+
+
+def script_verbs(script: str) -> list[str]:
+    """The first token of every non-empty script line, lower-cased."""
+    return [ln.split()[0].lower() for ln in script.splitlines() if ln.split()]

tan/core/proxy.py

@@ -0,0 +1,168 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Which proxy environment variable applies to an `https://` request, whether
+`NO_PROXY` exempts the target from it, and whether this interpreter can actually
+route through the proxy that wins.
+
+Port of `crates/tan-core/src/proxy.rs`, which is the frozen oracle's rule and
+therefore the contract. Pure on purpose, for the same reason the Rust is:
+reading the environment is IO and belongs at the call site (`sdk_cmd`), while
+the *precedence rule* is a decision, and a decision with a scheme trap in it
+deserves tests that never mutate the process environment.
+
+**Why this module exists at all.** The port's one network call site used a bare
+`urllib.request.urlopen`, which builds its proxy handler from
+`getproxies_environment()`. That maps `ALL_PROXY`/`all_proxy` to the key `all`,
+and `ProxyHandler` then installs an `all_open` method that `OpenerDirector._open`
+-- which dispatches on `req.type`, i.e. `"https"` -- never calls. Measured
+against the live GitHub Releases API: with `HTTPS_PROXY` pointing at a closed
+port `tan sdk list --online` failed as it should (rc 1, `sdk.fetch-failed`,
+`[Errno 111] Connection refused`); with `ALL_PROXY` pointing at that SAME closed
+port and nothing else set, tan connected DIRECTLY and returned rc 0 with 13
+releases. So a host whose only egress is `ALL_PROXY` -- the spelling curl, git
+and the shipped Rust `tan` all honour -- was hard-broken, and a host with direct
+egress silently circumvented the proxy it was told to use (tan-cli#497 defect 8).
+
+**The precedence, MEASURED on the oracle rather than read off `proxy.rs`.** Two
+listening sockets, `ALL_PROXY=http://127.0.0.1:45001` and
+`HTTPS_PROXY=http://127.0.0.1:45002`, one `target/debug/tan sdk list`: the
+connection landed on **45001**. `ALL_PROXY` outranks `HTTPS_PROXY`, and the
+uppercase spelling outranks its lowercase alias. `HTTP_PROXY`/`http_proxy` are
+deliberately ABSENT: curl, git and urllib all treat those as http-only, and
+pushing an `https://` request through a plain-HTTP proxy that may refuse
+`CONNECT` would break a corporate host that worked fine going direct.
+
+**`NO_PROXY` is the other half of the same rule**, also measured: with
+`ALL_PROXY` at a listening socket and `NO_PROXY=api.github.com`, the oracle went
+direct and returned the release list (rc 0), and nothing ever reached the
+socket. Honouring the proxy without the bypass list would proxy a host that was
+deliberately exempted.
+
+**SOCKS is where this port cannot follow the oracle.** `crates/tan-cli/src/http.rs`
+compiles ureq's `socks-proxy` feature, and the oracle really does dial a
+`socks5://` `ALL_PROXY` (measured: the listener on port 45012 was hit).
+`urllib` has no SOCKS transport at all -- `ProxyHandler` would hand the request
+back to `OpenerDirector` under the type `socks5` and produce `unknown url type`.
+[`unsupported_proxy_scheme`] names that case so the call site can REFUSE with a
+message that says what happened, rather than falling back to a direct
+connection: silently bypassing a proxy the host mandated is the failure mode
+this whole module exists to remove, and doing it as the *fix* would be worse
+than the bug.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Callable
+
+#: Proxy env vars that apply to an `https://` URL, in the oracle's own
+#: precedence order (`ALL_PROXY` first, each lowercase alias immediately after
+#: its uppercase form). `HTTP_PROXY`/`http_proxy` are deliberately absent -- see
+#: the module docstring.
+HTTPS_PROXY_ENV_VARS = ("ALL_PROXY", "all_proxy", "HTTPS_PROXY", "https_proxy")
+
+#: Bypass-list env vars, uppercase first for the same reason. curl and git read
+#: exactly these two.
+NO_PROXY_ENV_VARS = ("NO_PROXY", "no_proxy")
+
+#: URL schemes `urllib` can actually carry a proxied `https://` request over.
+#: Anything else (`socks5`, `socks5h`, `socks4`, `socks4a`) needs a transport
+#: this interpreter does not ship -- see [`unsupported_proxy_scheme`].
+SUPPORTED_PROXY_SCHEMES = ("http", "https")
+
+
+def _first_set(keys: tuple[str, ...], lookup: Callable[[str], str | None]) -> str | None:
+    """The first key with a non-blank value, or `None`.
+
+    An empty value counts as UNSET: exporting `HTTPS_PROXY=` is the conventional
+    way to disable an inherited proxy, and treating it as a proxy URL would make
+    every request fail.
+    """
+    for key in keys:
+        value = lookup(key)
+        if value is not None and value.strip():
+            return value
+    return None
+
+
+def host_of(url: str) -> str:
+    """The host of an absolute URL -- no scheme, userinfo, port, path or
+    trailing root dot -- lowercased for comparison.
+
+    Deliberately not a URL parser: the one URL this path ever requests is one we
+    wrote ourselves (`sdk_cmd.GITHUB_RELEASES_URL`), so a parser would be more
+    moving parts than the two splits it replaces.
+    """
+    after_scheme = url.split("://", 1)[-1] if "://" in url else url
+    authority = after_scheme
+    for delimiter in ("/", "?", "#"):
+        authority = authority.split(delimiter, 1)[0]
+    host = authority.rsplit("@", 1)[-1]
+    return host.split(":", 1)[0].rstrip(".").lower()
+
+
+def no_proxy_covers(list_: str, host: str) -> bool:
+    """Does a `NO_PROXY` list cover `host` (already lowercased by [`host_of`])?
+
+    The rules are curl's, git's and Python's, because those are what the user's
+    existing `NO_PROXY` was written against:
+
+    * `*` as an entry bypasses the proxy for everything.
+    * Comma-separated; surrounding whitespace and empty entries are ignored, so
+      `"a, ,b"` is two entries and a trailing comma is harmless.
+    * Case-insensitive on both sides -- DNS is.
+    * An entry matches the host exactly, or as a suffix **on a label boundary**:
+      `github.com` and `.github.com` both cover `api.github.com`, while
+      `hub.com` covers neither. A bare `endswith` is the classic bug here -- it
+      would let `hub.com` silently disable the proxy for `github.com`.
+    * A `:port` on an entry is ignored rather than honoured: every request on
+      this path is `https://` on 443, so a port-qualified entry can only mean
+      443 anyway.
+    """
+    for raw in list_.split(","):
+        entry = raw.strip()
+        if entry == "*":
+            return True
+        entry = entry.split(":", 1)[0].strip(".").lower()
+        if not entry:
+            continue
+        if host == entry:
+            return True
+        if host.endswith(entry) and host[: -len(entry)].endswith("."):
+            return True
+    return False
+
+
+def select_https_proxy(
+    target_url: str, lookup: Callable[[str], str | None] | None = None
+) -> str | None:
+    """The proxy URL an `https://` request to `target_url` should go through, or
+    `None` for direct.
+
+    `lookup` is the injected environment read, defaulting to `os.environ.get`.
+    Takes the whole URL rather than a pre-extracted host so that deriving the
+    host is covered by this module's tests too.
+    """
+    read = os.environ.get if lookup is None else lookup
+    proxy = _first_set(HTTPS_PROXY_ENV_VARS, read)
+    if proxy is None:
+        return None
+    bypass = _first_set(NO_PROXY_ENV_VARS, read)
+    if bypass is not None and no_proxy_covers(bypass, host_of(target_url)):
+        return None
+    return proxy.strip()
+
+
+def unsupported_proxy_scheme(proxy_url: str) -> str | None:
+    """The scheme of `proxy_url` when `urllib` cannot route through it, else
+    `None`.
+
+    A bare `host:port` with no scheme is supported: `urllib._parse_proxy` treats
+    it as the request's own scheme, which is exactly the http(s) CONNECT path.
+    """
+    scheme, separator, _ = proxy_url.partition("://")
+    if not separator:
+        return None
+    scheme = scheme.lower()
+    if scheme in SUPPORTED_PROXY_SCHEMES:
+        return None
+    return scheme

tan/core/publish.py

@@ -0,0 +1,31 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Publish a finished temp file to its final name without ever overwriting or
+following a link -- shared by `tan model add` and `tan model prep`."""
+
+from __future__ import annotations
+
+import os
+import shutil
+from pathlib import Path
+
+
+def publish_exclusive(tmp: Path, dest: Path) -> None:
+    """Move the verified temp file to `dest` without ever overwriting or
+    following a link: a hard link fails if `dest` exists (even dangling); on a
+    filesystem without hard links, `O_EXCL|O_NOFOLLOW` creates it instead.
+    Raises `FileExistsError` / `OSError`."""
+    try:
+        os.link(tmp, dest)
+        return
+    except FileExistsError:
+        raise
+    except (OSError, NotImplementedError):
+        pass
+    flags = os.O_CREAT | os.O_EXCL | os.O_WRONLY | getattr(os, "O_NOFOLLOW", 0) | getattr(os, "O_BINARY", 0)
+    fd = os.open(dest, flags, 0o644)
+    try:
+        with open(tmp, "rb") as src, os.fdopen(fd, "wb") as out:
+            shutil.copyfileobj(src, out)
+    except BaseException:
+        dest.unlink(missing_ok=True)
+        raise