opencode-anthropic-fix 0.6.0 → 2.0.0

package/lib/oauth.mjs

@@ -1,33 +1,38 @@
 import { createHash, randomBytes } from "node:crypto";
-import { CLIENT_ID, loadConfig } from "./config.mjs";
+import { loadConfig } from "./config.mjs";
 import { parseRetryAfterHeader, parseRetryAfterMsHeader } from "./backoff.mjs";
+import {
+  OAUTH_BETA,
+  OAUTH_CLAUDE_AI_AUTHORIZE_URL,
+  OAUTH_CLIENT_ID,
+  OAUTH_CONSOLE_AUTHORIZE_URL,
+  OAUTH_REDIRECT_URI,
+  OAUTH_SDK_USER_AGENT,
+  OAUTH_TOKEN_URL,
+} from "./oauth-constants.mjs";
+import { CLAUDE_AI_BASE_SCOPES, composeScopes, missingBaseScopes, serializeScopes } from "./oauth-scopes.mjs";
+import { resolveCustomOAuthUrl } from "./oauth-env.mjs";
 
 // ---------------------------------------------------------------------------
 // OAuth helpers — shared between plugin (index.mjs) and CLI (cli.mjs)
+//
+// Every *genuine* endpoint, user-agent and beta name used here is imported from
+// ./oauth-constants.mjs, which transcribes docs/oauth-2.1.280-contract.md.
+// This module owns OAuth *behaviour*; it owns no genuine OAuth *values*. The one
+// value it does own is OAUTH_REVOKE_URL below, which is a divergence (D1) and is
+// deliberately kept out of the transcription module.
 // ---------------------------------------------------------------------------
 
-const OAUTH_CONSOLE_HOST = "platform.claude.com";
-const OAUTH_MAX_HOST = "claude.ai";
-const OAUTH_REDIRECT_URI = `https://${OAUTH_CONSOLE_HOST}/oauth/code/callback`;
-const OAUTH_TOKEN_URL = `https://${OAUTH_CONSOLE_HOST}/v1/oauth/token`;
-const OAUTH_REVOKE_URL = `https://${OAUTH_CONSOLE_HOST}/v1/oauth/revoke`;
-// Real Claude Code uses axios 1.13.6 for OAuth calls — axios sets User-Agent
-// automatically and adds Accept header. We must match this fingerprint exactly.
-// CLI version profile: 2.1.84 (for reference; not sent on OAuth calls)
-const OAUTH_AXIOS_VERSION = "1.13.6";
-const OAUTH_USER_AGENT = `axios/${OAUTH_AXIOS_VERSION}`;
-const OAUTH_ACCEPT = "application/json, text/plain, */*";
-// Claude Code 2.1.195 migrated the OAuth token client from axios to the
-// Anthropic TS SDK's native-fetch `userOAuthProvider`. When the
-// `oauth.sdk_token_useragent` config flag is ON, the token POST switches to
-// this fingerprint: `User-Agent: anthropic-sdk-typescript/0.94.0
-// userOAuthProvider`, `anthropic-beta: oauth-2025-04-20`, JSON body, and NO
-// axios `Accept` header (native fetch sends no default Accept). The SDK version
-// mirrors request-headers.mjs `ANTHROPIC_SDK_VERSION` ("0.94.0"); hardcoded here
-// to avoid coupling the OAuth path to the messages-header module.
-const OAUTH_SDK_VERSION = "0.94.0";
-const OAUTH_SDK_USER_AGENT = `anthropic-sdk-typescript/${OAUTH_SDK_VERSION} userOAuthProvider`;
-const OAUTH_SDK_BETA = "oauth-2025-04-20";
+/**
+ * The RFC 7009 revocation endpoint.
+ *
+ * NOT PART OF GENUINE CLIENT BEHAVIOUR. `/v1/oauth/revoke` appears nowhere in
+ * the Claude Code 2.1.280 bundle, so this URL is deliberately absent from
+ * ./oauth-constants.mjs — that module is the transcription of the genuine
+ * contract, and this is a divergence.
+ * @see docs/oauth-2.1.280-contract.md §6 item 1, §7 divergence D1
+ */
+const OAUTH_REVOKE_URL = "https://platform.claude.com/v1/oauth/revoke";
 const OAUTH_MAX_RETRIES = 2;
 const OAUTH_MAX_RETRY_DELAY_MS = 30_000;
 const OAUTH_RATE_LIMIT_COOLDOWN_MS = 30_000;
@@ -35,14 +40,23 @@ const OAUTH_RETRY_AFTER_SOURCE_HEADER_MS = "retry-after-ms";
 const OAUTH_RETRY_AFTER_SOURCE_HEADER = "retry-after";
 const OAUTH_RETRY_AFTER_SOURCE_FALLBACK_429 = "fallback-429";
 
-export const CLAUDE_AI_SCOPES = [
-  "user:profile",
-  "user:inference",
-  "user:sessions:claude_code",
-  "user:mcp_servers",
-  "user:file_upload",
-];
-const CONSOLE_SCOPES = ["org:create_api_key", "user:profile"];
+/**
+ * The claude.ai base scope set, in wire order.
+ *
+ * The array itself is now owned by `./oauth-scopes.mjs`, which composes the
+ * conditional extensions. This is an alias binding onto that same frozen array
+ * (not an `export … from` re-export), retained so existing importers of
+ * `CLAUDE_AI_SCOPES` keep resolving.
+ *
+ * PARITY IS CONDITIONAL. §13.8 records two conditional extensions to this set:
+ * `user:plugins` is appended when the `PLUGINS_SCOPE_REGISTERED` gate is on, and
+ * `user:projects:read` / `user:projects:write` when requested. §13.8 does not
+ * record the gate's shipped state. If it ships on, a genuine authorize URL
+ * carries six scopes and this five-scope URL is itself a distinguishing signal.
+ * That is an open, unverifiable item, not a solved one.
+ * @see docs/oauth-2.1.280-contract.md §4.1, §4.2, §7 divergence D9
+ */
+export const CLAUDE_AI_SCOPES = CLAUDE_AI_BASE_SCOPES;
 
 function base64url(input) {
   return Buffer.from(input).toString("base64url");
@@ -56,40 +70,108 @@ function generatePKCE() {
 }
 
 /**
- * Resolve whether the SDK-native-fetch token fingerprint should be used.
- * An explicit boolean override (used by callers/tests) wins; otherwise the
- * live `oauth.sdk_token_useragent` config flag is read (default true).
+ * Resolve whether logout should attempt server-side token revocation.
+ *
+ * Defaults to `false`: revocation is not genuine-client behaviour, so it is an
+ * explicit opt-in rather than something a user has to discover and disable.
+ * An explicit boolean override (used by callers/tests) wins.
  * @param {boolean | undefined} override
  * @returns {boolean}
+ * @see docs/oauth-2.1.280-contract.md §7 divergence D1
  */
-function useSdkTokenFingerprint(override) {
+function revokeOnLogoutEnabled(override) {
   if (typeof override === "boolean") return override;
   try {
-    return loadConfig()?.oauth?.sdk_token_useragent === true;
+    return loadConfig()?.oauth?.revoke_on_logout === true;
   } catch {
     return false;
   }
 }
 
+/**
+ * Resolve the scope gates for an authorize call.
+ *
+ * An explicit option always wins over config, so a caller can force either
+ * state in a test without touching the user's config file. A wrongly-typed
+ * explicit option throws rather than silently deferring to config: these are
+ * programmer inputs, and a silent fallback would make the forced state a lie.
+ *
+ * Config is read live (never cached in a closed-over constant) because
+ * `/anthropic set` mutates it at runtime, and it is read ONLY when at least one
+ * gate is still unresolved — `authorize()` used to be free of any filesystem
+ * dependency and should reacquire one no more often than it must.
+ *
+ * A config read that fails degrades to the documented defaults rather than
+ * failing the login, but it warns: silently downgrading a user who configured
+ * `plugins_scope: true` to a five-scope token with no diagnostic is exactly the
+ * kind of unexplained behaviour this project treats as a defect.
+ * @param {{pluginsRegistered?: boolean, projectScopes?: string[]} | null} [options]
+ * @returns {{pluginsRegistered: boolean, projectScopes: unknown}}
+ * @see docs/oauth-2.1.280-contract.md §4.2, §7 divergence D9
+ */
+function resolveScopeOptions(options) {
+  const opts = options ?? {};
+  const pluginsExplicit = opts.pluginsRegistered !== undefined;
+  const projectExplicit = opts.projectScopes !== undefined;
+  if (pluginsExplicit && typeof opts.pluginsRegistered !== "boolean") {
+    throw new TypeError("authorize(): options.pluginsRegistered must be a boolean when supplied");
+  }
+  if (projectExplicit && !Array.isArray(opts.projectScopes)) {
+    throw new TypeError("authorize(): options.projectScopes must be an array when supplied");
+  }
+  if (pluginsExplicit && projectExplicit) {
+    return { pluginsRegistered: opts.pluginsRegistered === true, projectScopes: opts.projectScopes };
+  }
+
+  let oauth;
+  try {
+    oauth = loadConfig()?.oauth;
+  } catch (err) {
+    console.warn(
+      `[anthropic-auth] could not read config while composing OAuth scopes; requesting the default set: ${err?.message ?? err}`,
+    );
+    oauth = undefined;
+  }
+  return {
+    pluginsRegistered: pluginsExplicit ? opts.pluginsRegistered === true : oauth?.plugins_scope === true,
+    projectScopes: projectExplicit
+      ? opts.projectScopes
+      : Array.isArray(oauth?.project_scopes)
+        ? oauth.project_scopes
+        : [],
+  };
+}
+
 /**
  * Build the headers for an OAuth token POST (exchange/refresh).
- * @param {boolean} useSdk - When true, emit the CC 2.1.195 SDK-native-fetch
- *   fingerprint; when false, emit the legacy axios fingerprint (default).
+ *
+ * MEASURED FOR REFRESH, ASSUMED FOR EXCHANGE. §13.8 attests this triple only at
+ * the refresh call site (byte 4429828). It records no `authorization_code` grant
+ * at all, so reusing the triple on exchange is assumption D8, not a measurement.
+ *
+ * This module emits one triple rather than switching between two: no axios usage
+ * appears anywhere in §13.8, so a switch selecting an axios shape could not make
+ * a user more anonymous — it would make them the only client sending that shape.
+ *
+ * SCOPE OF THE CLAIM: these are the three headers this module controls. The host
+ * runtime adds its own (`host`, `connection`, `accept-encoding`, `content-length`
+ * and others) with its own casing and ordering. §13.8 names no transport and no
+ * platform, so the runtime-added set is unverifiable from the evidence and is
+ * listed as an open signal in the contract doc. §13.8 also records a second
+ * token-endpoint fingerprint (`oidcFederationProvider`); that surface is out of
+ * scope here (D12).
+ *
+ * Header **order** is emitted in the order §13.8 enumerates it for refresh; the
+ * source literal's own order is not attested. The literal is built in emission
+ * order and must never be sorted or spread through a helper that reorders it.
  * @returns {Record<string, string>}
+ * @see docs/oauth-2.1.280-contract.md §2.3, §2.5, §7 divergences D8 and D12
  */
-function buildTokenHeaders(useSdk) {
-  if (useSdk) {
-    // Native fetch sends no default Accept header — omit it deliberately.
-    return {
-      "Content-Type": "application/json",
-      "anthropic-beta": OAUTH_SDK_BETA,
-      "User-Agent": OAUTH_SDK_USER_AGENT,
-    };
-  }
+function buildTokenHeaders() {
   return {
-    Accept: OAUTH_ACCEPT,
     "Content-Type": "application/json",
-    "User-Agent": OAUTH_USER_AGENT,
+    "anthropic-beta": OAUTH_BETA,
+    "User-Agent": OAUTH_SDK_USER_AGENT,
   };
 }
 
@@ -205,19 +287,69 @@ function parseOAuthErrorBody(rawText) {
 
 /**
  * Build an OAuth authorization URL with PKCE challenge.
+ *
+ * ASSUMPTION — THE QUERY STRING IS NOT ATTESTED. §13.8 records the two authorize
+ * *URLs* and nothing else about this request: no query parameter set, no
+ * parameter order, no PKCE material, and no redirect URI. Everything below the
+ * origin and path is therefore pre-existing plugin behaviour preserved verbatim,
+ * not a transcription of a measurement. Tests pin it so it cannot drift
+ * accidentally; they do not certify it as genuine.
+ *
+ * The scope list is composed at call time from a base set plus gated additions.
+ * Defaults reproduce the previous five-scope / two-scope strings byte for byte.
+ * The genuine client's gate state is unattested (§7 divergence D9).
  * @param {"max" | "console"} mode
+ * @param {{pluginsRegistered?: boolean, projectScopes?: string[]}} [options]
  * @returns {Promise<{url: string, verifier: string, state: string}>}
+ * @see docs/oauth-2.1.280-contract.md §2.1, §1.1 (OAUTH_REDIRECT_URI)
  */
-export async function authorize(mode) {
-  const pkce = generatePKCE();
+export async function authorize(mode, options = {}) {
+  if (mode !== "max" && mode !== "console") {
+    // Silently treating an unknown mode as consumer login would send a user to
+    // the wrong provider with the wrong scope set and no visible failure.
+    throw new Error(`Unknown OAuth mode "${mode}" (expected "max" or "console")`);
+  }
+
+  // ATTESTED: §13.8 (byte 4657393) records that CLAUDE_CODE_CUSTOM_OAUTH_URL is
+  // validated against a three-entry allowlist and throws otherwise. That throw is
+  // the attested behaviour and is enforced here: an unapproved value rejects with
+  // the byte-exact genuine message.
+  //
+  // NOT ATTESTED: what an APPROVED value is then used for. §13.8 records the
+  // validation, not the consumption, so redirecting the flow to it would be an
+  // invention. But silently ignoring an approved value is worse than either
+  // option: an operator who points this plugin at a FedRAMP endpoint would get no
+  // error and would still have their authorization code and refresh token sent to
+  // platform.claude.com. Validate-then-ignore is a misroute dressed as a feature.
+  // So an approved value is refused explicitly until the use site is attested.
+  // Divergence D14.
+  const customOAuthUrl = resolveCustomOAuthUrl(options?.env ?? process.env);
+  if (customOAuthUrl) {
+    throw new Error(
+      `CLAUDE_CODE_CUSTOM_OAUTH_URL is set to the approved endpoint ${customOAuthUrl}, but this plugin cannot honour it: the evidence records that the value is validated, not what it is used for, so redirecting the flow would be a guess. Unset the variable to authenticate against the default endpoints. See the OAuth wire contract doc, divergence D14.`,
+    );
+  }
 
-  const url = new URL(`https://${mode === "console" ? OAUTH_CONSOLE_HOST : OAUTH_MAX_HOST}/oauth/authorize`);
+  const pkce = generatePKCE();
+  // Console mode ignores both gates (`composeScopes` drops them), so it must not
+  // pay for a config read: `authorize()` acquires a filesystem dependency only
+  // on the path that can actually use the answer.
+  const gates = mode === "console" ? { pluginsRegistered: false, projectScopes: [] } : resolveScopeOptions(options);
+
+  // The consumer authorize page carries a `/cai/` path segment, so this is a
+  // full URL and not a host interpolated into a shared template.
+  const url = new URL(mode === "console" ? OAUTH_CONSOLE_AUTHORIZE_URL : OAUTH_CLAUDE_AI_AUTHORIZE_URL);
+  // --- unattested region: parameter set, order, and values (see the docblock) ---
   url.searchParams.set("code", "true");
-  url.searchParams.set("client_id", CLIENT_ID);
+  url.searchParams.set("client_id", OAUTH_CLIENT_ID);
   url.searchParams.set("response_type", "code");
   url.searchParams.set("redirect_uri", OAUTH_REDIRECT_URI);
-  const scopes = mode === "console" ? CONSOLE_SCOPES : CLAUDE_AI_SCOPES;
-  url.searchParams.set("scope", scopes.join(" "));
+  url.searchParams.set(
+    "scope",
+    serializeScopes(
+      composeScopes({ mode, pluginsRegistered: gates.pluginsRegistered, projectScopes: gates.projectScopes }),
+    ),
+  );
   url.searchParams.set("code_challenge", pkce.challenge);
   url.searchParams.set("code_challenge_method", "S256");
   url.searchParams.set("state", pkce.state);
@@ -310,8 +442,9 @@ export function parseOAuthCallback(input) {
  * Exchange an authorization code for tokens.
  * @param {string} code
  * @param {string} verifier
- * @param {{ sdkTokenUserAgent?: boolean }} [options] - `sdkTokenUserAgent`
- *   overrides the `oauth.sdk_token_useragent` config flag (mainly for tests).
+ * @param {{ sdkTokenUserAgent?: boolean }} [options] - `sdkTokenUserAgent` is
+ *   accepted and ignored. It is retained so existing call sites keep type-
+ *   checking; there is only one token fingerprint. See §7 divergence D2.
  * @returns {Promise<
  *   | { type: "success", refresh: string, access: string, expires: number, email?: string }
  *   | {
@@ -325,8 +458,8 @@ export function parseOAuthCallback(input) {
  *     }
  * >}
  */
-export async function exchange(code, verifier, options = {}) {
-  const tokenHeaders = buildTokenHeaders(useSdkTokenFingerprint(options.sdkTokenUserAgent));
+export async function exchange(code, verifier, _options = {}) {
+  const tokenHeaders = buildTokenHeaders();
   const fail = (status, rawText = "", cooldownHint = { retryAfterMs: null }) => {
     const { errorCode, reason } = parseOAuthErrorBody(rawText);
     const retryAfterMs =
@@ -350,22 +483,27 @@ export async function exchange(code, verifier, options = {}) {
     };
   };
 
-  const { code: _authCode, state: _authState } = parseOAuthCallback(code);
+  const { code: authCode, state: authState } = parseOAuthCallback(code);
   let result;
   for (let attempt = 0; attempt <= OAUTH_MAX_RETRIES; attempt++) {
     try {
-      const _exchangeBody = {
+      // SHAPE IS INPUT-DEPENDENT (D8). `state` is present only when the pasted
+      // callback carried one, so this body is five keys for a bare code and six
+      // for a full callback URL. §13.8 records no authorization_code grant, so
+      // neither shape can be checked against the evidence; the conditional is
+      // preserved because the server has always accepted both from this client.
+      const exchangeBody = {
         grant_type: "authorization_code",
-        code: _authCode,
+        code: authCode,
         redirect_uri: OAUTH_REDIRECT_URI,
-        client_id: CLIENT_ID,
+        client_id: OAUTH_CLIENT_ID,
         code_verifier: verifier,
-        ...(_authState != null ? { state: _authState } : {}),
+        ...(authState != null ? { state: authState } : {}),
       };
       result = await fetch(OAUTH_TOKEN_URL, {
         method: "POST",
         headers: tokenHeaders,
-        body: JSON.stringify(_exchangeBody),
+        body: JSON.stringify(exchangeBody),
         signal: AbortSignal.timeout(15_000),
       });
     } catch (err) {
@@ -427,53 +565,86 @@ export async function exchange(code, verifier, options = {}) {
 }
 
 /**
- * Attempt to revoke a refresh token server-side (best-effort, RFC 7009).
+ * THIS REQUEST IS NOT PART OF GENUINE CLIENT BEHAVIOUR. `/v1/oauth/revoke`
+ * appears nowhere in the Claude Code 2.1.280 bundle, so every revocation this
+ * plugin performs is a request that identifies it. It is therefore gated behind
+ * `oauth.revoke_on_logout`, which defaults to `false`.
+ *
+ * With the gate off the function performs **no network call at all** and
+ * reports `{ attempted: false }`. With the gate on an RFC 7009-*style* request
+ * is sent — note that RFC 7009 §2.1 mandates form encoding and this body is
+ * JSON, matching the rest of this plugin's token layer rather than the RFC.
  *
- * Anthropic may or may not support this endpoint. The function returns
- * `true` on a 2xx response and `false` otherwise — callers should always
- * proceed with local cleanup regardless of the result.
+ * The request carries the same SDK fingerprint as the other token requests
+ * rather than the retired axios one. That is a judgement call, not a parity
+ * claim: §13.8 has no revoke endpoint, so no user-agent is "correct" here, and
+ * a `userOAuthProvider` agent on a path the SDK never calls is arguably its own
+ * tell. The alternative was keeping a second, equally unevidenced fingerprint
+ * alive purely for this one request, which is worse.
+ *
+ * THE RETURN VALUE DISTINGUISHES THREE OUTCOMES, because "we chose not to try"
+ * and "we tried and the server refused" are different facts and a caller must
+ * not report one as the other. Callers must proceed with local cleanup in all
+ * three cases.
  *
  * @param {string} refreshToken
- * @returns {Promise<boolean>}
+ * @param {{ revokeOnLogout?: boolean }} [options] - `revokeOnLogout` overrides
+ *   the config flag (mainly for tests).
+ * @returns {Promise<{ attempted: boolean, ok: boolean, status?: number, error?: string }>}
+ * @see docs/oauth-2.1.280-contract.md §6 item 1, §7 divergence D1
  */
-export async function revoke(refreshToken) {
+export async function revoke(refreshToken, options = {}) {
+  if (!revokeOnLogoutEnabled(options.revokeOnLogout)) return { attempted: false, ok: false };
   try {
     const resp = await fetch(OAUTH_REVOKE_URL, {
       method: "POST",
-      headers: {
-        Accept: OAUTH_ACCEPT,
-        "Content-Type": "application/json",
-        "User-Agent": OAUTH_USER_AGENT,
-      },
+      headers: buildTokenHeaders(),
       body: JSON.stringify({
         token: refreshToken,
         token_type_hint: "refresh_token",
-        client_id: CLIENT_ID,
+        client_id: OAUTH_CLIENT_ID,
       }),
       signal: AbortSignal.timeout(5000),
     });
-    return resp.ok;
-  } catch {
-    return false;
+    return { attempted: true, ok: resp.ok === true, status: resp.status };
+  } catch (err) {
+    return { attempted: true, ok: false, error: err instanceof Error ? err.message : String(err) };
   }
 }
 
 /**
  * Refresh an OAuth access token.
+ * The request body is exactly `{ grant_type, refresh_token, client_id }`.
+ * Genuine Claude Code 2.1.280 sends **no `scope` key** on refresh; sending one
+ * is a positive fingerprint. `options.scopes` is therefore accepted and
+ * ignored — it is retained so existing call sites keep working. No call site in
+ * this repository passes it; the guard exists so a future one cannot silently
+ * reintroduce the key.
+ *
  * @param {string} refreshTokenValue - The refresh token to use
- * @param {{ signal?: AbortSignal, scopes?: string[], sdkTokenUserAgent?: boolean }} [options]
- *   `sdkTokenUserAgent` overrides the `oauth.sdk_token_useragent` config flag
- *   (mainly for tests).
+ * @param {{ signal?: AbortSignal, scopes?: string[], sdkTokenUserAgent?: boolean, clientId?: string }} [options]
+ *   `scopes` and `sdkTokenUserAgent` are accepted and ignored. A caller-supplied
+ *   `signal` bounds the whole call including retries; when omitted, each attempt
+ *   gets its own fresh 30 s timeout.
+ *   `clientId` overrides the default OAuth client id. It exists for
+ *   CLAUDE_CODE_OAUTH_CLIENT_ID-seeded accounts (contract §5.2, divergence D10)
+ *   and does not change the body's key set — it stays exactly
+ *   { grant_type, refresh_token, client_id } per §2.3.
  * @returns {Promise<{access_token: string, refresh_token: string, expires_in: number}>}
  * @throws {Error} On HTTP errors or network failures
+ * @see docs/oauth-2.1.280-contract.md §2.3, §6 item 2
  */
 export async function refreshToken(refreshTokenValue, options = {}) {
-  // QA fix M13: default 30s timeout to prevent hanging on unresponsive server
-  const signal = options.signal ?? AbortSignal.timeout(30_000);
-  const tokenHeaders = buildTokenHeaders(useSdkTokenFingerprint(options.sdkTokenUserAgent));
+  const tokenHeaders = buildTokenHeaders();
 
   for (let attempt = 0; attempt <= OAUTH_MAX_RETRIES; attempt++) {
     let resp;
+    // A single AbortSignal.timeout() created outside the loop starts counting at
+    // creation, so a slow first attempt would leave the retries with no budget
+    // and turn a 3-attempt policy into a 1-attempt one. A caller that supplies
+    // its own signal is explicitly bounding the whole operation, retries
+    // included, so that one is shared on purpose.
+    const signal = options.signal ?? AbortSignal.timeout(30_000);
     try {
       resp = await fetch(OAUTH_TOKEN_URL, {
         method: "POST",
@@ -481,8 +652,8 @@ export async function refreshToken(refreshTokenValue, options = {}) {
         body: JSON.stringify({
           grant_type: "refresh_token",
           refresh_token: refreshTokenValue,
-          client_id: CLIENT_ID,
-          scope: options.scopes ? options.scopes.join(" ") : CLAUDE_AI_SCOPES.join(" "),
+          client_id:
+            typeof options.clientId === "string" && options.clientId.length > 0 ? options.clientId : OAUTH_CLIENT_ID,
         }),
         signal,
       });
@@ -526,11 +697,20 @@ export async function refreshToken(refreshTokenValue, options = {}) {
 
 /**
  * Check if an account has all required Claude.ai scopes.
+ *
+ * "Required" means the five-scope base set only. The conditional extensions
+ * (`user:plugins`, `user:projects:*`) are deliberately NOT required: they are
+ * opt-in, and demanding them would invalidate every already-stored token the
+ * moment a user enables a gate. The consequence is that enabling
+ * `oauth.plugins_scope` on an existing account does not by itself obtain the
+ * scope — the user must re-authorise for the wider grant to be issued. That
+ * gap is recorded in §7.3 of the contract doc.
  * @param {string[] | undefined} scopes
  * @returns {boolean}
  */
 export function hasRequiredScopes(scopes) {
   if (!Array.isArray(scopes) || scopes.length === 0) return false;
-  const stored = new Set(scopes);
-  return CLAUDE_AI_SCOPES.every((s) => stored.has(s));
+  // Routed through missingBaseScopes() so the refresh-time check and the
+  // headless boot-time check in ./oauth-env.mjs cannot drift apart.
+  return missingBaseScopes(scopes).length === 0;
 }

package/lib/passthrough-headers.mjs

@@ -0,0 +1,152 @@
+/**
+ * The emulation-OFF request envelope.
+ *
+ * WHY THIS MODULE IS NOT UNDER lib/mimicry/. That is the point of it. With
+ * `signature_emulation.enabled === false` the plugin makes NO attempt to look
+ * like Claude Code, so no mimicry function may compose the outgoing headers —
+ * if one did, "off" would keep meaning "less mimicry" instead of "none", which
+ * is exactly the half-state Phase 2.2 removed.
+ *
+ * WHAT SURVIVES, AND WHY IT IS NOT MIMICRY. The plugin is an OAuth transport:
+ * it owns the AUTH ENVELOPE and nothing else.
+ *
+ *  - `authorization` — the selected account's bearer. Without it there is no
+ *    request; account rotation is the plugin's entire reason to exist.
+ *  - `anthropic-beta` — ADDITIVE, never substitutive. The host's value is
+ *    preserved verbatim and `oauth-2025-04-20` is appended when missing. That
+ *    beta is a CONTRACT of the OAuth token, not a fingerprint: the API rejects
+ *    an OAuth bearer without it (docs/claude-code-reverse-engineering.md §14.2
+ *    item 3 and §14.3, both listing it as MUST for OAuth). Forging the rest of
+ *    the beta list, or replacing the host's, would be mimicry — and is gone.
+ *  - `x-api-key`, `x-session-affinity` — REMOVED. The first is a competing
+ *    credential that would travel next to our bearer; the second is an opencode
+ *    SDK routing hint that leaks session identity upstream. Both are envelope
+ *    hygiene, not disguise.
+ *
+ * Everything else the host sent — `user-agent` above all — goes out untouched.
+ */
+
+import { stripStainlessHelperMarkers } from "./mimicry/headers.mjs";
+
+/** The beta the Anthropic API requires alongside an OAuth bearer. */
+export const OAUTH_BETA_FLAG = "oauth-2025-04-20";
+
+/**
+ * Credentials and routing hints that must not travel with our bearer.
+ * @see the module comment
+ */
+const STRIPPED_HOST_HEADERS = ["x-api-key", "x-session-affinity"];
+
+/**
+ * Copy the host's headers, from either carrier, into one mutable set.
+ *
+ * @param {Request | URL | string | undefined} input
+ * @param {RequestInit} requestInit
+ * @returns {Headers}
+ */
+function collectHostHeaders(input, requestInit) {
+  const headers = new Headers();
+
+  if (input instanceof Request) {
+    input.headers.forEach((value, name) => headers.set(name, value));
+  }
+
+  const initHeaders = requestInit?.headers;
+  if (initHeaders instanceof Headers) {
+    initHeaders.forEach((value, name) => headers.set(name, value));
+  } else if (Array.isArray(initHeaders)) {
+    for (const [name, value] of initHeaders) {
+      if (typeof value !== "undefined") headers.set(name, String(value));
+    }
+  } else if (initHeaders && typeof initHeaders === "object") {
+    for (const [name, value] of Object.entries(initHeaders)) {
+      if (typeof value !== "undefined") headers.set(name, String(value));
+    }
+  }
+
+  return headers;
+}
+
+/**
+ * Build the outgoing headers for a request that carries NO Claude Code
+ * emulation: the host's own headers plus the auth envelope.
+ *
+ * @param {Request | URL | string | undefined} input The host's fetch input.
+ * @param {RequestInit} requestInit The host's fetch init.
+ * @param {string} accessToken The selected account's access token.
+ * @returns {Headers}
+ */
+export function buildPassthroughHeaders(input, requestInit, accessToken) {
+  const headers = collectHostHeaders(input, requestInit);
+
+  for (const name of STRIPPED_HOST_HEADERS) headers.delete(name);
+
+  // ANTHROPIC_AUTH_TOKEN is the documented manual-bearer escape hatch and
+  // belongs to the same envelope: it selects WHICH token authenticates, not how
+  // the request looks.
+  const authTokenOverride = process.env.ANTHROPIC_AUTH_TOKEN?.trim();
+  headers.set("authorization", `Bearer ${authTokenOverride || accessToken}`);
+
+  const hostBetas = (headers.get("anthropic-beta") || "")
+    .split(",")
+    .map((beta) => beta.trim())
+    .filter(Boolean);
+  if (!hostBetas.includes(OAUTH_BETA_FLAG)) hostBetas.push(OAUTH_BETA_FLAG);
+  headers.set("anthropic-beta", hostBetas.join(","));
+
+  return headers;
+}
+
+/**
+ * Remove the body fields the Anthropic API does not accept, and nothing else.
+ *
+ * THE ONLY BODY EDITS LEFT WITH EMULATION OFF. Every structural normalization
+ * `transformRequestBody` performs (output cap, thinking, effort ->
+ * output_config, system sanitize/compact, metadata, cache breakpoints) is
+ * skipped on this path — the host's body goes out as the host wrote it. These
+ * two strips are the exception, on the same grounds as the auth envelope: they
+ * are what keeps the request VALID, not what makes it look like Claude Code.
+ * Both were already applied unconditionally with emulation off, so keeping them
+ * preserves a working request rather than adding policy.
+ *
+ *  - `betas` — never a first-party field. It existed for Bedrock, which cannot
+ *    forward custom HTTP headers; the first-party API answers "Extra inputs are
+ *    not permitted".
+ *  - the stainless-helper markers — a HOST-side signal (opencode tags a tool or
+ *    message so the plugin can derive `x-stainless-helper`). The plugin never
+ *    injects them and, with emulation off, never derives the header either; the
+ *    API has never known the keys and rejects them inside a tool definition.
+ *    The marker list lives in lib/mimicry/headers.mjs and is imported rather
+ *    than copied: the boundary rule this module enforces is that no mimicry
+ *    function COMPOSES a fingerprint here, and removing a field the API rejects
+ *    is the exact inverse of that.
+ *
+ * When neither is present the ORIGINAL string is returned, byte for byte: a
+ * re-serialization would reorder nothing today but would make the passthrough
+ * claim untrue tomorrow.
+ *
+ * @param {unknown} body
+ * @returns {unknown} The body, with the non-API fields removed if present.
+ */
+export function stripNonApiBodyFields(body) {
+  if (typeof body !== "string" || body.length === 0) return body;
+
+  let parsed;
+  try {
+    parsed = JSON.parse(body);
+  } catch {
+    // Not JSON — there is no field to strip, and rewriting is not our business.
+    return body;
+  }
+
+  if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) return body;
+
+  let changed = false;
+  if (Object.hasOwn(parsed, "betas")) {
+    delete parsed.betas;
+    changed = true;
+  }
+  if (stripStainlessHelperMarkers(parsed.tools, parsed.messages) > 0) changed = true;
+
+  return changed ? JSON.stringify(parsed) : body;
+}