zft 0.2.0a1__py3-none-any.whl

traceagent/__init__.py

@@ -0,0 +1,7 @@
+"""zft — contract-first traceability for multiagent work.
+
+Dependency direction (plan §2): spec <- dsl <- codegen <- gates <- (attest,
+negotiate); lineage feeds gates; debug depends on nothing above it.
+"""
+
+__version__ = "0.2.0a1"

traceagent/attest/__init__.py

@@ -0,0 +1 @@
+"""attest: DSSE TraceManifest attestations over the contract store."""

traceagent/attest/dsse.py

@@ -0,0 +1,378 @@
+"""DSSE attestation (plan C-28): TraceManifest predicate binding clause hashes.
+
+Substrate: securesystemslib (in-toto 3.x's underlying DSSE library; in-toto 3.1
+removed its legacy models API). Predicate URI versioned: .../TraceManifest/v1.
+
+Payloads are canonicalized per RFC 8785 (JCS, see attest.jcs) before signing —
+securesystemslib's encode_canonical is the older OLPC Canonical-JSON draft
+(no float support, code-point key ordering), not JCS, so we do not sign over it.
+
+Malformed envelopes raise the typed errors below instead of leaking
+securesystemslib/binascii internals; parse_envelope collects every format
+problem it finds before failing (parser-style error recovery).
+"""
+from __future__ import annotations
+
+import base64
+import binascii
+import copy
+import hashlib
+import json
+import sys
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+import pytest
+from securesystemslib.dsse import Envelope
+from securesystemslib.exceptions import FormatError, VerificationError
+from securesystemslib.signer import CryptoSigner, Key, Signer
+
+from traceagent.attest.errors import (
+    AttestationError,
+    EnvelopeFormatError,
+    KeyValidationError,
+    SignatureVerificationError,
+    SubjectMismatchError,
+)
+from traceagent.attest.jcs import canonicalize
+
+if TYPE_CHECKING:
+    from traceagent.attest.keys import KeyDocument
+
+PREDICATE_TYPE = "https://traceagent.dev/attestations/TraceManifest/v1"
+PAYLOAD_TYPE = "application/vnd.in-toto+json"
+STATEMENT_TYPE = "https://in-toto.io/Statement/v1"
+
+__all__ = [
+    "AttestationError", "EnvelopeFormatError", "KeyValidationError",
+    "SignatureVerificationError", "SubjectMismatchError",
+    "attest_contract", "clause_subjects", "decode_payload", "parse_envelope",
+    "parse_payload", "verify_attestation",
+]
+
+
+def _gate_source_root() -> Path:
+    return Path(__file__).resolve().parent.parent.parent.parent
+
+
+def _gate_source_files() -> dict[str, str]:
+    """Relative-path -> sha256 hex for the gate source files embedded in the manifest."""
+    source_root = _gate_source_root()
+    gate_files = [
+        source_root / "src" / "traceagent" / "gates" / "l1.py",
+        source_root / "src" / "traceagent" / "gates" / "l2.py",
+        source_root / "src" / "traceagent" / "codegen" / "property_gen.py",
+    ]
+    gate_hashes: dict[str, str] = {}
+    for f in gate_files:
+        rel = f.relative_to(source_root)
+        gate_hashes[str(rel)] = hashlib.sha256(f.read_bytes()).hexdigest()
+    return gate_hashes
+
+
+def _check_gate_manifest(payload: dict) -> None:
+    """Fail if the gate manifest's own file hashes are tampered (zft lineage:
+    gate self-verification, unioned 2026-09-12)."""
+    predicate = payload.get("predicate")
+    if not isinstance(predicate, dict):
+        return
+    manifest = predicate.get("gate_manifest")
+    if not isinstance(manifest, dict):
+        return
+    files = manifest.get("files")
+    if not isinstance(files, dict):
+        return
+    for rel, recorded in files.items():
+        actual_path = _gate_source_root() / rel
+        try:
+            actual = hashlib.sha256(actual_path.read_bytes()).hexdigest()
+        except OSError:
+            raise AttestationError(
+                f"gate manifest file {rel!r} missing or unreadable"
+            ) from None
+        if actual != recorded:
+            raise AttestationError(
+                f"gate manifest file {rel!r} hash mismatch: expected {recorded!r}, "
+                f"found {actual!r}")
+
+
+def clause_subjects(root: Path) -> list[dict]:
+    subjects = []
+    for path in sorted((root / ".zft" / "specs").rglob("*.json")):
+        digest = hashlib.sha256(path.read_bytes()).hexdigest()
+        subjects.append({"name": f"clause:{path.name}", "digest": {"sha256": digest}})
+    return subjects
+
+
+def _deterministic_coverage(root: Path) -> str:
+    """covered/due clause count for milestone v0 (bindings vs deferred targets)."""
+    from traceagent.lineage.extract import extract_bindings
+    from traceagent.spec.store import Store, load_contract
+
+    store = Store.load(root)
+    milestone = "v0"
+    try:
+        deferred = load_contract(root).get("meta", {}).get("target_milestone", {})
+    except (FileNotFoundError, json.JSONDecodeError):
+        deferred = {}
+    due = {a for a, _n in store.nodes.items() if deferred.get(a, milestone) <= milestone}
+    bindings = extract_bindings(root)
+    bound = sorted({b["alias"] for b in bindings if b["alias"] in due})
+    return f"{len(bound)}/{len(due)}"
+
+
+def attest_contract(root: Path | str, producer_model: str | None = None,
+                    gate_model: str | None = None, signer: Signer | None = None,
+                    deterministic_coverage: str | None = None) -> dict:
+    """Sign a TraceManifest statement over the current store; returns DSSE envelope dict.
+
+    Payload is RFC 8785-canonicalized before signing. Sign with the passed
+    signer; the caller MUST keep it for verification. deterministic_coverage:
+    if None, computed from bindings vs due clauses.
+    """
+    root = Path(root)
+    signer = signer or CryptoSigner.generate_ed25519()
+    subjects = clause_subjects(root)
+    if not subjects:
+        raise AttestationError(
+            f"no clause specs found under {root / '.zft' / 'specs'} — nothing to attest")
+
+    from traceagent.spec.store import load_contract
+
+    try:
+        contract = load_contract(root)
+        deferred = contract.get("meta", {}).get("target_milestone", {})
+    except (FileNotFoundError, json.JSONDecodeError):
+        deferred = {}
+    if deterministic_coverage is None:
+        deterministic_coverage = _deterministic_coverage(root)
+
+
+    payload = {
+        "_type": STATEMENT_TYPE,
+        "subject": subjects,
+        "predicateType": PREDICATE_TYPE,
+        "predicate": {
+            "coverage": {"clauses_covered": deterministic_coverage or "pending-L2"},
+            "judge_excluded": [],
+            "deferred": sorted(deferred),
+            "models": {"producer": producer_model, "gate": gate_model},
+            "model_dependent": producer_model == gate_model,
+            "gate_manifest": {
+                "files": _gate_source_files(),
+                "python": sys.version.split()[0],
+                "pytest": pytest.__version__,
+            },
+        },
+    }
+    # JCS is the last gate before signing: a payload we cannot canonicalize
+    # (lone surrogate from surrogateescaped argv or escaped contract JSON,
+    # an out-of-double-range integer, ...) must be rejected typed and unsigned.
+    try:
+        payload_bytes = canonicalize(payload)
+    except ValueError as exc:
+        raise AttestationError(
+            f"payload is not RFC 8785 canonicalizable: {exc}") from exc
+    envelope = Envelope(
+        payload=payload_bytes,
+        payload_type=PAYLOAD_TYPE,
+        signatures={},
+    )
+    envelope.sign(signer)
+    return envelope.to_dict()
+
+
+def _envelope_problems(envelope_dict: object) -> list[str]:
+    """Collect ALL structural problems in a would-be DSSE envelope (error recovery)."""
+    if not isinstance(envelope_dict, dict):
+        return [f"envelope must be a JSON object, got {type(envelope_dict).__name__}"]
+    problems: list[str] = []
+    payload = envelope_dict.get("payload")
+    if not isinstance(payload, str) or not payload:
+        problems.append(f"'payload' must be a non-empty base64 string, got {payload!r}")
+    payload_type = envelope_dict.get("payloadType")
+    if not isinstance(payload_type, str) or not payload_type:
+        problems.append(f"'payloadType' must be a non-empty string, got {payload_type!r}")
+    signatures = envelope_dict.get("signatures")
+    # DSSE envelopes carry signatures as an array; securesystemslib's
+    # from_dict iterates it, so the legacy {keyid: sig} mapping shape is
+    # rejected here rather than by a stray TypeError deeper in.
+    if not isinstance(signatures, list) or not signatures:
+        problems.append(f"'signatures' must be a non-empty list, got {signatures!r}")
+        return problems
+    # each entry must at least be shaped for from_dict (a bare null/str/int
+    # entry used to escape as AttributeError from the substrate)
+    for i, entry in enumerate(signatures):
+        if not isinstance(entry, dict) or not isinstance(entry.get("sig"), str):
+            problems.append(
+                f"'signatures[{i}]' must be an object with a string 'sig', got {entry!r}")
+    return problems
+
+
+def _canonical_base64(text: str, what: str) -> None:
+    """Accept only canonical RFC 4648 standard-alphabet base64 (zero pad bits).
+
+    Two malleabilities are closed here: Python's b64decode ignores non-zero
+    pad bits, so 'QR==' decodes like 'QQ==' — a flipped last character yields
+    a byte-different envelope that still verifies; and securesystemslib also
+    decodes the urlsafe alphabet, so re-rendering a field urlsafe would give
+    the same signed content a textually different envelope (G5: envelope
+    equality must be byte equality — matrix CANON-2/3/6).
+    """
+    try:
+        data = base64.b64decode(text.encode("utf-8"), validate=True)
+    except (binascii.Error, ValueError) as exc:  # binascii.Error ⊂ ValueError
+        raise EnvelopeFormatError(
+            f"{what} is not canonical base64: {exc}") from exc
+    if base64.b64encode(data).decode("ascii") != text:
+        raise EnvelopeFormatError(
+            f"{what} is not canonical base64 "
+            f"(non-zero pad bits or altered padding): got {text!r}")
+
+
+def parse_envelope(envelope_dict: dict) -> Envelope:
+    """Validate + parse an envelope dict, reporting every format problem at once."""
+    problems = _envelope_problems(envelope_dict)
+    if problems:
+        raise EnvelopeFormatError("malformed DSSE envelope: " + "; ".join(problems))
+    _canonical_base64(envelope_dict["payload"], "'payload'")
+    for entry in envelope_dict["signatures"]:
+        if isinstance(entry, dict) and isinstance(entry.get("sig"), str):
+            _canonical_base64(entry["sig"], "'signatures[].sig'")
+    try:
+        # from_dict consumes signature entries in place — parse a copy so the
+        # caller's dict (and raw-envelope exports) stay pristine.
+        return Envelope.from_dict(copy.deepcopy(envelope_dict))
+    except (KeyError, TypeError, ValueError, FormatError) as exc:
+        # bad base64 (binascii.Error ⊂ ValueError), missing fields, bad shapes
+        raise EnvelopeFormatError(f"malformed DSSE envelope: {exc}") from exc
+
+
+def decode_payload(envelope: Envelope) -> dict:
+    """UTF-8 + JSON decode a parsed envelope's payload into a dict."""
+    try:
+        text = envelope.payload.decode("utf-8")
+    except (UnicodeDecodeError, AttributeError) as exc:
+        raise EnvelopeFormatError(f"payload is not valid UTF-8: {exc}") from exc
+    try:
+        payload = json.loads(text)
+    except json.JSONDecodeError as exc:
+        raise EnvelopeFormatError(f"payload is not valid JSON: {exc}") from exc
+    if not isinstance(payload, dict):
+        raise EnvelopeFormatError(
+            f"payload must be a JSON object, got {type(payload).__name__}")
+    return payload
+
+
+def _statement_problems(payload: dict) -> list[str]:
+    problems = []
+    if payload.get("_type") != STATEMENT_TYPE:
+        problems.append(f"'_type' must be {STATEMENT_TYPE!r}, got {payload.get('_type')!r}")
+    subject = payload.get("subject")
+    if not isinstance(subject, list) or not subject:
+        problems.append(f"'subject' must be a non-empty list, got {subject!r}")
+    predicate_type = payload.get("predicateType")
+    if not isinstance(predicate_type, str) or not predicate_type:
+        problems.append(f"'predicateType' must be a non-empty string, got {predicate_type!r}")
+    if not isinstance(payload.get("predicate"), dict):
+        problems.append(f"'predicate' must be an object, got {payload.get('predicate')!r}")
+    return problems
+
+
+def parse_payload(envelope_dict: dict) -> dict:
+    """Parse an envelope dict all the way to a validated in-toto Statement dict."""
+    payload = decode_payload(parse_envelope(envelope_dict))
+    if envelope_dict["payloadType"] != PAYLOAD_TYPE:
+        raise EnvelopeFormatError(
+            f"unsupported payloadType {envelope_dict['payloadType']!r} "
+            f"(expected {PAYLOAD_TYPE!r})")
+    problems = _statement_problems(payload)
+    if problems:
+        raise EnvelopeFormatError(
+            "payload is not a valid in-toto statement: " + "; ".join(problems))
+    return payload
+
+
+def _check_subjects(payload: dict, expected_subjects: dict[str, str]) -> None:
+    subjects = payload.get("subject")
+    if not isinstance(subjects, list):
+        raise EnvelopeFormatError(
+            f"payload 'subject' must be a list, got {type(subjects).__name__}")
+    got: dict[str, str] = {}
+    for entry in subjects:
+        try:
+            got[entry["name"]] = entry["digest"]["sha256"]
+        except (TypeError, KeyError, IndexError) as exc:
+            raise EnvelopeFormatError(f"malformed subject entry {entry!r}: {exc}") from exc
+    if got != expected_subjects:
+        changed = sorted(
+            f"{n} (attested {got[n][:12]}…, store {expected_subjects[n][:12]}…)"
+            for n in got.keys() & expected_subjects.keys()
+            if got[n] != expected_subjects[n])
+        missing = sorted(got.keys() - expected_subjects.keys())
+        added = sorted(expected_subjects.keys() - got.keys())
+        detail = "; ".join(
+            part for part in (
+                f"changed: {', '.join(changed)}" if changed else "",
+                f"attested but not in store: {', '.join(missing)}" if missing else "",
+                f"in store but not attested (subject-count mismatch): "
+                f"{', '.join(added)}" if added else "",
+            ) if part)
+        raise SubjectMismatchError(
+            f"subject digests do not match the contract store: {detail}")
+
+
+def verify_attestation(envelope_dict: dict, expected_subjects: dict[str, str] | None = None,
+                       public_key: Key | None = None, *,
+                       key_document: "KeyDocument | None" = None,
+                       now=None, expect_keyid: str | None = None) -> dict:
+    """Verify signature + subject digests; returns the payload dict on success.
+
+    Guards raise EnvelopeFormatError for malformed envelopes (all format
+    problems reported at once), KeyValidationError for missing/unusable keys
+    and key-policy failures, SignatureVerificationError when the signature
+    check fails, and SubjectMismatchError when verified digests differ from
+    expected_subjects.
+
+    Key policy (ATTACK_MATRIX G7): pass key_document (attest.keys.KeyDocument,
+    parsed from the published key file) instead of a bare public_key to have
+    revocation, the validity window, and an optional expect_keyid pin enforced
+    BEFORE any cryptographic work. now overrides the clock for the window
+    check (deterministic tests); naive datetimes are taken as UTC.
+    """
+    if key_document is not None and public_key is not None:
+        raise KeyValidationError(
+            "pass either public_key or key_document, not both — "
+            "which key governs verification must be unambiguous")
+    if key_document is not None:
+        public_key = key_document.check(now=now, expect_keyid=expect_keyid)
+    if public_key is None:
+        raise KeyValidationError(
+            "verify_attestation requires public_key (dev: signer.public_key)")
+    if not isinstance(public_key, Key):
+        raise KeyValidationError(
+            f"public_key must be a securesystemslib Key, got {type(public_key).__name__}")
+    if not getattr(public_key, "keyid", ""):
+        raise KeyValidationError("public_key carries no keyid")
+    envelope = parse_envelope(envelope_dict)
+    if envelope_dict["payloadType"] != PAYLOAD_TYPE:
+        raise EnvelopeFormatError(
+            f"unsupported payloadType {envelope_dict['payloadType']!r} "
+            f"(expected {PAYLOAD_TYPE!r})")
+    try:
+        envelope.verify([public_key], 1)
+    except VerificationError as exc:
+        raise SignatureVerificationError(f"signature verification failed: {exc}") from exc
+    except ValueError as exc:  # threshold / keyid-matching rejections
+        raise KeyValidationError(f"key rejected by DSSE verifier: {exc}") from exc
+    except Exception as exc:  # substrate escapes (review L-3): typed, never raw
+        if isinstance(exc, AttestationError):
+            raise
+        raise SignatureVerificationError(
+            f"signature verification layer failed: "
+            f"{type(exc).__name__}: {exc}") from exc
+    payload = decode_payload(envelope)
+    if expected_subjects is not None:
+        _check_subjects(payload, expected_subjects)
+    _check_gate_manifest(payload)
+    return payload

traceagent/attest/errors.py

@@ -0,0 +1,27 @@
+"""Typed attestation errors, shared by dsse.py (crypto + envelope) and
+keys.py (key documents + policy). Lives in its own module so the two can
+import the taxonomy without a cycle; dsse re-exports everything, so
+``from traceagent.attest.dsse import …`` keeps working.
+"""
+from __future__ import annotations
+
+
+class AttestationError(ValueError):
+    """Base class: malformed attestations, bad keys, failed verification."""
+
+
+class EnvelopeFormatError(AttestationError):
+    """DSSE envelope is structurally malformed (fields, base64, JSON payload)."""
+
+
+class KeyValidationError(AttestationError):
+    """Verification key is missing, unusable, or fails key policy
+    (revoked, outside its validity window, keyid pin mismatch)."""
+
+
+class SignatureVerificationError(AttestationError):
+    """Envelope signature did not verify against the provided key."""
+
+
+class SubjectMismatchError(AttestationError):
+    """Verified payload's subject digests differ from the expected set."""

traceagent/attest/export.py

@@ -0,0 +1,135 @@
+"""Compliance export (plan C-30): derive formats from attested manifests ONLY.
+
+Structured views over the attested envelope in ``.traceagent/attest.json``:
+``export_envelope`` (raw DSSE envelope, validated), ``export_matrix`` (trace
+matrix dict), and ``export_summary`` (human-readable attestation summary).
+Envelopes are structure-validated with the dsse guards; export is refused
+without an attestation file (ATT-EXPORTS-FROM-ATTESTATIONS).
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+from traceagent.attest.dsse import EnvelopeFormatError, parse_envelope, parse_payload
+
+FORMATS = ("dsse", "matrix", "summary")
+
+
+def export_attestation(root: Path | str, fmt: str = "matrix") -> dict | str:
+    """Dispatch an export by format: 'dsse' (raw envelope), 'matrix', 'summary'."""
+    if fmt not in FORMATS:
+        raise ValueError(
+            f"unknown export format {fmt!r} — expected one of: {', '.join(FORMATS)}")
+    if fmt == "dsse":
+        return export_envelope(root)
+    if fmt == "summary":
+        return export_summary(root)
+    return export_matrix(root)
+
+
+def load_envelope(root: Path | str) -> dict:
+    """Load the attested envelope; refuse without one (ATT-EXPORTS-FROM-ATTESTATIONS)."""
+    att_path = Path(root) / ".traceagent" / "attest.json"
+    if not att_path.exists():
+        raise FileNotFoundError(
+            "no attestation found — export refused (ATT-EXPORTS-FROM-ATTESTATIONS)")  # noqa: E501
+    try:
+        envelope = json.loads(att_path.read_text())
+    except json.JSONDecodeError as exc:
+        raise EnvelopeFormatError(
+            f"attestation file {att_path} is not valid JSON: {exc}") from exc
+    if not isinstance(envelope, dict):
+        raise EnvelopeFormatError(
+            f"attestation file {att_path} must contain a JSON object, "
+            f"got {type(envelope).__name__}")
+    return envelope
+
+
+def export_envelope(root: Path | str) -> dict:
+    """Raw DSSE envelope export: the attested envelope exactly as stored, validated."""
+    envelope = load_envelope(root)
+    parse_envelope(envelope)  # refuse to hand on a structurally malformed envelope
+    return envelope
+
+
+def _predicate_problems(predicate: dict) -> list[str]:
+    """Every way ``predicate`` violates the TraceManifest shape, at once."""
+    problems = [f"'predicate.{key}' missing" for key in ("coverage", "model_dependent")
+                if key not in predicate]
+    if "coverage" in predicate and not isinstance(predicate["coverage"], dict):
+        problems.append("'predicate.coverage' must be an object, got "
+                        f"{type(predicate['coverage']).__name__}")
+    if ("model_dependent" in predicate
+            and not isinstance(predicate["model_dependent"], bool)):
+        problems.append("'predicate.model_dependent' must be a bool, got "
+                        f"{type(predicate['model_dependent']).__name__}")
+    return problems
+
+
+def export_matrix(root: Path | str) -> dict:
+    """Build a trace matrix from the attested envelope; refuse without one."""
+    payload = parse_payload(load_envelope(root))
+    predicate = payload["predicate"]
+    problems = _predicate_problems(predicate)
+    if problems:
+        raise EnvelopeFormatError("attested predicate is incomplete: " + "; ".join(problems))
+    clauses = []
+    for entry in payload["subject"]:
+        try:
+            clauses.append(entry["name"])
+        except (TypeError, KeyError) as exc:
+            raise EnvelopeFormatError(f"malformed subject entry {entry!r}: {exc}") from exc
+    return {
+        "predicateType": payload["predicateType"],
+        "clauses": clauses,
+        "coverage": predicate["coverage"],
+        "model_dependent": predicate["model_dependent"],
+    }
+
+
+def export_summary(root: Path | str) -> str:
+    """Human-readable attestation summary derived from the attested envelope."""
+    envelope = load_envelope(root)
+    payload = parse_payload(envelope)
+    predicate = payload["predicate"]
+    problems = _predicate_problems(predicate)
+    if problems:
+        raise EnvelopeFormatError("attested predicate is incomplete: " + "; ".join(problems))
+    coverage = predicate["coverage"]
+    covered = (str(coverage["clauses_covered"])
+               if coverage.get("clauses_covered") is not None
+               else "unknown")
+    models = predicate.get("models") or {}
+    deferred = predicate.get("deferred") or []
+    keyids = _signature_keyids(envelope)
+    lines = [
+        "TraceAgent attestation summary",
+        "==============================",
+        f"statement type: {payload['_type']}",
+        f"predicate type: {payload['predicateType']}",
+        f"payload type:   {envelope.get('payloadType', '?')}",
+        f"signatures:     {len(keyids)}"
+        + (f" (keyid {keyids[0][:16]}…)" if keyids else ""),
+        f"coverage:       clauses covered {covered}",
+        f"models:         producer={models.get('producer') or 'unspecified'} "
+        f"gate={models.get('gate') or 'unspecified'} "
+        f"(model_dependent: {predicate.get('model_dependent', False)})",
+        f"deferred:       {len(deferred)} milestone target(s)",
+        f"subjects:       {len(payload['subject'])} clause digest(s)",
+    ]
+    for entry in payload["subject"]:
+        try:
+            lines.append(f"  - {entry['name']}")
+            lines.append(f"      sha256:{entry['digest']['sha256']}")
+        except (TypeError, KeyError):
+            lines.append(f"  - (malformed subject entry: {entry!r})")
+    return "\n".join(lines)
+
+
+def _signature_keyids(envelope: dict) -> list[str]:
+    signatures = envelope.get("signatures", [])
+    if isinstance(signatures, dict):  # legacy {keyid: sig} form
+        return [str(keyid) for keyid in signatures]
+    return [str(sig.get("keyid", "?")) for sig in signatures if isinstance(sig, dict)]
+

traceagent/attest/jcs.py

@@ -0,0 +1,130 @@
+"""RFC 8785 JSON Canonicalization Scheme (JCS) — the serialization we sign over.
+
+securesystemslib's ``encode_canonical`` implements the older OLPC "Canonical
+JSON" draft, which diverges from RFC 8785: it cannot serialize floats at all,
+and orders object keys by Unicode code point instead of UTF-16 code units.
+DSSE payloads here are canonicalized with this module instead, so any
+independent JCS implementation re-derives byte-identical bytes for a signature.
+
+Implements RFC 8785 §3.2: ECMAScript ``JSON.stringify`` string escaping and
+``Number::toString`` number serialization, object keys sorted by UTF-16 code
+units, output encoded as UTF-8.
+"""
+from __future__ import annotations
+
+import json
+import math
+from typing import Any
+
+# Largest integer exactly representable as an IEEE 754 double (RFC 8785 §3.1:
+# values outside double precision are not interoperable JCS input).
+_MAX_SAFE_INTEGER = (1 << 53) - 1
+
+
+def canonical_text(value: Any) -> str:
+    """Serialize ``value`` to canonical JSON text per RFC 8785."""
+    fragments: list[str] = []
+    _emit(value, fragments)
+    return "".join(fragments)
+
+
+def canonicalize(value: Any) -> bytes:
+    """Serialize ``value`` to canonical JSON bytes per RFC 8785 (UTF-8)."""
+    return canonical_text(value).encode("utf-8")
+
+
+def _emit(value: Any, out: list[str]) -> None:
+    if value is None:
+        out.append("null")
+    elif value is True:
+        out.append("true")
+    elif value is False:
+        out.append("false")
+    elif isinstance(value, int):
+        # bools were handled above; Python ints are unbounded but JCS input
+        # must stay within IEEE 754 double precision.
+        if abs(value) > _MAX_SAFE_INTEGER:
+            raise ValueError(
+                f"JCS: integer {value} exceeds the IEEE 754 double-safe range")
+        out.append(str(value))
+    elif isinstance(value, float):
+        out.append(_number_token(value))
+    elif isinstance(value, str):
+        out.append(_string_token(value))
+    elif isinstance(value, (list, tuple)):
+        out.append("[")
+        for i, item in enumerate(value):
+            if i:
+                out.append(",")
+            _emit(item, out)
+        out.append("]")
+    elif isinstance(value, dict):
+        out.append("{")
+        for i, key in enumerate(_sorted_keys(value)):
+            if i:
+                out.append(",")
+            out.append(_string_token(key))
+            out.append(":")
+            _emit(value[key], out)
+        out.append("}")
+    else:
+        raise ValueError(
+            f"JCS: cannot canonicalize {type(value).__name__} value: {value!r}")
+
+
+def _sorted_keys(obj: dict) -> list[str]:
+    keys = list(obj)
+    for key in keys:
+        if not isinstance(key, str):
+            raise ValueError(
+                f"JCS: object keys must be strings, got {type(key).__name__}")
+    # UTF-16 code-unit order (RFC 8785 §3.2.3): big-endian UTF-16 bytes compare
+    # exactly like the uint16 sequences the spec sorts by.  This differs from
+    # code-point order whenever non-BMP characters meet U+E000..U+FFFF.
+    try:
+        keys.sort(key=lambda k: k.encode("utf-16-be"))
+    except UnicodeEncodeError as exc:
+        raise ValueError(f"JCS: invalid object key: {exc}") from exc
+    return keys
+
+
+def _string_token(text: str) -> str:
+    # RFC 8785 input is parsed JSON; unpaired surrogates cannot round-trip
+    # through UTF-8 and would silently corrupt signatures.
+    try:
+        text.encode("utf-8")
+    except UnicodeEncodeError as exc:
+        raise ValueError(f"JCS: string is not valid Unicode: {exc}") from exc
+    # json.dumps(ensure_ascii=False) escapes exactly like JSON.stringify:
+    # \b \t \n \f \r, \" and \\, other C0 controls as lowercase \u00xx,
+    # everything non-ASCII literal.
+    return json.dumps(text, ensure_ascii=False)
+
+
+def _number_token(value: float) -> str:
+    if math.isnan(value) or math.isinf(value):
+        raise ValueError(f"JCS: cannot canonicalize non-JSON number {value!r}")
+    if value == 0:  # 0.0 and -0.0 both serialize as "0" (RFC 8785 §3.1.1)
+        return "0"
+    sign = "-" if value < 0 else ""
+    # repr() yields the same shortest round-trip digits as ECMAScript's
+    # Number::toString; re-render those digits in ECMA notation, which
+    # switches to exponent form only outside 1e-6 .. 1e21.
+    mantissa, _, exp_text = repr(abs(value)).partition("e")
+    exponent = int(exp_text) if exp_text else 0
+    int_part, _, frac_part = mantissa.partition(".")
+    digits = int_part + frac_part
+    point = len(int_part) + exponent  # digits before the decimal point
+    stripped = digits.lstrip("0")
+    point -= len(digits) - len(stripped)
+    s = stripped.rstrip("0") or "0"
+    k, n = len(s), point
+    if k <= n <= 21:
+        return sign + s + "0" * (n - k)
+    if 0 < n <= 21:
+        return sign + s[:n] + "." + s[n:]
+    if -6 < n <= 0:
+        return sign + "0." + "0" * -n + s
+    e = n - 1
+    return (sign + s[:1] + ("." + s[1:] if k > 1 else "")
+            + "e" + ("+" if e >= 0 else "-") + str(abs(e)))