From dbd7f76dd8155223e1ef28a6db95e7032cc7370d Mon Sep 17 00:00:00 2001 From: Teknium <127238744+teknium1@users.noreply.github.com> Date: Wed, 2 Sep 2026 19:56:36 -0700 Subject: [PATCH] refactor(relay): drop dead delivery-signature/verify_token/from_platform_entry auth+descriptor code --- gateway/relay/auth.py | 96 +----------------- gateway/relay/descriptor.py | 81 ++++------------ tests/gateway/relay/test_auth.py | 97 +++---------------- .../relay/test_descriptor_from_entry.py | 38 -------- 4 files changed, 35 insertions(+), 277 deletions(-) delete mode 100644 tests/gateway/relay/test_descriptor_from_entry.py diff --git a/gateway/relay/auth.py b/gateway/relay/auth.py index 37c92510f8..ca23ab1c5d 100644 --- a/gateway/relay/auth.py +++ b/gateway/relay/auth.py @@ -1,18 +1,10 @@ """Gateway-side relay authentication primitives. EXPERIMENTAL. -Gateway half of two HMAC schemes whose wire bytes must match the connector's -TypeScript exactly: - -1. **WS upgrade auth** (gateway → connector): ``Authorization: Bearer `` - on the ``/relay`` upgrade, ``token = make_upgrade_token(gateway_id, secret)``. - Mirrors ``relayAuthToken.ts`` ``makeToken``: ``base64url(f"{payload}:{exp}:{sig}")`` - with ``sig = HMAC_SHA256(f"{payload}:{exp}", secret).hexdigest()``. -2. **Inbound delivery signature** (connector → gateway): ``x-relay-timestamp`` + - ``x-relay-signature`` headers, ``sig = HMAC_SHA256(f"{ts}.{body_json}", key)`` - over the EXACT body bytes, with a replay-window skew check (``deliverySigning.ts``). - -Both verify against a multi-secret list (primary first, then a secondary during -a rotation window) so a rotation doesn't invalidate outstanding tokens. +WS upgrade auth (gateway -> connector): ``Authorization: Bearer `` on the +``/relay`` upgrade, ``token = make_upgrade_token(gateway_id, secret)``. Wire bytes +must match the connector's ``relayAuthToken.ts`` ``makeToken`` exactly: +``base64url(f"{payload}:{exp}:{sig}")`` with ``sig = HMAC_SHA256(f"{payload}:{exp}", +secret).hexdigest()``. The connector verifies against a multi-secret rotation list. """ from __future__ import annotations @@ -21,13 +13,7 @@ import base64 import hashlib import hmac import time -from typing import Optional, Sequence -# Header names used by the connector's deliverySigning.ts. -DELIVERY_TS_HEADER = "x-relay-timestamp" -DELIVERY_SIG_HEADER = "x-relay-signature" - -_DEFAULT_MAX_SKEW_SECONDS = 300 # connector default replay window _DEFAULT_UPGRADE_TTL_SECONDS = 300 # connector makeUpgradeToken default @@ -36,28 +22,6 @@ def sign(payload: str, secret: str) -> str: return hmac.new(secret.encode("utf-8"), payload.encode("utf-8"), hashlib.sha256).hexdigest() -def verify_signature(payload: str, sig_hex: str, secrets: Sequence[str]) -> bool: - """Constant-time check of ``sig_hex`` against ANY of ``secrets`` (rotation window). - - Length-mismatched candidates are skipped without a timing leak. - """ - try: - sig_buf = bytes.fromhex(sig_hex) - except (ValueError, TypeError): - return False - if len(sig_buf) == 0: - return False - for secret in secrets: - if not secret: - continue - expected = bytes.fromhex(sign(payload, secret)) - if len(expected) != len(sig_buf): - continue - if hmac.compare_digest(sig_buf, expected): - return True - return False - - def make_token(payload: str, secret: str, ttl_seconds: int = 0) -> str: """``base64url(f"{payload}:{exp}:{sig}")``; ``exp`` unix seconds (0 = never). @@ -74,53 +38,3 @@ def make_upgrade_token( ) -> str: """WS-upgrade bearer: ``payload = gateway_id`` (the connector peeks it to index its verify list).""" return make_token(gateway_id, secret, ttl_seconds) - - -def verify_token(token: str, secrets: Sequence[str]) -> Optional[str]: - """Verify a ``make_token`` token; return the payload or None. - - Splits from the right so a payload may itself contain colons. - """ - try: - padded = token + "=" * (-len(token) % 4) - decoded = base64.urlsafe_b64decode(padded.encode("ascii")).decode("utf-8") - except (ValueError, TypeError): - return None - parts = decoded.split(":") - if len(parts) < 3: - return None - sig = parts[-1] - try: - exp = int(parts[-2]) - except ValueError: - return None - payload = ":".join(parts[:-2]) - if exp != 0 and int(time.time()) > exp: - return None - return payload if verify_signature(f"{payload}:{exp}", sig, secrets) else None - - -def verify_delivery_signature( - body_json: str, - timestamp: Optional[str], - signature: Optional[str], - verify_keys: Sequence[str], - max_skew_seconds: int = _DEFAULT_MAX_SKEW_SECONDS, - *, - now: Optional[int] = None, -) -> bool: - """Verify a connector→gateway inbound delivery signature. - - ``body_json`` MUST be the exact request body bytes decoded as UTF-8 (no - re-serialization — the connector signed the literal body). - """ - if not timestamp or not signature: - return False - try: - ts = int(timestamp) - except (ValueError, TypeError): - return False - current = now if now is not None else int(time.time()) - if abs(current - ts) > max_skew_seconds: - return False - return verify_signature(f"{ts}.{body_json}", signature, verify_keys) diff --git a/gateway/relay/descriptor.py b/gateway/relay/descriptor.py index 47a9d72f72..92e9afad34 100644 --- a/gateway/relay/descriptor.py +++ b/gateway/relay/descriptor.py @@ -2,15 +2,9 @@ The connector hands one to the gateway's ``RelayAdapter`` at handshake: which platform it fronts and which capabilities to advertise to the stream consumer -(char limit, draft streaming, edit/threading, markdown dialect, length unit). -One gateway adapter thus serves every platform without per-platform branching. - -Schema evolution is additive-only, gated by ``contract_version`` -(docs/relay-connector-contract.md). Most fields are a wire projection of -``PlatformEntry`` (``max_message_length``, ``emoji``, ``platform_hint``, -``pii_safe``, ``label``) plus the adapter capability probes -(``supports_draft_streaming``, ``supports_edit``, ``supports_threads``, -``len_unit`` → which ``message_len_fn`` the adapter installs). +(char limit, draft streaming, edit/threading, markdown dialect, length unit), so +one adapter serves every platform without per-platform branching. Schema evolution +is additive-only, gated by ``contract_version`` (docs/relay-connector-contract.md). """ from __future__ import annotations @@ -39,23 +33,22 @@ class CapabilityDescriptor: emoji: str = "\U0001f50c" # 🔌 (matches PlatformEntry default) platform_hint: str = "" pii_safe: bool = False - # All optional bits below default False/empty so an older connector that - # never sends them is treated as "not supported" — additive within - # contract_version 1 (from_json also drops unknown keys, so newer connectors - # are safe against older gateways). + # Optional bits default False/empty so an older connector that never sends + # them reads as "not supported" — additive within contract_version 1 + # (from_json drops unknown keys, so newer connectors are safe against older gateways). # Connector can supply surrounding channel/group CONTEXT for an addressed turn. supports_context: bool = False # Platform can host a FLAT continuable cron surface (native Slack's # ``cron_continuable_surface: in_channel``); the scheduler fails safe to # thread mode when False (D6 gate). supports_inchannel_continuable: bool = False - # Platform sender renders block-level formatting from raw markdown; when - # True AND the operator enables rich_blocks/markdown_blocks, the gateway - # stamps ``format_hints`` on outbound send/edit metadata. + # Platform sender renders block-level formatting from raw markdown; when True + # AND the operator enables rich_blocks/markdown_blocks, the gateway stamps + # ``format_hints`` on outbound send/edit metadata. supports_block_formatting: bool = False - # Outbound op names the connector implements for this platform. Empty = - # the connector predates the field; callers MUST treat that as LEGACY_OPS, - # not "nothing supported". Tuple keeps the frozen dataclass hashable. + # Outbound op names the connector implements for this platform. Empty = the + # connector predates the field; callers MUST treat that as LEGACY_OPS, not + # "nothing supported". Tuple keeps the frozen dataclass hashable. supported_ops: tuple = () # Assumed capability set when a legacy connector sends no supported_ops. @@ -67,9 +60,7 @@ class CapabilityDescriptor: A NEW op is therefore only True when explicitly advertised — capability can be probed without trying the op and parsing an error. """ - if not self.supported_ops: - return op in self.LEGACY_OPS - return op in self.supported_ops + return op in (self.supported_ops or self.LEGACY_OPS) def to_json(self) -> str: """Compact, stable JSON for the handshake frame.""" @@ -86,7 +77,7 @@ class CapabilityDescriptor: fallback) when malformed. """ raw = json.loads(data) - known = {f for f in cls.__dataclass_fields__} # type: ignore[attr-defined] + known = cls.__dataclass_fields__ # type: ignore[attr-defined] filtered = {k: v for k, v in raw.items() if k in known} if "max_message_length" in filtered: try: @@ -96,43 +87,9 @@ class CapabilityDescriptor: filtered["max_message_length"] = 4096 if "supported_ops" in filtered: raw_ops = filtered["supported_ops"] - if isinstance(raw_ops, (list, tuple)): - filtered["supported_ops"] = tuple( - str(op) for op in raw_ops if isinstance(op, str) and op - ) - else: - filtered["supported_ops"] = () + filtered["supported_ops"] = ( + tuple(str(op) for op in raw_ops if isinstance(op, str) and op) + if isinstance(raw_ops, (list, tuple)) + else () + ) return cls(**filtered) - - @classmethod - def from_platform_entry( - cls, - entry, - *, - len_unit: str = "chars", - supports_draft_streaming: bool = False, - supports_edit: bool = True, - supports_threads: bool = False, - markdown_dialect: str = "plain", - ) -> "CapabilityDescriptor": - """Project a ``gateway.platform_registry.PlatformEntry`` into a descriptor. - - Runtime bits the entry does not encode (length unit, draft/edit/thread/ - markdown) come from the caller. A ``max_message_length`` of 0 ("no - limit") maps to the stream_consumer default of 4096. - """ - max_len = getattr(entry, "max_message_length", 0) or 4096 - return cls( - contract_version=CONTRACT_VERSION, - platform=entry.name, - label=entry.label, - max_message_length=max_len, - supports_draft_streaming=supports_draft_streaming, - supports_edit=supports_edit, - supports_threads=supports_threads, - markdown_dialect=markdown_dialect, - len_unit=len_unit, - emoji=getattr(entry, "emoji", "\U0001f50c"), - platform_hint=getattr(entry, "platform_hint", ""), - pii_safe=getattr(entry, "pii_safe", False), - ) diff --git a/tests/gateway/relay/test_auth.py b/tests/gateway/relay/test_auth.py index fdacc52e81..04ee7f1386 100644 --- a/tests/gateway/relay/test_auth.py +++ b/tests/gateway/relay/test_auth.py @@ -1,105 +1,30 @@ """Unit tests for gateway/relay/auth.py — the gateway-side relay auth primitives. -Two layers: +Cross-implementation conformance: a frozen vector generated by the connector's +TypeScript (``src/core/relayAuthToken.ts`` ``makeToken``/``sign``) must be +reproduced byte-for-byte by the Python port. If the connector ever changes its +wire scheme, the vector must be regenerated in lockstep (the test fails loudly on +drift). Regenerate with: -1. **Self-consistency** — make_token/verify_token round-trip, delivery-signature - verify, rotation verify list, tamper + skew + expiry rejection. -2. **Cross-implementation conformance** — frozen vectors generated by the - connector's TypeScript (``src/core/relayAuthToken.ts`` ``makeToken``/``sign``) - are reproduced byte-for-byte by the Python port. If the connector ever - changes its wire scheme, these vectors must be regenerated in lockstep - (and that is the point — the test fails loudly on drift). Regenerate with: - - node -e 'import("./dist/core/relayAuthToken.js").then(m=>{ \ - const s="00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff"; \ - console.log(m.makeToken("gw-instance-1", s, 0)); \ - console.log(m.sign("1750000000."+JSON.stringify({a:1}), s)); })' + node -e 'import("./dist/core/relayAuthToken.js").then(m=>{ \\ + const s="00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff"; \\ + console.log(m.makeToken("gw-instance-1", s, 0)); })' """ from __future__ import annotations -import json +from gateway.relay.auth import make_token, make_upgrade_token -from gateway.relay.auth import ( - DELIVERY_SIG_HEADER, - DELIVERY_TS_HEADER, - make_token, - make_upgrade_token, - sign, - verify_delivery_signature, - verify_signature, - verify_token, -) - -# A fixed 256-bit hex secret used for the frozen connector vectors below. +# A fixed 256-bit hex secret used for the frozen connector vector below. _SECRET = "00112233445566778899aabbccddeeff00112233445566778899aabbccddeeff" -# ── Frozen vectors produced by the connector's TypeScript (relayAuthToken.ts). -# Generated via dist/core/relayAuthToken.js makeToken/sign; see module docstring. +# Frozen vector produced by the connector's TypeScript (relayAuthToken.ts). _CONN_TOKEN = "Z3ctaW5zdGFuY2UtMTowOjM3YWE3YjE0NWU4NzY0ZDQwM2JhOWM2MzlmMjMwZGQ2M2RlOGVkOTliODhmZWQzNmFhMDI2MjVhOGE3ZTM1NjQ" -# The EXACT bytes the connector signed: JS JSON.stringify emits compact JSON -# (no spaces). The gateway verifies over the literal received body, so the -# vector is the compact form — NOT Python's spaced json.dumps default. This is -# the raw-byte-preservation discipline (a single differing byte breaks the HMAC). -_CONN_BODY = '{"type":"message","event":{"text":"hi","source":{"chat_id":"c1"}}}' -_CONN_TS = 1750000000 -_CONN_SIG = "ac9509c8dae52b5590f06378260877334ff1adc4b1c96bafa4b514165fae6dc6" - - -# ── Self-consistency ────────────────────────────────────────────────────── def test_upgrade_token_is_make_token_of_gateway_id(): assert make_upgrade_token("gw-1", _SECRET, 0) == make_token("gw-1", _SECRET, 0) -def test_token_wrong_secret_rejected(): - tok = make_token("p", _SECRET, 0) - assert verify_token(tok, ["deadbeef" * 8]) is None - - -def test_token_expired_rejected(): - # ttl in the past -> exp < now -> rejected. - tok = make_token("p", _SECRET, ttl_seconds=1) - # Force expiry by signing with a manual past exp via the low-level helper. - # Simpler: a 1s ttl token is still valid now; instead assert a clearly-old one. - # Build an already-expired token by hand using the same scheme. - import base64 - - signed = "p:1" # exp=1 (1970) -> long past - sig = sign(signed, _SECRET) - raw = f"{signed}:{sig}".encode() - expired = base64.urlsafe_b64encode(raw).decode().rstrip("=") - assert verify_token(expired, [_SECRET]) is None - # And the fresh one is accepted. - assert verify_token(tok, [_SECRET]) == "p" - - -def test_verify_signature_constant_time_multi_secret(): - payload = "1700000000.body" - s = sign(payload, _SECRET) - assert verify_signature(payload, s, ["wrong", _SECRET]) is True - assert verify_signature(payload, s, ["wrong"]) is False - assert verify_signature(payload, "zz", [_SECRET]) is False # bad hex - - -# ── Delivery signature (connector -> gateway inbound) ────────────────────── - - -def test_delivery_signature_skew_rejected(): - body = "{}" - ts = 1700000000 - s = sign(f"{ts}.{body}", _SECRET) - # Beyond the 300s replay window in either direction. - assert verify_delivery_signature(body, str(ts), s, [_SECRET], now=ts + 301) is False - assert verify_delivery_signature(body, str(ts), s, [_SECRET], now=ts - 301) is False - assert verify_delivery_signature(body, str(ts), s, [_SECRET], now=ts + 299) is True - - -# ── Cross-implementation conformance (frozen connector vectors) ──────────── - - def test_python_make_token_matches_connector_byte_for_byte(): assert make_token("gw-instance-1", _SECRET, 0) == _CONN_TOKEN - - diff --git a/tests/gateway/relay/test_descriptor_from_entry.py b/tests/gateway/relay/test_descriptor_from_entry.py deleted file mode 100644 index 5491ace894..0000000000 --- a/tests/gateway/relay/test_descriptor_from_entry.py +++ /dev/null @@ -1,38 +0,0 @@ -"""Descriptor <- PlatformEntry projection (relay Phase 0, Task 0.3). - -Proves the CapabilityDescriptor is a projection of the existing PlatformEntry, -not a parallel concept: the entry's label/limit/emoji/hint/pii fields carry -straight through. -""" - -from gateway.platform_registry import PlatformEntry -from gateway.relay.descriptor import CONTRACT_VERSION, CapabilityDescriptor - - -def _entry(**overrides) -> PlatformEntry: - base = dict( - name="telegram", - label="Telegram", - adapter_factory=lambda cfg: None, - check_fn=lambda: True, - max_message_length=4096, - pii_safe=False, - emoji="\u2708\ufe0f", - platform_hint="You are on Telegram.", - ) - base.update(overrides) - return PlatformEntry(**base) - - -def test_projection_carries_platform_entry_fields(): - d = CapabilityDescriptor.from_platform_entry(_entry(), len_unit="utf16") - assert d.contract_version == CONTRACT_VERSION - assert d.platform == "telegram" - assert d.label == "Telegram" - assert d.max_message_length == 4096 - assert d.emoji == "\u2708\ufe0f" - assert d.platform_hint == "You are on Telegram." - assert d.pii_safe is False - assert d.len_unit == "utf16" - -