[#4253 8/8] docs+test: release notes, policy docs, two-VP same-id integration test

[stevenvegt]

Parent PRD

#4253

Item 8 of 8, the integration close-out. Depends on #5 (#4287), #6 (#4288), #7 (#4290) — and transitively the rest. Based on the feature branch, since it exercises and documents the fully integrated behavior.

Summary

Document the new behavior and verify it end to end: release-notes entries (user-facing only), a docs/pages/deployment/policy.rst update, and an embedded-node integration test for the two-VP same-id binding.

Release notes — docs/pages/release_notes.rst

Append to the existing Unreleased / ## New features section. User-facing changes only — the MatchReport diagnostics are internal in this PRD (no endpoint/UI surface yet), so they are not mentioned here. Entries (each referencing #4253 and linking the relevant PR), with details deferred to the policy docs:

• Same-id binding: within one PresentationDefinition, reusing a field id across descriptors now requires the chosen credentials to agree on that id's value (previously the id was decorative and descriptors were matched independently).
• credential_selection validation: unknown credential_selection keys on request-service-access-token now return 400 invalid_request naming every unknown key, validated against the in-scope PD(s) (single-VP) or their union (two-VP). (Previously an unknown key surfaced inconsistently; the per-descriptor selector no longer rejects keys mid-flow.)
• Load-time PD validation: a policy or discovery PresentationDefinition whose same-id fields have incompatible filters (conflicting type/const, etc.) now fails at startup with an error naming the field id. Includes a one-line audit checklist: search deployed PDs for repeated id names, confirm the intended shared-value semantics, and verify filters on shared ids agree on type and const.

Each entry links to the new policy-docs section for detail.

Docs — docs/pages/deployment/policy.rst

Add a section explaining, for PD authors:

• how a reused field id across descriptors binds credentials to a single shared value (with a short example, e.g. org_ura on the HCP and delegation descriptors);
• that inconsistent same-id filters fail the node at boot, and what "consistent" means (same declared type/const; path differences allowed; pattern-vs-pattern not checked);
• credential_selection key validation and the 400 invalid_request response.
  Cross-link from oauth.rst if it documents request-service-access-token.

Integration test — auth/api/iam/jwtbearer_integration_test.go

Extend the existing embedded-node harness (node.StartServer, the medication-overview policy + the three MO credentials) rather than adding a docker scenario. Add scenarios on a policy whose organization and service_provider PDs share a field id:

• Policy 3 binding (happy path): the shared id resolves to one value across the chosen org and SP credentials → token issued; both VPs verify.
• Policy 3 binding (negative): a wallet whose only candidate pair disagrees on the shared id → no consistent assignment → request-service-access-token fails (no token), not a silently mismatched pair.
• Problem added baseline funcs from old repo #1 (cross-VP leniency): an org-captured id that is not a field id on the SP PD does not break the SP build — token still issued (regression test for the over-strict selector that Add error handling middleware to echo server #3/Moved Nuts-Network to Nuts-Node and implemented RFC004 #5 removed).

These exercise the real engine, real signing, and real VP verification through the integrated stack.

Acceptance Criteria

• Release notes: three user-facing entries under Unreleased (no MatchReport), each linking the policy docs; audit checklist included.
• policy.rst explains same-id binding, load-time validation, and credential_selection validation.
• Integration test covers same-id happy path, mismatch rejection, and the org-only-captured-key (problem added baseline funcs from old repo #1) case.
• go test ./auth/api/iam/... passes; docs build.

Out of scope

• The MatchReport developer-diagnostics surface (endpoint/UI) — separate follow-up to Facilitate developers with their policy development #4218.

[qltysh]

Coverage Impact

This PR will not change total coverage.

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.