evocode 0.1.0__py3-none-any.whl

evocode/keys.py

@@ -0,0 +1,137 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Recover your own coding (NCD) or SecurityAccess (L3) key from your own PSdZData — locally.
+
+One chain, keyed by the bootloader (BTLD) id read from the car:
+
+  "ncd" — coding signing key (Codier-Sign), from security/sec_ncdkeys.xml. (Re)signs an NCD.
+  "l3"  — Level-3 SecurityAccess key, from security/sec_auth_l3.xml. Unlocks a write session.
+
+Both are wrapped the same way: open the E-SYS PKCS#12 keystore in sec_security.lic with the derived
+password (evocode.psdz); RSA-unwrap the AES session key named by the key file's encKeyRef from
+sec_keyreference.xml; AES-128-CBC (IV=0) decrypt the BTLD's entry -> a PKCS#8 RSA private key. The
+modulus is public (baked into the HU); the private exponent is the secret, written only to a local
+file. Needs the `crypto` extra and nothing from BMW is embedded here.
+"""
+from __future__ import annotations
+
+import base64
+import re
+import xml.etree.ElementTree as ET
+from pathlib import Path
+from typing import Optional, Tuple
+
+from . import psdz
+
+KINDS = {
+    "ncd": {"file": "sec_ncdkeys.xml", "elem": "NCodSigKey", "use": "coding signature — (re)sign an NCD"},
+    "l3": {"file": "sec_auth_l3.xml", "elem": "AuthenticationKey", "use": "SecurityAccess — write unlock"},
+}
+_DIGESTS = {"MD5": "md5", "SHA-256": "sha256", "SHA256": "sha256", "SHA-1": "sha1"}
+
+
+def _local(tag: str) -> str:
+    return tag.rsplit("}", 1)[-1]
+
+
+def _bytes_of(s: str) -> bytes:
+    s = re.sub(r"\s+", "", s or "")
+    if re.fullmatch(r"[0-9a-fA-F]+", s) and len(s) % 2 == 0:
+        return bytes.fromhex(s)
+    return base64.b64decode(s)
+
+
+def _unwrap_session_key(keyref_path: Path, esys_priv, ref_name: Optional[str]) -> bytes:
+    """RSA-unwrap the AES session key. Select by the key file's exact encKeyRef: every SessionKey is
+    wrapped to the same E-SYS key, so any of them 'decrypts' — picking the wrong one yields garbage."""
+    from cryptography.hazmat.primitives.asymmetric import padding
+    root = ET.parse(keyref_path).getroot()
+    entries: list = []
+    for sk in root.iter():
+        if _local(sk.tag) != "SessionKey":
+            continue
+        ref = next(((c.text or "").strip() for c in sk.iter() if _local(c.tag).lower() == "reference"), None)
+        kd = next((c.text for c in sk.iter() if _local(c.tag).lower() == "keydata" and (c.text or "").strip()), None)
+        if kd:
+            entries.append((ref, kd))
+
+    def unwrap(text: str) -> bytes:
+        k = esys_priv.decrypt(_bytes_of(text), padding.PKCS1v15())
+        return k if len(k) in (16, 24, 32) else k[-16:]
+
+    if ref_name:
+        for r, t in entries:
+            if r == ref_name:
+                return unwrap(t)
+        for r, t in entries:
+            if r and ref_name in r:
+                return unwrap(t)
+    for _r, t in entries:                                    # last resort: first that unwraps sanely
+        try:
+            return unwrap(t)
+        except Exception:                                    # noqa: BLE001
+            continue
+    raise KeyError("no session key could be unwrapped from %s" % keyref_path)
+
+
+def _find_btld_entry(sec_path: Path, btld: str, elem: str) -> Tuple[bytes, dict]:
+    root = ET.parse(sec_path).getroot()
+    norm = btld.lower().lstrip("0") or "0"
+    for el in root.iter():
+        if _local(el.tag) != elem:
+            continue
+        text = ET.tostring(el, encoding="unicode").lower()
+        if ("btld-" + btld.lower()) in text or re.search(r"\b0*" + norm + r"\b", text):
+            kd = next((c for c in el.iter() if _local(c.tag).lower() in ("keydata", "key", "privatekey")), None)
+            if kd is not None and (kd.text or "").strip():
+                return _bytes_of(kd.text), kd.attrib
+    raise KeyError("no %s entry for BTLD %s in %s" % (elem, btld, sec_path))
+
+
+def recover(psdzdata: Path, btld: str, kind: str, keystore_password: bytes) -> dict:
+    """Recover the key dict (schema matches the shipped ncd_key.json / l3_key.json)."""
+    if kind not in KINDS:
+        raise ValueError("kind must be one of %s" % sorted(KINDS))
+    from cryptography.hazmat.primitives.serialization import load_der_private_key, pkcs12
+    from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+
+    spec = KINDS[kind]
+    sec = Path(psdzdata) / "security"
+    lic, keyref, src = sec / "sec_security.lic", sec / "sec_keyreference.xml", sec / spec["file"]
+    for p in (lic, keyref, src):
+        if not p.exists():
+            raise FileNotFoundError("expected %s — is --psdzdata the psdzdata/ root?" % p)
+
+    esys_priv, _, _ = pkcs12.load_key_and_certificates(psdz.keystore_der(lic), keystore_password)
+    if esys_priv is None:
+        raise ValueError("no private key in sec_security.lic (derived keystore password rejected)")
+    ref_name = ET.parse(src).getroot().get("encKeyRef")
+    aes_key = _unwrap_session_key(keyref, esys_priv, ref_name)
+
+    body, attrib = _find_btld_entry(src, btld, spec["elem"])
+    dec = Cipher(algorithms.AES(aes_key), modes.CBC(b"\x00" * 16)).decryptor()
+    pt = dec.update(body) + dec.finalize()
+    if pt and pt[-1] <= 16:                                  # PKCS#5 unpad
+        pt = pt[:-pt[-1]]
+    priv = load_der_private_key(pt, password=None)
+    nums = priv.private_numbers()
+    pub = nums.public_numbers
+    dattr = next((v for k, v in attrib.items() if _local(k).lower() == "digestalg"), None)
+    return {
+        "btld": btld.upper(),
+        "kind": kind,
+        "use": spec["use"],
+        "scheme": next((v for k, v in attrib.items() if _local(k).lower() == "signaturescheme"), "BMWSigVerify"),
+        "digest": _DIGESTS.get((dattr or "").upper().replace(" ", "-"), "md5"),
+        "test_key": str(attrib.get("testKey", "")).lower() == "true",
+        "public_exponent": pub.e,
+        "modulus_hex": "%x" % pub.n,
+        "private_exponent_hex": "%x" % nums.d,
+    }
+
+
+def recover_from_install(psdzdata: Path, btld: str, kind: str, *, resource_jar: Optional[Path] = None,
+                         logo: Optional[Path] = None, mini: Optional[Path] = None) -> dict:
+    """Derive the keystore password from the PSdZ resources, then recover the key."""
+    password = psdz.derive_password(Path(psdzdata) / "security" / "sec_security.lic",
+                                    resource_jar=resource_jar, logo=logo, mini=mini)
+    return recover(psdzdata, btld, kind, password)

evocode/l3.py

@@ -0,0 +1,39 @@
+# SPDX-License-Identifier: Apache-2.0
+"""SecurityAccess "L3" — turn a requestSeed into a sendKey response with your own recovered key.
+
+The coding write (and flashing) unlock with this handshake: hash a block built from the seed, sign
+it raw-RSA with your L3 private key, and wire-encode the result a particular way. The algorithm is
+public; only the key is yours, and it is never shipped — you pass the ``l3_key.json`` you recovered
+from your own PSdZData.
+"""
+from __future__ import annotations
+
+import hashlib
+
+
+def _wordswap(b: bytes) -> bytes:
+    if len(b) % 4:
+        raise ValueError("length must be a multiple of 4")
+    return b"".join(b[i:i + 4][::-1] for i in range(0, len(b), 4))
+
+
+def sign_seed(seed: bytes, key: dict, btld: int = 0x00001FFD, user_id: int = 0x00000000) -> bytes:
+    """Bytes to send after ``27 02``: ``MD5([UserID][Controller][seed])`` signed raw-RSA ``e=3``
+    (little-endian), as a big-endian 32-bit word count followed by the per-word-swapped signature.
+
+    ``key`` is a dict with ``modulus_hex`` and ``private_exponent_hex`` (public exponent defaults to
+    3). ``btld`` is the module's bootloader id; ``user_id`` is the testerId sent with requestSeed
+    (0 matches the proven flow). Raises if the signature fails self-verification (wrong key).
+    """
+    if len(seed) != 8:
+        raise ValueError("seed must be 8 bytes, got %d" % len(seed))
+    n = int(key["modulus_hex"], 16)
+    d = int(key["private_exponent_hex"], 16)
+    e = int(key.get("public_exponent", 3))
+    block = user_id.to_bytes(4, "big") + btld.to_bytes(4, "big") + seed
+    m = int.from_bytes(hashlib.md5(block).digest(), "little")
+    s = pow(m, d, n)
+    if pow(s, e, n) != m:
+        raise ValueError("signature failed self-check — wrong L3 key?")
+    size = (n.bit_length() + 7) // 8
+    return (size // 4).to_bytes(4, "big") + _wordswap(s.to_bytes(size, "little"))

evocode/psdz.py

@@ -0,0 +1,171 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Derive the ``sec_security.lic`` keystore password from your own PSdZ install — nothing to type.
+
+PSdZ never stores this password; it computes it from resources that ship in the BMW runtime, and so
+do we (reproducing BMW's ``LicenseValidatorCrypto.genHashedPIN`` + ``ResourceParser``):
+
+    password = HEX_UPPER( SHA1( passphrase[pid] ) )
+
+``pid`` is an attribute of your own ``sec_security.lic``. ``passphrase[pid]`` comes from a ``<pplist>``
+hidden in two BMW logo PNGs in your PSdZ runtime's ``resource.jar``: ``bmw_logo.png`` carries the
+AES-CBC ciphertext, ``bmw_mini_logo.png`` carries the AES key — both steganographically, in the low
+two bits of every pixel. This module embeds none of it: point it at your own ``resource.jar``.
+
+The AES/PKCS parts need the ``crypto`` extra (``pip install 'evocode[crypto]'``); the PNG/stego
+decode is pure stdlib.
+"""
+from __future__ import annotations
+
+import base64
+import hashlib
+import struct
+import xml.etree.ElementTree as ET
+import zipfile
+import zlib
+from pathlib import Path
+from typing import Dict, Optional, Tuple
+
+LOGO = "bmw_logo.png"
+MINI_LOGO = "bmw_mini_logo.png"
+
+
+# ---- a minimal 8-bit truecolor PNG decoder (avoids a Pillow dependency for two images) ----
+
+def _paeth(a: int, b: int, c: int) -> int:
+    p = a + b - c
+    pa, pb, pc = abs(p - a), abs(p - b), abs(p - c)
+    return a if pa <= pb and pa <= pc else (b if pb <= pc else c)
+
+
+def decode_png_rgb8(data: bytes) -> Tuple[int, int, bytes]:
+    """Return (width, height, rgb) for an 8-bit, non-interlaced, truecolor-RGB PNG."""
+    if data[:8] != b"\x89PNG\r\n\x1a\n":
+        raise ValueError("not a PNG")
+    pos, width, height, idat = 8, 0, 0, bytearray()
+    while pos < len(data):
+        (length,) = struct.unpack(">I", data[pos:pos + 4])
+        ctype = data[pos + 4:pos + 8]
+        chunk = data[pos + 8:pos + 8 + length]
+        if ctype == b"IHDR":
+            width, height, depth, color, _c, _f, interlace = struct.unpack(">IIBBBBB", chunk)
+            if (depth, color, interlace) != (8, 2, 0):
+                raise ValueError("expected an 8-bit non-interlaced RGB PNG (BMW logo format)")
+        elif ctype == b"IDAT":
+            idat += chunk
+        elif ctype == b"IEND":
+            break
+        pos += 12 + length                                   # length(4) + type(4) + data + CRC(4)
+    raw = zlib.decompress(bytes(idat))
+    stride = width * 3
+    out, prev, p = bytearray(), bytes(stride), 0
+    for _ in range(height):
+        ftype = raw[p]; p += 1
+        line = bytearray(raw[p:p + stride]); p += stride
+        if ftype == 1:                                       # Sub
+            for x in range(3, stride):
+                line[x] = (line[x] + line[x - 3]) & 0xFF
+        elif ftype == 2:                                     # Up
+            for x in range(stride):
+                line[x] = (line[x] + prev[x]) & 0xFF
+        elif ftype == 3:                                     # Average
+            for x in range(stride):
+                left = line[x - 3] if x >= 3 else 0
+                line[x] = (line[x] + ((left + prev[x]) >> 1)) & 0xFF
+        elif ftype == 4:                                     # Paeth
+            for x in range(stride):
+                left = line[x - 3] if x >= 3 else 0
+                upleft = prev[x - 3] if x >= 3 else 0
+                line[x] = (line[x] + _paeth(left, prev[x], upleft)) & 0xFF
+        elif ftype != 0:
+            raise ValueError("unsupported PNG filter %d" % ftype)
+        out += line
+        prev = bytes(line)
+    return width, height, bytes(out)
+
+
+# ---- the steganographic payload (BMW ResourceParser.processImg) ----
+
+def extract_payload(png: bytes) -> bytes:
+    """Low 2 bits of R,G,B of every pixel (row 0 and column 0 skipped), packed three 2-bit groups to
+    one byte (+32 for printable ASCII), until '_'. The ASCII is a hex string; return its bytes."""
+    w, h, px = decode_png_rgb8(png)
+    tb: list = []
+    for row in range(1, h):
+        for col in range(1, w):
+            o = (row * w + col) * 3
+            tb.append(px[o] & 3)
+            tb.append(px[o + 1] & 3)
+            tb.append(px[o + 2] & 3)
+    chars = []
+    for i in range(0, len(tb) - 2, 3):
+        ch = chr((tb[i] | (tb[i + 1] << 2) | (tb[i + 2] << 4)) + 32)
+        if ch == "_":
+            break
+        chars.append(ch)
+    return bytes.fromhex("".join(chars))
+
+
+def passphrases(logo_png: bytes, mini_logo_png: bytes) -> Dict[str, str]:
+    """{pid: passphrase} from the two logo PNGs (mini = AES key, full = AES-CBC ciphertext of pplist)."""
+    from cryptography.hazmat.primitives.ciphers import Cipher, algorithms, modes
+    from cryptography.hazmat.primitives.padding import PKCS7
+
+    ciphertext = extract_payload(logo_png)
+    key = extract_payload(mini_logo_png)
+    if len(key) not in (16, 24, 32):
+        raise ValueError("unexpected AES key length %d from %s" % (len(key), MINI_LOGO))
+    dec = Cipher(algorithms.AES(key), modes.CBC(b"\x00" * 16)).decryptor()
+    padded = dec.update(ciphertext) + dec.finalize()
+    unpad = PKCS7(128).unpadder()
+    xml = unpad.update(padded) + unpad.finalize()
+    root = ET.fromstring(xml)
+    pps = {e.attrib["id"]: (e.text or "") for e in root.iter() if e.tag.endswith("passphrase")}
+    if not pps:
+        raise ValueError("no <passphrase> entries in the decoded pplist")
+    return pps
+
+
+# ---- the .lic wrapper + password ----
+
+def read_logos(resource_jar: Optional[Path], logo: Optional[Path], mini: Optional[Path]) -> Tuple[bytes, bytes]:
+    if logo and mini:
+        return Path(logo).read_bytes(), Path(mini).read_bytes()
+    if resource_jar:
+        with zipfile.ZipFile(resource_jar) as z:
+            names = z.namelist()
+
+            def grab(leaf: str) -> bytes:
+                hit = next((n for n in names if n.rsplit("/", 1)[-1] == leaf), None)
+                if hit is None:
+                    raise FileNotFoundError("%s not in %s" % (leaf, resource_jar))
+                return z.read(hit)
+
+            return grab(LOGO), grab(MINI_LOGO)
+    raise ValueError("need --resource-jar (your PSdZ/bin/psdz/resource.jar) or both logo PNGs")
+
+
+def parse_lic(lic_path: Path) -> Tuple[Optional[str], bytes]:
+    """sec_security.lic is ``<... pid="N">BASE64(PKCS#12)</...>``. Return (pid, pkcs12_der)."""
+    data = Path(lic_path).read_bytes()
+    try:
+        root = ET.fromstring(data)
+    except ET.ParseError:
+        return None, data                                    # already a raw .p12
+    return root.attrib.get("pid"), base64.b64decode((root.text or "").strip())
+
+
+def keystore_der(lic_path: Path) -> bytes:
+    return parse_lic(lic_path)[1]
+
+
+def derive_password(lic_path: Path, *, resource_jar: Optional[Path] = None,
+                    logo: Optional[Path] = None, mini: Optional[Path] = None) -> bytes:
+    """The PKCS#12 password for sec_security.lic: HEX_UPPER(SHA1(passphrase[pid])), as ASCII bytes."""
+    pid, _ = parse_lic(lic_path)
+    if pid is None:
+        raise ValueError("no pid attribute on %s" % lic_path)
+    logo_b, mini_b = read_logos(resource_jar, logo, mini)
+    pps = passphrases(logo_b, mini_b)
+    if pid not in pps:
+        raise KeyError("sec_security.lic pid=%s not among passphrases %s" % (pid, sorted(pps)))
+    return hashlib.sha1(pps[pid].encode("ascii")).hexdigest().upper().encode("ascii")

evocode/root.py

@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: Apache-2.0
+"""OPT_DEBUG root-access enable/revert — starter.cfg edit and flash orchestration.
+
+``starter.cfg`` is a QNX ``starter``-format XML config (``/fs/sda0/opt/sys/etc/starter.cfg``).
+Enabling root = flipping the ``OPT_DEBUG`` service from ``STOP`` to ``RUN``; reverting = the
+opposite. The patched file is wrapped in a SWDL no-signature container and flashed via the
+diagnostic channel (ENET/HSFZ → bootloader → L3 → transferData). See ``docs/root-access.md``.
+
+The ``starter.cfg`` is **build-specific**: a wrong-version config fails the next boot. This module
+takes the operator's own config as input — it never inlines a version-specific blob.
+"""
+from __future__ import annotations
+
+import re
+import socket
+from pathlib import Path
+from typing import Optional
+
+# The OPT_DEBUG line in starter.cfg — QNX starter XML:
+#   <Name>OPT_DEBUG</Name>\n      <RequestState>STOP</RequestState>
+_RE_STOP = re.compile(
+    r"(<Name>OPT_DEBUG</Name>\s*<RequestState>)STOP(</RequestState>)")
+_RE_RUN = re.compile(
+    r"(<Name>OPT_DEBUG</Name>\s*<RequestState>)RUN(</RequestState>)")
+
+
+def is_enabled(cfg: str) -> Optional[bool]:
+    """True if OPT_DEBUG is RUN, False if STOP, None if not found."""
+    if _RE_RUN.search(cfg):
+        return True
+    if _RE_STOP.search(cfg):
+        return False
+    return None
+
+
+def patch(cfg: str) -> str:
+    """STOP → RUN. Raises if already RUN or OPT_DEBUG not found."""
+    state = is_enabled(cfg)
+    if state is True:
+        raise ValueError("OPT_DEBUG is already RUN")
+    if state is None:
+        raise ValueError("OPT_DEBUG service not found in starter.cfg")
+    return _RE_STOP.sub(r"\g<1>RUN\g<2>", cfg, count=1)
+
+
+def unpatch(cfg: str) -> str:
+    """RUN → STOP. Raises if already STOP or not found."""
+    state = is_enabled(cfg)
+    if state is False:
+        raise ValueError("OPT_DEBUG is already STOP")
+    if state is None:
+        raise ValueError("OPT_DEBUG service not found in starter.cfg")
+    return _RE_RUN.sub(r"\g<1>STOP\g<2>", cfg, count=1)
+
+
+# ------------------------------------------------------------------------------- status probe
+
+STARTER_PATH = "/fs/sda0/opt/sys/etc/"
+STARTER_NAME = "starter.cfg"
+
+
+def check_ports(host: str, ports: tuple[int, ...] = (22, 23, 8000),
+                timeout: float = 2.0) -> dict[int, bool]:
+    """Probe whether OPT_DEBUG dev ports are open on the HU."""
+    result: dict[int, bool] = {}
+    for p in ports:
+        s = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        s.settimeout(timeout)
+        try:
+            s.connect((host, p))
+            result[p] = True
+        except (OSError, socket.timeout):
+            result[p] = False
+        finally:
+            s.close()
+    return result

evocode/srec.py

@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: Apache-2.0
+"""Motorola S-record (SREC) read/write for NBT EVO coding NCD files.
+
+An NCD stores each coding datagroup's bytes at address ``(datagroup << 8) + offset``. BMW/E-Sys
+export these as **S2** (24-bit address) data records, an S0 header, and an S5 record-count trailer;
+others use S3 (32-bit) with an S7 end record. We accept S1/S2/S3 data and re-emit each with the same
+address width, and we preserve the header and trailer records verbatim, so an edited file round-trips
+byte-for-byte except where data changed. The signature is over the datagroup *content*, never the
+record framing.
+"""
+from __future__ import annotations
+
+from typing import Dict, List, Tuple
+
+Mem = Dict[int, int]            # address -> byte
+Chunk = Tuple[int, int, int]    # (start address, length, address-byte-width)
+
+_ADDR_WIDTH = {"1": 2, "2": 3, "3": 4}        # data-record type -> address bytes
+_TYPE_FOR_WIDTH = {2: "1", 3: "2", 4: "3"}
+
+
+def _checksum(payload: bytes) -> int:
+    """S-record checksum: ones' complement of the low byte of the sum of count+address+data."""
+    return (~sum(payload)) & 0xFF
+
+
+def parse(text: str) -> Tuple[Mem, dict]:
+    """Parse SREC text into a {address: byte} map plus the metadata needed to re-emit it."""
+    mem: Mem = {}
+    chunks: List[Chunk] = []
+    header = None
+    trailer: List[str] = []
+    for line in text.splitlines():
+        line = line.strip()
+        if len(line) < 4 or line[0] != "S":
+            continue
+        stype = line[1]
+        count = int(line[2:4], 16)
+        body = bytes.fromhex(line[4:4 + count * 2])          # address + data + checksum
+        if stype == "0":
+            header = line
+        elif stype in _ADDR_WIDTH:
+            w = _ADDR_WIDTH[stype]
+            addr = int.from_bytes(body[:w], "big")
+            data = body[w:-1]                                # strip trailing checksum
+            for i, b in enumerate(data):
+                mem[addr + i] = b
+            chunks.append((addr, len(data), w))
+        elif stype in ("5", "6", "7", "8", "9"):             # record-count + end records
+            trailer.append(line)
+    return mem, {"header": header, "chunks": chunks, "trailer": trailer}
+
+
+def _data_record(addr: int, data: bytes, width: int) -> str:
+    count = width + len(data) + 1
+    body = addr.to_bytes(width, "big") + data
+    return "S%s%02X%s%02X" % (_TYPE_FOR_WIDTH[width], count, body.hex().upper(),
+                              _checksum(bytes([count]) + body))
+
+
+def count_record(n: int) -> str:
+    """An S5 record stating the number of preceding data records."""
+    body = n.to_bytes(2, "big")
+    count = len(body) + 1
+    return "S5%02X%s%02X" % (count, body.hex().upper(), _checksum(bytes([count]) + body))
+
+
+def emit(mem: Mem, meta: dict) -> str:
+    """Re-emit SREC text from a (possibly edited) mem, preserving address widths and trailer records."""
+    lines = [meta.get("header") or "S0030000FC"]
+    for chunk in meta["chunks"]:
+        addr, length = chunk[0], chunk[1]
+        width = chunk[2] if len(chunk) > 2 else 4
+        data = bytes(mem.get(addr + i, 0) for i in range(length))
+        lines.append(_data_record(addr, data, width))
+    lines.extend(meta.get("trailer") or ["S70500000000FA"])
+    return "\n".join(lines) + "\n"
+
+
+def pages(mem: Mem, datagroups) -> Dict[int, bytes]:
+    """{datagroup: contiguous bytes} for each requested datagroup present in mem (address = dg<<8)."""
+    out: Dict[int, bytes] = {}
+    for dg in datagroups:
+        base = dg << 8
+        run = bytearray()
+        i = 0
+        while (base + i) in mem:
+            run.append(mem[base + i])
+            i += 1
+        if run:
+            out[dg] = bytes(run)
+    return out
+
+
+def set_byte(mem: Mem, dg: int, off: int, val: int, mask: int = 0xFF, shift: int = 0) -> None:
+    """Edit one coding byte in place: mem[dg,off] = (old & ~mask) | ((val<<shift) & mask)."""
+    addr = (dg << 8) + off
+    mem[addr] = (mem.get(addr, 0) & ~mask) | ((val << shift) & mask)