Skip to content

feat: verify endorsed receipt rotations - #38

Merged
luckyPipewrench merged 5 commits into
mainfrom
feat/rotation-endorsements
Jul 30, 2026
Merged

luckyPipewrench merged 5 commits into
mainfrom
feat/rotation-endorsements

Conversation

@luckyPipewrench

@luckyPipewrench luckyPipewrench commented Jul 30, 2026 •

Copy link
Copy Markdown
Member

Summary

  • verify old-key-signed ActionReceipt rotation endorsements from a pinned root
  • bind each transition to its recorder session, prior sequence and tail hash, and successor key
  • expose API and CLI support, add one- and two-rotation conformance coverage, and bump the package to 0.4.0

Summary by CodeRabbit

  • New Features

    • Added support for verifying receipt chains that use rotated signing keys.
    • Added rotation endorsement validation, including session binding and cryptographic integrity checks.
    • Added CLI options for session IDs, pinned root keys, and one or more rotation endorsements.
    • Exposed rotation verification capabilities through the package API.
    • Updated package version to 0.4.0.
  • Documentation

    • Expanded CLI guidance with examples for verifying chains across signing-key rotations.
    • Added conformance coverage for single and multiple key rotations.

@coderabbitai

coderabbitai Bot commented Jul 30, 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: 18 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: 0179a292-e533-4bfd-a424-5c9c58dc9851

📥 Commits

Reviewing files that changed from the base of the PR and between c79c02e and 590d5b1.

📒 Files selected for processing (12)
  • README.md
  • pipelock_verify/__main__.py
  • pipelock_verify/_rotation.py
  • pipelock_verify/_verify.py
  • pyproject.toml
  • requirements/ci.txt
  • requirements/fuzz.txt
  • requirements/pip.in
  • requirements/pip.txt
  • requirements/release.txt
  • tests/test_conformance.py
  • tests/test_regressions.py
📝 Walkthrough

Walkthrough

This change adds strict rotation endorsement APIs, integrates endorsements into rotated-chain verification, exposes session and endorsement options in the CLI, updates version and documentation metadata, and adds cross-language conformance fixtures and failure-case tests.

Changes

Rotation verification

Layer / File(s) Summary
Endorsement validation API
pipelock_verify/_rotation.py, pipelock_verify/__init__.py
Adds the validated RotationEndorsement model, strict parsing, canonicalization, Ed25519 verification, file loading, and public package exports.
Rotated chain traversal
pipelock_verify/_verify.py, tests/conformance/*, tests/test_conformance.py
Verifies endorsements before traversal, binds them to sessions and key-transition boundaries, tracks rotated segments, rejects ambiguous or unused endorsements, and tests single and repeated rotations.
CLI, release metadata, and fixtures
pipelock_verify/__main__.py, README.md, CHANGELOG.md, pyproject.toml, tests/conformance/*, tests/test_conformance.py
Adds --session-id and repeatable --rotation-endorsement options, updates version and CLI documentation, and adds endorsement validation fixtures and malformed-input coverage.

Estimated code review effort: 4 (Complex) | ~45 minutes

Sequence Diagram(s)

sequenceDiagram
  participant CLI
  participant verify_chain
  participant verify_rotation_endorsement
  participant _verify_chain_list
  CLI->>verify_chain: provide root key, session ID, and endorsements
  verify_chain->>verify_rotation_endorsement: validate endorsements
  verify_chain->>_verify_chain_list: verify receipt chain and transitions
  _verify_chain_list-->>verify_chain: return ChainResult
  verify_chain-->>CLI: report verification status
Loading

Possibly related PRs

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name Status Explanation Resolution
Docstring Coverage ⚠️ Warning Docstring coverage is 37.50% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (4 passed)
Check name Status Explanation
Description Check ✅ Passed Check skipped - CodeRabbit’s high-level summary is enabled.
Title check ✅ Passed The title clearly matches the main change: adding verification for signed rotation endorsements on receipt chains.
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 💡 1
📝 Generate docstrings 💡
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/rotation-endorsements

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.

@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: 3

🧹 Nitpick comments (3)
pipelock_verify/_rotation.py (1)

208-215: 🩺 Stability & Availability | 🔵 Trivial | ⚡ Quick win

"Bounded" read happens after the whole file is loaded.

read_bytes() pulls the entire file into memory; the _MAX_BYTES guard only applies afterwards inside verify_rotation_endorsement. Reading _MAX_BYTES + 1 bytes keeps the docstring's bound honest for oversized or non-regular files.

♻️ Proposed refactor
     file = Path(path)
     try:
-        data = file.read_bytes()
+        with file.open("rb") as handle:
+            data = handle.read(_MAX_BYTES + 1)
     except OSError as exc:
         raise InvalidReceiptError(f"read rotation endorsement: {exc}") from exc
     return verify_rotation_endorsement(data)
🤖 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/_rotation.py` around lines 208 - 215, Update
load_rotation_endorsement to read at most _MAX_BYTES + 1 bytes before calling
verify_rotation_endorsement, preserving the existing
OSError-to-InvalidReceiptError handling. Ensure the bounded read works for
oversized or non-regular files and allows downstream validation to detect data
exceeding _MAX_BYTES.
pipelock_verify/_verify.py (1)

1170-1178: 🎯 Functional Correctness | 🔵 Trivial | ⚡ Quick win

Normalize marker hex case like the successor key.

Line 1188 lowercases receipt["signer_key"] and expected_key is lowercased at line 1111, but marker.get("prior_signer_key") (and the endorsement's prior_signer_key, which _rotation._require_hex forces to lowercase) are compared as-is. An emitter that writes uppercase hex in key_transition would fail a legitimate rotation. Normalizing keeps the comparison symmetric across the four language implementations.

♻️ Proposed refactor
-            if marker.get("prior_signer_key") != expected_key:
+            if str(marker.get("prior_signer_key", "")).lower() != expected_key:
🤖 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/_verify.py` around lines 1170 - 1178, Normalize
marker.get("prior_signer_key") to lowercase before comparing it with
expected_key in the key-transition validation, matching the existing
normalization of receipt["signer_key"] and expected_key. Apply the same
normalization to the endorsement prior_signer_key comparison so uppercase hex
remains valid consistently across implementations.
README.md (1)

98-101: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Document the session_open binding requirement.

_verify_chain_list (pipelock_verify/_verify.py lines 1088-1107) requires, whenever endorsements are supplied, that every session_control.open in the chain carry recorder_session == session_id and that the root segment contain at least one such open. A chain without a signed session_open fails closed with "root receipt segment has no signed session_open recorder binding", which this section does not prepare the reader for.

📝 Proposed docs addition
 The endorsement is verified under the retiring key and bound to the exact
 prior sequence, tail hash, recorder session, and successor key. Missing,
 altered, duplicate, replayed, cross-session, and unused endorsements fail
 closed.
+
+`session_id` must equal the `recorder_session` in the chain's signed
+`session_open` records, and the root segment must contain one; chains without
+a signed session open cannot be verified with endorsements.
🤖 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 `@README.md` around lines 98 - 101, Update the endorsement verification
documentation near the described binding requirements to state that supplied
endorsements require every session_control.open to match session_id and the root
segment to contain at least one signed session_open; document that chains
without this binding fail closed with the corresponding validation error.
🤖 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/__main__.py`:
- Around line 107-114: Change the --rotation-endorsement argument in the
argument parser to use default=None instead of a mutable list, then normalize
args.rotation_endorsement at its consumption site (such as the
endorsement-loading comprehension) so missing values behave as an empty
collection while repeated main() calls remain isolated.

In `@pipelock_verify/_rotation.py`:
- Around line 199-204: Update the rotation endorsement verification flow around
Ed25519PublicKey.from_public_bytes: load the key separately from verify, catch
failures from key construction, and translate them into InvalidReceiptError.
Keep InvalidSignature handling for verification failures and preserve the
existing error message/context.

In `@pipelock_verify/_verify.py`:
- Line 1139: Update the sequencing logic around segment_base_seq and the gap
check so the root segment requires its first receipt to have chain_seq 0,
preserving the existing absolute-sequence validation. Apply segment-relative
sequencing only after a key_transition, and ensure the legacy _GENESIS_HASH path
cannot accept a truncated prefix without the bound g1: session_open genesis
validation.

---

Nitpick comments:
In `@pipelock_verify/_rotation.py`:
- Around line 208-215: Update load_rotation_endorsement to read at most
_MAX_BYTES + 1 bytes before calling verify_rotation_endorsement, preserving the
existing OSError-to-InvalidReceiptError handling. Ensure the bounded read works
for oversized or non-regular files and allows downstream validation to detect
data exceeding _MAX_BYTES.

In `@pipelock_verify/_verify.py`:
- Around line 1170-1178: Normalize marker.get("prior_signer_key") to lowercase
before comparing it with expected_key in the key-transition validation, matching
the existing normalization of receipt["signer_key"] and expected_key. Apply the
same normalization to the endorsement prior_signer_key comparison so uppercase
hex remains valid consistently across implementations.

In `@README.md`:
- Around line 98-101: Update the endorsement verification documentation near the
described binding requirements to state that supplied endorsements require every
session_control.open to match session_id and the root segment to contain at
least one signed session_open; document that chains without this binding fail
closed with the corresponding validation error.
🪄 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: 7ddda931-0148-42aa-93a2-c8b7511e9fba

📥 Commits

Reviewing files that changed from the base of the PR and between 3b700f1 and c79c02e.

📒 Files selected for processing (12)
  • CHANGELOG.md
  • README.md
  • pipelock_verify/__init__.py
  • pipelock_verify/__main__.py
  • pipelock_verify/_rotation.py
  • pipelock_verify/_verify.py
  • pyproject.toml
  • tests/conformance/g1-rotated-close-count-valid.jsonl
  • tests/conformance/g1-rotated-twice-valid.jsonl
  • tests/conformance/g1-rotation-endorsement-2.json
  • tests/conformance/g1-rotation-endorsement.json
  • tests/test_conformance.py

Comment thread pipelock_verify/__main__.py Resolved
Comment thread pipelock_verify/_rotation.py Resolved
Comment thread pipelock_verify/_verify.py Resolved
@luckyPipewrench
luckyPipewrench force-pushed the feat/rotation-endorsements branch from 8bf1ebc to 0c593bf Compare July 30, 2026 21:27
@luckyPipewrench luckyPipewrench self-assigned this Jul 30, 2026
@luckyPipewrench

Copy link
Copy Markdown
Member Author

/review deep

@github-actions

Copy link
Copy Markdown

AI Review: security deep (/review deep)

Model: gpt-5.5


Found material issues:

  1. severity: high
    file and function: pipelock_verify/_rotation.py, _decode() / verify_rotation_endorsement()
    why it matters / direction: The endorsement version field accepts non-integer JSON numbers such as 1.0 or 1e0 because the check is version != _VERSION, and in Python 1.0 == 1. _decode() then normalizes it back to integer 1 before constructing the canonical signing projection, so an existing valid endorsement can be changed from "version": 1 to "version": 1.0 and still verify here. Go unmarshalling into an integer field would reject 1.0. This is FAIL-OPEN: Python accepts endorsement JSON that Go rejects.
    concrete fix: Require the exact integer type for version, as is already done for prior_final_seq:

    version = value["version"]
    if isinstance(version, bool) or not isinstance(version, int) or version != _VERSION:
        raise InvalidReceiptError(f"unsupported rotation endorsement version {version!r}")

    Add regression tests for 1.0, 1e0, and "1".

  2. severity: high
    file and function: pipelock_verify/_rotation.py, verify_rotation_endorsement()
    why it matters / direction: Signature decoding uses bytes.fromhex(), which accepts and ignores ASCII whitespace. Because the endorsement signature field is not part of the signed canonical projection, an attacker can alter a valid endorsement from:

    "endorsement": "ed25519:<128 hex chars>"

    to include spaces/newlines inside the hex and it will still verify in Python. Go’s encoding/hex.DecodeString rejects whitespace. This is FAIL-OPEN: Python blesses an endorsement encoding Go would reject.
    concrete fix: Validate the signature string before decoding with an exact-format regex matching Go’s accepted format. For example, if uppercase hex is intended to match encoding/hex, allow only hex digits and exactly 128 of them:

    _ENDORSEMENT_SIG = re.compile(r"^ed25519:[0-9a-fA-F]{128}$")
    
    if _ENDORSEMENT_SIG.fullmatch(endorsement.endorsement) is None:
        raise InvalidReceiptError("invalid endorsement signature")
    signature = bytes.fromhex(endorsement.endorsement[len(_SIGNATURE_PREFIX):])

    If Go/emitter canonical format requires lowercase, use [0-9a-f] instead and enforce that consistently.

  3. severity: high
    file and function: pipelock_verify/_verify.py, _verify_chain_list()
    why it matters / direction: key_transition.prior_chain_seq is compared with != but never type-checked. Python equality lets invalid JSON shapes match valid integers, e.g. 2.0 == 2 and true == 1. A rotated boundary receipt with "prior_chain_seq": 2.0 can pass this verifier if the signature is otherwise valid, while Go strict unmarshalling into an integer/uint64 field would reject it. The same block also does not reject unknown fields in key_transition, so a transition object with extra fields can be accepted here even if Go’s strict struct decoding rejects it. This is FAIL-OPEN on rotated chain receipts.
    concrete fix: Add exact validation for the transition object before using it:

    _KEY_TRANSITION_FIELDS = {
        "prior_signer_key",
        "prior_chain_seq",
        "prior_chain_hash",
    }
    
    if not isinstance(marker, dict):
        ...
    unknown = set(marker) - _KEY_TRANSITION_FIELDS
    missing = _KEY_TRANSITION_FIELDS - set(marker)
    if unknown:
        return ChainResult(..., error=f"seq {seq}: key_transition contains unknown field {sorted(unknown)[0]}")
    if missing:
        return ChainResult(..., error=f"seq {seq}: key_transition missing required field {sorted(missing)[0]}")
    
    prior_chain_seq = marker["prior_chain_seq"]
    if (
        isinstance(prior_chain_seq, bool)
        or not isinstance(prior_chain_seq, int)
        or prior_chain_seq < 0
        or prior_chain_seq > _UINT64_MAX
    ):
        return ChainResult(..., error=f"seq {seq}: key_transition prior_chain_seq must be a uint64")

    Also validate prior_signer_key and prior_chain_hash as strings with the same lowercase-hex/hash shape Go accepts, rather than relying only on equality.

  4. severity: low
    file and function: pipelock_verify/_rotation.py, _decode() / verify_rotation_endorsement()
    why it matters / direction: Attacker-supplied in-memory dicts can still produce raw Python exceptions instead of clean InvalidReceiptErrors. For example, unknown = set(value) - _FIELDS followed by sorted(unknown)[0] can raise TypeError if unknown keys are of mixed incomparable types. Also, for direct str input, len(source.encode()) can raise UnicodeEncodeError on strings containing lone surrogates before the JSON parser/normalizer path handles them. This is not a signature bypass, but it violates the verifier expectation that attacker-controlled input returns a clean invalid result rather than a traceback.
    concrete fix: Normalize error handling for public inputs:

    try:
        ...
    except (UnicodeEncodeError, TypeError, ValueError) as exc:
        raise InvalidReceiptError(f"unmarshal rotation endorsement: {exc}") from exc

    And avoid sorting arbitrary key types directly; either require all keys to be strings up front or sort by repr only for error messages.

@luckyPipewrench

Copy link
Copy Markdown
Member Author

/review deep

@github-actions

Copy link
Copy Markdown

AI Review: security deep (/review deep)

Model: gpt-5.5


  1. severity: high
    file and function: pipelock_verify/_rotation.py, _decode
    why it matters / direction: version is not type-checked as an integer. JSON such as "version": 1.0 parses to Python float(1.0), and version != _VERSION is false, so the endorsement is accepted and then canonicalized as integer 1. Go unmarshalling into an integer field would reject 1.0. This is a fail-open parser differential: Python can verify and bless an endorsement shape Go rejects.
    concrete fix: Require an actual non-bool int before comparing:

    version = value["version"]
    if isinstance(version, bool) or not isinstance(version, int) or version != _VERSION:
        raise InvalidReceiptError(f"unsupported rotation endorsement version {version!r}")
  2. severity: high
    file and function: pipelock_verify/_rotation.py, verify_rotation_endorsement
    why it matters / direction: The endorsement signature suffix is decoded with bytes.fromhex(...), which ignores ASCII whitespace. A valid endorsement can be altered from e.g. ed25519:aabb... to ed25519:aa bb... or include escaped newlines in the JSON string, and Python will still verify it. Go’s hex.DecodeString rejects whitespace. Since endorsement itself is not covered by the signed canonical payload, this creates a fail-open differential for altered endorsement files that Go rejects.
    concrete fix: Validate the signature string syntax before decoding, using the exact format Go accepts/emits. If signatures must be lower-case canonical hex:

    _ENDORSEMENT_SIG = re.compile(r"^ed25519:[0-9a-f]{128}$")
    
    if _ENDORSEMENT_SIG.fullmatch(endorsement.endorsement) is None:
        raise InvalidReceiptError("invalid endorsement signature")
    signature = bytes.fromhex(endorsement.endorsement[len(_SIGNATURE_PREFIX):])

    If Go verifier intentionally accepts uppercase hex, use [0-9A-Fa-f], but still disallow all whitespace and require exactly 128 hex digits.

@luckyPipewrench

Copy link
Copy Markdown
Member Author

/review deep

@github-actions

Copy link
Copy Markdown

AI Review: security deep (/review deep)

Model: gpt-5.5


  1. severity: low
    file and function: pipelock_verify/_verify.py, _verify_chain_list()

    why it matters / direction:
    The new rotation pre-pass assumes parsed receipts and action_record values are dictionaries:

    (receipt.get("action_record") or {}).get("key_transition")
    ...
    _session_control_open(receipt.get("action_record") or {})

    On attacker-supplied JSONL such as an object with a non-empty array/string action_record, this can raise AttributeError before returning a clean ChainResult(valid=False, ...). With rotation endorsements supplied, this is now reachable in the added pre-scan path. Go’s strict unmarshal/validation would reject the malformed shape cleanly; Python can instead surface a traceback. This is not a signature fail-open, but it is an attacker-controlled error-path correctness issue.

    concrete fix:
    Normalize/validate shape before every .get() in the pre-pass and return an invalid chain result on malformed receipts, e.g.:

    def _action_record_or_invalid(receipt: Any, index: int) -> dict[str, Any] | ChainResult:
        if not isinstance(receipt, dict):
            return ChainResult(valid=False, broken_at_seq=index, error="receipt must be an object")
        ar = receipt.get("action_record") or {}
        if not isinstance(ar, dict):
            return ChainResult(
                valid=False,
                broken_at_seq=index,
                error="action_record must be an object",
            )
        return ar

    Then use that helper in the first_boundary scan, session-open scan, and main loop before accessing ar.get(...). Alternatively, inline the isinstance(..., dict) checks in those three places and return ChainResult(valid=False, ...) rather than allowing an exception to escape.

@luckyPipewrench

Copy link
Copy Markdown
Member Author

/review deep

@github-actions

Copy link
Copy Markdown

AI Review: security deep (/review deep)

Model: gpt-5.5


No material security or correctness issues found in this diff.

@luckyPipewrench
luckyPipewrench merged commit f70bca2 into main Jul 30, 2026
14 checks passed
@luckyPipewrench
luckyPipewrench deleted the feat/rotation-endorsements branch July 30, 2026 21:56
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