|
|
|
@@ -0,0 +1,336 @@
|
|
|
|
|
"""Ed25519 request-bound machine tokens.
|
|
|
|
|
|
|
|
|
|
This module never accepts browser cookies, GoAdmin JWTs, query tokens, or
|
|
|
|
|
shared secrets. HTTP adapters must obtain the compact token exclusively from
|
|
|
|
|
the Authorization bearer header and pass the request body unchanged.
|
|
|
|
|
"""
|
|
|
|
|
|
|
|
|
|
from __future__ import annotations
|
|
|
|
|
|
|
|
|
|
import base64
|
|
|
|
|
import hashlib
|
|
|
|
|
import json
|
|
|
|
|
import posixpath
|
|
|
|
|
import re
|
|
|
|
|
import secrets
|
|
|
|
|
import threading
|
|
|
|
|
import time
|
|
|
|
|
from dataclasses import dataclass
|
|
|
|
|
from pathlib import Path
|
|
|
|
|
from typing import Callable, Iterable, Protocol
|
|
|
|
|
from urllib.parse import urlsplit
|
|
|
|
|
|
|
|
|
|
from cryptography.exceptions import InvalidSignature
|
|
|
|
|
from cryptography.hazmat.primitives import serialization
|
|
|
|
|
from cryptography.hazmat.primitives.asymmetric.ed25519 import (
|
|
|
|
|
Ed25519PrivateKey,
|
|
|
|
|
Ed25519PublicKey,
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
VERSION = "yovision.machine-identity/v1"
|
|
|
|
|
TOKEN_TYPE = "YOVISION-MACHINE+JWT"
|
|
|
|
|
MAX_LIFETIME_SECONDS = 300
|
|
|
|
|
ALLOWED_SKEW_SECONDS = 30
|
|
|
|
|
MAX_KEY_OVERLAP_SECONDS = 24 * 60 * 60
|
|
|
|
|
_METHODS = frozenset({"GET", "POST", "PUT", "PATCH", "DELETE"})
|
|
|
|
|
_AUDIENCES = frozenset({"yovision-sense", "yovision-brain", "yovision-bell"})
|
|
|
|
|
_SCOPES = frozenset({"source-config:write", "runtime-status:write", "events:ingest", "evidence:read"})
|
|
|
|
|
_PRINCIPAL = re.compile(r"^yv:(sense|brain|bell):[a-z0-9][a-z0-9.-]{0,62}$")
|
|
|
|
|
_KEY_ID = re.compile(r"^[A-Za-z0-9._-]{8,64}$")
|
|
|
|
|
_TOKEN_ID = re.compile(r"^[A-Za-z0-9_-]{22,64}$")
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
class MachineIdentityError(ValueError):
|
|
|
|
|
"""A stable, non-secret authentication failure."""
|
|
|
|
|
|
|
|
|
|
def __init__(self, code: str) -> None:
|
|
|
|
|
super().__init__(code)
|
|
|
|
|
self.code = code
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
def bearer_token(authorization: str) -> str:
|
|
|
|
|
"""Extract only an Authorization bearer token; there is no cookie/query fallback."""
|
|
|
|
|
parts = authorization.split(" ")
|
|
|
|
|
if len(parts) != 2 or parts[0].lower() != "bearer" or not parts[1] or any(character in parts[1] for character in " \t\r\n,"):
|
|
|
|
|
raise MachineIdentityError("machine_token_missing")
|
|
|
|
|
return parts[1]
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
|
|
|
class Claims:
|
|
|
|
|
ver: str
|
|
|
|
|
iss: str
|
|
|
|
|
sub: str
|
|
|
|
|
aud: str
|
|
|
|
|
scope: tuple[str, ...]
|
|
|
|
|
iat: int
|
|
|
|
|
nbf: int
|
|
|
|
|
exp: int
|
|
|
|
|
jti: str
|
|
|
|
|
htm: str
|
|
|
|
|
htu: str
|
|
|
|
|
body_sha256: str
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
@dataclass(frozen=True)
|
|
|
|
|
class KeyRecord:
|
|
|
|
|
principal: str
|
|
|
|
|
key_id: str
|
|
|
|
|
public_key: Ed25519PublicKey
|
|
|
|
|
audience: str
|
|
|
|
|
scopes: frozenset[str]
|
|
|
|
|
enabled: bool = True
|
|
|
|
|
revoked: bool = False
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
class Registry:
|
|
|
|
|
def __init__(self, records: Iterable[KeyRecord]) -> None:
|
|
|
|
|
self._lock = threading.RLock()
|
|
|
|
|
self._records: dict[str, KeyRecord] = {}
|
|
|
|
|
for record in records:
|
|
|
|
|
if not _KEY_ID.fullmatch(record.key_id) or not _PRINCIPAL.fullmatch(record.principal) or record.audience not in _AUDIENCES or not _valid_scopes(record.scopes):
|
|
|
|
|
raise ValueError("invalid machine key record")
|
|
|
|
|
if record.key_id in self._records:
|
|
|
|
|
raise ValueError("duplicate machine key id")
|
|
|
|
|
self._records[record.key_id] = record
|
|
|
|
|
|
|
|
|
|
def lookup(self, key_id: str) -> KeyRecord | None:
|
|
|
|
|
with self._lock:
|
|
|
|
|
return self._records.get(key_id)
|
|
|
|
|
|
|
|
|
|
def revoke(self, key_id: str) -> bool:
|
|
|
|
|
with self._lock:
|
|
|
|
|
record = self._records.get(key_id)
|
|
|
|
|
if record is None:
|
|
|
|
|
return False
|
|
|
|
|
self._records[key_id] = KeyRecord(
|
|
|
|
|
principal=record.principal,
|
|
|
|
|
key_id=record.key_id,
|
|
|
|
|
public_key=record.public_key,
|
|
|
|
|
audience=record.audience,
|
|
|
|
|
scopes=record.scopes,
|
|
|
|
|
enabled=record.enabled,
|
|
|
|
|
revoked=True,
|
|
|
|
|
)
|
|
|
|
|
return True
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
class ReplayStore:
|
|
|
|
|
"""Process-local replay cache for tests or one uninterrupted process."""
|
|
|
|
|
def __init__(self) -> None:
|
|
|
|
|
self._lock = threading.Lock()
|
|
|
|
|
self._used: dict[tuple[str, str], int] = {}
|
|
|
|
|
|
|
|
|
|
def consume(self, principal: str, token_id: str, expires_at: int, now: int) -> bool:
|
|
|
|
|
with self._lock:
|
|
|
|
|
self._used = {key: expiry for key, expiry in self._used.items() if expiry > now}
|
|
|
|
|
key = (principal, token_id)
|
|
|
|
|
if key in self._used:
|
|
|
|
|
return False
|
|
|
|
|
self._used[key] = expires_at
|
|
|
|
|
return True
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
class ReplayCache(Protocol):
|
|
|
|
|
"""Connector implementations provide an atomic durable implementation."""
|
|
|
|
|
|
|
|
|
|
def consume(self, principal: str, token_id: str, expires_at: int, now: int) -> bool: ...
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
def load_private_key(path: str | Path) -> Ed25519PrivateKey:
|
|
|
|
|
if not str(path).strip():
|
|
|
|
|
raise ValueError("machine private key path is required")
|
|
|
|
|
try:
|
|
|
|
|
raw = Path(path).read_bytes()
|
|
|
|
|
key = serialization.load_pem_private_key(raw, password=None)
|
|
|
|
|
except (OSError, ValueError, TypeError) as exc:
|
|
|
|
|
raise ValueError("invalid machine private key file") from exc
|
|
|
|
|
if not isinstance(key, Ed25519PrivateKey):
|
|
|
|
|
raise ValueError("machine private key is not Ed25519")
|
|
|
|
|
return key
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
def load_registry(path: str | Path, expected_audience: str) -> Registry:
|
|
|
|
|
if not str(path).strip() or expected_audience not in _AUDIENCES:
|
|
|
|
|
raise ValueError("machine principal registry path and audience are required")
|
|
|
|
|
try:
|
|
|
|
|
document = json.loads(Path(path).read_text(encoding="utf-8"))
|
|
|
|
|
except (OSError, UnicodeDecodeError, json.JSONDecodeError) as exc:
|
|
|
|
|
raise ValueError("invalid machine principal registry") from exc
|
|
|
|
|
if not isinstance(document, dict) or set(document) != {"version", "audience", "principals"} or document["version"] != "yovision.machine-principal-registry/v1" or document["audience"] != expected_audience or not isinstance(document["principals"], list) or not document["principals"]:
|
|
|
|
|
raise ValueError("invalid machine principal registry")
|
|
|
|
|
records: list[KeyRecord] = []
|
|
|
|
|
try:
|
|
|
|
|
for principal in document["principals"]:
|
|
|
|
|
if not isinstance(principal, dict) or set(principal) != {"principal_id", "enabled", "keys"} or not isinstance(principal["enabled"], bool) or not isinstance(principal["keys"], list) or not principal["keys"]:
|
|
|
|
|
raise ValueError
|
|
|
|
|
for key in principal["keys"]:
|
|
|
|
|
if not isinstance(key, dict) or set(key) != {"kid", "public_key_base64url", "status", "scopes"} or key["status"] not in {"active", "revoked"} or not isinstance(key["scopes"], list):
|
|
|
|
|
raise ValueError
|
|
|
|
|
public_key = Ed25519PublicKey.from_public_bytes(_b64decode(key["public_key_base64url"]))
|
|
|
|
|
records.append(KeyRecord(principal["principal_id"], key["kid"], public_key, expected_audience, frozenset(key["scopes"]), principal["enabled"], key["status"] == "revoked"))
|
|
|
|
|
except (KeyError, TypeError, ValueError):
|
|
|
|
|
raise ValueError("invalid machine principal registry") from None
|
|
|
|
|
return Registry(records)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
class Signer:
|
|
|
|
|
def __init__(
|
|
|
|
|
self,
|
|
|
|
|
principal: str,
|
|
|
|
|
key_id: str,
|
|
|
|
|
private_key: Ed25519PrivateKey,
|
|
|
|
|
*,
|
|
|
|
|
clock: Callable[[], int] | None = None,
|
|
|
|
|
) -> None:
|
|
|
|
|
if not _PRINCIPAL.fullmatch(principal) or not _KEY_ID.fullmatch(key_id) or not isinstance(private_key, Ed25519PrivateKey):
|
|
|
|
|
raise ValueError("incomplete machine signer configuration")
|
|
|
|
|
self._principal = principal
|
|
|
|
|
self._key_id = key_id
|
|
|
|
|
self._private_key = private_key
|
|
|
|
|
self._clock = clock or (lambda: int(time.time()))
|
|
|
|
|
|
|
|
|
|
def mint(self, audience: str, scopes: Iterable[str], method: str, request_path: str, body: bytes) -> str:
|
|
|
|
|
normalized_path = _normalize_path(request_path)
|
|
|
|
|
normalized_method = method.upper()
|
|
|
|
|
scope_values = tuple(scopes)
|
|
|
|
|
if audience not in _AUDIENCES or not _valid_scopes(scope_values) or normalized_method not in _METHODS:
|
|
|
|
|
raise ValueError("invalid machine token request")
|
|
|
|
|
now = int(self._clock())
|
|
|
|
|
header = {"alg": "EdDSA", "typ": TOKEN_TYPE, "kid": self._key_id, "ver": VERSION}
|
|
|
|
|
claims = {
|
|
|
|
|
"ver": VERSION,
|
|
|
|
|
"iss": self._principal,
|
|
|
|
|
"sub": self._principal,
|
|
|
|
|
"aud": audience,
|
|
|
|
|
"scope": list(scope_values),
|
|
|
|
|
"iat": now,
|
|
|
|
|
"nbf": now,
|
|
|
|
|
"exp": now + MAX_LIFETIME_SECONDS,
|
|
|
|
|
"jti": secrets.token_urlsafe(16),
|
|
|
|
|
"htm": normalized_method,
|
|
|
|
|
"htu": normalized_path,
|
|
|
|
|
"body_sha256": hashlib.sha256(body).hexdigest(),
|
|
|
|
|
}
|
|
|
|
|
encoded_header = _encode_json(header)
|
|
|
|
|
encoded_claims = _encode_json(claims)
|
|
|
|
|
signing_input = f"{encoded_header}.{encoded_claims}".encode("ascii")
|
|
|
|
|
signature = self._private_key.sign(signing_input)
|
|
|
|
|
return f"{encoded_header}.{encoded_claims}.{_b64encode(signature)}"
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
class Verifier:
|
|
|
|
|
def __init__(
|
|
|
|
|
self,
|
|
|
|
|
registry: Registry,
|
|
|
|
|
replay_store: ReplayCache,
|
|
|
|
|
*,
|
|
|
|
|
clock: Callable[[], int] | None = None,
|
|
|
|
|
) -> None:
|
|
|
|
|
self._registry = registry
|
|
|
|
|
self._replay_store = replay_store
|
|
|
|
|
self._clock = clock or (lambda: int(time.time()))
|
|
|
|
|
|
|
|
|
|
def verify(
|
|
|
|
|
self,
|
|
|
|
|
token: str,
|
|
|
|
|
audience: str,
|
|
|
|
|
required_scope: str,
|
|
|
|
|
method: str,
|
|
|
|
|
request_path: str,
|
|
|
|
|
body: bytes,
|
|
|
|
|
) -> Claims:
|
|
|
|
|
parts = token.split(".")
|
|
|
|
|
if len(parts) != 3 or "=" in token:
|
|
|
|
|
raise MachineIdentityError("machine_token_invalid")
|
|
|
|
|
header = _decode_object(parts[0], {"alg", "typ", "kid", "ver"})
|
|
|
|
|
if header.get("alg") != "EdDSA" or header.get("typ") != TOKEN_TYPE or header.get("ver") != VERSION or not isinstance(header.get("kid"), str) or not _KEY_ID.fullmatch(header["kid"]):
|
|
|
|
|
raise MachineIdentityError("machine_token_invalid")
|
|
|
|
|
record = self._registry.lookup(header["kid"])
|
|
|
|
|
if record is None:
|
|
|
|
|
raise MachineIdentityError("machine_token_invalid")
|
|
|
|
|
try:
|
|
|
|
|
record.public_key.verify(_b64decode(parts[2]), f"{parts[0]}.{parts[1]}".encode("ascii"))
|
|
|
|
|
except (InvalidSignature, ValueError):
|
|
|
|
|
raise MachineIdentityError("machine_token_invalid") from None
|
|
|
|
|
if not record.enabled or record.revoked:
|
|
|
|
|
raise MachineIdentityError("machine_identity_revoked")
|
|
|
|
|
|
|
|
|
|
raw = _decode_object(parts[1], {"ver", "iss", "sub", "aud", "scope", "iat", "nbf", "exp", "jti", "htm", "htu", "body_sha256"})
|
|
|
|
|
claims = _claims_from_object(raw)
|
|
|
|
|
if claims.iss != record.principal or claims.sub != record.principal:
|
|
|
|
|
raise MachineIdentityError("machine_token_invalid")
|
|
|
|
|
now = int(self._clock())
|
|
|
|
|
if claims.exp - claims.iat <= 0 or claims.exp - claims.iat > MAX_LIFETIME_SECONDS or claims.nbf < claims.iat or claims.nbf > claims.exp or claims.iat > now + ALLOWED_SKEW_SECONDS:
|
|
|
|
|
raise MachineIdentityError("machine_token_invalid")
|
|
|
|
|
if claims.nbf > now + ALLOWED_SKEW_SECONDS or claims.exp < now - ALLOWED_SKEW_SECONDS:
|
|
|
|
|
raise MachineIdentityError("machine_token_expired")
|
|
|
|
|
if claims.aud != audience or record.audience != audience:
|
|
|
|
|
raise MachineIdentityError("machine_audience_denied")
|
|
|
|
|
if required_scope not in claims.scope or required_scope not in record.scopes:
|
|
|
|
|
raise MachineIdentityError("machine_scope_denied")
|
|
|
|
|
if claims.htm != method.upper() or claims.htu != _normalize_path(request_path) or claims.body_sha256 != hashlib.sha256(body).hexdigest():
|
|
|
|
|
raise MachineIdentityError("machine_token_invalid")
|
|
|
|
|
if not self._replay_store.consume(claims.iss, claims.jti, claims.exp + ALLOWED_SKEW_SECONDS, now):
|
|
|
|
|
raise MachineIdentityError("machine_token_replayed")
|
|
|
|
|
return claims
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
def _claims_from_object(value: dict[str, object]) -> Claims:
|
|
|
|
|
try:
|
|
|
|
|
scope = value["scope"]
|
|
|
|
|
if not isinstance(scope, list) or not _valid_scopes(scope):
|
|
|
|
|
raise ValueError
|
|
|
|
|
integer_fields = ("iat", "nbf", "exp")
|
|
|
|
|
if any(not isinstance(value[field], int) or isinstance(value[field], bool) for field in integer_fields):
|
|
|
|
|
raise ValueError
|
|
|
|
|
string_fields = ("ver", "iss", "sub", "aud", "jti", "htm", "htu", "body_sha256")
|
|
|
|
|
if any(not isinstance(value[field], str) for field in string_fields):
|
|
|
|
|
raise ValueError
|
|
|
|
|
claims = Claims(scope=tuple(scope), **{key: value[key] for key in string_fields + integer_fields})
|
|
|
|
|
if claims.ver != VERSION or not _PRINCIPAL.fullmatch(claims.iss) or claims.iss != claims.sub or claims.aud not in _AUDIENCES or not _TOKEN_ID.fullmatch(claims.jti) or claims.htm not in _METHODS or len(claims.body_sha256) != 64:
|
|
|
|
|
raise ValueError
|
|
|
|
|
bytes.fromhex(claims.body_sha256)
|
|
|
|
|
_normalize_path(claims.htu)
|
|
|
|
|
return claims
|
|
|
|
|
except (KeyError, TypeError, ValueError):
|
|
|
|
|
raise MachineIdentityError("machine_token_invalid") from None
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
def _normalize_path(value: str) -> str:
|
|
|
|
|
split = urlsplit(value)
|
|
|
|
|
if not value.startswith("/") or split.scheme or split.netloc or split.query or split.fragment or "\\" in split.path or "//" in split.path or posixpath.normpath(split.path) != split.path:
|
|
|
|
|
raise ValueError("machine request path must be normalized and contain no query or fragment")
|
|
|
|
|
return split.path
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
def _valid_scopes(scopes: Iterable[str]) -> bool:
|
|
|
|
|
values = tuple(scopes)
|
|
|
|
|
return 1 <= len(values) <= 4 and len(set(values)) == len(values) and all(scope in _SCOPES for scope in values)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
def _encode_json(value: dict[str, object]) -> str:
|
|
|
|
|
return _b64encode(json.dumps(value, ensure_ascii=True, separators=(",", ":"), sort_keys=True).encode("utf-8"))
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
def _decode_object(value: str, expected_keys: set[str]) -> dict[str, object]:
|
|
|
|
|
try:
|
|
|
|
|
decoded = json.loads(_b64decode(value).decode("utf-8"))
|
|
|
|
|
except (UnicodeDecodeError, ValueError, json.JSONDecodeError):
|
|
|
|
|
raise MachineIdentityError("machine_token_invalid") from None
|
|
|
|
|
if not isinstance(decoded, dict) or set(decoded) != expected_keys:
|
|
|
|
|
raise MachineIdentityError("machine_token_invalid")
|
|
|
|
|
return decoded
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
def _b64encode(value: bytes) -> str:
|
|
|
|
|
return base64.urlsafe_b64encode(value).rstrip(b"=").decode("ascii")
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
def _b64decode(value: str) -> bytes:
|
|
|
|
|
if not value or "=" in value:
|
|
|
|
|
raise ValueError("invalid base64url")
|
|
|
|
|
decoded = base64.b64decode(value + "=" * (-len(value) % 4), altchars=b"-_", validate=True)
|
|
|
|
|
if _b64encode(decoded) != value:
|
|
|
|
|
raise ValueError("non-canonical base64url")
|
|
|
|
|
return decoded
|