aevum-cli 0.7.1__tar.gz → 0.7.3__tar.gz

{aevum_cli-0.7.1 → aevum_cli-0.7.3}/PKG-INFO

@@ -1,11 +1,11 @@
 Metadata-Version: 2.4
 Name: aevum-cli
-Version: 0.7.1
+Version: 0.7.3
 Summary: Aevum -- command-line interface for operating Aevum nodes.
 Project-URL: Homepage, https://aevum.build
 Project-URL: Repository, https://github.com/aevum-labs/aevum
 License: Apache-2.0
-Classifier: Development Status :: 3 - Alpha
+Classifier: Development Status :: 4 - Beta
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: Apache Software License
 Classifier: Programming Language :: Python :: 3.11
@@ -13,7 +13,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Requires-Dist: aevum-core
 Requires-Dist: aevum-server
-Requires-Dist: typer[all]>=0.12
+Requires-Dist: typer>=0.12
 Requires-Dist: uvicorn[standard]>=0.30
 Provides-Extra: conform
 Requires-Dist: aevum-conformance; extra == 'conform'

{aevum_cli-0.7.1 → aevum_cli-0.7.3}/pyproject.toml

@@ -1,12 +1,12 @@
 [project]
 name = "aevum-cli"
-version = "0.7.1"
+version = "0.7.3"
 description = "Aevum -- command-line interface for operating Aevum nodes."
 readme = "README.md"
 requires-python = ">=3.11"
 license = { text = "Apache-2.0" }
 classifiers = [
-    "Development Status :: 3 - Alpha",
+    "Development Status :: 4 - Beta",
     "Intended Audience :: Developers",
     "License :: OSI Approved :: Apache Software License",
     "Programming Language :: Python :: 3.11",
@@ -15,7 +15,7 @@ classifiers = [
 dependencies = [
     "aevum-core",
     "aevum-server",
-    "typer[all]>=0.12",
+    "typer>=0.12",
     "uvicorn[standard]>=0.30",
 ]
 

{aevum_cli-0.7.1 → aevum_cli-0.7.3}/src/aevum/cli/__init__.py

@@ -12,4 +12,4 @@ Commands:
     conformance run  Run the conformance suite
 """
 
-__version__ = "0.4.0"
+__version__ = "0.7.3"

{aevum_cli-0.7.1 → aevum_cli-0.7.3}/src/aevum/cli/app.py

@@ -87,18 +87,42 @@ def init(
 
 @app.command()
 def verify(
-    session_id: Annotated[str, typer.Argument(help="Session ID to verify")],
+    receipt_or_session: Annotated[
+        str,
+        typer.Argument(
+            help=(
+                "Session ID to verify (queries local DB), "
+                "or path to a receipt JSON file (no DB required)."
+            )
+        ),
+    ],
     state_dir: Annotated[
         Path,
         typer.Option("--state-dir", "-s"),
     ] = _DEFAULT_STATE,
 ) -> None:
     """
-    Verify a session's Merkle root and signatures.
+    Verify a session or receipt file.
+
+    Session mode:   aevum verify <session_id>
+      Re-reads stored events, recomputes Merkle root. Requires local DB.
+
+    Receipt mode:   aevum verify receipt.json
+      Reads a self-contained receipt file (produced by `aevum receipt`).
+      Verifies hash chain without accessing a local DB.
 
-    Re-reads the stored session events from SQLite, recomputes the
-    Merkle root, and compares it to the signed root in the sigchain.
+    Exit 0 = VERIFIED. Exit 1 = TAMPERED or not found.
     """
+    receipt_path = Path(receipt_or_session)
+    if receipt_path.exists() and receipt_path.suffix in (".cbor", ".cose"):
+        _verify_cose_receipt(receipt_path)
+    elif receipt_path.exists() and receipt_path.suffix == ".json":
+        _verify_receipt_file(receipt_path)
+    else:
+        _verify_session(receipt_or_session, state_dir)
+
+
+def _verify_session(session_id: str, state_dir: Path) -> None:
     db_path = state_dir / "aevum.db"
     if not db_path.exists():
         typer.echo(f"Database not found: {db_path}", err=True)
@@ -131,6 +155,215 @@ def verify(
         raise typer.Exit(code=1) from None
 
 
+def _compute_merkle_from_entries(entries: list[dict[str, Any]]) -> str:
+    """Replicates SessionRecord.compute_merkle_root() over receipt entry dicts."""
+    if not entries:
+        return hashlib.sha256(b"").hexdigest()
+    sorted_entries = sorted(entries, key=lambda e: e["sequence"])
+    leaves = [
+        hashlib.sha256((e["input_hash"] + e["output_hash"]).encode("ascii")).hexdigest()
+        for e in sorted_entries
+    ]
+    current = leaves
+    while len(current) > 1:
+        next_level: list[str] = []
+        for i in range(0, len(current), 2):
+            left = current[i]
+            right = current[i + 1] if i + 1 < len(current) else left
+            next_level.append(hashlib.sha256((left + right).encode("ascii")).hexdigest())
+        current = next_level
+    return current[0]
+
+
+def _verify_cose_receipt(receipt_path: Path) -> None:
+    """Verify a COSE_Sign1 receipt file (.cbor / .cose) via the verify command."""
+    try:
+        import cbor2
+        import nacl.exceptions
+        import nacl.signing
+        from aevum.core.receipt import AevumReceipt
+    except ImportError as exc:
+        typer.echo(f"Missing dependency: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+
+    try:
+        raw = receipt_path.read_bytes()
+        cose = cbor2.loads(raw)
+    except Exception as exc:  # noqa: BLE001
+        typer.echo(f"INVALID: cannot read or decode {receipt_path}: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+
+    if not isinstance(cose, list) or len(cose) != 4:
+        typer.echo("INVALID: not a 4-element COSE_Sign1 array", err=True)
+        raise typer.Exit(code=1)
+
+    protected_bstr, unprotected, payload_bstr, signature_bytes = cose
+
+    try:
+        protected = cbor2.loads(protected_bstr)
+    except Exception as exc:  # noqa: BLE001
+        typer.echo(f"INVALID: cannot decode protected header: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+
+    alg = protected.get(1)
+    if alg != -8:
+        typer.echo(
+            f"UNSUPPORTED ALGORITHM: alg={alg!r} (expected -8 for EdDSA/Ed25519)", err=True
+        )
+        raise typer.Exit(code=2)
+
+    try:
+        receipt = AevumReceipt.model_validate(cbor2.loads(payload_bstr))
+    except Exception as exc:  # noqa: BLE001
+        typer.echo(f"INVALID: cannot decode receipt payload: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+
+    sig_structure = cbor2.dumps(["Signature1", protected_bstr, b"", payload_bstr])
+    digest = hashlib.sha3_256(sig_structure).digest()
+
+    pub_key_bytes: bytes | None = None
+    ed25519_pub_path = _DEFAULT_STATE / "ed25519.pub"
+    if ed25519_pub_path.exists():
+        pub_key_bytes = ed25519_pub_path.read_bytes()
+
+    if pub_key_bytes is None:
+        typer.echo(
+            typer.style("STRUCTURE VALID (signature not checked)", fg=typer.colors.YELLOW)
+        )
+        typer.echo("  Set ~/.aevum/ed25519.pub to verify the Ed25519 signature.")
+        typer.echo(f"  Action:    {receipt.action}")
+        typer.echo(f"  Principal: {receipt.principal}")
+        typer.echo(f"  At:        {receipt.occurred_at}")
+        return
+
+    try:
+        verify_key = nacl.signing.VerifyKey(pub_key_bytes)
+        verify_key.verify(digest, bytes(signature_bytes))
+    except nacl.exceptions.BadSignatureError:
+        typer.echo(typer.style("TAMPERED", fg=typer.colors.RED), err=True)
+        raise typer.Exit(code=1) from None
+    except Exception as exc:  # noqa: BLE001
+        typer.echo(f"SIGNATURE INVALID: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+
+    typer.echo(
+        typer.style(
+            f"Session {receipt.agent_id[:12]}... VERIFIED", fg=typer.colors.GREEN
+        )
+    )
+    typer.echo(f"  Action:    {receipt.action}")
+    typer.echo(f"  Principal: {receipt.principal}")
+    typer.echo(f"  At:        {receipt.occurred_at}")
+
+
+def _verify_receipt_file(receipt_path: Path) -> None:
+    """Verify a receipt JSON file without database access."""
+    try:
+        receipt = json.loads(receipt_path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError) as exc:
+        typer.echo(f"Cannot read receipt file: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+
+    required = {"session_id", "entry_count", "entries", "exported_at", "merkle_root"}
+    missing = required - set(receipt.keys())
+    if missing:
+        typer.echo(f"Invalid receipt: missing fields {sorted(missing)}", err=True)
+        raise typer.Exit(code=1)
+
+    session_id = receipt["session_id"]
+    entries = receipt["entries"]
+    entry_count = receipt["entry_count"]
+    stored_root = receipt["merkle_root"]
+
+    if len(entries) != entry_count:
+        typer.echo(
+            typer.style(f"Session {session_id[:12]}... TAMPERED", fg=typer.colors.RED),
+            err=True,
+        )
+        typer.echo(
+            f"  Entry count mismatch: expected {entry_count}, found {len(entries)}",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    try:
+        recomputed_root = _compute_merkle_from_entries(entries)
+    except (KeyError, TypeError) as exc:
+        typer.echo(f"Invalid receipt entries: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+
+    if recomputed_root != stored_root:
+        typer.echo(
+            typer.style(f"Session {session_id[:12]}... TAMPERED", fg=typer.colors.RED),
+            err=True,
+        )
+        typer.echo("  Merkle root mismatch:", err=True)
+        typer.echo(f"  Stored:     {stored_root[:16]}...", err=True)
+        typer.echo(f"  Recomputed: {recomputed_root[:16]}...", err=True)
+        raise typer.Exit(code=1)
+
+    typer.echo(typer.style(f"Session {session_id[:12]}... VERIFIED", fg=typer.colors.GREEN))
+    typer.echo(f"  Merkle root: {recomputed_root[:16]}...")
+    typer.echo(f"  Entries:     {len(entries)}")
+    typer.echo(f"  Exported at: {receipt.get('exported_at', 'unknown')}")
+
+
+@app.command()
+def receipt(
+    session_id: Annotated[str, typer.Argument(help="Session ID to export as a receipt")],
+    state_dir: Annotated[
+        Path,
+        typer.Option("--state-dir", "-s"),
+    ] = _DEFAULT_STATE,
+) -> None:
+    """
+    Export a self-contained JSON receipt for a session.
+
+    Prints JSON to stdout — redirect to save:
+      aevum receipt <session_id> > proof.json
+
+    Verify the receipt offline (no DB required):
+      aevum verify proof.json
+    """
+    import datetime as dt
+
+    db_path = state_dir / "aevum.db"
+    if not db_path.exists():
+        typer.echo(f"Database not found: {db_path}", err=True)
+        raise typer.Exit(code=1)
+
+    try:
+        from aevum.core.replay import ReplayEngine
+        engine = ReplayEngine(db_path)
+        record = engine.load_session_record(session_id)
+
+        entries = [
+            {
+                "sequence": ev.sequence,
+                "event_type": ev.event_type.value,
+                "input_hash": ev.input_hash,
+                "output_hash": ev.output_hash,
+                "occurred_at": ev.occurred_at.isoformat(),
+                "latency_ms": ev.latency_ms,
+            }
+            for ev in record.events
+        ]
+
+        receipt_doc = {
+            "session_id": record.session_id,
+            "exported_at": dt.datetime.now(dt.UTC).isoformat(),
+            "entry_count": len(entries),
+            "merkle_root": record.merkle_root,
+            "entries": entries,
+        }
+
+        typer.echo(json.dumps(receipt_doc, indent=2))
+
+    except ValueError as exc:
+        typer.echo(f"Session not found: {exc}", err=True)
+        raise typer.Exit(code=1) from None
+
+
 @app.command(name="audit-pack")
 def audit_pack(
     session_id: Annotated[str, typer.Argument(help="Session ID")],

{aevum_cli-0.7.1 → aevum_cli-0.7.3}/tests/test_phase8_cli.py

@@ -321,7 +321,7 @@ class TestCLIHelp:
         result = runner.invoke(app, ["--help"])
         assert result.exit_code == 0
         clean = strip_ansi(result.output)
-        for cmd in ("init", "verify", "audit-pack", "conform", "replay"):
+        for cmd in ("init", "verify", "receipt", "audit-pack", "conform", "replay"):
             assert cmd in clean
 
     def test_help_still_shows_existing_commands(self) -> None:
@@ -332,7 +332,7 @@ class TestCLIHelp:
             assert cmd in clean
 
     def test_each_new_command_has_help(self) -> None:
-        for cmd in ("init", "verify", "audit-pack", "conform", "replay"):
+        for cmd in ("init", "verify", "receipt", "audit-pack", "conform", "replay"):
             result = runner.invoke(app, [cmd, "--help"])
             assert result.exit_code == 0, f"--help failed for command: {cmd}"
 
@@ -350,3 +350,210 @@ class TestCLIHelp:
         result = runner.invoke(app, ["replay", "--help"])
         assert result.exit_code == 0
         assert "verbose" in strip_ansi(result.output).lower()
+
+
+_EMPTY_MERKLE = hashlib.sha256(b"").hexdigest()
+
+_DB_SCHEMA = """
+    CREATE TABLE sessions (
+        session_id TEXT PRIMARY KEY, commit_type TEXT,
+        principal TEXT, purpose TEXT, started_at TEXT,
+        closed_at TEXT, event_count INTEGER, fact_count INTEGER,
+        checkpoint_count INTEGER, merkle_root TEXT,
+        ed25519_sig TEXT, mldsa65_sig TEXT, ed25519_pub TEXT,
+        mldsa65_pub TEXT, tsa_token TEXT, sigchain_entry_id INTEGER
+    );
+    CREATE TABLE session_events (
+        event_id TEXT PRIMARY KEY, session_id TEXT,
+        sequence INTEGER, event_type TEXT, occurred_at TEXT,
+        input_hash TEXT, output_hash TEXT, latency_ms INTEGER
+    );
+"""
+
+
+def _receipt_merkle_root(entries: list[dict]) -> str:  # type: ignore[type-arg]
+    """Compute the same Merkle root as _compute_merkle_from_entries for test fixtures."""
+    if not entries:
+        return hashlib.sha256(b"").hexdigest()
+    sorted_entries = sorted(entries, key=lambda e: e["sequence"])
+    leaves = [
+        hashlib.sha256((e["input_hash"] + e["output_hash"]).encode("ascii")).hexdigest()
+        for e in sorted_entries
+    ]
+    current = leaves
+    while len(current) > 1:
+        nxt = []
+        for i in range(0, len(current), 2):
+            left = current[i]
+            right = current[i + 1] if i + 1 < len(current) else left
+            nxt.append(hashlib.sha256((left + right).encode("ascii")).hexdigest())
+        current = nxt
+    return current[0]
+
+
+def _make_receipt_doc(
+    session_id: str = "test-session-001",
+    n_entries: int = 0,
+    tamper_count: bool = False,
+    tamper_root: bool = False,
+) -> dict:  # type: ignore[type-arg]
+    entries = []
+    for i in range(n_entries):
+        entries.append({
+            "sequence": i,
+            "event_type": "relate",
+            "input_hash": hashlib.sha256(f"in-{i}".encode()).hexdigest(),
+            "output_hash": hashlib.sha256(f"out-{i}".encode()).hexdigest(),
+            "occurred_at": "2026-01-01T00:00:00+00:00",
+            "latency_ms": 5,
+        })
+    return {
+        "session_id": session_id,
+        "exported_at": "2026-01-01T01:00:00+00:00",
+        "entry_count": len(entries) + (1 if tamper_count else 0),
+        "merkle_root": ("a" * 64) if tamper_root else _receipt_merkle_root(entries),
+        "entries": entries,
+    }
+
+
+class TestReceiptCommand:
+    def _make_db(self, tmp_path: Path, session_id: str = "sess-r01") -> None:
+        db = tmp_path / "aevum.db"
+        conn = sqlite3.connect(str(db))
+        conn.executescript(_DB_SCHEMA)
+        now = datetime.now(UTC).isoformat()
+        conn.execute(
+            "INSERT INTO sessions VALUES (?,?,?,?,?,?,?,?,?,?,NULL,NULL,NULL,NULL,NULL,NULL)",
+            (session_id, "complete", "alice", "test", now, now, 0, 0, 0, _EMPTY_MERKLE),
+        )
+        conn.commit()
+        conn.close()
+
+    def test_receipt_help(self) -> None:
+        result = runner.invoke(app, ["receipt", "--help"])
+        assert result.exit_code == 0
+        assert "receipt" in strip_ansi(result.output).lower()
+
+    def test_receipt_missing_db_exits_1(self, tmp_path: Path) -> None:
+        result = runner.invoke(
+            app, ["receipt", "sess-r01", "--state-dir", str(tmp_path)]
+        )
+        assert result.exit_code == 1
+        assert "not found" in strip_ansi(result.output).lower()
+
+    def test_receipt_valid_session_outputs_json(self, tmp_path: Path) -> None:
+        self._make_db(tmp_path)
+        result = runner.invoke(
+            app, ["receipt", "sess-r01", "--state-dir", str(tmp_path)]
+        )
+        assert result.exit_code == 0
+        doc = json.loads(strip_ansi(result.output))
+        assert doc["session_id"] == "sess-r01"
+
+    def test_receipt_output_has_required_fields(self, tmp_path: Path) -> None:
+        self._make_db(tmp_path)
+        result = runner.invoke(
+            app, ["receipt", "sess-r01", "--state-dir", str(tmp_path)]
+        )
+        assert result.exit_code == 0
+        doc = json.loads(strip_ansi(result.output))
+        for field in ("session_id", "entry_count", "entries", "exported_at", "merkle_root"):
+            assert field in doc, f"Missing field: {field}"
+
+    def test_receipt_empty_session_has_correct_merkle_root(self, tmp_path: Path) -> None:
+        self._make_db(tmp_path)
+        result = runner.invoke(
+            app, ["receipt", "sess-r01", "--state-dir", str(tmp_path)]
+        )
+        assert result.exit_code == 0
+        doc = json.loads(strip_ansi(result.output))
+        assert doc["entry_count"] == 0
+        assert doc["merkle_root"] == _EMPTY_MERKLE
+
+    def test_receipt_missing_session_exits_1(self, tmp_path: Path) -> None:
+        self._make_db(tmp_path)
+        result = runner.invoke(
+            app, ["receipt", "no-such-session", "--state-dir", str(tmp_path)]
+        )
+        assert result.exit_code == 1
+
+
+class TestVerifyReceiptFile:
+    def _write_receipt(self, tmp_path: Path, doc: dict) -> Path:  # type: ignore[type-arg]
+        f = tmp_path / "receipt.json"
+        f.write_text(json.dumps(doc), encoding="utf-8")
+        return f
+
+    def test_verify_receipt_file_valid_exits_0(self, tmp_path: Path) -> None:
+        f = self._write_receipt(tmp_path, _make_receipt_doc())
+        result = runner.invoke(app, ["verify", str(f)])
+        assert result.exit_code == 0
+        assert "VERIFIED" in strip_ansi(result.output)
+
+    def test_verify_receipt_file_with_entries_exits_0(self, tmp_path: Path) -> None:
+        f = self._write_receipt(tmp_path, _make_receipt_doc(n_entries=2))
+        result = runner.invoke(app, ["verify", str(f)])
+        assert result.exit_code == 0
+        assert "VERIFIED" in strip_ansi(result.output)
+
+    def test_verify_receipt_file_shows_merkle_root(self, tmp_path: Path) -> None:
+        f = self._write_receipt(tmp_path, _make_receipt_doc(n_entries=2))
+        result = runner.invoke(app, ["verify", str(f)])
+        assert result.exit_code == 0
+        assert "Merkle root:" in strip_ansi(result.output)
+
+    def test_verify_receipt_file_tampered_count_exits_1(self, tmp_path: Path) -> None:
+        f = self._write_receipt(tmp_path, _make_receipt_doc(n_entries=2, tamper_count=True))
+        result = runner.invoke(app, ["verify", str(f)])
+        assert result.exit_code == 1
+        assert "TAMPERED" in strip_ansi(result.output)
+
+    def test_verify_receipt_file_tampered_root_exits_1(self, tmp_path: Path) -> None:
+        f = self._write_receipt(tmp_path, _make_receipt_doc(n_entries=2, tamper_root=True))
+        result = runner.invoke(app, ["verify", str(f)])
+        assert result.exit_code == 1
+        assert "TAMPERED" in strip_ansi(result.output)
+
+    def test_verify_receipt_file_missing_fields_exits_1(self, tmp_path: Path) -> None:
+        f = tmp_path / "partial.json"
+        f.write_text('{"session_id": "x", "entries": []}', encoding="utf-8")
+        result = runner.invoke(app, ["verify", str(f)])
+        assert result.exit_code == 1
+
+    def test_verify_receipt_file_bad_json_exits_1(self, tmp_path: Path) -> None:
+        f = tmp_path / "bad.json"
+        f.write_bytes(b"not valid json {{{")
+        result = runner.invoke(app, ["verify", str(f)])
+        assert result.exit_code == 1
+
+    def test_verify_dispatches_to_session_mode_for_nonfile(self, tmp_path: Path) -> None:
+        result = runner.invoke(
+            app, ["verify", "sess-abc-not-a-file", "--state-dir", str(tmp_path)]
+        )
+        assert result.exit_code == 1
+        assert "not found" in strip_ansi(result.output).lower()
+
+    def test_verify_receipt_roundtrip(self, tmp_path: Path) -> None:
+        """Receipt produced by aevum receipt verifies cleanly with aevum verify."""
+        db = tmp_path / "aevum.db"
+        conn = sqlite3.connect(str(db))
+        conn.executescript(_DB_SCHEMA)
+        now = datetime.now(UTC).isoformat()
+        conn.execute(
+            "INSERT INTO sessions VALUES (?,?,?,?,?,?,?,?,?,?,NULL,NULL,NULL,NULL,NULL,NULL)",
+            ("roundtrip-01", "complete", "alice", "test", now, now, 0, 0, 0, _EMPTY_MERKLE),
+        )
+        conn.commit()
+        conn.close()
+
+        export_result = runner.invoke(
+            app, ["receipt", "roundtrip-01", "--state-dir", str(tmp_path)]
+        )
+        assert export_result.exit_code == 0
+
+        receipt_file = tmp_path / "roundtrip.json"
+        receipt_file.write_text(export_result.output, encoding="utf-8")
+
+        verify_result = runner.invoke(app, ["verify", str(receipt_file)])
+        assert verify_result.exit_code == 0
+        assert "VERIFIED" in strip_ansi(verify_result.output)