tan-cli 0.7.0__py3-none-any.whl

tan/core/trusted_path.py

@@ -0,0 +1,134 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Is this path trustworthy as an interlock binary? (tan-cli#1452)
+
+The same rule PR #1454 (`flash_raw.py`, tan-cli#1457) applies to the
+reservation-enforcing J-Link wrapper: an ABSOLUTE path that resolves (symlinks
+followed) to an executable regular file outside the cwd, where BOTH chains --
+the path as written and the resolved target, each with its parents -- are owned
+by root or the current user and are not writable by others or by a group anyone
+else belongs to (a sticky directory is allowed).
+
+`tan reset` additionally requires the per-session lease nonce under
+`JLINK_RUN_PLACE` (tan-cli#1457): `reset_cmd` calls
+`flash_raw._reservation_refusal`, the same gate `tan flash --raw` uses. This module
+only judges the wrapper path; the two path checks are still separate copies.
+"""
+from __future__ import annotations
+
+import os
+import stat
+
+WRAPPER_ENV = "TAN_JLINK_WRAPPER"
+
+
+def _current_user() -> str:
+    """The account name of the real uid (never `USER`, which the caller controls)."""
+    import pwd  # noqa: PLC0415 (POSIX only: this module must import on Windows)
+
+    return pwd.getpwuid(os.getuid()).pw_name
+
+
+def _private_group(gid: int) -> bool:
+    """Whether `gid` is a group only the current user belongs to."""
+    import grp  # noqa: PLC0415 (POSIX only)
+    import pwd  # noqa: PLC0415
+
+    me = _current_user()
+    try:
+        members = set(grp.getgrgid(gid).gr_mem)
+    except KeyError:
+        return False
+    return members <= {me} and all(u.pw_name == me for u in pwd.getpwall() if u.pw_gid == gid)
+
+
+def _node_problem(node: str, st: os.stat_result) -> str | None:
+    mode = st.st_mode
+    sticky_dir = stat.S_ISDIR(mode) and bool(mode & stat.S_ISVTX)
+    if st.st_uid not in (0, os.getuid()):
+        return f"{node} is owned by uid {st.st_uid}, not root or you"
+    if stat.S_ISLNK(mode):
+        return None  # a symlink's own mode bits are always 0777 and mean nothing
+    if mode & stat.S_IWOTH and not sticky_dir:
+        return f"{node} is world-writable"
+    if mode & stat.S_IWGRP and not sticky_dir and not (
+        st.st_gid == os.getgid() and _private_group(st.st_gid)
+    ):
+        return f"{node} is group-writable by a group others belong to"
+    return None
+
+
+def _chain_problem(start: str) -> str | None:
+    node = start
+    while True:
+        try:
+            st = os.lstat(node)
+        except OSError:
+            return f"{node} cannot be inspected"
+        problem = _node_problem(node, st)
+        if problem:
+            return problem
+        parent = os.path.dirname(node)
+        if parent == node:
+            return None
+        node = parent
+
+
+def unsafe(path: str) -> str | None:
+    """Why `path` cannot be trusted as an interlock binary, or `None`."""
+    if not os.path.isabs(path):
+        return "is not an absolute path"
+    real = os.path.realpath(path)
+    cwd = os.path.realpath(os.getcwd())
+    if real == cwd or real.startswith(cwd + os.sep):
+        return "lives under the current directory"
+    if not (os.path.isfile(real) and os.access(real, os.X_OK)):
+        return "is not an executable file"
+    return _chain_problem(os.path.abspath(path)) or _chain_problem(real)
+
+
+#: Short reason codes (no paths): the operator's own `TAN_JLINK_WRAPPER` is already known.
+REASON_ENV_UNSET = "wrapper-env-unset"
+REASON_PATH_UNSAFE = "wrapper-path-unsafe"
+REASON_NOT_RESOLVED = "wrapper-not-resolved-binary"
+REASON_UNSUPPORTED = "unsupported-platform"
+
+
+def _supported() -> bool:
+    if not hasattr(os, "getuid"):
+        return False
+    try:
+        import grp  # noqa: F401, PLC0415
+        import pwd  # noqa: F401, PLC0415
+    except ImportError:
+        return False
+    return True
+
+
+def configured_wrapper() -> tuple[str | None, str | None]:
+    """`(path, None)` when `TAN_JLINK_WRAPPER` names a safe wrapper, else `(None, reason code)`."""
+    if not _supported():
+        return None, REASON_UNSUPPORTED
+    configured = os.environ.get(WRAPPER_ENV, "").strip()
+    if not configured:
+        return None, REASON_ENV_UNSET
+    if unsafe(configured) is not None:
+        return None, REASON_PATH_UNSAFE
+    return configured, None
+
+
+def is_configured_wrapper(exe: str | None) -> tuple[bool, str | None]:
+    """`(True, None)` only when `exe` IS the wrapper named by `TAN_JLINK_WRAPPER`
+    (absolute, trustworthy, same realpath). Otherwise `(False, reason code)`: a
+    marker string, a PATH name or a look-alike proves nothing. The trust is
+    operator-asserted: the variable attests a PATH, not that the file really masks
+    the other probes."""
+    if not _supported():
+        return False, REASON_UNSUPPORTED
+    configured = os.environ.get(WRAPPER_ENV, "").strip()
+    if not configured:
+        return False, REASON_ENV_UNSET
+    if unsafe(configured) is not None:
+        return False, REASON_PATH_UNSAFE
+    if not exe or not os.path.isabs(exe) or os.path.realpath(exe) != os.path.realpath(configured):
+        return False, REASON_NOT_RESOLVED
+    return True, None

tan/core/uboot_breakin.py

@@ -0,0 +1,154 @@
+# SPDX-License-Identifier: Apache-2.0
+"""U-Boot autoboot break-in: pure matching/timing logic for `tan monitor
+--break-uboot` (tan-cli#1315).
+
+The bench recipe is "power-cycle the board, then spam a key on the console
+until the `=> ` prompt appears". This module is that loop and nothing else: it
+takes an already-open port-like object (anything with `write(bytes)` and
+`read(size) -> bytes`; a pyserial `Serial`, a `loop://` port, an `rfc2217://`
+or `socket://` URL port, or a test fake), keeps sending the interrupt key,
+watches the received stream for the prompt, and stops the moment it is seen
+or the deadline passes. It never opens a port and never controls power --
+the operator or labgrid does the power-cycle.
+
+The clock is injected so the timing logic is testable without sleeping.
+"""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from dataclasses import dataclass
+from typing import Protocol
+
+#: pyserial `Serial` reads below this many seconds keep the loop responsive
+#: and also pace the key presses (one write per read window).
+DEFAULT_INTERVAL_S = 0.1
+DEFAULT_KEY = b" "
+DEFAULT_PROMPT = b"=> "
+DEFAULT_TIMEOUT_S = 30.0
+
+#: How much received text the envelope carries (`bytesSeenTail`), and how
+#: much is kept for prompt matching (a prompt cannot be longer than this).
+TAIL_BYTES = 256
+_MATCH_WINDOW = 4096
+
+
+class BytePort(Protocol):
+    def write(self, data: bytes, /) -> object: ...
+    def read(self, size: int = 1, /) -> bytes: ...
+
+
+@dataclass(frozen=True)
+class BreakInResult:
+    caught: bool
+    elapsed_s: float
+    bytes_seen: int
+    tail: str
+    keys_sent: int = 0
+    #: Seconds from the first key until the first byte came back (None if none did).
+    first_byte_s: float | None = None
+    #: The last (up to 4 KiB of) raw bytes received, so a caller can carry them
+    #: into the next phase (`--capture` after `--break-uboot`).
+    window: bytes = b""
+
+
+_SIMPLE_ESCAPES = {"r": b"\r", "n": b"\n", "t": b"\t", "\\": b"\\"}
+_HEX = "0123456789abcdefABCDEF"
+
+
+def parse_escaped(text: str, what: str) -> bytes:
+    """Turn a CLI string into bytes. Supported escapes: `\\xNN` (exactly two
+    hex digits), `\\r`, `\\n`, `\\t`, `\\\\`. Any other backslash sequence is
+    rejected rather than guessed at; other characters are taken literally
+    (UTF-8). Raises `ValueError` naming `what` on a bad escape or empty result.
+    """
+    out = bytearray()
+    i = 0
+    while i < len(text):
+        ch = text[i]
+        if ch != "\\":
+            out += ch.encode("utf-8")
+            i += 1
+            continue
+        nxt = text[i + 1 : i + 2]
+        if nxt in _SIMPLE_ESCAPES:
+            out += _SIMPLE_ESCAPES[nxt]
+            i += 2
+        elif nxt == "x" and len(text[i + 2 : i + 4]) == 2 and all(c in _HEX for c in text[i + 2 : i + 4]):
+            out.append(int(text[i + 2 : i + 4], 16))
+            i += 4
+        else:
+            raise ValueError(
+                f"{what} {text!r}: unsupported escape at position {i} "
+                "(allowed: \\xNN, \\r, \\n, \\t, \\\\)"
+            )
+    if not out:
+        raise ValueError(f"{what} must not be empty")
+    return bytes(out)
+
+
+def _tail_text(buf: bytes) -> str:
+    if len(buf) > TAIL_BYTES:
+        buf = buf[-TAIL_BYTES:]
+        # Do not start mid-way through a multibyte UTF-8 character.
+        while buf and 0x80 <= buf[0] < 0xC0:
+            buf = buf[1:]
+    return buf.decode("utf-8", errors="replace")
+
+
+def break_into_uboot(
+    port: BytePort,
+    *,
+    key: bytes = DEFAULT_KEY,
+    prompt: bytes = DEFAULT_PROMPT,
+    timeout_s: float = DEFAULT_TIMEOUT_S,
+    interval_s: float = DEFAULT_INTERVAL_S,
+    clock: Callable[[], float] = time.monotonic,
+) -> BreakInResult:
+    """Send `key` repeatedly until `prompt` is received or `timeout_s` passes.
+
+    One iteration = drain what is already waiting (return if the prompt is in
+    it), send a key if `interval_s` has passed since the last one, then one
+    `read` (the port's own read timeout, set by the caller to about
+    `interval_s`, paces the loop). The deadline is checked after the read, so
+    at least one key is always sent. At most the one key already in flight
+    when the prompt arrives is sent; none after.
+    """
+    start = clock()
+    deadline = start + timeout_s
+    window = b""
+    seen = 0
+    keys = 0
+    first_byte = None
+    last_write = None
+
+    def absorb(chunk: bytes) -> bool:
+        nonlocal window, seen, first_byte
+        if first_byte is None:
+            first_byte = clock() - start
+        seen += len(chunk)
+        window = (window + chunk)[-_MATCH_WINDOW:]
+        return prompt in window
+
+    def result(caught: bool) -> BreakInResult:
+        return BreakInResult(
+            caught, clock() - start, seen, _tail_text(window), keys, first_byte, window
+        )
+
+    while True:
+        # Drain everything already received BEFORE deciding to send another
+        # key, so no key goes out once the prompt is already in hand.
+        waiting = int(getattr(port, "in_waiting", 0) or 0)
+        if waiting and absorb(port.read(waiting) or b""):
+            return result(True)
+        now = clock()
+        if last_write is None or now - last_write >= interval_s:
+            port.write(key)
+            keys += 1
+            last_write = now
+        chunk = port.read(max(1, int(getattr(port, "in_waiting", 0) or 0))) or b""
+        if chunk and absorb(chunk):
+            return result(True)
+        if clock() >= deadline:
+            return result(False)