feat(ai): DeviceFlowTokenProvider — completes MCP device flow (AI-050b)

[mrviduus]

AI-050b — DeviceFlowTokenProvider (Phase 8)

The CLI side of AI-050a: the MCP server now obtains a per-user JWT via the device grant instead of the AI-048a static shared token. Completes the device flow end to end.

Async token-provider interface

IMcpTokenProvider → Task<TokenResult> GetTokenAsync(ct) with Authorized(token) | Pending(verificationUri, userCode) | Failed(msg). TextStackApiClient.AuthorizedRequestAsync awaits it; Pending/Failed → McpUnauthorizedException (now carrying uri+code) → the catalog's shared wrapper renders an actionable IsError: "open {uri} and enter code {user_code} to connect TextStack, then retry."

DeviceFlowTokenProvider — non-blocking

1. Cached access token, local JWT-exp decode (not a security boundary — the API validates the signature on use; just decides refresh) → Authorized.
2. Else cached refresh token → body-based POST /auth/refresh-mobile (rotates the refresh token, re-caches) → Authorized; on 401 fall through.
3. Else start the device flow: POST /auth/device/code, prompt on stderr, spawn a background poll of /auth/device/token at interval until approved (cache) / expired / denied — and return Pending immediately so the tool call never hangs. Self-heals via finally → ClearInFlight so a later call re-initiates.

Token cache

~/.textstack/mcp-token.json (XDG-aware, TEXTSTACK_MCP_TOKEN_CACHE override). 0600 set before the secret is written; group/world-readable files refused on read.

Mode

TEXTSTACK_MCP_TOKEN set → StaticEnvTokenProvider (CI escape hatch); else DeviceFlowTokenProvider. stdout stays JSON-RPC only — the device prompt goes through the stderr-routed logger.

Hardened per adversarial QA (0 P1)

• Single-flight on the device-code request: concurrent first-callers previously each fired their own /auth/device/code (orphaning server codes). Now the claim is taken under the lock before the POST; all concurrent callers share ONE request and return the same Pending code (DeviceCodeCount == 1 test).
• A failed code POST clears the slot (reference-guarded) → retryable, never wedged.
• Genuine caller cancellation propagates via WaitAsync(ct) without killing the shared background poll (CancellationToken.None lifetime); lock never spans await.
• Refresh-token rotation cached; malformed/no-exp/2-segment JWTs treated as expired, never thrown, never returned as Authorized.

Tests — 29 MCP device-flow/cache (full unit suite 561)

Non-blocking timing assert, single-flight concurrency (20 callers → 1 flow), refresh + rotation + 401-fallthrough, exp-decode edge cases, 0600 + world-readable refusal, recovery-on-denied/expired, cancellation propagation. StudyBuddy set-equality green; no ITool leaked.

Verify

• dotnet test tests/TextStack.UnitTests → 561 pass
• dotnet build / dotnet format --verify-no-changes → clean

Unlocks AI-048b (save_highlight write) on a per-user consented token.

🤖 Generated with Claude Code