federlet 0.1.0__py3-none-any.whl

federlet/__init__.py

@@ -0,0 +1,168 @@
+"""Federlet.
+
+A hubless HTTPS federation protocol for directory nodes (ADR-005).
+"""
+
+from .admission import (
+    AdmissionDecision,
+    AdmissionPolicy,
+    EvidenceVerifier,
+    KeyContinuityDecision,
+    KeyContinuityPolicy,
+    admit_manifest,
+    check_key_continuity,
+    domain_evidence_verifier,
+)
+from .audit import audit_record
+from .client import (
+    SIGNATURE_HEADER,
+    FederationClient,
+    ManifestVerificationError,
+    MissingCapabilitySummaryEndpointError,
+    MissingRevocationsEndpointError,
+    ResponseSignatureError,
+)
+from .crypto import (
+    JWK,
+    b64u_decode,
+    b64u_encode,
+    canonical_bytes,
+    generate_key,
+    public_jwk,
+    public_key_from_jwk,
+)
+from .discovery import (
+    DiscoveryOutcome,
+    DiscoveryRefreshReport,
+    refresh_discovered_members,
+)
+from .health import PeerHealthProbeResult, probe_peer_health
+from .membership import (
+    DisclosurePolicy,
+    MemberRecord,
+    MembershipTable,
+    PeerState,
+    apply_revocation_notice,
+    disclose_members,
+)
+from .models import (
+    AdmissionEvidence,
+    CapabilitySummary,
+    Disclosure,
+    DomainProofEvidence,
+    GenericAdmissionEvidence,
+    HealthResponse,
+    IntroduceRequest,
+    IntroduceResponse,
+    Manifest,
+    ManifestLimits,
+    MemberRef,
+    Membership,
+    MembersResponse,
+    ProtocolResponse,
+    PublicKey,
+    RevocationNotice,
+    RevocationsResponse,
+    Signature,
+    SignedRequest,
+)
+from .net import SSRFError
+from .protocols import (
+    MembershipStore,
+    NonceCache,
+    RateLimiter,
+    TokenBucketRateLimiter,
+)
+from .refresh import ManifestRefreshDecision, refresh_peer_manifest
+from .signing import (
+    build_signed_request,
+    check_body_size,
+    check_manifest,
+    find_jwk,
+    sha256_hex,
+    sign_dict,
+    sign_manifest,
+    sign_model,
+    verify_dict,
+    verify_manifest,
+    verify_model,
+    verify_response_signature,
+    verify_revocation_notice,
+    verify_signed_request,
+)
+
+__all__ = [
+    "FederationClient",
+    "MissingCapabilitySummaryEndpointError",
+    "ManifestVerificationError",
+    "MissingRevocationsEndpointError",
+    "ResponseSignatureError",
+    "SIGNATURE_HEADER",
+    "SSRFError",
+    "AdmissionDecision",
+    "AdmissionPolicy",
+    "admit_manifest",
+    "check_key_continuity",
+    "domain_evidence_verifier",
+    "KeyContinuityDecision",
+    "KeyContinuityPolicy",
+    "audit_record",
+    "JWK",
+    "b64u_decode",
+    "b64u_encode",
+    "canonical_bytes",
+    "generate_key",
+    "public_jwk",
+    "public_key_from_jwk",
+    "DiscoveryOutcome",
+    "DiscoveryRefreshReport",
+    "refresh_discovered_members",
+    "PeerHealthProbeResult",
+    "probe_peer_health",
+    "DisclosurePolicy",
+    "MemberRecord",
+    "MembershipTable",
+    "PeerState",
+    "apply_revocation_notice",
+    "disclose_members",
+    "AdmissionEvidence",
+    "CapabilitySummary",
+    "Disclosure",
+    "DomainProofEvidence",
+    "GenericAdmissionEvidence",
+    "HealthResponse",
+    "IntroduceRequest",
+    "IntroduceResponse",
+    "Manifest",
+    "ManifestLimits",
+    "MemberRef",
+    "Membership",
+    "MembersResponse",
+    "ProtocolResponse",
+    "PublicKey",
+    "RevocationNotice",
+    "RevocationsResponse",
+    "Signature",
+    "SignedRequest",
+    "EvidenceVerifier",
+    "MembershipStore",
+    "NonceCache",
+    "RateLimiter",
+    "TokenBucketRateLimiter",
+    "ManifestRefreshDecision",
+    "refresh_peer_manifest",
+    "build_signed_request",
+    "check_body_size",
+    "check_manifest",
+    "find_jwk",
+    "sha256_hex",
+    "sign_dict",
+    "sign_manifest",
+    "sign_model",
+    "verify_dict",
+    "verify_manifest",
+    "verify_model",
+    "verify_response_signature",
+    "verify_revocation_notice",
+    "verify_signed_request",
+]

federlet/_time.py

@@ -0,0 +1,15 @@
+"""Shared UTC timestamp helpers."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+
+def utc_now() -> datetime:
+    return datetime.now(UTC)
+
+
+def iso_z(dt: datetime | None) -> str | None:
+    if dt is None:
+        return None
+    return dt.astimezone(UTC).replace(microsecond=0).isoformat().replace("+00:00", "Z")

federlet/admission.py

@@ -0,0 +1,157 @@
+"""Small local-admission helper for signed node manifests."""
+
+from __future__ import annotations
+
+import ipaddress
+from dataclasses import dataclass, field
+from typing import Literal, Protocol
+from urllib.parse import urlparse
+
+from .models import DomainProofEvidence, Manifest
+from .net import is_disallowed_ip
+from .signing import check_manifest, verify_model
+
+
+class EvidenceVerifier(Protocol):
+    async def __call__(self, manifest: Manifest) -> tuple[bool, str]:
+        """Verify host-owned admission evidence for a manifest (may do I/O)."""
+        ...
+
+
+@dataclass(frozen=True)
+class AdmissionPolicy:
+    federation_id: str
+    protocol_versions: set[str]
+    require_expires_at: bool = True
+    require_signed_http: bool = True
+    require_https: bool = True
+    allow_private_hosts: bool = False
+    allowed_endpoint_domains: set[str] = field(default_factory=set)
+    evidence_verifier: EvidenceVerifier | None = None
+
+
+@dataclass(frozen=True)
+class AdmissionDecision:
+    accepted: bool
+    reason: str = "ok"
+
+
+@dataclass(frozen=True)
+class KeyContinuityPolicy:
+    allow_key_rotation: bool = True
+    evidence_verifier: EvidenceVerifier | None = None
+
+
+@dataclass(frozen=True)
+class KeyContinuityDecision:
+    action: Literal["accept", "quarantine", "reject"]
+    reason: str = "ok"
+
+
+async def admit_manifest(
+    manifest: Manifest,
+    policy: AdmissionPolicy,
+    *,
+    max_skew_seconds: int = 300,
+) -> AdmissionDecision:
+    ok, reason = check_manifest(manifest, max_skew_seconds=max_skew_seconds)
+    if not ok:
+        return AdmissionDecision(False, reason)
+    if policy.require_expires_at and not manifest.expires_at:
+        return AdmissionDecision(False, "missing_expires_at")
+    if policy.federation_id not in manifest.federations:
+        return AdmissionDecision(False, "wrong_federation")
+    if not set(manifest.protocol_versions) & policy.protocol_versions:
+        return AdmissionDecision(False, "unsupported_protocol")
+    if policy.require_signed_http and "signed_http" not in manifest.auth_methods:
+        return AdmissionDecision(False, "signed_http_required")
+
+    endpoint_reason = _check_endpoint(manifest.endpoint, policy)
+    if endpoint_reason:
+        return AdmissionDecision(False, endpoint_reason)
+
+    if policy.evidence_verifier is not None:
+        ok, reason = await policy.evidence_verifier(manifest)
+        if not ok:
+            return AdmissionDecision(False, reason)
+    return AdmissionDecision(True)
+
+
+async def check_key_continuity(
+    old_manifest: Manifest,
+    new_manifest: Manifest,
+    policy: KeyContinuityPolicy | None = None,
+) -> KeyContinuityDecision:
+    """Decide whether a refreshed manifest preserves signing-key continuity."""
+    policy = policy or KeyContinuityPolicy()
+    if old_manifest.node_id != new_manifest.node_id:
+        return KeyContinuityDecision("reject", "node_id_changed")
+    if old_manifest.org_id != new_manifest.org_id:
+        return KeyContinuityDecision("reject", "org_id_changed")
+
+    old_keys = {key.key_id: key.public_jwk for key in old_manifest.public_keys}
+    new_keys = {key.key_id: key.public_jwk for key in new_manifest.public_keys}
+    if old_keys == new_keys:
+        return KeyContinuityDecision("accept")
+
+    if not policy.allow_key_rotation:
+        return KeyContinuityDecision("reject", "rotation_denied")
+
+    signature = new_manifest.signature
+    if signature is not None:
+        old_jwk = old_keys.get(signature.key_id)
+        if old_jwk is not None and verify_model(new_manifest, old_jwk):
+            return KeyContinuityDecision("accept", "signed_rotation")
+
+    if policy.evidence_verifier is not None:
+        ok, reason = await policy.evidence_verifier(new_manifest)
+        if ok:
+            return KeyContinuityDecision("accept", "admission_evidence")
+        if reason == "rotation_denied":
+            return KeyContinuityDecision("reject", reason)
+
+    return KeyContinuityDecision("quarantine", "stale_manifest")
+
+
+async def domain_evidence_verifier(manifest: Manifest) -> tuple[bool, str]:
+    """Minimal built-in verifier for ADR domain_proof evidence.
+
+    This is deliberately not a DNS/CA proof. It only checks that the manifest's
+    declared endpoint host is inside the declared domain. Stronger evidence
+    types (SPIFFE, partner credentials, charter keys) belong behind host-supplied
+    callbacks with their own trust material.
+    """
+    ev = manifest.admission_evidence
+    if not isinstance(ev, DomainProofEvidence):
+        return False, "unsupported_evidence"
+    if not ev.domain:
+        return False, "bad_domain_evidence"
+    if _host_in_domain(urlparse(manifest.endpoint).hostname or "", ev.domain):
+        return True, "ok"
+    return False, "domain_mismatch"
+
+
+def _host_in_domain(host: str, domain: str) -> bool:
+    host = host.lower().rstrip(".")
+    domain = domain.lower().rstrip(".")
+    return host == domain or host.endswith("." + domain)
+
+
+def _check_endpoint(endpoint: str, policy: AdmissionPolicy) -> str | None:
+    parsed = urlparse(endpoint)
+    host = (parsed.hostname or "").lower().rstrip(".")
+    if not host:
+        return "bad_endpoint"
+    if policy.require_https and parsed.scheme != "https":
+        return "https_required"
+    if policy.allowed_endpoint_domains and not any(
+        _host_in_domain(host, d) for d in policy.allowed_endpoint_domains
+    ):
+        return "endpoint_domain_denied"
+    try:
+        ip = ipaddress.ip_address(host)
+    except ValueError:
+        return None
+    if not policy.allow_private_hosts and is_disallowed_ip(ip):
+        return "private_endpoint_denied"
+    return None

federlet/audit.py

@@ -0,0 +1,39 @@
+"""Pure audit-record builder for host logging sinks."""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from ._time import iso_z, utc_now
+
+
+def audit_record(
+    *,
+    event: str,
+    request_id: str | None = None,
+    query_id: str | None = None,
+    source_node_id: str | None = None,
+    target_node_id: str | None = None,
+    manifest_revision: int | None = None,
+    decision: str | None = None,
+    reason: str | None = None,
+    extra: Mapping[str, Any] | None = None,
+) -> dict[str, Any]:
+    record: dict[str, Any] = {
+        "timestamp": iso_z(utc_now()),
+        "event": event,
+    }
+    optional = {
+        "request_id": request_id,
+        "query_id": query_id,
+        "source_node_id": source_node_id,
+        "target_node_id": target_node_id,
+        "manifest_revision": manifest_revision,
+        "decision": decision,
+        "reason": reason,
+    }
+    record.update({key: value for key, value in optional.items() if value is not None})
+    if extra:
+        record.update({key: value for key, value in extra.items() if value is not None})
+    return record

federlet/client.py

@@ -0,0 +1,184 @@
+"""httpx client helpers for federation calls, with SSRF-safe manifest fetch."""
+
+from __future__ import annotations
+
+import asyncio
+from urllib.parse import urlparse
+
+import httpx
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+
+from .models import (
+    CapabilitySummary,
+    HealthResponse,
+    IntroduceRequest,
+    IntroduceResponse,
+    Manifest,
+    MembersResponse,
+    ProtocolResponse,
+    RevocationsResponse,
+)
+from .net import _assert_public_host
+from .signing import build_signed_request, check_manifest, verify_response_signature
+
+SIGNATURE_HEADER = "X-Federlet-Signature"
+
+
+class ResponseSignatureError(ValueError):
+    """Raised when a peer returns an unsigned or unverifiable response."""
+
+
+class ManifestVerificationError(ValueError):
+    """Raised when a fetched manifest is unsigned, stale, or unverifiable."""
+
+
+class MissingRevocationsEndpointError(ValueError):
+    """Raised when a peer manifest does not advertise a revocations endpoint."""
+
+
+class MissingCapabilitySummaryEndpointError(ValueError):
+    """Raised when a peer manifest does not advertise a capability summary endpoint."""
+
+
+def _verify_response(
+    peer: Manifest,
+    resp: IntroduceResponse | MembersResponse | RevocationsResponse | CapabilitySummary,
+) -> bool:
+    return verify_response_signature(peer, resp)
+
+
+class FederationClient:
+    def __init__(
+        self,
+        *,
+        node_id: str,
+        federation_id: str,
+        key: Ed25519PrivateKey,
+        key_id: str,
+        manifest_revision: int = 0,
+        allow_private: bool = False,
+        client: httpx.AsyncClient | None = None,
+    ) -> None:
+        self.node_id = node_id
+        self.federation_id = federation_id
+        self.key = key
+        self.key_id = key_id
+        self.manifest_revision = manifest_revision
+        self.allow_private = allow_private
+        self._http = client or httpx.AsyncClient(timeout=10.0, follow_redirects=False)
+
+    async def __aenter__(self) -> FederationClient:
+        return self
+
+    async def __aexit__(self, *exc: object) -> None:
+        await self.close()
+
+    def _signed_headers(
+        self, target_node_id: str, method: str, path: str, body: bytes
+    ) -> dict[str, str]:
+        env = build_signed_request(
+            self.key,
+            self.key_id,
+            federation_id=self.federation_id,
+            source_node_id=self.node_id,
+            target_node_id=target_node_id,
+            method=method,
+            path=path,
+            body=body,
+            source_manifest_revision=self.manifest_revision,
+        )
+        return {SIGNATURE_HEADER: env.model_dump_json(exclude_none=True)}
+
+    async def _send(
+        self,
+        target_node_id: str,
+        method: str,
+        url: str,
+        *,
+        body: bytes = b"",
+        params: dict | None = None,
+    ) -> httpx.Response:
+        """Sign, send, and raise-for-status a single federation call."""
+        headers = self._signed_headers(target_node_id, method, urlparse(url).path, body)
+        r = await self._http.request(
+            method, url, content=body or None, params=params, headers=headers
+        )
+        r.raise_for_status()
+        return r
+
+    async def fetch_manifest(
+        self, manifest_url: str, *, max_skew_seconds: int = 300
+    ) -> Manifest:
+        # DNS resolution is blocking; keep the SSRF guard off the event loop.
+        await asyncio.get_running_loop().run_in_executor(
+            None, _assert_public_host, manifest_url, self.allow_private
+        )
+        r = await self._http.get(manifest_url)
+        r.raise_for_status()
+        manifest = Manifest.model_validate(r.json())
+        ok, reason = check_manifest(manifest, max_skew_seconds=max_skew_seconds)
+        if not ok:
+            raise ManifestVerificationError(reason)
+        return manifest
+
+    async def introduce(
+        self, peer: Manifest, intro: IntroduceRequest
+    ) -> IntroduceResponse:
+        body = intro.model_dump_json(exclude_none=True).encode()
+        r = await self._send(
+            peer.node_id, "POST", peer.membership.introduce_url, body=body
+        )
+        resp = IntroduceResponse.model_validate(r.json())
+        if not _verify_response(peer, resp):
+            raise ResponseSignatureError("bad_signature")
+        return resp
+
+    async def get_members(
+        self, peer: Manifest, since: str | None = None
+    ) -> MembersResponse:
+        params = {"since": since} if since else None
+        r = await self._send(
+            peer.node_id, "GET", peer.membership.members_url, params=params
+        )
+        resp = MembersResponse.model_validate(r.json())
+        if not _verify_response(peer, resp):
+            raise ResponseSignatureError("bad_signature")
+        return resp
+
+    async def get_revocations(
+        self, peer: Manifest, since: str | None = None
+    ) -> RevocationsResponse:
+        if peer.membership.revocations_url is None:
+            raise MissingRevocationsEndpointError("missing_revocations_url")
+        params = {"since": since} if since else None
+        r = await self._send(
+            peer.node_id, "GET", peer.membership.revocations_url, params=params
+        )
+        resp = RevocationsResponse.model_validate(r.json())
+        if not _verify_response(peer, resp):
+            raise ResponseSignatureError("bad_signature")
+        return resp
+
+    async def get_capability_summary(self, peer: Manifest) -> CapabilitySummary:
+        if peer.capability_summary_url is None:
+            raise MissingCapabilitySummaryEndpointError(
+                "missing_capability_summary_url"
+            )
+        r = await self._send(peer.node_id, "GET", peer.capability_summary_url)
+        resp = CapabilitySummary.model_validate(r.json())
+        if not _verify_response(peer, resp):
+            raise ResponseSignatureError("bad_signature")
+        return resp
+
+    async def get_protocol(self, peer: Manifest) -> ProtocolResponse:
+        r = await self._send(
+            peer.node_id, "GET", f"{peer.endpoint.rstrip('/')}/protocol"
+        )
+        return ProtocolResponse.model_validate(r.json())
+
+    async def get_health(self, peer: Manifest) -> HealthResponse:
+        r = await self._send(peer.node_id, "GET", f"{peer.endpoint.rstrip('/')}/health")
+        return HealthResponse.model_validate(r.json())
+
+    async def close(self) -> None:
+        await self._http.aclose()

federlet/crypto.py

@@ -0,0 +1,57 @@
+"""Ed25519 keys, JWK conversion, canonical bytes, and detached signing."""
+
+from __future__ import annotations
+
+import base64
+from typing import Any
+
+import rfc8785
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric.ed25519 import (
+    Ed25519PrivateKey,
+    Ed25519PublicKey,
+)
+
+JWK = dict[str, str]
+
+
+def b64u_encode(raw: bytes) -> str:
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()
+
+
+def b64u_decode(s: str) -> bytes:
+    return base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+
+
+def generate_key() -> Ed25519PrivateKey:
+    return Ed25519PrivateKey.generate()
+
+
+def public_jwk(key: Ed25519PrivateKey | Ed25519PublicKey) -> JWK:
+    pub = key.public_key() if isinstance(key, Ed25519PrivateKey) else key
+    raw = pub.public_bytes(serialization.Encoding.Raw, serialization.PublicFormat.Raw)
+    return {"kty": "OKP", "crv": "Ed25519", "alg": "EdDSA", "x": b64u_encode(raw)}
+
+
+def public_key_from_jwk(jwk: JWK) -> Ed25519PublicKey:
+    if jwk.get("kty") != "OKP" or jwk.get("crv") != "Ed25519":
+        raise ValueError("unsupported JWK; expected OKP/Ed25519")
+    return Ed25519PublicKey.from_public_bytes(b64u_decode(jwk["x"]))
+
+
+def canonical_bytes(obj: Any) -> bytes:
+    """Deterministic JSON per RFC 8785 (JCS) so peers in any language agree."""
+    return rfc8785.dumps(obj)
+
+
+def sign_bytes(key: Ed25519PrivateKey, data: bytes) -> str:
+    return b64u_encode(key.sign(data))
+
+
+def verify_bytes(jwk: JWK, sig: str, data: bytes) -> bool:
+    try:
+        public_key_from_jwk(jwk).verify(b64u_decode(sig), data)
+        return True
+    except (InvalidSignature, ValueError):
+        return False