feat: v0.2.0 EvidenceReceipt v2 + well-known directory (#8)

* feat: v0.2.0 — EvidenceReceipt v2 + well-known directory

Adds EvidenceReceipt v2 verification alongside the existing ActionReceipt
v1 path. v1 callers see no behavior change. New v2 surface is required by
Pipelock v2.4 release-spec criteria 2 and 5: every contract-aware proxy
decision and contract-lifecycle event ships in the new envelope, and
external auditors must be able to verify them.

New surface:

- Version routing in `verify()`: dispatches on the top-level `record_type`
  discriminator. `"action_receipt_v1"` (or absent) routes to v1.
  `"evidence_receipt_v2"` routes to v2. Unknown types are rejected with
  a clear error.
- `verify_evidence()` for direct v2 verification with full payload detail.
- 13 EvidenceReceipt v2 payload kinds: `proxy_decision`,
  `contract_ratified`, `contract_promote_intent`,
  `contract_promote_committed`, `contract_rollback_authorized`,
  `contract_rollback_committed`, `contract_demoted`, `contract_expired`,
  `contract_drift`, `shadow_delta`, `opportunity_missing`,
  `key_rotation`, `contract_redaction_request`. Each has its own schema
  validator with strict unknown-field rejection.
- Key-purpose authority matrix: receipts must carry the correct
  `key_purpose` for their payload kind. Mismatches reject.
- RFC 8785 JCS canonicalization (`_jcs.py`) for signable preimage
  computation. Mirrors the Go reference: parse strict, reject duplicate
  keys, reject floats, NFC-normalize strings, sort keys.
- Well-known directory fetch (`_directory.py`): `fetch_directory()` and
  `parse_directory()` per RFC 9421. The README example switches from
  hardcoded SHA hex to directory-based key discovery.

Backward compatibility: confirmed across all 62 original tests. Public
v1 API surface unchanged. v1 conformance golden files verify
byte-identically.

Tests: 172 pass (62 v1 unchanged + 110 new). Build: clean wheel + sdist.
Lint: ruff check + ruff format both pass.

Follow-ups (tracked):

- Cross-implementation Go-generated v2 conformance golden vectors not
  yet in `tests/conformance/`. v2 signature round-trip is currently
  proven via Python-generated keys only. To prove byte-for-byte parity
  with the Go reference, generate v2 fixtures from
  `internal/contract/receipt` and copy them in.
- `verify_chain()` still validates v1 chain linkage only. Mixed v1/v2
  chains require a chain-verifier upgrade in a follow-up.

* tests: cross-implementation conformance for EvidenceReceipt v2

Adds three Go-emitted v2 receipt fixtures and a conformance test suite
that loads each via the Python verifier. Proves byte-for-byte JCS
preimage parity between the Go reference (internal/contract/receipt)
and the Python implementation for the proxy_decision, contract_promote_
committed, and shadow_delta payload kinds — the load-bearing audit
kinds for the v2.4 release spec's external verification claim.

Fixtures (under tests/conformance/):
  valid-evidence-proxy-decision.json
  valid-evidence-promote-committed.json
  valid-evidence-shadow-delta.json

Each is signed with the RFC 8032 section 7.1 test-1 private seed, so
the corresponding public key (also in v2-test-keys.json) is the same
across both implementations. A divergence in either side's
canonicalisation logic surfaces here as a signature mismatch.

tests/test_v2_conformance.py covers:
  - parametrised happy-path verification for each fixture
  - tampered-payload rejection (single-byte verdict flip on
    proxy_decision must invalidate the signature)
  - wrong-key rejection (all-zero public key must fail)

172 v2 tests in test_evidence.py + 18 in test_directory.py + 5 here +
the v0.1.x suite = 178 total. All pass.

Follow-up: the remaining 10 v2 payload kinds (contract_ratified,
contract_promote_intent, contract_rollback_authorized/committed,
contract_demoted, contract_expired, contract_drift, opportunity_missing,
key_rotation, contract_redaction_request) are still synthesised
internally by test_evidence.py and not yet covered by Go-emitted
goldens. Adding them follows the same pattern: emit from
internal/contract/receipt/golden_vectors_test.go with UPDATE_GOLDEN=1,
copy into tests/conformance/, append to V2_FIXTURES.

* fix: break import cycle between _verify and _evidence

Extract InvalidReceiptError, _is_valid_rfc3339, and _RFC3339_RE into a
new leaf module _common.py. Both _verify (v1) and _evidence (v2) now
import from _common, which has no intra-package imports of its own.
This removes the static cycle CodeQL flagged at _evidence.py:19 and
_verify.py:184.

The class object identity is preserved (re-exported via `import X as X`
from _verify), so existing `except InvalidReceiptError` callers and the
public pipelock_verify.InvalidReceiptError API continue to work.

* fix: report declared chain_seq in v2 fail-closed chain branch

The v2-in-chain fail-closed branch reported the list index for
broken_at_seq instead of the receipt's declared chain_seq, which
diverges from the v1 branch (which reads action_record.chain_seq
with index fallback). Auditors now see the same sequence number the
emitter wrote.

Defensive: only accept int values (rejecting bool, which Python
treats as int). Missing or non-int chain_seq falls back to the list
index so broken_at_seq is never None on the fail-closed path.

Adds three regression tests covering declared, missing, and non-int
chain_seq cases.

* chore: fix lint + typecheck CI (pre-existing, surfaced after b64fa7d)

CI on the branch has been failing both lint (ruff format) and
typecheck (mypy strict no-any-return) since b64fa7d. Fixing both
together so the branch goes green.

mypy: _PAYLOAD_VALIDATORS was typed `dict[str, Any]`, which lost
the validators' `(payload: dict[str, Any]) -> str | None` signature
and made `_validate_payload` return Any from a `str | None` slot.
Replace with `dict[str, Callable[[dict[str, Any]], str | None]]` so
the return type checks through the dispatch.

ruff format: blank-line and string-wrap normalisations across
_verify.py and the new test_regressions.py block. Auto-applied.

Author: luckyPipewrench

.github/workflows/codeql.yml

@@ -16,6 +16,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 15
     permissions:
+      contents: read
       security-events: write
       packages: read
 

.github/workflows/scorecard.yml

@@ -14,6 +14,7 @@ jobs:
   analysis:
     runs-on: ubuntu-latest
     permissions:
+      contents: read
       security-events: write
       id-token: write
     steps:

CHANGELOG.md

@@ -0,0 +1,77 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - 2026-05-01
+
+### Added
+
+- **EvidenceReceipt v2 support.** Full schema parsing and verification for
+  the contract-aware receipt envelope introduced in Pipelock v2.4. Includes:
+  - All 13 payload kinds: `proxy_decision`, `contract_ratified`,
+    `contract_promote_intent`, `contract_promote_committed`,
+    `contract_rollback_authorized`, `contract_rollback_committed`,
+    `contract_demoted`, `contract_expired`, `contract_drift`,
+    `shadow_delta`, `opportunity_missing`, `key_rotation`,
+    `contract_redaction_request`.
+  - Strict unknown-field rejection at envelope, signature proof, and payload
+    levels.
+  - Key purpose authority matrix enforcement (rejects valid signatures from
+    the wrong purpose).
+  - Detached Ed25519 PureEdDSA signature verification with JCS (RFC 8785)
+    canonicalization over typed structures.
+  - `verify_evidence()` function for direct v2 verification with
+    `expected_signer_key_id` and `expected_key_purpose` parameters.
+  - `EvidenceVerifyResult` dataclass with v2-specific diagnostic fields.
+  - `evidence_receipt_hash()` for v2 chain linkage computation.
+
+- **Version routing in `verify()`.** The existing `verify()` function now
+  auto-detects v1 vs v2 receipts by the `record_type` field and dispatches
+  to the correct verification path. Unknown record types are rejected with
+  a clear error.
+
+- **Well-known directory fetch helper.** `fetch_directory(host)` retrieves
+  the signing keyset from `/.well-known/http-message-signatures-directory`
+  (RFC 9421). `parse_directory()` parses the keyset from raw JSON.
+  `Directory` dataclass with `get_key()` and `public_key_hex()` lookup
+  methods.
+
+- **RFC 8785 JCS canonicalization module** (`_jcs.py`). Strict JSON parser
+  with duplicate-key rejection, float rejection, trailing-token rejection,
+  and NFC normalization. Used by EvidenceReceipt v2 preimage computation.
+
+### Changed
+
+- README updated with v2 documentation, well-known directory example, and
+  13-payload-kind authority matrix table. The key-pinning example now uses
+  the well-known directory fetch instead of a hardcoded SHA digest.
+
+### Fixed
+
+- Nothing. This is a backward-compatible feature release.
+
+### Backward compatibility
+
+- **No breaking changes.** All v0.1.x callers verifying ActionReceipt v1
+  continue to work without modification.
+- `verify()` returns `VerifyResult` for both v1 and v2 (v2 fields are
+  mapped: `event_id` to `action_id`, `payload_kind` to `action_type`).
+- `verify_chain()` is unchanged.
+- The `PAYLOAD_KINDS` and `PAYLOAD_AUTHORITY` constants are exported for
+  callers that need to inspect the v2 schema programmatically.
+
+## [0.1.1] - 2026-04-25
+
+### Fixed
+
+- Internal version metadata sync.
+
+## [0.1.0] - 2026-04-09
+
+### Added
+
+- Initial release. ActionReceipt v1 verification with Ed25519 signatures,
+  chain linkage, flight-recorder unwrapping, and CLI.

README.md

@@ -7,11 +7,11 @@
 [![OpenSSF Scorecard](https://api.scorecard.dev/projects/github.com/luckyPipewrench/pipelock-verify-python/badge)](https://scorecard.dev/viewer/?uri=github.com/luckyPipewrench/pipelock-verify-python)
 [![License: Apache-2.0](https://img.shields.io/badge/License-Apache_2.0-blue.svg)](LICENSE)
 
-**Python verifier for [Pipelock](https://github.com/luckyPipewrench/pipelock) action receipts.** Verifies the Ed25519 signature, chain linkage, and flight-recorder wrapping of receipts emitted by the Pipelock mediator.
+**Python verifier for [Pipelock](https://github.com/luckyPipewrench/pipelock) receipts.** Supports both **ActionReceipt v1** (legacy proxy decisions) and **EvidenceReceipt v2** (contract-aware lifecycle events). Verifies Ed25519 signatures, chain linkage, payload schemas, key-purpose authority, and flight-recorder wrapping.
 
 Mirrors the Go reference implementation byte-for-byte. The conformance golden files in `tests/conformance/` are generated by Pipelock's Go code and verified identically by both sides.
 
-[Install](#install) · [Usage](#usage) · [What gets verified](#what-gets-verified) · [Canonicalization](#canonicalization-rules) · [Spec](https://pipelab.org/learn/action-receipt-spec/) · [Go reference](https://github.com/luckyPipewrench/pipelock)
+[Install](#install) · [Usage](#usage) · [EvidenceReceipt v2](#evidencereceipt-v2) · [Well-known directory](#well-known-directory) · [What gets verified](#what-gets-verified) · [Spec](https://pipelab.org/learn/action-receipt-spec/) · [Go reference](https://github.com/luckyPipewrench/pipelock)
 
 ## Install
 
@@ -23,7 +23,7 @@ Only one runtime dependency: [`cryptography`](https://cryptography.io) for the E
 
 ## Usage
 
-### Single receipt
+### Single receipt (auto-detects v1 vs v2)
 
 ```python
 import pipelock_verify
@@ -37,11 +37,23 @@ if not result.valid:
 print(f"OK: {result.action_id} {result.verdict} {result.target}")
 ```
 
-Pin a specific signing key to reject receipts from any other signer:
+The `verify()` function automatically routes to the correct verification
+path based on the `record_type` field:
+
+- **No `record_type` or `"action_receipt_v1"`** routes to ActionReceipt v1.
+- **`"evidence_receipt_v2"`** routes to EvidenceReceipt v2.
+- **Unknown `record_type`** is rejected with a clear error.
+
+### Pin a signing key via the well-known directory
 
 ```python
-PROD_KEY = "70b991eb77816fc4ef0ae6a54d8a4119ddc5a16c9711c332c39e743079f6c63e"
-result = pipelock_verify.verify(receipt_bytes, public_key_hex=PROD_KEY)
+import pipelock_verify
+
+# Fetch the signing keyset from the Pipelock instance.
+directory = pipelock_verify.fetch_directory("pipelab.org")
+key_hex = directory.public_key_hex()
+
+result = pipelock_verify.verify(receipt_bytes, public_key_hex=key_hex)
 ```
 
 ### Receipt chain
@@ -73,9 +85,91 @@ python -m pipelock_verify evidence.jsonl --key 70b991eb77816fc4...
 
 Exit codes match `pipelock verify-receipt`: 0 on success, 1 on failure.
 
+## EvidenceReceipt v2
+
+EvidenceReceipt v2 is the contract-aware receipt envelope introduced in
+Pipelock v2.4. It sits alongside ActionReceipt v1 (which remains unchanged
+for backward compatibility).
+
+### Direct v2 verification
+
+For fine-grained control over v2-specific checks (key purpose enforcement,
+signer key ID pinning):
+
+```python
+from pipelock_verify import verify_evidence
+
+result = verify_evidence(
+    receipt_dict,
+    public_key_hex="...",
+    expected_signer_key_id="receipt-key-prod",
+    expected_key_purpose="receipt-signing",
+)
+
+if not result.valid:
+    raise SystemExit(f"v2 receipt failed: {result.error}")
+
+print(f"Event: {result.event_id}, Kind: {result.payload_kind}")
+```
+
+### 13 payload kinds
+
+| Payload kind | Signing purpose |
+|---|---|
+| `proxy_decision` | `receipt-signing` |
+| `contract_ratified` | `receipt-signing` |
+| `contract_promote_intent` | `contract-activation-signing` |
+| `contract_promote_committed` | `receipt-signing` |
+| `contract_rollback_authorized` | `contract-activation-signing` |
+| `contract_rollback_committed` | `receipt-signing` |
+| `contract_demoted` | `receipt-signing` |
+| `contract_expired` | `receipt-signing` |
+| `contract_drift` | `receipt-signing` |
+| `shadow_delta` | `receipt-signing` |
+| `opportunity_missing` | `receipt-signing` |
+| `key_rotation` | `contract-activation-signing` |
+| `contract_redaction_request` | `contract-activation-signing` |
+
+The authority matrix is enforced automatically. A valid signature from the
+wrong key purpose is rejected.
+
+### v2 canonicalization
+
+EvidenceReceipt v2 uses RFC 8785 JSON Canonicalization Scheme (JCS) for
+signable preimages, not Go's `encoding/json` byte order (which is what
+ActionReceipt v1 uses). JCS rules:
+
+- Object keys sorted lexicographically by Unicode codepoint.
+- Strings NFC-normalized.
+- Floats rejected (use decimal strings).
+- No whitespace between tokens.
+
+The `signature` field is zeroed before computing the preimage.
+
+## Well-known directory
+
+Pipelock instances serve their signing keys at
+`/.well-known/http-message-signatures-directory` (RFC 9421). Use the
+built-in fetch helper to retrieve and parse the keyset:
+
+```python
+from pipelock_verify import fetch_directory, parse_directory
+
+# Fetch from a live instance.
+directory = fetch_directory("pipelab.org")
+
+# Or parse from a pre-fetched JSON blob.
+directory = parse_directory(json_bytes)
+
+# Look up a specific key.
+key = directory.get_key("pipelock-mediation-prod")
+if key:
+    print(f"Key: {key.public_key}, Use: {key.use}")
+```
+
 ## What gets verified
 
-On a single receipt:
+On a single **ActionReceipt v1**:
 
 - Envelope version (rejects anything other than v1).
 - Action record version (rejects anything other than v1).
@@ -86,56 +180,47 @@ On a single receipt:
 - Optional trust anchor match (`public_key_hex` argument).
 - Ed25519 signature over `SHA-256(canonical action record)`.
 
-On a chain:
+On a single **EvidenceReceipt v2**:
 
-- Every individual receipt above.
-- Signer consistency (every receipt uses the same `signer_key`, or the
-  pinned trust anchor if one was supplied).
-- Monotonic `chain_seq` starting at 0.
-- `chain_prev_hash` linkage: each receipt's `chain_prev_hash` equals
-  `SHA-256` of the previous receipt's canonical envelope, in hex.
-- First receipt's `chain_prev_hash` equals the literal string `"genesis"`.
+- Envelope `record_type` and `receipt_version`.
+- Strict unknown-field rejection (envelope, signature proof, and payload).
+- Required envelope fields (`event_id`, `timestamp`, `payload_kind`).
+- Payload schema validation for all 13 payload kinds.
+- Key purpose authority matrix enforcement.
+- Signature proof structure (`signer_key_id`, `key_purpose`, `algorithm`).
+- Ed25519 PureEdDSA signature over `JCS(receipt_without_signature)`.
+- Optional trust anchors: `public_key_hex`, `expected_signer_key_id`,
+  `expected_key_purpose`.
 
-Failing receipts return the first break point (`broken_at_seq`) and a
-descriptive `error`, the same shape the Go CLI prints.
+On a **chain**:
+
+- Every individual receipt above (v1 or v2).
+- Signer consistency across the chain.
+- Monotonic `chain_seq` starting at 0.
+- `chain_prev_hash` linkage via SHA-256 of canonical envelopes.
+- First receipt's `chain_prev_hash` equals `"genesis"`.
 
 ## Input formats
 
 `verify_chain()` accepts JSONL in two shapes:
 
-1. **Flight-recorder entries** — the format Pipelock actually writes to
+1. **Flight-recorder entries** -- the format Pipelock actually writes to
    disk. Each line is a `recorder.Entry` object with `type ==
    "action_receipt"` and the receipt nested in `detail`. Non-receipt
    entries (checkpoints etc.) are skipped, not rejected.
-2. **Bare receipts** — one receipt object per line, no wrapping. Used by
-   the conformance suite and handy for ad-hoc testing.
+2. **Bare receipts** -- one receipt object per line, no wrapping. Used by
+   the conformance suite and handy for ad-hoc testing. Both v1 and v2
+   bare receipts are recognized.
 
 `verify()` accepts:
 
 - A JSON string or UTF-8 bytes.
 - A pre-parsed `dict` (for callers that already have the receipt loaded).
 - A flight-recorder entry dict (transparently unwrapped).
 
-## Canonicalization rules
-
-The signing input is the SHA-256 of the Go `json.Marshal` output of the
-`ActionRecord` struct. "Canonical" means matching that exactly:
-
-- Fields emitted in Go struct declaration order (not alphabetical).
-- `omitempty` fields dropped when the value is the Go zero value
-  (`""`, empty slice, `0`, `false`, `nil`).
-- Compact JSON (no whitespace between tokens).
-- HTML-safe escapes: `<`, `>`, `&`, U+2028, U+2029 encoded as Unicode
-  escapes, matching Go's default `encoding/json` behavior.
-- Fields unknown to the v1 schema are dropped (matches Go
-  `json.Unmarshal` round-trip behavior).
-
-Any deviation produces different bytes, a different hash, and a failed
-signature. See `pipelock_verify/_canonical.py` for the full rule set.
-
 ## Relationship to the Go reference
 
-* Go reference: https://github.com/luckyPipewrench/pipelock/tree/main/internal/receipt
+* Go reference: https://github.com/luckyPipewrench/pipelock/tree/main/internal/receipt (v1), https://github.com/luckyPipewrench/pipelock/tree/main/internal/contract/receipt (v2)
 * Conformance suite: https://github.com/luckyPipewrench/pipelock/tree/main/sdk/conformance
 * Spec page: https://pipelab.org/learn/action-receipt-spec/