firetail-finchly 0.0.1__py3-none-any.whl

firetail_finchly/__init__.py

@@ -0,0 +1,37 @@
+"""Python SDK for the Finchly platform."""
+
+from ._version import __version__
+from .config import DEFAULT_MANIFEST_PATH, PlatformConfig, load_config
+from .errors import IDENTITY_REJECTIONS, FinchlyError, IdentityError
+from .identity import IDENTITY_HEADER, Identity, IdentityVerifier
+from .manifest import check_manifest, load_manifest
+from .platform_api import (
+    MANIFEST_VERSION,
+    PLATFORM_API_VERSION,
+    SDK_NAME,
+    SDK_VERSION,
+    SUPPORTED_PLATFORM_API_VERSIONS,
+)
+from .service import ServiceClient, ServiceResponse
+
+__all__ = [
+    "DEFAULT_MANIFEST_PATH",
+    "FinchlyError",
+    "IDENTITY_HEADER",
+    "IDENTITY_REJECTIONS",
+    "Identity",
+    "IdentityError",
+    "IdentityVerifier",
+    "MANIFEST_VERSION",
+    "PLATFORM_API_VERSION",
+    "PlatformConfig",
+    "SDK_NAME",
+    "SDK_VERSION",
+    "SUPPORTED_PLATFORM_API_VERSIONS",
+    "ServiceClient",
+    "ServiceResponse",
+    "__version__",
+    "check_manifest",
+    "load_config",
+    "load_manifest",
+]

firetail_finchly/_version.py

@@ -0,0 +1 @@
+__version__ = "0.0.1"

firetail_finchly/config.py

@@ -0,0 +1,90 @@
+"""Settings a service is deployed with. See spec/registration.md, section 1."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+from typing import Mapping
+from urllib.parse import urlsplit
+
+from .errors import FinchlyError
+
+#: Where the manifest lives in an image unless PLATFORM_MANIFEST_PATH says otherwise.
+DEFAULT_MANIFEST_PATH = "/finchly/manifest.json"
+
+
+@dataclass(frozen=True)
+class PlatformConfig:
+    #: The gateway's internal address, without a trailing slash.
+    gateway_url: str
+    #: Path of the manifest inside the container.
+    manifest_path: str = DEFAULT_MANIFEST_PATH
+    #: Address the gateway should use to reach this service, if set.
+    app_address: str | None = None
+    #: Enrolment token for self-registration, if set. Left out of the repr,
+    #: so it does not appear when the config is logged.
+    enrolment_token: str | None = field(default=None, repr=False)
+    #: The credential a built-in service registers its instance key with,
+    #: if set. Left out of the repr, like the enrolment token.
+    service_credential: str | None = field(default=None, repr=False)
+
+
+def _http_url(name: str, value: str, problems: list[str]) -> str | None:
+    try:
+        parts = urlsplit(value)
+        # Reading these can raise for a malformed port or host.
+        _ = parts.port, parts.hostname
+    except ValueError:
+        problems.append(f"{name} is not a URL")
+        return None
+    if not parts.scheme or " " in value:
+        problems.append(f"{name} is not a URL")
+        return None
+    if parts.scheme not in ("http", "https") or not parts.hostname:
+        problems.append(f"{name} must be an http or https URL")
+        return None
+    if parts.username or parts.password:
+        problems.append(f"{name} must not contain credentials")
+        return None
+    if parts.query or parts.fragment:
+        problems.append(f"{name} must not have a query string or fragment")
+        return None
+    return value.rstrip("/")
+
+
+def load_config(env: Mapping[str, str] | None = None) -> PlatformConfig:
+    """Read the platform settings from the environment.
+
+    Raises a FinchlyError listing every problem, so a misconfigured
+    container fails once with the full picture.
+    """
+    env = os.environ if env is None else env
+    problems: list[str] = []
+
+    gateway_url: str | None = None
+    raw_gateway = (env.get("PLATFORM_GATEWAY_URL") or "").strip()
+    if not raw_gateway:
+        problems.append("PLATFORM_GATEWAY_URL is not set")
+    else:
+        gateway_url = _http_url("PLATFORM_GATEWAY_URL", raw_gateway, problems)
+
+    raw_address = (env.get("PLATFORM_APP_ADDRESS") or "").strip()
+    app_address = _http_url("PLATFORM_APP_ADDRESS", raw_address, problems) if raw_address else None
+
+    manifest_path = (env.get("PLATFORM_MANIFEST_PATH") or "").strip() or DEFAULT_MANIFEST_PATH
+    if not manifest_path.startswith("/"):
+        problems.append("PLATFORM_MANIFEST_PATH must be an absolute path")
+
+    enrolment_token = (env.get("PLATFORM_ENROLMENT_TOKEN") or "").strip() or None
+    service_credential = (env.get("PLATFORM_SERVICE_CREDENTIAL") or "").strip() or None
+
+    if problems or gateway_url is None:
+        raise FinchlyError("config_invalid", "Platform settings are invalid", problems)
+
+    return PlatformConfig(
+        gateway_url=gateway_url,
+        manifest_path=manifest_path,
+        app_address=app_address,
+        enrolment_token=enrolment_token,
+        service_credential=service_credential,
+    )

firetail_finchly/errors.py

@@ -0,0 +1,48 @@
+from __future__ import annotations
+
+from typing import Sequence
+
+
+class FinchlyError(Exception):
+    """Every error this SDK raises on purpose.
+
+    ``code`` is stable and safe to branch on. ``problems`` lists each thing
+    that was wrong, so a caller can report all of them at once instead of
+    one per restart.
+
+    Codes: ``config_invalid``, ``manifest_invalid``, ``manifest_unreadable``,
+    ``identity_invalid``, ``gateway_unreachable``, ``platform_api_unsupported``,
+    ``service_call_invalid``, ``service_key_rejected``.
+    """
+
+    def __init__(self, code: str, message: str, problems: Sequence[str] = ()) -> None:
+        self.code = code
+        self.problems: tuple[str, ...] = tuple(problems)
+        text = f"{message}: {'; '.join(self.problems)}" if self.problems else message
+        super().__init__(text)
+
+
+#: Why an identity token can be rejected. Defined in spec/identity-token.md.
+IDENTITY_REJECTIONS = (
+    "missing",
+    "malformed",
+    "algorithm",
+    "unknown_key",
+    "signature",
+    "issuer",
+    "audience",
+    "expired",
+    "claims",
+)
+
+
+class IdentityError(FinchlyError):
+    """The request carries no acceptable identity.
+
+    Treat it as unauthenticated (HTTP 401). ``reason`` is one of
+    ``IDENTITY_REJECTIONS`` and is for logs; do not show it to the caller.
+    """
+
+    def __init__(self, reason: str) -> None:
+        super().__init__("identity_invalid", f"Identity token rejected: {reason}")
+        self.reason = reason

firetail_finchly/identity.py

@@ -0,0 +1,322 @@
+"""Verifies the x-platform-identity token.
+
+Every check here is required by spec/identity-token.md in
+firetail-io/finchly, and the conformance vectors in tests/conformance pin
+the verdict for each kind of bad token.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+import threading
+import time
+import urllib.error
+import urllib.request
+from dataclasses import dataclass
+from types import MappingProxyType
+from typing import Any, Callable, Mapping
+from urllib.parse import urlsplit
+
+import jwt
+
+from .errors import FinchlyError, IdentityError
+from .platform_api import SUPPORTED_PLATFORM_API_VERSIONS
+
+#: Header the gateway sets on every request it proxies.
+IDENTITY_HEADER = "x-platform-identity"
+
+_REQUIRED_CLAIMS = ("iss", "sub", "aud", "iat", "exp")
+_DEFAULT_CLOCK_SKEW_SECONDS = 30
+_KEY_CACHE_SECONDS = 60 * 60
+_KEY_REFETCH_COOLDOWN_SECONDS = 30
+_GATEWAY_TIMEOUT_SECONDS = 5.0
+_SLUG = re.compile(r"[a-z][a-z0-9]*(-[a-z0-9]+)*")
+
+
+@dataclass(frozen=True)
+class Identity:
+    """Who is calling, as asserted by the gateway."""
+
+    #: The user's platform id, or ``service:<slug>`` for a service calling as itself.
+    subject: str
+    #: True when the caller is a service calling as itself, with no user.
+    service: bool
+    email: str | None
+    name: str | None
+    #: Platform group names.
+    groups: tuple[str, ...]
+    #: The user's roles for this service.
+    roles: tuple[str, ...]
+    #: How the caller was authenticated.
+    amr: tuple[str, ...]
+    #: ``service:<slug>`` when a service is acting on the user's behalf.
+    actor: str | None
+    session_id: str | None
+    #: Every claim in the token. Read-only.
+    claims: Mapping[str, Any]
+
+
+def _is_number(value: Any) -> bool:
+    return isinstance(value, (int, float)) and not isinstance(value, bool)
+
+
+def _optional_string(claims: Mapping[str, Any], name: str) -> str | None:
+    value = claims.get(name)
+    if value is None and name not in claims:
+        return None
+    if not isinstance(value, str):
+        raise IdentityError("claims")
+    return value
+
+
+def _string_tuple(claims: Mapping[str, Any], name: str) -> tuple[str, ...]:
+    if name not in claims:
+        return ()
+    value = claims[name]
+    if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+        raise IdentityError("claims")
+    return tuple(value)
+
+
+def _keys_by_id(jwks: Any) -> dict[str, Any]:
+    """Index a JWKS by kid, keeping only keys usable for ES256."""
+    keys: dict[str, Any] = {}
+    entries = jwks.get("keys") if isinstance(jwks, dict) else None
+    if not isinstance(entries, list):
+        raise ValueError("key set has no keys list")
+    for entry in entries:
+        if not isinstance(entry, dict) or not isinstance(entry.get("kid"), str):
+            continue
+        if entry.get("kty") != "EC" or entry.get("crv") != "P-256":
+            continue
+        try:
+            keys[entry["kid"]] = jwt.PyJWK(entry, algorithm="ES256").key
+        except jwt.PyJWTError:
+            continue
+    return keys
+
+
+class IdentityVerifier:
+    """Verifies identity tokens for one service.
+
+    Create one at startup and reuse it: it caches the gateway's issuer and
+    signing keys. It is safe to share between threads.
+
+    Give ``gateway_url`` (``PLATFORM_GATEWAY_URL``); the issuer and keys are
+    fetched from it. ``issuer`` and ``jwks`` together fix them instead, for
+    tests.
+    """
+
+    def __init__(
+        self,
+        *,
+        slug: str,
+        gateway_url: str | None = None,
+        issuer: str | None = None,
+        jwks: Mapping[str, Any] | None = None,
+        clock_skew_seconds: float = _DEFAULT_CLOCK_SKEW_SECONDS,
+        now: Callable[[], float] | None = None,
+    ) -> None:
+        problems: list[str] = []
+        if not isinstance(slug, str) or not _SLUG.fullmatch(slug):
+            problems.append("slug must be this service's slug")
+        fixed = issuer is not None or jwks is not None
+        if fixed and gateway_url is not None:
+            problems.append("give either gateway_url, or issuer and jwks, not both")
+        elif fixed and (issuer is None or jwks is None):
+            problems.append("issuer and jwks must be given together")
+        elif not fixed and not gateway_url:
+            problems.append("gateway_url is required")
+        elif not fixed and urlsplit(gateway_url or "").scheme not in ("http", "https"):
+            # urllib would otherwise follow file: and other schemes.
+            problems.append("gateway_url must be an http or https URL")
+        if not _is_number(clock_skew_seconds) or clock_skew_seconds < 0:
+            problems.append("clock_skew_seconds must be zero or more")
+        if problems:
+            raise FinchlyError("config_invalid", "Identity verifier options are invalid", problems)
+
+        self._slug = slug
+        self._skew = clock_skew_seconds
+        #: Seconds since the epoch.
+        self._now = now or time.time
+        self._gateway_url = gateway_url.rstrip("/") if gateway_url else None
+        self._lock = threading.Lock()
+
+        self._issuer: str | None = issuer
+        self._keys: dict[str, Any] | None = None
+        self._keys_fetched_at = 0.0
+        if jwks is not None:
+            try:
+                self._keys = _keys_by_id(dict(jwks))
+            except ValueError as exc:
+                raise FinchlyError(
+                    "config_invalid", "Identity verifier options are invalid", [f"jwks: {exc}"]
+                ) from exc
+
+    # ── Gateway ────────────────────────────────────────────────────────────
+
+    def _get_json(self, path: str) -> Any:
+        url = f"{self._gateway_url}{path}"
+        try:
+            with urllib.request.urlopen(url, timeout=_GATEWAY_TIMEOUT_SECONDS) as response:
+                return json.loads(response.read().decode("utf-8"))
+        except (urllib.error.URLError, OSError, ValueError) as exc:
+            raise FinchlyError("gateway_unreachable", f"Cannot read {url}", [str(exc)]) from exc
+
+    def _discovered_issuer(self) -> str:
+        """The gateway's issuer. A failed discovery is not cached."""
+        if self._issuer is not None:
+            return self._issuer
+        with self._lock:
+            if self._issuer is None:
+                path = "/_gateway/.well-known/platform.json"
+                doc = self._get_json(path)
+                issuer = doc.get("issuer") if isinstance(doc, dict) else None
+                if not isinstance(issuer, str) or not issuer:
+                    raise FinchlyError(
+                        "gateway_unreachable", f"{self._gateway_url}{path} does not name an issuer"
+                    )
+                served = doc.get("platformApi")
+                served = served if isinstance(served, list) else []
+                if not any(v in SUPPORTED_PLATFORM_API_VERSIONS for v in served):
+                    raise FinchlyError(
+                        "platform_api_unsupported",
+                        f"The gateway serves platform API {json.dumps(served)}; "
+                        f"this SDK speaks {', '.join(SUPPORTED_PLATFORM_API_VERSIONS)}",
+                    )
+                self._issuer = issuer
+            return self._issuer
+
+    def _key_for(self, kid: Any) -> Any:
+        """The published key with this id, refetching when it is not known."""
+        if not isinstance(kid, str):
+            raise IdentityError("unknown_key")
+        if self._gateway_url is None:
+            key = (self._keys or {}).get(kid)
+            if key is None:
+                raise IdentityError("unknown_key")
+            return key
+
+        with self._lock:
+            age = time.monotonic() - self._keys_fetched_at
+            known = self._keys is not None and kid in self._keys
+            stale = self._keys is None or age >= _KEY_CACHE_SECONDS
+            # An unknown kid may mean the gateway has rotated its key, so
+            # look again, but not more often than the cooldown allows.
+            may_refetch = self._keys is None or age >= _KEY_REFETCH_COOLDOWN_SECONDS
+            if stale or (not known and may_refetch):
+                try:
+                    fetched = _keys_by_id(self._get_json("/_gateway/.well-known/jwks.json"))
+                except ValueError as exc:
+                    raise FinchlyError(
+                        "gateway_unreachable", "The gateway's key set is not usable", [str(exc)]
+                    ) from exc
+                self._keys = fetched
+                self._keys_fetched_at = time.monotonic()
+            key = (self._keys or {}).get(kid)
+        if key is None:
+            raise IdentityError("unknown_key")
+        return key
+
+    # ── Verification ───────────────────────────────────────────────────────
+
+    def verify(self, token: str | None) -> Identity:
+        """Verify a token. Raises IdentityError if it is not acceptable."""
+        if not isinstance(token, str) or not token:
+            raise IdentityError("missing")
+
+        try:
+            header = jwt.get_unverified_header(token)
+        except jwt.PyJWTError as exc:
+            raise IdentityError("malformed") from exc
+        # Checked first and by hand, so that no other property of the token
+        # can influence what happens to one with the wrong algorithm.
+        if header.get("alg") != "ES256":
+            raise IdentityError("algorithm")
+
+        issuer = self._discovered_issuer()
+        key = self._key_for(header.get("kid"))
+
+        try:
+            # Only the signature is checked here. The claims are checked
+            # below, against this verifier's clock, so that the rules are the
+            # ones in the specification and not the library's defaults.
+            claims = jwt.decode(
+                token,
+                key=key,
+                algorithms=["ES256"],
+                options={
+                    "verify_signature": True,
+                    "verify_exp": False,
+                    "verify_nbf": False,
+                    "verify_iat": False,
+                    "verify_aud": False,
+                    "verify_iss": False,
+                    "verify_sub": False,
+                    "verify_jti": False,
+                    "require": [],
+                },
+            )
+        except jwt.InvalidSignatureError as exc:
+            raise IdentityError("signature") from exc
+        except jwt.InvalidAlgorithmError as exc:
+            raise IdentityError("algorithm") from exc
+        except jwt.DecodeError as exc:
+            raise IdentityError("malformed") from exc
+        except jwt.PyJWTError as exc:
+            raise IdentityError("claims") from exc
+
+        return self._identity(claims, issuer)
+
+    def _identity(self, claims: dict[str, Any], issuer: str) -> Identity:
+        for name in _REQUIRED_CLAIMS:
+            if name not in claims:
+                raise IdentityError("claims")
+        if claims["iss"] != issuer:
+            raise IdentityError("issuer")
+        # A token is for exactly one service. A list of audiences that
+        # happens to include this one is not accepted.
+        if claims["aud"] != self._slug or not isinstance(claims["aud"], str):
+            raise IdentityError("audience")
+        if not isinstance(claims["sub"], str) or not claims["sub"]:
+            raise IdentityError("claims")
+        if not _is_number(claims["iat"]) or not _is_number(claims["exp"]):
+            raise IdentityError("claims")
+        # Rejected once the full skew has passed since exp.
+        if claims["exp"] <= self._now() - self._skew:
+            raise IdentityError("expired")
+
+        actor: str | None = None
+        if "act" in claims:
+            act = claims["act"]
+            if not isinstance(act, dict) or not isinstance(act.get("sub"), str):
+                raise IdentityError("claims")
+            actor = act["sub"]
+
+        subject: str = claims["sub"]
+        return Identity(
+            subject=subject,
+            service=subject.startswith("service:"),
+            email=_optional_string(claims, "email"),
+            name=_optional_string(claims, "name"),
+            groups=_string_tuple(claims, "groups"),
+            roles=_string_tuple(claims, "roles"),
+            amr=_string_tuple(claims, "amr"),
+            actor=actor,
+            session_id=_optional_string(claims, "sid"),
+            claims=MappingProxyType(dict(claims)),
+        )
+
+    def from_headers(self, headers: Mapping[str, Any]) -> Identity:
+        """Verify the token in a request's headers.
+
+        Header names are matched without regard to case. The gateway sets the
+        header exactly once, so more than one value is rejected.
+        """
+        values = [v for k, v in headers.items() if isinstance(k, str) and k.lower() == IDENTITY_HEADER]
+        if not values:
+            raise IdentityError("missing")
+        if len(values) > 1 or isinstance(values[0], (list, tuple)):
+            raise IdentityError("malformed")
+        return self.verify(values[0])

firetail_finchly/manifest.py

@@ -0,0 +1,97 @@
+"""Load a Finchly manifest and check what this SDK depends on.
+
+The schema is in firetail-io/finchly under spec/manifest.
+"""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from .config import DEFAULT_MANIFEST_PATH
+from .errors import FinchlyError
+from .platform_api import MANIFEST_VERSION, SUPPORTED_PLATFORM_API_VERSIONS
+
+# Used with fullmatch: in Python "$" also matches before a trailing newline,
+# which would let "slug\n" through.
+_SLUG = re.compile(r"[a-z][a-z0-9]*(-[a-z0-9]+)*")
+
+
+def _is_int(value: Any) -> bool:
+    # bool is a subclass of int in Python; True is not a port.
+    return isinstance(value, int) and not isinstance(value, bool)
+
+
+def check_manifest(value: Any) -> dict[str, Any]:
+    """Check the parts of a manifest this SDK itself depends on.
+
+    This is deliberately not the full schema. The platform runs the full
+    check when the service registers, and is the authority. The point here
+    is to stop a container at startup, with a clear message, when the
+    manifest is missing something the SDK cannot work without.
+    """
+    if not isinstance(value, dict):
+        raise FinchlyError("manifest_invalid", "Manifest is not a JSON object")
+
+    problems: list[str] = []
+
+    version = value.get("manifestVersion")
+    if not _is_int(version) or version != MANIFEST_VERSION:
+        problems.append(f"manifestVersion must be {MANIFEST_VERSION}")
+
+    platform_api = value.get("platformApi")
+    if not isinstance(platform_api, str):
+        problems.append("platformApi must be a string")
+    elif platform_api not in SUPPORTED_PLATFORM_API_VERSIONS:
+        problems.append(
+            f'platformApi "{platform_api}" is not one this SDK speaks '
+            f"({', '.join(SUPPORTED_PLATFORM_API_VERSIONS)})"
+        )
+
+    slug = value.get("slug")
+    slug_ok = isinstance(slug, str) and 2 <= len(slug) <= 40 and bool(_SLUG.fullmatch(slug))
+    if not slug_ok:
+        problems.append(
+            "slug must be 2 to 40 lowercase letters, digits and single hyphens, starting with a letter"
+        )
+
+    name = value.get("name")
+    if not isinstance(name, str) or not name:
+        problems.append("name must be a non-empty string")
+
+    release = value.get("version")
+    if not isinstance(release, str) or not release:
+        problems.append("version must be a non-empty string")
+
+    port = value.get("port")
+    # isinstance is spelled out here so type checkers narrow `port` to int.
+    if not (isinstance(port, int) and not isinstance(port, bool) and 1 <= port <= 65535):
+        problems.append("port must be an integer from 1 to 65535")
+
+    health_path = value.get("healthPath")
+    if not isinstance(health_path, str):
+        problems.append("healthPath must be a string")
+    elif slug_ok and not health_path.startswith(f"/{slug}/"):
+        problems.append(f"healthPath must start with /{slug}/")
+
+    if problems:
+        raise FinchlyError("manifest_invalid", "Manifest is invalid", problems)
+    return value
+
+
+def load_manifest(path: str = DEFAULT_MANIFEST_PATH) -> dict[str, Any]:
+    """Read and check the manifest from the container's filesystem."""
+    try:
+        with open(path, encoding="utf-8") as handle:
+            text = handle.read()
+    except OSError as exc:
+        raise FinchlyError(
+            "manifest_unreadable", f"Cannot read manifest at {path}", [str(exc)]
+        ) from exc
+
+    try:
+        parsed = json.loads(text)
+    except ValueError as exc:
+        raise FinchlyError("manifest_invalid", f"Manifest at {path} is not valid JSON") from exc
+    return check_manifest(parsed)

firetail_finchly/platform_api.py

@@ -0,0 +1,24 @@
+"""The platform API versions this SDK release speaks.
+
+The platform API is specified in firetail-io/finchly under spec/. This
+package is one implementation of it and defines no protocol of its own.
+"""
+
+from __future__ import annotations
+
+from ._version import __version__
+
+#: Platform API version this SDK release speaks by default.
+PLATFORM_API_VERSION = "v1"
+
+#: Every platform API version this SDK release can speak.
+SUPPORTED_PLATFORM_API_VERSIONS: tuple[str, ...] = ("v1",)
+
+#: Manifest schema version this SDK release reads.
+MANIFEST_VERSION = 1
+
+#: Package name, as reported to the platform at registration.
+SDK_NAME = "firetail_finchly"
+
+#: Package version, as reported to the platform at registration.
+SDK_VERSION = __version__

firetail_finchly/service.py

@@ -0,0 +1,351 @@
+"""Calls from this service to another, through the gateway.
+
+Services never address each other directly. A call goes to the gateway's
+internal address with a token this instance signs with its own key; the
+gateway checks it, decides whether the call is allowed, and forwards it.
+The token format is in spec/service-token.md and key registration in
+spec/registration.md, both in firetail-io/finchly.
+"""
+
+from __future__ import annotations
+
+import base64
+import hashlib
+import json
+import re
+import threading
+import time
+import urllib.error
+import urllib.request
+import uuid
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any, Callable, Mapping
+
+import jwt
+from cryptography.hazmat.primitives.asymmetric import ec
+
+from .errors import FinchlyError
+
+_SLUG = re.compile(r"[a-z][a-z0-9]*(-[a-z0-9]+)*")
+_USER_ID = re.compile(r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}")
+_DOT_SEGMENT = re.compile(r"(^|/)\.\.?(/|$)")
+#: The audience of a token meant for the gateway itself.
+_GATEWAY_AUDIENCE = "gateway"
+_KEYS_PATH = "/_gateway/keys"
+#: How long a token is valid. The specification allows up to 300 seconds.
+_TOKEN_TTL_SECONDS = 60
+_REGISTRATION_TIMEOUT_SECONDS = 10.0
+#: After a call is refused as unauthenticated, wait this long before registering again.
+_REREGISTER_COOLDOWN_SECONDS = 60.0
+
+
+class _NoRedirect(urllib.request.HTTPRedirectHandler):
+    """Hand a redirect back instead of following it.
+
+    A credential or a token is for the gateway and goes nowhere a response
+    points.
+    """
+
+    def redirect_request(self, req, fp, code, msg, headers, newurl):  # type: ignore[no-untyped-def]
+        return None
+
+
+_OPENER = urllib.request.build_opener(_NoRedirect)
+
+
+@dataclass(frozen=True)
+class ServiceResponse:
+    """What the target answered."""
+
+    status: int
+    #: Header names in lower case.
+    headers: Mapping[str, str]
+    body: bytes
+
+    def json(self) -> Any:
+        return json.loads(self.body.decode("utf-8"))
+
+
+def _b64url(data: bytes) -> str:
+    return base64.urlsafe_b64encode(data).rstrip(b"=").decode("ascii")
+
+
+def _invalid(message: str) -> FinchlyError:
+    return FinchlyError("service_call_invalid", message)
+
+
+def _send(request: urllib.request.Request, timeout: float) -> ServiceResponse:
+    """Send a request and return the response, whatever its status."""
+    try:
+        with _OPENER.open(request, timeout=timeout) as response:
+            return ServiceResponse(
+                response.status, {k.lower(): v for k, v in response.headers.items()}, response.read()
+            )
+    except urllib.error.HTTPError as err:
+        with err:
+            return ServiceResponse(err.code, {k.lower(): v for k, v in err.headers.items()}, err.read())
+
+
+class ServiceClient:
+    """Calls other services, as this service or for a user.
+
+    Create one at startup and share it; it is safe to use from several
+    threads.
+
+    :param slug: this service's slug.
+    :param gateway_url: the gateway's internal address (PLATFORM_GATEWAY_URL).
+    :param credential: the credential this built-in service was deployed
+        with (PLATFORM_SERVICE_CREDENTIAL). It is what gets the instance
+        key accepted. An app has none; its key is accepted when it
+        registers.
+    :param now: clock, in seconds since the epoch. For tests.
+    """
+
+    def __init__(
+        self,
+        *,
+        slug: str,
+        gateway_url: str,
+        credential: str | None = None,
+        now: Callable[[], float] | None = None,
+    ) -> None:
+        if not isinstance(slug, str) or not _SLUG.fullmatch(slug):
+            raise _invalid(f"slug {slug!r} is not a slug")
+        if not isinstance(gateway_url, str) or not re.match(r"https?://", gateway_url):
+            raise _invalid("gateway_url must be an http or https URL")
+        self._slug = slug
+        self._issuer = f"service:{slug}"
+        self._gateway_url = gateway_url.rstrip("/")
+        self._credential = credential or None
+        self._now = now or time.time
+        self._lock = threading.Lock()
+
+        self._private_key: ec.EllipticCurvePrivateKey | None = None
+        self._public_jwk: dict[str, str] = {}
+        self._kid: str | None = None
+        #: When the gateway stops accepting the key, and when to extend it.
+        self._expires_at = 0.0
+        self._renew_at = 0.0
+        #: Set when a call came back 401: the gateway may no longer know the key.
+        self._doubted = False
+        self._last_forced_at = float("-inf")
+
+    def __repr__(self) -> str:
+        # Never the credential.
+        return f"ServiceClient(slug={self._slug!r}, gateway_url={self._gateway_url!r})"
+
+    # The instance key -----------------------------------------------------
+
+    @property
+    def key_id(self) -> str | None:
+        """The id of this instance's key, once the gateway has accepted one."""
+        return self._kid if self._expires_at else None
+
+    def start(self) -> None:
+        """Make the instance key and have the gateway accept it.
+
+        Optional: the first call does this. Call it at startup to fail
+        early instead.
+        """
+        self._instance_key()
+
+    def _generate(self) -> None:
+        private_key = ec.generate_private_key(ec.SECP256R1())
+        numbers = private_key.public_key().public_numbers()
+        jwk = {
+            "kty": "EC",
+            "crv": "P-256",
+            "x": _b64url(numbers.x.to_bytes(32, "big")),
+            "y": _b64url(numbers.y.to_bytes(32, "big")),
+        }
+        # RFC 7638: the required members, in order, with no spaces.
+        canonical = json.dumps(
+            {name: jwk[name] for name in ("crv", "kty", "x", "y")}, separators=(",", ":")
+        )
+        self._private_key = private_key
+        self._public_jwk = jwk
+        self._kid = _b64url(hashlib.sha256(canonical.encode("ascii")).digest())
+
+    def _sign(self, audience: str, subject: str) -> str:
+        issued_at = int(self._now())
+        return jwt.encode(
+            {
+                "iss": self._issuer,
+                "sub": subject,
+                "aud": audience,
+                "iat": issued_at,
+                "exp": issued_at + _TOKEN_TTL_SECONDS,
+                "jti": str(uuid.uuid4()),
+            },
+            self._private_key,  # type: ignore[arg-type]
+            algorithm="ES256",
+            headers={"kid": self._kid, "typ": "JWT"},
+        )
+
+    def _register(self, authorization: str, with_slug: bool) -> ServiceResponse:
+        """Ask the gateway to accept the key, or to extend it."""
+        body: dict[str, Any] = {"key": {"kid": self._kid, "jwk": self._public_jwk}}
+        if with_slug:
+            body["slug"] = self._slug
+        request = urllib.request.Request(
+            f"{self._gateway_url}{_KEYS_PATH}",
+            data=json.dumps(body).encode("utf-8"),
+            method="POST",
+            headers={
+                "Authorization": authorization,
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            },
+        )
+        try:
+            return _send(request, _REGISTRATION_TIMEOUT_SECONDS)
+        except (urllib.error.URLError, OSError) as err:
+            reason = getattr(err, "reason", err)
+            raise FinchlyError(
+                "gateway_unreachable",
+                "Cannot register this instance's key with the gateway",
+                [str(reason)],
+            ) from None
+
+    def _accept(self, response: ServiceResponse) -> None:
+        body: Any = None
+        try:
+            body = response.json()
+        except ValueError:
+            pass
+        expires_at: float | None = None
+        if response.status == 200 and isinstance(body, dict) and isinstance(body.get("keyExpiresAt"), str):
+            try:
+                expires_at = datetime.fromisoformat(body["keyExpiresAt"].replace("Z", "+00:00")).timestamp()
+            except ValueError:
+                expires_at = None
+        if expires_at is None:
+            reason = body.get("error") if isinstance(body, dict) and isinstance(body.get("error"), str) else None
+            raise FinchlyError(
+                "service_key_rejected",
+                "The gateway did not accept this instance's key",
+                [reason or f"status {response.status}"],
+            )
+        now = self._now()
+        self._expires_at = expires_at
+        # Extend it when two thirds of its life has gone.
+        self._renew_at = now + (expires_at - now) * 2 / 3
+
+    def _with_credential(self) -> None:
+        if not self._credential:
+            raise FinchlyError(
+                "service_key_rejected",
+                "This instance has no key the gateway accepts, and no credential to register one",
+                [
+                    "A built-in service is deployed with PLATFORM_SERVICE_CREDENTIAL.",
+                    "An app's key is accepted when it registers, which this SDK release cannot do yet.",
+                ],
+            )
+        self._accept(self._register(f"Service-Credential {self._credential}", True))
+
+    def _instance_key(self) -> None:
+        """Make sure the instance key exists, is registered and is current."""
+        with self._lock:
+            now = self._now()
+            # Only a credential can re-register, so only then is it worth trying.
+            force = (
+                self._doubted
+                and self._credential is not None
+                and now - self._last_forced_at >= _REREGISTER_COOLDOWN_SECONDS
+            )
+            if self._expires_at and not force and now < self._renew_at:
+                return
+            if self._private_key is None:
+                self._generate()
+            if force:
+                self._last_forced_at = now
+                self._doubted = False
+            elif self._expires_at and now < self._expires_at:
+                # Still accepted: extend it with a token it signs itself.
+                response = self._register(f"Bearer {self._sign(_GATEWAY_AUDIENCE, self._issuer)}", False)
+                if response.status != 401:
+                    self._accept(response)
+                    return
+            # New, expired, or no longer known to the gateway: use the credential.
+            self._with_credential()
+
+    # Calls ----------------------------------------------------------------
+
+    def _subject(self, as_user: str | None) -> str:
+        if as_user is None:
+            return self._issuer
+        if not isinstance(as_user, str) or not _USER_ID.fullmatch(as_user):
+            raise _invalid("as_user must be a user's platform id")
+        return as_user
+
+    @staticmethod
+    def _check_target(target: str) -> None:
+        if not isinstance(target, str) or not _SLUG.fullmatch(target):
+            raise _invalid(f"target {target!r} is not a slug")
+
+    def token(self, target: str, *, as_user: str | None = None) -> str:
+        """A signed token for a call to ``target``. Most code wants ``call``."""
+        self._check_target(target)
+        subject = self._subject(as_user)
+        self._instance_key()
+        return self._sign(target, subject)
+
+    def url(self, target: str, path: str) -> str:
+        """The gateway URL for a path under ``target``. ``path`` starts with "/"."""
+        self._check_target(target)
+        # The path is joined as text. It must not be able to climb out of the target.
+        if (
+            not isinstance(path, str)
+            or not path.startswith("/")
+            or "\\" in path
+            or _DOT_SEGMENT.search(path.split("?", 1)[0])
+        ):
+            raise _invalid('path must start with "/" and contain no "." or ".." segments')
+        return f"{self._gateway_url}/{target}{path}"
+
+    def headers(self, target: str, *, as_user: str | None = None) -> dict[str, str]:
+        """The header to add to a request to ``target``, for use with another HTTP client.
+
+        Build the address with ``url``. A token is for one target and is
+        valid for a minute: get fresh headers for every request.
+        """
+        return {"Authorization": f"Bearer {self.token(target, as_user=as_user)}"}
+
+    def call(
+        self,
+        target: str,
+        path: str,
+        *,
+        method: str = "GET",
+        headers: Mapping[str, str] | None = None,
+        body: bytes | None = None,
+        as_user: str | None = None,
+        timeout: float = 30.0,
+    ) -> ServiceResponse:
+        """Call another service and return its response, whatever the status.
+
+        A 403 means this service's manifest does not declare the target in
+        ``calls``, or the user has no access to it. A redirect is handed
+        back, not followed. Nothing is retried.
+
+        :param as_user: the id of the user this call is made for. The
+            target then sees that user, and this service as the one acting
+            for them. Leave it out to call as the service itself.
+        """
+        url = self.url(target, path)
+        token = self.token(target, as_user=as_user)
+        sent = {name: value for name, value in (headers or {}).items() if name.lower() != "authorization"}
+        # Whatever the caller set, the gateway reads this one.
+        sent["Authorization"] = f"Bearer {token}"
+        request = urllib.request.Request(url, data=body, method=method.upper(), headers=sent)
+        try:
+            response = _send(request, timeout)
+        except (urllib.error.URLError, OSError) as err:
+            reason = getattr(err, "reason", err)
+            raise FinchlyError(
+                "gateway_unreachable", f"Cannot reach {target} through the gateway", [str(reason)]
+            ) from None
+        if response.status == 401:
+            self._doubted = True
+        return response

firetail_finchly-0.0.1.dist-info/METADATA

@@ -0,0 +1,242 @@
+Metadata-Version: 2.5
+Name: firetail_finchly
+Version: 0.0.1
+Summary: Python SDK for the Finchly platform
+Project-URL: Repository, https://github.com/firetail-io/finchly-sdk-py
+Project-URL: Changelog, https://github.com/firetail-io/finchly-sdk-py/blob/main/CHANGELOG.md
+Classifier: Development Status :: 2 - Pre-Alpha
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Requires-Dist: pyjwt[crypto]<3,>=2.8
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == 'dev'
+Requires-Dist: pytest>=8; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# firetail_finchly
+
+Python SDK for the [Finchly](https://github.com/firetail-io/finchly)
+platform. A service or app uses it to register with a Finchly deployment,
+verify who is calling it, and reach the platform's database, object store,
+queue and other services.
+
+Status: early. The package is tested, but only the first four modules
+exist.
+
+The SDK implements the platform API, which is specified in
+`firetail-io/finchly` under `spec/`. This release speaks platform API `v1`
+(draft).
+
+## Install
+
+```
+pip install firetail_finchly
+```
+
+Requires Python 3.10 or later. Depends on PyJWT with its `crypto` extra.
+
+## Use
+
+```python
+from firetail_finchly import load_config, load_manifest
+
+config = load_config()                         # reads PLATFORM_* settings
+manifest = load_manifest(config.manifest_path)
+```
+
+Both raise a `FinchlyError` with a stable `code` and a `problems` tuple that
+names everything wrong, so a misconfigured container fails once with the
+full picture.
+
+### Who is calling
+
+The gateway puts a short-lived signed token in the `x-platform-identity`
+header of every request it proxies. It is the only identity a service
+should accept.
+
+```python
+from firetail_finchly import IdentityError, IdentityVerifier
+
+# Once, at startup. It caches the gateway's issuer and signing keys, and
+# is safe to share between threads.
+identity = IdentityVerifier(slug=manifest["slug"], gateway_url=config.gateway_url)
+
+# Per request.
+try:
+    caller = identity.from_headers(request.headers)
+    caller.subject   # user id, or "service:<slug>"
+    caller.email     # None for a service calling as itself
+    caller.groups    # platform groups
+    caller.roles     # roles for this service: "user", "operator"
+    caller.actor     # "service:<slug>" when a service acts for the user
+except IdentityError as err:
+    ...  # Unauthenticated: respond 401. err.reason is for logs only.
+```
+
+Any other `FinchlyError` from the verifier means the gateway could not be
+reached; respond 503.
+
+A token is rejected unless it is signed with ES256 by a key the gateway
+publishes, names that gateway as issuer and this service as its only
+audience, and has not expired. The rules are in `spec/identity-token.md` in
+`firetail-io/finchly`.
+
+No other header is ever consulted. On a path the manifest declares in
+`publicPaths` there is no token, and the service authenticates the request
+itself.
+
+### Calling another service
+
+Services never address each other directly. A call goes through the
+gateway, signed by this instance's own key.
+
+```python
+from firetail_finchly import ServiceClient
+
+# Once, at startup. Safe to share between threads.
+service = ServiceClient(
+    slug=manifest["slug"],
+    gateway_url=config.gateway_url,
+    credential=config.service_credential,
+)
+service.start()   # optional: fail now, not on the first call
+
+# As the service itself.
+response = service.call(
+    "notification-service",
+    "/api/send",
+    method="POST",
+    headers={"Content-Type": "application/json"},
+    body=b'{"text": "hello"}',
+)
+response.status, response.headers, response.body, response.json()
+
+# For a user: the target sees that user, and this service acting for them.
+service.call("notification-service", "/api/inbox", as_user=caller.subject)
+```
+
+`call` returns the response, whatever its status.
+
+- **403** means this service's manifest does not list the target in
+  `calls`, or the user has no access to the target.
+- **A redirect is handed back, not followed.**
+- **Nothing is retried.** After a 401 the next call registers the key
+  again, in case the gateway no longer knows it.
+
+To use another HTTP client, such as `requests` or `httpx`, take the address
+and the header from the client and send the request yourself. A token is
+for one target and is valid for a minute, so get fresh headers each time:
+
+```python
+requests.post(
+    service.url("notification-service", "/api/send"),
+    headers=service.headers("notification-service"),
+    json={"text": "hello"},
+    allow_redirects=False,
+)
+```
+
+The instance makes an ES256 key pair in memory the first time it is needed.
+The private half never leaves the process. The public half is registered
+with the gateway using the credential the service was deployed with, and
+extended by itself for as long as the instance runs. The rules are in
+`spec/service-token.md` and `spec/registration.md` in `firetail-io/finchly`.
+
+Only a built-in service has a credential. An app's key is accepted when it
+registers, which the `app` module will do; until then an app cannot use
+`service`.
+
+### Settings
+
+| Variable | Required | Meaning |
+|---|---|---|
+| `PLATFORM_GATEWAY_URL` | yes | The gateway's internal address |
+| `PLATFORM_MANIFEST_PATH` | no | Manifest path in the container. Default `/finchly/manifest.json` |
+| `PLATFORM_APP_ADDRESS` | no | Address the gateway should use to reach this service |
+| `PLATFORM_ENROLMENT_TOKEN` | no | Token for self-registration |
+| `PLATFORM_SERVICE_CREDENTIAL` | no | What a built-in service registers its instance key with |
+
+The enrolment token and the service credential are left out of the
+config's `repr`, so logging the config does not leak them.
+
+## Modules
+
+The Python SDK may trail the Node SDK for modules that only Node services
+use.
+
+| Module | What it does | State |
+|---|---|---|
+| `config` | Read and validate the platform settings | Done |
+| `manifest` | Load the manifest and check what the SDK depends on | Done |
+| `identity` | Verify `x-platform-identity` | Done. Directory lookups (`list_users`, `members_of`) and `require_*` helpers are planned |
+| `app` | Register with the platform, serve `/_platform/*`, renew keys, fetch settings | Next |
+| `service` | Call other services through the gateway, as the service or for a user | Done for built-in services. An app's first key waits on `app` |
+| `db` | PostgreSQL: queries, transactions, advisory locks, migrations | Planned |
+| `blobs` | Object storage with conditional writes | Planned |
+| `queue` | Publish, lease, ack, nack | Planned |
+| `secrets` | Secrets and envelope encryption | Planned |
+| `llm` | Model calls through the platform | Planned |
+| `audit`, `usage`, `notify`, `schedule`, `connectors` | Clients for platform services | Planned |
+| `ui` | Shared header, footer and theme | Not planned; Node only |
+
+The manifest check here is not the full schema. The platform runs the full
+check at registration and is the authority.
+
+## Develop
+
+```
+python -m venv .venv && . .venv/bin/activate
+pip install -e ".[dev]"
+python -m pytest
+```
+
+Without a local Python environment, run them in a container:
+
+```
+docker run --rm -v "$PWD":/src:ro python:3.12-slim sh -c \
+  "cp -r /src /w && cd /w && pip install -q -e '.[dev]' && python -m pytest -q"
+```
+
+### Conformance vectors
+
+`tests/conformance/` holds test vectors copied from `firetail-io/finchly`
+(`conformance/vectors/`). Both SDKs must reach the verdict each vector
+states. Do not edit them here: change them in `finchly`, regenerate, and
+copy the file to both SDK repositories. Until `finchly` publishes its
+conformance suite as an image, the copy is made by hand.
+
+## Release
+
+Each package version follows semver, independent of the Node SDK and of the
+platform.
+
+1. Changes land on `main` by pull request. Each one adds a line to
+   `CHANGELOG.md` under "Unreleased".
+2. To release, set the version in `src/firetail_finchly/_version.py`, move
+   the changelog entries under that version, merge, and tag the merge
+   commit `v` plus the version, for example `v1.2.0`.
+3. The `release` workflow checks the tag matches the version, runs the
+   tests, builds the sdist and wheel, and publishes.
+4. A release candidate uses the PEP 440 form, `1.2.0rc1`, tagged
+   `v1.2.0rc1`. pip does not install pre-releases unless asked.
+5. A bad release is yanked on PyPI and followed by a patch release.
+
+Publishing uses PyPI trusted publishing: the workflow proves its identity to
+PyPI with its GitHub Actions token, so no PyPI token is stored in this
+repository.
+
+One-time setup, not yet done:
+
+- On PyPI, add a pending trusted publisher for the project
+  `firetail_finchly`: owner `firetail-io`, repository `finchly-sdk-py`,
+  workflow `release.yml`, environment `pypi`.
+- Create a GitHub environment called `pypi` in this repository, restricted
+  to tags.
+
+Still to add: the conformance suite from `firetail-io/finchly`, run in CI on
+every change, once that suite exists.

firetail_finchly-0.0.1.dist-info/RECORD

@@ -0,0 +1,12 @@
+firetail_finchly/__init__.py,sha256=IheK8HWBcojxM7Bk_zIZIwaRdO2aFphjdJSotlg0FJo,982
+firetail_finchly/_version.py,sha256=sXLh7g3KC4QCFxcZGBTpG2scR7hmmBsMjq6LqRptkRg,22
+firetail_finchly/config.py,sha256=WgaVUdXrGzGIJ-s9z5jdrzAYzSG4gFGtAz3EiKod5Ms,3506
+firetail_finchly/errors.py,sha256=v6r_Ca0qkHmjmHAjq2Bj8BR_0__amEfh3jaivNEEfsI,1471
+firetail_finchly/identity.py,sha256=ojLOhYKCU8b3tUR9W5U2Y3Rl-oxc04qxxQnrwt9NdVw,13135
+firetail_finchly/manifest.py,sha256=JDGUjVVDiwKi9GCgA0FYKKYoF5-5FDEAk2i0bgufoiM,3601
+firetail_finchly/platform_api.py,sha256=4PkNaiMohm2TAh4VAAyZ4GVULht0O40AoewKapo49qE,738
+firetail_finchly/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+firetail_finchly/service.py,sha256=EVqrTTQr8cL_iPSdcNC9jb8lRxesVZaa3PLZcHADtH4,13682
+firetail_finchly-0.0.1.dist-info/METADATA,sha256=hTWqTCeewX06a-gPZUAXSTXbqlp2vh1d9n0hkR6YaWU,9177
+firetail_finchly-0.0.1.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+firetail_finchly-0.0.1.dist-info/RECORD,,

firetail_finchly-0.0.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.33.0
+Root-Is-Purelib: true
+Tag: py3-none-any