session_auth/family0: add LutGenerator and ChecksumTransform

Thirteenth slice of the HarpoS7 port (refs #717). Manual port of the
two GHASH-style transforms — both vector-verified against HarpoS7's
fixtures.

LutGenerator builds a 4 KB table of 256 UInt128 values from a 16-byte
seed by iterated GF(2¹²⁸) doubling under the AES-GCM-style reduction
polynomial x¹²⁸ + x⁷ + x² + x + 1.

ChecksumTransform consumes that table plus a 16-byte key to produce
a 16-byte integrity tag, walking key bytes MSB→LSB and rotating the
work buffer one byte after every 4-byte block.

Neither depends on the still-broken Monolith9/10 path.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

Author: gijzelaerr

s7/session_auth/family0/checksum_transform.py

@@ -0,0 +1,80 @@
+"""GF(2¹²⁸)-based checksum / GHASH-style integrity transform.
+
+Manual port of ``HarpoS7.Family0.Transforms.ChecksumTransform``. Takes
+a 16-byte key and a 4 KB lookup table (from ``lut_generator``) and
+produces a 16-byte checksum. The work buffer is a uint32[8] and the
+algorithm walks through key bytes from MSB to LSB, XORing in
+``lut[byte * 16 .. byte * 16 + 16]`` and rotating after every 4-byte
+block.
+"""
+
+from __future__ import annotations
+
+import struct
+
+KEY_SIZE = 0x10
+DESTINATION_SIZE = 0x10
+LOOKUP_TABLE_SIZE = 0x1000
+
+_U32 = 0xFFFFFFFF
+
+
+def _xor_128(work: list[int], offset: int, lut: list[int], lut_index: int) -> None:
+    """XOR four uint32s from ``lut[lut_index..lut_index+4]`` into
+    ``work[offset..offset+4]`` in place."""
+    for i in range(4):
+        work[offset + i] ^= lut[lut_index + i]
+
+
+def execute(destination: bytearray, key: bytes, lookup_table: bytes) -> None:
+    """Compute the 16-byte checksum.
+
+    Args:
+        destination: 16-byte buffer for the result.
+        key: 16-byte input key.
+        lookup_table: 4 KB table from ``lut_generator.execute``.
+    """
+    if len(destination) < DESTINATION_SIZE:
+        raise ValueError(f"destination must be at least {DESTINATION_SIZE} bytes")
+    if len(key) < KEY_SIZE:
+        raise ValueError(f"key must be at least {KEY_SIZE} bytes")
+    if len(lookup_table) < LOOKUP_TABLE_SIZE:
+        raise ValueError(f"lookup_table must be at least {LOOKUP_TABLE_SIZE} bytes")
+
+    work = [0] * 8
+
+    key_dwords = list(struct.unpack("<4I", bytes(key[:16])))
+    lut_dwords = list(struct.unpack(f"<{LOOKUP_TABLE_SIZE // 4}I", bytes(lookup_table[:LOOKUP_TABLE_SIZE])))
+
+    # Walk key bytes from byte 3 down to byte 1 (in each uint32 of the key).
+    for i in (0x18, 0x10, 0x08):
+        for j in range(4):
+            lut_index = ((key_dwords[j] >> i) & 0xFF) << 2
+            _xor_128(work, j, lut_dwords, lut_index)
+
+        # Rotate work buffer left by one byte.
+        for j in range(7, 0, -1):
+            work[j] = ((work[j - 1] >> 0x18) | ((work[j] << 0x08) & _U32)) & _U32
+        work[0] = (work[0] << 0x08) & _U32
+
+    # Final round: lowest byte of each key uint32.
+    for i in range(4):
+        lut_index = (key_dwords[i] & 0xFF) << 2
+        _xor_128(work, i, lut_dwords, lut_index)
+
+    # Final mixing.
+    temp = (((work[7] >> 0x0D) ^ work[7]) >> 0x11 ^ work[4] ^ work[7]) & _U32
+
+    dst = [0] * 4
+    dst[0] = (((((temp << 0x0D) & _U32) ^ temp) << 0x02) & _U32 ^ work[0] ^ temp) & _U32
+    dst[1] = (
+        ((temp >> 0x0D) ^ temp) >> 0x11 ^ ((((work[5] << 0x0D) & _U32) ^ work[5]) << 2) & _U32 ^ work[1] ^ temp ^ work[5]
+    ) & _U32
+    dst[2] = (
+        ((work[5] >> 0x0D) ^ work[5]) >> 0x11 ^ ((((work[6] << 0x0D) & _U32) ^ work[6]) << 2) & _U32 ^ work[2] ^ work[5] ^ work[6]
+    ) & _U32
+    dst[3] = (
+        ((work[6] >> 0x0D) ^ work[6]) >> 0x11 ^ ((((work[7] << 0x0D) & _U32) ^ work[7]) << 2) & _U32 ^ work[3] ^ work[6] ^ work[7]
+    ) & _U32
+
+    struct.pack_into("<4I", destination, 0, *dst)

s7/session_auth/family0/lut_generator.py

@@ -0,0 +1,75 @@
+"""Lookup-table generator used by ``ChecksumTransform`` (HarpoHash variant).
+
+Builds a 4 KB table of 256 ``UInt128`` entries from a 16-byte seed
+key. Each entry is the seed multiplied by ``i`` over GF(2¹²⁸) under
+the polynomial ``x^128 + x^7 + x^2 + x + 1`` (canonical AES-GCM
+field). The construction doubles iteratively and cross-XORs to fill
+the rest of the rows.
+
+Manual port of ``HarpoS7.Family0.Transforms.LutGenerator``.
+"""
+
+from __future__ import annotations
+
+import struct
+
+SOURCE_SIZE = 0x10
+DESTINATION_SIZE = 0x1000
+
+_U128 = (1 << 128) - 1
+_REDUCTION = 0x010000_8005  # x^128 + x^7 + x^2 + x + 1, low 33 bits
+
+
+def _to_u128_list(buf: bytes, count: int) -> list[int]:
+    """Read ``count`` little-endian 16-byte values as Python ints."""
+    out = []
+    for i in range(count):
+        out.append(int.from_bytes(bytes(buf[i * 16 : (i + 1) * 16]), "little"))
+    return out
+
+
+def _from_u128_list(values: list[int]) -> bytes:
+    parts = [(v & _U128).to_bytes(16, "little") for v in values]
+    return b"".join(parts)
+
+
+def execute(destination: bytearray, source: bytes) -> None:
+    """Generate the 4 KB lookup table from a 16-byte source.
+
+    Args:
+        destination: 4096-byte buffer to populate.
+        source: 16-byte seed key.
+    """
+    if len(destination) < DESTINATION_SIZE:
+        raise ValueError(f"destination must be at least {DESTINATION_SIZE} bytes, got {len(destination)}")
+    if len(source) < SOURCE_SIZE:
+        raise ValueError(f"source must be at least {SOURCE_SIZE} bytes, got {len(source)}")
+
+    # Initial layout:
+    #   dwords [0..4)  = 0       → quadDwords[0] = 0
+    #   dwords [4..8)  = source  → quadDwords[1] = source as UInt128
+    #   dwords [8..)   = 0       (zero-initialised destination)
+    quads = [0] * 256
+    quads[1] = int.from_bytes(bytes(source[:16]), "little")
+
+    i = 1
+    while i < 128:
+        multiplicand = quads[i]
+        product = (multiplicand * 2) & _U128
+        if (multiplicand >> 0x7F) != 0:
+            product ^= _REDUCTION
+
+        product_index = i * 2
+        quads[product_index] = product
+
+        for j in range(1, product_index):
+            quads[product_index + j] = quads[j] ^ product
+
+        i *= 2
+
+    destination[:DESTINATION_SIZE] = _from_u128_list(quads)
+
+
+# Backwards-compatible shim: tests can import via class-style or
+# function-style. The function entry point is canonical.
+del struct  # not used outside the helper functions

tests/fixtures/family0/transforms/transform3-dst.bin

@@ -0,0 +1 @@
+Gg"j.�����<��

tests/fixtures/family0/transforms/transform3-src.bin

@@ -0,0 +1 @@
+%%%%%%%%%%%%%%%%

tests/fixtures/family0/transforms/transform4-dst.bin

@@ -0,0 +1,30 @@
+"""Vector tests for the LutGenerator and ChecksumTransform Family-0 transforms.
+
+Vendored from ``HarpoS7.Family0.Tests/Transforms/TransformTests.cs``
+plus the corresponding ``Blobs/Transforms`` fixtures.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from s7.session_auth.family0 import checksum_transform, lut_generator
+
+_FIXTURES = Path(__file__).parent / "fixtures" / "family0" / "transforms"
+
+
+def test_lut_generator_vector() -> None:
+    src = (_FIXTURES / "transform3-src.bin").read_bytes()
+    expected = (_FIXTURES / "transform3-dst.bin").read_bytes()
+    dst = bytearray(lut_generator.DESTINATION_SIZE)
+    lut_generator.execute(dst, src)
+    assert bytes(dst) == expected
+
+
+def test_checksum_transform_vector() -> None:
+    key = (_FIXTURES / "transform4-key.bin").read_bytes()
+    lut = (_FIXTURES / "transform4-lut.bin").read_bytes()
+    expected = (_FIXTURES / "transform4-dst.bin").read_bytes()
+    dst = bytearray(checksum_transform.DESTINATION_SIZE)
+    checksum_transform.execute(dst, key, lut)
+    assert bytes(dst) == expected