x403 0.1.0__py3-none-any.whl

x403/__init__.py

@@ -0,0 +1,46 @@
+"""x403: a signed risk decision before money moves."""
+
+from .client import AsyncX403, X403, X403Error, build_query
+from .headers import (
+    AUTH_SCHEME,
+    HEADER_DECISION,
+    HEADER_PRESENTATION,
+    HEADER_REQUIRED,
+    HEADER_RISK_DECISION,
+    authorization_risk,
+    decode,
+    encode,
+    parse_authorization_risk,
+    parse_www_authenticate,
+    www_authenticate,
+)
+from .jcs import canonicalize, hash_object, hash_string
+from .jws import (
+    KeyPair,
+    VerifyResult,
+    decision_hash,
+    generate_key,
+    sign,
+    sign_outcome,
+    sign_query,
+    sign_receipt,
+    thumbprint,
+    verify,
+    verify_decision,
+    verify_receipt,
+)
+from .registry import CODES, GROUPS, NORMATIVE_STATUSES, REGISTRY, check_of, effect_of, entry_of, escalation_of, group_of, status_for
+from .types import VERSION
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "AsyncX403", "X403", "X403Error", "build_query",
+    "AUTH_SCHEME", "HEADER_DECISION", "HEADER_PRESENTATION", "HEADER_REQUIRED", "HEADER_RISK_DECISION",
+    "authorization_risk", "decode", "encode", "parse_authorization_risk", "parse_www_authenticate", "www_authenticate",
+    "canonicalize", "hash_object", "hash_string",
+    "KeyPair", "VerifyResult", "decision_hash", "generate_key", "sign", "sign_outcome", "sign_query", "sign_receipt",
+    "thumbprint", "verify", "verify_decision", "verify_receipt",
+    "CODES", "GROUPS", "NORMATIVE_STATUSES", "REGISTRY", "check_of", "effect_of", "entry_of", "escalation_of", "group_of", "status_for",
+    "VERSION", "__version__",
+]

x403/client.py

@@ -0,0 +1,166 @@
+"""The authority API client: the six calls of spec section 7, sync and async, and
+offline verification against the authority's published keys."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from .headers import decode, encode
+from .jws import VerifyResult, verify_decision
+from .types import VERSION, Authority, Decision, JWKS, Outcome, Receipt, RiskQuery
+
+try:
+    import httpx
+except ImportError:  # pragma: no cover - the client extra is optional
+    httpx = None  # type: ignore[assignment]
+
+
+class X403Error(Exception):
+    def __init__(self, status: int, detail: Any):
+        self.status = status
+        self.detail = detail
+        super().__init__(f"{status}: {detail if isinstance(detail, str) else detail!r}")
+
+
+def build_query(**fields: Any) -> RiskQuery:
+    """Fill scheme and version so a caller passes only what varies."""
+    query: dict[str, Any] = {"scheme": "x403", "version": VERSION}
+    query.update({k: v for k, v in fields.items() if v is not None})
+    return query  # type: ignore[return-value]
+
+
+def _need_httpx() -> None:
+    if httpx is None:
+        raise RuntimeError("install x403[client] for the HTTP client")
+
+
+def _unpack(res: Any) -> Any:
+    try:
+        payload = res.json() if res.content else {}
+    except ValueError:
+        payload = res.text
+    if res.status_code >= 400:
+        detail = payload.get("detail") if isinstance(payload, dict) and "detail" in payload else payload
+        raise X403Error(res.status_code, detail)
+    return payload
+
+
+class _Base:
+    encode = staticmethod(encode)
+    decode = staticmethod(decode)
+
+    def __init__(self, authority: str, api_key: str | None = None, headers: dict[str, str] | None = None, timeout: float = 10.0):
+        self.authority = authority.rstrip("/")
+        self.api_key = api_key
+        self.timeout = timeout
+        self.extra = dict(headers or {})
+        self._jwks: JWKS | None = None
+        self._authority: Authority | None = None
+
+    def _headers(self, body: bool) -> dict[str, str]:
+        out = {"accept": "application/json", **self.extra}
+        if body:
+            out["content-type"] = "application/json"
+        if self.api_key:
+            out["authorization"] = f"Bearer {self.api_key}"
+        return out
+
+    def _jwks_path(self) -> str:
+        url = (self._authority or {}).get("jwks_url") or f"{self.authority}/.well-known/x403/jwks.json"
+        return url[len(self.authority) :] if url.startswith(self.authority) else url
+
+    def reset(self) -> None:
+        """Forget cached keys, e.g. after a verify fails on an unknown kid."""
+        self._jwks = None
+        self._authority = None
+
+
+class X403(_Base):
+    def __init__(self, authority: str, api_key: str | None = None, headers: dict[str, str] | None = None, timeout: float = 10.0, client: Any = None):
+        super().__init__(authority, api_key, headers, timeout)
+        _need_httpx()
+        self._client = client or httpx.Client(timeout=timeout)
+
+    def _call(self, method: str, path: str, body: Any = None) -> Any:
+        url = path if path.startswith("http") else f"{self.authority}{path}"
+        res = self._client.request(method, url, json=body, headers=self._headers(body is not None))
+        return _unpack(res)
+
+    def decide(self, **fields: Any) -> Decision:
+        return self._call("POST", "/x403/decide", build_query(**fields))
+
+    def preflight(self, **fields: Any) -> Decision:
+        """The same question with mode preflight: decide now, pay later citing the id."""
+        return self._call("POST", "/x403/decide", build_query(**{**fields, "mode": "preflight"}))
+
+    def receipt(self, receipt: Receipt) -> Receipt:
+        return self._call("POST", "/x403/receipts", receipt)
+
+    def outcome(self, outcome: Outcome) -> Outcome:
+        return self._call("POST", "/x403/outcomes", outcome)
+
+    def get(self, decision_id: str) -> Decision:
+        return self._call("GET", f"/x403/decisions/{decision_id}")
+
+    def authority_document(self) -> Authority:
+        if self._authority is None:
+            self._authority = self._call("GET", "/.well-known/x403/authority.json")
+        return self._authority  # type: ignore[return-value]
+
+    def jwks(self) -> JWKS:
+        """The authority's keys, fetched once from the address its document names."""
+        if self._jwks is None:
+            try:
+                self.authority_document()
+            except X403Error:
+                pass  # without a document the conventional path still answers
+            self._jwks = self._call("GET", self._jwks_path())
+        return self._jwks  # type: ignore[return-value]
+
+    def verify(self, decision: Decision) -> VerifyResult:
+        """Offline verification of a decision against the cached keys."""
+        return verify_decision(decision, self.jwks())
+
+
+class AsyncX403(_Base):
+    def __init__(self, authority: str, api_key: str | None = None, headers: dict[str, str] | None = None, timeout: float = 10.0, client: Any = None):
+        super().__init__(authority, api_key, headers, timeout)
+        _need_httpx()
+        self._client = client or httpx.AsyncClient(timeout=timeout)
+
+    async def _call(self, method: str, path: str, body: Any = None) -> Any:
+        url = path if path.startswith("http") else f"{self.authority}{path}"
+        res = await self._client.request(method, url, json=body, headers=self._headers(body is not None))
+        return _unpack(res)
+
+    async def decide(self, **fields: Any) -> Decision:
+        return await self._call("POST", "/x403/decide", build_query(**fields))
+
+    async def preflight(self, **fields: Any) -> Decision:
+        return await self._call("POST", "/x403/decide", build_query(**{**fields, "mode": "preflight"}))
+
+    async def receipt(self, receipt: Receipt) -> Receipt:
+        return await self._call("POST", "/x403/receipts", receipt)
+
+    async def outcome(self, outcome: Outcome) -> Outcome:
+        return await self._call("POST", "/x403/outcomes", outcome)
+
+    async def get(self, decision_id: str) -> Decision:
+        return await self._call("GET", f"/x403/decisions/{decision_id}")
+
+    async def authority_document(self) -> Authority:
+        if self._authority is None:
+            self._authority = await self._call("GET", "/.well-known/x403/authority.json")
+        return self._authority  # type: ignore[return-value]
+
+    async def jwks(self) -> JWKS:
+        if self._jwks is None:
+            try:
+                await self.authority_document()
+            except X403Error:
+                pass
+            self._jwks = await self._call("GET", self._jwks_path())
+        return self._jwks  # type: ignore[return-value]
+
+    async def verify(self, decision: Decision) -> VerifyResult:
+        return verify_decision(decision, await self.jwks())

x403/headers.py

@@ -0,0 +1,70 @@
+"""The HTTP binding: X403-* headers carry base64url JSON without padding, and the
+auth-scheme binding carries the same objects under WWW-Authenticate: Risk."""
+
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from .jws import base64url, from_base64url
+
+HEADER_REQUIRED = "X403-Required"
+HEADER_PRESENTATION = "X403-Presentation"
+HEADER_DECISION = "X403-Decision"
+HEADER_RISK_DECISION = "Risk-Decision"
+AUTH_SCHEME = "Risk"
+
+
+def encode(value: Any) -> str:
+    return base64url(json.dumps(value, separators=(",", ":"), ensure_ascii=False))
+
+
+def decode(text: str) -> Any:
+    return json.loads(from_base64url(text).decode("utf-8"))
+
+
+def _quote(value: str) -> str:
+    return '"' + value.replace("\\", "\\\\").replace('"', '\\"') + '"'
+
+
+def www_authenticate(policy: str, realm: str | None = None, request: str | None = None, expires: str | None = None) -> str:
+    """`WWW-Authenticate: Risk policy="...", realm="...", request="...", expires="..."`"""
+    parts = [f"policy={_quote(policy)}"]
+    if realm:
+        parts.append(f"realm={_quote(realm)}")
+    if request:
+        parts.append(f"request={_quote(request)}")
+    if expires:
+        parts.append(f"expires={_quote(expires)}")
+    return f"{AUTH_SCHEME} " + ", ".join(parts)
+
+
+_PARAM = re.compile(r'(\w+)=(?:"((?:[^"\\]|\\.)*)"|([^,\s]+))')
+
+
+def parse_www_authenticate(header: str) -> dict[str, str] | None:
+    m = re.match(r"^\s*Risk\s+(.*)$", header, re.S)
+    if not m:
+        return None
+    out: dict[str, str] = {}
+    for name, quoted, bare in _PARAM.findall(m.group(1)):
+        out[name] = re.sub(r"\\(.)", r"\1", quoted if quoted else bare)
+    return out if "policy" in out else None
+
+
+def authorization_risk(presentation: dict[str, Any]) -> str:
+    """`Authorization: Risk <base64url presentation>`"""
+    return f"{AUTH_SCHEME} {encode(presentation)}"
+
+
+def parse_authorization_risk(header: str | None) -> dict[str, Any] | None:
+    if not header:
+        return None
+    m = re.match(r"^\s*Risk\s+([A-Za-z0-9_-]+)\s*$", header)
+    if not m:
+        return None
+    try:
+        return decode(m.group(1))
+    except (ValueError, UnicodeDecodeError):
+        return None

x403/jcs.py

@@ -0,0 +1,103 @@
+"""RFC 8785 (JSON Canonicalization Scheme). Every hash and every signature in x403 is
+over this form, so two implementations that agree here agree everywhere. Numbers print
+the way ES6 Number.prototype.toString prints them, which is the form the RFC fixes."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import math
+from typing import Any
+
+
+def _es6_number(x: float) -> str:
+    if math.isnan(x) or math.isinf(x):
+        raise ValueError("JCS: non-finite number")
+    if x == 0:
+        return "0"
+    sign = "-" if x < 0 else ""
+    x = abs(x)
+    # repr gives the shortest digits that round-trip, which is the digit string ES6 uses;
+    # only the placement of the point and the exponent form differ, handled below.
+    text = repr(x)
+    if "e" in text:
+        mantissa, exponent = text.split("e")
+        e = int(exponent)
+    else:
+        mantissa, e = text, 0
+    if "." in mantissa:
+        whole, frac = mantissa.split(".")
+    else:
+        whole, frac = mantissa, ""
+    digits = whole + frac
+    point = e - len(frac)  # value = int(digits) * 10 ** point
+    digits = digits.lstrip("0")
+    while digits.endswith("0"):
+        digits = digits[:-1]
+        point += 1
+    k = len(digits)
+    n = point + k  # value = 0.digits * 10 ** n
+    if k <= n <= 21:
+        return sign + digits + "0" * (n - k)
+    if 0 < n <= 21:
+        return sign + digits[:n] + "." + digits[n:]
+    if -6 < n <= 0:
+        return sign + "0." + "0" * (-n) + digits
+    exp = n - 1
+    exp_text = ("+" if exp >= 0 else "-") + str(abs(exp))
+    if k == 1:
+        return sign + digits + "e" + exp_text
+    return sign + digits[0] + "." + digits[1:] + "e" + exp_text
+
+
+def _key(name: str) -> bytes:
+    # The RFC sorts by UTF-16 code units; comparing UTF-16BE bytes is the same order.
+    return name.encode("utf-16-be")
+
+
+def _serialize(value: Any) -> str:
+    if value is None:
+        return "null"
+    if value is True:
+        return "true"
+    if value is False:
+        return "false"
+    if isinstance(value, int):
+        if abs(value) < 2**53:
+            return str(value)
+        return _es6_number(float(value))
+    if isinstance(value, float):
+        return _es6_number(value)
+    if isinstance(value, str):
+        # json.dumps escapes only what the RFC escapes, with lowercase hex.
+        return json.dumps(value, ensure_ascii=False)
+    if isinstance(value, (list, tuple)):
+        return "[" + ",".join(_serialize(v) for v in value) + "]"
+    if isinstance(value, dict):
+        items = sorted(((str(k), v) for k, v in value.items()), key=lambda kv: _key(kv[0]))
+        return "{" + ",".join(json.dumps(k, ensure_ascii=False) + ":" + _serialize(v) for k, v in items) + "}"
+    raise TypeError(f"JCS: cannot serialize {type(value).__name__}")
+
+
+def canonicalize(value: Any) -> str:
+    """The canonical JSON text of a value."""
+    return _serialize(value)
+
+
+def canonical_bytes(value: Any) -> bytes:
+    return canonicalize(value).encode("utf-8")
+
+
+def sha256_hex(data: bytes | str) -> str:
+    raw = data.encode("utf-8") if isinstance(data, str) else data
+    return hashlib.sha256(raw).hexdigest()
+
+
+def hash_object(value: Any) -> str:
+    """`sha256:<hex>` of the canonical form of an object."""
+    return "sha256:" + sha256_hex(canonical_bytes(value))
+
+
+def hash_string(text: str) -> str:
+    """`sha256:<hex>` of a string as given: a JWT, an SD-JWT, any opaque artifact."""
+    return "sha256:" + sha256_hex(text)

x403/jws.py

@@ -0,0 +1,211 @@
+"""Compact JWS with ES256 over the RFC 8785 form. Signatures are raw r||s as JWS wants;
+`cryptography` hands back DER, so the two are converted at the edge and nowhere else."""
+
+from __future__ import annotations
+
+import base64
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from typing import Any
+
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives import hashes
+from cryptography.hazmat.primitives.asymmetric import ec
+from cryptography.hazmat.primitives.asymmetric.utils import decode_dss_signature, encode_dss_signature
+
+from .jcs import canonical_bytes, canonicalize, sha256_hex
+from .types import JWK, JWKS, Decision, Outcome, Receipt, RiskQuery
+
+CURVE = ec.SECP256R1()
+COORD = 32
+
+
+def base64url(data: bytes | str) -> str:
+    raw = data.encode("utf-8") if isinstance(data, str) else data
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
+def from_base64url(text: str) -> bytes:
+    text = text.strip()
+    return base64.urlsafe_b64decode(text + "=" * ((4 - len(text) % 4) % 4))
+
+
+def _int(text: str) -> int:
+    return int.from_bytes(from_base64url(text), "big")
+
+
+def _b64int(n: int) -> str:
+    return base64url(n.to_bytes(COORD, "big"))
+
+
+def thumbprint(jwk: JWK) -> str:
+    """RFC 7638: over exactly these members, in this order."""
+    if jwk.get("kty") != "EC":
+        raise TypeError("thumbprint: only EC keys")
+    text = canonicalize({"crv": jwk["crv"], "kty": jwk["kty"], "x": jwk["x"], "y": jwk["y"]})
+    return base64url(bytes.fromhex(sha256_hex(text)))
+
+
+@dataclass
+class KeyPair:
+    private_jwk: JWK
+    public_jwk: JWK
+    kid: str
+
+
+def generate_key() -> KeyPair:
+    """A fresh P-256 pair as JWKs, with the RFC 7638 thumbprint as kid."""
+    private = ec.generate_private_key(CURVE)
+    return key_pair_from_private(private)
+
+
+def key_pair_from_private(private: ec.EllipticCurvePrivateKey) -> KeyPair:
+    numbers = private.private_numbers()
+    pub = numbers.public_numbers
+    public_jwk: JWK = {"kty": "EC", "crv": "P-256", "x": _b64int(pub.x), "y": _b64int(pub.y)}
+    kid = thumbprint(public_jwk)
+    public_jwk.update({"kid": kid, "alg": "ES256", "use": "sig"})
+    private_jwk: JWK = {**public_jwk, "d": _b64int(numbers.private_value)}
+    private_jwk.pop("use", None)
+    return KeyPair(private_jwk=private_jwk, public_jwk=public_jwk, kid=kid)
+
+
+def private_key(jwk: JWK) -> ec.EllipticCurvePrivateKey:
+    if jwk.get("kty") != "EC" or jwk.get("crv") != "P-256" or "d" not in jwk:
+        raise TypeError("a P-256 private JWK is needed")
+    return ec.derive_private_key(_int(jwk["d"]), CURVE)
+
+
+def public_key(jwk: JWK) -> ec.EllipticCurvePublicKey:
+    if jwk.get("kty") != "EC" or jwk.get("crv") != "P-256":
+        raise TypeError("a P-256 public JWK is needed")
+    return ec.EllipticCurvePublicNumbers(_int(jwk["x"]), _int(jwk["y"]), CURVE).public_key()
+
+
+def sign(payload: Any, private_jwk: JWK, kid: str | None = None, typ: str | None = None) -> str:
+    """Sign the canonical form of `payload` as a compact JWS."""
+    kid = kid or private_jwk.get("kid") or thumbprint(private_jwk)
+    header: dict[str, Any] = {"alg": "ES256", "kid": kid}
+    if typ:
+        header["typ"] = typ
+    signing_input = base64url(canonicalize(header)) + "." + base64url(canonical_bytes(payload))
+    der = private_key(private_jwk).sign(signing_input.encode("ascii"), ec.ECDSA(hashes.SHA256()))
+    r, s = decode_dss_signature(der)
+    return signing_input + "." + base64url(r.to_bytes(COORD, "big") + s.to_bytes(COORD, "big"))
+
+
+@dataclass
+class Verified:
+    header: dict[str, Any]
+    payload: Any
+    payload_text: str
+
+
+def _pick_key(jwks: JWKS | JWK, kid: str | None) -> JWK:
+    if "keys" not in jwks:
+        return jwks  # type: ignore[return-value]
+    keys = [k for k in jwks["keys"] if k.get("kty") == "EC" and k.get("crv") == "P-256"]  # type: ignore[index]
+    match = next((k for k in keys if kid and k.get("kid") == kid), None)
+    if match is None and len(keys) == 1:
+        match = keys[0]
+    if match is None:
+        raise ValueError(f"no key with kid {kid}" if kid else "no single P-256 key to verify with")
+    return match
+
+
+def verify(jws: str, jwks: JWKS | JWK) -> Verified:
+    """Verify a compact JWS against a key set and return its header and payload. Raises when it does not verify."""
+    parts = jws.split(".")
+    if len(parts) != 3:
+        raise ValueError("not a compact JWS")
+    h, p, s = parts
+    header = json.loads(from_base64url(h))
+    if header.get("alg") != "ES256":
+        raise ValueError(f"unsupported alg {header.get('alg')}")
+    raw = from_base64url(s)
+    if len(raw) != 2 * COORD:
+        raise ValueError("signature is not raw r||s")
+    der = encode_dss_signature(int.from_bytes(raw[:COORD], "big"), int.from_bytes(raw[COORD:], "big"))
+    key = public_key(_pick_key(jwks, header.get("kid")))
+    try:
+        key.verify(der, f"{h}.{p}".encode("ascii"), ec.ECDSA(hashes.SHA256()))
+    except InvalidSignature as e:
+        raise ValueError("signature does not verify") from e
+    payload_text = from_base64url(p).decode("utf-8")
+    return Verified(header=header, payload=json.loads(payload_text), payload_text=payload_text)
+
+
+@dataclass
+class VerifyResult:
+    ok: bool
+    reason: str | None = None
+    kid: str | None = None
+
+    def __bool__(self) -> bool:
+        return self.ok
+
+
+def _parse_time(text: str) -> datetime:
+    dt = datetime.fromisoformat(text.replace("Z", "+00:00"))
+    return dt if dt.tzinfo else dt.replace(tzinfo=timezone.utc)
+
+
+def verify_decision(decision: Decision, jwks: JWKS | JWK, now: datetime | None = None) -> VerifyResult:
+    """A decision verifies when decision_sig is a valid ES256 signature by one of the
+    authority's keys over the object without decision_sig, and it has not expired."""
+    sig = decision.get("decision_sig")
+    if not sig:
+        return VerifyResult(False, "unsigned")
+    body = {k: v for k, v in decision.items() if k != "decision_sig"}
+    try:
+        verified = verify(sig, jwks)
+    except ValueError as e:
+        return VerifyResult(False, str(e))
+    kid = verified.header.get("kid")
+    # The signed payload must be this object, byte for byte in canonical form: a decision
+    # whose fields were edited after signing carries a signature over something else.
+    if verified.payload_text != canonicalize(body):
+        return VerifyResult(False, "object differs from signed payload", kid)
+    expires = decision.get("expires_at")
+    if expires and _parse_time(expires) <= (now or datetime.now(timezone.utc)):
+        return VerifyResult(False, "decision_expired", kid)
+    return VerifyResult(True, None, kid)
+
+
+def verify_receipt(receipt: Receipt, jwks: JWKS | JWK) -> VerifyResult:
+    sig = receipt.get("executor_sig")
+    if not sig:
+        return VerifyResult(False, "unsigned")
+    body = {k: v for k, v in receipt.items() if k != "executor_sig"}
+    try:
+        verified = verify(sig, jwks)
+    except ValueError as e:
+        return VerifyResult(False, str(e))
+    if verified.payload_text != canonicalize(body):
+        return VerifyResult(False, "object differs from signed payload", verified.header.get("kid"))
+    return VerifyResult(True, None, verified.header.get("kid"))
+
+
+def sign_receipt(receipt: Receipt, private_jwk: JWK, kid: str | None = None) -> Receipt:
+    """Countersign a receipt: executor_sig is over the receipt without executor_sig."""
+    body = {k: v for k, v in receipt.items() if k != "executor_sig"}
+    kid = kid or (receipt.get("executor") or {}).get("kid")
+    return {**body, "executor_sig": sign(body, private_jwk, kid=kid, typ="x403-receipt+jws")}  # type: ignore[return-value]
+
+
+def sign_outcome(outcome: Outcome, private_jwk: JWK, kid: str | None = None) -> Outcome:
+    body = {k: v for k, v in outcome.items() if k != "sig"}
+    kid = kid or (outcome.get("reporter") or {}).get("kid")
+    return {**body, "sig": sign(body, private_jwk, kid=kid, typ="x403-outcome+jws")}  # type: ignore[return-value]
+
+
+def sign_query(query: RiskQuery, private_jwk: JWK, kid: str | None = None) -> RiskQuery:
+    body = {k: v for k, v in query.items() if k != "requester_sig"}
+    kid = kid or (query.get("requester") or {}).get("kid")
+    return {**body, "requester_sig": sign(body, private_jwk, kid=kid, typ="x403-query+jws")}  # type: ignore[return-value]
+
+
+def decision_hash(decision: Decision) -> str:
+    """The hash a receipt must carry: the decision as signed, decision_sig included."""
+    return "sha256:" + sha256_hex(canonical_bytes(decision))