ci,scripts: pin the conformance catalog tooling, stop ignoring uv lockfiles, record the changelog

The conformance suite stops xfailing the inbound DPoP-Nonce case now that the
catalog carries it, and the catalog-fetch tooling is aligned with the pinned ref
so a local run matches CI rather than the moving default branch.

`backport-fixes.sh` accepts a tag as `--from`: `release.yml` deletes
`release/vX.Y.Z` once the tag is pushed, so afterwards the tag is the only ref
naming those commits — which is exactly what the release summary tells the
operator to pass. `--from` and `--to` are validated as ref names before reaching
a fetch refspec, since `git ls-remote` matches its arguments as globs.

`uv.lock` is ignored: nothing tracks or consumes these files — no workflow
installs with uv — so they are local resolution artifacts. Three of them were
swept into a merge commit as untracked files once and accounted for 94% of that
diff. Tracking them for reproducible installs is a real decision and belongs in
its own PR, alongside the CI change that would make them load-bearing.

Author: RobertoIskandarani

.github/workflows/security.yml

@@ -74,16 +74,6 @@ jobs:
         # latest released version, so `pip install --upgrade pip` can't pull
         # a patched build. Drop this ignore once pip >= 26.1 is on PyPI.
         # See https://github.com/pypa/pip/pull/13870.
-        #
-        # PYSEC-2026-3483: affects mcp <= 1.27.2 (fixed in 1.28.1). The
-        # authplane-mcp adapter pins mcp <1.28.0 because 1.28 renamed the
-        # elicitation field elicitationId -> elicitation_id (snake_case),
-        # which breaks url_elicitation.py's ElicitRequestURLParams wire
-        # handling (every consent-driven exchange would raise a pydantic
-        # ValidationError). Accepted risk until the adapter is migrated to
-        # the 1.28 field name and the floor is raised to 1.28.1; drop this
-        # ignore then.
         run: >-
           pip-audit --skip-editable --progress-spinner off
           --ignore-vuln CVE-2026-3219
-          --ignore-vuln PYSEC-2026-3483

.github/workflows/workflows-lint.yml

@@ -1,19 +1,28 @@
-name: Lint workflows
+name: Release tooling
 
 # Catches workflow YAML / shell-in-`run:` regressions at PR time so a
 # typo can't reach a release tag and surface only when a publish run
-# fails. Scoped to changes under `.github/workflows/**` to keep CI
-# overhead off unrelated PRs.
+# fails. The shell scripts under scripts/ are in the same category — a
+# break in them surfaces only when someone reaches for them after a
+# release, which is the worst moment to discover it — so they are linted
+# and tested here too. Scoped to those two paths to keep CI overhead off
+# unrelated PRs.
+#
+# The scripts trigger is `scripts/**`, not `scripts/*.sh`: a single-level
+# glob would leave a future scripts/lib/*.sh both untriggered here and
+# unlinted below, in each case silently.
 
 on:
   pull_request:
     paths:
       - ".github/workflows/**"
+      - "scripts/**"
   push:
     branches:
       - main
     paths:
       - ".github/workflows/**"
+      - "scripts/**"
 
 permissions:
   contents: read
@@ -56,9 +65,36 @@ jobs:
           echo "${ACTIONLINT_INSTALL_DIR}" >> "${GITHUB_PATH}"
           "${ACTIONLINT_INSTALL_DIR}/actionlint" -version
 
-      # `-shellcheck=shellcheck` makes the shellcheck dependency explicit
-      # rather than relying on actionlint's implicit lookup against the
-      # runner image's $PATH; if the Ubuntu image ever drops shellcheck the
-      # job fails loudly instead of silently degrading.
+      # Both steps below resolve `shellcheck` off the runner image's $PATH —
+      # actionlint via `-shellcheck=shellcheck`, the script lint directly.
+      # Asserting it once, up front, is what makes that dependency explicit:
+      # naming the binary in actionlint's flag only changes which lookup
+      # fails, and neither step announces the version it linted with. If the
+      # Ubuntu image ever drops shellcheck, this fails first and says so,
+      # rather than actionlint quietly degrading to no shell analysis.
+      - name: Check shellcheck is available
+        run: shellcheck --version
+
       - name: Run actionlint
         run: actionlint -color -shellcheck=shellcheck
+
+      - name: Shellcheck the release scripts
+        # find, not `scripts/*.sh`: the single-level glob would silently skip
+        # a future scripts/lib/*.sh, the same blind spot the path trigger had.
+        # An empty result is an error rather than a green no-op, so a moved or
+        # renamed directory cannot pass as a clean lint.
+        run: |
+          mapfile -d '' -t sh_files < <(find scripts -type f -name '*.sh' -print0)
+          if [[ ${#sh_files[@]} -eq 0 ]]; then
+            echo "error: no shell scripts found under scripts/" >&2
+            exit 1
+          fi
+          printf 'shellcheck: %s\n' "${sh_files[@]}"
+          shellcheck "${sh_files[@]}"
+
+      # backport-fixes.sh accepts a branch or a tag as --from, and only the
+      # branch form has a remote-tracking ref. The tag form is what the release
+      # flow tells you to use once release.yml has deleted the branch, so it is
+      # the form least likely to be exercised before it is needed.
+      - name: Test backport-fixes.sh
+        run: scripts/backport-fixes.test.sh

.gitignore

@@ -22,6 +22,14 @@ wheels/
 .installed.cfg
 *.egg
 
+# uv lockfiles. Not tracked on main and nothing consumes them — no workflow
+# installs with uv — so they are local resolution artifacts. Three of them were
+# swept into a merge commit as untracked files and accounted for 94% of a PR's
+# diff; ignoring them is what stops that recurring. Tracking them for
+# reproducible installs is a real decision, and it belongs in its own PR
+# alongside the CI change that would make them load-bearing.
+uv.lock
+
 # Testing
 .pytest_cache/
 .coverage

CHANGELOG.md

@@ -23,35 +23,70 @@ Tests can carry optional coverage metadata to flag partial coverage or known gap
 
 ```python
 @pytest.mark.conformance(
-    "rfc9449-dpop-proof-jwk-must-not-include-private-key-material",
+    "<catalog-case-id>",
     level="partial",
     gaps=["expected.error_hint"],
-    note="Python rejects the proof but does not expose a stable diagnostic.",
+    note="<which part of the case the test does not reach>",
 )
 async def test_...(...):
     ...
 ```
 
+The case id is a placeholder on purpose: naming a real one here would claim
+coverage metadata that the marker on the actual test may not carry.
+
 | Parameter | Default | Description |
 |-----------|---------|-------------|
-| `level` | `"full"` | `"full"` or `"partial"` — how closely the test matches the catalog spec |
-| `gaps` | `[]` | List of expected catalog fields not covered by this test |
-| `note` | `""` | Free-text explanation (appears in both JSON and Markdown reports) |
+| `level` | `"full"` | `"full"` or `"partial"` — how closely the test matches the catalog spec. Always reaches `conformance-report.md`. |
+| `gaps` | `[]` | Catalog *field paths* the test does not reach (`use_case`, `expected.error_hint`, …). Reaches `conformance-report.md` only alongside a `note`; always reaches `conformance-report.json`. |
+| `note` | `""` | Free-text prose. Gates the Coverage Notes section — see below. |
+
+Keep them in that order — `gaps` names the fields, `note` carries the prose —
+and **always write a `note` alongside `gaps`, because `note` is the gate**. In
+`conftest.py`'s `_build_markdown_report`, a single filter (`:216`) selects the
+cases with a truthy `note`, and it decides both whether the Coverage Notes
+section is emitted at all (`:217`) and which cases it lists (`:219`) — and the
+`Gaps:` line (`:224-225`) is emitted *inside* that section. So a `gaps`-only
+marker states no reason anywhere in `conformance-report.md` and its `gaps`
+survive in `conformance-report.json` alone; set a `note` and both render.
+
+`level` is not gated on `note`: it reaches the markdown either way, via the
+Cases table's Coverage column (`:193-197`).
+
+Also keep `|` out of the `note` — it is interpolated into a markdown table cell
+unescaped and will break the row.
+
+### Partial coverage vs. not implemented
 
-### Not-yet-implemented tests
+A test that exercises part of a case but not all of it is a `partial`: it still
+runs and still asserts. Prefer that over an `xfail` wherever one is honest — an
+`xfail` asserts nothing, so it cannot notice the day the gap closes, and it
+reports as a skip while the report carries the case as not-run.
 
-Tests for features that don't exist yet should still be present with the marker and a `pytest.xfail(...)` body that documents what is missing:
+A case with nothing behind it at all should carry the marker with a
+`pytest.xfail(...)` body documenting what is missing:
 
 ```python
 @pytest.mark.conformance(
-    "rfc9449-dpop-inbound-nonce-must-be-validated-when-required",
-    note="Not implemented: the SDK has no nonce generation, DPoP-Nonce challenge emission, or challenge-retry lifecycle for resource servers.",
+    "<catalog-case-id>",
+    note="Not implemented: <what the SDK does not have>.",
 )
-async def test_rfc9449_dpop_inbound_nonce_must_be_validated_when_required(...):
+async def test_<catalog_case_id>(...):
     pytest.xfail("Not implemented: ...")
 ```
 
-These tests show up as `skipped` (with their `note` carried through) in both `conformance-report.json` and `conformance-report.md` — pytest classifies `xfail` outcomes as skips. Keeping the suite green for known gaps means CI never has to be ignored to merge; the gap is still visible in the report's per-case status and coverage notes.
+The id is a placeholder deliberately: **the suite currently has no `xfail`s**,
+so there is no live case to point at, and `test_catalog_alignment.py` requires
+every catalog id to carry a marker — so any real id named here would be one
+that does have a test behind it. (This section previously used
+`rfc9449-dpop-inbound-nonce-must-be-validated-when-required` as its worked
+example; that case now runs as a `partial`.)
+
+`xfail` tests show up as `skipped` — with their `note` carried through — in both
+`conformance-report.json` and `conformance-report.md`, because pytest
+classifies `xfail` outcomes as skips. Keeping the suite green for known gaps
+means CI never has to be ignored to merge; the gap stays visible in the
+report's per-case status and coverage notes.
 
 ## Running
 

conformance-tests/README.md

@@ -10,22 +10,48 @@ async def test_rfc9068_valid_at_jwt_must_verify(...):
 Optional coverage metadata can be added::
 
     @pytest.mark.conformance(
-        "rfc9449-dpop-proof-jwk-must-not-include-private-key-material",
+        "<catalog-case-id>",
         level="partial",
         gaps=["expected.error_hint"],
-        note="Python rejects the proof but does not expose a stable diagnostic.",
+        note="<which part of the case the test does not reach>",
     )
     async def test_...(...):
         ...
 
-Tests that are not yet implemented should use ``pytest.xfail`` — these
-appear as ``skipped`` in the generated report (pytest classifies ``xfail``
-outcomes as skips) so the suite stays green for known gaps while the gap
-itself remains visible in the per-case status and the ``note`` field::
+Case ids in this docstring are placeholders on purpose: a real id here would
+be claiming coverage metadata that the marker on the actual test may not
+carry.
 
-    @pytest.mark.conformance("rfc9449-dpop-inbound-nonce-must-be-validated-when-required")
+``gaps`` holds *catalog field paths* — the parts of the case the test does
+not reach. ``note`` holds the prose. Always write a ``note`` alongside
+``gaps``, because ``note`` is the gate: one filter selects the cases with a
+truthy ``note``, and it decides both whether the Coverage Notes section is
+emitted at all and which cases it lists — and the ``Gaps:`` line is emitted
+*inside* that section. So a ``gaps``-only marker states no reason anywhere
+in ``conformance-report.md`` and its ``gaps`` survive in
+``conformance-report.json`` alone; set a ``note`` and both render. ``level``
+is not gated on ``note`` — it reaches the markdown either way, via the Cases
+table's Coverage column.
+
+A test that exercises part of a case but not all of it is a ``partial`` — it
+still runs and still asserts::
+
+    @pytest.mark.conformance(
+        "<catalog-case-id>",
+        level="partial",
+        gaps=["use_case"],
+        note="setup/stimulus/expected are covered; the lifecycle the use_case "
+        "narrates is not implemented and is not exercised here.",
+    )
     async def test_...(...):
-        pytest.xfail("Not implemented: inbound nonce enforcement")
+        ...
+
+A case with nothing behind it at all should use ``pytest.xfail``, which the
+report records as ``skipped`` (pytest classifies ``xfail`` outcomes as skips)
+so the suite stays green while the per-case status keeps the gap visible.
+Prefer a running ``partial`` where one is honest: an xfail asserts nothing,
+so it cannot notice the day the gap closes. The suite currently has no
+xfails.
 """
 
 import json

conformance-tests/conftest.py

@@ -1077,24 +1077,76 @@ async def test_rfc9449_dpop_replay_store_must_evict_expired_entries() -> None:
 
 @pytest.mark.conformance(
     "rfc9449-dpop-inbound-nonce-must-be-validated-when-required",
-    note="Not implemented: the SDK has no nonce generation, DPoP-Nonce challenge emission, or challenge-retry lifecycle for resource servers.",
+    level="partial",
+    gaps=["use_case"],
+    note=(
+        "setup/stimulus/expected are covered: the verifier enforces a nonce policy "
+        "when one is supplied. The use_case narrative is not: the SDK issues no "
+        "nonce, emits no 401 + DPoP-Nonce challenge, and expected_nonce is not "
+        "reachable from AuthplaneResource.verify() or the MCP adapters, only from "
+        "verify_dpop_proof. That lifecycle is tracked separately."
+    ),
 )
 async def test_rfc9449_dpop_inbound_nonce_must_be_validated_when_required(
     jwks_keypair: dict[str, Any],
 ) -> None:
-    """Full resource-server nonce challenge-retry flow:
-    1. Client sends proof without nonce.
-    2. Resource server responds 401 + DPoP-Nonce: <fresh-nonce>.
-    3. Client retries with the issued nonce in the proof.
-    4. Resource server verifies the nonce matches and accepts.
-
-    The SDK must own the nonce lifecycle: generation, DPoP-Nonce header
-    emission on rejection, and validation on retry. None of this is
-    currently implemented."""
-    pytest.xfail(
-        "Not implemented: SDK lacks nonce generation, DPoP-Nonce challenge "
-        "emission, and the challenge-retry lifecycle for resource servers."
+    """A configured nonce policy must reject a proof that carries the wrong
+    nonce, and one that omits the claim entirely.
+
+    The catalog stimulus is "verify_dpop_proof with nonce policy" — setup
+    supplies ``expected_nonce: server-nonce-abc`` against a proof claiming
+    ``nonce: wrong-nonce``, expecting rejection with hint "nonce". Both arms
+    below match ts-sdk's case for the same id. This is the RFC 9449 §9
+    resource-server nonce, not the §8 AS-provided one.
+
+    This was previously ``pytest.xfail``ed on the grounds that the SDK owns no
+    nonce lifecycle. It does not — but the catalog case does not ask for one,
+    and the primitive it does ask for has been present in ``verify_dpop_proof``
+    all along. The xfail reported as a skip, so the suite stayed green while
+    the report carried the case as not-run."""
+    provider = DPoPProvider(
+        DPoPKeyMaterial.from_pem(jwks_keypair["private_key"], algorithm="ES256")
+    )
+    url = "https://api.example.com/resource"
+
+    wrong_nonce_proof = provider.build_proof("GET", url, access_token="tok", nonce="wrong-nonce")
+    with pytest.raises(InvalidDPoPProofError, match="nonce mismatch"):
+        await verify_dpop_proof(
+            wrong_nonce_proof,
+            method="GET",
+            url=url,
+            replay_store=MemoryReplayStore(),
+            access_token="tok",
+            expected_jkt=provider.key_material.thumbprint,
+            expected_nonce="server-nonce-abc",
+        )
+
+    # RFC 9449 §9: an omitted nonce claim is as much a policy violation as a
+    # wrong one. The catalog's requirement_summary names both.
+    missing_nonce_proof = provider.build_proof("GET", url, access_token="tok")
+    with pytest.raises(InvalidDPoPProofError, match="nonce mismatch"):
+        await verify_dpop_proof(
+            missing_nonce_proof,
+            method="GET",
+            url=url,
+            replay_store=MemoryReplayStore(),
+            access_token="tok",
+            expected_jkt=provider.key_material.thumbprint,
+            expected_nonce="server-nonce-abc",
+        )
+
+    # The policy must not reject the honest case: the nonce the server issued.
+    matching_proof = provider.build_proof("GET", url, access_token="tok", nonce="server-nonce-abc")
+    verified = await verify_dpop_proof(
+        matching_proof,
+        method="GET",
+        url=url,
+        replay_store=MemoryReplayStore(),
+        access_token="tok",
+        expected_jkt=provider.key_material.thumbprint,
+        expected_nonce="server-nonce-abc",
     )
+    assert verified.raw["nonce"] == "server-nonce-abc"
 
 
 @pytest.mark.conformance("rfc9728-well-known-path-must-derive-from-resource-uri")