aot-ev1 0.1.0__py3-none-any.whl

aot_ev1/__init__.py

@@ -0,0 +1,4 @@
+"""AOT-EV1 — deterministic evidence layer (see SPEC.md)."""
+
+__version__ = "0.1.0"
+__all__ = ["__version__"]

aot_ev1/anchor.py

@@ -0,0 +1,16 @@
+"""Optional anchoring hook — optional, not part of core.
+
+AOT-EV1 deliberately ships without any anchoring (no BTC timestamps, no
+network calls). A future extra may implement :func:`anchor_bundle`; until
+then it is an explicit stub so callers fail loudly instead of assuming that
+an evidence bundle has been anchored.
+"""
+
+from __future__ import annotations
+
+from typing import Any, NoReturn
+
+
+def anchor_bundle(*args: Any, **kwargs: Any) -> NoReturn:
+    """Anchor a bundle (optional, not part of core) — not implemented."""
+    raise NotImplementedError("optional, not part of core")

aot_ev1/bundle.py

@@ -0,0 +1,196 @@
+"""Deterministic ``.aotev.zip`` bundles (SPEC.md §6, §7)."""
+
+from __future__ import annotations
+
+import hashlib
+import io
+import zipfile
+from pathlib import Path
+from typing import Iterable, Mapping
+
+from .canonical import canonical_bytes, check_canonical_payload, evidence_hash_hex
+from .errors import AOTEV1Error
+from .jcs_strict import MAX_SAFE_INT
+from .schema_lite import validate_payload
+
+__all__ = [
+    "MANIFEST_NAME",
+    "PAYLOAD_NAME",
+    "MAX_ENTRIES",
+    "MAX_UNCOMPRESSED",
+    "ZIP_DATE_TIME",
+    "ZIP_EXTERNAL_ATTR",
+    "signature_file",
+    "bundle_hash",
+    "build_manifest",
+    "bundle_bytes",
+    "write_bundle",
+    "read_signed_dir",
+]
+
+MANIFEST_NAME = "manifest.json"
+PAYLOAD_NAME = "payload.json"
+MAX_ENTRIES = 32
+MAX_UNCOMPRESSED = 8 * 1024 * 1024
+ZIP_DATE_TIME = (1980, 1, 1, 0, 0, 0)
+ZIP_EXTERNAL_ATTR = 0o100644 << 16
+
+_SIGNATURE_SUFFIX = {"ed25519": "ed25519", "eip712": "eip712"}
+_SIGNATURE_SIZE = {"ed25519": 64, "eip712": 65}
+
+
+def signature_file(role: str, scheme: str) -> str:
+    try:
+        suffix = _SIGNATURE_SUFFIX[scheme]
+    except KeyError:
+        raise AOTEV1Error(f"unsupported signature scheme: {scheme!r}") from None
+    if role not in ("issuer", "auditor"):
+        raise AOTEV1Error(f"unsupported signature role: {role!r}")
+    return f"signatures/{role}.{suffix}"
+
+
+def bundle_hash(entries: Iterable[tuple[str, bytes]]) -> bytes:
+    """``sha256`` over ``name + b"\\x00" + sha256(content)`` sorted by name."""
+    parts = []
+    for name, content in sorted(entries, key=lambda item: item[0]):
+        parts.append(name.encode("ascii") + b"\x00" + hashlib.sha256(content).digest())
+    return hashlib.sha256(b"".join(parts)).digest()
+
+
+def _signature_entries(
+    payload: dict, signatures: Mapping[str, bytes]
+) -> list[tuple[str, bytes]]:
+    for role in signatures:
+        if role not in ("issuer", "auditor"):
+            raise AOTEV1Error(f"unsupported signature role: {role!r}")
+    if "issuer" not in signatures:
+        raise AOTEV1Error("missing issuer signature")
+    if payload["auditor"] is None and "auditor" in signatures:
+        raise AOTEV1Error("auditor signature given but payload.auditor is null")
+    if payload["auditor"] is not None and "auditor" not in signatures:
+        raise AOTEV1Error("missing auditor signature")
+
+    entries: list[tuple[str, bytes]] = []
+    for role in ("issuer", "auditor"):
+        if role not in signatures:
+            continue
+        identity = payload[role]
+        scheme = identity["scheme"]
+        signature = bytes(signatures[role])
+        expected = _SIGNATURE_SIZE[scheme]
+        if len(signature) != expected:
+            raise AOTEV1Error(
+                f"{role} signature must be {expected} bytes for {scheme}, got {len(signature)}"
+            )
+        entries.append((signature_file(role, scheme), signature))
+    return entries
+
+
+def build_manifest(
+    payload: dict,
+    data_entries: list[tuple[str, bytes]],
+    created_at: int,
+) -> dict:
+    signatures = []
+    for role in ("issuer", "auditor"):
+        identity = payload[role]
+        if identity is None:
+            continue
+        signatures.append(
+            {
+                "role": role,
+                "scheme": identity["scheme"],
+                "key_id": identity["key_id"],
+                "file": signature_file(role, identity["scheme"]),
+            }
+        )
+    payload_bytes = dict(data_entries)[PAYLOAD_NAME]
+    return {
+        "v": "1",
+        "created_at": created_at,
+        "evidence_hash": evidence_hash_hex(payload),
+        "payload_sha256": hashlib.sha256(payload_bytes).hexdigest(),
+        "entries": [
+            {"name": name, "sha256": hashlib.sha256(content).hexdigest(), "size": len(content)}
+            for name, content in sorted(data_entries, key=lambda item: item[0])
+        ],
+        "signatures": signatures,
+        "bundle_hash": bundle_hash(data_entries).hex(),
+    }
+
+
+def _zip_info(name: str) -> zipfile.ZipInfo:
+    info = zipfile.ZipInfo(name, date_time=ZIP_DATE_TIME)
+    info.compress_type = zipfile.ZIP_STORED
+    info.create_system = 0
+    info.external_attr = ZIP_EXTERNAL_ATTR
+    info.flag_bits = 0
+    info.extra = b""
+    info.comment = b""
+    return info
+
+
+def _write_zip(records: list[tuple[str, bytes]]) -> bytes:
+    buffer = io.BytesIO()
+    with zipfile.ZipFile(buffer, "w", compression=zipfile.ZIP_STORED, allowZip64=False) as archive:
+        for name, content in records:
+            info = _zip_info(name)
+            info.file_size = len(content)
+            archive.writestr(info, content)
+    return buffer.getvalue()
+
+
+def bundle_bytes(
+    payload: dict,
+    signatures: Mapping[str, bytes],
+    created_at: int | None = None,
+) -> bytes:
+    """Build deterministic zip bytes for ``payload`` and its signatures."""
+    validate_payload(payload)
+    payload_bytes = canonical_bytes(payload)
+    if created_at is None:
+        created_at = payload["valid_from"]
+    if not isinstance(created_at, int) or isinstance(created_at, bool):
+        raise AOTEV1Error("created_at must be an integer")
+    if created_at < 0 or created_at > MAX_SAFE_INT:
+        raise AOTEV1Error("created_at outside the safe integer range")
+
+    data_entries = [(PAYLOAD_NAME, payload_bytes)]
+    data_entries.extend(_signature_entries(payload, signatures))
+    if len(data_entries) + 1 > MAX_ENTRIES:
+        raise AOTEV1Error(f"bundle exceeds {MAX_ENTRIES} entries")
+    if sum(len(content) for _, content in data_entries) > MAX_UNCOMPRESSED:
+        raise AOTEV1Error(f"bundle exceeds {MAX_UNCOMPRESSED} uncompressed bytes")
+
+    manifest = build_manifest(payload, data_entries, created_at)
+    records = [(MANIFEST_NAME, canonical_bytes(manifest))]
+    records.extend(sorted(data_entries, key=lambda item: item[0]))
+    return _write_zip(records)
+
+
+def write_bundle(
+    path: str | Path,
+    payload: dict,
+    signatures: Mapping[str, bytes],
+    created_at: int | None = None,
+) -> str:
+    """Write ``bundle_bytes`` to ``path`` and return the sha256 hex digest."""
+    data = bundle_bytes(payload, signatures, created_at)
+    target = Path(path)
+    target.parent.mkdir(parents=True, exist_ok=True)
+    target.write_bytes(data)
+    return hashlib.sha256(data).hexdigest()
+
+
+def read_signed_dir(directory: str | Path) -> tuple[dict, dict[str, bytes]]:
+    """Read ``payload.json`` + ``signatures/`` produced by ``aotev sign``."""
+    root = Path(directory)
+    payload = check_canonical_payload((root / PAYLOAD_NAME).read_bytes())
+    signatures: dict[str, bytes] = {}
+    for role in ("issuer", "auditor"):
+        identity = payload[role]
+        if identity is None:
+            continue
+        path = root / signature_file(role, identity["scheme"])
+        signatures[role] = path.read_bytes()
+    return payload, signatures

aot_ev1/canonical.py

@@ -0,0 +1,119 @@
+"""Payload bytes, canonical form and ``evidence_hash`` (SPEC.md §1, §3)."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from typing import Any, NoReturn
+
+from .errors import CanonicalError
+from .jcs_strict import MAX_SAFE_INT, canonical_bytes, canonical_text
+
+__all__ = [
+    "EVIDENCE_DOMAIN",
+    "canonical_bytes",
+    "canonical_text",
+    "evidence_hash",
+    "evidence_hash_hex",
+    "parse_payload",
+    "parse_json",
+    "check_canonical_payload",
+]
+
+EVIDENCE_DOMAIN = b"AOT-EV1"
+
+
+def _reject_float(token: str) -> NoReturn:
+    raise CanonicalError(f"floats are not allowed: {token}")
+
+
+def _reject_constant(token: str) -> NoReturn:
+    raise CanonicalError(f"non-finite numbers are not allowed: {token}")
+
+
+def _parse_int(token: str) -> int:
+    if token == "-0":
+        raise CanonicalError("negative zero is not allowed")
+    value = int(token)
+    if value < -MAX_SAFE_INT or value > MAX_SAFE_INT:
+        raise CanonicalError(f"integer outside safe range: {token}")
+    return value
+
+
+def _pairs_hook(pairs: list[tuple[str, Any]]) -> dict[str, Any]:
+    result: dict[str, Any] = {}
+    for key, value in pairs:
+        if key in result:
+            raise CanonicalError(f"duplicate object key: {key!r}")
+        result[key] = value
+    return result
+
+
+def _check_node(value: Any) -> None:
+    if isinstance(value, str):
+        for ch in value:
+            if 0xD800 <= ord(ch) <= 0xDFFF:
+                raise CanonicalError("lone surrogate in string")
+    elif isinstance(value, list):
+        for item in value:
+            _check_node(item)
+    elif isinstance(value, dict):
+        for key, item in value.items():
+            if not isinstance(key, str):
+                raise CanonicalError(f"object key is not a string: {type(key).__name__}")
+            for ch in key:
+                if 0xD800 <= ord(ch) <= 0xDFFF:
+                    raise CanonicalError("lone surrogate in object key")
+            _check_node(item)
+
+
+def parse_json(data: bytes | str) -> Any:
+    """Parse strict JSON: no floats, no ``-0``, no duplicate keys."""
+    if isinstance(data, bytes):
+        try:
+            text = data.decode("utf-8")
+        except UnicodeDecodeError as exc:
+            raise CanonicalError(f"payload is not valid UTF-8: {exc}") from exc
+    else:
+        text = data
+    if text.startswith("\ufeff"):
+        raise CanonicalError("byte-order mark is not allowed")
+    try:
+        value = json.loads(
+            text,
+            object_pairs_hook=_pairs_hook,
+            parse_float=_reject_float,
+            parse_constant=_reject_constant,
+            parse_int=_parse_int,
+        )
+    except CanonicalError:
+        raise
+    except ValueError as exc:
+        raise CanonicalError(f"invalid JSON: {exc}") from exc
+    _check_node(value)
+    return value
+
+
+def parse_payload(data: bytes | str) -> dict[str, Any]:
+    """Parse ``payload.json`` bytes and require a top-level object."""
+    value = parse_json(data)
+    if not isinstance(value, dict):
+        raise CanonicalError("payload must be a JSON object")
+    return value
+
+
+def evidence_hash(payload: Any) -> bytes:
+    """``sha256(b"AOT-EV1" + canonical_bytes)`` (SPEC.md §1)."""
+    return hashlib.sha256(EVIDENCE_DOMAIN + canonical_bytes(payload)).digest()
+
+
+def evidence_hash_hex(payload: Any) -> str:
+    return evidence_hash(payload).hex()
+
+
+def check_canonical_payload(raw: bytes) -> dict[str, Any]:
+    """Step 6 helper: parse ``raw`` and require it to be canonical bytes."""
+    payload = parse_payload(raw)
+    if canonical_bytes(payload) != raw:
+        raise CanonicalError("payload.json is not stored in canonical bytes")
+    return payload

aot_ev1/cli.py

@@ -0,0 +1,206 @@
+"""Command line interface for AOT-EV1 (see SPEC.md)."""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from pathlib import Path
+from typing import Sequence
+
+from . import __version__
+from .canonical import canonical_bytes, evidence_hash_hex, parse_payload
+from .errors import AOTEV1Error, exit_code_for
+from .bundle import read_signed_dir, write_bundle
+from .verify import verify_bundle
+from .schema_lite import validate_payload
+from .sign import eip712_types, sign_evidence
+
+__all__ = ["main"]
+
+
+def _read_input(path: str | None) -> bytes:
+    if path is None or path == "-":
+        return sys.stdin.buffer.read()
+    with open(path, "rb") as handle:
+        return handle.read()
+
+
+def _cmd_canonical(args: argparse.Namespace) -> int:
+    raw = _read_input(args.path)
+    payload = parse_payload(raw)
+    data = canonical_bytes(payload)
+    sys.stdout.write(f"canonical_bytes: {data.hex()}\n")
+    sys.stdout.write(f"canonical_json: {data.decode('ascii')}\n")
+    sys.stdout.write(f"evidence_hash: {evidence_hash_hex(payload)}\n")
+    return 0
+
+
+def _cmd_sign(args: argparse.Namespace) -> int:
+    payload = parse_payload(_read_input(args.payload))
+    validate_payload(payload)
+    out = Path(args.out)
+    out.mkdir(parents=True, exist_ok=True)
+    if payload["issuer"]["scheme"] == "ed25519":
+        issuer_file = "signatures/issuer.ed25519"
+    else:
+        issuer_file = "signatures/issuer.eip712"
+    (out / "signatures").mkdir(exist_ok=True)
+    (out / "payload.json").write_bytes(canonical_bytes(payload))
+    (out / issuer_file).write_bytes(sign_evidence(payload, "issuer", args.issuer_key, args.chain_id))
+    sys.stdout.write(f"issuer: {issuer_file} ({payload['issuer']['key_id']})\n")
+    if payload["auditor"] is not None:
+        if not args.auditor_key:
+            raise AOTEV1Error("payload has an auditor but --auditor-key was not given")
+        auditor_file = (
+            "signatures/auditor.ed25519"
+            if payload["auditor"]["scheme"] == "ed25519"
+            else "signatures/auditor.eip712"
+        )
+        (out / auditor_file).write_bytes(
+            sign_evidence(payload, "auditor", args.auditor_key, args.chain_id)
+        )
+        sys.stdout.write(f"auditor: {auditor_file} ({payload['auditor']['key_id']})\n")
+    elif args.auditor_key:
+        raise AOTEV1Error("--auditor-key given but payload.auditor is null")
+    sys.stdout.write(f"payload: payload.json\nevidence_hash: {evidence_hash_hex(payload)}\n")
+    return 0
+
+
+def _print_types() -> None:
+    from .sign import PAYLOAD_FIELDS
+
+    sys.stdout.write("payload fields:\n")
+    for name, kind in PAYLOAD_FIELDS:
+        sys.stdout.write(f"  {name}: {kind}\n")
+    sys.stdout.write("eip712 types:\n")
+    for type_name, fields in eip712_types().items():
+        rendered = ", ".join(f"{item['name']} {item['type']}" for item in fields)
+        sys.stdout.write(f"  {type_name}({rendered})\n")
+
+
+def _cmd_inspect(args: argparse.Namespace) -> int:
+    if args.types:
+        _print_types()
+        if not args.path:
+            return 0
+    if not args.path:
+        raise AOTEV1Error("inspect needs a bundle path or --types")
+    import json
+    import zipfile
+
+    from .bundle import MANIFEST_NAME, PAYLOAD_NAME
+    from .canonical import parse_json
+
+    try:
+        with zipfile.ZipFile(args.path) as archive:
+            manifest = parse_json(archive.read(MANIFEST_NAME))
+            payload_bytes = archive.read(PAYLOAD_NAME)
+        payload = parse_json(payload_bytes)
+    except (zipfile.BadZipFile, KeyError, OSError) as exc:
+        raise AOTEV1Error(f"cannot inspect bundle: {exc}") from exc
+    sys.stdout.write(f"evidence_hash: {manifest['evidence_hash']}\n")
+    sys.stdout.write(f"created_at: {manifest['created_at']}\n")
+    sys.stdout.write(f"bundle_hash: {manifest['bundle_hash']}\n")
+    sys.stdout.write("entries:\n")
+    for entry in manifest["entries"]:
+        sys.stdout.write(f"  {entry['name']} {entry['size']} {entry['sha256']}\n")
+    sys.stdout.write("signatures:\n")
+    for signature in manifest["signatures"]:
+        sys.stdout.write(
+            f"  {signature['role']} {signature['scheme']} {signature['key_id']} {signature['file']}\n"
+        )
+    sys.stdout.write("payload:\n")
+    sys.stdout.write(json.dumps(payload, indent=2, ensure_ascii=True, sort_keys=True) + "\n")
+    return 0
+
+
+def _cmd_bundle(args: argparse.Namespace) -> int:
+    payload, signatures = read_signed_dir(args.directory)
+    out = Path(args.out) if args.out else Path(f"{evidence_hash_hex(payload)}.aotev.zip")
+    digest = write_bundle(out, payload, signatures, args.created_at)
+    sys.stdout.write(f"bundle: {out}\n")
+    sys.stdout.write(f"evidence_hash: {evidence_hash_hex(payload)}\n")
+    sys.stdout.write(f"bundle_sha256: {digest}\n")
+    return 0
+
+
+def _cmd_verify(args: argparse.Namespace) -> int:
+    result = verify_bundle(
+        args.bundle,
+        now=args.now,
+        chain_path=args.chain,
+        chain_id=args.chain_id,
+    )
+    for step in result.steps:
+        state = "ok" if step.ok else (step.error or "failed")
+        sys.stdout.write(f"step {step.number:2d}: {state:<14} {step.name}\n")
+    sys.stdout.write(f"status: {result.status}\n")
+    if result.bundle_sha256:
+        sys.stdout.write(f"bundle_sha256: {result.bundle_sha256}\n")
+    if result.evidence_hash:
+        sys.stdout.write(f"evidence_hash: {result.evidence_hash}\n")
+    sys.stdout.write(f"chain: {result.chain}\n")
+    if result.error is not None:
+        sys.stdout.write(f"error: {result.error}\n")
+    return result.exit_code
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="aotev",
+        description="AOT-EV1 — deterministic evidence layer for ERC-8325.",
+        epilog="Exit codes: 0 valid, 2 broken (steps 1-10), 3 expired/revoked, 4 chain error.",
+    )
+    parser.add_argument("--version", action="version", version=f"aot-ev1 {__version__}")
+    sub = parser.add_subparsers(dest="command", required=True)
+
+    canonical = sub.add_parser("canonical", help="print canonical payload bytes and evidence_hash")
+    canonical.add_argument("path", nargs="?", help="payload JSON file (default: stdin)")
+    canonical.set_defaults(func=_cmd_canonical)
+
+    sign = sub.add_parser("sign", help="sign a payload and write payload.json + signatures/")
+    sign.add_argument("--payload", required=True, help="payload JSON file")
+    sign.add_argument("--issuer-key", required=True, help="Ed25519 seed/secret hex or 0x EVM private key")
+    sign.add_argument("--auditor-key", help="auditor key, required when payload.auditor is set")
+    sign.add_argument("--chain-id", type=int, default=1, help="EIP-712 chainId (default: 1)")
+    sign.add_argument("--out", required=True, help="output directory")
+    sign.set_defaults(func=_cmd_sign)
+
+    inspect = sub.add_parser("inspect", help="inspect a payload bundle or print type information")
+    inspect.add_argument("path", nargs="?", help="bundle file")
+    inspect.add_argument("--types", action="store_true", help="print payload and EIP-712 type tables")
+    inspect.set_defaults(func=_cmd_inspect)
+
+    bundle = sub.add_parser("bundle", help="pack a signed payload directory into a deterministic zip")
+    bundle.add_argument("directory", help="directory with payload.json and signatures/")
+    bundle.add_argument("-o", "--out", help="output zip path (default: <evidence_hash>.aotev.zip)")
+    bundle.add_argument("--created-at", type=int, help="manifest created_at (default: payload.valid_from)")
+    bundle.set_defaults(func=_cmd_bundle)
+
+    verify = sub.add_parser("verify", help="verify a bundle offline (12 checks)")
+    verify.add_argument("bundle", help="bundle file")
+    verify.add_argument("--chain", help="previous bundle for chain continuity (optional)")
+    verify.add_argument("--now", type=int, help="verification time in unix seconds (default: system clock)")
+    verify.add_argument("--chain-id", type=int, default=1, help="EIP-712 chainId (default: 1)")
+    verify.set_defaults(func=_cmd_verify)
+    return parser
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = build_parser()
+    args = parser.parse_args(argv)
+    try:
+        return int(args.func(args))
+    except AOTEV1Error as exc:
+        sys.stderr.write(f"error: {exc}\n")
+        return exit_code_for(exc)
+    except ImportError as exc:
+        sys.stderr.write(f"error: {exc}\n")
+        return 2
+    except OSError as exc:
+        sys.stderr.write(f"error: {exc}\n")
+        return 2
+
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

aot_ev1/ed25519_strict.py

@@ -0,0 +1,49 @@
+"""Strict Ed25519 verification profile (D2, 2026-11-02).
+
+Rejects non-canonical/small-order public keys, S >= L, and non-canonical R.
+Used for both agent (sig_A) and notary (sig_N) signatures.
+"""
+import nacl.bindings
+from nacl.exceptions import BadSignatureError
+from nacl.signing import VerifyKey
+
+L = 2**252 + 27742317777372353535851937790883648493
+
+# Canonical encodings of the eight small-order points (identity, order 2, etc.).
+SMALL_ORDER_POINTS = {
+    bytes.fromhex("00" * 32),
+    bytes.fromhex("01" + "00" * 31),
+    bytes.fromhex("ec" + "ff" * 31),
+    bytes.fromhex("ed" + "ff" * 31),
+    bytes.fromhex("26e8958fc2b227b045c3f489f2ef98f0d5dfac05d3c63339b13802886d53fc05"),
+    bytes.fromhex("c7176a703d4dd84fba3c0b760d10670f2a2053fa2c39ccc64ec7fd7792ac037a"),
+    bytes.fromhex("c7176a703d4dd84fba3c0b760d10670f2a2053fa2c39ccc64ec7fd7792ac03fa"),
+    bytes.fromhex("26e8958fc2b227b045c3f489f2ef98f0d5dfac05d3c63339b13802886d53fc85"),
+}
+
+
+def _canonical_point(enc: bytes) -> bool:
+    if len(enc) != 32:
+        return False
+    try:
+        return bool(nacl.bindings.crypto_core_ed25519_is_valid_point(enc))
+    except Exception:
+        return False
+
+
+def verify_strict(pubkey: bytes, message: bytes, signature: bytes) -> bool:
+    if len(pubkey) != 32 or len(signature) != 64:
+        return False
+    pubkey = bytes(pubkey)
+    if pubkey in SMALL_ORDER_POINTS or not _canonical_point(pubkey):
+        return False
+    s = int.from_bytes(signature[32:], "little")
+    if s >= L:
+        return False
+    if not _canonical_point(signature[:32]):
+        return False
+    try:
+        VerifyKey(pubkey).verify(bytes(message), bytes(signature))
+        return True
+    except (BadSignatureError, ValueError, TypeError):
+        return False