Skip to content

fix: restore v1 signing-projection parity with the Go emitter - #34

Merged
luckyPipewrench merged 3 commits into
mainfrom
fix/v1-canonical-parity
Jul 25, 2026
Merged

luckyPipewrench merged 3 commits into
mainfrom
fix/v1-canonical-parity

Conversation

@luckyPipewrench

@luckyPipewrench luckyPipewrench commented Jul 24, 2026 •

Copy link
Copy Markdown
Member

What changed

The v1 canonical projection omitted nine fields that the Go emitter signs, so every receipt produced by a current Pipelock failed signature verification against this package. decision_phase is emitted on ordinary proxy decisions, which made the break total rather than partial.

Restores decision_phase, defer_id, resolution_policy, resolution_source, session_id, session_id_original, run_nonce, key_transition and session_control in the emitter's declaration order, with the nested ordering and omitempty semantics the frozen signing projection uses.

Ports the bound session-open genesis validation so chains anchored with the g1: prefix verify, and tightens v1 shape checking. Malformed session_control, out-of-range chain_seq, unknown signed fields, malformed nested objects, misplaced key_transition markers, and restart opens not bound to the prior tail were all accepted with a valid signature and are now rejected.

Why it went unnoticed

The projection's source-of-truth comment pointed at the action record definition rather than the frozen signing projection, so the two drifted apart without anything failing. That comment now names the correct file.

Verification

Parity is proven against two independent chains captured from a real release binary, using different signing keys and different traffic. This package and the Go verifier return identical root hashes on both, and both exit zero.

One of those chains is committed as a regression fixture covering session open, heartbeat and close, evidence receipts, transcript root and checkpoint records. Parity is now checked against genuine emitter output rather than hand written data that can drift alongside the code.

Every new guard was verified by removing it and confirming its tests fail, then restoring it. That check caught one guard that passed the whole suite while being deleted, and the missing cases were added.

Known limitation

The field drift tests compare against a checked in copy of the projection field list, so this package and its own test can still drift together. A gate that genuinely pins the contract needs the emitter definition available at test time, which is a separate design decision and is not attempted here.

Not included

No version bump and no changelog entry. Release sequencing is a separate decision.

Summary by CodeRabbit

  • Enhancements

    • Added support for verifying session open, heartbeat, close, and key-transition records.
    • Improved receipt-chain validation, including session continuity, genesis anchoring, hash bindings, and restart handling.
    • Added stricter validation for malformed structures, unexpected fields, invalid numeric values, and inconsistent session states.
    • Improved cross-language canonicalization for nested session and key-transition data.
  • Tests

    • Added conformance coverage for a complete v3.2.0 live receipt chain.
    • Expanded regression tests for malformed receipts, session transitions, field ordering, and chain integrity.

The v1 canonical projection omitted nine fields the emitter signs, so every receipt produced by a current Pipelock failed signature verification. decision_phase is emitted on ordinary proxy decisions, which made the break total rather than partial. Adds decision_phase, defer_id, resolution_policy, resolution_source, session_id, session_id_original, run_nonce, key_transition and session_control in the emitter's declaration order, with the nested ordering and omitempty semantics the signing projection uses.

Ports the bound session-open genesis validation so chains anchored with the g1 prefix verify, and tightens v1 shape checking: malformed session_control, out-of-range chain_seq, unknown signed fields, malformed nested objects, misplaced key_transition markers, and restart opens not bound to the prior tail were all accepted with a valid signature and are now rejected.

Adds a captured chain from a real 3.2.0 binary as a regression fixture covering session open, heartbeat, close, evidence receipts, transcript root and checkpoint records. Parity is now proven against genuine emitter output rather than hand-written data that can drift alongside the code.

The projection's source-of-truth comment pointed at the wrong file, which is the likely reason this drift went unnoticed. It now names the frozen signing projection.
@coderabbitai

coderabbitai Bot commented Jul 24, 2026 •

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

@luckyPipewrench, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 10 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4adeb4a1-8945-4f9b-8545-8906b0e8ff66

📥 Commits

Reviewing files that changed from the base of the PR and between 68fdd69 and 6e5ed2d.

📒 Files selected for processing (5)
  • README.md
  • pipelock_verify/_canonical.py
  • pipelock_verify/_verify.py
  • tests/test_conformance.py
  • tests/test_regressions.py
📝 Walkthrough

Walkthrough

The change extends Go-compatible canonicalization for nested key-transition and session-control records, adds structured v1 receipt validation, and enforces session genesis, lifecycle, hash-linkage, and key-transition rules. Tests cover canonical ordering, malformed inputs, chain failures, and a v3.2.0 live recorder fixture.

Changes

Session Receipt Verification

Layer / File(s) Summary
Canonical nested payload ordering
pipelock_verify/_canonical.py, tests/test_field_drift.py
Adds field-order definitions and recursive zero-value emission for key-transition and session-control payloads, with regression coverage for Go-compatible ordering and genesis hashing.
V1 receipt shape validation
pipelock_verify/_verify.py, tests/test_regressions.py
Validates allowed fields, JSON types, integer bounds, nested structures, and session-control payload cardinality before signature and chain verification.
Session-chain linkage and state transitions
pipelock_verify/_verify.py, tests/test_regressions.py
Enforces session-open genesis, restart binding, heartbeat and close linkage, key-transition placement, run nonce continuity, and chained hash invariants.
Live-chain conformance coverage
tests/fixtures/v3_2_0_live_chain.jsonl, tests/test_conformance.py
Adds a v3.2.0 chained-session fixture and verifies it with a pinned public key and expected result metadata.

Estimated code review effort: 5 (Critical) | ~90+ minutes

Sequence Diagram(s)

sequenceDiagram
  participant TestFixture
  participant verify_chain
  participant ReceiptShapeValidator
  participant SessionState
  TestFixture->>verify_chain: submit signed receipt chain
  verify_chain->>ReceiptShapeValidator: validate v1 receipt structure
  ReceiptShapeValidator-->>verify_chain: return valid shape or rejection
  verify_chain->>SessionState: validate genesis and session-control linkage
  SessionState-->>verify_chain: update chain state or return failure
  verify_chain-->>TestFixture: return verification result and metadata
Loading
🚥 Pre-merge checks | ✅ 5
✅ Passed checks (5 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title accurately summarizes the main change: restoring v1 signing-projection parity with the Go emitter.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch fix/v1-canonical-parity

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

Comment @coderabbitai help to get the list of available commands.

@luckyPipewrench

Copy link
Copy Markdown
Member Author

/review deep

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 4

🧹 Nitpick comments (1)
pipelock_verify/_canonical.py (1)

38-39: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Pin the Go source-of-truth link to a tag or commit.

blob/main/internal/receipt/canonical.go moves as Go evolves, so this mirror's provenance is unverifiable after any upstream reordering. Reference a frozen ref instead.

🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@pipelock_verify/_canonical.py` around lines 38 - 39, Update the
source-of-truth comment near the ActionRecord field ordering to reference a
frozen Go repository tag or commit instead of the moving main branch, preserving
the existing canonical.go path and provenance context.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@pipelock_verify/_verify.py`:
- Line 68: Update canonicalize_receipt to reject any receipt key not represented
in the canonical _RECEIPT_FIELDS ordering, including ext, instead of validating
against the broader _V1_RECEIPT_FIELDS set and silently omitting it from the
chain hash. Ensure unknown keys fail before canonicalization while preserving
ordering and hashing for supported fields.
- Around line 327-330: Update _require_int to enforce the appropriate 64-bit
bounds instead of accepting arbitrary Python integers, reusing _require_int64
for signed fields and _require_uint64 for non-negative counters. Apply this
validation to redaction.total_redactions, redaction by_class values, and shield
counters so out-of-range receipt values are rejected consistently.

In `@tests/test_conformance.py`:
- Around line 149-153: Update the live v3.2.0 chain assertions in the
conformance test to also compare result.root_hash against the independently
computed expected Go root hash. Keep the existing validity, receipt count,
sequence, and timestamp assertions unchanged.
- Around line 135-148: Remove the v2 evidence receipts from the v3.2.0
live-chain conformance fixture in tests/fixtures/v3_2_0_live_chain.jsonl (lines
3-13) so test_v3_2_0_live_recorder_chain_verifies_with_pinned_key in
tests/test_conformance.py (lines 135-148) no longer includes unsupported
evidence_receipt_v2 entries; if v2 coverage is retained, test those receipts
separately via verify_evidence() rather than verify_chain().

---

Nitpick comments:
In `@pipelock_verify/_canonical.py`:
- Around line 38-39: Update the source-of-truth comment near the ActionRecord
field ordering to reference a frozen Go repository tag or commit instead of the
moving main branch, preserving the existing canonical.go path and provenance
context.
🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

  • Push a commit to this branch (recommended)
  • Create a new PR with the fixes

ℹ️ Review info
⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: db9ff7fa-42e8-4b76-b334-0173bfc6891b

📥 Commits

Reviewing files that changed from the base of the PR and between 329f1c7 and 68fdd69.

⛔ Files ignored due to path filters (1)
  • tests/fixtures/v3_2_0_live_chain.pub is excluded by !**/*.pub
📒 Files selected for processing (6)
  • pipelock_verify/_canonical.py
  • pipelock_verify/_verify.py
  • tests/fixtures/v3_2_0_live_chain.jsonl
  • tests/test_conformance.py
  • tests/test_field_drift.py
  • tests/test_regressions.py

Comment thread pipelock_verify/_verify.py Resolved
Comment thread pipelock_verify/_verify.py Resolved
Comment thread tests/test_conformance.py Resolved
Comment thread tests/test_conformance.py Resolved
…ields

The receipt envelope canonicalization omitted ext, but Go's ReceiptHash is a digest over the marshalled receipt and ext is a marshalled field. This verifier therefore agreed with Go only while ext was absent, and ext could be attached or altered on a receipt without changing the chain hash it commits to. ext is now ordered last in the envelope, matching the Go struct, and stays out of the signed action record projection where it does not belong.

Routes the redaction and shield counters through the int64 bound rather than accepting arbitrary integers, so a value the emitter could never produce and Go would refuse to decode is rejected here too. Drops the now unused unbounded helper.

Pins the live chain regression to the root hash the Go verifier independently computed for that fixture. Two verifiers can agree a chain is well formed while disagreeing on what it commits to, so validity alone did not cover the parity objective.
Go emits the ext bag verbatim into the bytes its receipt hash digests, so the chain hash commits to the producer's exact ext bytes. Parsing ext and re-serializing it changed key order, number spelling such as 1e+06, and escaping, which meant this verifier disagreed with Go on any receipt carrying ext even though the previous commit had started including ext in the envelope. The raw source slice is now kept whenever the caller supplies the original JSON, covering both the recorder detail object and the JSON string form.

Documents the one case that cannot preserve bytes, an already parsed receipt passed straight to the library, along with why that direction is fail closed rather than exploitable.

Joins a wrapped line in a README example so the formatter check passes on it.
@luckyPipewrench
luckyPipewrench merged commit 6a77e6f into main Jul 25, 2026
14 checks passed
@luckyPipewrench
luckyPipewrench deleted the fix/v1-canonical-parity branch July 25, 2026 01:01
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant