refactor(relay): drop dead delivery-signature/verify_token/from_platform_entry auth+descriptor code
This commit is contained in:
+5
-91
@@ -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 <token>``
|
||||
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 <token>`` 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)
|
||||
|
||||
+19
-62
@@ -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),
|
||||
)
|
||||
|
||||
@@ -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
|
||||
|
||||
|
||||
|
||||
@@ -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"
|
||||
|
||||
|
||||
Reference in New Issue
Block a user