ainra 0.4.0__py3-none-any.whl

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/_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/_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")

ainra/_crypto.py

@@ -0,0 +1,152 @@
+# SPDX-License-Identifier: Apache-2.0 OR MIT
+"""Cryptographic primitives — shared audited libraries, fail-closed wrappers.
+
+Independence note (see the package README and decision D-041): the verification
+*logic* in this package is written independently from the specification and the
+conformance vectors. The primitives themselves are deliberately NOT reimplemented
+— reimplementing a signature scheme would be less safe, not more independent:
+
+* **Ed25519** (32-byte key, 64-byte signature) and **ML-DSA-65 / FIPS 204**
+  (1952-byte key, 3309-byte signature) come from ``cryptography`` (pyca), which
+  wraps OpenSSL 3.5+.
+* **SLH-DSA-SHA2-128s / FIPS 205** (32-byte key, 7856-byte signature) is not yet
+  surfaced by ``cryptography``, so it is bound directly from the same OpenSSL
+  ``libcrypto`` via ``ctypes`` (EVP raw-public-key verify) — an established C
+  implementation used for that primitive only.
+* **SHA-256** is the Python standard library ``hashlib``.
+
+The differential (the fourth column of ``make diff``) exercises the *logic*, not
+the primitives; agreement with the Rust core, the TS SDK, and the JS CLI is the
+independent confirmation. Every wrapper returns ``bool`` and never raises: a
+verifier fails closed, so any error, wrong size, or exception is ``False``.
+"""
+
+from __future__ import annotations
+
+import ctypes
+import ctypes.util
+import hashlib
+
+from cryptography.hazmat.primitives.asymmetric import ed25519, mldsa
+
+# Exact FIPS / RFC 8032 sizes — asserted as a conformance gate, matching the
+# Rust core's size asserts (a deviation means a broken dependency, not a code
+# change).
+ED25519_PUB_LEN = 32
+ED25519_SIG_LEN = 64
+MLDSA65_PUB_LEN = 1952
+MLDSA65_SIG_LEN = 3309
+SLH_DSA_SHA2_128S_PUB_LEN = 32
+SLH_DSA_SHA2_128S_SIG_LEN = 7856
+
+
+def sha256(data: bytes) -> bytes:
+    return hashlib.sha256(data).digest()
+
+
+def ed25519_verify(pub: bytes, sig: bytes, msg: bytes) -> bool:
+    """Verify an Ed25519 signature; fail closed on any anomaly."""
+    if len(pub) != ED25519_PUB_LEN or len(sig) != ED25519_SIG_LEN:
+        return False
+    try:
+        ed25519.Ed25519PublicKey.from_public_bytes(pub).verify(sig, msg)
+        return True
+    except Exception:
+        return False
+
+
+def mldsa65_verify(pub: bytes, sig: bytes, msg: bytes) -> bool:
+    """Verify an ML-DSA-65 (FIPS 204) signature; fail closed on any anomaly."""
+    if len(pub) != MLDSA65_PUB_LEN or len(sig) != MLDSA65_SIG_LEN:
+        return False
+    try:
+        mldsa.MLDSA65PublicKey.from_public_bytes(pub).verify(sig, msg)
+        return True
+    except Exception:
+        return False
+
+
+# ── SLH-DSA-SHA2-128s via OpenSSL libcrypto (ctypes) ────────────────────────
+class _SlhBackend:
+    """Lazy, process-wide binding to OpenSSL's SLH-DSA-SHA2-128s verify."""
+
+    _ALG = b"SLH-DSA-SHA2-128s"
+
+    def __init__(self) -> None:
+        self._lib = None
+
+    def _load(self):
+        if self._lib is not None:
+            return self._lib
+        name = ctypes.util.find_library("crypto") or "libcrypto.so.3"
+        lib = ctypes.CDLL(name)
+
+        lib.EVP_PKEY_new_raw_public_key_ex.restype = ctypes.c_void_p
+        lib.EVP_PKEY_new_raw_public_key_ex.argtypes = [
+            ctypes.c_void_p, ctypes.c_char_p, ctypes.c_void_p,
+            ctypes.c_char_p, ctypes.c_size_t,
+        ]
+        lib.EVP_PKEY_free.restype = None
+        lib.EVP_PKEY_free.argtypes = [ctypes.c_void_p]
+        lib.EVP_MD_CTX_new.restype = ctypes.c_void_p
+        lib.EVP_MD_CTX_new.argtypes = []
+        lib.EVP_MD_CTX_free.restype = None
+        lib.EVP_MD_CTX_free.argtypes = [ctypes.c_void_p]
+        lib.EVP_DigestVerifyInit_ex.restype = ctypes.c_int
+        lib.EVP_DigestVerifyInit_ex.argtypes = [
+            ctypes.c_void_p, ctypes.c_void_p, ctypes.c_char_p, ctypes.c_void_p,
+            ctypes.c_char_p, ctypes.c_void_p, ctypes.c_void_p,
+        ]
+        lib.EVP_DigestVerify.restype = ctypes.c_int
+        lib.EVP_DigestVerify.argtypes = [
+            ctypes.c_void_p, ctypes.c_char_p, ctypes.c_size_t,
+            ctypes.c_char_p, ctypes.c_size_t,
+        ]
+        self._lib = lib
+        return lib
+
+    def verify(self, pub: bytes, sig: bytes, msg: bytes) -> bool:
+        if len(pub) != SLH_DSA_SHA2_128S_PUB_LEN or len(sig) != SLH_DSA_SHA2_128S_SIG_LEN:
+            return False
+        try:
+            lib = self._load()
+        except Exception:
+            return False
+        pkey = None
+        ctx = None
+        try:
+            pkey = lib.EVP_PKEY_new_raw_public_key_ex(
+                None, self._ALG, None, pub, len(pub)
+            )
+            if not pkey:
+                return False
+            ctx = lib.EVP_MD_CTX_new()
+            if not ctx:
+                return False
+            if lib.EVP_DigestVerifyInit_ex(ctx, None, None, None, None, pkey, None) != 1:
+                return False
+            return lib.EVP_DigestVerify(ctx, sig, len(sig), msg, len(msg)) == 1
+        except Exception:
+            return False
+        finally:
+            if ctx:
+                lib.EVP_MD_CTX_free(ctx)
+            if pkey:
+                lib.EVP_PKEY_free(pkey)
+
+
+_slh = _SlhBackend()
+
+
+def slh_dsa_sha2_128s_verify(pub: bytes, sig: bytes, msg: bytes) -> bool:
+    """Verify an SLH-DSA-SHA2-128s (FIPS 205) signature; fail closed."""
+    return _slh.verify(pub, sig, msg)
+
+
+def slh_available() -> bool:
+    """True iff the OpenSSL SLH-DSA verify path is usable in this environment."""
+    try:
+        _slh._load()
+        return True
+    except Exception:
+        return False

ainra/_merkle.py

@@ -0,0 +1,76 @@
+# SPDX-License-Identifier: Apache-2.0 OR MIT
+"""RFC 6962 Merkle hashing (decision D-008): SHA-256 with domain separation.
+
+Leaf hash is ``SHA-256(0x00 || data)``; interior node is
+``SHA-256(0x01 || left || right)``. Inclusion is verified by the standard
+RFC 6962 §2.1.1 audit-path walk. Written independently from RFC 6962.
+"""
+
+from __future__ import annotations
+
+import hashlib
+
+
+def leaf_hash(data: bytes) -> bytes:
+    return hashlib.sha256(b"\x00" + data).digest()
+
+
+def _node_hash(left: bytes, right: bytes) -> bytes:
+    return hashlib.sha256(b"\x01" + left + right).digest()
+
+
+def root_from_audit_path(leaf: bytes, index: object, proof: list[bytes]) -> bytes | None:
+    """Reconstruct the tree root from an audit path using only the leaf index.
+
+    At each level the proof sibling is combined left/right by the current index
+    bit (``index & 1``), then the index is shifted down — the method AINRA's
+    logs use to emit inclusion proofs. Returns ``None`` on a structurally invalid
+    input (fail closed). The caller compares the result to the credential's
+    committed ``log.root``.
+    """
+    if not isinstance(index, int) or index < 0:
+        return None
+    h = leaf
+    i = index
+    for sibling in proof:
+        if len(sibling) != 32:
+            return None
+        if i & 1:
+            h = _node_hash(sibling, h)
+        else:
+            h = _node_hash(h, sibling)
+        i >>= 1
+    return h
+
+
+def root_from_inclusion(
+    leaf: bytes, index: int, tree_size: int, proof: list[bytes]
+) -> bytes | None:
+    """Reconstruct the tree root from an RFC 6962 inclusion proof.
+
+    Returns the computed root hash, or ``None`` if the (index, size, proof) are
+    structurally inconsistent. The caller compares the result to the signed
+    checkpoint root — a mismatch (or ``None``) is fail-closed ``not_logged``.
+    """
+    if index < 0 or tree_size <= 0 or index >= tree_size:
+        return None
+    fn = index
+    sn = tree_size - 1
+    h = leaf
+    for sibling in proof:
+        if len(sibling) != 32:
+            return None
+        if fn == sn or (fn & 1) == 1:
+            h = _node_hash(sibling, h)
+            # Ascend past every left-child ancestor.
+            while fn != 0 and (fn & 1) == 0:
+                fn >>= 1
+                sn >>= 1
+        else:
+            h = _node_hash(h, sibling)
+        fn >>= 1
+        sn >>= 1
+    # A well-formed proof consumes exactly enough siblings to reach the root.
+    if sn != 0:
+        return None
+    return h

ainra/_name.py

@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: Apache-2.0 OR MIT
+"""AINRA name grammar (The Standard §2).
+
+``ainra:{registrar}:{operator}:{lineage}@{version}`` where each label is
+lowercase alphanumerics and hyphens, and ``version`` is a 1–3 field numeric
+semver. The issuer is a version-less DID: ``did:ainra:{registrar}:{operator}:{lineage}``.
+Written from the grammar; the ``name-malformed`` vectors are the ground truth.
+"""
+
+from __future__ import annotations
+
+import re
+from dataclasses import dataclass
+
+# A label is one or more lowercase alphanumerics / hyphens.
+_LABEL = re.compile(r"^[a-z0-9-]+$")
+# semver: 1 to 3 dot-separated numeric fields.
+_VERSION = re.compile(r"^[0-9]+(\.[0-9]+){0,2}$")
+
+
+def _label_ok(s: str) -> bool:
+    return bool(_LABEL.match(s))
+
+
+@dataclass(frozen=True)
+class SubjectName:
+    registrar: str
+    operator: str
+    lineage: str
+    version: str
+
+    @property
+    def number(self) -> str:
+        """The permanent version-less AINRA Number (a ``did:ainra`` DID)."""
+        return f"did:ainra:{self.registrar}:{self.operator}:{self.lineage}"
+
+
+def parse_subject(name: object) -> SubjectName | None:
+    """Parse ``ainra:reg:op:lin@ver``; ``None`` if it violates the grammar."""
+    if not isinstance(name, str) or "@" not in name:
+        return None
+    body, _, version = name.partition("@")
+    if not _VERSION.match(version):
+        return None
+    parts = body.split(":")
+    if len(parts) != 4 or parts[0] != "ainra":
+        return None
+    reg, op, lin = parts[1], parts[2], parts[3]
+    if not (_label_ok(reg) and _label_ok(op) and _label_ok(lin)):
+        return None
+    return SubjectName(reg, op, lin, version)
+
+
+def parse_issuer(iss: object) -> str | None:
+    """Parse ``did:ainra:reg:op:lin`` and return the registrar id, else ``None``."""
+    if not isinstance(iss, str):
+        return None
+    parts = iss.split(":")
+    # ["did", "ainra", reg, op, lin]
+    if len(parts) != 5 or parts[0] != "did" or parts[1] != "ainra":
+        return None
+    reg, op, lin = parts[2], parts[3], parts[4]
+    if not (_label_ok(reg) and _label_ok(op) and _label_ok(lin)):
+        return None
+    return reg

ainra/_vector_runner.py

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: Apache-2.0 OR MIT
+"""Differential runner: the fourth column of ``make diff``.
+
+Reads a directory of conformance vectors and prints, one line per vector,
+``<name>\\t<canonical-result-json>`` — the verdict+reason (passport), or the
+accept+reason/registrars (delta / directory). ``tools/diff-harness/run.mjs``
+spawns this once per corpus and asserts every line agrees with the vector's
+recorded ``expect`` (which is the Rust core's verdict), so the Python verifier
+joins the core / TS-SDK / JS-CLI differential as an independent fourth brain.
+
+Usage:  python -m ainra._vector_runner <passport|delta|directory> <dir>
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import sys
+
+from .delta import verify_delta_vector
+from .directory import verify_directory
+from .verify import verify as verify_passport
+
+
+def _stable(obj) -> str:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"))
+
+
+def run(kind: str, directory: str) -> int:
+    files = sorted(f for f in os.listdir(directory) if f.endswith(".json") and f != "manifest.json")
+    out = []
+    for f in files:
+        with open(os.path.join(directory, f), encoding="utf-8") as fh:
+            v = json.load(fh)
+        if kind == "passport":
+            pres = v["presentation"]
+            result = verify_passport(v["anchors"], pres, pres.get("now")).as_result()
+        elif kind == "delta":
+            result = verify_delta_vector(v)
+        elif kind == "directory":
+            result = verify_directory(v)
+        else:
+            print(f"unknown kind: {kind}", file=sys.stderr)
+            return 2
+        out.append(f"{v['name']}\t{_stable(result)}")
+    sys.stdout.write("\n".join(out) + ("\n" if out else ""))
+    return 0
+
+
+if __name__ == "__main__":
+    if len(sys.argv) != 3:
+        print(__doc__, file=sys.stderr)
+        sys.exit(2)
+    sys.exit(run(sys.argv[1], sys.argv[2]))