docs: add research note on revoking Claude Code OAuth tokens

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

docs/research/claude-code-token-revocation.md

@@ -0,0 +1,79 @@
+# Revoking a Claude Code OAuth token
+
+Research into how to revoke a long-lived `CLAUDE_CODE_OAUTH_TOKEN` (the kind
+`claude setup-token` mints), prompted by needing to rotate a token baked into a
+claude-bottle container.
+
+## Summary
+
+There is a documented revoke button, but it does not currently provide reliable
+immediate invalidation. As of early 2026, an open bug shows tokens remaining
+valid for **3–4 days after explicit revocation**, including after "Log out all
+sessions". Anthropic has not commented on the bug or on the related
+feature-request issue. For a known-leaked token there is no guaranteed way to
+make it stop working today; rotate immediately and hope server-side enforcement
+catches up.
+
+## What works (with caveats)
+
+`claude.ai/settings/claude-code` lists active Claude Code instances with a
+per-entry "Revoke" control. This is the only path mentioned in any GitHub
+issue thread; it is not mentioned in the
+[official auth docs](https://code.claude.com/docs/en/authentication), which
+document `claude setup-token` but say nothing about revocation.
+
+A second lever is `claude.ai → Settings → Account → Active Sessions → "Log
+out all sessions"`.
+
+Empirically, neither reliably propagates. [Issue #43801](https://github.com/anthropics/claude-code/issues/43801)
+documents a reproducible failure: the reporter shut down their VM completely
+while offline, performed both revocation actions via claude.ai, waited 3–4
+days, then booted the VM cold — Claude Code authenticated without re-login.
+Because the VM was offline during the revocation window, this isolates the
+failure to the server side. The issue is open with zero Anthropic staff
+responses.
+
+[Issue #34198](https://github.com/anthropics/claude-code/issues/34198) (filed
+March 2026) requests proper server-side revocation on `claude logout` and
+devcontainer shutdown. Also open, also no Anthropic response.
+
+## What does not work
+
+`claude logout` (or `claude /logout`) only clears local credentials. It makes
+no server-side revocation call. Do not rely on it.
+
+It is also not confirmed whether changing the Anthropic account password or
+revoking the broader account session invalidates Claude Code OAuth tokens; no
+issue thread tested this directly.
+
+## Unconfirmed
+
+- Whether `setup-token`-generated long-lived tokens appear on
+  `claude.ai/settings/claude-code` as a distinct entry type vs. interactive
+  sessions. Plausible but not confirmed.
+- Whether the 3–4 day server-enforcement gap is consistent or has been
+  silently reduced since the issue was filed. No release notes mention it.
+- Whether contacting Anthropic support for a leaked token gets faster
+  server-side action than the self-service UI.
+
+## Practical rotation procedure
+
+For a known-leaked or suspected-leaked token:
+
+1. Revoke the entry at `claude.ai/settings/claude-code`.
+2. Run "Log out all sessions" under Settings → Account → Active Sessions.
+3. Run `claude setup-token` to mint a replacement, and rotate it into
+   `CLAUDE_BOTTLE_OAUTH_TOKEN` immediately.
+4. Email Anthropic support at `support.anthropic.com`. Security issues
+   sometimes get attention that GitHub issues do not.
+
+The new token is in effect right away; the old token may continue to
+authenticate for up to several days. There is no client-side mitigation for
+that — the server is the only authority.
+
+## Sources
+
+- [Authentication — Claude Code docs](https://code.claude.com/docs/en/authentication)
+- [#43801 — revocation does not invalidate OAuth tokens](https://github.com/anthropics/claude-code/issues/43801)
+- [#34198 — feature request: server-side revoke on logout](https://github.com/anthropics/claude-code/issues/34198)
+- [#13350 — OAuth token revoked / Please run /login](https://github.com/anthropics/claude-code/issues/13350)