asexec 0.3.14__py3-none-any.whl

asexec/__init__.py

@@ -0,0 +1,17 @@
+"""asexec - a pre-registration & notarization primitive for AI evaluations.
+
+Local-first, pseudonymous, offline-verifiable. An evaluator signs a
+*pre-registration* before a run and *receipts* after, publishing them to a
+public git repo whose witnessed history is the (social) ceiling that gives
+"pre" its meaning. A third party can verify the commitment -> fulfillment /
+gap offline, trusting only a keypair and the published files.
+
+See the module docstrings and the README for what this does!
+"""
+
+__version__ = "0.3.14"
+
+SCHEMA_VERSION = "asexec"
+PREDICATE_TYPE = "https://asexec.dev/manifest"
+
+__all__ = ["__version__", "SCHEMA_VERSION", "PREDICATE_TYPE"]

asexec/__main__.py

@@ -0,0 +1,4 @@
+from .cli import main
+
+if __name__ == "__main__":  # pragma: no cover
+    raise SystemExit(main())

asexec/canonical.py

@@ -0,0 +1,61 @@
+"""Canonical serialization and the PAE signing input.
+
+We sign the PAE (Pre-Authentication Encoding, borrowed from DSSE) of a fixed,
+documented canonical byte serialization of the payload.
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+# Media type of the signed payload (an asexec manifest body).
+PAYLOAD_TYPE = b"application/vnd.asexec+json"
+
+# Domain-separation prefix for our PAE construction (cf. DSSE's "DSSEv1").
+_PAE_PREFIX = b"asexec-PAE/v1"
+
+
+def canonical_bytes(payload: Any) -> bytes:
+    """Deterministically serialize a JSON-compatible object to bytes.
+
+    Rules (documented so any implementation can reproduce them):
+      - UTF-8
+      - object keys sorted (lexicographic, by Unicode code point)
+      - no insignificant whitespace (compact separators)
+      - non-ASCII preserved (ensure_ascii=False)
+
+    The payload passed here must NOT contain the outer signature block; only
+    the manifest body is signed.
+    """
+    return json.dumps(
+        payload,
+        sort_keys=True,
+        separators=(",", ":"),
+        ensure_ascii=False,
+    ).encode("utf-8")
+
+
+def pae(payload_type: bytes, body: bytes) -> bytes:
+    """Pre-Authentication Encoding.
+
+    PAE(t, b) = PREFIX SP LEN(t) SP t SP LEN(b) SP b
+
+    where SP is a single ASCII space and LEN is ASCII decimal of the byte
+    length. Signing/verifying always happens over this string, never over raw
+    JSON.
+    """
+    return b" ".join(
+        [
+            _PAE_PREFIX,
+            str(len(payload_type)).encode("ascii"),
+            payload_type,
+            str(len(body)).encode("ascii"),
+            body,
+        ]
+    )
+
+
+def signing_input(payload: Any) -> bytes:
+    """The exact bytes to sign/verify for a manifest payload."""
+    return pae(PAYLOAD_TYPE, canonical_bytes(payload))

asexec/cli.py

@@ -0,0 +1,455 @@
+"""asexec command-line interface.
+
+Commands: keygen, prereg, postreg, verify, identity.
+
+``verify`` is fully offline; only the sign-time drand (``--floor``)/Roughtime (``--ceiling``)
+fetches and ``identity match`` touch the network.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import uuid
+from collections.abc import Callable
+from datetime import datetime
+from typing import TypeVar
+
+from . import __version__, drand, hashing, identity, keys, manifest, verifier
+from .errors import VerificationError
+
+OK = "✓"
+NO = "✗"
+T = TypeVar("T")
+
+
+# --------------------------------------------------------------------------- #
+# input helpers
+# --------------------------------------------------------------------------- #
+def _load_json(path: str) -> str | dict:
+    """Load JSON from the given path."""
+    try:
+        with open(path) as f:
+            return json.load(f)
+    except json.JSONDecodeError as e:
+        raise SystemExit(f"error: {path} must contain valid JSON: {e}") from e
+
+
+def _get_arg_or_file(
+    args, arg_name: str, file_arg_name: str, load_file: Callable[[str], T]
+) -> str | T | None:
+    """Load a value from either ``--<arg>`` or ``--<file-arg>``, but not both."""
+    value = getattr(args, arg_name, None)
+    file_path = getattr(args, file_arg_name, None)
+    if value and file_path:
+        raise SystemExit(
+            f"error: provide --{arg_name.replace('_', '-')} "
+            f"OR --{file_arg_name.replace('_', '-')}, not both"
+        )
+    if value:
+        return value
+    if file_path:
+        try:
+            return load_file(file_path)
+        except FileNotFoundError:
+            raise SystemExit(
+                f"error: --{file_arg_name.replace('_', '-')} not found: {file_path}"
+            ) from None
+    return None
+
+
+def _get_target(args) -> str | dict | None:
+    """Retrieve the target value (from arg xor file), if any."""
+    return _get_arg_or_file(args, "target", "target_file", _load_json)
+
+
+def _get_declaration(args) -> str | dict | None:
+    """Retrieve the declaration value (from arg xor file), if any."""
+    return _get_arg_or_file(args, "declaration", "declaration_file", _load_json)
+
+
+def _get_notes(args) -> str | dict | None:
+    """Retrieve the notes value (from arg xor file), if any."""
+    return _get_arg_or_file(args, "notes", "notes_file", _load_json)
+
+
+def _get_due(args) -> str | None:
+    """Validate the provided ``--due`` ISO-8601 deadline; return it verbatim."""
+    if not args.due:
+        return None
+    try:
+        datetime.fromisoformat(args.due.replace("Z", "+00:00"))
+    except ValueError:
+        raise SystemExit(f"error: --due is not a valid ISO-8601 timestamp: {args.due}") from None
+    return args.due
+
+
+def _get_floor(args) -> dict | None:
+    """Fetch a drand freshness floor (anchor.floor) at sign time, or None."""
+    if not args.floor:
+        return None
+    try:
+        return drand.fetch_floor()
+    except Exception as e:
+        sys.stderr.write(f"warning: drand fetch failed ({e}); continuing without freshness floor\n")
+        return None
+
+
+def _build_subject(paths: list[str] | None, hash_alg: str) -> list | None:
+    """Construct subject data (a list of filenames/dirnames and their associated
+    digest hashes) given source paths and a hash algorithm."""
+    return hashing.build_subject(paths, hash_alg) if paths else None
+
+
+def _resolve_ref(value: str) -> str:
+    """A --fulfills/--prev value may be a manifest file path or a literal ref."""
+    if os.path.isfile(value):
+        return manifest.ref(manifest.get_body(manifest.load(value)))
+    return value
+
+
+def _attach_ceiling(mani: dict, body: dict, want_ceiling: bool) -> None:
+    """Optionally fetch a Roughtime ceiling witness and attach it (sign-time,
+    network). The nonce is the body ref, so this must run *after* signing; it
+    does not perturb ref."""
+    if not want_ceiling:
+        return
+    from . import roughtime
+
+    nonce = manifest.ref(body)  # sha-256:<hex>
+    try:
+        ceiling = roughtime.fetch_ceiling(nonce)
+    except Exception as e:
+        sys.stderr.write(
+            f"warning: ceiling witness fetch failed ({e}); continuing without a ceiling\n"
+        )
+        return
+    manifest.attach_ceiling(mani, ceiling)
+    print(
+        f"  ceiling : {ceiling.get('ceiling_type')} witness {ceiling.get('witness_id')} "
+        f"@ {ceiling.get('midpoint')} (±{ceiling.get('radius')}s)"
+    )
+
+
+# --------------------------------------------------------------------------- #
+# commands
+# --------------------------------------------------------------------------- #
+def cmd_keygen(args) -> int:
+    """Generate a cryptographic key for signing pre- and post-registrations."""
+    out = args.out or f"asexec-{uuid.uuid4()}.key"
+    priv, _pub = keys.generate()
+    kid = keys.save(priv, out)
+    print(f"{OK} generated ed25519 key")
+    print(f"  secret : {out} (keep private; mode 0600)")
+    print(f"  public : {out}.pub")
+    print(f"  keyid  : {kid}")
+    return 0
+
+
+def cmd_prereg(args) -> int:
+    """Write a signed pre-registration, signalling the intended execution."""
+    target = _get_target(args)
+    if target is None:
+        raise SystemExit("error: give --target or --target-file (the only mandatory claim)")
+    priv, pub = keys.load_signing_key(args.key)
+    subject = _build_subject(args.subject, args.hash_alg)
+    body = manifest.build_prereg(
+        target,
+        due=_get_due(args),
+        declaration=_get_declaration(args),
+        subject=subject,
+        hash_alg=args.hash_alg,
+        floor=_get_floor(args),
+        notes=_get_notes(args),
+    )
+    mani = manifest.sign(body, priv, pub)
+    _attach_ceiling(mani, body, args.ceiling)
+    manifest.save(mani, args.out)
+    print(f"{OK} pre-registration written: {args.out}")
+    print(f"  ref : {manifest.ref(body)}")
+    if body.get("due"):
+        print(f"  due : {body['due']}")
+    return 0
+
+
+def cmd_postreg(args) -> int:
+    """Write a signed post-registration, documenting the execution and fulfilling
+    a pre-registration as promised."""
+    priv, pub = keys.load_signing_key(args.key)
+
+    prereg_body = None
+    if os.path.isfile(args.fulfills):
+        prereg_body = manifest.get_body(manifest.load(args.fulfills))
+
+    # target / due / declaration / hash_alg inherit from the fulfilled prereg
+    # unless overridden on this postreg.
+    target = _get_target(args)
+    if target is None:
+        if prereg_body is None:
+            raise SystemExit("error: no --target and --fulfills is not a readable prereg")
+        target = prereg_body["target"]
+
+    due = _get_due(args) or (prereg_body or {}).get("due")
+    declaration = _get_declaration(args) or (prereg_body or {}).get("declaration")
+    hash_alg = args.hash_alg or (prereg_body or {}).get("hash_alg") or hashing.DEFAULT_ALG
+
+    subject = _build_subject(args.subject, hash_alg)
+    body = manifest.build_postreg(
+        target,
+        fulfills=_resolve_ref(args.fulfills),
+        due=due,
+        declaration=declaration,
+        subject=subject,
+        hash_alg=hash_alg,
+        prev_hash=_resolve_ref(args.prev) if args.prev else None,
+        floor=_get_floor(args),
+        notes=_get_notes(args),
+        provenance=args.provenance,
+        repro_recipe=json.loads(args.repro_recipe) if args.repro_recipe else None,
+    )
+    mani = manifest.sign(body, priv, pub)
+    _attach_ceiling(mani, body, args.ceiling)
+    manifest.save(mani, args.out)
+    print(f"{OK} post-registration written: {args.out}")
+    print(f"  ref      : {manifest.ref(body)}")
+    print(f"  fulfills : {body['fulfills']}")
+    if body.get("prev_hash"):
+        print(f"  prev     : {body['prev_hash']}")
+    return 0
+
+
+def cmd_verify(args) -> int:
+    """Run a series of verification tests on the prereg-postreg cycle to prove that
+    this execution met the desired standards. Produces a code summarizing the tests
+    performed and the results of each."""
+    try:
+        tests = verifier.parse_tests(args.tests)
+    except VerificationError as e:
+        raise SystemExit(f"error: {e}") from e
+
+    report = verifier.verify_paths(args.paths, tests, artifacts_dir=args.artifacts)
+
+    print("=== manifests ===")
+    for m in report["manifests"]:
+        sig = m["signature"]
+        s = OK if (sig.get("signature_ok") and sig.get("keyid_ok")) else NO
+        print(f"{s} {m['path']}  [{m.get('phase')}]  keyid={m.get('keyid')}")
+        fl = m["floor"]
+        if fl["status"] != "absent":
+            fs = OK if fl["status"] == "verified" else NO
+            extra = (
+                f" (created no earlier than {fl.get('created_no_earlier_than')})"
+                if fl["status"] == "verified"
+                else ""
+            )
+            print(f"    {fs} drand freshness floor round {fl.get('round', '?')}{extra}")
+        cl = m["ceiling"]
+        if cl["status"] != "absent":
+            cs = OK if cl["status"] == "verified" else NO
+            extra = (
+                f" (created no later than {cl.get('midpoint')} ±{cl.get('radius')}s, "
+                f"witness {cl.get('witness_id')})"
+                if cl["status"] == "verified"
+                else f" ({cl.get('error', cl['status'])})"
+            )
+            print(f"    {cs} ceiling witness{extra}")
+        c = m["content"]
+        if c["status"] not in ("skipped",):
+            cs = OK if c["status"] == "ok" else NO
+            print(f"    {cs} content hashes {c['status']}")
+            for e in c.get("entries", []):
+                if not e["ok"]:
+                    print(f"        {NO} {e['name']}: {e.get('reason', 'digest mismatch')}")
+
+    print("\n=== commitments ===")
+    if not report["commitments"]:
+        print("  (no pre-registrations among the provided manifests)")
+    for c in report["commitments"]:
+        print(f"  [{c['state'].upper()}] prereg {c['ref']}")
+        print(f"    due          : {c.get('due') or '(none declared)'}")
+        print(
+            f"    postregs     : {len(c['receipts'])}"
+            + ("" if c["chain_ok"] else f"  {NO} {c['chain_note']}")
+        )
+        if not c["key_consistent"]:
+            print(f"    {NO} postregs signed by a different key than the pre-registration")
+    if report["notarization_only"]:
+        print("\n=== notarization-only (postregs with no matching pre-registration) ===")
+        for n in report["notarization_only"]:
+            print(f"  {n['ref']}  (fulfills {n.get('fulfills')})")
+
+    print("\n=== tests ===")
+    for t in report["tests"]:
+        r = report["results"][t]
+        s = OK if r["result"] == "PASS" else NO
+        print(f"  {s} {t}={r['result']}  ({r['reason']})")
+
+    if report["ceiling_trust"]:
+        print("\n=== ceiling trust (what you are accepting) ===")
+        for line in report["ceiling_trust"]:
+            print(f"  - {line}")
+
+    print("\n=== what this does NOT prove ===")
+    for nc in report["non_claims"]:
+        print(f"  - {nc}")
+
+    print(f"\n{report['code']}")
+    print(f"DISCLAIMER: {report['disclaimer']}")
+    return 0 if report["ok"] else 2
+
+
+def cmd_identity(args) -> int:
+    """Standalone emit/match function pair for tying a known public identity via
+    domain to a public key, no certificate authority (CA) needed. ``emit`` a json file
+    which embeds the key and domain and publish it. Anyone may then check via
+    ``match`` that the asserted identity is placed at the given domain."""
+    if args.identity_cmd == "emit":
+        _priv, pub = keys.load_signing_key(args.key)
+        pair = {"keyid": keys.keyid_for(pub), "pubkey": pub.hex()}
+        doc = identity.build_wellknown([pair], domain=args.domain)
+        identity.write_wellknown(doc, args.out)
+        print(f"{OK} wrote {args.out}")
+        print("  publish at: https://<your-domain>/.well-known/asexec.json")
+        print(f"  keyid     : {pair['keyid']}")
+        return 0
+    if args.identity_cmd == "match":
+        keyid = args.keyid
+        pubkey = args.pubkey
+        if args.key:
+            _priv, pub = keys.load_signing_key(args.key)
+            keyid = keys.keyid_for(pub)
+        res = identity.match_binding(args.domain, keyid=keyid, pubkey_hex=pubkey)
+        s = OK if res["bound"] else NO
+        print(
+            f"{s} key {'IS' if res['bound'] else 'is NOT'} asserted by {args.domain} "
+            f"({res['listed_count']} key(s) listed)"
+        )
+        print(f"  caveat: {res['caveat']}")
+        return 0 if res["bound"] else 2
+    raise SystemExit("error: use 'identity emit' or 'identity match'")
+
+
+# --------------------------------------------------------------------------- #
+# parser
+# --------------------------------------------------------------------------- #
+def _add_anchor_flags(p):
+    """Time-anchor parsing helper, shared by prereg and postreg."""
+    p.add_argument(
+        "--floor",
+        action="store_true",
+        help="attach a drand freshness floor (proves created no earlier than T; network)",
+    )
+    p.add_argument(
+        "--ceiling",
+        action="store_true",
+        help="attach a Roughtime ceiling witness (proves created no later than T; network)",
+    )
+
+
+def build_parser() -> argparse.ArgumentParser:
+    """``asexec`` parsing core."""
+    p = argparse.ArgumentParser(
+        prog="asexec",
+        description="Pre-registration & notarization primitive for AI evaluations. "
+        "Does NOT prove identity, eval quality, provenance, or cryptographic "
+        "'pre' (see 'verify' output).",
+    )
+    p.add_argument("--version", action="version", version=f"asexec {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    # asexec keygen
+    kg = sub.add_parser("keygen", help="generate an ed25519 keypair (no CA)")
+    kg.add_argument("--out", default=None, help="secret key file (default: asexec-<uuid>.key)")
+    kg.set_defaults(func=cmd_keygen)
+
+    # asexec prereg
+    pr = sub.add_parser("prereg", help="sign a pre-registration before a run")
+    pr.add_argument("--key", required=True, help="key that signs the prereg")
+    pr.add_argument("--target", help="plain-text target details (what you commit to run)")
+    pr.add_argument("--target-file", help="structured JSON target details")
+    pr.add_argument(
+        "--due",
+        help="disclosure deadline, ISO-8601 (optional; e.g. 2026-08-30T00:00:00Z)",
+    )
+    pr.add_argument("--declaration", help="plain-language commitment text")
+    pr.add_argument("--declaration-file", help="structured JSON declaration")
+    pr.add_argument(
+        "--subject",
+        nargs="+",
+        help="path(s) to harness/eval to hash (optional at prereg time)",
+    )
+    pr.add_argument(
+        "--hash-alg",
+        default=hashing.DEFAULT_ALG,
+        choices=hashing.available_algorithms(),
+    )
+    pr.add_argument("--notes", help="free-form context (hypothesis/methodology)")
+    pr.add_argument("--notes-file", help="structured JSON notes")
+    _add_anchor_flags(pr)
+    pr.add_argument("--out", default="preregistration.json")
+    pr.set_defaults(func=cmd_prereg)
+
+    # asexec postreg
+    po = sub.add_parser("postreg", help="sign a post-registration (receipt) after a run")
+    po.add_argument("--key", required=True)
+    po.add_argument(
+        "--fulfills",
+        required=True,
+        help="pre-registration file (or literal ref) this fulfils",
+    )
+    po.add_argument("--target", help="override target (default: inherit from prereg)")
+    po.add_argument("--target-file")
+    po.add_argument("--due", help="override disclosure deadline (default: inherit from prereg)")
+    po.add_argument("--declaration")
+    po.add_argument("--declaration-file")
+    po.add_argument("--subject", nargs="+", help="path(s) to outputs/transcript/harness to hash")
+    po.add_argument("--hash-alg", default=None, choices=hashing.available_algorithms())
+    po.add_argument("--prev", help="prior postreg file (or ref) in this commitment's chain")
+    po.add_argument("--provenance", choices=["asserted", "reproducible"], default="asserted")
+    po.add_argument(
+        "--repro-recipe",
+        help="JSON: {seed, decode, runtime} if provenance=reproducible",
+    )
+    po.add_argument("--notes")
+    po.add_argument("--notes-file")
+    _add_anchor_flags(po)
+    po.add_argument("--out", default="postregistration.json")
+    po.set_defaults(func=cmd_postreg)
+
+    # asexec verify
+    vy = sub.add_parser("verify", help="verify manifests offline; produce a canonical verify code")
+    vy.add_argument("paths", nargs="+", help="manifest file(s) or a directory of them")
+    vy.add_argument(
+        "--tests",
+        required=True,
+        help="comma-separated tests to run (MUST include 'BDR'). "
+        f"available: {', '.join(verifier.TEST_CATALOG)}",
+    )
+    vy.add_argument("--artifacts", help="directory of original artifacts, to check content hashes")
+    vy.set_defaults(func=cmd_verify)
+
+    # asexec identity
+    idp = sub.add_parser("identity", help="key<->domain binding via .well-known (no CA)")
+    isub = idp.add_subparsers(dest="identity_cmd", required=True)
+    ie = isub.add_parser("emit", help="write a .well-known/asexec.json for your key")
+    ie.add_argument("--key", required=True)
+    ie.add_argument("--domain")
+    ie.add_argument("--out", default="asexec.json")
+    ie.set_defaults(func=cmd_identity)
+    iv = isub.add_parser(
+        "match", help="check a key matches that which is asserted by a domain (network)"
+    )
+    iv.add_argument("--domain", required=True)
+    iv.add_argument("--keyid")
+    iv.add_argument("--pubkey")
+    iv.add_argument("--key", help="a key file, to derive the keyid")
+    iv.set_defaults(func=cmd_identity)
+
+    return p
+
+
+def main(argv: list[str] | None = None) -> int:
+    args = build_parser().parse_args(argv)
+    return args.func(args)