devora-python 0.1.0__py3-none-any.whl

devora_sdk/sdk.py

@@ -0,0 +1,390 @@
+from __future__ import annotations
+
+import json
+import inspect
+import os
+import re
+import time
+from typing import Any, Callable, Optional
+
+from .constants import (
+	DEFAULT_API_URL,
+	DEFAULT_TIMESTAMP_TOLERANCE_SECONDS,
+	DEVORA_ENDPOINTS,
+	ENDPOINT_METHODS,
+	PROTECTED_ENDPOINTS,
+	SDK_VERSION,
+	BROWSER_RESUME_CODE_ENDPOINT,
+	TAB_REF_PATTERN,
+)
+from .hmac import sha256_hex, sign_request, signature_matches
+from .models import DevoraRequest, SDKRoute, SDKStats, ValidationResult
+from .policy import ScopeConfig, ScopeConfigFetcher
+from .security import is_valid_timestamp_tolerance, validate_timestamp, validate_timestamp_tolerance
+from .signing import (
+	CUSTOMER_TO_DEVORA,
+	DEVORA_TO_CUSTOMER,
+	build_canonical_string,
+	has_identity_content_encoding,
+	is_valid_signed_path,
+	is_valid_signed_query,
+	matches,
+	parse_signature_headers,
+	replay_expires_at_ms,
+	replay_namespace,
+)
+from .transport import ControlPlaneError, control_plane_request
+from .replay import InMemoryReplayStore, ReplayStore
+
+
+def resolve_environment(explicit: Optional[str] = None) -> str:
+	"""Explicit option first, then DEVORA_ENV / NODE_ENV as hints, else production."""
+	raw = (explicit or os.environ.get("DEVORA_ENV") or os.environ.get("NODE_ENV") or "production")
+	raw = str(raw).strip().lower()
+	return raw if raw in ("development", "test") else "production"
+
+
+class DevoraBackendSDK:
+	def __init__(
+		self,
+		api_key: str,
+		secret_key: str,
+		org_id: str,
+		timestamp_tolerance: int = DEFAULT_TIMESTAMP_TOLERANCE_SECONDS,
+		collect_stats: bool = False,
+		debug: bool = False,
+		api_url: Optional[str] = None,
+		replay_store: Optional[ReplayStore] = None,
+		environment: Optional[str] = None,
+		prefetch_scope_config: bool = False,
+		**_ignored_options: Any,
+	) -> None:
+		# Unknown preferences are intentionally discarded; capture is owned by Devora.
+		if not matches("key_id", api_key):
+			raise ValueError("Devora SDK: api_key must be a server key identifier (pk_server_live_*)")
+		if not _valid_secret_key(secret_key):
+			raise ValueError("Devora SDK: invalid server secret key")
+		if not org_id.strip():
+			raise ValueError("Devora SDK: org_id is required")
+		validate_timestamp_tolerance(timestamp_tolerance)
+
+		self.api_key = api_key
+		self._secret_key = secret_key
+		self.org_id = org_id
+		self.api_url = _resolve_api_url(api_url)
+		self.timestamp_tolerance = timestamp_tolerance
+		self.collect_stats = collect_stats
+		self.debug = debug
+		self.stats = SDKStats()
+		self._routes: list[SDKRoute] = []
+		# Fail closed: anything that is not explicitly a development/test runtime
+		# is production, and production must share replay protection across
+		# processes. Explicit option first, then DEVORA_ENV / NODE_ENV as hints.
+		self.environment = resolve_environment(environment)
+		if self.environment == "production" and replay_store is None:
+			raise ValueError(
+				"Devora SDK: replay_store is required in production. Pass a persistent "
+				"ReplayStore, or environment='development' (InMemoryReplayStore) for local "
+				"development only."
+			)
+		self._replay_store = replay_store or InMemoryReplayStore()
+		self._scope_config = ScopeConfigFetcher(
+			api_key=api_key,
+			api_url=self.api_url,
+			prefetch=prefetch_scope_config,
+			sign_request=lambda: sign_request(
+				secret_key=self._secret_key,
+				direction=CUSTOMER_TO_DEVORA,
+				key_id=self.api_key,
+				org_id=self.org_id,
+				method="GET",
+				path="/api/sdk/scope-config",
+			),
+		)
+		self._register_built_ins()
+
+	@property
+	def config(self) -> dict[str, Any]:
+		"""Redacted configuration view. The secret key is never exposed."""
+		return {
+			"api_key": self.api_key,
+			"secret_key": "[REDACTED]",
+			"org_id": self.org_id,
+			"api_url": self.api_url,
+			"timestamp_tolerance": self.timestamp_tolerance,
+			"collect_stats": self.collect_stats,
+			"debug": self.debug,
+		}
+
+	def register(
+		self,
+		path: str,
+		handler: Optional[Callable[[DevoraRequest], Any]] = None,
+		method: Optional[str] = None,
+	) -> Any:
+		def add_route(route_handler: Callable[[DevoraRequest], Any]) -> SDKRoute:
+			if path in PROTECTED_ENDPOINTS:
+				raise ValueError(f"Cannot override protected endpoint: {path}")
+			if any(route.path == path for route in self._routes):
+				raise ValueError(f"Endpoint already registered: {path}")
+			route_method = (ENDPOINT_METHODS.get(path) or method or "GET").upper()
+			route = SDKRoute(path=path, method=route_method, handler=route_handler, is_built_in=False)
+			self._routes.append(route)
+			return route
+
+		if handler is None:
+			return add_route
+		return add_route(handler)
+
+	def get_routes(self) -> list[SDKRoute]:
+		return list(self._routes)
+
+	def get_stats(self) -> dict[str, Any]:
+		return self.stats.to_dict()
+
+	def verify_request(
+		self,
+		method: str,
+		path: str,
+		query: str,
+		body: bytes,
+		headers: Any,
+		timestamp_tolerance: Optional[int] = None,
+	) -> ValidationResult:
+		"""Verify a signed request from Devora (signature v3) over its exact bytes.
+
+		``path`` is relative to the SDK mount and still percent-encoded; ``query``
+		is everything after the first ``?``; ``body`` is the raw bytes; ``headers``
+		is a mapping or a list of ``(name, value)`` pairs (duplicates are
+		rejected). Steps before the replay store never touch it.
+		"""
+		tolerance = self.timestamp_tolerance if timestamp_tolerance is None else timestamp_tolerance
+		if not is_valid_timestamp_tolerance(tolerance):
+			return ValidationResult(valid=False, error="Invalid timestamp tolerance", error_code="TIMESTAMP_EXPIRED")
+
+		parsed, error_code, error_message = parse_signature_headers(headers)
+		if parsed is None:
+			return ValidationResult(valid=False, error=error_message, error_code=error_code)
+		if parsed["key_id"] != self.api_key or parsed["org_id"] != self.org_id:
+			return ValidationResult(
+				valid=False,
+				error="Request key or organization does not match SDK configuration",
+				error_code="ORG_MISMATCH",
+			)
+		sent_at = int(parsed["sent_at"])
+		timestamp_ok, timestamp_error = validate_timestamp(sent_at, tolerance)
+		if not timestamp_ok:
+			return ValidationResult(valid=False, error=timestamp_error, error_code="TIMESTAMP_EXPIRED")
+		if not matches("method", method) or not is_valid_signed_path(path) or not is_valid_signed_query(query):
+			return ValidationResult(valid=False, error="Invalid request target", error_code="INVALID_REQUEST_TARGET")
+		if not has_identity_content_encoding(headers):
+			return ValidationResult(
+				valid=False, error="Content-Encoding is not supported", error_code="UNSUPPORTED_CONTENT_ENCODING"
+			)
+		if not isinstance(body, (bytes, bytearray)):
+			return ValidationResult(valid=False, error="Raw body bytes are required", error_code="INVALID_BODY")
+
+		canonical = build_canonical_string(
+			direction=DEVORA_TO_CUSTOMER,
+			key_id=parsed["key_id"],
+			org_id=parsed["org_id"],
+			sent_at=parsed["sent_at"],
+			request_id=parsed["request_id"],
+			method=method,
+			path=path,
+			query=query,
+			body_sha256=sha256_hex(bytes(body)),
+		)
+		if not signature_matches(self._secret_key, canonical, parsed["signature"]):
+			return ValidationResult(valid=False, error="Invalid HMAC signature", error_code="INVALID_SIGNATURE")
+
+		try:
+			fresh = self._replay_store.consume(
+				replay_namespace(DEVORA_TO_CUSTOMER, parsed["key_id"]),
+				parsed["request_id"],
+				replay_expires_at_ms(sent_at, int(time.time()), tolerance),
+			)
+		except Exception:
+			return ValidationResult(
+				valid=False, error="Replay protection is unavailable", error_code="REPLAY_STORE_UNAVAILABLE"
+			)
+		if not isinstance(fresh, bool):
+			if inspect.iscoroutine(fresh):
+				fresh.close()
+			return ValidationResult(
+				valid=False, error="Replay store must return a boolean decision", error_code="REPLAY_STORE_UNAVAILABLE"
+			)
+		if not fresh:
+			return ValidationResult(valid=False, error="Request was already processed", error_code="REPLAYED_REQUEST")
+		return ValidationResult(
+			valid=True,
+			org_id=parsed["org_id"],
+			key_id=parsed["key_id"],
+			timestamp=sent_at,
+			request_id=parsed["request_id"],
+		)
+
+	def get_scope_config(self) -> Optional[ScopeConfig]:
+		return self._scope_config.get_config()
+
+	def get_cached_scope_config(self) -> Optional[ScopeConfig]:
+		return self._scope_config.get_cached_config()
+
+	def refresh_scope_config(self) -> Optional[ScopeConfig]:
+		return self._scope_config.refresh()
+
+	def _signed_devora_post(self, path: str, payload: dict[str, Any]) -> tuple[int, Optional[dict[str, Any]]]:
+		"""POST a signed JSON body to a Devora SDK endpoint (customer-to-devora)."""
+		body = json.dumps(payload, separators=(",", ":"), ensure_ascii=False).encode("utf-8")
+		headers = sign_request(
+			secret_key=self._secret_key,
+			direction=CUSTOMER_TO_DEVORA,
+			key_id=self.api_key,
+			org_id=self.org_id,
+			method="POST",
+			path=path,
+			body=body,
+		)
+		status, json_body, _ = control_plane_request(f"{self.api_url}{path}", "POST", headers, body)
+		return status, json_body
+
+	def get_session_status(self, session_id: str) -> Optional[dict[str, Any]]:
+		"""Check whether a Devora session is still live (server-side liveness check).
+
+		Returns the status payload (including a ``valid`` flag), or ``None`` when Devora is
+		unreachable so callers can choose fail-open or fail-closed behavior.
+		"""
+		if not isinstance(session_id, str) or not session_id or len(session_id) > 128:
+			return None
+		try:
+			status, payload = self._signed_devora_post("/api/sdk/session-status", {"sessionId": session_id})
+		except (ControlPlaneError, ValueError):
+			return None
+		if status == 404:
+			return {"valid": False, "error": "SESSION_NOT_FOUND"}
+		if not (200 <= status < 300) or not payload or payload.get("success") is not True:
+			return None
+		data = payload.get("data")
+		if isinstance(data, dict) and isinstance(data.get("valid"), bool):
+			return data
+		return None
+
+	def create_browser_resume_code(
+		self, session_id: str, tab_ref: str, origin: str
+	) -> Optional[dict[str, Any]]:
+		"""Mint a one-time browser resume code for an active session.
+
+		Signed customer-to-devora. Returns ``{"code", "expiresAt"}``; ``{"error": ...}``
+		when Devora rejected the request; ``None`` when Devora is unreachable.
+		"""
+		if not isinstance(session_id, str) or not session_id or len(session_id) > 128:
+			return {"error": "INVALID_SESSION"}
+		if not isinstance(tab_ref, str) or not re.fullmatch(TAB_REF_PATTERN, tab_ref):
+			return {"error": "INVALID_TAB_REF"}
+		try:
+			status, payload = self._signed_devora_post(
+				BROWSER_RESUME_CODE_ENDPOINT, {"sessionId": session_id, "tabRef": tab_ref, "origin": origin}
+			)
+		except (ControlPlaneError, ValueError):
+			return None
+		data = payload.get("data") if payload else None
+		if 200 <= status < 300 and payload and payload.get("success") is True and isinstance(data, dict) and isinstance(data.get("code"), str):
+			return data
+		if status >= 500 or status == 429:
+			return None
+		error_code = payload.get("error") if payload else None
+		return {"error": error_code if isinstance(error_code, str) else "RESUME_REJECTED", "status": status}
+
+	def destroy(self) -> None:
+		self._scope_config.stop()
+
+	def record_request(self, endpoint: str, outcome: str) -> None:
+		self.stats.total_requests += 1
+		if self.collect_stats:
+			self.stats.requests_by_endpoint[endpoint] = self.stats.requests_by_endpoint.get(endpoint, 0) + 1
+		if outcome == "success":
+			self.stats.successful_requests += 1
+		else:
+			self.stats.failed_requests += 1
+			if outcome == "security_error":
+				self.stats.security_errors += 1
+
+	def _register_built_ins(self) -> None:
+		def test_handler(req: DevoraRequest) -> dict[str, Any]:
+			return {
+				"status": "success",
+				"message": "Devora SDK connection test successful",
+				"timestamp": _now_ms(),
+				"orgId": req.org_id,
+				"keyId": req.key_id,
+				"sdk": {"name": "devora-python", "version": SDK_VERSION, "type": "backend", "runtime": "python"},
+				"security": {"hmacValidated": True, "timestampValid": True},
+			}
+
+		def health_handler(_: DevoraRequest) -> dict[str, Any]:
+			return {
+				"status": "healthy",
+				"sdk": {"name": "devora-python", "version": SDK_VERSION, "type": "backend", "runtime": "python"},
+				"stats": self.get_stats() if self.collect_stats else None,
+				"endpoints": {route.path: route.method for route in self._routes},
+			}
+
+		self._routes.append(SDKRoute(DEVORA_ENDPOINTS.TEST, "GET", test_handler, True))
+		self._routes.append(SDKRoute(DEVORA_ENDPOINTS.HEALTH, "GET", health_handler, True))
+
+
+def devora_sdk(
+	api_key: str,
+	secret_key: str,
+	org_id: str,
+	timestamp_tolerance: int = DEFAULT_TIMESTAMP_TOLERANCE_SECONDS,
+	collect_stats: bool = False,
+	debug: bool = False,
+	api_url: Optional[str] = None,
+	replay_store: Optional[ReplayStore] = None,
+	environment: Optional[str] = None,
+	prefetch_scope_config: bool = False,
+	**_ignored_options: Any,
+) -> DevoraBackendSDK:
+	return DevoraBackendSDK(
+		api_key=api_key,
+		secret_key=secret_key,
+		org_id=org_id,
+		timestamp_tolerance=timestamp_tolerance,
+		collect_stats=collect_stats,
+		debug=debug,
+		api_url=api_url,
+		replay_store=replay_store,
+		environment=environment,
+		prefetch_scope_config=prefetch_scope_config,
+	)
+
+
+def _valid_secret_key(secret_key: str) -> bool:
+	return matches("secret_key", secret_key)
+
+
+def _resolve_api_url(override: Optional[str]) -> str:
+	"""Validate an API origin override (advanced; e.g. self-hosted deployments).
+
+	Only https origins are accepted (http for localhost/127.0.0.1 development).
+	"""
+	if not override:
+		return DEFAULT_API_URL
+	from urllib.parse import urlparse
+
+	parsed = urlparse(override.strip())
+	is_localhost = parsed.hostname in ("localhost", "127.0.0.1")
+	if parsed.scheme != "https" and not (parsed.scheme == "http" and is_localhost):
+		raise ValueError("Devora SDK: api_url must use https (http is allowed for localhost only)")
+	if parsed.username or parsed.password or (parsed.path and parsed.path != "/") or parsed.query or parsed.fragment:
+		raise ValueError("Devora SDK: api_url must be an origin without path, query, or credentials")
+	if not parsed.netloc:
+		raise ValueError(f"Devora SDK: api_url is not a valid URL: {override}")
+	return f"{parsed.scheme}://{parsed.netloc}"
+
+
+def _now_ms() -> int:
+	import time
+
+	return int(time.time() * 1000)

devora_sdk/security.py

@@ -0,0 +1,37 @@
+from __future__ import annotations
+
+import time
+from typing import Optional
+
+from .constants import DEFAULT_TIMESTAMP_TOLERANCE_SECONDS
+
+
+def is_valid_timestamp_tolerance(value: object) -> bool:
+	"""A tolerance is a whole, non-negative number of seconds (0 = current second only)."""
+	return isinstance(value, int) and not isinstance(value, bool) and value >= 0
+
+
+def validate_timestamp_tolerance(value: object, name: str = "timestamp_tolerance") -> None:
+	"""Raise for configuration values that :func:`is_valid_timestamp_tolerance` rejects.
+
+	``None`` means "use the default" and is accepted. NaN, infinities, negatives,
+	floats and bools are rejected: they would make every drift comparison pass.
+	"""
+	if value is not None and not is_valid_timestamp_tolerance(value):
+		raise ValueError(f"Devora SDK: {name} must be a non-negative integer number of seconds")
+
+
+def validate_timestamp(
+	request_timestamp: int, tolerance_seconds: int = DEFAULT_TIMESTAMP_TOLERANCE_SECONDS
+) -> tuple[bool, Optional[str]]:
+	if not is_valid_timestamp_tolerance(tolerance_seconds):
+		return False, "Invalid timestamp tolerance"
+	if not isinstance(request_timestamp, int) or request_timestamp <= 0:
+		return False, "Invalid timestamp"
+	drift = abs(int(time.time()) - request_timestamp)
+	if drift > tolerance_seconds:
+		return (
+			False,
+			f"Request timestamp outside tolerance window (drift: {drift}s, max: {tolerance_seconds}s)",
+		)
+	return True, None

devora_sdk/signing.py

@@ -0,0 +1,240 @@
+"""Devora request signing, version 3. Mirrors @devorash/core security/signing.ts.
+
+The signature covers the exact bytes on the wire: raw path, raw query and a
+SHA-256 of the raw body, plus the direction the request travels in. Every
+header has one accepted spelling. Conformance vectors:
+packages/sdks/test/signing-v3-vectors.json.
+"""
+from __future__ import annotations
+
+import json
+import math
+import re
+from typing import Any, Iterable, Mapping, Optional, Sequence, Union
+from urllib.parse import parse_qsl, unquote
+
+from .constants import SECURITY_HEADERS
+
+VERSION = "3"
+ALGORITHM = "DEVORA-HMAC-SHA256"
+DEVORA_TO_CUSTOMER = "devora-to-customer"
+CUSTOMER_TO_DEVORA = "customer-to-devora"
+EMPTY_BODY_SHA256 = "e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855"
+
+#: Exact header grammars. A value must match in full; nothing is trimmed.
+PATTERNS = {
+	"signature_version": re.compile(r"3"),
+	"key_id": re.compile(r"pk_server_live_[A-Za-z0-9_-]{32}"),
+	"org_id": re.compile(r"[A-Za-z0-9_-]{1,128}"),
+	"sent_at": re.compile(r"[1-9][0-9]{9}"),
+	"request_id": re.compile(r"[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}"),
+	"signature": re.compile(r"[0-9a-f]{64}"),
+	"method": re.compile(r"[A-Z]{3,7}"),
+	"body_sha256": re.compile(r"[0-9a-f]{64}"),
+	"secret_key": re.compile(r"sk_server_live_[A-Za-z0-9_-]{64}"),
+}
+
+HeaderInput = Union[Mapping[str, Any], Sequence[tuple[Any, Any]]]
+
+_UNRESERVED = frozenset(b"ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_.~")
+
+
+def matches(name: str, value: Any) -> bool:
+	"""Full-string ASCII match; ``str.isdigit``-style Unicode digits never pass."""
+	return isinstance(value, str) and value.isascii() and PATTERNS[name].fullmatch(value) is not None
+
+
+def strict_encode(value: str) -> str:
+	"""UTF-8 percent-encode every byte outside ``A-Z a-z 0-9 - _ . ~`` (uppercase hex)."""
+	return "".join(chr(byte) if byte in _UNRESERVED else f"%{byte:02X}" for byte in value.encode("utf-8"))
+
+
+def encode_path_param(value: str) -> str:
+	"""Encode one path parameter; ``""``, ``.`` and ``..`` cannot be sent as signed."""
+	if value in ("", ".", ".."):
+		raise ValueError("Devora signing: unroutable path parameter")
+	return strict_encode(value)
+
+
+def build_strict_query(pairs: Iterable[tuple[str, str]]) -> str:
+	"""Strict-encoded ``key=value`` pairs in the given order (the order is signed)."""
+	return "&".join(f"{strict_encode(key)}={strict_encode(value)}" for key, value in pairs)
+
+
+_STRICT_ASCII = re.compile(r"[\x21-\x7E]*")
+_BAD_ESCAPE = re.compile(r"%(?![0-9A-F]{2})")
+
+
+def _is_strict_ascii(value: str) -> bool:
+	return _STRICT_ASCII.fullmatch(value) is not None and not _BAD_ESCAPE.search(value)
+
+
+def is_valid_signed_path(path: str) -> bool:
+	"""Absolute, printable ASCII, uppercase escapes, no empty or dot segments."""
+	if not isinstance(path, str) or not path.startswith("/") or len(path) > 8192 or not _is_strict_ascii(path) or any(char in path for char in "?#\\"):
+		return False
+	if path == "/":
+		return True
+	try:
+		unquote(path, errors="strict")
+	except UnicodeDecodeError:
+		return False
+	return all(segment.replace("%2E", ".") not in ("", ".", "..") for segment in path[1:].split("/"))
+
+
+def is_valid_signed_query(query: str) -> bool:
+	if not isinstance(query, str) or "#" in query or len(query) > 8192 or not _is_strict_ascii(query):
+		return False
+	try:
+		unquote(query, errors="strict")
+		return True
+	except UnicodeDecodeError:
+		return False
+
+
+def build_canonical_string(
+	*,
+	direction: str,
+	key_id: str,
+	org_id: str,
+	sent_at: str,
+	request_id: str,
+	method: str,
+	path: str,
+	query: str,
+	body_sha256: str,
+) -> str:
+	"""Build the canonical string. Raises ValueError if any field is outside its grammar."""
+	checks = [
+		(direction in (DEVORA_TO_CUSTOMER, CUSTOMER_TO_DEVORA), "direction"),
+		(matches("key_id", key_id), "key id"),
+		(matches("org_id", org_id), "org id"),
+		(matches("sent_at", sent_at), "sent-at"),
+		(matches("request_id", request_id), "request id"),
+		(matches("method", method), "method"),
+		(is_valid_signed_path(path), "path"),
+		(is_valid_signed_query(query), "query"),
+		(matches("body_sha256", body_sha256), "body digest"),
+	]
+	for ok, name in checks:
+		if not ok:
+			raise ValueError(f"Devora signing: invalid {name}")
+	return "\n".join(
+		[ALGORITHM, VERSION, direction, key_id, org_id, sent_at, request_id, method, path, query, body_sha256]
+	)
+
+
+def _header_items(headers: HeaderInput) -> Iterable[tuple[str, Any]]:
+	if isinstance(headers, Mapping):
+		return headers.items()
+	return headers
+
+
+def get_single_header(headers: HeaderInput, name: str) -> Union[str, None, bool]:
+	"""The single value of a header; ``None`` if absent, ``False`` if repeated.
+
+	Accepts a mapping or a list of ``(name, value)`` pairs (so frameworks that
+	keep duplicates can pass them). Byte values are decoded as latin-1.
+	"""
+	values: list[str] = []
+	for key, value in _header_items(headers):
+		key = key.decode("latin-1") if isinstance(key, (bytes, bytearray)) else str(key)
+		if key.lower() != name or value is None:
+			continue
+		for item in value if isinstance(value, (list, tuple)) else [value]:
+			values.append(item.decode("latin-1") if isinstance(item, (bytes, bytearray)) else str(item))
+	if len(values) > 1:
+		return False
+	return values[0] if values else None
+
+
+def parse_signature_headers(headers: HeaderInput) -> tuple[Optional[dict[str, str]], Optional[str], Optional[str]]:
+	"""Return ``(headers, error_code, error)``. Never first-wins, never trims."""
+	version = get_single_header(headers, SECURITY_HEADERS.SIGNATURE_VERSION)
+	values = {
+		"key_id": get_single_header(headers, SECURITY_HEADERS.KEY_ID),
+		"org_id": get_single_header(headers, SECURITY_HEADERS.ORG_ID),
+		"sent_at": get_single_header(headers, SECURITY_HEADERS.SENT_AT),
+		"request_id": get_single_header(headers, SECURITY_HEADERS.REQUEST_ID),
+		"signature": get_single_header(headers, SECURITY_HEADERS.SIGNATURE),
+	}
+	if isinstance(version, str) and version != VERSION and version.isascii() and version.isdigit():
+		return None, "UNSUPPORTED_SIGNATURE_VERSION", "Unsupported signature version"
+	if not matches("signature_version", version) or not all(matches(name, value) for name, value in values.items()):
+		return None, "INVALID_SIGNATURE_HEADERS", "Missing, duplicate or malformed signature headers"
+	return values, None, None  # type: ignore[return-value]
+
+
+def has_identity_content_encoding(headers: HeaderInput) -> bool:
+	value = get_single_header(headers, "content-encoding")
+	return value is None or value == "identity"
+
+
+def replay_namespace(direction: str, key_id: str) -> str:
+	return f"v{VERSION}:{direction}:{key_id}"
+
+
+def replay_expires_at_ms(sent_at: int, now_seconds: int, tolerance_seconds: int) -> int:
+	"""Covers the floor second of the timestamp check plus one second of jitter."""
+	return (max(now_seconds, sent_at) + tolerance_seconds + 2) * 1000
+
+
+def parse_verified_query(query: str) -> dict[str, Union[str, list[str]]]:
+	"""Parse a verified raw query. Repeated keys become lists in wire order."""
+	result: dict[str, Union[str, list[str]]] = {}
+	for key, value in parse_qsl(query, keep_blank_values=True, strict_parsing=False, errors="strict"):
+		existing = result.get(key)
+		if existing is None:
+			result[key] = value
+		elif isinstance(existing, list):
+			existing.append(value)
+		else:
+			result[key] = [existing, value]
+	return result
+
+
+def parse_verified_json_body(body: bytes, content_type: Optional[str]) -> tuple[bool, Any]:
+	"""``(True, value)`` or ``(False, error)``. Empty means ``None``; otherwise
+	strict UTF-8 JSON declared as ``application/json``."""
+	if not body:
+		return True, None
+	if not isinstance(content_type, str) or not re.fullmatch(r"application/json(\s*;.*)?", content_type.strip(), re.IGNORECASE):
+		return False, "Signed request bodies must be application/json"
+	try:
+		return True, json.loads(
+			body.decode("utf-8"), object_pairs_hook=_unique_object,
+			parse_constant=_reject_constant, parse_float=_finite_float,
+		)
+	except (UnicodeDecodeError, ValueError, RecursionError):
+		return False, "Invalid JSON body"
+
+
+def _unique_object(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+	result: dict[str, Any] = {}
+	for key, value in pairs:
+		if key in result:
+			raise ValueError("Duplicate JSON key")
+		result[key] = value
+	return result
+
+
+def _reject_constant(value: str) -> Any:
+	raise ValueError("Non-finite JSON number")
+
+
+def _finite_float(value: str) -> float:
+	parsed = float(value)
+	if not math.isfinite(parsed):
+		raise ValueError("Non-finite JSON number")
+	return parsed
+
+
+def route_relative_path(raw_path: str, route_template: str) -> Optional[str]:
+	"""Last N raw segments of ``raw_path`` (N = the template's segment count)."""
+	count = len([part for part in route_template.split("/") if part])
+	if count == 0:
+		return "/"
+	segments = raw_path.split("/")
+	if len(segments) - 1 < count:
+		return None
+	return "/" + "/".join(segments[-count:])