feat(ppclock): 离线激活 keygen（ror2 公式+EFEF 反解 MAC）+ activate --auto；docs 终稿（firmware-analysis/protocol/PROGRESS），132 测试全绿

src/ppclock/protocol.py

@@ -162,3 +162,41 @@ def parse_device_id(data: bytes) -> str:
     if all(0x20 <= b < 0x7F for b in data):
         return data.decode("ascii")
     return data.hex().upper()
+
+
+def _ror2(v: int) -> int:
+    """8 位循环右移 2（证据 0x07FC24C8：(t<<6)+(t>>2) & 0xFF = ror2，非左移）。"""
+    return ((v << 6) + (v >> 2)) & 0xFF
+
+
+def keygen_code(mac: bytes) -> bytes:
+    """本地激活码：code[i] = ror2(((MAC[i]<<1)&0xFF)^0xEF) % 101，i=0..5。
+    证据：docs/firmware-analysis.md §4.2（keygen @0x07FC24C8，MAC=BD 地址，NVDS 顺序）。
+    EF 成败不门禁任何固件命令——激活仅影响屏显激活页。"""
+    if len(mac) != 6:
+        raise ValueError("MAC 必须 6 字节")
+    return bytes(_ror2(((b << 1) & 0xFF) ^ 0xEF) % 101 for b in mac)
+
+
+def recover_mac_from_device_id(device_id: str) -> bytes:
+    """14hex 设备 ID → 6B MAC。
+    ID = %02X(|MAC4-0x99|,|MAC5-0x99|,|MAC3-0x99|,|MAC2-0x99|,|MAC1-0x99|,|MAC0-0x99|,flags)，
+    flags bit i = MAC[i] ≥ 0x9A（证据 §4.2 生成函数 0x07FCA22C）。"""
+    if len(device_id) != 14:
+        raise ValueError("设备 ID 必须 14 个 hex 字符")
+    try:
+        vals = [int(device_id[i:i + 2], 16) for i in range(0, 14, 2)]
+    except ValueError:
+        raise ValueError("设备 ID 含非 hex 字符") from None
+    *v, flags = vals
+    # v 顺序：MAC4,MAC5,MAC3,MAC2,MAC1,MAC0 → 反映射
+    order = [4, 5, 3, 2, 1, 0]
+    mac = [0] * 6
+    for vi, idx in zip(v, order):
+        if flags & (1 << idx):
+            mac[idx] = 0x99 + vi
+        else:
+            mac[idx] = 0x99 - vi
+        if not 0 <= mac[idx] <= 0xFF:
+            raise ValueError("设备 ID 无法反解（掩码与差值矛盾）")
+    return bytes(mac)