Implement Engine HTTP interfaces for health, enrollment, and tokens

Data/Engine/services/auth/__init__.py

@@ -3,6 +3,8 @@
 from __future__ import annotations
 
 from .device_auth_service import DeviceAuthService, DeviceRecord
+from .dpop import DPoPReplayError, DPoPVerificationError, DPoPValidator
+from .jwt_service import JWTService, load_service as load_jwt_service
 from .token_service import (
     RefreshTokenRecord,
     TokenRefreshError,
@@ -13,6 +15,11 @@ from .token_service import (
 __all__ = [
     "DeviceAuthService",
     "DeviceRecord",
+    "DPoPReplayError",
+    "DPoPVerificationError",
+    "DPoPValidator",
+    "JWTService",
+    "load_jwt_service",
     "RefreshTokenRecord",
     "TokenRefreshError",
     "TokenRefreshErrorCode",

Data/Engine/services/auth/dpop.py

@@ -0,0 +1,105 @@
+"""DPoP proof validation for Engine services."""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from threading import Lock
+from typing import Dict, Optional
+
+import jwt
+
+__all__ = ["DPoPValidator", "DPoPVerificationError", "DPoPReplayError"]
+
+
+_DP0P_MAX_SKEW = 300.0
+
+
+class DPoPVerificationError(Exception):
+    pass
+
+
+class DPoPReplayError(DPoPVerificationError):
+    pass
+
+
+class DPoPValidator:
+    def __init__(self) -> None:
+        self._observed_jti: Dict[str, float] = {}
+        self._lock = Lock()
+
+    def verify(
+        self,
+        method: str,
+        htu: str,
+        proof: str,
+        access_token: Optional[str] = None,
+    ) -> str:
+        if not proof:
+            raise DPoPVerificationError("DPoP proof missing")
+
+        try:
+            header = jwt.get_unverified_header(proof)
+        except Exception as exc:
+            raise DPoPVerificationError("invalid DPoP header") from exc
+
+        jwk = header.get("jwk")
+        alg = header.get("alg")
+        if not jwk or not isinstance(jwk, dict):
+            raise DPoPVerificationError("missing jwk in DPoP header")
+        if alg not in ("EdDSA", "ES256", "ES384", "ES512"):
+            raise DPoPVerificationError(f"unsupported DPoP alg {alg}")
+
+        try:
+            key = jwt.PyJWK(jwk)
+            public_key = key.key
+        except Exception as exc:
+            raise DPoPVerificationError("invalid jwk in DPoP header") from exc
+
+        try:
+            claims = jwt.decode(
+                proof,
+                public_key,
+                algorithms=[alg],
+                options={"require": ["htm", "htu", "jti", "iat"]},
+            )
+        except Exception as exc:
+            raise DPoPVerificationError("invalid DPoP signature") from exc
+
+        htm = claims.get("htm")
+        proof_htu = claims.get("htu")
+        jti = claims.get("jti")
+        iat = claims.get("iat")
+        ath = claims.get("ath")
+
+        if not isinstance(htm, str) or htm.lower() != method.lower():
+            raise DPoPVerificationError("DPoP htm mismatch")
+        if not isinstance(proof_htu, str) or proof_htu != htu:
+            raise DPoPVerificationError("DPoP htu mismatch")
+        if not isinstance(jti, str):
+            raise DPoPVerificationError("DPoP jti missing")
+        if not isinstance(iat, (int, float)):
+            raise DPoPVerificationError("DPoP iat missing")
+
+        now = time.time()
+        if abs(now - float(iat)) > _DP0P_MAX_SKEW:
+            raise DPoPVerificationError("DPoP proof outside allowed skew")
+
+        if ath and access_token:
+            expected_ath = jwt.utils.base64url_encode(
+                hashlib.sha256(access_token.encode("utf-8")).digest()
+            ).decode("ascii")
+            if expected_ath != ath:
+                raise DPoPVerificationError("DPoP ath mismatch")
+
+        with self._lock:
+            expiry = self._observed_jti.get(jti)
+            if expiry and expiry > now:
+                raise DPoPReplayError("DPoP proof replay detected")
+            self._observed_jti[jti] = now + _DP0P_MAX_SKEW
+            stale = [key for key, exp in self._observed_jti.items() if exp <= now]
+            for key in stale:
+                self._observed_jti.pop(key, None)
+
+        thumbprint = jwt.PyJWK(jwk).thumbprint()
+        return thumbprint.decode("ascii")

Data/Engine/services/auth/jwt_service.py

@@ -0,0 +1,124 @@
+"""JWT issuance utilities for the Engine."""
+
+from __future__ import annotations
+
+import hashlib
+import time
+from typing import Any, Dict, Optional
+
+import jwt
+from cryptography.hazmat.primitives import serialization
+from cryptography.hazmat.primitives.asymmetric import ed25519
+
+from Data.Engine.runtime import ensure_runtime_dir, runtime_path
+
+__all__ = ["JWTService", "load_service"]
+
+
+_KEY_DIR = runtime_path("auth_keys")
+_KEY_FILE = _KEY_DIR / "engine-jwt-ed25519.key"
+_LEGACY_KEY_FILE = runtime_path("keys") / "borealis-jwt-ed25519.key"
+
+
+class JWTService:
+    def __init__(self, private_key: ed25519.Ed25519PrivateKey, key_id: str) -> None:
+        self._private_key = private_key
+        self._public_key = private_key.public_key()
+        self._key_id = key_id
+
+    @property
+    def key_id(self) -> str:
+        return self._key_id
+
+    def issue_access_token(
+        self,
+        guid: str,
+        ssl_key_fingerprint: str,
+        token_version: int,
+        expires_in: int = 900,
+        extra_claims: Optional[Dict[str, Any]] = None,
+    ) -> str:
+        now = int(time.time())
+        payload: Dict[str, Any] = {
+            "sub": f"device:{guid}",
+            "guid": guid,
+            "ssl_key_fingerprint": ssl_key_fingerprint,
+            "token_version": int(token_version),
+            "iat": now,
+            "nbf": now,
+            "exp": now + int(expires_in),
+        }
+        if extra_claims:
+            payload.update(extra_claims)
+
+        token = jwt.encode(
+            payload,
+            self._private_key.private_bytes(
+                encoding=serialization.Encoding.PEM,
+                format=serialization.PrivateFormat.PKCS8,
+                encryption_algorithm=serialization.NoEncryption(),
+            ),
+            algorithm="EdDSA",
+            headers={"kid": self._key_id},
+        )
+        return token
+
+    def decode(self, token: str, *, audience: Optional[str] = None) -> Dict[str, Any]:
+        options = {"require": ["exp", "iat", "sub"]}
+        public_pem = self._public_key.public_bytes(
+            encoding=serialization.Encoding.PEM,
+            format=serialization.PublicFormat.SubjectPublicKeyInfo,
+        )
+        return jwt.decode(
+            token,
+            public_pem,
+            algorithms=["EdDSA"],
+            audience=audience,
+            options=options,
+        )
+
+    def public_jwk(self) -> Dict[str, Any]:
+        public_bytes = self._public_key.public_bytes(
+            encoding=serialization.Encoding.Raw,
+            format=serialization.PublicFormat.Raw,
+        )
+        jwk_x = jwt.utils.base64url_encode(public_bytes).decode("ascii")
+        return {"kty": "OKP", "crv": "Ed25519", "kid": self._key_id, "alg": "EdDSA", "use": "sig", "x": jwk_x}
+
+
+def load_service() -> JWTService:
+    private_key = _load_or_create_private_key()
+    public_bytes = private_key.public_key().public_bytes(
+        encoding=serialization.Encoding.DER,
+        format=serialization.PublicFormat.SubjectPublicKeyInfo,
+    )
+    key_id = hashlib.sha256(public_bytes).hexdigest()[:16]
+    return JWTService(private_key, key_id)
+
+
+def _load_or_create_private_key() -> ed25519.Ed25519PrivateKey:
+    ensure_runtime_dir("auth_keys")
+
+    if _KEY_FILE.exists():
+        with _KEY_FILE.open("rb") as fh:
+            return serialization.load_pem_private_key(fh.read(), password=None)
+
+    if _LEGACY_KEY_FILE.exists():
+        with _LEGACY_KEY_FILE.open("rb") as fh:
+            return serialization.load_pem_private_key(fh.read(), password=None)
+
+    private_key = ed25519.Ed25519PrivateKey.generate()
+    pem = private_key.private_bytes(
+        encoding=serialization.Encoding.PEM,
+        format=serialization.PrivateFormat.PKCS8,
+        encryption_algorithm=serialization.NoEncryption(),
+    )
+    _KEY_DIR.mkdir(parents=True, exist_ok=True)
+    with _KEY_FILE.open("wb") as fh:
+        fh.write(pem)
+    try:
+        if hasattr(_KEY_FILE, "chmod"):
+            _KEY_FILE.chmod(0o600)
+    except Exception:
+        pass
+    return private_key