feat(auth): logout/clear commands and client_id mismatch diagnostic

[robpc]

Re-lands the useful part of #15 — Jess Finger's bebb0b5, cherry-picked from the archived yahoo-orion/desk#52 — on top of #83. Jess is credited as co-author on the commit.

Stacked on #83 (feat/scope-aware-commands): this needs ADR-037's granted-scope missing_scopes and edits the same auth status code, so the base is #83's branch. GitHub retargets to main when #83 merges; the diff shown here is only this PR's work.

What it adds — ADR-040

Recovering from stale keychain state (a token minted against a different OAuth client than the one now configured) used to mean security CLI surgery. The keyring helpers existed but nothing exposed them.

• desk auth logout — removes the OAuth token, keeps the client credentials, scrubs secrets from the legacy ~/.desk/token.json. Idempotent. --json.
• desk auth clear [--token|--client] [--yes] — removes token and/or client credentials. Confirmation prompt; --yes required when there's no TTY (same pattern as docs delete-tab). --json.
• desk auth status now reports client_id (what the next login would use — keyring, then credentials.json, same order as login()), token_client_id (what minted the stored token), and token_source (keyring / file / gcloud_adc / none). When the two client ids differ, the human output says the token cannot refresh and names the fix.
• desk auth set-client drops a stored token whose client_id differs from the new one, with a one-line note — the token could never have refreshed against it.
• keyring_store.delete_client_credentials() mirrors delete_token().

What's deliberately dropped from #15

• The bundled-credentials fallback. _get_configured_client_id() fell through to get_bundled_credentials(), which exists in the yahoo-orion fork and was never part of robpc/desk — that import is why feat(auth): add logout/clear commands and stale-token detection #15's CI never passed here.
• The stored scopes field and its display. It printed the token's requested scope list, the same requested-vs-granted confusion feat(cal,meet): scope-aware commands, Calendar event fields, Google Meet settings #83 fixed (auth: granted scopes are never persisted, so auth status missing_scopes is always empty #82). missing_scopes from ADR-037 is the actionable signal and is already on auth status, so this PR leans on it instead. A test pins that scopes stays absent and missing_scopes stays present.

Kept from #15 but not on the original keep list: the set-client auto-invalidation. It is the proactive half of the same mismatch diagnostic, three lines, and already tested — easy to pull if unwanted.

clear composes delete_token() + delete_client_credentials() rather than calling clear_all(), so its result can say which key was actually removed (--json consumers get keyring_token_removed / keyring_client_removed separately).

Verification

• 27 new tests (tests/test_auth_logout_clear.py): logout idempotence and legacy-file scrub (including that ADR-037's granted_scopes survives the scrub), the clear flag matrix, non-interactive --yes enforcement, status field shape and credentials.json fallback, the mismatch wording in human output, and the set-client invalidation path.
• 1022 tests total, 1021 passing normally and under PYTHON_KEYRING_BACKEND=keyring.backends.fail.Keyring; the one failure (test_preexisting_directory_tightened_to_0o700) fails identically on main in a umask-077 sandbox and passes in CI.
• ruff check clean.
• Live, read-only: desk auth status on this build shows the configured and token client_id matching with token source: keyring; desk auth --help lists clear and logout. logout/clear were not run against the real keychain.

Docs

ADR-040 (Jess's ADR-017/019 text, renumbered past #83's ADR-039, with a "What changed in the re-land" section), decisions index, CLAUDE.md architecture tree, README "Signing out and resetting".

Refs #15 (to be closed once this merges).

🤖 Generated with Claude Code