subcheck 0.4.0__tar.gz → 0.4.2__tar.gz

subcheck-0.4.2/.github/workflows/ci.yml

@@ -0,0 +1,76 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install
+        run: |
+          python -m pip install --upgrade pip
+          pip install -e ".[dev]"
+      - name: Lint (ruff)
+        run: ruff check .
+      - name: Type check (mypy)
+        run: mypy
+      - name: Security lint (bandit)
+        run: bandit -q -r src
+      - name: Tests (pytest)
+        run: pytest -q --cov=subcheck --cov-report=term-missing
+
+  # The composite action is the entry point the README advertises
+  # (uses: Dashtid/subcheck@vX). Nothing here had ever executed it, so a break
+  # in action.yml would have surfaced in a user's pipeline, not in CI.
+  # Runs only on same-repo pushes/PRs: a fork PR gets no OIDC token, and the
+  # step exits 2 by design when ACTIONS_ID_TOKEN_REQUEST_TOKEN is absent.
+  action:
+    if: github.event_name == 'push' || github.event.pull_request.head.repo.full_name == github.repository
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write   # mint the OIDC token the action inspects
+    steps:
+      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+      - name: Write a policy matching this very job's token
+        # Context values go through env, never interpolated into run: - the same
+        # template-injection rule action.yml follows.
+        env:
+          REPO: ${{ github.repository }}
+          OWNER: ${{ github.repository_owner }}
+        run: |
+          {
+            echo "issuer: https://token.actions.githubusercontent.com"
+            echo "audience: sts.amazonaws.com"
+            echo "claims:"
+            echo "  repository:"
+            echo "    equals: \"$REPO\""
+            echo "  repository_owner:"
+            echo "    equals: \"$OWNER\""
+            echo "  ref:"
+            echo "    glob: \"refs/*\""
+          } > ci-policy.yaml
+          cat ci-policy.yaml
+      - name: Run the action against it
+        uses: ./
+        with:
+          policy: ci-policy.yaml
+      - name: JSON format still works
+        uses: ./
+        with:
+          policy: ci-policy.yaml
+          format: json

{subcheck-0.4.0 → subcheck-0.4.2}/ARCHITECTURE.md

@@ -103,8 +103,15 @@ These are decisions, not gaps. See `BACKLOG.md` → Non-goals.
 - **It does not simulate cloud trust conditions.** Your policy's `glob` is not "what AWS would do."
   Grading real cloud rules is subvectors' job. Blurring that line risks being wrong in exactly the
   way subvectors exists to catch.
-- **It is not released.** No PyPI package, no git tag, no `action.yml` — on purpose. The launch is
-  parked until the flagship and the companion article are ready.
+
+> [i] **A third entry used to sit here and is now false on both counts.** It read: *"It is not
+> released. No PyPI package, no git tag, no `action.yml` — on purpose. The launch is parked until
+> the flagship and the companion article are ready."* Retired 2026-08-29. subcheck v0.2.0 shipped to
+> PyPI on 2026-08-24 via OIDC trusted publishing (`pip install subcheck`), tag `v0.2.0` and the
+> `action.yml` composite wrapper are live, and subvectors released the same day — so the flagship
+> half of the gate fired. The article half no longer exists: the article programme was closed
+> 2026-08-29 in favour of artifact-shaped proof (shipped packages, merged upstream PRs, the cited
+> subvectors corpus). Release status is not a non-goal any more; it is history.
 
 ## Running it
 

{subcheck-0.4.0 → subcheck-0.4.2}/BACKLOG.md

@@ -12,9 +12,12 @@ expectation language and a fail-fast CI gate. It is **not** a cloud-trust-condit
 provider's job at assume-time. Keep that line sharp (see Non-goals).
 
 **Sequencing.** subvectors is the flagship; subcheck is the finished companion. The original plan
-was to keep subcheck parked until a subvectors v0.1 + article #1 launch burst — but as of
-2026-08-16 that gate has partly fired on its own (subcheck is pinned at public slot #2) while both
-gate conditions remain outside your control. See the DECISION in Phase 4 before doing more here.
+was to keep subcheck parked until a subvectors v0.1 + article #1 launch burst. **That gate is gone
+— retired 2026-08-29.** Every leg of it dissolved on its own: the pin fired ahead of schedule
+(public slot #2, 2026-08-16), both packages shipped to PyPI regardless (subcheck v0.2.0 and
+subvectors v0.2.0, both 2026-08-24), and the article programme was **closed 2026-08-29** — article
+#1 was never drafted and now never will be. Nothing in this repo is gated on anything: ship a slice
+when it is ready. Phase 4 below is the shipping history, not a gate.
 
 Status keys: `[ ]` todo · `[~]` in progress · `[x]` done this cycle.
 
@@ -61,8 +64,9 @@ new/renamed/transferred repos on **2026-07-15**; name-based policies silently st
   `parse_github_sub` agrees with the subvectors subject grammar on all 9 (legacy, both immutable ID
   forms, case-sensitivity, nested-branch ref, tag ref, customized multi-segment sub). One-way,
   test-time, self-contained (CI-safe) — subvectors is never a runtime dependency.
-- `[ ]` (upstream, separate subvectors session) record subcheck as the corpus's first consumer in
-  subvectors' BACKLOG "Consumer-adoption" item — the adoption datapoint its success metric tracks.
+- `[x]` (upstream) subcheck recorded as the corpus's first consumer in subvectors' BACKLOG
+  "Consumer-adoption" item — **done 2026-08-25**, together with the decoder bug that consumption
+  caught (the combined-customization subject; fixed in 0.3.0).
 
 ## Phase 3 — ship it properly (DE-GATED 2026-08-22 — decision taken, executed)
 
@@ -86,7 +90,11 @@ new/renamed/transferred repos on **2026-07-15**; name-based policies silently st
 
 - `[x]` **Set the GitHub pin** — done, and at slot **#2** (verified 2026-08-16), ahead of its gate.
 - `[ ]` Record the demo GIF/asciinema (a PR failing on `sub=...:pull_request`).
-- `[ ]` Coordinated burst *with subvectors*: article -> Show HN -> one subreddit -> LinkedIn.
+- `[ ]` Coordinated burst *with subvectors* — **article leg dropped 2026-08-29** (the article
+  programme is closed; the shipped artifact is the announcement). What remains, if it is ever worth
+  the evening: Show HN -> one subreddit -> LinkedIn, all pointing at `pip install subcheck` and the
+  subvectors corpus. Low priority by design — an installable package and a merged upstream PR are
+  the durable proof; a launch post decays in a week.
 
 > [x] **DECISION RESOLVED 2026-08-24 — de-gated and shipped.** v0.2.0 is live on PyPI via
 > trusted publishing; both names reserved as pending publishers. The pin at slot #2 now points
@@ -96,12 +104,17 @@ new/renamed/transferred repos on **2026-07-15**; name-based policies silently st
 ## Phase 2.5 — technical-soundness pass (done this cycle)
 
 Driven by a research fan-out (article-saturation + primary-source verification + adversarial
-refutation) before any article gets published. Findings that were *facts*, fixed here:
+refutation) originally run ahead of an article that was never drafted — the article programme
+closed 2026-08-29. [i] The pass keeps all of its value regardless: its output was never the article,
+it was the corrections below, which landed in the code and the README. Findings that were *facts*,
+fixed here:
 
 - `[x]` **The fork claim was wrong.** A fork's `pull_request` cannot mint a token for the upstream
   repo — `id-token: write` is downgraded and `ACTIONS_ID_TOKEN_REQUEST_TOKEN` is never injected.
-  README now lists the real paths. This error is endemic to the published literature; do not
-  reintroduce it, and it is worth an article of its own (see below).
+  README now lists the real paths. This error is endemic to the third-party literature; do not
+  reintroduce it. **Kept as reference material, not as an article idea (2026-08-29).** The durable
+  home for a correction this sharp is the README plus an upstream PR against a tool that encodes the
+  wrong model — an artifact someone can cite, not a post that scrolls away.
 - `[x]` Half-immutable subjects (`@id` on one segment) reported as `malformed`, not `immutable`.
 - `[x]` Migration hints suppressed for non-github.com issuers (GHES keeps mutable names).
 - `[x]` Legacy hint no longer implies format follows from repo age (org/repo opt-in exists).
@@ -122,6 +135,33 @@ Open follow-ups from the same pass:
 
 ## Correctness / quality parking lot
 
+- `[x]` **Policy-shape validation — DONE 2026-08-31 (v0.4.1), and it found two silent fail-opens.**
+  A 22-agent audit sweep (5 lenses, each finding then adversarially verified; roughly half the raw
+  findings were refuted) turned up two ways a malformed policy passed every token it was written to
+  reject, both reproduced through the shipped CLI: claim rules written at the **top level** were
+  dropped without a word (only `issuer`/`audience` were read, so the gate went green having checked
+  the issuer alone), and **`in:` given a string** became Python substring containment, so `prod`
+  satisfied `in: production` and so did the empty string. Rule *keys* had been validated since the
+  start; rule *values* never were. Both now raise on the documented rc=2 path, along with a
+  non-compiling `matches`, a non-string `glob`, and a quoted `required`.
+  **The lesson worth keeping:** green CI, 93% coverage and a tidy backlog all held while these
+  shipped, because no test had ever written a *malformed policy*. Coverage measures the lines you
+  execute, not the inputs you never thought to send. A gate whose own config can silently weaken it
+  is the failure this tool exists to prevent, so policy-shape tests belong next to claim tests.
+
+- `[x]` **Claims-shape validation — DONE 2026-09-01 (v0.4.2), found by asking 0.4.1's question of
+  the other input.** The tool takes two things: a policy and a set of claims. v0.4.1 hardened the
+  policy and never asked the same question of the claims, and that gap *was* the bug — `--claims`
+  went straight to `json.loads` while `decode_claims` had always required a JSON object, so the two
+  claim-input paths disagreed about what claims are. A list-shaped claims file made `validate()`
+  return **all PASS** (`rule.name not in claims` is legal on any container, so every rule read as
+  absent, which is PASS when optional); the only thing preventing a green gate was an unrelated
+  crash a few lines later in `build_report`. `--claims <non-object> --format json` exited **0** and
+  echoed the garbage back. Everything else exited **1** on a traceback — bad input wearing the
+  gate-failure exit code, the same confusion 0.4.1 fixed one input over.
+  **The generalisable move:** when a fix hardens one input, check the others *for the same defect*
+  before closing it out. Symmetry between inputs is cheap to check and, here, was the whole finding.
+
 - `[ ]` `--fail-on <severity>` threshold gating — today any single required-but-missing medium claim
   fails the whole gate (`report.py` `passed = all(PASS)`); no way to gate on high only.
 - `[x]` `exp`/`iat`/`nbf` time checks — **DONE 2026-08-25 (v0.4.0)**, as advisory NOTES, never
@@ -145,10 +185,18 @@ Open follow-ups from the same pass:
   subject parses, not whether it parses *correctly*.
 - `[ ]` Decide `equals`/`in` type handling: coerce, or keep type-strict + documented (currently the
   latter).
-- `[ ]` Close test-coverage holes (92% now): `glob` branch, `--token-file`, `--token -` stdin,
-  `load_policy_file` suffix logic, `to_json`/summary counts, and the `rc=2` bad-policy/bad-JSON paths.
-- `[ ]` Cosmetic: rephrase the `# nosec B105` comments so bandit stops emitting "Test in comment"
-  warnings (prose after `# nosec` is parsed as test IDs).
+- `[x]` Close test-coverage holes — **DONE 2026-08-31: 92% -> 100%, every module.** The v0.4.1 pass
+  took the `glob` branch, the `equals` FAIL path and the `rc=2` bad-policy paths
+  (`tests/test_policy_shape.py`); the follow-up took the rest (`tests/test_cli_inputs.py`):
+  `--token-file`, `--token -` stdin, both `python -m` entry points, the unknown-policy-suffix
+  branch, the JSON summary counts, malformed-JWT rejection, and the customized-sub and
+  days-duration report branches. **Worth noting which ones mattered**: `--token-file` and
+  `--token -` are how `action.yml` feeds the tool, so the shipped Action's only invocation path had
+  been running on untested code. 100% is not the point and is not a target to defend — it just
+  happens to be where the risk-driven list ran out.
+- `[x]` Cosmetic: rephrase the `# nosec B105` comments — **DONE 2026-08-31**. The prose moved to
+  its own line above; `# nosec B105` is now bare, so bandit stops parsing "a status constant, not
+  a secret" as a list of test IDs and runs silent.
 
 ## Non-goals (hold the line)
 

{subcheck-0.4.0 → subcheck-0.4.2}/CHANGELOG.md

@@ -4,6 +4,99 @@ All notable changes are documented here. Format based on
 [Keep a Changelog](https://keepachangelog.com/); this project follows
 [Semantic Versioning](https://semver.org/).
 
+## [Unreleased]
+
+## [0.4.2] - 2026-09-01
+
+### Fixed
+- **A claims file that is not a JSON object was half-processed instead of rejected.**
+  `decode_claims` has always required the JWT payload to decode to an object; `--claims` went
+  straight to `json.loads` with no such check, so the tool's two claim-input paths disagreed about
+  what "claims" means. Three consequences, all reproduced through the shipped CLI on 0.4.1:
+  - **`validate()` returned *all PASS* for list-shaped claims.** `rule.name not in claims` is legal
+    on any container, so every rule read as absent - MISSING for a required rule, but **PASS** for
+    an optional one. An all-optional policy therefore reported a clean pass over claims holding
+    nothing at all. Nothing downstream caught that on purpose: the report merely happened to crash
+    a few lines later on `claims.get()`, and that accident was the only thing standing between
+    `--claims '[]'` and a green gate. `validate()` and `build_report()` now reject the shape, so
+    the guard does not depend on a crash that a refactor could remove.
+  - **`--claims <non-object> --format json` exited 0**, echoing the input back as though it were a
+    decoded token. That branch consults no policy and calls no `.items()`, so it had no crash to
+    hide behind - a silent success on input that was never claims.
+  - **Every other combination exited 1** - the "a claim did not match" code - with a raw
+    `AttributeError` traceback. That is the same bad-input-indistinguishable-from-a-finding
+    confusion 0.4.1 fixed on the policy side; it now lands on the documented rc=2 path.
+
+  An empty object `{}` is still accepted, and a required rule still reports MISSING against it: the
+  guard rejects the wrong *shape*, not an empty token.
+
+### Added
+- `tests/test_claims_shape.py` - 28 regression tests, 27 of which fail against 0.4.1. One of them
+  is a parity test asserting that `--token-file` and `--claims` now return the same verdict and the
+  same exit code for the same non-object payload, since that asymmetry is what caused this.
+- Tests for the claim-input paths that had none: `--token-file`, `--token -` (stdin), and both
+  `python -m` entry points - the three the shipped `action.yml` actually uses, so the Action's only
+  invocation path had been running on untested code. Plus malformed-JWT rejection, the
+  unknown-policy-suffix branch, the JSON summary counts, the structurally-invalid-policy rejections
+  through the CLI, and the customized-sub and days-duration report branches.
+  Coverage 95% -> **100%**, every module (still 100% after this release's guards).
+
+### Changed
+- README documents the exit codes explicitly (`0` / `1` / `2`) instead of "non-zero on any
+  finding". Both 0.4.1 and 0.4.2 turn on the 1-vs-2 distinction, and someone wiring this into a CI
+  gate has to know which code means "fix your config" and which means "the gate caught something".
+
+## [0.4.1] - 2026-08-31
+
+### Fixed
+- **A malformed policy could pass every token it was written to reject.** Two silent fail-open
+  paths, both found by an audit sweep and both reproduced through the shipped CLI before fixing:
+  - **Claim rules written at the top level were ignored entirely.** `issuer` and `audience`
+    legitimately live at the top level, so putting the rest of the rules there too is the natural
+    slip - and unknown top-level keys were dropped without a word. A policy pinning `repository`
+    and `sub` that way returned `PASS (1 pass, 0 fail, 0 missing)` and exit 0 against a token from
+    an entirely different repository, having checked only the issuer. Unknown top-level keys are
+    now rejected, matching the unknown-rule-key check that already existed one level down.
+  - **`in:` given a string did substring matching.** `{"in": "production"}` - a one-item YAML list
+    missing its `- ` - became Python containment, so `prod` passed, and so did the empty string.
+    `in` must now be a list.
+- **Rule values are validated, not just rule key names.** `matches` must be a string and must
+  compile; `glob` must be a string; `required` must be a real boolean (`"false"` is a non-empty
+  string, so it silently made an optional claim mandatory). Each of these previously escaped
+  `validate()` as a raw `TypeError`/`re.error` traceback and exited **1** - the "a claim did not
+  match" code - making a broken policy indistinguishable from a real gate failure. They now raise
+  a readable error on the documented rc=2 path. `equals` is deliberately unrestricted: it compares
+  against the claim's real JSON type, so a number is a legitimate rule.
+- **An unparseable YAML policy exited 1 instead of 2.** `yaml.YAMLError` is not a `ValueError`
+  (`json.JSONDecodeError` is), so it slipped past the CLI's bad-input handler.
+- **A claim carrying two constraints reported the wrong one on failure.** `describe()` named only
+  the first constraint, so a `ref` failing its regex was reported against the glob it satisfied.
+  All constraints are now listed, which is also what the validator actually requires.
+
+### Added
+- CI now **executes the composite action** (`uses: ./`) against a policy pinning this repository's
+  own OIDC token, in both text and JSON formats. `action.yml` is the entry point the README
+  advertises and nothing had ever run it, so a break would have surfaced in a user's pipeline
+  rather than here. Skipped on fork PRs, which get no token by design.
+- `tests/test_policy_shape.py` - 20 regression tests; 8 of them fail against the previous release.
+  Also closes three long-standing coverage holes: the `glob` matcher (which had no assertion
+  anywhere despite being a documented rule), the `equals` FAIL path (every prior failure case went
+  through `matches` or an absent claim), and the rc=2 bad-policy paths. Coverage 93% -> 95%, with
+  `validator.py` at 100%.
+
+### Changed
+- The two `# nosec B105` comments no longer carry trailing prose, which bandit was parsing as a
+  comma-separated list of test IDs and warning about on every run.
+
+### Changed
+- Pinned corpus bumped `subvectors==0.2.1` -> `0.3.0`, the release carrying the first six
+  `observed` vectors. **No fixture re-derivation was needed and that is a verified fact, not an
+  assumption**: `git diff v0.2.1..v0.3.0 -- vectors/` changes no `"subject"` line at all — 0.3.0
+  adds `observation` blocks and the schema that enforces them, so the subject grammar this
+  project consumes is byte-identical. All three drift directions stay green against the new pin
+  (9 vendored subjects, 21 upstream). Bumping still means re-deriving whenever a subject string
+  *does* move.
+
 ## [0.4.0] - 2026-08-25
 
 ### Added

{subcheck-0.4.0 → subcheck-0.4.2}/CONTRIBUTING.md

@@ -10,7 +10,7 @@ sibling [subvectors](https://github.com/Dashtid/subvectors) vector suite.
 
 ```bash
 pip install -e ".[dev]"
-pytest -q && ruff check . && bandit -r src
+pytest -q && ruff check . && mypy && bandit -r src
 ```
 
 ## Good first issues
@@ -24,5 +24,5 @@ Small, self-contained additions (labelled `good first issue`):
 
 ## Pull requests
 
-Keep the change focused, add a test, and make sure `pytest`, `ruff check`, and `bandit` pass.
+Keep the change focused, add a test, and make sure `pytest`, `ruff check`, `mypy`, and `bandit` pass - CI runs all four.
 Not sure about scope? Open an issue first — open questions are welcome.

{subcheck-0.4.0 → subcheck-0.4.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: subcheck
-Version: 0.4.0
+Version: 0.4.2
 Summary: Decode GitHub Actions OIDC token claims and validate them against an expected-claims policy - a CI gate against over-broad cloud trust.
 Project-URL: Homepage, https://github.com/Dashtid/subcheck
 Project-URL: Related, https://github.com/Dashtid/subvectors
@@ -26,7 +26,7 @@ Requires-Dist: mypy>=1.8; extra == 'dev'
 Requires-Dist: pytest-cov>=4; extra == 'dev'
 Requires-Dist: pytest>=7; extra == 'dev'
 Requires-Dist: ruff>=0.4; extra == 'dev'
-Requires-Dist: subvectors==0.2.1; (python_version >= '3.11') and extra == 'dev'
+Requires-Dist: subvectors==0.3.0; (python_version >= '3.11') and extra == 'dev'
 Requires-Dist: types-pyyaml>=6; extra == 'dev'
 Description-Content-Type: text/markdown
 
@@ -56,9 +56,22 @@ OIDC claim inspection: FAIL  (5 pass, 1 fail, 1 missing)
   [-] sub                 high    claim 'sub'='repo:acme/payments-api:pull_request' does not satisfy matches /^repo:acme/payments-api:(ref:refs/heads/main|environment:production|ref:refs/tags/v[0-9].*)$/
   [!] environment         medium  claim 'environment' is required but absent
   [+] runner_environment  medium  claim 'runner_environment' satisfies equals 'github-hosted'
+
+Notes:
+  [i] sub is pinned by name; when this repo adopts the immutable format the sub becomes 'owner@id/repo@id:...' and this pattern stops matching - pin repository_id / repository_owner_id to stay durable. Adoption is automatic for repos created, renamed, or transferred after 2026-07-15, but any repo can be switched on sooner via the org-level or repo-level immutable-subject setting, so do not infer the format from the repo's age.
 ```
 
-Exit code is non-zero on any finding, so the command drops straight into a CI step as a gate.
+Notes are advisory and never change the verdict. Exit code is non-zero on any finding, so the
+command drops straight into a CI step as a gate:
+
+| code | meaning |
+|------|---------|
+| `0`  | every rule passed |
+| `1`  | at least one claim FAILed or was required-but-MISSING - the gate caught something |
+| `2`  | bad input: the token, the claims file or the policy could not be read as what it claims to be |
+
+The `1` / `2` split matters in CI. A malformed policy or a claims file that is not a JSON object
+exits `2`, so it reads as "fix your config", never as "the gate caught something".
 
 ## Why
 
@@ -299,6 +312,7 @@ steps:
 pip install -e ".[dev]"
 pytest -q          # tests
 ruff check .       # lint
+mypy               # type check (CI enforces this)
 bandit -r src      # security lint
 ```
 

{subcheck-0.4.0 → subcheck-0.4.2}/README.md

@@ -24,9 +24,22 @@ OIDC claim inspection: FAIL  (5 pass, 1 fail, 1 missing)
   [-] sub                 high    claim 'sub'='repo:acme/payments-api:pull_request' does not satisfy matches /^repo:acme/payments-api:(ref:refs/heads/main|environment:production|ref:refs/tags/v[0-9].*)$/
   [!] environment         medium  claim 'environment' is required but absent
   [+] runner_environment  medium  claim 'runner_environment' satisfies equals 'github-hosted'
+
+Notes:
+  [i] sub is pinned by name; when this repo adopts the immutable format the sub becomes 'owner@id/repo@id:...' and this pattern stops matching - pin repository_id / repository_owner_id to stay durable. Adoption is automatic for repos created, renamed, or transferred after 2026-07-15, but any repo can be switched on sooner via the org-level or repo-level immutable-subject setting, so do not infer the format from the repo's age.
 ```
 
-Exit code is non-zero on any finding, so the command drops straight into a CI step as a gate.
+Notes are advisory and never change the verdict. Exit code is non-zero on any finding, so the
+command drops straight into a CI step as a gate:
+
+| code | meaning |
+|------|---------|
+| `0`  | every rule passed |
+| `1`  | at least one claim FAILed or was required-but-MISSING - the gate caught something |
+| `2`  | bad input: the token, the claims file or the policy could not be read as what it claims to be |
+
+The `1` / `2` split matters in CI. A malformed policy or a claims file that is not a JSON object
+exits `2`, so it reads as "fix your config", never as "the gate caught something".
 
 ## Why
 
@@ -267,6 +280,7 @@ steps:
 pip install -e ".[dev]"
 pytest -q          # tests
 ruff check .       # lint
+mypy               # type check (CI enforces this)
 bandit -r src      # security lint
 ```
 

{subcheck-0.4.0 → subcheck-0.4.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "subcheck"
-version = "0.4.0"
+version = "0.4.2"
 description = "Decode GitHub Actions OIDC token claims and validate them against an expected-claims policy - a CI gate against over-broad cloud trust."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -38,7 +38,7 @@ dev = [
     "types-PyYAML>=6",
     "ruff>=0.4",
     "bandit>=1.7",
-    'subvectors==0.2.1; python_version >= "3.11"',
+    'subvectors==0.3.0; python_version >= "3.11"',
 ]
 
 [project.urls]

{subcheck-0.4.0 → subcheck-0.4.2}/src/subcheck/__init__.py

@@ -5,7 +5,7 @@ from .policy import ClaimRule, Policy, load_policy, load_policy_file
 from .report import build_report, to_json, to_text
 from .validator import Result, validate
 
-__version__ = "0.4.0"
+__version__ = "0.4.2"
 
 __all__ = [
     "decode_claims",

{subcheck-0.4.0 → subcheck-0.4.2}/src/subcheck/cli.py

@@ -16,12 +16,23 @@ from .validator import validate
 
 def _load_claims(args: argparse.Namespace) -> dict:
     if args.token:
-        token = sys.stdin.read() if args.token == "-" else args.token  # noqa: S105  # nosec B105 - a JWT, not a secret to store
+        # A JWT read from stdin/argv, not a stored secret.
+        token = sys.stdin.read() if args.token == "-" else args.token  # noqa: S105  # nosec B105
         return decode_claims(token)
     if args.token_file:
         return decode_claims(Path(args.token_file).read_text(encoding="utf-8"))
     if args.claims:
-        return json.loads(Path(args.claims).read_text(encoding="utf-8"))
+        claims = json.loads(Path(args.claims).read_text(encoding="utf-8"))
+        # decode_claims already rejects a payload that is not a JSON object, but
+        # --claims went straight to json.loads, so a file holding a list or a bare
+        # scalar reached the report unchecked. See validate() for why that shape
+        # is not merely untidy.
+        if not isinstance(claims, dict):
+            raise ValueError(
+                f"--claims file {args.claims} did not decode to a JSON object "
+                f"(got {type(claims).__name__})"
+            )
+        return claims
     raise ValueError("provide one of --token, --token-file, or --claims")
 
 

{subcheck-0.4.0 → subcheck-0.4.2}/src/subcheck/policy.py

@@ -3,6 +3,7 @@
 from __future__ import annotations
 
 import json
+import re
 from dataclasses import dataclass, field
 from pathlib import Path
 
@@ -26,6 +27,7 @@ CLAIM_SEVERITY = {
 DEFAULT_SEVERITY = "medium"
 
 _ALLOWED_KEYS = {"equals", "in", "matches", "glob", "required"}
+_ALLOWED_TOP_KEYS = {"issuer", "audience", "claims"}
 
 
 @dataclass
@@ -42,15 +44,19 @@ class ClaimRule:
         return CLAIM_SEVERITY.get(self.name, DEFAULT_SEVERITY)
 
     def describe(self) -> str:
+        # Every constraint set on a rule must hold (validator._matches ANDs them),
+        # so describe them all - reporting only the first produced a failure line
+        # that contradicted itself when a claim carried two constraints.
+        parts = []
         if self.equals is not None:
-            return f"equals {self.equals!r}"
+            parts.append(f"equals {self.equals!r}")
         if self.one_of is not None:
-            return f"one of {self.one_of!r}"
+            parts.append(f"one of {self.one_of!r}")
         if self.matches is not None:
-            return f"matches /{self.matches}/"
+            parts.append(f"matches /{self.matches}/")
         if self.glob is not None:
-            return f"glob {self.glob!r}"
-        return "present"
+            parts.append(f"glob {self.glob!r}")
+        return " and ".join(parts) if parts else "present"
 
 
 @dataclass
@@ -62,6 +68,15 @@ def load_policy(data: dict) -> Policy:
     """Build a Policy from a parsed mapping (see the README for the schema)."""
     if not isinstance(data, dict):
         raise ValueError("policy must be a mapping/object")
+    # Claim rules belong under 'claims'. Silently ignoring anything else let a
+    # policy that put its rules at the top level pass every token it was written
+    # to reject, green and rc=0, because only 'issuer'/'audience' were read.
+    unknown_top = set(data) - _ALLOWED_TOP_KEYS
+    if unknown_top:
+        raise ValueError(
+            f"policy: unknown top-level keys {sorted(unknown_top)} - claim rules "
+            "belong under 'claims'; only 'issuer', 'audience' and 'claims' are read"
+        )
     rules: list = []
     if "issuer" in data:
         rules.append(ClaimRule(name="iss", equals=str(data["issuer"])))
@@ -86,13 +101,44 @@ def _rule_from_spec(name: str, spec) -> ClaimRule:
         unknown = set(spec) - _ALLOWED_KEYS
         if unknown:
             raise ValueError(f"claim {name!r}: unknown rule keys {sorted(unknown)}")
+        one_of = spec.get("in")
+        if one_of is not None and not isinstance(one_of, list):
+            # `in: production` (a one-item YAML list missing its '- ') became
+            # Python containment: substring matching, so 'prod' and even '' passed.
+            raise ValueError(
+                f"claim {name!r}: 'in' must be a list of values, got "
+                f"{type(one_of).__name__}"
+            )
+        matches = spec.get("matches")
+        if matches is not None:
+            if not isinstance(matches, str):
+                raise ValueError(
+                    f"claim {name!r}: 'matches' must be a regex string, got "
+                    f"{type(matches).__name__}"
+                )
+            try:
+                re.compile(matches)
+            except re.error as exc:
+                raise ValueError(f"claim {name!r}: 'matches' is not a valid regex: {exc}") from exc
+        glob = spec.get("glob")
+        if glob is not None and not isinstance(glob, str):
+            raise ValueError(
+                f"claim {name!r}: 'glob' must be a pattern string, got {type(glob).__name__}"
+            )
+        required = spec.get("required", True)
+        if not isinstance(required, bool):
+            # bool("false") is True, so a quoted boolean silently made an
+            # optional claim mandatory.
+            raise ValueError(
+                f"claim {name!r}: 'required' must be true or false, got {required!r}"
+            )
         return ClaimRule(
             name=name,
             equals=spec.get("equals"),
-            one_of=spec.get("in"),
-            matches=spec.get("matches"),
-            glob=spec.get("glob"),
-            required=bool(spec.get("required", True)),
+            one_of=one_of,
+            matches=matches,
+            glob=glob,
+            required=required,
         )
     raise ValueError(f"claim {name!r}: rule must be a string, list, or mapping")
 
@@ -109,7 +155,13 @@ def load_policy_file(path: str | Path) -> Policy:
                 "PyYAML is required to load YAML policies (pip install PyYAML), "
                 "or use a .json policy instead"
             ) from exc
-        data = yaml.safe_load(text)
+        try:
+            data = yaml.safe_load(text)
+        except yaml.YAMLError as exc:
+            # YAMLError is not a ValueError (json.JSONDecodeError is), so an
+            # unparseable YAML policy escaped the CLI's rc=2 handler and exited 1
+            # - the "a claim did not match" code.
+            raise ValueError(f"policy file {p} is not valid YAML: {exc}") from exc
     else:
         data = json.loads(text)
     return load_policy(data)

{subcheck-0.4.0 → subcheck-0.4.2}/src/subcheck/report.py

@@ -13,6 +13,9 @@ from .validator import FAIL, MISSING, PASS, Result
 
 def build_report(claims: dict, results: list[Result], now: float | None = None) -> dict:
     """Assemble the report. ``now`` (unix seconds) is injectable for tests."""
+    # Same guard as validate(): both are public API and both read claims as a mapping.
+    if not isinstance(claims, dict):
+        raise ValueError(f"claims must be a mapping/object, got {type(claims).__name__}")
     passed = all(r.status == PASS for r in results)
     return {
         "passed": passed,

{subcheck-0.4.0 → subcheck-0.4.2}/src/subcheck/validator.py

@@ -8,7 +8,8 @@ from dataclasses import dataclass
 
 from .policy import ClaimRule, Policy
 
-PASS = "PASS"  # noqa: S105  # nosec B105 - a status constant, not a secret
+# A status constant, not a secret - the linters flag the literal name only.
+PASS = "PASS"  # noqa: S105  # nosec B105
 FAIL = "FAIL"
 MISSING = "MISSING"
 
@@ -38,6 +39,13 @@ def _matches(rule: ClaimRule, value) -> bool:
 
 def validate(claims: dict, policy: Policy) -> list[Result]:
     """Check each policy rule against the claims and return one Result per rule."""
+    # `rule.name not in claims` is legal on any container, so a list or tuple read
+    # as "every claim absent" - MISSING for a required rule, but PASS for an
+    # optional one, so an all-optional policy passed claims that held nothing at
+    # all. The only thing that stopped a green report was an unrelated crash further
+    # down, on claims.get(). Reject the shape here rather than lean on that accident.
+    if not isinstance(claims, dict):
+        raise ValueError(f"claims must be a mapping/object, got {type(claims).__name__}")
     results: list[Result] = []
     for rule in policy.rules:
         expected = rule.describe()

subcheck-0.4.2/tests/test_claims_shape.py

@@ -0,0 +1,100 @@
+"""A claims file that is not a JSON object must be rejected, not half-processed.
+
+`decode_claims` has always rejected a JWT payload that is not an object. `--claims`
+went straight to `json.loads` with no such check, so the two claim-input paths
+disagreed about what "claims" means. Three things followed from that asymmetry,
+all reproduced on 0.4.1 and all pinned below:
+
+* `validate()` returned **all PASS** for list-shaped claims - `rule.name not in
+  claims` is legal on any container, so every rule read as absent, which is PASS
+  for an optional rule. Only an unrelated crash further down stopped a green report.
+* `--claims <non-object> --format json` with no policy printed the garbage and
+  **exited 0**.
+* Every other combination raised an AttributeError traceback and exited **1** - the
+  "a claim did not match" code, so bad input was indistinguishable from a real
+  gate failure.
+"""
+
+import json
+
+import pytest
+
+from subcheck import build_report, load_policy, validate
+from subcheck.cli import main
+from subcheck.validator import MISSING, PASS
+
+NOT_OBJECTS = [[], [1, 2, 3], "hello", 42, None, True]
+
+OPTIONAL_POLICY = {
+    "claims": {
+        "repository": {"equals": "acme/api", "required": False},
+        "sub": {"matches": "^repo:acme/api:", "required": False},
+    }
+}
+
+
+# --- the library API ---------------------------------------------------------
+
+@pytest.mark.parametrize("claims", NOT_OBJECTS + [()])
+def test_validate_rejects_claims_that_are_not_a_mapping(claims):
+    # Was: [] and (1,2,3) returned one PASS per rule, so an all-optional policy
+    # reported a clean pass over claims holding nothing at all.
+    with pytest.raises(ValueError, match="mapping/object"):
+        validate(claims, load_policy(OPTIONAL_POLICY))
+
+
+@pytest.mark.parametrize("claims", NOT_OBJECTS)
+def test_build_report_rejects_claims_that_are_not_a_mapping(claims):
+    with pytest.raises(ValueError, match="mapping/object"):
+        build_report(claims, [])
+
+
+def test_an_empty_claims_object_is_still_accepted():
+    # The guard must reject the wrong SHAPE, not an empty token: {} is a legitimate
+    # (if useless) claim set, and a required rule should report MISSING as before.
+    policy = load_policy({"claims": {"repository": {"equals": "acme/api"}}})
+    assert [r.status for r in validate({}, policy)] == [MISSING]
+    assert [r.status for r in validate({}, load_policy(OPTIONAL_POLICY))] == [PASS, PASS]
+
+
+# --- through the CLI ---------------------------------------------------------
+
+def _claims_file(tmp_path, value):
+    f = tmp_path / "claims.json"
+    f.write_text(json.dumps(value), encoding="utf-8")
+    return str(f)
+
+
+@pytest.mark.parametrize("claims", NOT_OBJECTS)
+def test_cli_rejects_a_non_object_claims_file_on_rc2(tmp_path, capsys, claims):
+    # Was: rc=1 with an AttributeError traceback - the gate-failure exit code.
+    assert main(["--claims", _claims_file(tmp_path, claims)]) == 2
+    assert "did not decode to a JSON object" in capsys.readouterr().err
+
+
+@pytest.mark.parametrize("claims", NOT_OBJECTS)
+def test_cli_json_format_no_longer_exits_zero_on_a_non_object(tmp_path, capsys, claims):
+    # Was: rc=0, echoing the garbage back as if it were a decoded token. This is
+    # the worst of the three - a silent success on input that is not claims.
+    assert main(["--claims", _claims_file(tmp_path, claims), "--format", "json"]) == 2
+    assert "did not decode to a JSON object" in capsys.readouterr().err
+
+
+def test_cli_rejects_a_non_object_claims_file_with_a_policy(tmp_path, capsys):
+    policy = tmp_path / "policy.json"
+    policy.write_text(json.dumps(OPTIONAL_POLICY), encoding="utf-8")
+    rc = main(["--claims", _claims_file(tmp_path, []), "--policy", str(policy)])
+    assert rc == 2
+    assert "did not decode to a JSON object" in capsys.readouterr().err
+
+
+def test_both_claim_input_paths_agree_on_what_claims_are(tmp_path, capsys, make_jwt):
+    # Parity: the token path has always rejected a non-object payload. The point of
+    # the fix is that --claims now gives the same verdict and the same exit code.
+    token = tmp_path / "token.jwt"
+    token.write_text(make_jwt(["not", "an", "object"]), encoding="utf-8")
+    assert main(["--token-file", str(token)]) == 2
+    assert "did not decode to a JSON object" in capsys.readouterr().err
+
+    assert main(["--claims", _claims_file(tmp_path, ["not", "an", "object"])]) == 2
+    assert "did not decode to a JSON object" in capsys.readouterr().err

subcheck-0.4.2/tests/test_cli_inputs.py

@@ -0,0 +1,113 @@
+"""The claim-input paths and the failure exits, which had no coverage.
+
+`--token-file` and `--token -` are how the shipped GitHub Action feeds subcheck
+(action.yml pipes the token into `--token -`), so the tool's own advertised entry
+point ran on code no test executed.
+"""
+
+import json
+import subprocess
+import sys
+
+import pytest
+
+from subcheck.cli import main
+
+
+def test_token_file(make_jwt, tmp_path, capsys):
+    jwt = make_jwt({"iss": "https://token.actions.githubusercontent.com", "repository": "acme/api"})
+    f = tmp_path / "token.jwt"
+    f.write_text(jwt, encoding="utf-8")
+    assert main(["--token-file", str(f)]) == 0
+    assert "repository: acme/api" in capsys.readouterr().out
+
+
+def test_token_stdin(make_jwt, monkeypatch, capsys):
+    # The action.yml path: `... | python3 -m subcheck --token - ...`
+    jwt = make_jwt({"iss": "https://token.actions.githubusercontent.com", "repository": "acme/api"})
+    monkeypatch.setattr("sys.stdin", __import__("io").StringIO(jwt + "\n"))
+    assert main(["--token", "-"]) == 0
+    assert "repository: acme/api" in capsys.readouterr().out
+
+
+def test_token_stdin_then_policy(make_jwt, monkeypatch, tmp_path, capsys):
+    jwt = make_jwt({"iss": "https://x", "repository": "acme/api"})
+    policy = tmp_path / "p.json"
+    policy.write_text(
+        json.dumps({"claims": {"repository": {"equals": "acme/api"}}}), encoding="utf-8"
+    )
+    monkeypatch.setattr("sys.stdin", __import__("io").StringIO(jwt))
+    assert main(["--token", "-", "--policy", str(policy)]) == 0
+
+
+@pytest.mark.parametrize("token", ["not-a-jwt", "a.b", "a.!!!!.c"])
+def test_malformed_token_exits_2(token, capsys):
+    assert main(["--token", token]) == 2
+    assert "error:" in capsys.readouterr().err
+
+
+def test_token_payload_that_is_not_an_object_exits_2(capsys):
+    import base64
+
+    def seg(obj):
+        return base64.urlsafe_b64encode(json.dumps(obj).encode()).rstrip(b"=").decode()
+
+    jwt = f"{seg({'alg': 'none'})}.{seg(['not', 'an', 'object'])}.xxxxxxxx"
+    assert main(["--token", jwt]) == 2
+
+
+def test_missing_claims_file_exits_2(capsys):
+    assert main(["--claims", "no-such-file.json"]) == 2
+    assert "error:" in capsys.readouterr().err
+
+
+def test_policy_file_with_unknown_suffix_is_read_as_json(tmp_path, make_jwt, monkeypatch):
+    # load_policy_file only special-cases .yaml/.yml; everything else is JSON.
+    policy = tmp_path / "policy.txt"
+    policy.write_text(
+        json.dumps({"claims": {"repository": {"equals": "acme/api"}}}), encoding="utf-8"
+    )
+    claims = tmp_path / "c.json"
+    claims.write_text(json.dumps({"repository": "acme/api"}), encoding="utf-8")
+    assert main(["--claims", str(claims), "--policy", str(policy)]) == 0
+
+
+def test_json_format_report_shape(examples_dir, capsys):
+    rc = main(["--claims", str(examples_dir / "claims-pull-request.json"),
+               "--policy", str(examples_dir / "policy.json"), "--format", "json"])
+    assert rc == 1
+    report = json.loads(capsys.readouterr().out)
+    assert report["passed"] is False
+    assert report["summary"]["fail"] >= 1
+    counted = sum(report["summary"][k] for k in ("pass", "fail", "missing"))
+    assert counted == len(report["results"])
+    assert isinstance(report["notes"], list)
+
+
+def test_python_dash_m_entry_point():
+    # `python -m subcheck` is what action.yml invokes; __main__.py had 0% coverage.
+    # Run out-of-process against this checkout, so it works whether or not the
+    # package happens to be installed in the environment running the tests.
+    import os
+    from pathlib import Path
+
+    src = Path(__file__).resolve().parent.parent / "src"
+    env = {**os.environ, "PYTHONPATH": str(src)}
+    r = subprocess.run([sys.executable, "-m", "subcheck", "--version"],
+                       capture_output=True, text=True, env=env)
+    assert r.returncode == 0, r.stderr
+    assert "subcheck" in r.stdout
+
+
+def test_python_dash_m_subcheck_cli_entry_point():
+    # cli.py carries its own `if __name__ == "__main__"` guard, reachable as
+    # `python -m subcheck.cli`. Both entry points are real; exercise both.
+    import os
+    from pathlib import Path
+
+    src = Path(__file__).resolve().parent.parent / "src"
+    env = {**os.environ, "PYTHONPATH": str(src)}
+    r = subprocess.run([sys.executable, "-m", "subcheck.cli", "--version"],
+                       capture_output=True, text=True, env=env)
+    assert r.returncode == 0, r.stderr
+    assert "subcheck" in r.stdout

subcheck-0.4.2/tests/test_policy_shape.py

@@ -0,0 +1,196 @@
+"""A malformed policy must be rejected, never silently weakened.
+
+Every case here PASSED with rc=0 before the guards landed - the gate went green
+while checking less than the author wrote. That is the one failure mode this
+tool exists to prevent, so each case is pinned as a regression test.
+"""
+
+import json
+
+import pytest
+
+from subcheck import load_policy, validate
+from subcheck.policy import load_policy_file
+from subcheck.validator import FAIL, PASS
+
+# --- claim rules written at the top level instead of under 'claims' ----------
+
+def test_unknown_top_level_keys_are_rejected():
+    # Was: silently ignored, so the policy checked only 'issuer' and passed a
+    # token from an entirely different repository.
+    with pytest.raises(ValueError, match="unknown top-level keys"):
+        load_policy(
+            {
+                "issuer": "https://token.actions.githubusercontent.com",
+                "repository": {"equals": "acme/payments-api"},
+                "sub": {"matches": "^repo:acme/payments-api:"},
+            }
+        )
+
+
+def test_the_documented_top_level_keys_are_still_accepted():
+    policy = load_policy(
+        {
+            "issuer": "https://token.actions.githubusercontent.com",
+            "audience": "sts.amazonaws.com",
+            "claims": {"repository": {"equals": "acme/api"}},
+        }
+    )
+    assert len(policy.rules) == 3
+
+
+# --- rule value shapes -------------------------------------------------------
+
+def test_in_must_be_a_list_not_a_string():
+    # Was: `value not in "production"` - substring containment, so 'prod' and
+    # even '' satisfied it. In YAML this is a one-item list missing its '- '.
+    with pytest.raises(ValueError, match="'in' must be a list"):
+        load_policy({"claims": {"environment": {"in": "production"}}})
+
+
+def test_in_as_a_list_still_works():
+    policy = load_policy({"claims": {"environment": {"in": ["production", "prod"]}}})
+    assert validate({"environment": "prod"}, policy)[0].status == PASS
+    assert validate({"environment": "staging"}, policy)[0].status == FAIL
+
+
+@pytest.mark.parametrize(
+    ("spec", "expected"),
+    [
+        ({"matches": 123}, "'matches' must be a regex string"),
+        ({"matches": "refs/heads/(main"}, "not a valid regex"),
+        ({"glob": ["a", "b"]}, "'glob' must be a pattern string"),
+        ({"required": "false"}, "'required' must be true or false"),
+    ],
+)
+def test_malformed_rule_values_are_rejected(spec, expected):
+    # Each of these previously escaped as a raw TypeError/re.error traceback
+    # from validate(), exiting 1 - the "a claim did not match" code.
+    with pytest.raises(ValueError, match=expected):
+        load_policy({"claims": {"ref": spec}})
+
+
+def test_equals_still_accepts_any_json_scalar():
+    # equals compares with != against the claim's real JSON type, so a number
+    # is a legitimate rule - the shape guards must not break it.
+    policy = load_policy({"claims": {"run_attempt": {"equals": 1}}})
+    assert validate({"run_attempt": 1}, policy)[0].status == PASS
+
+
+# --- file-level parse failures ----------------------------------------------
+
+def test_unparseable_yaml_policy_raises_valueerror(tmp_path):
+    # yaml.YAMLError is not a ValueError (json.JSONDecodeError is), so this
+    # escaped the CLI's rc=2 handler and exited 1.
+    p = tmp_path / "policy.yaml"
+    p.write_text("claims:\n  ref: {matches: '['\n", encoding="utf-8")
+    with pytest.raises(ValueError, match="not valid YAML"):
+        load_policy_file(p)
+
+
+def test_unparseable_json_policy_raises_valueerror(tmp_path):
+    p = tmp_path / "policy.json"
+    p.write_text("{not json", encoding="utf-8")
+    with pytest.raises(ValueError):
+        load_policy_file(p)
+
+
+def test_every_shipped_example_policy_still_loads():
+    from pathlib import Path
+
+    examples = sorted(Path(__file__).resolve().parent.parent.glob("examples/policy*"))
+    assert examples, "no example policies found"
+    for path in examples:
+        load_policy_file(path)
+
+
+# --- describe() reports every constraint ------------------------------------
+
+def test_describe_reports_all_constraints_not_just_the_first():
+    # Was: only the first constraint was named, so a claim failing on the
+    # regex was reported against the glob it actually satisfied.
+    policy = load_policy({"claims": {"ref": {"glob": "refs/heads/*", "matches": "main$"}}})
+    result = validate({"ref": "refs/tags/v1"}, policy)[0]
+    assert result.status == FAIL
+    assert "matches /main$/" in result.expected
+    assert "glob 'refs/heads/*'" in result.expected
+
+
+def test_json_policy_round_trips(tmp_path):
+    p = tmp_path / "policy.json"
+    p.write_text(json.dumps({"claims": {"repository": {"equals": "acme/api"}}}), encoding="utf-8")
+    assert len(load_policy_file(p).rules) == 1
+
+
+# --- the glob matcher, previously untested anywhere ---------------------------
+
+@pytest.mark.parametrize(
+    ("pattern", "value", "expected"),
+    [
+        ("refs/heads/*", "refs/heads/main", PASS),
+        ("refs/heads/*", "refs/tags/v1", FAIL),
+        # fnmatch's '*' spans '/', exactly like AWS StringLike - a nested branch
+        # still matches, which is the footgun the README documents.
+        ("refs/heads/*", "refs/heads/feature/a", PASS),
+        # fnmatchcase, so matching is case-sensitive.
+        ("refs/heads/Main", "refs/heads/main", FAIL),
+    ],
+)
+def test_glob_matching(pattern, value, expected):
+    policy = load_policy({"claims": {"ref": {"glob": pattern}}})
+    assert validate({"ref": value}, policy)[0].status == expected
+
+
+# --- the equals FAIL path, previously never exercised -------------------------
+
+def test_equals_mismatch_fails():
+    # `equals` is the most common rule type and no test had ever made one FAIL:
+    # every existing failure case went through `matches` or an absent claim.
+    policy = load_policy({"claims": {"repository": {"equals": "acme/api"}}})
+    ok, bad = (validate({"repository": v}, policy)[0] for v in ("acme/api", "attacker/evil"))
+    assert ok.status == PASS
+    assert bad.status == FAIL
+    assert bad.severity == "high"
+    assert "attacker/evil" in bad.message
+
+
+def test_equals_shorthand_string_form_fails_too():
+    # The bare-string shorthand builds the same rule as {"equals": ...}.
+    policy = load_policy({"claims": {"repository": "acme/api"}})
+    assert validate({"repository": "attacker/evil"}, policy)[0].status == FAIL
+
+
+# --- the remaining rejection paths -------------------------------------------
+
+@pytest.mark.parametrize(
+    ("data", "expected"),
+    [
+        (["not", "a", "mapping"], "policy must be a mapping"),
+        ({"claims": ["not", "a", "mapping"]}, "'claims' must be a mapping"),
+        ({}, "policy is empty"),
+        ({"claims": {"ref": 42}}, "rule must be a string, list, or mapping"),
+    ],
+)
+def test_structurally_invalid_policies_are_rejected(data, expected):
+    with pytest.raises(ValueError, match=expected):
+        load_policy(data)
+
+
+def test_bad_policy_file_exits_2_through_the_cli(tmp_path, capsys):
+    from subcheck.cli import main
+
+    claims = tmp_path / "c.json"
+    claims.write_text('{"repository": "acme/api"}', encoding="utf-8")
+    policy = tmp_path / "p.json"
+    policy.write_text('{"claims": {"environment": {"in": "production"}}}', encoding="utf-8")
+    assert main(["--claims", str(claims), "--policy", str(policy)]) == 2
+    assert "must be a list" in capsys.readouterr().err
+
+
+def test_missing_policy_file_exits_2_through_the_cli(tmp_path, capsys):
+    from subcheck.cli import main
+
+    claims = tmp_path / "c.json"
+    claims.write_text('{"repository": "acme/api"}', encoding="utf-8")
+    assert main(["--claims", str(claims), "--policy", str(tmp_path / "nope.json")]) == 2
+    assert "error:" in capsys.readouterr().err

{subcheck-0.4.0 → subcheck-0.4.2}/tests/test_report.py

@@ -64,3 +64,25 @@ def test_malformed_half_immutable_sub_is_flagged():
     policy = {"claims": {"sub": {"matches": r"^repo:.*$"}}}
     note = " ".join(_report(claims, policy)["notes"])
     assert "only one segment" in note
+
+
+def test_customized_sub_warns_that_default_format_conditions_stop_matching():
+    # A customized sub REPLACES the default format rather than varying it, so a
+    # trust condition written for 'repo:ORG/REPO:...' stops matching entirely -
+    # wildcards included. That advisory had no test.
+    claims = {
+        "sub": "repo:acme/payments-api:environment:production"
+        ":job_workflow_ref:acme/shared/.github/workflows/deploy.yml@refs/tags/v1.2.3"
+    }
+    note = " ".join(_report(claims, {"claims": {"sub": {"matches": "^repo:acme/"}}})["notes"])
+    assert "CUSTOMIZED" in note
+    assert "wildcards included" in note
+
+
+def test_unparseable_sub_yields_no_format_notes():
+    # A sub that is not a GitHub subject at all (another issuer's format) must
+    # not produce migration advice about a format it does not have.
+    claims = {"sub": "project_path:acme/api:ref_type:branch:ref:main"}
+    report = _report(claims, {"claims": {"sub": {"matches": "^project_path:"}}})
+    assert report["passed"]
+    assert not any("immutable" in n for n in report["notes"])

{subcheck-0.4.0 → subcheck-0.4.2}/tests/test_time_notes.py

@@ -53,3 +53,13 @@ def test_non_numeric_time_claims_are_ignored():
 
 def test_absent_time_claims_produce_no_notes():
     assert _notes({}) == ""
+
+
+def test_long_expiry_is_reported_in_days():
+    # _duration's coarsest branch: anything past 48h reads in days, not hours.
+    from subcheck.report import _duration
+
+    assert _duration(30) == "30s"
+    assert _duration(600) == "10m"
+    assert _duration(7200) == "2h"
+    assert _duration(3 * 86400) == "3d"

subcheck-0.4.0/.github/workflows/ci.yml

@@ -1,34 +0,0 @@
-name: CI
-
-on:
-  push:
-    branches: [main]
-  pull_request:
-
-permissions:
-  contents: read
-
-jobs:
-  test:
-    runs-on: ubuntu-latest
-    strategy:
-      fail-fast: false
-      matrix:
-        python-version: ["3.10", "3.11", "3.12", "3.13"]
-    steps:
-      - uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
-      - uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
-        with:
-          python-version: ${{ matrix.python-version }}
-      - name: Install
-        run: |
-          python -m pip install --upgrade pip
-          pip install -e ".[dev]"
-      - name: Lint (ruff)
-        run: ruff check .
-      - name: Type check (mypy)
-        run: mypy
-      - name: Security lint (bandit)
-        run: bandit -q -r src
-      - name: Tests (pytest)
-        run: pytest -q --cov=subcheck --cov-report=term-missing