keel-verifier 1.0.0__tar.gz

keel_verifier-1.0.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Keel API, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

keel_verifier-1.0.0/PKG-INFO

@@ -0,0 +1,193 @@
+Metadata-Version: 2.4
+Name: keel-verifier
+Version: 1.0.0
+Summary: Independent verifier for Keel governance evidence
+Author: Keel API, Inc.
+License: MIT License
+        
+        Copyright (c) 2026 Keel API, Inc.
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://keelapi.com/verify
+Project-URL: Documentation, https://docs.keelapi.com/11-running-keel-verify
+Project-URL: Repository, https://github.com/keelapi/keel-verifier
+Project-URL: Changelog, https://github.com/keelapi/keel-verifier/releases
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: cryptography>=42
+Dynamic: license-file
+
+# keel-verifier
+
+Independent verifier for Keel governance evidence.
+
+It runs locally, requires no access to Keel, and makes no outbound network calls unless you explicitly ask it to fetch a public key or key manifest URL.
+
+## Quick Start
+
+```bash
+python -m pip install keel-verifier
+keel-verify export --help
+```
+
+From a checkout:
+
+```bash
+python -m pip install -e .
+python -m keel_verifier --help
+```
+
+The v0.2.0 invocation pattern still works:
+
+```bash
+python -m keel_verifier sample/export.json --self-attested
+```
+
+## What It Verifies
+
+`keel-verify export` verifies a signed compliance export in three layers:
+
+1. The export bytes match the signed manifest `content_hash`.
+2. The manifest Ed25519 signature verifies against a trusted key.
+3. Optional Phase C/D checks walk bundled chain entries and verify closure records.
+
+`keel-verify checkpoint` verifies integrity checkpoint JSON artifacts: the `chain_heads` composite hash, the Ed25519 checkpoint signature, and an embedded RFC 3161 timestamp MessageImprint when present.
+
+## Obtaining a Signed Export
+
+Request an audit export from Keel's compliance export API and include chain entries when you want full lifecycle walking:
+
+```bash
+curl -sS -X POST "https://api.keelapi.com/v1/compliance/exports?include_chain_entries=true"   -H "Authorization: Bearer $KEEL_API_KEY"   -H "Content-Type: application/json"   -d '{"project_id":"<project_uuid>","format":"json"}'
+```
+
+Download both artifacts returned by the export workflow:
+
+- the export payload, for example `export.json`
+- the signed manifest, for example `manifest.json`
+
+Then run:
+
+```bash
+keel-verify export export.json manifest.json --walk-events --verify-closure
+```
+
+The flag form used by the internal verifier is also supported:
+
+```bash
+keel-verify export --export-file export.json --manifest manifest.json --walk-events --verify-closure
+```
+
+## Chain Walking
+
+`--walk-events` parses `audit_export_bundle` files with `schema_version=2` and `include_chain_entries=true`.
+
+It groups entries by `chain_scope`, sorts by `sequence_number`, recomputes every `record_hash`, verifies `prev_hash` continuity inside the export window, and fails closed on unknown `chain_format_version` values.
+
+Schema version 1 exports remain backward compatible. They can still be verified at the export-signature layer, but they do not contain chain entries to walk.
+
+## Closure Verification
+
+`--verify-closure` verifies `permit.closed` entries.
+
+For `closure_v1`, it verifies the closure Ed25519 signature and cross-references provider/client response digests against the bundled lifecycle events.
+
+For `closure_v2`, it also verifies `dispatch_request_digest_v1` against the permit's `binding_request_hash`, proving that the dispatch-time request body is the one covered by the closure record.
+
+Closure verification uses public keys with purpose `permit_binding_signing`. Pass a manifest explicitly when needed:
+
+```bash
+keel-verify export export.json manifest.json   --key-manifest permit-binding-keys.json   --walk-events   --verify-closure
+```
+
+The bundled trust root lives at `keel_verifier/data/trust_root.json`. It includes the production export and checkpoint signing keys currently served by `https://api.keelapi.com/v1/compliance/keys`. The production permit-binding endpoint returned 404 on 2026-05-07, so maintainers should refresh the bundled manifest when `https://api.keelapi.com/v1/integrity/permit-binding-public-keys` is live.
+
+## Tampering Matrix
+
+The verifier emits stable `WALK_*` failure codes, including:
+
+- `WALK_RECORD_HASH_MISMATCH`
+- `WALK_PREV_HASH_DISCONTINUITY`
+- `WALK_SEQUENCE_INVERSION`
+- `WALK_UNKNOWN_CHAIN_FORMAT`
+- `WALK_CLOSURE_SIGNATURE_INVALID`
+- `WALK_CLOSURE_DIGEST_MISMATCH`
+- `WALK_CLOSURE_DIGEST_MISSING`
+- `WALK_CLOSURE_DISPATCH_DIGEST_MISMATCH`
+- `WALK_UNKNOWN_CLOSURE_FORMAT`
+
+The authoritative matrix is maintained in the Keel docs: https://docs.keelapi.com/12-tampering-detection-matrix
+
+## Trust Model
+
+There are two useful kinds of verification:
+
+- Self-attested: the file agrees with itself. This proves internal consistency only.
+- Trust-root verified: the artifact verifies against a key you trust, such as the bundled production trust root, a pinned public key, or a manifest fetched and saved out-of-band.
+
+Trust sources, strongest first:
+
+| Mode | Flags | Notes |
+| --- | --- | --- |
+| Pinned key | `--expected-public-key ed25519:...` or `--public-key ed25519:...` | Strongest when obtained out-of-band. |
+| Key manifest | `--key-manifest keys.json` | Supports key rotation and active windows. |
+| Key manifest URL | `--key-manifest-url URL` | Explicit network fetch. |
+| Bundled trust root | none | Default. No phone-home. |
+| Self-attested | `--self-attested` | Development/sample mode only. |
+
+`--public-key-url` is also supported for checkpoint verification against the single live checkpoint public-key endpoint.
+
+## CLI Examples
+
+```bash
+keel-verify export export.json manifest.json
+keel-verify export export.json manifest.json --walk-events
+keel-verify export export.json manifest.json --walk-events --verify-closure
+keel-verify checkpoint checkpoint.json
+python -m keel_verifier sample/export.json --self-attested
+python -m keel_verifier sample/export.json --json --self-attested
+```
+
+Exit code `0` means verified. Exit code `1` means verification failed. Exit code `2` means bad usage.
+
+## Network Behavior
+
+The verifier does not phone home. It reaches the network only when you pass `--public-key-url` or `--key-manifest-url`.
+
+There is no telemetry.
+
+## Library Use
+
+```python
+from keel_verifier import verify, verify_export_walk_events, verify_closure_record
+
+result = verify("sample/export.json", self_attested=True)
+if not result.ok:
+    raise SystemExit(result.error)
+```
+
+## Versioning
+
+v1.0.0 syncs the public verifier with the Phase A/B/C/D internal verifier. v0.2.0 users can keep using `python -m keel_verifier <artifact>`.
+
+## License
+
+MIT. See `LICENSE`.

keel_verifier-1.0.0/README.md

@@ -0,0 +1,156 @@
+# keel-verifier
+
+Independent verifier for Keel governance evidence.
+
+It runs locally, requires no access to Keel, and makes no outbound network calls unless you explicitly ask it to fetch a public key or key manifest URL.
+
+## Quick Start
+
+```bash
+python -m pip install keel-verifier
+keel-verify export --help
+```
+
+From a checkout:
+
+```bash
+python -m pip install -e .
+python -m keel_verifier --help
+```
+
+The v0.2.0 invocation pattern still works:
+
+```bash
+python -m keel_verifier sample/export.json --self-attested
+```
+
+## What It Verifies
+
+`keel-verify export` verifies a signed compliance export in three layers:
+
+1. The export bytes match the signed manifest `content_hash`.
+2. The manifest Ed25519 signature verifies against a trusted key.
+3. Optional Phase C/D checks walk bundled chain entries and verify closure records.
+
+`keel-verify checkpoint` verifies integrity checkpoint JSON artifacts: the `chain_heads` composite hash, the Ed25519 checkpoint signature, and an embedded RFC 3161 timestamp MessageImprint when present.
+
+## Obtaining a Signed Export
+
+Request an audit export from Keel's compliance export API and include chain entries when you want full lifecycle walking:
+
+```bash
+curl -sS -X POST "https://api.keelapi.com/v1/compliance/exports?include_chain_entries=true"   -H "Authorization: Bearer $KEEL_API_KEY"   -H "Content-Type: application/json"   -d '{"project_id":"<project_uuid>","format":"json"}'
+```
+
+Download both artifacts returned by the export workflow:
+
+- the export payload, for example `export.json`
+- the signed manifest, for example `manifest.json`
+
+Then run:
+
+```bash
+keel-verify export export.json manifest.json --walk-events --verify-closure
+```
+
+The flag form used by the internal verifier is also supported:
+
+```bash
+keel-verify export --export-file export.json --manifest manifest.json --walk-events --verify-closure
+```
+
+## Chain Walking
+
+`--walk-events` parses `audit_export_bundle` files with `schema_version=2` and `include_chain_entries=true`.
+
+It groups entries by `chain_scope`, sorts by `sequence_number`, recomputes every `record_hash`, verifies `prev_hash` continuity inside the export window, and fails closed on unknown `chain_format_version` values.
+
+Schema version 1 exports remain backward compatible. They can still be verified at the export-signature layer, but they do not contain chain entries to walk.
+
+## Closure Verification
+
+`--verify-closure` verifies `permit.closed` entries.
+
+For `closure_v1`, it verifies the closure Ed25519 signature and cross-references provider/client response digests against the bundled lifecycle events.
+
+For `closure_v2`, it also verifies `dispatch_request_digest_v1` against the permit's `binding_request_hash`, proving that the dispatch-time request body is the one covered by the closure record.
+
+Closure verification uses public keys with purpose `permit_binding_signing`. Pass a manifest explicitly when needed:
+
+```bash
+keel-verify export export.json manifest.json   --key-manifest permit-binding-keys.json   --walk-events   --verify-closure
+```
+
+The bundled trust root lives at `keel_verifier/data/trust_root.json`. It includes the production export and checkpoint signing keys currently served by `https://api.keelapi.com/v1/compliance/keys`. The production permit-binding endpoint returned 404 on 2026-05-07, so maintainers should refresh the bundled manifest when `https://api.keelapi.com/v1/integrity/permit-binding-public-keys` is live.
+
+## Tampering Matrix
+
+The verifier emits stable `WALK_*` failure codes, including:
+
+- `WALK_RECORD_HASH_MISMATCH`
+- `WALK_PREV_HASH_DISCONTINUITY`
+- `WALK_SEQUENCE_INVERSION`
+- `WALK_UNKNOWN_CHAIN_FORMAT`
+- `WALK_CLOSURE_SIGNATURE_INVALID`
+- `WALK_CLOSURE_DIGEST_MISMATCH`
+- `WALK_CLOSURE_DIGEST_MISSING`
+- `WALK_CLOSURE_DISPATCH_DIGEST_MISMATCH`
+- `WALK_UNKNOWN_CLOSURE_FORMAT`
+
+The authoritative matrix is maintained in the Keel docs: https://docs.keelapi.com/12-tampering-detection-matrix
+
+## Trust Model
+
+There are two useful kinds of verification:
+
+- Self-attested: the file agrees with itself. This proves internal consistency only.
+- Trust-root verified: the artifact verifies against a key you trust, such as the bundled production trust root, a pinned public key, or a manifest fetched and saved out-of-band.
+
+Trust sources, strongest first:
+
+| Mode | Flags | Notes |
+| --- | --- | --- |
+| Pinned key | `--expected-public-key ed25519:...` or `--public-key ed25519:...` | Strongest when obtained out-of-band. |
+| Key manifest | `--key-manifest keys.json` | Supports key rotation and active windows. |
+| Key manifest URL | `--key-manifest-url URL` | Explicit network fetch. |
+| Bundled trust root | none | Default. No phone-home. |
+| Self-attested | `--self-attested` | Development/sample mode only. |
+
+`--public-key-url` is also supported for checkpoint verification against the single live checkpoint public-key endpoint.
+
+## CLI Examples
+
+```bash
+keel-verify export export.json manifest.json
+keel-verify export export.json manifest.json --walk-events
+keel-verify export export.json manifest.json --walk-events --verify-closure
+keel-verify checkpoint checkpoint.json
+python -m keel_verifier sample/export.json --self-attested
+python -m keel_verifier sample/export.json --json --self-attested
+```
+
+Exit code `0` means verified. Exit code `1` means verification failed. Exit code `2` means bad usage.
+
+## Network Behavior
+
+The verifier does not phone home. It reaches the network only when you pass `--public-key-url` or `--key-manifest-url`.
+
+There is no telemetry.
+
+## Library Use
+
+```python
+from keel_verifier import verify, verify_export_walk_events, verify_closure_record
+
+result = verify("sample/export.json", self_attested=True)
+if not result.ok:
+    raise SystemExit(result.error)
+```
+
+## Versioning
+
+v1.0.0 syncs the public verifier with the Phase A/B/C/D internal verifier. v0.2.0 users can keep using `python -m keel_verifier <artifact>`.
+
+## License
+
+MIT. See `LICENSE`.

keel_verifier-1.0.0/keel_verifier/__init__.py

@@ -0,0 +1,21 @@
+"""Standalone verifier for Keel governance evidence."""
+
+from keel_verifier.verifier import (
+    CHAIN_FORMAT_HASHERS,
+    CLOSURE_FORMAT_VERIFIERS,
+    VerifyResult,
+    verify,
+    verify_closure_record,
+    verify_export_walk_events,
+)
+
+__all__ = [
+    "CHAIN_FORMAT_HASHERS",
+    "CLOSURE_FORMAT_VERIFIERS",
+    "VerifyResult",
+    "verify",
+    "verify_closure_record",
+    "verify_export_walk_events",
+    "__version__",
+]
+__version__ = "1.0.0"

keel_verifier-1.0.0/keel_verifier/__main__.py

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

keel_verifier-1.0.0/keel_verifier/cli.py

@@ -0,0 +1,296 @@
+"""Command-line interface for keel_verifier."""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from keel_verifier import __version__
+from keel_verifier.verifier import (
+    KEELAPI_CHECKPOINT_PUBLIC_KEY_URL,
+    KEELAPI_COMPLIANCE_KEYS_URL,
+    VerifyResult,
+    cmd_checkpoint,
+    cmd_export,
+    verify,
+)
+
+LEGACY_COMMANDS = {"export", "checkpoint"}
+
+
+def _public_key_alias(args: argparse.Namespace) -> None:
+    if getattr(args, "public_key", None) and getattr(args, "expected_public_key", None):
+        raise argparse.ArgumentTypeError(
+            "--public-key and --expected-public-key are aliases; pass only one"
+        )
+    if getattr(args, "expected_public_key", None) is None:
+        args.expected_public_key = getattr(args, "public_key", None)
+
+
+def _trust_flag_count(args: argparse.Namespace, *, include_public_key_url: bool) -> int:
+    values = [
+        getattr(args, "expected_public_key", None),
+        getattr(args, "key_manifest", None),
+        getattr(args, "key_manifest_url", None),
+        getattr(args, "self_attested", False),
+    ]
+    if include_public_key_url:
+        values.append(getattr(args, "public_key_url", None))
+    return sum(bool(value) for value in values)
+
+
+def _add_key_manifest_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument(
+        "--key-manifest",
+        help=(
+            "Local path to a Keel public key manifest JSON file. Defaults to "
+            "the bundled production trust root when no trust override is passed."
+        ),
+    )
+    p.add_argument(
+        "--key-manifest-url",
+        help=f"URL to fetch the key manifest from (canonical: {KEELAPI_COMPLIANCE_KEYS_URL}).",
+    )
+
+
+def _add_common_trust_args(p: argparse.ArgumentParser) -> None:
+    p.add_argument(
+        "--expected-public-key",
+        help="ed25519:<base64> public key the artifact must be signed with.",
+    )
+    p.add_argument(
+        "--public-key",
+        help="Alias for --expected-public-key, preserved for v0.2.0 users.",
+    )
+    p.add_argument(
+        "--self-attested",
+        action="store_true",
+        help=(
+            "Verify against the artifact's embedded public_key. This only proves "
+            "internal consistency; it does not prove Keel signed the artifact."
+        ),
+    )
+    p.add_argument(
+        "--offline",
+        action="store_true",
+        help=argparse.SUPPRESS,
+    )
+
+
+def _cmd_export_cli(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int:
+    try:
+        _public_key_alias(args)
+    except argparse.ArgumentTypeError as exc:
+        parser.error(str(exc))
+    args.export_file = args.export_file_flag or args.export_file_pos
+    args.manifest = args.manifest_flag or args.manifest_pos
+    if not args.export_file:
+        parser.error("export requires EXPORT_FILE or --export-file")
+    if not args.manifest:
+        parser.error("export requires MANIFEST or --manifest")
+    if _trust_flag_count(args, include_public_key_url=False) > 1:
+        parser.error(
+            "--expected-public-key/--public-key, --key-manifest, "
+            "--key-manifest-url, and --self-attested are mutually exclusive"
+        )
+    return cmd_export(args)
+
+
+def _cmd_checkpoint_cli(parser: argparse.ArgumentParser, args: argparse.Namespace) -> int:
+    try:
+        _public_key_alias(args)
+    except argparse.ArgumentTypeError as exc:
+        parser.error(str(exc))
+    args.checkpoint_file = args.checkpoint_file_flag or args.checkpoint_file_pos
+    if not args.checkpoint_file:
+        parser.error("checkpoint requires CHECKPOINT_FILE or --checkpoint-file")
+    if _trust_flag_count(args, include_public_key_url=True) > 1:
+        parser.error(
+            "--expected-public-key/--public-key, --public-key-url, --key-manifest, "
+            "--key-manifest-url, and --self-attested are mutually exclusive"
+        )
+    return cmd_checkpoint(args)
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="keel-verify",
+        description="Standalone verifier for Keel trust artifacts.",
+        epilog=(
+            "New export verification supports --walk-events and --verify-closure. "
+            "Backward compatible usage remains: python -m keel_verifier <checkpoint.json>."
+        ),
+    )
+    parser.add_argument("--version", action="version", version=f"keel_verifier {__version__}")
+    sub = parser.add_subparsers(dest="cmd")
+
+    p_export = sub.add_parser("export", help="Verify a signed compliance export.")
+    p_export.add_argument("export_file_pos", nargs="?", metavar="EXPORT_FILE")
+    p_export.add_argument("manifest_pos", nargs="?", metavar="MANIFEST")
+    p_export.add_argument("--export-file", dest="export_file_flag")
+    p_export.add_argument("--manifest", dest="manifest_flag")
+    p_export.add_argument(
+        "--walk-events",
+        action="store_true",
+        help=(
+            "After export content hash and signature verification, parse an "
+            "audit export bundle and walk bundled chain_entries."
+        ),
+    )
+    p_export.add_argument(
+        "--verify-closure",
+        action="store_true",
+        help=(
+            "After export content hash and signature verification, verify "
+            "permit.closed closure signatures and dispatch/provider/client digest "
+            "consistency from bundled chain_entries."
+        ),
+    )
+    _add_common_trust_args(p_export)
+    _add_key_manifest_args(p_export)
+    p_export.set_defaults(func=lambda args: _cmd_export_cli(p_export, args))
+
+    p_cp = sub.add_parser("checkpoint", help="Verify an integrity checkpoint JSON file.")
+    p_cp.add_argument("checkpoint_file_pos", nargs="?", metavar="CHECKPOINT_FILE")
+    p_cp.add_argument("--checkpoint-file", dest="checkpoint_file_flag")
+    _add_common_trust_args(p_cp)
+    p_cp.add_argument(
+        "--public-key-url",
+        help=(
+            "URL to fetch the single checkpoint public key "
+            f"(canonical: {KEELAPI_CHECKPOINT_PUBLIC_KEY_URL})."
+        ),
+    )
+    _add_key_manifest_args(p_cp)
+    p_cp.add_argument(
+        "--tsa-ca-bundle",
+        help="Optional CA bundle for TSA trust-chain validation (note only).",
+    )
+    p_cp.set_defaults(func=lambda args: _cmd_checkpoint_cli(p_cp, args))
+    return parser
+
+
+def _build_legacy_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="python -m keel_verifier",
+        description=(
+            "Backward-compatible v0.2.0 checkpoint verifier. For signed "
+            "compliance exports, use: keel-verify export --help."
+        ),
+    )
+    parser.add_argument("export_file", help="Path to a sealed Keel checkpoint/export JSON file.")
+    parser.add_argument("--json", action="store_true", dest="as_json")
+    parser.add_argument("--no-tsa", action="store_true", help="Skip RFC 3161 TSA receipt verification.")
+    parser.add_argument("--public-key", metavar="ed25519:BASE64")
+    parser.add_argument(
+        "--public-key-url",
+        metavar="URL",
+        help=f"Fetch the trust-root public key from this URL (canonical: {KEELAPI_CHECKPOINT_PUBLIC_KEY_URL}).",
+    )
+    parser.add_argument(
+        "--self-attested",
+        action="store_true",
+        dest="self_attested",
+        help=(
+            "Verify against the artifact's own embedded public_key. This only "
+            "proves internal consistency; it does not prove Keel signed it."
+        ),
+    )
+    parser.add_argument("--offline", action="store_true", help=argparse.SUPPRESS)
+    parser.add_argument("--version", action="version", version=f"keel_verifier {__version__}")
+    return parser
+
+
+def _print_human(result: VerifyResult, export_path: str, stream) -> None:
+    p = lambda s="": print(s, file=stream)
+
+    if result.ok:
+        p(f"VERIFIED: {export_path}")
+    else:
+        p(f"FAILED: {export_path}")
+        if result.error:
+            for line in result.error.splitlines():
+                p(f"  {line}")
+
+    if result.checkpoint_id:
+        p(f"  Checkpoint:    {result.checkpoint_id}")
+    if result.computed_at:
+        p(f"  Computed at:   {result.computed_at}")
+    if result.composite_hash:
+        p(f"  Composite:     {result.composite_hash}")
+    if result.chain_heads_count:
+        p(f"  Chain heads:   {result.chain_heads_count} scope(s)")
+    if result.public_key:
+        p(f"  Public key:    {result.public_key}")
+    if result.key_id:
+        p(f"  Key id:        {result.key_id}")
+    if result.trust_source:
+        p(f"  Trust source:  {result.trust_source}")
+
+    if result.tsa_present:
+        if not result.tsa_checked:
+            p("  TSA:           present (skipped — --no-tsa)")
+        elif result.tsa_verified:
+            p(f"  TSA:           verified ({result.tsa_reason})")
+            if result.tsa_url:
+                p(f"    url:         {result.tsa_url}")
+            if result.tsa_requested_at:
+                p(f"    stamped at:  {result.tsa_requested_at}")
+        else:
+            p(f"  TSA:           FAILED ({result.tsa_reason})")
+    else:
+        p("  TSA:           not present")
+
+    if result.ok and result.self_attested:
+        p()
+        p("WARNING: --self-attested verification only proves internal consistency.")
+        p("It does not prove that Keel signed this artifact. Drop --self-attested to")
+        p("verify against the bundled trust root, or pin explicitly with:")
+        p(f"  --public-key-url {KEELAPI_CHECKPOINT_PUBLIC_KEY_URL}")
+
+
+def _main_legacy(argv: list[str]) -> int:
+    parser = _build_legacy_parser()
+    args = parser.parse_args(argv)
+    flags = (args.public_key, args.public_key_url, args.self_attested)
+    if sum(bool(x) for x in flags) > 1:
+        print(
+            "ERROR: --public-key, --public-key-url, and --self-attested are mutually exclusive.",
+            file=sys.stderr,
+        )
+        return 2
+
+    result = verify(
+        args.export_file,
+        public_key=args.public_key,
+        public_key_url=args.public_key_url,
+        self_attested=args.self_attested,
+        check_tsa=not args.no_tsa,
+    )
+
+    if args.as_json:
+        print(json.dumps(result.to_dict(), indent=2, sort_keys=True))
+        if not result.ok and result.error:
+            print(result.error, file=sys.stderr)
+    else:
+        stream = sys.stdout if result.ok else sys.stderr
+        _print_human(result, args.export_file, stream)
+    return 0 if result.ok else 1
+
+
+def main(argv: list[str] | None = None) -> int:
+    raw = list(sys.argv[1:] if argv is None else argv)
+    if raw and raw[0] not in LEGACY_COMMANDS and raw[0] not in {"-h", "--help", "--version"}:
+        return _main_legacy(raw)
+
+    parser = _build_parser()
+    args = parser.parse_args(raw)
+    if not hasattr(args, "func"):
+        parser.print_help()
+        return 0
+    return args.func(args)
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())