S17/S18: send success and failure routes; Sphinx HTML/PDF

Python router + Go sm-leaf reject missing to, empty ct, plaintext body.
Summary logs never include ciphertext. MODULE.md.

python/secure_messaging/__init__.py

@@ -4,6 +4,7 @@ from .envelope import PassthroughEnvelope  # dest-in-clear, body ciphertext
 from .error_bundle import NetworkErrorBundle  # system-key + sender-only
 from .admin_history import AdminHistory  # DataCube-shaped append-only config log
 from .npe_adapter import NpeRequired  # fail-closed NPE
+from .router import RouteResult, handle_send  # success/failure send policy
 
 __all__ = [
     "SignedConfig",
@@ -12,4 +13,6 @@ __all__ = [
     "NetworkErrorBundle",
     "AdminHistory",
     "NpeRequired",
+    "RouteResult",
+    "handle_send",
 ]

python/secure_messaging/router.py

@@ -0,0 +1,106 @@
+"""Passthrough send policy: accept good mail, reject bad, emit logging.
+
+Correct targeted messages get an ack with lookup_id.
+Incorrect messages take the failure path: Network Error Bundle shape,
+dead letter, and a summary log that never includes ciphertext.
+"""
+
+from __future__ import annotations  # annotations
+
+import json  # parse wire
+from typing import Any, Dict, List, Optional  # types
+
+from .error_bundle import NetworkErrorBundle, build_bundle, log_summary  # failure path
+
+
+ALLOWED_ALG = {"npe", "lab-xor", "plain-lab"}  # signed-config crypto.mode set
+
+
+class RouteResult:
+    """Outcome of one verae.sm.send."""
+
+    def __init__(
+        self,
+        *,
+        accepted: bool,
+        lookup_id: str = "",
+        error_code: str = "",
+        dest_class: str = "",
+        events: Optional[List[Dict[str, Any]]] = None,
+        bundle: Optional[NetworkErrorBundle] = None,
+    ):
+        self.accepted = accepted  # success path
+        self.lookup_id = lookup_id  # opaque sender handle
+        self.error_code = error_code  # empty on success
+        self.dest_class = dest_class  # mailbox | parse
+        self.events = events or []  # NATS publishes (subject, body)
+        self.bundle = bundle  # failure only
+
+    def ack(self) -> Dict[str, Any]:
+        """JSON reply to the sender (no ciphertext)."""
+        out = {"accepted": self.accepted, "lookup_id": self.lookup_id}  # always lookup
+        if self.error_code:  # failure
+            out["error_code"] = self.error_code  # machine code
+        return out  # wire ack
+
+
+def handle_send(
+    raw: bytes,
+    *,
+    sender_pub: bytes = b"sender-pub",
+    system_pub: bytes = b"system-pub",
+) -> RouteResult:
+    """Apply catalog reject rules to one passthrough envelope."""
+    try:  # JSON required
+        env = json.loads(raw.decode() or "{}")  # object
+    except json.JSONDecodeError:  # bad json
+        return _fail("SM-BAD-JSON", "parse", "", sender_pub, system_pub, "not json")
+    if not isinstance(env, dict):  # must be object
+        return _fail("SM-BAD-JSON", "parse", "", sender_pub, system_pub, "not object")
+    to = str(env.get("to") or "")  # dest in the clear
+    alg = str(env.get("alg") or "")  # npe | lab-xor | plain-lab
+    ct = str(env.get("ct") or "")  # ciphertext hex
+    lid = str(env.get("from_lookup_id") or "")  # opaque
+    if "ct" in env and "body" in env:  # never log/accept plaintext body field
+        return _fail("SM-PLAINTEXT-BODY", "mailbox", lid, sender_pub, system_pub, "body field forbidden")
+    if not to:  # catalog reject: missing to
+        return _fail("SM-MISSING-TO", "mailbox", lid, sender_pub, system_pub, "missing to")
+    if alg and alg not in ALLOWED_ALG:  # alg not in signed config
+        return _fail("SM-BAD-ALG", "mailbox", lid, sender_pub, system_pub, "alg not allowed")
+    if alg != "plain-lab" and not ct:  # empty ciphertext when not plain-lab
+        return _fail("SM-EMPTY-CT", "mailbox", lid, sender_pub, system_pub, "empty ciphertext")
+    # success: do not keep body; dest stays in the clear
+    return RouteResult(accepted=True, lookup_id=lid, dest_class="mailbox")
+
+
+def _fail(
+    code: str,
+    dest_class: str,
+    lookup_id: str,
+    sender_pub: bytes,
+    system_pub: bytes,
+    detail: str,
+) -> RouteResult:
+    """Failure path: bundle + dead + summary (no recipient plaintext)."""
+    bundle = build_bundle(  # two ciphertexts
+        lookup_id=lookup_id or "unknown",
+        error_code=code,
+        dest_class=dest_class,
+        sender_pub=sender_pub,
+        system_pub=system_pub,
+        detail=detail,
+    )
+    summary = log_summary(bundle)  # codes only
+    events = [  # order: summary, error, dead
+        {"subject": "verae.sm.log.summary", "body": summary},
+        {"subject": "verae.sm.error", "body": bundle.wire()},
+        {"subject": "verae.sm.dead", "body": bundle.wire()},
+    ]
+    return RouteResult(
+        accepted=False,
+        lookup_id=lookup_id,
+        error_code=code,
+        dest_class=dest_class,
+        events=events,
+        bundle=bundle,
+    )