rttp 0.1.0__py3-none-any.whl

rttp/__init__.py

@@ -0,0 +1,61 @@
+"""
+rttp — RTTP reference implementation (RFC-002 §4.1 framing · §10 addressing · §11 mapping)
+
+**Zero dependencies.** Everything in the core package runs on the Python standard
+library alone. The optional Ed25519 seal backend is the single exception and is
+opt-in: `pip install rttp[ed25519]`.
+
+    >>> from rttp import pulse_header, rttp_uri
+    >>> parsed = rttp_uri.parse("rttp://brain.epoekie.aicent/verify")
+    >>> raw = pulse_header.build_for_uri(1, 255, 1, parsed["canonical_uri"],
+    ...                                  aid_origin=bytes(32))
+    >>> pulse_header.verify(raw)["action"]
+    'verify'
+
+Self-check (this is the point of the package — a stranger can verify an
+independent implementation in one command):
+
+    $ python -m rttp.selftest
+
+Modules
+-------
+`pulse_header`  PulseHeader128 codec — the 128-byte hardware-aligned frame header.
+`rttp_uri`      `rttp` URI validation, canonicalisation and ROUTE_SHARD derivation.
+`seal`          Radiant Seal, managed profile — symmetric HMAC-SHA256 over a
+                pre-shared key table. Suitable for a closed set of mutually
+                known roles.
+`seal_asym`     Radiant Seal, sovereign profile — Ed25519, self-certifying:
+                AID = SHA-256(public key), no issuance and no registry.
+`aid`           Autonomous Identity derivation.
+
+Authority boundary
+------------------
+* URI **syntax** — RFC-002 §10.2 ABNF. This package adds no syntax.
+* Frame **layout** — RFC-002 §4.1, extended by SPEC/RTTP-FRAME-EXT-v1.2.6.md.
+* Each module docstring names its own authority; where the spec is silent, the
+  module says so rather than inventing a rule.
+"""
+
+from . import aid, pulse_header, rttp_uri, seal
+from .pulse_header import PulseHeaderError
+from .rttp_uri import RttpUriError
+
+__version__ = "0.1.0"
+
+#: The protocol revision this package implements. Mirrors `pulse_header.SPEC_REV`.
+SPEC_REV = pulse_header.SPEC_REV
+
+#: The RTTP specification release these vectors were generated against.
+SPEC_RELEASE = "v1.2.6"
+
+__all__ = [
+    "aid",
+    "pulse_header",
+    "rttp_uri",
+    "seal",
+    "PulseHeaderError",
+    "RttpUriError",
+    "__version__",
+    "SPEC_REV",
+    "SPEC_RELEASE",
+]

rttp/aid.py

@@ -0,0 +1,35 @@
+"""
+AID — Autonomous Identity（对齐 demo.rs: AID::derive_from_entropy）
+
+demo.rs 原文: let node_aid = AID::derive_from_entropy(node_seed);
+             NODE_AID_GENESIS: {:032X}  →  genesis_shard 为 u128（16 字节）
+
+本模块以 SHA-256 派生 256-bit 身份 DNA（双分片: Genesis^Resonance），
+与 RFC-002 §4.1 的 AID_ORIGIN (0x46, 256-bit) 字段直接对应。
+"""
+
+import hashlib
+
+# 交换机（Imperial Nerve）的熵种子 —— 与 demo.rs 中的种子一致
+SWITCH_SEED = b"imperial_nerve_genesis_2026_radiant_totality"
+
+
+def derive_from_entropy(seed: bytes) -> dict:
+    """从熵种子派生 256-bit AID（双分片）。"""
+    aid = hashlib.sha256(seed).digest()
+    return {
+        "aid": aid,                                # 32B 完整身份 DNA
+        "genesis_shard": aid[:16],                 # u128 Genesis 分片
+        "resonance_shard": aid[16:],               # u128 Resonance 分片
+        "genesis_shard_hex": aid[:16].hex().upper(),
+        "aid_hex": aid.hex(),
+    }
+
+
+def agent_seed(role: str) -> bytes:
+    """各 Agent 角色的确定性熵种子。"""
+    return f"rttp_agent_{role}_genesis_2026".encode()
+
+
+def switch_aid() -> dict:
+    return derive_from_entropy(SWITCH_SEED)

rttp/pulse_header.py

@@ -0,0 +1,254 @@
+"""
+PulseHeader128 — RFC-002 §4.1 官方 128 字节硬件对齐帧头
+
+（v1.3.0: 每个神经脉冲封装在临床级 PulseHeader128 中，
+  128-BYTE 硬件对齐结构，与 CPU 双缓存行共振。）
+
+字段布局（大端，与 RFC-002 §4.1 表逐一对应）:
+    0x00  u32   RTTP_MAGIC    0x52545450（物理寄存器门验证）
+    0x04  u128  VERSION_ID    锁定 130（v1.3.0-Alpha）
+    0x14  u128  SEQUENCE_ID   单调脉冲序号（12ns 审计用）
+    0x24  u128  TIMESTAMP     绝对纳秒发射时刻（12ns 精度）
+    0x34  u8    TTL_PULSE     跳数上限（255 后脉冲蒸发）
+    0x35  u8    PRIORITY      128-bit 分流权重（255 = Sovereign）
+    0x36  u128  ROUTE_SHARD   12ns 抖动对齐的 Hive 导航哈希
+    0x46  32B   AID_ORIGIN    256-bit 双分片身份 DNA（Genesis^Resonance）
+
+--- v1.2.6 起：保留区分配（详见 SPEC/RTTP-FRAME-EXT-v1.2.6.md）---
+    0x66  u8    SPEC_REV      0 = v1.2.6 之前（整块全零）; 1 = v1.2.6
+    0x67  u8    FLAGS         bit0 = URI_ANCHORED; 其余位在 v1.2.6 MUST 为 0
+    0x68  u8    ACTION_LEN    ACTION 有效字节数（0 = action 省略）
+    0x69  16B   ACTION        §10.2 action 动词（小写 ASCII，右补 0x00）
+    0x79  7B    RESERVED      v1.2.6 MUST 全零
+
+⚠ **0x00–0x65 一个字节都没有改动**，VERSION_ID 亦保持 130。
+   扩展只填「原本就是零」的保留区，因此只读 0x00–0x65 的旧实现天然兼容。
+"""
+
+import struct
+import time
+
+try:                        # pip 安装后：作为包内模块导入
+    from . import rttp_uri
+except ImportError:         # 平铺布局（DEMO/ 目录）：作为同目录脚本导入
+    import rttp_uri         # action 语法（§10.2）唯一权威所在，避免规则重写
+
+# ---- 固定区 ----
+SIZE = 128
+MAGIC = 0x52545450          # "RTTP"
+VERSION_ID = 130            # v1.3.0-Alpha
+AID_ORIGIN_OFFSET = 0x46
+
+# ---- 扩展块（v1.2.6）----
+SPEC_REV = 1
+
+OFF_SPEC_REV = 0x66
+OFF_FLAGS = 0x67
+OFF_ACTION_LEN = 0x68
+OFF_ACTION = 0x69
+ACTION_MAX_LEN = 16
+OFF_RESERVED = 0x79
+RESERVED_LEN = 7
+
+FLAG_URI_ANCHORED = 0x01
+
+# 读端只认这些 SPEC_REV；未知修订一律拒斥（fail closed）
+KNOWN_SPEC_REVS = (0, 1)
+
+
+class PulseHeaderError(Exception):
+    pass
+
+
+# ---------------------------------------------------------------------------
+# ACTION 编解码
+# ---------------------------------------------------------------------------
+
+def encode_action(action: str) -> bytes:
+    """action 动词 → 16 字节（小写 ASCII，右补 0x00）。"""
+    if action == "":
+        return bytes(ACTION_MAX_LEN)
+    if not rttp_uri.is_valid_action(action):
+        raise PulseHeaderError(
+            f"invalid action token {action!r} (RFC-002 §10.2: 1*( a-z / 0-9 / '-' ))")
+    raw = action.encode("ascii")
+    if len(raw) > ACTION_MAX_LEN:
+        raise PulseHeaderError(
+            f"action too long: {len(raw)} > {ACTION_MAX_LEN} bytes")
+    return raw + bytes(ACTION_MAX_LEN - len(raw))
+
+
+def decode_action(block16: bytes) -> str:
+    """16 字节 ACTION 区 → 动词字符串（字节级解码，不含语法校验）。"""
+    if len(block16) != ACTION_MAX_LEN:
+        raise PulseHeaderError("action block must be 16 bytes")
+    end = block16.find(b"\x00")
+    raw = block16 if end < 0 else block16[:end]
+    try:
+        return raw.decode("ascii")
+    except UnicodeDecodeError as exc:
+        raise PulseHeaderError(f"ACTION is not ASCII: {exc}") from exc
+
+
+# ---------------------------------------------------------------------------
+# 构造
+# ---------------------------------------------------------------------------
+
+def build(sequence_id: int, ttl: int, priority: int,
+          route_shard: bytes, aid_origin: bytes,
+          timestamp_ns: int = None,
+          action: str = "", uri_anchored: bool = False) -> bytes:
+    """按官方解剖表构造 128 字节帧头。
+
+    action / uri_anchored 为 v1.2.6 新增的**可选**参数：
+      * 不传时产出与旧实现逐字节相同的帧（SPEC_REV 仍写 1，见 spec §4 R6）
+      * action="" 表示 §10.4 的默认操作（standing read / 无动作谓词）
+    """
+    if len(route_shard) != 16:
+        raise PulseHeaderError("route_shard must be 16 bytes (u128)")
+    if len(aid_origin) != 32:
+        raise PulseHeaderError("aid_origin must be 32 bytes (256-bit)")
+    if not 0 <= sequence_id < (1 << 128):
+        raise PulseHeaderError("sequence_id out of u128 range")
+    if timestamp_ns is None:
+        timestamp_ns = time.time_ns()
+
+    action_block = encode_action(action)
+
+    buf = bytearray(SIZE)
+    struct.pack_into(">I", buf, 0x00, MAGIC)
+    buf[0x04:0x14] = VERSION_ID.to_bytes(16, "big")
+    buf[0x14:0x24] = sequence_id.to_bytes(16, "big")
+    buf[0x24:0x34] = timestamp_ns.to_bytes(16, "big")
+    buf[0x34] = ttl & 0xFF
+    buf[0x35] = priority & 0xFF
+    buf[0x36:0x46] = route_shard
+    buf[0x46:0x66] = aid_origin
+
+    # --- v1.2.6 扩展块 ---
+    buf[OFF_SPEC_REV] = SPEC_REV
+    buf[OFF_FLAGS] = FLAG_URI_ANCHORED if uri_anchored else 0x00
+    buf[OFF_ACTION_LEN] = len(action.encode("ascii")) if action else 0
+    buf[OFF_ACTION:OFF_ACTION + ACTION_MAX_LEN] = action_block
+    # 0x79..0x80 保持零（RESERVED）
+
+    return bytes(buf)
+
+
+def build_for_uri(sequence_id: int, ttl: int, priority: int,
+                  uri: str, aid_origin: bytes,
+                  timestamp_ns: int = None) -> bytes:
+    """从一条 `rttp` URI 直接构造帧头 —— 即 §10.4 所承诺的那次映射。
+
+    ROUTE_SHARD 由 authority 派生（而非脉冲序号），ACTION 取自 path。
+    """
+    parsed = rttp_uri.parse(uri)
+    return build(sequence_id, ttl, priority,
+                 route_shard=parsed["route_shard"],
+                 aid_origin=aid_origin,
+                 timestamp_ns=timestamp_ns,
+                 action=parsed["action"],
+                 uri_anchored=True)
+
+
+# ---------------------------------------------------------------------------
+# 解析 / 校验
+# ---------------------------------------------------------------------------
+
+def parse(raw: bytes) -> dict:
+    """解析并校验 128 字节帧头，返回字段字典（不判合法性，只做结构解码）。"""
+    if not isinstance(raw, (bytes, bytearray)) or len(raw) != SIZE:
+        raise PulseHeaderError(f"header must be exactly {SIZE} bytes")
+    raw = bytes(raw)
+    magic = struct.unpack_from(">I", raw, 0x00)[0]
+    if magic != MAGIC:
+        raise PulseHeaderError(f"bad RTTP_MAGIC: 0x{magic:08X}")
+
+    spec_rev = raw[OFF_SPEC_REV]
+    flags = raw[OFF_FLAGS]
+    action_len = raw[OFF_ACTION_LEN]
+    action = "" if spec_rev == 0 else decode_action(
+        raw[OFF_ACTION:OFF_ACTION + ACTION_MAX_LEN])
+
+    return {
+        "magic_ok": True,
+        "version_id": int.from_bytes(raw[0x04:0x14], "big"),
+        "sequence_id": int.from_bytes(raw[0x14:0x24], "big"),
+        "timestamp_ns": int.from_bytes(raw[0x24:0x34], "big"),
+        "ttl": raw[0x34],
+        "priority": raw[0x35],
+        "route_shard": raw[0x36:0x46],
+        "aid_origin": raw[0x46:0x66],
+        # --- v1.2.6 ---
+        "spec_rev": spec_rev,
+        "flags": flags,
+        "uri_anchored": bool(flags & FLAG_URI_ANCHORED),
+        "action": action,
+        "action_len": action_len,
+        "action_omitted": action_len == 0,
+    }
+
+
+def verify(raw: bytes, expected_aid_origin: bytes = None) -> dict:
+    """解析 + 校验版本、来源 AID 与扩展块，返回字段字典。
+
+    扩展块校验规则（spec §4 R1–R7）：
+      * SPEC_REV 不在 KNOWN_SPEC_REVS 内            → 拒斥
+      * SPEC_REV=0 但扩展块非全零                    → 拒斥（形态自相矛盾）
+      * SPEC_REV=1 但 RESERVED 非零 / FLAGS 未知位   → 拒斥
+      * ACTION_LEN > 16 / 有内嵌 NUL / 非 §10.2 语法 → 拒斥
+    """
+    fields = parse(raw)
+    if fields["version_id"] != VERSION_ID:
+        raise PulseHeaderError(
+            f"VERSION_ID mismatch: {fields['version_id']} != {VERSION_ID}")
+
+    spec_rev = fields["spec_rev"]
+    block = bytes(raw[OFF_SPEC_REV:SIZE])
+
+    if spec_rev not in KNOWN_SPEC_REVS:
+        raise PulseHeaderError(f"unknown SPEC_REV: {spec_rev} (fail closed)")
+    if spec_rev == 0:
+        if any(block):
+            raise PulseHeaderError(
+                "SPEC_REV=0 but extension block is not all-zero")
+    else:
+        if any(raw[OFF_RESERVED:SIZE]):
+            raise PulseHeaderError("RESERVED bytes must be zero in SPEC_REV=1")
+        unknown_flags = fields["flags"] & ~FLAG_URI_ANCHORED
+        if unknown_flags:
+            raise PulseHeaderError(
+                f"unknown FLAGS bits set: 0x{unknown_flags:02X}")
+
+        action_block = raw[OFF_ACTION:OFF_ACTION + ACTION_MAX_LEN]
+        action = fields["action"]
+        if fields["action_len"] > ACTION_MAX_LEN:
+            raise PulseHeaderError(
+                f"ACTION_LEN {fields['action_len']} > {ACTION_MAX_LEN}")
+        if fields["action_len"] != len(action.encode("ascii")):
+            raise PulseHeaderError("ACTION_LEN disagrees with ACTION payload")
+        # 补零区必须全零（不留夹缝）
+        if any(action_block[len(action.encode("ascii")):]):
+            raise PulseHeaderError("ACTION padding must be zero")
+        if action and not rttp_uri.is_valid_action(action):
+            raise PulseHeaderError(f"ACTION violates RFC-002 §10.2: {action!r}")
+
+    if expected_aid_origin is not None and \
+            fields["aid_origin"] != expected_aid_origin:
+        raise PulseHeaderError("AID_ORIGIN mismatch (spoofed origin?)")
+    return fields
+
+
+# ---------------------------------------------------------------------------
+# 十六进制编解码
+# ---------------------------------------------------------------------------
+
+def to_hex(header_bytes: bytes) -> str:
+    return header_bytes.hex()
+
+
+def from_hex(hex_str: str) -> bytes:
+    raw = bytes.fromhex(hex_str)
+    if len(raw) != SIZE:
+        raise PulseHeaderError("hex must decode to exactly 128 bytes")
+    return raw

rttp/rttp_uri.py

@@ -0,0 +1,214 @@
+"""
+rttp_uri — RFC-002 §10 `rttp` URI 解析 / 规范化 / ROUTE_SHARD 派生
+
+本模块是 RFC-002 §10.4 所承诺映射的**参考实现**：
+    "Dereferencing an `rttp` URI emits one pulse ... carrying `action` as the intent verb."
+规范此前只有语法（§10.2 ABNF），没有「URI → 帧字段」的映射；本模块与
+`SPEC/RTTP-FRAME-EXT-v1.2.6.md` 一起补上这一段。
+
+权威边界（重要）：
+    * URI **语法**唯一权威 = RFC-002 §10.2 ABNF。本模块不新增语法。
+    * 本模块只做两件事：① 按 §10.2/§10.3 校验并**规范化**；② 派生 ROUTE_SHARD。
+
+设计约束（逐条对应规范原文）：
+    * §10.1  intent 既可为 8 位小写 hex（32-bit routing hash），也可为可读 organ token
+    * §10.2  action 是**开集**：1*( %x61-7A / DIGIT / "-" )，例如 vessel / verify / pulse
+    * §10.3  规范形式为**小写 US-ASCII**；无 userinfo / port / query / fragment
+    * §10.5  **不解析 DNS**：ROUTE_SHARD 纯计算可得，不依赖任何注册表或网络
+
+ROUTE_SHARD 派生规则：见 spec §5。一句话：取 authority 的 SHA-256 前 16 字节。
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+# ---------------------------------------------------------------------------
+# 常量
+# ---------------------------------------------------------------------------
+
+SCHEME = "rttp"
+WEB_SCHEME = "web+rttp"                      # 浏览器处理器形态：容忍，非规范定义（2026-09-17 起规范不再定义它）
+
+ROUTE_SHARD_BYTES = 16                       # §4.1 ROUTE_SHARD = u128
+
+# §10.2:  name-intent / pillar / root / action = 1*( %x61-7A / DIGIT / "-" )
+_LOWER = "abcdefghijklmnopqrstuvwxyz"
+_DIGITS = "0123456789"
+_TOKEN_CHARS = frozenset(_LOWER + _DIGITS + "-")
+_HEX_CHARS = frozenset("0123456789abcdef")   # §10.2 lowhex = %x30-39 / %x61-66
+
+HASH_INTENT_LEN = 8                          # 8 位小写 hex = 32-bit routing hash
+
+# §10.3: 本 scheme 不定义 userinfo / port / query / fragment
+_FORBIDDEN_CHARS = ("@", "?", "#", "[", "]")
+
+
+class RttpUriError(ValueError):
+    """URI 不合规。**一律 fail closed**（§10.5：无 fallback，无 rttps）。"""
+
+
+# ---------------------------------------------------------------------------
+# 校验助手
+# ---------------------------------------------------------------------------
+
+def _check_token(value: str, what: str) -> None:
+    if not value:
+        raise RttpUriError(f"{what} is empty")
+    for ch in value:
+        if ch in _TOKEN_CHARS:
+            continue
+        if ch.isupper():
+            # §10.3 规范形式为小写。大写**不是**可归一化的书写差异，而是非法输入。
+            raise RttpUriError(
+                f"{what} contains uppercase '{ch}' - lowercase US-ASCII only (RFC-002 §10.3)")
+        raise RttpUriError(
+            f"{what} contains illegal character {ch!r} "
+            f"(allowed: a-z, 0-9, '-')")
+    if value[0] == "-" or value[-1] == "-":
+        raise RttpUriError(f"{what} must not begin or end with '-'")
+
+
+def _check_intent(value: str) -> bool:
+    """返回 True 表示 hash-intent（8 lowhex），False 表示 name-intent。"""
+    if len(value) == HASH_INTENT_LEN and all(c in _HEX_CHARS for c in value):
+        return True
+    _check_token(value, "intent")
+    return False
+
+
+def is_valid_action(value: str) -> bool:
+    """§10.2 action 语法判定：1*( %x61-7A / DIGIT / "-" )。
+
+    `action` 是**开集** —— 本函数只判**形态**，不判动词是否已知语义。
+    供帧层（`pulse_header`）复用，避免把同一条规则写两遍。
+    """
+    if not isinstance(value, str) or not value:
+        return False
+    if value[0] == "-" or value[-1] == "-":
+        return False
+    return all(c in _TOKEN_CHARS for c in value)
+
+
+# ---------------------------------------------------------------------------
+# 解析 / 规范化
+# ---------------------------------------------------------------------------
+
+def parse(uri: str) -> dict:
+    """解析一条 `rttp` URI，返回规范化字段。
+
+    校验顺序刻意保持「先拒斥、后解释」：任何可疑形态立即抛错，绝不猜测意图。
+    （§10.5: user agents that do not implement this scheme fail closed.）
+    """
+    if not isinstance(uri, str):
+        raise RttpUriError("uri must be a string")
+    if not uri:
+        raise RttpUriError("uri is empty")
+    if uri != uri.strip():
+        # 前后空白：可能是粘贴污染，也可能是绕过前缀检查的尝试 —— 拒斥。
+        raise RttpUriError("uri must not contain leading/trailing whitespace")
+
+    # --- scheme（§10.6 前缀白名单）---
+    if uri.startswith(WEB_SCHEME + "://"):
+        scheme = WEB_SCHEME
+        rest = uri[len(WEB_SCHEME) + 3:]
+    elif uri.startswith(SCHEME + "://"):
+        scheme = SCHEME
+        rest = uri[len(SCHEME) + 3:]
+    else:
+        raise RttpUriError(
+            f"not an rttp URI: must begin with '{SCHEME}://' or '{WEB_SCHEME}://'")
+
+    # --- §10.3 排除字符 ---
+    for ch in _FORBIDDEN_CHARS:
+        if ch in uri:
+            raise RttpUriError(
+                f"illegal character {ch!r}: this scheme defines no "
+                f"userinfo / query / fragment")
+
+    # --- authority 与 path ---
+    authority, sep, action = rest.partition("/")
+    if sep and "/" in action:
+        raise RttpUriError("path must be a single segment '/<action>'")
+    if sep and not action:
+        # §10.2: path = "/" action, action = 1*(...) —— 至少一个字符。
+        # "带空 action 的尾斜杠" 与 "无 path" 是两种不同形态，不可混同。
+        raise RttpUriError("trailing '/' with empty action: path must be '/<action>'")
+
+    parts = authority.split(".")
+    if len(parts) != 3:
+        raise RttpUriError(
+            f"authority must be exactly '<intent>.<pillar>.<root>' "
+            f"(got {len(parts)} segment(s))")
+    intent, pillar, root = parts
+
+    is_hash = _check_intent(intent)
+    _check_token(pillar, "pillar")
+    _check_token(root, "root")
+    if action:
+        _check_token(action, "action")
+
+    canonical_authority = f"{intent}.{pillar}.{root}"
+    canonical_uri = f"{SCHEME}://{canonical_authority}"
+    if action:
+        canonical_uri += f"/{action}"
+
+    return {
+        "scheme": scheme,
+        "intent": intent,
+        "intent_is_hash": is_hash,
+        "intent_hash32": int(intent, 16) if is_hash else None,
+        "pillar": pillar,
+        "root": root,
+        "action": action,                      # "" = 省略（§10.4 默认操作）
+        "action_omitted": action == "",
+        "authority": canonical_authority,
+        "canonical_uri": canonical_uri,
+        "route_shard": derive_route_shard(canonical_authority),
+    }
+
+
+# ---------------------------------------------------------------------------
+# ROUTE_SHARD 派生（本文件的核心；规范此前未定义）
+# ---------------------------------------------------------------------------
+
+def derive_route_shard(canonical_authority: str) -> bytes:
+    """authority → ROUTE_SHARD（16 字节）。
+
+    ROUTE_SHARD = SHA-256( ASCII(canonical_authority) )[0:16]
+
+    性质：
+      * **确定性**：同一 authority 永远同一 shard。
+      * **纯计算**：无 DNS、无注册表、无网络（§10.5）。
+      * **单向**：不可是从 shard 还原 authority（SHA-256 前像抗性）。
+      * **与 action 无关**：路由到「哪里」，不路由到「做什么」——
+        这正是 `action` 必须作为独立帧字段存在的原因（见 spec §5.3）。
+    """
+    if not canonical_authority:
+        raise RttpUriError("canonical_authority is empty")
+    if canonical_authority != canonical_authority.lower():
+        raise RttpUriError("canonical_authority must be lowercase (RFC-002 §10.3)")
+    return hashlib.sha256(canonical_authority.encode("ascii")).digest()[:ROUTE_SHARD_BYTES]
+
+
+def route_shard_hex(canonical_authority: str) -> str:
+    return derive_route_shard(canonical_authority).hex()
+
+
+def parse_and_derive(uri: str) -> dict:
+    """便捷入口：解析 + 派生，一步到位。"""
+    return parse(uri)
+
+
+if __name__ == "__main__":  # 手工冒烟
+    import sys
+
+    for arg in sys.argv[1:]:
+        try:
+            r = parse(arg)
+            print(f"OK    {r['canonical_uri']}")
+            print(f"      authority   = {r['authority']}")
+            print(f"      route_shard = {r['route_shard'].hex()}")
+            print(f"      action      = {r['action'] or '(omitted)'}")
+        except RttpUriError as exc:
+            print(f"REJECT {arg}\n      {exc}")

rttp/seal.py

@@ -0,0 +1,129 @@
+"""
+Radiant Seal — RTTP v1.3.0 节点签名验证（HMAC-SHA256）
+
+信任模型:
+    * 每个 Agent 持有独立 32 字节密钥（seal_keys.json 中 node-* 条目）
+    * 交换机持有 switch 密钥，发给 Agent 的数据包同样签名（双向验证）
+    * RTTP_IDENTIFY: 签名内容 = "role|ts|nonce"  （防重放：ts 偏差 > 120s 拒收）
+    * RTTP_RESPONSE: 签名内容 = task_id 与 result 的 sha256 绑定
+    * 未知角色 / 密钥缺失 → 拒绝（fail-closed）
+
+密钥文件缺失时进入 OPEN_MODE（仅本地开发用），并在每条日志中明示。
+"""
+
+import hashlib
+import hmac
+import json
+import os
+import secrets
+import time
+
+KEYFILE = os.path.join(os.path.dirname(os.path.abspath(__file__)),
+                       "seal_keys.json")
+MAX_CLOCK_SKEW = 120  # 秒
+
+_keys_cache = None
+
+
+def load_keys(force=False):
+    """读取密钥表；文件缺失时返回 None（OPEN_MODE）。"""
+    global _keys_cache
+    if _keys_cache is not None and not force:
+        return _keys_cache
+    if not os.path.exists(KEYFILE):
+        return None
+    with open(KEYFILE, "r", encoding="utf-8") as f:
+        _keys_cache = json.load(f)
+    return _keys_cache
+
+
+def open_mode() -> bool:
+    return load_keys() is None
+
+
+def _key_for(role: str) -> str:
+    keys = load_keys()
+    if keys is None:
+        return ""
+    return keys.get(role, "")
+
+
+def sign(message: str, key_hex: str) -> str:
+    return hmac.new(bytes.fromhex(key_hex), message.encode("utf-8"),
+                    hashlib.sha256).hexdigest()
+
+
+def verify(message: str, sig_hex: str, key_hex: str) -> bool:
+    if not key_hex or not sig_hex:
+        return False
+    return hmac.compare_digest(sign(message, key_hex), sig_hex)
+
+
+# ---- IDENTIFY 签名 ----
+
+def make_identify_challenge() -> dict:
+    return {"ts": int(time.time()), "nonce": secrets.token_hex(8)}
+
+
+def canonical_identify(role: str, ts: int, nonce: str) -> str:
+    return f"{role}|{ts}|{nonce}"
+
+
+def sign_identify(role: str, ts: int, nonce: str, key_hex: str) -> str:
+    return sign(canonical_identify(role, ts, nonce), key_hex)
+
+
+def verify_identify(role: str, ts: int, nonce: str, sig_hex: str) -> tuple:
+    """返回 (ok: bool, reason: str)。"""
+    if open_mode():
+        return True, "OPEN_MODE"
+    key = _key_for(role)
+    if not key:
+        return False, f"unknown role or missing key: {role}"
+    if abs(int(time.time()) - int(ts)) > MAX_CLOCK_SKEW:
+        return False, "timestamp skew too large (replay?)"
+    if verify(canonical_identify(role, ts, nonce), sig_hex, key):
+        return True, "sealed"
+    return False, "bad seal"
+
+
+# ---- RESPONSE 签名（Agent → 交换机）----
+
+def canonical_response(task_id: str, result: str) -> str:
+    result_digest = hashlib.sha256(result.encode("utf-8")).hexdigest()
+    return f"{task_id}|{result_digest}"
+
+
+def sign_response(task_id: str, result: str, key_hex: str) -> str:
+    return sign(canonical_response(task_id, result), key_hex)
+
+
+def verify_response(task_id: str, result: str, role: str, sig_hex: str) -> tuple:
+    if open_mode():
+        return True, "OPEN_MODE"
+    key = _key_for(role)
+    if not key:
+        return False, f"missing key for {role}"
+    if verify(canonical_response(task_id, result), sig_hex, key):
+        return True, "sealed"
+    return False, "bad seal"
+
+
+# ---- 交换机签名（交换机 → Agent，双向信任）----
+
+def canonical_packet(task_id: str, content: str) -> str:
+    return f"{task_id}|{content}"
+
+
+def sign_packet(task_id: str, content: str) -> str:
+    key = _key_for("switch")
+    if not key:
+        return ""
+    return sign(canonical_packet(task_id, content), key)
+
+
+def verify_packet(task_id: str, content: str, sig_hex: str) -> bool:
+    key = _key_for("switch")
+    if not key:
+        return True  # OPEN_MODE
+    return verify(canonical_packet(task_id, content), sig_hex, key)