witseal 0.1.0__py3-none-any.whl

witseal/__init__.py

@@ -0,0 +1,27 @@
+"""WitSeal Python — the Ecosystem SDK: consume, verify, and inspect WitSeal artifacts.
+
+The Python line is the **SDK / verifier** layer. It provides
+RFC 8785 canonicalization, SHA-256 hashing, Pydantic v2 wire-format
+schemas, Ed25519 receipt verification, witness-event hash-chain and
+evidence-package verification, a unified ``verify_artifact`` discriminator,
+and keyless ``inspect``.
+
+It does NOT generate artifacts or run a runtime: no signing/receipt
+generation, no subprocess mediation, no policy evaluation, no witness
+event-log append, no approval flow, no ``witseal exec``. Canonical
+generation is the Rust trust core. Public API surface is not yet
+frozen.
+"""
+
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
+
+try:
+    # Single source of truth: the version declared in pyproject.toml, surfaced
+    # through the installed distribution metadata, so __version__ can never
+    # drift from the packaged version.
+    __version__ = _version("witseal")
+except PackageNotFoundError:  # pragma: no cover - source tree without an install
+    __version__ = "0.1.0"
+
+__all__ = ["__version__"]

witseal/__main__.py

@@ -0,0 +1,292 @@
+"""Verifier / SDK CLI for the Python track (SDK role: consume / verify).
+
+Scope is intentionally narrow: schema + read-side verification + keyless
+inspection. No runtime execution, subprocess mediation, policy evaluation,
+artifact generation, or implicit public-key discovery — generation is the
+Rust track.
+
+Commands:
+
+  witseal verify receipt  <path> --public-key <path-or-hex>
+  witseal verify evidence <path> [--public-key <path-or-hex>]
+  witseal verify artifact <path> [--public-key <path-or-hex>]   (auto-discriminate)
+  witseal inspect         <path>                                 (keyless)
+
+All commands print a single JSON object to stdout (sorted keys); exit code
+is 0 for VALID, 1 for INVALID, 2 for an input/usage error.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from collections.abc import Mapping, Sequence
+from pathlib import Path
+from typing import Any
+
+from cryptography.hazmat.primitives.asymmetric.ed25519 import Ed25519PublicKey
+
+from witseal.inspect import inspect_artifact
+from witseal.schemas.receipt import ReceiptV02
+from witseal.verify import (
+    load_public_key_pem,
+    verify_artifact,
+    verify_evidence_package,
+    verify_receipt,
+)
+from witseal.verify.result import VerificationResult
+
+
+def _build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(
+        prog="witseal",
+        description=(
+            "WitSeal Python verifier / SDK CLI "
+            "(schema + read-side verification + keyless inspection only)."
+        ),
+    )
+    subparsers = parser.add_subparsers(dest="command", required=True)
+
+    verify_parser = subparsers.add_parser("verify", help="Verify WitSeal artifacts")
+    verify_subparsers = verify_parser.add_subparsers(
+        dest="verify_command", required=True
+    )
+
+    receipt_parser = verify_subparsers.add_parser(
+        "receipt",
+        help="Verify a v0.2 receipt with an explicit Ed25519 public key",
+    )
+    receipt_parser.add_argument("receipt_path", type=Path, metavar="path")
+    receipt_parser.add_argument(
+        "--public-key",
+        required=True,
+        metavar="path-or-hex",
+        help="Ed25519 public key as a PEM file path or 32-byte raw hex string",
+    )
+
+    evidence_parser = verify_subparsers.add_parser(
+        "evidence",
+        help="Verify an evidence package (chain + per-receipt integrity)",
+    )
+    evidence_parser.add_argument("artifact_path", type=Path, metavar="path")
+    evidence_parser.add_argument(
+        "--public-key",
+        required=False,
+        default=None,
+        metavar="path-or-hex",
+        help="Ed25519 public key (required only if the package holds a v0.2 receipt)",
+    )
+
+    artifact_parser = verify_subparsers.add_parser(
+        "artifact",
+        help="Verify any WitSeal artifact (auto-discriminate on schema_version)",
+    )
+    artifact_parser.add_argument("artifact_path", type=Path, metavar="path")
+    artifact_parser.add_argument(
+        "--public-key",
+        required=False,
+        default=None,
+        metavar="path-or-hex",
+        help="Ed25519 public key (required for v0.2 receipts / packages with one)",
+    )
+
+    inspect_parser = subparsers.add_parser(
+        "inspect",
+        help="Keyless inspection of a WitSeal artifact (no signature check)",
+    )
+    inspect_parser.add_argument("artifact_path", type=Path, metavar="path")
+
+    return parser
+
+
+def _load_receipt(path: Path) -> ReceiptV02:
+    return ReceiptV02.model_validate_json(path.read_bytes())
+
+
+def _load_json_mapping(path: Path) -> Mapping[str, Any]:
+    value = json.loads(path.read_text(encoding="utf-8"))
+    if not isinstance(value, Mapping):
+        raise ValueError("artifact must be a JSON object")
+    return value
+
+
+def _load_public_key_hex(value: str) -> Ed25519PublicKey:
+    normalized = value.strip()
+    if normalized.startswith(("0x", "0X")):
+        normalized = normalized[2:]
+
+    try:
+        raw = bytes.fromhex(normalized)
+    except ValueError as exc:
+        raise ValueError(
+            "public key must be an existing PEM path or 32-byte Ed25519 public key hex"
+        ) from exc
+
+    if len(raw) != 32:
+        raise ValueError("public key hex must decode to exactly 32 bytes")
+
+    return Ed25519PublicKey.from_public_bytes(raw)
+
+
+def _load_public_key(value: str) -> Ed25519PublicKey:
+    path = Path(value).expanduser()
+    if path.is_file():
+        return load_public_key_pem(path.read_bytes())
+    return _load_public_key_hex(value)
+
+
+def _emit(payload: dict[str, Any]) -> None:
+    sys.stdout.write(json.dumps(payload, sort_keys=True) + "\n")
+
+
+def _print_result(result: VerificationResult) -> None:
+    _emit(
+        {
+            "valid": result.valid,
+            "receipt_hash_valid": result.receipt_hash_valid,
+            "signature_valid": result.signature_valid,
+            "reason": result.reason,
+        }
+    )
+
+
+def _input_error(message: str) -> int:
+    sys.stderr.write(f"witseal: {message}\n")
+    return 2
+
+
+def _resolve_optional_key(value: str | None) -> Ed25519PublicKey | None:
+    if value is None:
+        return None
+    return _load_public_key(value)
+
+
+def _verify_receipt_command(args: argparse.Namespace) -> int:
+    try:
+        receipt = _load_receipt(args.receipt_path)
+    except OSError as exc:
+        return _input_error(f"could not read receipt '{args.receipt_path}': {exc}")
+    except ValueError as exc:
+        return _input_error(f"invalid receipt '{args.receipt_path}': {exc}")
+
+    try:
+        public_key = _load_public_key(args.public_key)
+    except OSError as exc:
+        return _input_error(f"could not read public key '{args.public_key}': {exc}")
+    except ValueError as exc:
+        return _input_error(f"invalid public key: {exc}")
+
+    try:
+        result = verify_receipt(receipt, public_key)
+    except ValueError as exc:
+        return _input_error(f"invalid receipt signature encoding: {exc}")
+
+    _print_result(result)
+    return 0 if result.valid else 1
+
+
+def _verify_evidence_command(args: argparse.Namespace) -> int:
+    try:
+        artifact = _load_json_mapping(args.artifact_path)
+    except OSError as exc:
+        return _input_error(f"could not read artifact '{args.artifact_path}': {exc}")
+    except ValueError as exc:
+        return _input_error(f"invalid artifact '{args.artifact_path}': {exc}")
+
+    try:
+        public_key = _resolve_optional_key(args.public_key)
+    except OSError as exc:
+        return _input_error(f"could not read public key '{args.public_key}': {exc}")
+    except ValueError as exc:
+        return _input_error(f"invalid public key: {exc}")
+
+    result = verify_evidence_package(artifact, public_key)
+    _emit(
+        {
+            "valid": result.valid,
+            "kind": result.kind,
+            "reason": result.reason,
+            "chain_valid": result.chain_valid,
+            "receipt_results": [
+                {"index": r.index, "valid": r.valid, "reason": r.reason}
+                for r in result.receipt_results
+            ],
+        }
+    )
+    return 0 if result.valid else 1
+
+
+def _verify_artifact_command(args: argparse.Namespace) -> int:
+    try:
+        artifact = _load_json_mapping(args.artifact_path)
+    except OSError as exc:
+        return _input_error(f"could not read artifact '{args.artifact_path}': {exc}")
+    except ValueError as exc:
+        return _input_error(f"invalid artifact '{args.artifact_path}': {exc}")
+
+    try:
+        public_key = _resolve_optional_key(args.public_key)
+    except OSError as exc:
+        return _input_error(f"could not read public key '{args.public_key}': {exc}")
+    except ValueError as exc:
+        return _input_error(f"invalid public key: {exc}")
+
+    result = verify_artifact(artifact, public_key)
+    _emit(
+        {
+            "valid": result.valid,
+            "kind": result.kind,
+            "schema_version": result.schema_version,
+            "reason": result.reason,
+        }
+    )
+    return 0 if result.valid else 1
+
+
+def _inspect_command(args: argparse.Namespace) -> int:
+    try:
+        artifact = _load_json_mapping(args.artifact_path)
+    except OSError as exc:
+        return _input_error(f"could not read artifact '{args.artifact_path}': {exc}")
+    except ValueError as exc:
+        return _input_error(f"invalid artifact '{args.artifact_path}': {exc}")
+
+    inspection = inspect_artifact(artifact)
+    _emit(
+        {
+            "kind": inspection.kind,
+            "schema_version": inspection.schema_version,
+            "fields": inspection.fields,
+            "integrity": inspection.integrity,
+            "notes": list(inspection.notes),
+            "reason": inspection.reason,
+        }
+    )
+    # Inspection is descriptive, not a pass/fail gate: exit 0 unless the
+    # artifact was unrecognized / unparseable (kind == 'unknown' or a parse
+    # reason was set).
+    if inspection.kind == "unknown" or inspection.reason is not None:
+        return 1
+    return 0
+
+
+def main(argv: Sequence[str] | None = None) -> int:
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+
+    if args.command == "verify":
+        if args.verify_command == "receipt":
+            return _verify_receipt_command(args)
+        if args.verify_command == "evidence":
+            return _verify_evidence_command(args)
+        if args.verify_command == "artifact":
+            return _verify_artifact_command(args)
+    elif args.command == "inspect":
+        return _inspect_command(args)
+
+    parser.error("unsupported command")
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

witseal/inspect/__init__.py

@@ -0,0 +1,10 @@
+"""Keyless artifact inspection — the SDK *consume* surface.
+
+Exposes :func:`inspect_artifact`, which summarizes a WitSeal receipt or
+evidence package and reports the integrity checks that require no public key.
+Signature verification (key-requiring) lives in :mod:`witseal.verify`.
+"""
+
+from witseal.inspect._inspect import ArtifactInspection, inspect_artifact
+
+__all__ = ["ArtifactInspection", "inspect_artifact"]

witseal/inspect/_inspect.py

@@ -0,0 +1,189 @@
+"""Keyless inspection of WitSeal artifacts — the SDK *consume* surface.
+
+``inspect`` answers "what is this artifact and what can I confirm about it
+*without a key*". It parses a receipt or evidence package, summarizes its
+salient fields, and reports the integrity checks that need no public key:
+
+- receipt ``receipt_hash`` self-consistency (recomputed over the S1
+  pre-image for v0.2, over the body for v0.1);
+- evidence-package chain integrity (linkage, self-hashes, sequence
+  monotonicity) and head-after-range match.
+
+Checks that DO need a key — Ed25519 signature verification on v0.2 receipts —
+are explicitly reported as *not checked here*; use ``verify`` with a public
+key for those. Inspection never fails closed on a bad artifact: it returns a
+structured report (including ``kind='unknown'`` for unrecognized input) so a
+consumer can see what it received.
+
+Read-side only. Python does not generate artifacts.
+"""
+
+from __future__ import annotations
+
+import hmac
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Any
+
+from pydantic import ValidationError
+
+from witseal.integrity.hash import sha256_canonical
+from witseal.integrity.signing import compute_receipt_hash
+from witseal.schemas.evidence_package import EvidencePackage
+from witseal.schemas.receipt import ExecutionReceipt, ReceiptV02
+from witseal.verify.chain import verify_chain
+
+_RECEIPT_HASH_FIELD = "receipt_hash"
+
+
+@dataclass(frozen=True, slots=True)
+class ArtifactInspection:
+    """Structured, keyless summary of a WitSeal artifact.
+
+    ``fields`` holds salient identifiers/values for display. ``integrity``
+    holds the keyless checks that were run (name -> bool). ``notes`` lists
+    things a consumer should know — notably which checks require a key and
+    were therefore not run here.
+    """
+
+    kind: str
+    schema_version: str | None = None
+    fields: dict[str, Any] = field(default_factory=dict)
+    integrity: dict[str, bool] = field(default_factory=dict)
+    notes: tuple[str, ...] = field(default_factory=tuple)
+    reason: str | None = None
+
+
+def _read_schema_version(value: Any) -> str | None:  # noqa: ANN401
+    if isinstance(value, Mapping):
+        sv = value.get("schema_version")
+        return sv if isinstance(sv, str) else None
+    return None
+
+
+def _inspect_receipt_v01(value: Mapping[str, Any]) -> ArtifactInspection:
+    try:
+        receipt = ExecutionReceipt.model_validate(dict(value))
+    except (ValidationError, ValueError) as exc:
+        return ArtifactInspection(
+            kind="receipt.v0.1",
+            schema_version="witseal.receipt.v0.1",
+            reason=f"schema validation failed: {exc}",
+        )
+    body = receipt.model_dump(by_alias=True)
+    body.pop(_RECEIPT_HASH_FIELD, None)
+    receipt_hash_ok = hmac.compare_digest(
+        sha256_canonical(body), receipt.receipt_hash
+    )
+    return ArtifactInspection(
+        kind="receipt.v0.1",
+        schema_version="witseal.receipt.v0.1",
+        fields={
+            "receipt_id": receipt.receipt_id,
+            "witness_event_id": receipt.witness_event_id,
+            "chain_segment_id": receipt.chain_segment_id,
+            "outcome": receipt.outcome,
+            "finalized_at": receipt.finalized_at,
+        },
+        integrity={"receipt_hash_self_consistent": receipt_hash_ok},
+        notes=("v0.1 receipts are unsigned; no signature check applies.",),
+    )
+
+
+def _inspect_receipt_v02(value: Mapping[str, Any]) -> ArtifactInspection:
+    try:
+        receipt = ReceiptV02.model_validate(dict(value))
+    except (ValidationError, ValueError) as exc:
+        return ArtifactInspection(
+            kind="receipt.v0.2",
+            schema_version="witseal.receipt.v0.2",
+            reason=f"schema validation failed: {exc}",
+        )
+    receipt_hash_ok = hmac.compare_digest(
+        compute_receipt_hash(receipt), receipt.receipt_hash
+    )
+    signature_algorithm = receipt.signature.split(":", 1)[0] if ":" in receipt.signature else None
+    return ArtifactInspection(
+        kind="receipt.v0.2",
+        schema_version="witseal.receipt.v0.2",
+        fields={
+            "receipt_id": receipt.receipt_id,
+            "witness_event_id": receipt.witness_event_id,
+            "chain_segment_id": receipt.chain_segment_id,
+            "outcome": receipt.outcome,
+            "finalized_at": receipt.finalized_at,
+            "artifact_type": receipt.artifact_type,
+            "build_id": receipt.build_id,
+            "git_commit": receipt.git_commit,
+            "signature_algorithm": signature_algorithm,
+            "is_genesis": receipt.prev_hash is None,
+        },
+        integrity={"receipt_hash_self_consistent": receipt_hash_ok},
+        notes=(
+            "signature verification requires a public key; not checked by "
+            "inspect — use `verify` with --public-key.",
+        ),
+    )
+
+
+def _inspect_evidence(value: Mapping[str, Any]) -> ArtifactInspection:
+    envelope_raw = {**value, "receipts": []}
+    try:
+        envelope = EvidencePackage.model_validate(envelope_raw)
+    except (ValidationError, ValueError) as exc:
+        return ArtifactInspection(
+            kind="evidence-package.v0.1",
+            schema_version="witseal.evidence-package.v0.1",
+            reason=f"schema validation failed: {exc}",
+        )
+    chain = verify_chain(envelope.events, envelope.chain_head_before_range)
+    recomputed_head = envelope.events[-1].event_hash if envelope.events else None
+    head_ok = recomputed_head == envelope.chain_head_after_range
+    raw_receipts = value.get("receipts")
+    receipt_count = len(raw_receipts) if isinstance(raw_receipts, list) else 0
+    return ArtifactInspection(
+        kind="evidence-package.v0.1",
+        schema_version="witseal.evidence-package.v0.1",
+        fields={
+            "package_id": envelope.package_id,
+            "chain_segment_id": envelope.chain_segment_id,
+            "exported_at": envelope.exported_at,
+            "range_start": envelope.range.start_sequence,
+            "range_end": envelope.range.end_sequence,
+            "event_count": len(envelope.events),
+            "receipt_count": receipt_count,
+            "policy_pack_count": len(envelope.policy_packs),
+        },
+        integrity={
+            "chain_valid": chain.valid,
+            "chain_head_after_range_matches": head_ok,
+        },
+        notes=(
+            "receipt signature verification requires a public key; not "
+            "checked by inspect — use `verify` with --public-key.",
+        )
+        + ((f"chain broke at index {chain.broken_at}: {chain.reason}",) if not chain.valid else ()),
+    )
+
+
+def inspect_artifact(value: Mapping[str, Any]) -> ArtifactInspection:
+    """Inspect *value* (a parsed JSON mapping) and return a keyless summary.
+
+    Discriminates on ``schema_version``; returns ``kind='unknown'`` for an
+    unrecognized artifact rather than raising.
+    """
+    schema_version = _read_schema_version(value)
+    if schema_version == "witseal.receipt.v0.1":
+        return _inspect_receipt_v01(value)
+    if schema_version == "witseal.receipt.v0.2":
+        return _inspect_receipt_v02(value)
+    if schema_version == "witseal.evidence-package.v0.1":
+        return _inspect_evidence(value)
+    reason = (
+        "no schema_version field: not a recognized WitSeal artifact"
+        if schema_version is None
+        else f"unrecognized schema_version '{schema_version}'"
+    )
+    return ArtifactInspection(
+        kind="unknown", schema_version=schema_version, reason=reason
+    )

witseal/integrity/__init__.py

@@ -0,0 +1,7 @@
+"""Integrity primitives: canonical JSON serialization, hashing, signing bytes."""
+
+from witseal.integrity.canonical_json import canonicalize
+from witseal.integrity.hash import sha256_canonical
+from witseal.integrity.signing import compute_signing_bytes
+
+__all__ = ["canonicalize", "compute_signing_bytes", "sha256_canonical"]

witseal/integrity/canonical_json.py

@@ -0,0 +1,18 @@
+"""Canonical JSON serialization per RFC 8785 (JSON Canonicalization Scheme)."""
+
+from __future__ import annotations
+
+from typing import Any
+
+import rfc8785
+
+
+def canonicalize(value: Any) -> bytes:  # noqa: ANN401
+    """Serialize *value* to RFC 8785 canonical JSON as UTF-8 bytes.
+
+    Output is byte-deterministic for any JSON-compatible Python value
+    (``dict`` with ``str`` keys, ``list``/``tuple``, ``str``, ``int``,
+    ``float``, ``bool``, ``None``). The result is the input to evidence-chain
+    hashing; see :func:`witseal.integrity.hash.sha256_canonical`.
+    """
+    return rfc8785.dumps(value)

witseal/integrity/hash.py

@@ -0,0 +1,29 @@
+"""SHA-256 hashing primitives for the evidence chain."""
+
+from __future__ import annotations
+
+import hashlib
+from typing import Any
+
+from witseal.integrity.canonical_json import canonicalize
+
+
+def sha256_hex_of_bytes(data: bytes) -> str:
+    """Return lowercase-hex SHA-256 of raw *data* bytes.
+
+    Used by the v0.2 verifier path: ``receipt_hash`` is the SHA-256 of the
+    already-canonical S1 pre-image bytes (see
+    :func:`witseal.integrity.signing.compute_receipt_hash`), so the input
+    must NOT be canonicalized again. Output matches the ``Sha256Hex``
+    primitive (64 lowercase hex chars).
+    """
+    return hashlib.sha256(data).hexdigest()
+
+
+def sha256_canonical(value: Any) -> str:  # noqa: ANN401
+    """Return lowercase-hex SHA-256 of the RFC 8785 canonical JSON form of *value*.
+
+    Matches the ``Sha256Hex`` primitive in :mod:`witseal.schemas._primitives`
+    (64 lowercase hex chars).
+    """
+    return sha256_hex_of_bytes(canonicalize(value))

witseal/integrity/hash_chain.py

@@ -0,0 +1,58 @@
+"""Witness-event hashing primitive — mirror of TS `src/integrity/hash-chain.ts`.
+
+The witness-event hash chain links events via ``previous_event_hash``; each
+event self-attests via ``event_hash``. The hashing rule (cross-track canon,
+wire-format spec § 3.3 / TS ``hashEvent``):
+
+    event_hash = SHA-256( canonicalize( event WITHOUT the event_hash field ) )
+
+The ``event_hash`` key is OMITTED entirely from the pre-image — not set to
+``null``, not set to ``""`` — exactly as the TS reference strips it
+(``const { event_hash, ...draft } = event``). Canonicalization is RFC 8785
+via :func:`witseal.integrity.canonical_json.canonicalize`, the same
+byte-identity-proven canonicalizer used for the golden receipt
+(``8fc29592…``). Because event_hash is a deterministic composition over that
+canonicalizer with a fixed field-omission rule, an event_hash computed here
+matches the value any conforming track (TS / Rust) computes for the same
+event bytes.
+
+Python is the ecosystem-facing SDK: it *consumes and verifies* events, it
+does not generate them at runtime. This module is the read-side primitive
+the chain verifier (:mod:`witseal.verify.chain`) builds on.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Mapping
+from typing import Any
+
+from witseal.integrity.canonical_json import canonicalize
+from witseal.integrity.hash import sha256_hex_of_bytes
+from witseal.schemas.witness_event import WitnessEvent
+
+EVENT_HASH_FIELD: str = "event_hash"
+PREVIOUS_EVENT_HASH_FIELD: str = "previous_event_hash"
+
+
+def _event_body(event: WitnessEvent | Mapping[str, Any]) -> dict[str, Any]:
+    """Return the canonical wire dict of *event* (by-alias), as a plain dict.
+
+    Accepts a parsed :class:`WitnessEvent` (preferred — the §7 model
+    serializer applies, so unset ``identity_origin`` / ``operation_id`` are
+    omitted, preserving pre-§7 byte-identity) or a raw mapping (used when a
+    caller already holds wire bytes and only needs the hash recomputation).
+    """
+    if isinstance(event, WitnessEvent):
+        return event.model_dump(by_alias=True)
+    return dict(event)
+
+
+def hash_event(event: WitnessEvent | Mapping[str, Any]) -> str:
+    """Compute the ``event_hash`` for *event* (lowercase hex).
+
+    Strips the ``event_hash`` field, canonicalizes the remainder per
+    RFC 8785, and returns the SHA-256 hex. The input is never mutated.
+    """
+    body = _event_body(event)
+    body.pop(EVENT_HASH_FIELD, None)
+    return sha256_hex_of_bytes(canonicalize(body))