feat(witan-core): ask for offline_access at login, so a session outlives its task

[blarghmatey]

What are the relevant tickets?

Addresses tk-a-witan-login-lasts-5-minutes-of-token-and-dies--550dd4. Unblocks
tk-re-measure-indeterminate-writes-in-qa-once-witan-100d95, which cannot run today.

Description (What does it do?)

• witan login requests openid offline_access instead of openid alone.
• Falls back to plain openid when the realm refuses the scope.
• Releases witan-core 0.21.0.

The device grant tied the refresh token to the interactive SSO session, which on
this deployment is about five minutes. A login went stale in the middle of the
work it was started for, and retrying did not help — a fresh login died at the
same point.

Measured, not inferred. The concurrency probe needs ~8 minutes across two
phases (lead 20 + WORKER_TIMEOUT_S 90 + _PHASE_MARGIN_S 120 = 230s each). On
2026-08-16 it pinned a token for phase A with 249s of life, then got
invalid_grant pinning phase B — four minutes after a successful login:

probe A: token pinned, 249s of life for a 230s phase
...
_pinned_token → auth._refresh(entry["refresh_token"], client)
NeedsLogin: Session expired — run `witan login` to re-authenticate.

--lead cannot rescue it: 90 + 120 dominates, so even --lead 1 leaves 211s
per phase. That blocks the witan deployment's phase-exit measurement outright.

Keycloak advertises an offline refresh token as refresh_expires_in: 0, which
_store_token already interprets as "never expires" rather than "already
expired", so nothing downstream needed changing.

★ The trade, stated plainly

The cached refresh token stops expiring on its own, so a stolen cache file is
usable until the grant is revoked at the IdP rather than until the session
lapses. That is a real widening of exposure.

It is accepted because:

• the cache is created by os.open(..., 0o600) — restrictive from creation,
  never even briefly group- or world-readable (there is an existing test
  asserting the mode);
• the alternative on offer was raising the realm's SSO Session Idle/Max, which
  would lengthen every session for every client rather than just this
  credential.

Revocation now belongs to the IdP; there is no longer a short clock doing it
implicitly. Worth a look if that is not an acceptable posture for this realm —
the realm-config route is the other option and this PR does not foreclose it.

How can this be tested?

just test-witan-core   # 501 passed, 2 skipped

Three new tests, each verified to bind by reverting _LOGIN_SCOPE to
"openid" — test_login_asks_for_offline_access and
test_login_falls_back_when_the_realm_refuses_offline_access both fail, while
test_a_non_scope_failure_at_the_device_endpoint_is_not_retried correctly stays
green.

End-to-end confirmation is a real witan login --target qa followed by a probe
run that survives both phases. I have not run that — it needs an interactive
device flow — so the live behaviour of this change is unverified and the
realm may yet refuse the scope. If it does, the fallback keeps login working and
we take the realm-config route instead.

Additional Context

Why the fallback is not optional. A realm that does not grant
offline_access to this client answers the device-authorization endpoint with
invalid_scope. Raising there would convert a convenience into "nobody can log
in at all" — strictly worse than the short session being fixed. So that specific
refusal retries with plain openid.

Why only that refusal. Any other failure propagates and is deliberately not
retried. A 500 is not a scope problem, and a second identical attempt would bury
the diagnosis rather than surface it. A test asserts the endpoint is hit exactly
once in that case.

🤖 Generated with Claude Code

https://claude.ai/code/session_01JYb9sMjetD9Nxjf24Aw3m5

[Copilot]

Pull request overview

Updates Witan’s OIDC device login to request longer-lived offline sessions while retaining compatibility with realms that reject the scope.

Changes:

• Requests openid offline_access, with an openid fallback.
• Adds tests for scope handling and retry behavior.
• Releases witan-core 0.21.0.

Reviewed changes

Copilot reviewed 4 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
packages/witan-core/witan_core/remote/oidc.py	Implements offline-access requests and fallback.
packages/witan-core/tests/test_remote_oidc.py	Tests scope and fallback behavior.
packages/witan-core/pyproject.toml	Bumps the package version.
packages/witan-core/CHANGELOG.md	Documents the release and security tradeoff.
uv.lock	Synchronizes the workspace version.

---

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