ainra 0.4.0__tar.gz

ainra-0.4.0/PKG-INFO

@@ -0,0 +1,209 @@
+Metadata-Version: 2.4
+Name: ainra
+Version: 0.4.0
+Summary: Independent Python implementation of the AINRA agent-passport verifier (verify-only, offline, fail-closed). The fourth column of the conformance differential.
+Author: AINRA contributors
+License-Expression: Apache-2.0 OR MIT
+Project-URL: Homepage, https://ainra.org
+Project-URL: Live, https://ainra.vercel.app/
+Project-URL: Source, https://github.com/JacobJandon/ainra
+Keywords: ainra,agent-identity,verifier,passport,post-quantum
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Security :: Cryptography
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: cryptography>=44
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+
+<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
+# ainra — Python verifier (independent implementation #4)
+
+A verify-only, offline, fail-closed, zero-telemetry Python implementation of the
+AINRA agent-passport verifier. It is written **independently** from the AINRA
+specification (`docs/AINRA_I_The_Standard.md`, `docs/AINRA_Master_Technical_Specification_v1.md`)
+and the CC0 conformance vectors — **not** transliterated from the Rust core or
+the TypeScript SDK. It joins the conformance differential as a **fourth column**:
+core ↔ sdk ↔ P0 ↔ **py**, agreeing byte-for-byte on every vector's verdict *and*
+reason.
+
+Why a fourth brain? If an independent reimplementation, built to the same
+spec + vector reference, reaches the same verdict on every vector, that is
+independent confirmation the standard is unambiguous and the reference is
+correct. If it disagreed, we would have found something. It agrees on
+**1153 passport + 17 delta + 9 directory** vectors.
+
+## Package name
+
+`ainra` — checked against PyPI on 2026-07-30 (`GET /pypi/ainra/json` → HTTP 404,
+i.e. the name is unregistered and available). It is **not** published to PyPI by
+this work; the name is reserved by intent and used for local installs only.
+
+## Install
+
+```
+pip install -e packages/sdk-py     # editable, from a checkout
+```
+
+Requires Python ≥ 3.10 and `cryptography` ≥ 44 (already present on most systems;
+it ships Ed25519 and ML-DSA-65). SLH-DSA-SHA2-128s, SHA-256, and zlib need no
+extra dependency (see below).
+
+## Quickstart
+
+```python
+import json, base64
+from ainra import Verifier
+
+vec = json.load(open("vectors/v1/valid-0000.json"))
+
+# 1) Build an offline verifier from the trust anchors.
+verifier = Verifier(vec["anchors"])
+
+# 2) Verify a bundle. The caller supplies `now`; there is no I/O.
+verdict = verifier.verify(vec["presentation"], now=1500)
+print("valid :", verdict.valid, "| reason:", verdict.reason)
+print("event :", json.dumps(verdict.event()))
+
+# 3) A revoked lineage fails closed with a named reason.
+rvk = json.load(open("vectors/v1/revoked-0000.json"))
+rv = Verifier(rvk["anchors"]).verify(rvk["presentation"], rvk["presentation"]["now"])
+print("revoked ->", rv.valid, "| reason:", rv.reason)
+
+# 4) The verifier owns the clock: forward-dating past `exp` cannot dodge expiry.
+exp = json.loads(base64.urlsafe_b64decode(vec["presentation"]["claims"] + "=="))["exp"]
+print("at exp ->", verifier.verify(vec["presentation"], exp).reason)
+```
+
+Real output (run from the repo root):
+
+```
+valid : True | reason: None
+event : {"status": "valid", "reason": null, "name": "ainra:registrar-01:acme:invoicing@1.0.0", "number": "did:ainra:registrar-01:acme:invoicing", "tier": "L1", "freshness_age_s": 10}
+revoked -> False | reason: revoked
+at exp -> expired
+```
+
+The verdict event is the M16 shape every AINRA surface emits
+(`docs/PRESENTATION.md`): `status`, `reason`, `name`, `number` (the permanent
+version-less AINRA Number), `tier`, `freshness_age_s`.
+
+## ASGI middleware — gate a route, fail closed
+
+Framework-agnostic (Starlette, FastAPI, Quart, any ASGI app). Every gated request
+must carry a valid passport or it is denied **403 + `x-ainra-reason`**; on allow,
+the response carries the verdict event in `x-ainra-verdict`.
+
+```python
+from ainra import Verifier, ainra_gate
+
+verifier = Verifier.from_directory(directory, root_ed25519, root_slh)  # None if not authentic
+app.add_middleware(ainra_gate(verifier))   # or: AinraGate(app, verifier)
+```
+
+The bundle is read from the `x-ainra-passport` header (base64url of canonical
+JSON, or raw JSON for local testing), falling back to the JSON body field
+`ainra_passport`. Verification never needs the body, so the header form is
+streaming-safe.
+
+## What it verifies
+
+The frozen nine-step verify, first-failure-wins, mapping to the 20 frozen reasons
+(`docs/reasons.json`): AINRA name grammar; canonical JSON (sorted keys, no spaces,
+rejecting floats / non-ASCII keys / integers beyond 2⁵³); the strict base64url
+decode gateway (D-029 — every external decode is a canonical round-trip, fail
+closed); hybrid **Ed25519 + ML-DSA-65** (both signatures or `alg_downgrade`/`sig_invalid`);
+the exact validity window (`nbf` inclusive, `exp` exclusive — no skew, no grace);
+scope-ceiling and delegation narrowing; revocation-status freshness classes
+(F1 ≤ 30 s · F2 ≤ 5 min · F3 ≤ 24 h, fail closed); logged-before-valid RFC 6962
+inclusion to a signed checkpoint (root **SLH-DSA-SHA2-128s** or a scope-limited,
+in-window, unrevoked delegate); the signed status delta / fresh-head classes; and
+the dual-root-signed directory. Fail closed everywhere; `.verify` never raises.
+
+## Cryptography — shared primitives, independent logic (state precisely, D-041)
+
+The verification **logic** is independent; the cryptographic **primitives** are
+shared, audited libraries — reimplementing a signature scheme would be less safe,
+not more independent:
+
+| Primitive | Sizes (confirmed) | Source |
+|---|---|---|
+| Ed25519 | 32 B key / 64 B sig | `cryptography` (pyca, wraps OpenSSL 3.5+) |
+| ML-DSA-65 (FIPS 204) | 1952 B key / 3309 B sig | `cryptography` (pyca / OpenSSL 3.5+) |
+| SLH-DSA-SHA2-128s (FIPS 205) | 32 B key / 7856 B sig | OpenSSL `libcrypto` via `ctypes` (EVP raw-public-key verify) — that primitive only |
+| SHA-256 (RFC 6962 prefixes) | — | Python stdlib `hashlib` |
+
+**The claim, precisely:** *shared cryptographic primitives (pyca `cryptography` /
+OpenSSL 3.5+ for Ed25519 + ML-DSA-65; OpenSSL `libcrypto` via `ctypes` for
+SLH-DSA-SHA2-128s; stdlib for SHA-256), with an independent verification logic —
+the differential exercises the logic, not the primitives.* `cryptography` 49 does
+not yet surface SLH-DSA, so it is reached from the same underlying OpenSSL
+directly; if the OpenSSL SLH-DSA verify path is unavailable, that primitive fails
+**closed** (returns `False`).
+
+## Differential — the fourth column
+
+`make diff` (or `node tools/diff-harness/run.mjs`) runs the Python verifier over
+the whole corpus and asserts it agrees with the Rust core's recorded verdict on
+every vector, including the `alg-downgrade-*`, `noncanon-*`, `boundary-*`,
+`renewal-*` classes, plus delta and directory:
+
+```
+(A) verdict diff  core↔sdk : 1153/1153 agree
+(B) canon 3-way  core↔sdk↔P0 : 10/10 byte-identical
+(C) canon reject core↔sdk : 4/4 both refuse
+(D) delta diff   core↔sdk : 17/17 agree
+(E) directory diff core↔sdk : 9/9 agree
+(F) verdict diff  core↔py : 1153/1153 agree
+(F) delta diff   core↔py : 17/17 agree
+(F) directory diff core↔py : 9/9 agree
+
+DIFF OK: all implementations agree (core ↔ sdk ↔ P0 ↔ py)
+```
+
+## Tests
+
+```
+cd packages/sdk-py && PYTHONPATH=. python3 -m unittest discover -s tests
+```
+
+Covers the whole-corpus agreement (all 20 reasons reachable), the ~5-line
+`Verifier` surface (valid / revoked / verifier-owns-the-clock), the ASGI gate
+(allow on VALID, deny 403 fail-closed on missing/revoked), and the strict
+base64url / canonical-JSON gateways. Zero telemetry, no network.
+
+## License
+
+Apache-2.0 OR MIT (dual). The conformance vectors are CC0 (`vectors/LICENSE`).
+
+## Build it the documented way
+
+```python
+v = Verifier.from_directory(directory, roots["root_ed25519"], roots["root_slh"],
+                            audience="https://api.example", freshness="F2")
+```
+
+`from_directory` authenticates the directory against both ceremony roots and carries the registrar's **status
+key**, its **status URI**, and any **graduated-distrust cutoff** into the verifier — so revocations are
+authenticated (D-020) and a distrusted registrar is refused (D-044).
+
+The raw `Verifier(anchors, …)` constructor exists for callers embedding anchors they already trust. It **cannot**
+authenticate revocations, because anchors supplied that way carry no status key. Use `from_directory` in
+production; the difference is recorded in [`docs/POLICY-PARITY.md`](../../docs/POLICY-PARITY.md).
+
+## Verify a running copy (ADR-019)
+
+Same call; supply **your** audience when you build the verifier:
+
+```python
+v = Verifier.from_directory(directory, roots["root_ed25519"], roots["root_slh"],
+                            audience="https://api.example")   # never taken from the bundle
+v.verify(bundle, now)     # the instance layer is checked automatically when present
+```
+
+The default empty audience is fail-closed — a service that has not said who it is accepts no instance credential.
+
+Minting lives on the operator's side and takes a signing callback, so no key material enters this package:
+`mint_instance_credential`, `prove_instance_possession`.

ainra-0.4.0/README.md

@@ -0,0 +1,189 @@
+<!-- SPDX-License-Identifier: Apache-2.0 OR MIT -->
+# ainra — Python verifier (independent implementation #4)
+
+A verify-only, offline, fail-closed, zero-telemetry Python implementation of the
+AINRA agent-passport verifier. It is written **independently** from the AINRA
+specification (`docs/AINRA_I_The_Standard.md`, `docs/AINRA_Master_Technical_Specification_v1.md`)
+and the CC0 conformance vectors — **not** transliterated from the Rust core or
+the TypeScript SDK. It joins the conformance differential as a **fourth column**:
+core ↔ sdk ↔ P0 ↔ **py**, agreeing byte-for-byte on every vector's verdict *and*
+reason.
+
+Why a fourth brain? If an independent reimplementation, built to the same
+spec + vector reference, reaches the same verdict on every vector, that is
+independent confirmation the standard is unambiguous and the reference is
+correct. If it disagreed, we would have found something. It agrees on
+**1153 passport + 17 delta + 9 directory** vectors.
+
+## Package name
+
+`ainra` — checked against PyPI on 2026-07-30 (`GET /pypi/ainra/json` → HTTP 404,
+i.e. the name is unregistered and available). It is **not** published to PyPI by
+this work; the name is reserved by intent and used for local installs only.
+
+## Install
+
+```
+pip install -e packages/sdk-py     # editable, from a checkout
+```
+
+Requires Python ≥ 3.10 and `cryptography` ≥ 44 (already present on most systems;
+it ships Ed25519 and ML-DSA-65). SLH-DSA-SHA2-128s, SHA-256, and zlib need no
+extra dependency (see below).
+
+## Quickstart
+
+```python
+import json, base64
+from ainra import Verifier
+
+vec = json.load(open("vectors/v1/valid-0000.json"))
+
+# 1) Build an offline verifier from the trust anchors.
+verifier = Verifier(vec["anchors"])
+
+# 2) Verify a bundle. The caller supplies `now`; there is no I/O.
+verdict = verifier.verify(vec["presentation"], now=1500)
+print("valid :", verdict.valid, "| reason:", verdict.reason)
+print("event :", json.dumps(verdict.event()))
+
+# 3) A revoked lineage fails closed with a named reason.
+rvk = json.load(open("vectors/v1/revoked-0000.json"))
+rv = Verifier(rvk["anchors"]).verify(rvk["presentation"], rvk["presentation"]["now"])
+print("revoked ->", rv.valid, "| reason:", rv.reason)
+
+# 4) The verifier owns the clock: forward-dating past `exp` cannot dodge expiry.
+exp = json.loads(base64.urlsafe_b64decode(vec["presentation"]["claims"] + "=="))["exp"]
+print("at exp ->", verifier.verify(vec["presentation"], exp).reason)
+```
+
+Real output (run from the repo root):
+
+```
+valid : True | reason: None
+event : {"status": "valid", "reason": null, "name": "ainra:registrar-01:acme:invoicing@1.0.0", "number": "did:ainra:registrar-01:acme:invoicing", "tier": "L1", "freshness_age_s": 10}
+revoked -> False | reason: revoked
+at exp -> expired
+```
+
+The verdict event is the M16 shape every AINRA surface emits
+(`docs/PRESENTATION.md`): `status`, `reason`, `name`, `number` (the permanent
+version-less AINRA Number), `tier`, `freshness_age_s`.
+
+## ASGI middleware — gate a route, fail closed
+
+Framework-agnostic (Starlette, FastAPI, Quart, any ASGI app). Every gated request
+must carry a valid passport or it is denied **403 + `x-ainra-reason`**; on allow,
+the response carries the verdict event in `x-ainra-verdict`.
+
+```python
+from ainra import Verifier, ainra_gate
+
+verifier = Verifier.from_directory(directory, root_ed25519, root_slh)  # None if not authentic
+app.add_middleware(ainra_gate(verifier))   # or: AinraGate(app, verifier)
+```
+
+The bundle is read from the `x-ainra-passport` header (base64url of canonical
+JSON, or raw JSON for local testing), falling back to the JSON body field
+`ainra_passport`. Verification never needs the body, so the header form is
+streaming-safe.
+
+## What it verifies
+
+The frozen nine-step verify, first-failure-wins, mapping to the 20 frozen reasons
+(`docs/reasons.json`): AINRA name grammar; canonical JSON (sorted keys, no spaces,
+rejecting floats / non-ASCII keys / integers beyond 2⁵³); the strict base64url
+decode gateway (D-029 — every external decode is a canonical round-trip, fail
+closed); hybrid **Ed25519 + ML-DSA-65** (both signatures or `alg_downgrade`/`sig_invalid`);
+the exact validity window (`nbf` inclusive, `exp` exclusive — no skew, no grace);
+scope-ceiling and delegation narrowing; revocation-status freshness classes
+(F1 ≤ 30 s · F2 ≤ 5 min · F3 ≤ 24 h, fail closed); logged-before-valid RFC 6962
+inclusion to a signed checkpoint (root **SLH-DSA-SHA2-128s** or a scope-limited,
+in-window, unrevoked delegate); the signed status delta / fresh-head classes; and
+the dual-root-signed directory. Fail closed everywhere; `.verify` never raises.
+
+## Cryptography — shared primitives, independent logic (state precisely, D-041)
+
+The verification **logic** is independent; the cryptographic **primitives** are
+shared, audited libraries — reimplementing a signature scheme would be less safe,
+not more independent:
+
+| Primitive | Sizes (confirmed) | Source |
+|---|---|---|
+| Ed25519 | 32 B key / 64 B sig | `cryptography` (pyca, wraps OpenSSL 3.5+) |
+| ML-DSA-65 (FIPS 204) | 1952 B key / 3309 B sig | `cryptography` (pyca / OpenSSL 3.5+) |
+| SLH-DSA-SHA2-128s (FIPS 205) | 32 B key / 7856 B sig | OpenSSL `libcrypto` via `ctypes` (EVP raw-public-key verify) — that primitive only |
+| SHA-256 (RFC 6962 prefixes) | — | Python stdlib `hashlib` |
+
+**The claim, precisely:** *shared cryptographic primitives (pyca `cryptography` /
+OpenSSL 3.5+ for Ed25519 + ML-DSA-65; OpenSSL `libcrypto` via `ctypes` for
+SLH-DSA-SHA2-128s; stdlib for SHA-256), with an independent verification logic —
+the differential exercises the logic, not the primitives.* `cryptography` 49 does
+not yet surface SLH-DSA, so it is reached from the same underlying OpenSSL
+directly; if the OpenSSL SLH-DSA verify path is unavailable, that primitive fails
+**closed** (returns `False`).
+
+## Differential — the fourth column
+
+`make diff` (or `node tools/diff-harness/run.mjs`) runs the Python verifier over
+the whole corpus and asserts it agrees with the Rust core's recorded verdict on
+every vector, including the `alg-downgrade-*`, `noncanon-*`, `boundary-*`,
+`renewal-*` classes, plus delta and directory:
+
+```
+(A) verdict diff  core↔sdk : 1153/1153 agree
+(B) canon 3-way  core↔sdk↔P0 : 10/10 byte-identical
+(C) canon reject core↔sdk : 4/4 both refuse
+(D) delta diff   core↔sdk : 17/17 agree
+(E) directory diff core↔sdk : 9/9 agree
+(F) verdict diff  core↔py : 1153/1153 agree
+(F) delta diff   core↔py : 17/17 agree
+(F) directory diff core↔py : 9/9 agree
+
+DIFF OK: all implementations agree (core ↔ sdk ↔ P0 ↔ py)
+```
+
+## Tests
+
+```
+cd packages/sdk-py && PYTHONPATH=. python3 -m unittest discover -s tests
+```
+
+Covers the whole-corpus agreement (all 20 reasons reachable), the ~5-line
+`Verifier` surface (valid / revoked / verifier-owns-the-clock), the ASGI gate
+(allow on VALID, deny 403 fail-closed on missing/revoked), and the strict
+base64url / canonical-JSON gateways. Zero telemetry, no network.
+
+## License
+
+Apache-2.0 OR MIT (dual). The conformance vectors are CC0 (`vectors/LICENSE`).
+
+## Build it the documented way
+
+```python
+v = Verifier.from_directory(directory, roots["root_ed25519"], roots["root_slh"],
+                            audience="https://api.example", freshness="F2")
+```
+
+`from_directory` authenticates the directory against both ceremony roots and carries the registrar's **status
+key**, its **status URI**, and any **graduated-distrust cutoff** into the verifier — so revocations are
+authenticated (D-020) and a distrusted registrar is refused (D-044).
+
+The raw `Verifier(anchors, …)` constructor exists for callers embedding anchors they already trust. It **cannot**
+authenticate revocations, because anchors supplied that way carry no status key. Use `from_directory` in
+production; the difference is recorded in [`docs/POLICY-PARITY.md`](../../docs/POLICY-PARITY.md).
+
+## Verify a running copy (ADR-019)
+
+Same call; supply **your** audience when you build the verifier:
+
+```python
+v = Verifier.from_directory(directory, roots["root_ed25519"], roots["root_slh"],
+                            audience="https://api.example")   # never taken from the bundle
+v.verify(bundle, now)     # the instance layer is checked automatically when present
+```
+
+The default empty audience is fail-closed — a service that has not said who it is accepts no instance credential.
+
+Minting lives on the operator's side and takes a signing callback, so no key material enters this package:
+`mint_instance_credential`, `prove_instance_possession`.

ainra-0.4.0/ainra/__init__.py

@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: Apache-2.0 OR MIT
+"""ainra — an independent Python implementation of the AINRA passport verifier.
+
+Verify-only, offline, fail-closed, zero-telemetry. Written from the AINRA
+specification and conformance vectors (not transliterated from the Rust core or
+the TypeScript SDK); the differential harness proves it agrees with them
+byte-for-byte on every vector's verdict and reason. See the package README and
+decision D-041 for the precise independence claim and the shared cryptographic
+primitives.
+
+Quickstart::
+
+    from ainra import Verifier
+    v = Verifier(anchors)               # anchors: {registrar_id: {...keys...}}
+    verdict = v.verify(bundle, now)     # caller supplies `now`; no I/O
+    if verdict.valid:
+        ...
+    else:
+        print(verdict.reason)           # one of the 20 frozen reasons
+"""
+
+from __future__ import annotations
+
+from . import reasons
+from .delta import verify_delta, verify_head
+from .directory import verify_directory
+from .instance import (
+    INSTANCE_CRED_DEFAULT_SECS,
+    instance_signing_bytes,
+    mint_instance_credential,
+    instance_cred_digest,
+    pop_signing_bytes,
+    prove_instance_possession,
+)
+from .middleware import AinraGate, ainra_gate
+from .verdict import Verdict
+from .verifier import Verifier
+from .verify import verify
+
+__all__ = [
+    # ADR-019 — the instance rung. Verification is automatic (step 10 of verify()); these are the PRODUCING side,
+    # and they live on opposite sides of the container boundary on purpose.
+    "mint_instance_credential",
+    "prove_instance_possession",
+    "instance_signing_bytes",
+    "instance_cred_digest",
+    "pop_signing_bytes",
+    "INSTANCE_CRED_DEFAULT_SECS",
+    "Verifier",
+    "Verdict",
+    "verify",
+    "verify_delta",
+    "verify_head",
+    "verify_directory",
+    "AinraGate",
+    "ainra_gate",
+    "reasons",
+]
+
+__version__ = "0.3.0"

ainra-0.4.0/ainra/_b64.py

@@ -0,0 +1,57 @@
+# SPDX-License-Identifier: Apache-2.0 OR MIT
+"""The strict canonical base64url gateway (decision D-029).
+
+Every external base64url ingestion in the verifier routes through :func:`decode`.
+Python's :func:`base64.urlsafe_b64decode` is *lenient* — it silently accepts
+non-zero trailing bits, standard-alphabet ("+"/"/") swaps, whitespace, and
+padding. That leniency is exactly the fail-open class D-029 closes. We require a
+canonical round-trip (``encode(decode(s)) == s``) plus an explicit alphabet
+check, mirroring the Rust core's ``base64ct`` ``Base64UrlUnpadded`` byte-for-byte:
+a value is accepted iff it is unpadded base64url whose final character's unused
+low bits are all zero. Anything else is refused (returns ``None``); the caller
+maps that refusal to the field-appropriate frozen reason.
+"""
+
+from __future__ import annotations
+
+import base64
+
+_ALPHABET = frozenset(
+    "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_"
+)
+
+
+def decode(s: object) -> bytes | None:
+    """Strictly decode a canonical unpadded base64url string.
+
+    Returns the raw bytes, or ``None`` if ``s`` is not a canonical encoding.
+    Never raises — a verifier must fail closed, not crash.
+    """
+    if not isinstance(s, str):
+        return None
+    # Reject padding, whitespace, and any non-alphabet character up front.
+    for ch in s:
+        if ch not in _ALPHABET:
+            return None
+    try:
+        raw = base64.urlsafe_b64decode(s + "=" * (-len(s) % 4))
+    except Exception:
+        return None
+    # Canonical round-trip: catches non-zero trailing bits (a lenient decoder
+    # would drop them). Identical acceptance set to base64ct Base64UrlUnpadded.
+    if base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii") != s:
+        return None
+    return raw
+
+
+def encode(raw: bytes) -> str:
+    """Canonical unpadded base64url encoding of ``raw``."""
+    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode("ascii")
+
+
+def decode_fixed(s: object, length: int) -> bytes | None:
+    """Strictly decode and require exactly ``length`` bytes, else ``None``."""
+    raw = decode(s)
+    if raw is None or len(raw) != length:
+        return None
+    return raw

ainra-0.4.0/ainra/_canon.py

@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: Apache-2.0 OR MIT
+"""Deterministic canonical JSON (decisions D-003 and D-010).
+
+The canonical form is the sorted-key, no-whitespace scheme the whole AINRA
+corpus is signed and hashed over: object keys sorted, ``"key":value`` with no
+spaces, scalars serialized exactly as a minimal JSON encoder would. Three input
+classes are *rejected* (:class:`CanonError`) because they would diverge across a
+byte-for-byte cross-language differential (D-010): floating-point numbers,
+non-ASCII object keys (UTF-16 vs UTF-8 sort order disagree), and integers
+outside ``[-(2**53 - 1), 2**53 - 1]`` (not exactly representable as a JS
+``Number``). No conformant AINRA credential uses any of them.
+
+This is an independent implementation written from the specification, not a port
+of the Rust ``canon`` or the TypeScript ``canonicalize``; the differential
+harness is what proves the three agree.
+"""
+
+from __future__ import annotations
+
+_MAX_SAFE_INT = (2**53) - 1
+
+
+class CanonError(ValueError):
+    """Raised when a value cannot be canonicalized deterministically."""
+
+
+def _string(s: str) -> str:
+    # Minimal JSON string escaping, matching a standard JSON encoder (the same
+    # set produced by JSON.stringify / serde_json): quote, backslash, the five
+    # short control escapes, and \u00xx for the remaining C0 controls. Forward
+    # slash is NOT escaped. Non-ASCII characters are emitted verbatim (UTF-8).
+    out = ['"']
+    for ch in s:
+        o = ord(ch)
+        if ch == '"':
+            out.append('\\"')
+        elif ch == "\\":
+            out.append("\\\\")
+        elif ch == "\b":
+            out.append("\\b")
+        elif ch == "\f":
+            out.append("\\f")
+        elif ch == "\n":
+            out.append("\\n")
+        elif ch == "\r":
+            out.append("\\r")
+        elif ch == "\t":
+            out.append("\\t")
+        elif o < 0x20:
+            out.append("\\u%04x" % o)
+        else:
+            out.append(ch)
+    out.append('"')
+    return "".join(out)
+
+
+def _is_ascii(s: str) -> bool:
+    return all(ord(c) < 0x80 for c in s)
+
+
+def canonicalize(value: object) -> str:
+    """Return the canonical JSON string for ``value`` (raises on divergent input)."""
+
+    def enc(v: object) -> str:
+        if v is None:
+            return "null"
+        if v is True:
+            return "true"
+        if v is False:
+            return "false"
+        if isinstance(v, float):
+            # A float in the input is a divergence hazard (D-010): reject.
+            raise CanonError("floats are not canonicalizable")
+        if isinstance(v, int):
+            if v > _MAX_SAFE_INT or v < -_MAX_SAFE_INT:
+                raise CanonError("integer outside the JS-safe range")
+            return str(v)
+        if isinstance(v, str):
+            return _string(v)
+        if isinstance(v, (list, tuple)):
+            return "[" + ",".join(enc(x) for x in v) + "]"
+        if isinstance(v, dict):
+            items = []
+            for k in v:
+                if not isinstance(k, str):
+                    raise CanonError("object keys must be strings")
+                if not _is_ascii(k):
+                    raise CanonError("non-ASCII object key")
+            for k in sorted(v.keys()):
+                items.append(_string(k) + ":" + enc(v[k]))
+            return "{" + ",".join(items) + "}"
+        raise CanonError(f"uncanonicalizable value of type {type(v).__name__}")
+
+    return enc(value)
+
+
+def canon_bytes(value: object) -> bytes:
+    return canonicalize(value).encode("utf-8")