feat: demo-ready improvements — fingerprint words, compare tool, sender TTL

Feature 1 — Visual Fingerprint Words (PGP Word List):
  Add _fingerprint_words() using 256 even + 256 odd PGP Word List.
  Returns 6-word human-readable fingerprints alongside hex, e.g.
  "snapline-Eskimo-tumor-informant-deadbolt-detector". Included
  in pqc_fingerprint, hybrid_keygen, and keygen handler responses.
  Added fingerprint_words to key store schema allowlist.

Feature 2 — Classical vs PQC Comparison Tool:
  New pqc_compare tool benchmarks a PQC algorithm against its
  classical counterpart (ML-KEM-768 vs X25519, ML-DSA-65 vs
  Ed25519). Shows side-by-side latency, key sizes, and ratios.

Feature 3 — Sender-Controlled TTL (Self-Destruct):
  Optional max_decrypt_time parameter on pqc_hybrid_auth_seal.
  Value is signed in the auth transcript (tamper-proof). After
  timestamp + max_decrypt_time, auth_open refuses to decrypt:
  "The sender set this message to self-destruct."
  Backwards compatible — envelopes without it work unchanged.

305 tests passing, zero regressions.

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

Author: scottdhughes

pqc_mcp_server/__init__.py

@@ -66,6 +66,7 @@ class SenderVerificationError(Exception):  # type: ignore[no-redef]
         handle_hash,
         handle_security_analysis,
         handle_benchmark,
+        handle_compare,
     )
 
     _PQC_HANDLERS = {
@@ -80,6 +81,7 @@ class SenderVerificationError(Exception):  # type: ignore[no-redef]
         "pqc_hash_to_curve": handle_hash,  # deprecated alias
         "pqc_security_analysis": handle_security_analysis,
         "pqc_benchmark": handle_benchmark,
+        "pqc_compare": handle_compare,
     }
 
 if HAS_HYBRID:
@@ -157,7 +159,7 @@ class SenderVerificationError(Exception):  # type: ignore[no-redef]
 )
 _DICT_FIELDS = frozenset({"envelope", "key_data"})
 _BOOL_FIELDS = frozenset({"overwrite", "include_secret_key"})
-_INT_FIELDS = frozenset({"iterations", "max_age_seconds"})
+_INT_FIELDS = frozenset({"iterations", "max_age_seconds", "max_decrypt_time"})
 
 _SIZE_LIMITS: dict[str, int] = {
     "plaintext": _MAX_PLAINTEXT_SIZE,

pqc_mcp_server/handlers_hybrid.py

@@ -29,6 +29,7 @@
     hybrid_auth_open,
     hybrid_auth_verify,
     _fingerprint_public_key,
+    _fingerprint_words,
 )
 from pqc_mcp_server.security_policy import get_policy
 from pqc_mcp_server.replay_cache import get_replay_cache, signature_digest
@@ -118,6 +119,7 @@ def handle_fingerprint(arguments: dict[str, Any]) -> dict[str, Any]:
     pk_bytes = _b64(arguments["public_key"])
     return {
         "fingerprint": _fingerprint_public_key(pk_bytes),
+        "fingerprint_words": _fingerprint_words(pk_bytes),
         "algorithm": "SHA3-256",
         "public_key_size": len(pk_bytes),
     }
@@ -136,11 +138,13 @@ def handle_hybrid_keygen(arguments: dict[str, Any]) -> dict[str, Any]:
                 "algorithm": result["classical"]["algorithm"],
                 "public_key": result["classical"]["public_key"],
                 "fingerprint": result["classical"]["fingerprint"],
+                "fingerprint_words": result["classical"]["fingerprint_words"],
             },
             "pqc": {
                 "algorithm": result["pqc"]["algorithm"],
                 "public_key": result["pqc"]["public_key"],
                 "fingerprint": result["pqc"]["fingerprint"],
+                "fingerprint_words": result["pqc"]["fingerprint_words"],
             },
         }
     return result
@@ -197,7 +201,11 @@ def handle_hybrid_auth_seal(arguments: dict[str, Any]) -> dict[str, Any]:
     pt_bytes = _resolve_plaintext(arguments)
     classical_pk, pqc_pk = _resolve_hybrid_public(arguments, prefix="recipient_")
     sender_sk, sender_pk = _resolve_sender(arguments)
-    envelope = hybrid_auth_seal(pt_bytes, classical_pk, pqc_pk, sender_sk, sender_pk)
+    kwargs: dict[str, Any] = {}
+    mdt = arguments.get("max_decrypt_time")
+    if mdt is not None:
+        kwargs["max_decrypt_time"] = int(mdt)
+    envelope = hybrid_auth_seal(pt_bytes, classical_pk, pqc_pk, sender_sk, sender_pk, **kwargs)
     return {"envelope": envelope}
 
 

pqc_mcp_server/handlers_pqc.py

@@ -437,3 +437,132 @@ def handle_benchmark(arguments: dict[str, Any]) -> dict[str, Any]:
         },
         "nist_level": details.get("claimed_nist_level", "Unknown"),
     }
+
+
+# Classical counterpart mapping for comparison tool
+_CLASSICAL_COUNTERPARTS: dict[str, str] = {
+    "ML-KEM-768": "X25519",
+    "ML-KEM-512": "X25519",
+    "ML-KEM-1024": "X25519",
+    "ML-DSA-44": "Ed25519",
+    "ML-DSA-65": "Ed25519",
+    "ML-DSA-87": "Ed25519",
+}
+
+
+def _benchmark_classical(algorithm: str, iterations: int) -> dict[str, Any]:
+    """Benchmark a classical algorithm (X25519 or Ed25519)."""
+    from cryptography.hazmat.primitives.asymmetric.x25519 import X25519PrivateKey
+    from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+    test_message = b"Benchmark test message for classical operations"
+
+    if algorithm == "X25519":
+        # Keygen
+        t0 = time.perf_counter()
+        for _ in range(iterations):
+            sk = X25519PrivateKey.generate()
+            sk.public_key()
+        keygen_ms = (time.perf_counter() - t0) / iterations * 1000
+
+        # Key exchange
+        sk1 = X25519PrivateKey.generate()
+        pk2 = X25519PrivateKey.generate().public_key()
+        t0 = time.perf_counter()
+        for _ in range(iterations):
+            sk1.exchange(pk2)
+        exchange_ms = (time.perf_counter() - t0) / iterations * 1000
+
+        return {
+            "algorithm": "X25519",
+            "type": "Key Exchange",
+            "iterations": iterations,
+            "timing_ms": {"keygen": round(keygen_ms, 3), "exchange": round(exchange_ms, 3)},
+            "sizes_bytes": {"public_key": 32, "secret_key": 32, "shared_secret": 32},
+        }
+
+    elif algorithm == "Ed25519":
+        # Keygen
+        t0 = time.perf_counter()
+        for _ in range(iterations):
+            sk = Ed25519PrivateKey.generate()
+            sk.public_key()
+        keygen_ms = (time.perf_counter() - t0) / iterations * 1000
+
+        # Sign
+        sk = Ed25519PrivateKey.generate()
+        t0 = time.perf_counter()
+        for _ in range(iterations):
+            sig = sk.sign(test_message)
+        sign_ms = (time.perf_counter() - t0) / iterations * 1000
+
+        # Verify
+        pk = sk.public_key()
+        t0 = time.perf_counter()
+        for _ in range(iterations):
+            pk.verify(sig, test_message)
+        verify_ms = (time.perf_counter() - t0) / iterations * 1000
+
+        return {
+            "algorithm": "Ed25519",
+            "type": "Signature",
+            "iterations": iterations,
+            "timing_ms": {
+                "keygen": round(keygen_ms, 3),
+                "sign": round(sign_ms, 3),
+                "verify": round(verify_ms, 3),
+            },
+            "sizes_bytes": {"public_key": 32, "secret_key": 32, "signature": 64},
+        }
+
+    raise ValueError(f"Unknown classical algorithm: {algorithm}")
+
+
+def handle_compare(arguments: dict[str, Any]) -> dict[str, Any]:
+    """Compare a PQC algorithm against its classical counterpart."""
+    alg = arguments["algorithm"]
+    iterations = min(arguments.get("iterations", 10), 100)
+
+    classical_name = _CLASSICAL_COUNTERPARTS.get(alg)
+    if not classical_name:
+        supported = ", ".join(sorted(_CLASSICAL_COUNTERPARTS.keys()))
+        raise ValueError(f"No classical counterpart for '{alg}'. Supported: {supported}")
+
+    pqc_result = handle_benchmark({"algorithm": alg, "iterations": iterations})
+    classical_result = _benchmark_classical(classical_name, iterations)
+
+    # Compute ratios
+    ratios: dict[str, str] = {}
+    ratios["keygen"] = (
+        f"{pqc_result['timing_ms']['keygen'] / max(classical_result['timing_ms']['keygen'], 0.001):.1f}x"
+    )
+
+    if pqc_result["type"] == "KEM":
+        classical_op = classical_result["timing_ms"]["exchange"]
+        pqc_op = pqc_result["timing_ms"]["encap"]
+        ratios["encap_vs_exchange"] = f"{pqc_op / max(classical_op, 0.001):.1f}x"
+        pk_ratio = (
+            pqc_result["sizes_bytes"]["public_key"] / classical_result["sizes_bytes"]["public_key"]
+        )
+        ratios["public_key_size"] = f"{pk_ratio:.0f}x"
+    else:
+        classical_sign = classical_result["timing_ms"]["sign"]
+        pqc_sign = pqc_result["timing_ms"]["sign"]
+        ratios["sign"] = f"{pqc_sign / max(classical_sign, 0.001):.1f}x"
+        classical_verify = classical_result["timing_ms"]["verify"]
+        pqc_verify = pqc_result["timing_ms"]["verify"]
+        ratios["verify"] = f"{pqc_verify / max(classical_verify, 0.001):.1f}x"
+        sig_ratio = (
+            pqc_result["sizes_bytes"]["signature"] / classical_result["sizes_bytes"]["signature"]
+        )
+        ratios["signature_size"] = f"{sig_ratio:.0f}x"
+
+    return {
+        "pqc": pqc_result,
+        "classical": classical_result,
+        "ratios": ratios,
+        "summary": (
+            f"{alg} vs {classical_name}: PQC keygen is {ratios['keygen']} slower. "
+            f"PQC provides NIST Level {pqc_result.get('nist_level', '?')} quantum resistance."
+        ),
+    }