feat(b2b_learner_records): refuse tokens past the contract end date

[blarghmatey]

What are the relevant tickets?

N/A. Stacked on #69, which adds token.py.

Description (What does it do?)

Learner-records clients carry learner_records_contract_end_date (hardcoded from the contract in mitodl/ol-infrastructure#5939), but nothing checked it. A partner whose contract ended kept reading identifiable records until someone deleted its Keycloak client. This refuses the partner's tokens with a 401 once that date has passed.

Implementation details

• The check runs in verified_claims, after the signature and token-class checks. It returns 401 unauthorized, not 403, because the credential itself is no longer valid.
• The date is inclusive and read as Anywhere on Earth (UTC-12), so access stops at 12:00 UTC the day after the end date. The contract names no timezone, and this is the reading that never cuts a partner off before its end date by its own clock. Partners east of UTC-12 get up to a day of extra access.
• An absent claim means no end date. Existing clients were provisioned without one (the mapper is only created when contract_end_date is set), and treating absence as expired would revoke all of them on deploy.
• A present claim that isn't exactly YYYY-MM-DD (what the mapper writes with date.isoformat()) refuses. date.fromisoformat also accepts 20270630 and ISO week dates, so the parse round-trips to catch those. 9999-12-31 is a valid end date, not an overflow.
• The contract-ended refusal gets its own detail naming the date, unlike the uniform verification refusals. Only a validly signed token reaches that check, so the message tells a forger nothing, and it tells a partner why its sync broke.
• It logs learner_records_contract_ended at warning level when it fires. That means a client outlived its contract and nobody removed it. learner_records_access now carries contract_end_date, so a Loki alert can warn MIT ahead of a lapse. The alert rule itself isn't in this PR.
• docs/b2b-learner-records-provider-authorization.md replaces the open "does access expire with the contract?" question with this behavior. @pdpinch, that question was addressed to you, so please confirm the end-of-day reading before this merges. Partners should be told about it too.

How can this be tested?

ruff check, ruff format --check, mypy src, bin/generate-openapi-spec --check, and the full pytest suite (340 tests) pass locally. New tests cover an expired claim (refused), a future one (accepted), an absent one (accepted), nine malformed values (refused), 9999-12-31, the access-log field, and the UTC-12 boundary through the endpoint at 2027-07-01 11:59:59Z vs. 12:00:00Z. Nothing was run against a live Keycloak token.

🤖 Generated with Claude Code

https://claude.ai/code/session_01GoWu48siDM16978y9JKmhr

[Copilot]

Copilot review overview

🟡 Changes recommended

The operational contract-ended warning event lacks regression coverage.

Get a fresh assessment by requesting another Copilot review.

Review effort: Balanced
Findings: 1

Open (1)

• Add assertions for contract-ended alert logging · New

What changed in this PR

Adds contract-end enforcement for learner-record clients using an inclusive Anywhere-on-Earth cutoff.

Changes:

• Rejects expired or malformed contract-date claims.
• Logs contract dates and expiration events.
• Documents behavior and adds boundary tests.

File	Description
token.py	Enforces contract expiration.
auth.py	Adds contract dates to access logs.
test_learner_records_token.py	Tests expiration and date validation.
b2b-learner-records-v1.yaml	Documents expired-token responses.
b2b-learner-records-provider-authorization.md	Documents the authorization policy.

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.