trustchain-verify 0.1.0__tar.gz

trustchain_verify-0.1.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: trustchain-verify
+Version: 0.1.0
+Summary: Open-source CLI verifier for Arkava Trust Chain witness manifests
+Author: Arkava Ltd
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/Arkava-Ai/arkava-trustchain
+Project-URL: Source, https://github.com/Arkava-Ai/arkava-trustchain
+Project-URL: Documentation, https://github.com/Arkava-Ai/arkava-trustchain/blob/develop/docs/TRUSTCHAIN_VERIFY_CLI.md
+Keywords: arkava,trust-chain,audit,sovereign-ai,verifier
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1
+Requires-Dist: trustchain-core
+Requires-Dist: requests>=2.31
+
+# trustchain-verify
+
+Open-source CLI verifier for Arkava® Trust Chain witness manifests.
+
+## Installation
+
+```bash
+pip install trustchain-verify
+```
+
+Requires Python 3.11+.
+
+## Quick Start
+
+```bash
+# Verify a local manifest file
+trustchain-verify verify-manifest manifest.json
+
+# Verify a remote manifest
+trustchain-verify verify-manifest https://raw.githubusercontent.com/Arkava-Ai/arkava-trustchain/main/witness-history/2026/06/26/manifest_2026-06-26.json
+
+# Batch-verify multiple manifests
+trustchain-verify verify-batch manifest_1.json manifest_2.json
+
+# Validate schema only (no signature check)
+trustchain-verify validate-schema manifest.json
+
+# List published operator public keys
+trustchain-verify list-keys
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Verification succeeded |
+| 1 | Schema validation error |
+| 2 | Signature verification error |
+| 3 | Usage error |
+
+## Documentation
+
+- CLI reference: [`docs/TRUSTCHAIN_VERIFY_CLI.md`](https://github.com/Arkava-Ai/arkava-trustchain/blob/develop/docs/TRUSTCHAIN_VERIFY_CLI.md)
+- Architecture: [`docs/Arkava_TrustChain_Technical_Architecture_v0.2.md`](https://github.com/Arkava-Ai/arkava-trustchain/blob/develop/docs/Arkava_TrustChain_Technical_Architecture_v0.2.md) §2.9
+- ADR: [TC-ADR-0011](https://github.com/Arkava-Ai/arkava-trustchain/blob/develop/docs/adr/TC-ADR-0011-api-and-verification.md)
+
+## Licence
+
+Apache-2.0. Arkava® Trust Chain is a registered trademark of Arkava Ltd.
+
+© 2026 Arkava® / All rights reserved.

trustchain_verify-0.1.0/README.md

@@ -0,0 +1,51 @@
+# trustchain-verify
+
+Open-source CLI verifier for Arkava® Trust Chain witness manifests.
+
+## Installation
+
+```bash
+pip install trustchain-verify
+```
+
+Requires Python 3.11+.
+
+## Quick Start
+
+```bash
+# Verify a local manifest file
+trustchain-verify verify-manifest manifest.json
+
+# Verify a remote manifest
+trustchain-verify verify-manifest https://raw.githubusercontent.com/Arkava-Ai/arkava-trustchain/main/witness-history/2026/06/26/manifest_2026-06-26.json
+
+# Batch-verify multiple manifests
+trustchain-verify verify-batch manifest_1.json manifest_2.json
+
+# Validate schema only (no signature check)
+trustchain-verify validate-schema manifest.json
+
+# List published operator public keys
+trustchain-verify list-keys
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Verification succeeded |
+| 1 | Schema validation error |
+| 2 | Signature verification error |
+| 3 | Usage error |
+
+## Documentation
+
+- CLI reference: [`docs/TRUSTCHAIN_VERIFY_CLI.md`](https://github.com/Arkava-Ai/arkava-trustchain/blob/develop/docs/TRUSTCHAIN_VERIFY_CLI.md)
+- Architecture: [`docs/Arkava_TrustChain_Technical_Architecture_v0.2.md`](https://github.com/Arkava-Ai/arkava-trustchain/blob/develop/docs/Arkava_TrustChain_Technical_Architecture_v0.2.md) §2.9
+- ADR: [TC-ADR-0011](https://github.com/Arkava-Ai/arkava-trustchain/blob/develop/docs/adr/TC-ADR-0011-api-and-verification.md)
+
+## Licence
+
+Apache-2.0. Arkava® Trust Chain is a registered trademark of Arkava Ltd.
+
+© 2026 Arkava® / All rights reserved.

trustchain_verify-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[project]
+name = "trustchain-verify"
+version = "0.1.0"
+description = "Open-source CLI verifier for Arkava Trust Chain witness manifests"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "Apache-2.0" }
+authors = [{ name = "Arkava Ltd" }]
+keywords = ["arkava", "trust-chain", "audit", "sovereign-ai", "verifier"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Environment :: Console",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Information Technology",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Security :: Cryptography",
+    "Topic :: System :: Systems Administration",
+]
+dependencies = [
+    "click>=8.1",
+    "trustchain-core",
+    "requests>=2.31",
+]
+
+[project.urls]
+Homepage = "https://github.com/Arkava-Ai/arkava-trustchain"
+Source = "https://github.com/Arkava-Ai/arkava-trustchain"
+Documentation = "https://github.com/Arkava-Ai/arkava-trustchain/blob/develop/docs/TRUSTCHAIN_VERIFY_CLI.md"
+
+[project.scripts]
+trustchain-verify = "trustchain_verify.cli:main"
+
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+include = ["trustchain_verify*"]

trustchain_verify-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

trustchain_verify-0.1.0/src/trustchain_verify/cli.py

@@ -0,0 +1,210 @@
+"""trustchain-verify CLI — open-source manifest verifier (ARK-3560, TC-ADR-0011).
+
+Commands:
+    verify-manifest <path-or-url>  Verify a single manifest (schema + Ed25519 signature)
+    verify-batch <path1> <path2>… Batch-verify multiple manifests
+    validate-schema <path>        Validate manifest against JSON Schema only
+    list-keys                     List published operator public keys
+    list-manifests <dir>          List manifest files in a witness-history directory
+
+Exit codes:
+    0 — success (all verifications passed)
+    1 — schema validation error
+    2 — signature verification error
+    3 — usage error (bad arguments, file not found, network error)
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import tempfile
+from pathlib import Path
+from typing import Any
+
+import click
+
+from trustchain_core.witness import (
+    PublicKeyStore,
+    VerificationResult,
+    verify_manifest_file,
+    verify_manifest_schema,
+)
+
+
+def _fetch_remote(url: str) -> str:
+    """Download a manifest from a URL to a temp file and return its path."""
+    import requests
+
+    try:
+        resp = requests.get(url, timeout=30, allow_redirects=True)
+        resp.raise_for_status()
+    except requests.RequestException as exc:
+        click.echo(json.dumps({"error": f"Failed to fetch {url}: {exc}", "valid": False}))
+        sys.exit(3)
+
+    tmp = tempfile.NamedTemporaryFile(mode="w", suffix=".json", delete=False)
+    tmp.write(resp.text)
+    tmp.close()
+    return tmp.name
+
+
+def _result_to_json(result: VerificationResult, source: str) -> dict[str, Any]:
+    """Convert a VerificationResult to a JSON-serialisable dict."""
+    output: dict[str, Any] = {
+        "source": source,
+        "valid": result.valid,
+        "schema_valid": result.schema_valid,
+        "signature_valid": result.signature_valid,
+        "errors": result.errors,
+    }
+    if result.manifest is not None:
+        output["manifest"] = result.manifest.to_dict()
+    return output
+
+
+@click.group()
+@click.version_option(version="0.1.0")
+def cli() -> None:
+    """Arkava Trust Chain — open-source manifest verifier."""
+
+
+@cli.command("verify-manifest")
+@click.argument("source")
+@click.option("--keys", default=None, help="Path to operator public keys JSON file")
+def verify_manifest(source: str, keys: str | None) -> None:
+    """Verify a single manifest (schema + Ed25519 signature).
+
+    SOURCE is a local file path or a URL (http/https).
+    """
+    key_store = PublicKeyStore.from_file(keys) if keys else PublicKeyStore.from_default()
+
+    if source.startswith("http://") or source.startswith("https://"):
+        local_path = _fetch_remote(source)
+    else:
+        local_path = source
+
+    if not Path(local_path).exists():
+        click.echo(json.dumps({"error": f"File not found: {source}", "valid": False}))
+        sys.exit(3)
+
+    result = verify_manifest_file(local_path, key_store)
+    output = _result_to_json(result, source)
+    click.echo(json.dumps(output, indent=2, sort_keys=True))
+
+    if not result.schema_valid:
+        sys.exit(1)
+    if result.signature_valid is False:
+        sys.exit(2)
+    if not result.valid:
+        sys.exit(3)
+    sys.exit(0)
+
+
+@cli.command("verify-batch")
+@click.argument("sources", nargs=-1, required=True)
+@click.option("--keys", default=None, help="Path to operator public keys JSON file")
+def verify_batch(sources: tuple[str, ...], keys: str | None) -> None:
+    """Batch-verify multiple manifests.
+
+    Each SOURCE is a local file path or URL. Exits 0 only if ALL pass.
+    """
+    key_store = PublicKeyStore.from_file(keys) if keys else PublicKeyStore.from_default()
+
+    results: list[dict[str, Any]] = []
+    all_valid = True
+    has_schema_error = False
+    has_sig_error = False
+
+    for source in sources:
+        if source.startswith("http://") or source.startswith("https://"):
+            local_path = _fetch_remote(source)
+        else:
+            local_path = source
+
+        result = verify_manifest_file(local_path, key_store)
+        entry = _result_to_json(result, source)
+        results.append(entry)
+
+        if not result.valid:
+            all_valid = False
+        if not result.schema_valid:
+            has_schema_error = True
+        if result.signature_valid is False:
+            has_sig_error = True
+
+    batch_output: dict[str, Any] = {
+        "total": len(sources),
+        "valid": sum(1 for r in results if r["valid"]),
+        "invalid": sum(1 for r in results if not r["valid"]),
+        "results": results,
+    }
+    click.echo(json.dumps(batch_output, indent=2, sort_keys=True))
+
+    if has_schema_error:
+        sys.exit(1)
+    if has_sig_error:
+        sys.exit(2)
+    if not all_valid:
+        sys.exit(3)
+    sys.exit(0)
+
+
+@cli.command("validate-schema")
+@click.argument("path")
+def validate_schema(path: str) -> None:
+    """Validate a manifest file against the v1 JSON Schema only (no signature check)."""
+    file_path = Path(path)
+    if not file_path.exists():
+        click.echo(json.dumps({"error": f"File not found: {path}", "valid": False}))
+        sys.exit(3)
+
+    try:
+        with open(file_path, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    except json.JSONDecodeError as exc:
+        click.echo(json.dumps({"error": f"JSON parse error: {exc}", "valid": False}))
+        sys.exit(3)
+
+    valid = verify_manifest_schema(data)
+    click.echo(json.dumps({"path": path, "schema_valid": valid}, indent=2, sort_keys=True))
+    sys.exit(0 if valid else 1)
+
+
+@cli.command("list-keys")
+@click.option("--keys", default=None, help="Path to operator public keys JSON file")
+def list_keys(keys: str | None) -> None:
+    """List published operator public keys."""
+    key_store = PublicKeyStore.from_file(keys) if keys else PublicKeyStore.from_default()
+    dids = key_store.list_dids()
+    output: list[dict[str, str]] = []
+    for did in dids:
+        pk = key_store.lookup(did)
+        if pk:
+            output.append({"participant_did": did, "public_key_hex": pk})
+    click.echo(json.dumps({"keys": output}, indent=2, sort_keys=True))
+    sys.exit(0)
+
+
+@cli.command("list-manifests")
+@click.argument("directory")
+def list_manifests(directory: str) -> None:
+    """List manifest files in a witness-history directory."""
+    dir_path = Path(directory)
+    if not dir_path.exists():
+        click.echo(json.dumps({"error": f"Directory not found: {directory}"}))
+        sys.exit(3)
+
+    manifests = sorted(dir_path.rglob("manifest_*.json"))
+    output = [{"path": str(m.relative_to(dir_path))} for m in manifests]
+    click.echo(json.dumps({"directory": directory, "manifests": output}, indent=2, sort_keys=True))
+    sys.exit(0)
+
+
+def main() -> None:
+    """Entry point for the trustchain-verify CLI."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

trustchain_verify-0.1.0/src/trustchain_verify.egg-info/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.4
+Name: trustchain-verify
+Version: 0.1.0
+Summary: Open-source CLI verifier for Arkava Trust Chain witness manifests
+Author: Arkava Ltd
+License: Apache-2.0
+Project-URL: Homepage, https://github.com/Arkava-Ai/arkava-trustchain
+Project-URL: Source, https://github.com/Arkava-Ai/arkava-trustchain
+Project-URL: Documentation, https://github.com/Arkava-Ai/arkava-trustchain/blob/develop/docs/TRUSTCHAIN_VERIFY_CLI.md
+Keywords: arkava,trust-chain,audit,sovereign-ai,verifier
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Information Technology
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Security :: Cryptography
+Classifier: Topic :: System :: Systems Administration
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+Requires-Dist: click>=8.1
+Requires-Dist: trustchain-core
+Requires-Dist: requests>=2.31
+
+# trustchain-verify
+
+Open-source CLI verifier for Arkava® Trust Chain witness manifests.
+
+## Installation
+
+```bash
+pip install trustchain-verify
+```
+
+Requires Python 3.11+.
+
+## Quick Start
+
+```bash
+# Verify a local manifest file
+trustchain-verify verify-manifest manifest.json
+
+# Verify a remote manifest
+trustchain-verify verify-manifest https://raw.githubusercontent.com/Arkava-Ai/arkava-trustchain/main/witness-history/2026/06/26/manifest_2026-06-26.json
+
+# Batch-verify multiple manifests
+trustchain-verify verify-batch manifest_1.json manifest_2.json
+
+# Validate schema only (no signature check)
+trustchain-verify validate-schema manifest.json
+
+# List published operator public keys
+trustchain-verify list-keys
+```
+
+## Exit Codes
+
+| Code | Meaning |
+|---|---|
+| 0 | Verification succeeded |
+| 1 | Schema validation error |
+| 2 | Signature verification error |
+| 3 | Usage error |
+
+## Documentation
+
+- CLI reference: [`docs/TRUSTCHAIN_VERIFY_CLI.md`](https://github.com/Arkava-Ai/arkava-trustchain/blob/develop/docs/TRUSTCHAIN_VERIFY_CLI.md)
+- Architecture: [`docs/Arkava_TrustChain_Technical_Architecture_v0.2.md`](https://github.com/Arkava-Ai/arkava-trustchain/blob/develop/docs/Arkava_TrustChain_Technical_Architecture_v0.2.md) §2.9
+- ADR: [TC-ADR-0011](https://github.com/Arkava-Ai/arkava-trustchain/blob/develop/docs/adr/TC-ADR-0011-api-and-verification.md)
+
+## Licence
+
+Apache-2.0. Arkava® Trust Chain is a registered trademark of Arkava Ltd.
+
+© 2026 Arkava® / All rights reserved.

trustchain_verify-0.1.0/src/trustchain_verify.egg-info/SOURCES.txt

@@ -0,0 +1,11 @@
+README.md
+pyproject.toml
+src/trustchain_verify/__init__.py
+src/trustchain_verify/cli.py
+src/trustchain_verify.egg-info/PKG-INFO
+src/trustchain_verify.egg-info/SOURCES.txt
+src/trustchain_verify.egg-info/dependency_links.txt
+src/trustchain_verify.egg-info/entry_points.txt
+src/trustchain_verify.egg-info/requires.txt
+src/trustchain_verify.egg-info/top_level.txt
+tests/test_cli.py

trustchain_verify-0.1.0/src/trustchain_verify.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

trustchain_verify-0.1.0/src/trustchain_verify.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+trustchain-verify = trustchain_verify.cli:main

trustchain_verify-0.1.0/src/trustchain_verify.egg-info/requires.txt

@@ -0,0 +1,3 @@
+click>=8.1
+trustchain-core
+requests>=2.31

trustchain_verify-0.1.0/src/trustchain_verify.egg-info/top_level.txt

@@ -0,0 +1 @@
+trustchain_verify

trustchain_verify-0.1.0/tests/test_cli.py

@@ -0,0 +1,377 @@
+"""trustchain-verify CLI tests (ARK-3560 AC 7-10).
+
+Acceptance criteria:
+    AC7:  CLI verify-manifest <path-or-url> — verifies local + remote
+    AC8:  CLI exit codes: 0=success, 1=schema error, 2=signature error, 3=usage error
+    AC9:  CLI batch verification: verify-batch <path1> <path2> ...
+    AC10: CLI help text comprehensive with examples
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from pathlib import Path
+from typing import Any
+
+from click.testing import CliRunner
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PrivateKey
+from cryptography.hazmat.primitives.serialization import (
+    Encoding,
+    NoEncryption,
+    PrivateFormat,
+    PublicFormat,
+)
+
+from trustchain_core.witness import Manifest
+from trustchain_core.witness.canonical_encoding import ALGORITHM_ID_SHA3_512
+from trustchain_core.witness.verifier import _reconstruct_signed_data
+from trustchain_verify.cli import cli
+
+_TEST_DID = "did:arkava:log-test"
+
+
+def _extract_json(output: str) -> Any:
+    lines = output.strip().split("\n")
+    for i in range(len(lines) - 1, -1, -1):
+        if lines[i].strip().startswith("{"):
+            candidate = "\n".join(lines[i:])
+            try:
+                return json.loads(candidate)
+            except json.JSONDecodeError:
+                continue
+    return json.loads(lines[-1])
+
+
+def _make_keypair() -> tuple[bytes, bytes]:
+    private_key = Ed25519PrivateKey.generate()
+    seed = private_key.private_bytes(
+        encoding=Encoding.Raw,
+        format=PrivateFormat.Raw,
+        encryption_algorithm=NoEncryption(),
+    )
+    public = private_key.public_key().public_bytes(encoding=Encoding.Raw, format=PublicFormat.Raw)
+    return seed, public
+
+
+def _sha3_512_root(seed: str = "test") -> str:
+    return hashlib.sha3_512(seed.encode()).hexdigest()
+
+
+def _sign_manifest(manifest: Manifest, tree_height: int, seed: bytes) -> bytes:
+    root_hash_bytes = bytes.fromhex(manifest.merkle_root)
+    signed_data = _reconstruct_signed_data(
+        tree_height,
+        manifest.participant_did,
+        manifest.timestamp,
+        root_hash_bytes,
+    )
+    key = Ed25519PrivateKey.from_private_bytes(seed)
+    return key.sign(signed_data)
+
+
+def _make_signed_manifest_dict(
+    public_key_hex: str, seed: bytes, tree_height: int = 2
+) -> dict[str, Any]:
+    root = _sha3_512_root("cli-test-root")
+    timestamp = "2026-06-26T12:00:00Z"
+    manifest = Manifest(
+        timestamp=timestamp,
+        merkle_root=root,
+        participant_did=_TEST_DID,
+        batch_count=5,
+        stump_proof_path=[],
+        algorithm_id=ALGORITHM_ID_SHA3_512,
+        key_version="v1",
+        tree_height=tree_height,
+    )
+    signature = _sign_manifest(manifest, tree_height, seed)
+    return {
+        "manifest_version": "v1",
+        "timestamp": timestamp,
+        "merkle_root": root,
+        "participant_did": _TEST_DID,
+        "batch_count": 5,
+        "stump_proof_path": [],
+        "algorithm_id": ALGORITHM_ID_SHA3_512,
+        "key_version": "v1",
+        "signature_hex": signature.hex(),
+        "tree_height": tree_height,
+    }
+
+
+def _make_key_file(tmp_path: Path, public_key_hex: str, did: str = _TEST_DID) -> Path:
+    key_file = tmp_path / "keys.json"
+    key_file.write_text(
+        json.dumps(
+            {
+                "keys": [
+                    {"participant_did": did, "key_version": "v1", "public_key_hex": public_key_hex}
+                ]
+            }
+        ),
+        encoding="utf-8",
+    )
+    return key_file
+
+
+def _write_manifest(
+    tmp_path: Path, manifest_dict: dict[str, Any], name: str = "manifest.json"
+) -> Path:
+    p = tmp_path / name
+    p.write_text(json.dumps(manifest_dict, sort_keys=True), encoding="utf-8")
+    return p
+
+
+class TestAC7VerifyManifest:
+    """AC7: CLI verify-manifest <path-or-url> — verifies local + remote."""
+
+    def test_verify_valid_local_manifest_exit_0(self, tmp_path: Path) -> None:
+        seed, public = _make_keypair()
+        manifest_dict = _make_signed_manifest_dict(public.hex(), seed)
+        manifest_path = _write_manifest(tmp_path, manifest_dict)
+        key_file = _make_key_file(tmp_path, public.hex())
+
+        runner = CliRunner()
+        result = runner.invoke(
+            cli, ["verify-manifest", str(manifest_path), "--keys", str(key_file)]
+        )
+
+        assert result.exit_code == 0
+        output = _extract_json(result.output)
+        assert output["valid"] is True
+        assert output["schema_valid"] is True
+        assert output["signature_valid"] is True
+
+    def test_verify_schema_invalid_manifest_exit_1(self, tmp_path: Path) -> None:
+        bad_data: dict[str, Any] = {
+            "manifest_version": "v1",
+            "timestamp": "2026-06-26T12:00:00Z",
+            "merkle_root": _sha3_512_root(),
+            "participant_did": "",
+            "batch_count": 1,
+            "stump_proof_path": [],
+            "algorithm_id": ALGORITHM_ID_SHA3_512,
+            "key_version": "v1",
+        }
+        manifest_path = _write_manifest(tmp_path, bad_data, "bad.json")
+        key_file = _make_key_file(tmp_path, "a" * 64)
+
+        runner = CliRunner()
+        result = runner.invoke(
+            cli, ["verify-manifest", str(manifest_path), "--keys", str(key_file)]
+        )
+
+        assert result.exit_code == 1
+
+    def test_verify_tampered_signature_exit_2(self, tmp_path: Path) -> None:
+        seed, public = _make_keypair()
+        manifest_dict = _make_signed_manifest_dict(public.hex(), seed)
+        manifest_dict["merkle_root"] = _sha3_512_root("tampered")
+        manifest_path = _write_manifest(tmp_path, manifest_dict, "tampered.json")
+        key_file = _make_key_file(tmp_path, public.hex())
+
+        runner = CliRunner()
+        result = runner.invoke(
+            cli, ["verify-manifest", str(manifest_path), "--keys", str(key_file)]
+        )
+
+        assert result.exit_code == 2
+
+    def test_verify_nonexistent_file_exit_3(self, tmp_path: Path) -> None:
+        key_file = _make_key_file(tmp_path, "a" * 64)
+
+        runner = CliRunner()
+        result = runner.invoke(
+            cli, ["verify-manifest", str(tmp_path / "nope.json"), "--keys", str(key_file)]
+        )
+
+        assert result.exit_code == 3
+
+
+class TestAC8ExitCodes:
+    """AC8: CLI exit codes: 0=success, 1=schema error, 2=signature error, 3=usage error."""
+
+    def test_exit_0_on_valid_manifest(self, tmp_path: Path) -> None:
+        seed, public = _make_keypair()
+        manifest_dict = _make_signed_manifest_dict(public.hex(), seed)
+        manifest_path = _write_manifest(tmp_path, manifest_dict)
+        key_file = _make_key_file(tmp_path, public.hex())
+
+        runner = CliRunner()
+        result = runner.invoke(
+            cli, ["verify-manifest", str(manifest_path), "--keys", str(key_file)]
+        )
+        assert result.exit_code == 0
+
+    def test_exit_1_on_schema_error(self, tmp_path: Path) -> None:
+        bad_data: dict[str, Any] = {"not": "valid"}
+        manifest_path = _write_manifest(tmp_path, bad_data, "bad.json")
+        key_file = _make_key_file(tmp_path, "a" * 64)
+
+        runner = CliRunner()
+        result = runner.invoke(
+            cli, ["verify-manifest", str(manifest_path), "--keys", str(key_file)]
+        )
+        assert result.exit_code == 1
+
+    def test_exit_2_on_signature_error(self, tmp_path: Path) -> None:
+        seed, public = _make_keypair()
+        manifest_dict = _make_signed_manifest_dict(public.hex(), seed)
+        manifest_dict["signature_hex"] = "00" * 64
+        manifest_path = _write_manifest(tmp_path, manifest_dict, "badsig.json")
+        key_file = _make_key_file(tmp_path, public.hex())
+
+        runner = CliRunner()
+        result = runner.invoke(
+            cli, ["verify-manifest", str(manifest_path), "--keys", str(key_file)]
+        )
+        assert result.exit_code == 2
+
+    def test_exit_3_on_missing_file(self, tmp_path: Path) -> None:
+        key_file = _make_key_file(tmp_path, "a" * 64)
+
+        runner = CliRunner()
+        result = runner.invoke(
+            cli, ["verify-manifest", "/nonexistent/path.json", "--keys", str(key_file)]
+        )
+        assert result.exit_code == 3
+
+
+class TestAC9BatchVerification:
+    """AC9: CLI batch verification: verify-batch <path1> <path2> ..."""
+
+    def test_batch_all_valid_exit_0(self, tmp_path: Path) -> None:
+        seed, public = _make_keypair()
+        m1 = _make_signed_manifest_dict(public.hex(), seed, tree_height=1)
+        m2 = _make_signed_manifest_dict(public.hex(), seed, tree_height=2)
+        p1 = _write_manifest(tmp_path, m1, "m1.json")
+        p2 = _write_manifest(tmp_path, m2, "m2.json")
+        key_file = _make_key_file(tmp_path, public.hex())
+
+        runner = CliRunner()
+        result = runner.invoke(cli, ["verify-batch", str(p1), str(p2), "--keys", str(key_file)])
+
+        assert result.exit_code == 0
+        output = _extract_json(result.output)
+        assert output["total"] == 2
+        assert output["valid"] == 2
+        assert output["invalid"] == 0
+
+    def test_batch_one_invalid_exit_2(self, tmp_path: Path) -> None:
+        seed, public = _make_keypair()
+        m1 = _make_signed_manifest_dict(public.hex(), seed, tree_height=1)
+        m2 = _make_signed_manifest_dict(public.hex(), seed, tree_height=2)
+        m2["merkle_root"] = _sha3_512_root("tampered")
+        p1 = _write_manifest(tmp_path, m1, "m1.json")
+        p2 = _write_manifest(tmp_path, m2, "m2.json")
+        key_file = _make_key_file(tmp_path, public.hex())
+
+        runner = CliRunner()
+        result = runner.invoke(cli, ["verify-batch", str(p1), str(p2), "--keys", str(key_file)])
+
+        assert result.exit_code == 2
+        output = _extract_json(result.output)
+        assert output["total"] == 2
+        assert output["valid"] == 1
+        assert output["invalid"] == 1
+
+
+class TestAC10HelpText:
+    """AC10: CLI help text comprehensive with examples."""
+
+    def test_top_level_help(self) -> None:
+        runner = CliRunner()
+        result = runner.invoke(cli, ["--help"])
+
+        assert result.exit_code == 0
+        assert "verify-manifest" in result.output
+        assert "verify-batch" in result.output
+        assert "validate-schema" in result.output
+        assert "list-keys" in result.output
+        assert "list-manifests" in result.output
+
+    def test_verify_manifest_help(self) -> None:
+        runner = CliRunner()
+        result = runner.invoke(cli, ["verify-manifest", "--help"])
+
+        assert result.exit_code == 0
+        assert "SOURCE" in result.output
+        assert "schema" in result.output
+        assert "signature" in result.output
+
+    def test_verify_batch_help(self) -> None:
+        runner = CliRunner()
+        result = runner.invoke(cli, ["verify-batch", "--help"])
+
+        assert result.exit_code == 0
+        assert "SOURCES" in result.output or "sources" in result.output.lower()
+
+    def test_version_flag(self) -> None:
+        runner = CliRunner()
+        result = runner.invoke(cli, ["--version"])
+
+        assert result.exit_code == 0
+        assert "0.1.0" in result.output
+
+
+class TestAdditionalCommands:
+    """validate-schema, list-keys, list-manifests commands."""
+
+    def test_validate_schema_valid_exit_0(self, tmp_path: Path) -> None:
+        data: dict[str, Any] = {
+            "manifest_version": "v1",
+            "timestamp": "2026-06-26T12:00:00Z",
+            "merkle_root": _sha3_512_root(),
+            "participant_did": "did:arkava:test",
+            "batch_count": 1,
+            "stump_proof_path": [],
+            "algorithm_id": ALGORITHM_ID_SHA3_512,
+            "key_version": "v1",
+        }
+        manifest_path = _write_manifest(tmp_path, data, "valid.json")
+
+        runner = CliRunner()
+        result = runner.invoke(cli, ["validate-schema", str(manifest_path)])
+
+        assert result.exit_code == 0
+        output = _extract_json(result.output)
+        assert output["schema_valid"] is True
+
+    def test_validate_schema_invalid_exit_1(self, tmp_path: Path) -> None:
+        data: dict[str, Any] = {"not": "valid"}
+        manifest_path = _write_manifest(tmp_path, data, "invalid.json")
+
+        runner = CliRunner()
+        result = runner.invoke(cli, ["validate-schema", str(manifest_path)])
+
+        assert result.exit_code == 1
+
+    def test_list_keys(self, tmp_path: Path) -> None:
+        key_file = _make_key_file(tmp_path, "ab" * 32, did="did:arkava:list-test")
+
+        runner = CliRunner()
+        result = runner.invoke(cli, ["list-keys", "--keys", str(key_file)])
+
+        assert result.exit_code == 0
+        output = _extract_json(result.output)
+        assert len(output["keys"]) == 1
+        assert output["keys"][0]["participant_did"] == "did:arkava:list-test"
+
+    def test_list_manifests(self, tmp_path: Path) -> None:
+        witness_dir = tmp_path / "witness-history" / "2026" / "06" / "26"
+        witness_dir.mkdir(parents=True)
+        (witness_dir / "manifest_2026-06-26.json").write_text("{}", encoding="utf-8")
+
+        runner = CliRunner()
+        result = runner.invoke(cli, ["list-manifests", str(tmp_path)])
+
+        assert result.exit_code == 0
+        output = _extract_json(result.output)
+        assert len(output["manifests"]) == 1
+
+    def test_list_manifests_nonexistent_dir_exit_3(self, tmp_path: Path) -> None:
+        runner = CliRunner()
+        result = runner.invoke(cli, ["list-manifests", str(tmp_path / "nope")])
+
+        assert result.exit_code == 3