decision-cert 0.1.0__py3-none-any.whl

decision_cert/__init__.py

@@ -0,0 +1,50 @@
+"""Verify and apply `decision-certificate.v1` (spec/decision-certificate.v1.md).
+
+A port of the Rust crate in this repository's `rust/`, which is the reference: both must agree on
+every conformance fixture. A certificate describes a measured process; it never promises an outcome.
+
+    from decision_cert import loads, verify
+    v = verify(loads(open("cert.json").read()), keys)   # keys: key id -> base64url public key
+    v.id, v.threshold_for("north"), v.is_expired(now)
+"""
+
+from ._verify import (
+    ABSTAIN_ALL,
+    SPEC,
+    BadKey,
+    BadSignature,
+    CertError,
+    Invalid,
+    UntrustedKey,
+    Verified,
+    canonical,
+    certificate_id,
+    is_expired,
+    key_id,
+    loads,
+    threshold_for,
+    timestamp,
+    verify,
+)
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ABSTAIN_ALL",
+    "SPEC",
+    "BadKey",
+    "BadSignature",
+    "CertError",
+    "Invalid",
+    "UntrustedKey",
+    "Verified",
+    "__version__",
+    "canonical",
+    "certificate_id",
+    "is_expired",
+    "key_id",
+    "loads",
+    "threshold_for",
+    "timestamp",
+    "verify",
+]

decision_cert/__main__.py

@@ -0,0 +1,73 @@
+"""`python -m decision_cert verify <cert.json> --keys <keys.json> [--now <ts>]`
+
+Exit 0: the certificate verifies against the trusted keys and has not expired at `--now` (default:
+the current time); its id is printed on stdout.
+Exit 1: it does not verify, or it has expired; the reason is printed on stderr.
+Exit 2: usage error, an unreadable file, or a keys file that is not a JSON object of strings.
+The Rust `decision-cert verify` behaves the same.
+"""
+
+from __future__ import annotations
+
+import argparse
+import datetime as dt
+import sys
+from collections.abc import Sequence
+from pathlib import Path
+
+from . import CertError, Invalid, loads, timestamp, verify
+
+
+def _usage(msg: str) -> int:
+    print(f"decision-cert: {msg}", file=sys.stderr)
+    return 2
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="decision-cert", description="Verify decision-certificate.v1 certificates")
+    sub = ap.add_subparsers(dest="command", required=True)
+    v = sub.add_parser("verify", help="Verify a certificate against trusted keys and check its expiry.")
+    v.add_argument("cert", type=Path, help="The certificate, a JSON object.")
+    v.add_argument("--keys", type=Path, required=True, help="Trusted keys: key id -> base64url public key.")
+    v.add_argument("--now", help="The time to check expiry at, YYYY-MM-DDTHH:MM:SSZ (default: now).")
+    args = ap.parse_args(argv)  # exits 2 on a usage error
+
+    try:
+        keys_text = args.keys.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as e:
+        return _usage(f"{args.keys}: {e}")
+    try:
+        keys = loads(keys_text)
+    except Invalid as e:
+        return _usage(f"{args.keys}: not a JSON object of key id -> public key: {e}")
+    if not isinstance(keys, dict) or not all(isinstance(k, str) and isinstance(x, str) for k, x in keys.items()):
+        return _usage(f"{args.keys}: not a JSON object of key id -> public key")
+    if args.now is None:
+        now = dt.datetime.now(dt.UTC)
+    else:
+        try:
+            now = timestamp(args.now)
+        except Invalid:
+            return _usage(f"--now {args.now!r} is not YYYY-MM-DDTHH:MM:SSZ")
+    try:
+        text = args.cert.read_text(encoding="utf-8")
+    except (OSError, UnicodeDecodeError) as e:
+        return _usage(f"{args.cert}: {e}")
+
+    try:
+        cert = verify(loads(text), keys)
+    except CertError as e:
+        print(f"{args.cert}: {e}", file=sys.stderr)
+        return 1
+    if cert.is_expired(now):
+        print(
+            f"{args.cert}: certificate {cert.id} has expired (its expires_at is not after the check time)",
+            file=sys.stderr,
+        )
+        return 1
+    print(cert.id)
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

decision_cert/_ed25519.py

@@ -0,0 +1,85 @@
+"""The parts of Ed25519 point handling that `cryptography` does not expose, in pure Python.
+
+The Rust crate verifies with ed25519-dalek's `verify_strict`, which on top of the RFC 8032 equation
+rejects a small-order public key `A` or a small-order `R`, and a non-canonical `S`. OpenSSL (behind
+`cryptography`) checks `S` but not small order, so these checks run here first. Decoding follows
+curve25519-dalek's `CompressedEdwardsY::decompress`, which is what the Rust crate uses: `y` is read
+modulo p and `x = 0` with the sign bit set is accepted. Nothing here is secret, so nothing here needs
+to run in constant time.
+"""
+
+from __future__ import annotations
+
+P = 2**255 - 19
+L = 2**252 + 27742317777372353535851937790883648493
+D = -121665 * pow(121666, P - 2, P) % P
+_SQRT_M1 = pow(2, (P - 1) // 4, P)
+
+Point = tuple[int, int, int, int]  # extended coordinates (X, Y, Z, T), x = X/Z, y = Y/Z, xy = T/Z
+
+
+def decode(b: bytes) -> Point | None:
+    """The point a 32-byte encoding names, or None when it names no curve point."""
+    if len(b) != 32:
+        return None
+    n = int.from_bytes(b, "little")
+    sign = n >> 255
+    y = (n & ((1 << 255) - 1)) % P
+    u = (y * y - 1) % P
+    v = (D * y * y + 1) % P
+    # x = sqrt(u / v), per RFC 8032 §5.1.3 step 3.
+    x = u * pow(v, 3, P) * pow(u * pow(v, 7, P), (P - 5) // 8, P) % P
+    if (v * x * x - u) % P != 0:
+        x = x * _SQRT_M1 % P
+        if (v * x * x - u) % P != 0:
+            return None
+    if (x & 1) != sign:
+        x = (P - x) % P
+    return (x, y, 1, x * y % P)
+
+
+def add(p: Point, q: Point) -> Point:
+    x1, y1, z1, t1 = p
+    x2, y2, z2, t2 = q
+    a = (y1 - x1) * (y2 - x2) % P
+    b = (y1 + x1) * (y2 + x2) % P
+    c = t1 * 2 * D * t2 % P
+    d = z1 * 2 * z2 % P
+    e, f, g, h = b - a, d - c, d + c, b + a
+    return (e * f % P, g * h % P, f * g % P, e * h % P)
+
+
+IDENTITY: Point = (0, 1, 1, 0)
+
+
+def mul(k: int, p: Point) -> Point:
+    out = IDENTITY
+    while k:
+        if k & 1:
+            out = add(out, p)
+        p = add(p, p)
+        k >>= 1
+    return out
+
+
+def is_identity(p: Point) -> bool:
+    x, y, z, _ = p
+    return x % P == 0 and (y - z) % P == 0
+
+
+def is_small_order(p: Point) -> bool:
+    """True when 8·p is the identity: p lies in the torsion subgroup."""
+    for _ in range(3):
+        p = add(p, p)
+    return is_identity(p)
+
+
+def encode(p: Point) -> bytes:
+    x, y, z, _ = p
+    zi = pow(z, P - 2, P)
+    x, y = x * zi % P, y * zi % P
+    return (y | ((x & 1) << 255)).to_bytes(32, "little")
+
+
+_BASE_Y = 4 * pow(5, P - 2, P) % P
+BASE: Point = decode(_BASE_Y.to_bytes(32, "little"))  # type: ignore[assignment]

decision_cert/_verify.py

@@ -0,0 +1,549 @@
+"""A port of the Rust crate's `verify` (rust/src/lib.rs). The Rust crate is the oracle: where the two
+disagree on a certificate, this module is wrong.
+
+The typed read mirrors serde's: every field is required, nullable fields must be present (as null),
+unknown fields are rejected at every level, booleans are never numbers, and integer fields reject
+floats even when integral. `check` then mirrors the crate's `check`, the schema constraints a typed
+read does not enforce.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+import datetime as dt
+import hashlib
+import json
+import math
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+import rfc8785
+from cryptography.exceptions import InvalidSignature
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+from . import _ed25519
+
+SPEC = "decision-certificate.v1"
+#: `abstain_below` that abstains on every case.
+ABSTAIN_ALL = 1.01
+
+_U64_MAX = 2**64 - 1
+_I64 = (-(2**63), 2**63 - 1)
+_SAFE_INT = 2**53 - 1
+
+
+class CertError(Exception):
+    """A certificate that does not verify. The message matches the Rust crate's `CertError`."""
+
+
+class Invalid(CertError):
+    def __init__(self, reason: str) -> None:
+        super().__init__(f"certificate is not a valid {SPEC}: {reason}")
+
+
+class UntrustedKey(CertError):
+    def __init__(self, key_id: str) -> None:
+        super().__init__(f"certificate signed by {key_id}, which is not a trusted key")
+
+
+class BadKey(CertError):
+    def __init__(self, key_id: str) -> None:
+        super().__init__(f"trusted key {key_id} is malformed or does not hash to its id")
+
+
+class BadSignature(CertError):
+    def __init__(self) -> None:
+        super().__init__("certificate signature does not verify")
+
+
+class _TypeError(Exception):
+    """A serde-style typed-read error; becomes `Invalid`."""
+
+
+# ---------- typed read (serde's semantics) ----------
+
+
+def _unexpected(v: Any) -> str:
+    if v is None:
+        return "null"
+    if isinstance(v, bool):
+        return f"boolean `{'true' if v else 'false'}`"
+    if isinstance(v, int):
+        return f"integer `{v}`"
+    if isinstance(v, float):
+        return f"floating point `{v!r}`"
+    if isinstance(v, str):
+        return f"string {json.dumps(v, ensure_ascii=False)}"
+    if isinstance(v, list):
+        return "sequence"
+    if isinstance(v, Mapping):
+        return "map"
+    return type(v).__name__
+
+
+def _bad_type(v: Any, expected: str) -> _TypeError:
+    return _TypeError(f"invalid type: {_unexpected(v)}, expected {expected}")
+
+
+Reader = Callable[[Any], Any]
+
+
+def _string(v: Any) -> str:
+    if not isinstance(v, str):
+        raise _bad_type(v, "a string")
+    return v
+
+
+def _boolean(v: Any) -> bool:
+    if not isinstance(v, bool):
+        raise _bad_type(v, "a boolean")
+    return v
+
+
+def _f64(v: Any) -> float:
+    if isinstance(v, bool) or not isinstance(v, (int, float)):
+        raise _bad_type(v, "f64")
+    try:
+        x = float(v)
+    except OverflowError:
+        raise _TypeError(f"invalid value: {_unexpected(v)}, expected f64") from None
+    if not math.isfinite(x):
+        raise _TypeError(f"invalid value: {_unexpected(v)}, expected a finite f64")
+    return x
+
+
+def _integer(lo: int, hi: int, name: str) -> Reader:
+    def read(v: Any) -> int:
+        if isinstance(v, bool) or not isinstance(v, int):
+            raise _bad_type(v, name)
+        if not lo <= v <= hi:
+            raise _TypeError(f"invalid value: {_unexpected(v)}, expected {name}")
+        return v
+
+    return read
+
+
+_u64 = _integer(0, _U64_MAX, "u64")
+_i64 = _integer(*_I64, "i64")
+
+
+def _nullable(inner: Reader) -> Reader:
+    return lambda v: None if v is None else inner(v)
+
+
+def _seq(inner: Reader) -> Reader:
+    def read(v: Any) -> list[Any]:
+        if not isinstance(v, list):
+            raise _bad_type(v, "a sequence")
+        return [inner(x) for x in v]
+
+    return read
+
+
+def _map_of(inner: Reader) -> Reader:
+    def read(v: Any) -> dict[str, Any]:
+        if not isinstance(v, Mapping):
+            raise _bad_type(v, "a map")
+        return {_string(k): inner(x) for k, x in sorted(v.items())}
+
+    return read
+
+
+def _struct(name: str, fields: dict[str, Reader]) -> Reader:
+    """A `#[serde(deny_unknown_fields)]` struct with no defaults. Keys are read in sorted order (as
+    serde_json's map holds them), and missing fields are reported after the present ones."""
+
+    def read(v: Any) -> dict[str, Any]:
+        if not isinstance(v, Mapping):
+            raise _bad_type(v, f"struct {name}")
+        out: dict[str, Any] = {}
+        for k in sorted(v):
+            if not isinstance(k, str):
+                raise _bad_type(k, "a string")
+            if k not in fields:
+                raise _TypeError(f"unknown field `{k}`, expected one of {', '.join(f'`{f}`' for f in fields)}")
+            out[k] = fields[k](v[k])
+        for f in fields:
+            if f not in out:
+                raise _TypeError(f"missing field `{f}`")
+        return out
+
+    return read
+
+
+_band = _struct("Band", {"level": _f64, "low": _f64, "high": _f64})
+_segment = _struct(
+    "Segment",
+    {
+        "field": _string,
+        "value": _string,
+        "n": _u64,
+        "abstain_below": _f64,
+        "coverage": _f64,
+        "ucb": _nullable(_f64),
+        "realized_band": _nullable(_band),
+        "inherited": _boolean,
+    },
+)
+_certificate = _struct(
+    "Certificate",
+    {
+        "spec": _string,
+        "domain": _string,
+        "decision": _string,
+        "options": _seq(_string),
+        "model_id": _string,
+        "manifest_hash": _nullable(_string),
+        "data_hash": _string,
+        "n_cal": _u64,
+        "n_temperature": _u64,
+        "split": _struct("Split", {"method": _string, "seed": _nullable(_i64)}),
+        "calibration_map": _struct(
+            "CalibrationMap", {"kind": _string, "params": _map_of(_f64), "label_budget": _nullable(_u64)}
+        ),
+        "rule": _struct("Rule", {"cannot_tell_above": _nullable(_f64), "unscored": _string}),
+        "alpha": _f64,
+        "delta": _nullable(_f64),
+        "method": _string,
+        "risk": _string,
+        "n": _u64,
+        "abstain_below": _f64,
+        "coverage": _f64,
+        "ucb": _nullable(_f64),
+        "realized_band": _band,
+        "segments": _seq(_segment),
+        "window": _nullable(_struct("Window", {"start": _string, "end": _string})),
+        "fitted_at": _string,
+        "expires_at": _string,
+        "audit": _struct("Audit", {"mode": _string, "rate": _f64, "n": _u64, "propensity_logged": _boolean}),
+        "issuer": _struct("Issuer", {"tool": _string, "version": _string}),
+        "signer_key_id": _string,
+        "signature": _string,
+    },
+)
+
+
+# ---------- check (the schema constraints a typed read doesn't enforce) ----------
+
+
+def _unit(x: float) -> bool:
+    return 0.0 <= x <= 1.0
+
+
+def _open(x: float) -> bool:
+    return 0.0 < x < 1.0
+
+
+def _threshold(x: float) -> bool:
+    return 0.0 <= x <= ABSTAIN_ALL
+
+
+def _band_ok(b: Mapping[str, float]) -> bool:
+    return _open(b["level"]) and _unit(b["low"]) and _unit(b["high"])
+
+
+def _lower_hex(s: str) -> bool:
+    return all(c in "0123456789abcdef" for c in s)
+
+
+def _sha256_ok(h: str) -> bool:
+    return h.startswith("sha256:") and len(h) == 71 and _lower_hex(h[7:])
+
+
+def _model_id_ok(m: str) -> bool:
+    """`^[^/]+/.+@.+$`, and not ending in `@?`. The pattern's `.` matches no line terminator."""
+    if any(c in "\n\r\u2028\u2029" for c in m):
+        return False
+    backend, slash, rest = m.partition("/")
+    if not slash or not backend:
+        return False
+    at = any(ch == "@" and i + 1 < len(rest) for i, ch in enumerate(rest) if i >= 1)
+    return at and not m.endswith("@?")
+
+
+_B64URL = frozenset("ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_")
+
+
+def _check(c: Mapping[str, Any]) -> None:
+    def bad(m: str) -> Invalid:
+        return Invalid(m)
+
+    if c["spec"] != SPEC:
+        raise bad("spec is not decision-certificate.v1")
+    opts = c["options"]
+    if len(opts) < 2 or not all(o for o in opts) or len(set(opts)) != len(opts):
+        raise bad("options needs at least 2 distinct non-empty ids")
+    if not all((c["domain"], c["decision"], c["calibration_map"]["kind"], c["issuer"]["tool"], c["issuer"]["version"])):
+        raise bad("domain, decision, calibration_map.kind and issuer must be non-empty")
+    method, risk, delta, ucb = c["method"], c["risk"], c["delta"], c["ucb"]
+    if not (
+        (method == "ltt" and risk == "selective_error" and delta is not None and _open(delta))
+        or (method == "crc" and risk == "joint_error" and delta is None and ucb is None)
+    ):
+        raise bad("method, risk, delta and ucb disagree")
+    if not _open(c["alpha"]) or not _threshold(c["abstain_below"]) or not _unit(c["coverage"]):
+        raise bad("alpha, abstain_below or coverage out of range")
+    if (ucb is not None and not _unit(ucb)) or not _band_ok(c["realized_band"]):
+        raise bad("ucb or realized_band out of range")
+    for s in c["segments"]:
+        if (
+            not s["field"]
+            or not _threshold(s["abstain_below"])
+            or not _unit(s["coverage"])
+            or (s["ucb"] is not None and not _unit(s["ucb"]))
+            or (s["realized_band"] is not None and not _band_ok(s["realized_band"]))
+        ):
+            raise bad("a segment is out of range")
+    split = c["split"]
+    if not (
+        (split["method"] == "time" and split["seed"] is None)
+        or (split["method"] == "seeded" and split["seed"] is not None)
+    ):
+        raise bad("split.method and split.seed disagree")
+    rule = c["rule"]
+    if rule["unscored"] != "abstain" or (
+        rule["cannot_tell_above"] is not None and not _unit(rule["cannot_tell_above"])
+    ):
+        raise bad("rule out of range")
+    audit = c["audit"]
+    if audit["mode"] not in ("sample", "full-label") or not 0.0 < audit["rate"] <= 1.0:
+        raise bad("audit out of range")
+    if not _model_id_ok(c["model_id"]):
+        raise bad("model_id must be <backend>/<model>@<version>")
+    if not _sha256_ok(c["data_hash"]) or (c["manifest_hash"] is not None and not _sha256_ok(c["manifest_hash"])):
+        raise bad("data_hash and manifest_hash must be sha256:<64 hex>")
+    kid = c["signer_key_id"]
+    if not (kid.startswith("ed25519:") and len(kid) == 24 and _lower_hex(kid[8:])):
+        raise bad("signer_key_id must be ed25519:<16 hex>")
+    sig = c["signature"]
+    if len(sig) != 86 or not set(sig) <= _B64URL:
+        raise bad("signature must be 86 base64url characters")
+    timestamp(c["fitted_at"])
+    timestamp(c["expires_at"])
+    if c["window"] is not None:
+        timestamp(c["window"]["start"])
+        timestamp(c["window"]["end"])
+
+
+# ---------- timestamps ----------
+
+
+def _days_in_month(year: int, month: int) -> int:
+    if month == 2:
+        return 29 if year % 4 == 0 and (year % 100 != 0 or year % 400 == 0) else 28
+    return 30 if month in (4, 6, 9, 11) else 31
+
+
+def timestamp(s: str) -> dt.datetime:
+    """Parse the spec's timestamp form, `YYYY-MM-DDTHH:MM:SSZ`, exactly as the Rust crate does.
+
+    Like the crate (chrono), a leap second (`:60`) and year 0000 are accepted. Python's datetime can
+    hold neither, so `:60` reads as `:59.999999` and year 0000 as `datetime.min`; both keep
+    `is_expired` correct at microsecond resolution.
+    """
+    digits = "0123456789"
+    shape = len(s) == 20 and all(
+        (ch == "-")
+        if i in (4, 7)
+        else (ch == "T")
+        if i == 10
+        else (ch == ":")
+        if i in (13, 16)
+        else (ch == "Z")
+        if i == 19
+        else (ch in digits)
+        for i, ch in enumerate(s)
+    )
+    if shape:
+        y, mo, d, h, mi, se = (int(s[a:b]) for a, b in ((0, 4), (5, 7), (8, 10), (11, 13), (14, 16), (17, 19)))
+        if 1 <= mo <= 12 and 1 <= d <= _days_in_month(y, mo) and h <= 23 and mi <= 59 and se <= 60:
+            if y == 0:
+                return dt.datetime.min.replace(tzinfo=dt.UTC)
+            if se == 60:
+                return dt.datetime(y, mo, d, h, mi, 59, 999999, tzinfo=dt.UTC)
+            return dt.datetime(y, mo, d, h, mi, se, tzinfo=dt.UTC)
+    raise Invalid(f"timestamp {json.dumps(s, ensure_ascii=False)} is not YYYY-MM-DDTHH:MM:SSZ")
+
+
+# ---------- canonical bytes, ids, keys ----------
+
+
+def _as_serde_number(v: Any) -> Any:
+    """serde_jcs writes every number through f64, so an integer beyond 2^53 loses precision there;
+    rfc8785 refuses it instead. Convert such integers the way the crate does."""
+    if isinstance(v, bool) or v is None or isinstance(v, (str, float)):
+        return v
+    if isinstance(v, int):
+        return float(v) if abs(v) > _SAFE_INT else v
+    if isinstance(v, Mapping):
+        return {k: _as_serde_number(x) for k, x in v.items()}
+    if isinstance(v, (list, tuple)):
+        return [_as_serde_number(x) for x in v]
+    return v
+
+
+def canonical(v: Any) -> bytes:
+    """The RFC 8785 (JCS) bytes of a JSON value, identical to the crate's `canonical`."""
+    try:
+        return rfc8785.dumps(_as_serde_number(v))
+    except Exception as e:  # noqa: BLE001 - rfc8785 raises several unrelated types
+        raise Invalid(f"not canonicalisable: {e}") from None
+
+
+def certificate_id(v: Any) -> str:
+    """`sha256:` + hex SHA-256 of the signed certificate's canonical bytes."""
+    return "sha256:" + hashlib.sha256(canonical(v)).hexdigest()
+
+
+def key_id(raw_public_key: bytes) -> str:
+    """`ed25519:` + the first 16 hex chars of SHA-256 of the raw 32-byte public key."""
+    return "ed25519:" + hashlib.sha256(raw_public_key).hexdigest()[:16]
+
+
+def b64url_decode(s: str) -> bytes | None:
+    """Strict base64url without padding, as the crate's `URL_SAFE_NO_PAD`: no `=`, no characters
+    outside the alphabet, no non-zero trailing bits. None when `s` is not such a string."""
+    if not isinstance(s, str) or not set(s) <= _B64URL or len(s) % 4 == 1:
+        return None
+    try:
+        b = base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+    except (binascii.Error, ValueError):
+        return None
+    return b if b64url_encode(b) == s else None
+
+
+def b64url_encode(b: bytes) -> str:
+    return base64.urlsafe_b64encode(b).rstrip(b"=").decode()
+
+
+def _verify_strict(raw_key: bytes, sig: bytes, msg: bytes) -> bool:
+    """ed25519-dalek's `verify_strict`: canonical S, neither A nor R of small order, then RFC 8032."""
+    if int.from_bytes(sig[32:], "little") >= _ed25519.L:
+        return False
+    a = _ed25519.decode(raw_key)
+    r = _ed25519.decode(sig[:32])
+    if a is None or r is None or _ed25519.is_small_order(a) or _ed25519.is_small_order(r):
+        return False
+    try:
+        Ed25519PublicKey.from_public_bytes(raw_key).verify(sig, msg)
+    except (InvalidSignature, ValueError):
+        return False
+    return True
+
+
+# ---------- verify ----------
+
+
+@dataclass(frozen=True)
+class Verified:
+    """A certificate whose signature verified against a trusted key."""
+
+    #: `sha256:<hex>` of the signed certificate's canonical bytes.
+    id: str
+    #: The certificate as received.
+    cert: Mapping[str, Any]
+    expires_at: dt.datetime
+    _typed: Mapping[str, Any] = field(repr=False, compare=False)
+
+    def threshold_for(self, segment: str | None) -> float:
+        """The threshold for a case in `segment`: a certified segment's own, else the top-level one."""
+        if segment is not None:
+            for s in self._typed["segments"]:
+                if not s["inherited"] and s["value"] == segment:
+                    return float(s["abstain_below"])
+        return float(self._typed["abstain_below"])
+
+    def is_expired(self, now: dt.datetime) -> bool:
+        """True from `expires_at` on. `now` must be timezone-aware."""
+        if now.tzinfo is None or now.utcoffset() is None:
+            raise ValueError("now must be timezone-aware")
+        return now >= self.expires_at
+
+    def temperature(self) -> float | None:
+        """The temperature of a `kind: temperature` calibration map; None for other kinds."""
+        m = self._typed["calibration_map"]
+        if m["kind"] != "temperature":
+            return None
+        t = m["params"].get("temperature")
+        return None if t is None else float(t)
+
+
+def verify(v: Any, keys: Mapping[str, str]) -> Verified:
+    """Verify `v` (a parsed JSON value) against `keys` (key id → base64url raw public key) and read it.
+
+    Raises `Invalid`, `UntrustedKey`, `BadKey` or `BadSignature`, in that order of checking.
+    """
+    if not isinstance(v, Mapping):
+        raise Invalid("not a JSON object")
+    try:
+        typed = _certificate(v)
+    except _TypeError as e:
+        raise Invalid(str(e)) from None
+    _check(typed)
+
+    kid = typed["signer_key_id"]
+    if kid not in keys:
+        raise UntrustedKey(kid)
+    raw = b64url_decode(keys[kid])
+    if raw is None or len(raw) != 32 or _ed25519.decode(raw) is None or key_id(raw) != kid:
+        raise BadKey(kid)
+    sig = b64url_decode(typed["signature"])
+    if sig is None or len(sig) != 64:
+        raise BadSignature()
+    body = {k: x for k, x in v.items() if k != "signature"}
+    if not _verify_strict(raw, sig, canonical(body)):
+        raise BadSignature()
+
+    return Verified(id=certificate_id(v), cert=v, expires_at=timestamp(typed["expires_at"]), _typed=typed)
+
+
+def is_expired(cert: Verified, now: dt.datetime) -> bool:
+    """Module-level form of `Verified.is_expired`."""
+    return cert.is_expired(now)
+
+
+def threshold_for(cert: Verified, segment: str | None) -> float:
+    """Module-level form of `Verified.threshold_for`."""
+    return cert.threshold_for(segment)
+
+
+def _reject_constant(name: str) -> Any:
+    raise Invalid(f"{name} is not a JSON number")
+
+
+def _parse_int(s: str) -> int | float:
+    # serde_json reads `-0` as the float -0.0, so an integer field rejects it.
+    return -0.0 if s == "-0" else int(s)
+
+
+def _parse_float(s: str) -> float:
+    x = float(s)
+    if not math.isfinite(x):
+        raise Invalid(f"number {s} is out of range")
+    return x
+
+
+def _no_surrogates(v: Any) -> None:
+    if isinstance(v, str):
+        if any(0xD800 <= ord(c) <= 0xDFFF for c in v):
+            raise Invalid("string contains a lone surrogate")
+    elif isinstance(v, Mapping):
+        for k, x in v.items():
+            _no_surrogates(k)
+            _no_surrogates(x)
+    elif isinstance(v, list):
+        for x in v:
+            _no_surrogates(x)
+
+
+def loads(text: str | bytes) -> Any:
+    """Parse JSON as the crate's serde_json does: no NaN or Infinity, no out-of-range numbers, no lone
+    surrogates, `-0` read as a float. A duplicate key keeps its last value, as in serde_json."""
+    try:
+        v = json.loads(text, parse_constant=_reject_constant, parse_int=_parse_int, parse_float=_parse_float)
+    except (ValueError, RecursionError) as e:
+        raise Invalid(f"not JSON: {e}") from None
+    _no_surrogates(v)
+    return v

decision_cert-0.1.0.dist-info/METADATA

@@ -0,0 +1,50 @@
+Metadata-Version: 2.5
+Name: decision-cert
+Version: 0.1.0
+Summary: Verify and apply decision-certificate.v1: signed records of how a model's decisions were measured
+Project-URL: Repository, https://github.com/zer07labs/decision-cert
+Project-URL: Specification, https://github.com/zer07labs/decision-cert/blob/main/spec/decision-certificate.v1.md
+Author: zer07 Labs
+License-Expression: Apache-2.0
+License-File: LICENSE
+Keywords: calibration,certificate,ed25519,jcs,verification
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Security :: Cryptography
+Classifier: Typing :: Typed
+Requires-Python: >=3.12
+Requires-Dist: cryptography>=43
+Requires-Dist: rfc8785>=0.1.4
+Description-Content-Type: text/markdown
+
+# decision-cert (Python verifier)
+
+A pure-Python verifier for `decision-certificate.v1`, a port of the Rust crate in
+[`rust/`](https://github.com/zer07labs/decision-cert/tree/main/rust). Dependencies: `rfc8785` and `cryptography`, nothing else. It verifies; it
+does not issue.
+
+```python
+from decision_cert import loads, verify
+
+cert = loads(open("cert.json").read())  # strict JSON, as the Rust crate parses it
+keys = loads(open("trusted-keys.json").read())  # key id -> base64url raw Ed25519 public key
+v = verify(cert, keys)  # raises Invalid, UntrustedKey, BadKey or BadSignature
+v.id, v.threshold_for("north"), v.is_expired(datetime.now(UTC))
+```
+
+The Rust crate is the reference. This package passes the same conformance fixtures
+([`fixtures/`](https://github.com/zer07labs/decision-cert/tree/main/fixtures)); where the two disagree, this package is wrong. A certificate
+describes a measured process and never promises an outcome; see the
+[spec](https://github.com/zer07labs/decision-cert/blob/main/spec/decision-certificate.v1.md).
+
+```bash
+pip install decision-cert
+python -m decision_cert verify cert.json --keys trusted-keys.json   # exit 0 / 1 / 2
+```
+
+Development, from `python/` in the repository:
+
+```bash
+uv sync && uv run pytest && uv run ruff check && uv run mypy
+```

decision_cert-0.1.0.dist-info/RECORD

@@ -0,0 +1,10 @@
+decision_cert/__init__.py,sha256=iDtXDW4gGODvqYiDef3AjPJGO3FBnTLaHWiOvxDp1G8,1068
+decision_cert/__main__.py,sha256=gicGRr3wVU3pEbrZxSY08SnRKxV9rDmyg_CeRpQSA24,2759
+decision_cert/_ed25519.py,sha256=0n3BeyYvY7cFRsn0ph10c3isfj-U5K3YtQTg5dVzcPI,2615
+decision_cert/_verify.py,sha256=aRf7dR3DkaJXu83uJbdOC2UdImhX6cPwFInPi3NnfoI,18882
+decision_cert/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+decision_cert-0.1.0.dist-info/METADATA,sha256=APLFVP8PL81kp9w70zkPPq1M-8SgTfpxVicPSDkas_I,2112
+decision_cert-0.1.0.dist-info/WHEEL,sha256=2iZrJkDIkeDh0k9SikKMqFuRP-ua6mb4Ir1AsER4BEw,87
+decision_cert-0.1.0.dist-info/entry_points.txt,sha256=bTtuSaC8ZKdTI0K9RPfX9ClRn6NONmpfvpRgLiEd2D4,62
+decision_cert-0.1.0.dist-info/licenses/LICENSE,sha256=yVuuHRzgI17MzTVgt3LsHvuX80innw--CmNPDCzO_iw,11358
+decision_cert-0.1.0.dist-info/RECORD,,

decision_cert-0.1.0.dist-info/WHEEL

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

decision_cert-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+decision-cert = decision_cert.__main__:main

decision_cert-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+