diff --git a/.github/workflows/canonical-contract-drift.yml b/.github/workflows/canonical-contract-drift.yml new file mode 100644 index 0000000..7f7d651 --- /dev/null +++ b/.github/workflows/canonical-contract-drift.yml @@ -0,0 +1,34 @@ +name: Canonical Contract Drift + +on: + schedule: + - cron: '17 10 * * *' + workflow_dispatch: + inputs: + go_ref: + description: 'Go branch, tag, or commit SHA to resolve and check' + required: false + default: main + +permissions: + contents: read + +jobs: + go-canonical-v1-contract: + runs-on: ubuntu-latest + timeout-minutes: 5 + steps: + - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0 # v7 + with: + persist-credentials: false + + - name: Set up Python + uses: actions/setup-python@ece7cb06caefa5fff74198d8649806c4678c61a1 # v6.3.0 + with: + python-version: '3.12' + + - name: Check Go canonical v1 signing projection + env: + GITHUB_TOKEN: ${{ github.token }} + PIPELOCK_GO_REF: ${{ github.event.inputs.go_ref || 'main' }} + run: python scripts/check_go_canonical_contract.py diff --git a/scripts/check_go_canonical_contract.py b/scripts/check_go_canonical_contract.py new file mode 100644 index 0000000..bd7b949 --- /dev/null +++ b/scripts/check_go_canonical_contract.py @@ -0,0 +1,352 @@ +"""Check pipelock-verify's v1 canonical contract against the Go emitter. + +The fast pytest guard in ``tests/test_field_drift.py`` compares the Python +implementation to a checked-in mirror. This script is the authoritative drift +gate: it fetches the live Go source, extracts the canonical JSON struct tags, +and fails when the Python projection no longer matches. +""" + +from __future__ import annotations + +import argparse +import dataclasses +import difflib +import json +import os +import pathlib +import re +import sys +import urllib.error +import urllib.request +from collections.abc import Iterable, Mapping, Sequence + +_REPO_ROOT = pathlib.Path(__file__).resolve().parent.parent + +GO_OWNER = "luckyPipewrench" +GO_REPO = "pipelock" +GO_SOURCE_PATH = "internal/receipt/canonical.go" +DEFAULT_REF = "main" + +GO_STRUCTS: tuple[str, ...] = ( + "actionRecordCanonicalV1", + "taintSourceRefCanonicalV1", + "keyTransitionCanonicalV1", + "sessionControlCanonicalV1", + "sessionOpenCanonicalV1", + "sessionHeartbeatCanonicalV1", + "sessionCloseCanonicalV1", + "redactionSummaryCanonicalV1", + "shieldSummaryCanonicalV1", +) + +# Any Go type named *CanonicalV1 is a signing projection this package must +# mirror. Discovered rather than predeclared, so an addition on the Go side +# cannot pass unnoticed. +CANONICAL_STRUCT_RE = re.compile(r"^[A-Za-z_][A-Za-z0-9_]*CanonicalV1$") +STRUCT_RE = re.compile(r"^type\s+(?P[A-Za-z_][A-Za-z0-9_]*)\s+struct\s*\{\s*$") +FIELD_RE = re.compile( + r"^(?P[A-Z][A-Za-z0-9_]*)\s+(?P.+?)\s+`json:\"(?P[^\"]+)\"`" + r"(?:\s*//.*)?$" +) +COMMENT_RE = re.compile(r"^\s*(?://.*)?$") +COMMIT_SHA_RE = re.compile(r"^[0-9a-f]{40}$") + + +@dataclasses.dataclass(frozen=True, slots=True) +class FieldSpec: + json_name: str + omitempty: bool + + def render(self, index: int) -> str: + return f"{index:02d} {self.json_name} omitempty={str(self.omitempty).lower()}" + + +class ContractCheckError(RuntimeError): + """Base class for fail-closed contract check errors.""" + + +class ContractFetchError(ContractCheckError): + """Raised when the Go source cannot be resolved or fetched.""" + + +class ContractParseError(ContractCheckError): + """Raised when the Go source shape is not recognised.""" + + +class ContractDriftError(ContractCheckError): + """Raised when the extracted Go contract differs from Python.""" + + +def _strip_nested_kind(fields: Sequence[tuple[str, bool, str | None]]) -> list[FieldSpec]: + return [FieldSpec(json_name, omitempty) for json_name, omitempty, _nested_kind in fields] + + +def python_contract() -> dict[str, list[FieldSpec]]: + """Return the Python v1 contract in Go canonical struct names. + + Imported here, from THIS checkout, rather than at module scope. Running + `python scripts/.py` puts scripts/ on sys.path and the repository root + nowhere, so a top-level import either fails outright (CI, where nothing is + installed) or silently reads an unrelated installed copy and reports a pass + that means nothing. + """ + + if str(_REPO_ROOT) not in sys.path: + sys.path.insert(0, str(_REPO_ROOT)) + + from pipelock_verify._canonical import ( + _ACTION_RECORD_FIELDS, + _KEY_TRANSITION_FIELDS, + _REDACTION_FIELDS, + _SESSION_CLOSE_FIELDS, + _SESSION_CONTROL_FIELDS, + _SESSION_HEARTBEAT_FIELDS, + _SESSION_OPEN_FIELDS, + _SHIELD_FIELDS, + _TAINT_SOURCE_FIELDS, + ) + + return { + "actionRecordCanonicalV1": _strip_nested_kind(_ACTION_RECORD_FIELDS), + "taintSourceRefCanonicalV1": _strip_nested_kind(_TAINT_SOURCE_FIELDS), + "keyTransitionCanonicalV1": _strip_nested_kind(_KEY_TRANSITION_FIELDS), + "sessionControlCanonicalV1": _strip_nested_kind(_SESSION_CONTROL_FIELDS), + "sessionOpenCanonicalV1": _strip_nested_kind(_SESSION_OPEN_FIELDS), + "sessionHeartbeatCanonicalV1": _strip_nested_kind(_SESSION_HEARTBEAT_FIELDS), + "sessionCloseCanonicalV1": _strip_nested_kind(_SESSION_CLOSE_FIELDS), + "redactionSummaryCanonicalV1": _strip_nested_kind(_REDACTION_FIELDS), + "shieldSummaryCanonicalV1": _strip_nested_kind(_SHIELD_FIELDS), + } + + +def _request(url: str, *, timeout: float) -> bytes: + headers = { + "Accept": "application/vnd.github+json", + "User-Agent": "pipelock-verify-canonical-contract-gate", + } + # Named gh_token, not token: the self-scan's "credential in URL" pattern + # matches any assignment whose name starts with a credential word, with no + # URL involved, and fails the security check on a false positive. + gh_token = os.environ.get("GITHUB_TOKEN") + if gh_token: + headers["Authorization"] = f"Bearer {gh_token}" + request = urllib.request.Request(url, headers=headers) + try: + with urllib.request.urlopen(request, timeout=timeout) as response: + return response.read() + except (OSError, urllib.error.URLError) as exc: + raise ContractFetchError(f"failed to fetch {url}: {exc}") from exc + + +def resolve_ref(ref: str, *, timeout: float) -> str: + """Resolve a branch or tag to a commit SHA so the later raw fetch is pinned.""" + + if COMMIT_SHA_RE.fullmatch(ref): + return ref + url = f"https://api.github.com/repos/{GO_OWNER}/{GO_REPO}/commits/{ref}" + raw = _request(url, timeout=timeout) + try: + payload = json.loads(raw.decode("utf-8")) + sha = payload["sha"] + except (KeyError, TypeError, UnicodeDecodeError, json.JSONDecodeError) as exc: + raise ContractFetchError(f"could not resolve Go ref {ref!r} from {url}") from exc + if not isinstance(sha, str) or not COMMIT_SHA_RE.fullmatch(sha): + raise ContractFetchError(f"Go ref {ref!r} resolved to invalid commit SHA {sha!r}") + return sha + + +def fetch_go_source(ref: str, *, timeout: float) -> tuple[str, str]: + """Fetch canonical.go at a concrete commit and return ``(source, sha)``.""" + + resolved_sha = resolve_ref(ref, timeout=timeout) + url = f"https://raw.githubusercontent.com/{GO_OWNER}/{GO_REPO}/{resolved_sha}/{GO_SOURCE_PATH}" + raw = _request(url, timeout=timeout) + try: + return raw.decode("utf-8"), resolved_sha + except UnicodeDecodeError as exc: + raise ContractFetchError(f"Go source {url} is not valid UTF-8") from exc + + +def read_source_arg(source: str) -> tuple[str, str]: + if source == "-": + return sys.stdin.read(), "stdin" + try: + with open(source, encoding="utf-8") as handle: + return handle.read(), source + except OSError as exc: + raise ContractFetchError(f"failed to read Go source {source}: {exc}") from exc + + +def extract_go_contract( + source: str, + *, + struct_names: Iterable[str] = GO_STRUCTS, +) -> dict[str, list[FieldSpec]]: + """Extract JSON field order and omitempty semantics from canonical structs.""" + + wanted = tuple(struct_names) + contract: dict[str, list[FieldSpec]] = {} + lines = source.splitlines() + index = 0 + while index < len(lines): + match = STRUCT_RE.match(lines[index].strip()) + if not match: + index += 1 + continue + struct_name = match.group("name") + index += 1 + body: list[str] = [] + while index < len(lines) and lines[index].strip() != "}": + body.append(lines[index]) + index += 1 + if index >= len(lines): + raise ContractParseError(f"unterminated Go struct {struct_name}") + # Parse every canonical-v1 projection found, not just the predeclared + # ones. Restricting to a fixed list made the "unexpected struct" check + # below unreachable: a NEW signed projection added on the Go side would + # be skipped in silence and the gate would pass without a Python + # counterpart existing at all. + if struct_name in wanted or CANONICAL_STRUCT_RE.match(struct_name): + contract[struct_name] = _parse_struct_fields(struct_name, body) + index += 1 + + missing = [struct_name for struct_name in wanted if struct_name not in contract] + if missing: + joined = ", ".join(missing) + raise ContractParseError(f"missing expected canonical Go struct(s): {joined}") + return contract + + +def _parse_struct_fields(struct_name: str, body: Sequence[str]) -> list[FieldSpec]: + fields: list[FieldSpec] = [] + for offset, raw_line in enumerate(body, start=1): + line = raw_line.strip() + if COMMENT_RE.fullmatch(line): + continue + match = FIELD_RE.match(line) + if not match: + raise ContractParseError( + f"unrecognised field declaration in {struct_name} line {offset}: {raw_line!r}" + ) + tag = match.group("tag") + parts = tag.split(",") + json_name = parts[0] + options = set(parts[1:]) + if not json_name or json_name == "-": + raise ContractParseError( + f"unsupported json tag in {struct_name} line {offset}: {tag!r}" + ) + unsupported = options - {"omitempty"} + if unsupported: + joined = ", ".join(sorted(unsupported)) + raise ContractParseError( + f"unsupported json tag option(s) in {struct_name} line {offset}: {joined}" + ) + fields.append(FieldSpec(json_name=json_name, omitempty="omitempty" in options)) + if not fields: + raise ContractParseError(f"canonical Go struct {struct_name} has no JSON fields") + return fields + + +def diff_contracts( + go_contract: Mapping[str, Sequence[FieldSpec]], + expected_contract: Mapping[str, Sequence[FieldSpec]], +) -> list[str]: + diffs: list[str] = [] + for struct_name, expected_fields in expected_contract.items(): + actual_fields = go_contract.get(struct_name) + if actual_fields is None: + diffs.append(f"Go contract missing parsed struct {struct_name}") + continue + if list(actual_fields) == list(expected_fields): + continue + expected_lines = [ + field.render(index) for index, field in enumerate(expected_fields, start=1) + ] + actual_lines = [field.render(index) for index, field in enumerate(actual_fields, start=1)] + diffs.extend( + difflib.unified_diff( + expected_lines, + actual_lines, + fromfile=f"python/{struct_name}", + tofile=f"go/{struct_name}", + lineterm="", + ) + ) + extra = sorted(set(go_contract) - set(expected_contract)) + if extra: + joined = ", ".join(extra) + diffs.append(f"Go contract has unexpected parsed struct(s): {joined}") + return diffs + + +def check_source( + source: str, + *, + source_label: str, + expected_contract: Mapping[str, Sequence[FieldSpec]] | None = None, + struct_names: Iterable[str] = GO_STRUCTS, +) -> None: + expected = expected_contract if expected_contract is not None else python_contract() + go_contract = extract_go_contract(source, struct_names=struct_names) + diffs = diff_contracts(go_contract, expected) + if diffs: + details = "\n".join(diffs) + raise ContractDriftError( + "Go canonical v1 signing projection drifted from pipelock-verify.\n" + f"Go source: {source_label}\n" + f"Inspect {GO_SOURCE_PATH}; update pipelock_verify/_canonical.py and the " + "checked-in mirror tests together.\n\n" + f"{details}" + ) + + +def parse_args(argv: Sequence[str]) -> argparse.Namespace: + parser = argparse.ArgumentParser( + description=( + "Fail closed if pipelock-verify's v1 canonical projection drifts from " + "the Go internal/receipt/canonical.go emitter." + ) + ) + parser.add_argument( + "--ref", + default=os.environ.get("PIPELOCK_GO_REF", DEFAULT_REF), + help=( + "Go branch, tag, or 40-character commit SHA to check. Branches/tags are " + "resolved to a concrete commit before fetching canonical.go." + ), + ) + parser.add_argument( + "--source", + help="Read Go source from this file path instead of fetching. Use '-' for stdin.", + ) + parser.add_argument( + "--timeout", + type=float, + default=20.0, + help="Network timeout in seconds for each GitHub request.", + ) + return parser.parse_args(argv) + + +def main(argv: Sequence[str] | None = None) -> int: + args = parse_args(sys.argv[1:] if argv is None else argv) + try: + if args.source: + source, source_label = read_source_arg(args.source) + else: + source, resolved_sha = fetch_go_source(args.ref, timeout=args.timeout) + source_label = ( + f"github.com/{GO_OWNER}/{GO_REPO}@{resolved_sha}:{GO_SOURCE_PATH} " + f"(requested ref {args.ref!r})" + ) + check_source(source, source_label=source_label) + except ContractCheckError as exc: + print(f"FAIL: {exc}", file=sys.stderr) + return 1 + print(f"PASS: Python canonical v1 contract matches {source_label}") + return 0 + + +if __name__ == "__main__": + raise SystemExit(main()) diff --git a/tests/test_field_drift.py b/tests/test_field_drift.py index 97c1e76..96630ff 100644 --- a/tests/test_field_drift.py +++ b/tests/test_field_drift.py @@ -37,6 +37,9 @@ ) from pipelock_verify._verify import _compute_session_open_genesis, verify +# Fast offline mirror guard. The authoritative live drift gate is +# scripts/check_go_canonical_contract.py, which fetches Go's +# internal/receipt/canonical.go at a resolved commit and fails closed. CANONICAL_GO_MESSAGE = ( "Checked-in Python mirror of Go internal/receipt/canonical.go " "actionRecordCanonicalV1 drifted; refresh this list from Go origin/main." diff --git a/tests/test_go_canonical_contract_gate.py b/tests/test_go_canonical_contract_gate.py new file mode 100644 index 0000000..dd93097 --- /dev/null +++ b/tests/test_go_canonical_contract_gate.py @@ -0,0 +1,138 @@ +"""Offline proof tests for the authoritative Go canonical drift gate.""" + +from __future__ import annotations + +import importlib.util +import sys +from pathlib import Path + +import pytest + +SCRIPT_PATH = Path(__file__).resolve().parents[1] / "scripts" / "check_go_canonical_contract.py" +SCRIPT_SPEC = importlib.util.spec_from_file_location("check_go_canonical_contract", SCRIPT_PATH) +assert SCRIPT_SPEC is not None +contract_gate = importlib.util.module_from_spec(SCRIPT_SPEC) +assert SCRIPT_SPEC.loader is not None +sys.modules[SCRIPT_SPEC.name] = contract_gate +SCRIPT_SPEC.loader.exec_module(contract_gate) + +ContractDriftError = contract_gate.ContractDriftError +ContractFetchError = contract_gate.ContractFetchError +ContractParseError = contract_gate.ContractParseError +FieldSpec = contract_gate.FieldSpec +check_source = contract_gate.check_source +extract_go_contract = contract_gate.extract_go_contract +read_source_arg = contract_gate.read_source_arg + +STRUCT_NAME = "actionRecordCanonicalV1" + +BASE_GO_SOURCE = """ +package receipt + +type actionRecordCanonicalV1 struct { + Version int `json:"version"` + ActionID string `json:"action_id"` + ParentActionID string `json:"parent_action_id,omitempty"` +} +""" + +EXPECTED_CONTRACT: dict[str, list[FieldSpec]] = { + STRUCT_NAME: [ + FieldSpec("version", False), + FieldSpec("action_id", False), + FieldSpec("parent_action_id", True), + ] +} + + +def _check_test_source(source: str) -> None: + check_source( + source, + source_label="test canonical.go", + expected_contract=EXPECTED_CONTRACT, + struct_names=(STRUCT_NAME,), + ) + + +def test_extracts_go_json_field_order_and_omitempty(): + assert extract_go_contract(BASE_GO_SOURCE, struct_names=(STRUCT_NAME,)) == EXPECTED_CONTRACT + + +def test_gate_fails_when_go_adds_signed_field(): + changed = BASE_GO_SOURCE.replace( + ' ActionID string `json:"action_id"`\n', + ' ActionID string `json:"action_id"`\n' + ' NewSignedField string `json:"new_signed_field,omitempty"`\n', + ) + + with pytest.raises(ContractDriftError) as error: + _check_test_source(changed) + + assert "+03 new_signed_field omitempty=true" in str(error.value) + assert "internal/receipt/canonical.go" in str(error.value) + + +def test_gate_fails_when_go_reorders_signed_fields(): + changed = BASE_GO_SOURCE.replace( + ' ActionID string `json:"action_id"`\n' + ' ParentActionID string `json:"parent_action_id,omitempty"`\n', + ' ParentActionID string `json:"parent_action_id,omitempty"`\n' + ' ActionID string `json:"action_id"`\n', + ) + + with pytest.raises(ContractDriftError) as error: + _check_test_source(changed) + + message = str(error.value) + assert "--- python/actionRecordCanonicalV1" in message + assert "+++ go/actionRecordCanonicalV1" in message + + +def test_gate_fails_when_go_omitempty_changes(): + changed = BASE_GO_SOURCE.replace( + ' ParentActionID string `json:"parent_action_id,omitempty"`\n', + ' ParentActionID string `json:"parent_action_id"`\n', + ) + + with pytest.raises(ContractDriftError) as error: + _check_test_source(changed) + + assert "-03 parent_action_id omitempty=true" in str(error.value) + assert "+03 parent_action_id omitempty=false" in str(error.value) + + +def test_gate_fails_closed_when_go_shape_is_unrecognised(): + changed = BASE_GO_SOURCE.replace( + ' ActionID string `json:"action_id"`\n', + ' ActionID, ParentActionID string `json:"action_id"`\n', + ) + + with pytest.raises(ContractParseError): + _check_test_source(changed) + + +def test_gate_fails_closed_when_source_cannot_be_read(tmp_path): + missing_source = tmp_path / "missing-canonical.go" + + with pytest.raises(ContractFetchError): + read_source_arg(str(missing_source)) + + +def test_gate_rejects_a_newly_added_go_canonical_projection(): + """A NEW *CanonicalV1 struct on the Go side must fail the gate. + + The parser originally walked a predeclared list of struct names, which made + the unexpected-struct branch unreachable: a signing projection added on the + Go side was skipped in silence and the gate passed while this package had no + counterpart for it. Structs are discovered now, so the branch can fire. + """ + changed = BASE_GO_SOURCE + ( + "\ntype brandNewThingCanonicalV1 struct {\n" + ' SecretField string `json:"secret_field"`\n' + "}\n" + ) + + with pytest.raises(ContractDriftError) as excinfo: + _check_test_source(changed) + + assert "brandNewThingCanonicalV1" in str(excinfo.value)