opencode-anthropic-fix 1.0.0 → 2.1.0

package/lib/mimicry/system-prompt.mjs

@@ -1,5 +1,6 @@
 import { isTruthyEnv } from "../env.mjs";
 import { isOpus46Model, isOpus47Model, isOpus48Model } from "./wire-compat.mjs";
+import { truncateGraphemes } from "../unicode-text.mjs";
 
 /**
  * The canonical Claude Code identity text.
@@ -146,16 +147,25 @@ export function tailSystemBlock(text, maxChars, turnThreshold) {
 }
 
 export function compactToolDescription(text) {
-  return text
-    .replace(/<example[\s\S]*?<\/example>/gi, "")
-    .replace(/\|[\s|:-]+\|/g, "")
-    .replace(/^\|.*\|$/gm, "")
-    .replace(/^(?:\s*[-*]\s+.{200,})$/gm, (m) => m.slice(0, 200) + "...")
-    .replace(/^(#{1,3}\s+)/gm, "")
-    .replace(/\*\*([^*]+)\*\*/g, "$1")
-    .replace(/`([^`]+)`/g, "$1")
-    .replace(/\n{3,}/g, "\n\n")
-    .trim();
+  return (
+    text
+      .replace(/<example[\s\S]*?<\/example>/gi, "")
+      .replace(/\|[\s|:-]+\|/g, "")
+      .replace(/^\|.*\|$/gm, "")
+      // Budget is 200 UTF-16 units on the matched line itself; the "..." suffix
+      // is NOT counted against that budget (legacy contract: it is appended
+      // unconditionally after the cut). truncateGraphemes only ever cuts on a
+      // grapheme boundary, so a surrogate pair or combining sequence sitting
+      // across unit 200 is excluded whole rather than split — for ASCII text
+      // (single-unit graphemes) this is byte-for-byte identical to the old
+      // `m.slice(0, 200)`.
+      .replace(/^(?:\s*[-*]\s+.{200,})$/gm, (m) => truncateGraphemes(m, 200) + "...")
+      .replace(/^(#{1,3}\s+)/gm, "")
+      .replace(/\*\*([^*]+)\*\*/g, "$1")
+      .replace(/`([^`]+)`/g, "$1")
+      .replace(/\n{3,}/g, "\n\n")
+      .trim()
+  );
 }
 
 export function compactSystemText(text, mode) {

package/lib/mimicry/wire-compat.mjs

@@ -5,10 +5,10 @@
  */
 
 import {
-  BETA_REGISTRY_2_1_233,
+  BETA_REGISTRY_2_1_280,
   buildClaudeCodeRequest,
   buildClaudeCodeCountTokensRequest,
-  CLAUDE_CODE_2_1_233_PROFILE,
+  CLAUDE_CODE_2_1_280_PROFILE,
   hasOneMillionContext,
   isAdaptiveThinkingModel,
   isClaude3Model,
@@ -22,8 +22,13 @@ import {
   supportsStructuredOutputs,
   supportsWebSearch,
 } from "@tormentalabs/claude-code-wire-compat";
+import { existsSync, readFileSync } from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
 import { stripStainlessHelperMarkers } from "./headers.mjs";
 
+const WIRE_COMPAT_PACKAGE_NAME = "@tormentalabs/claude-code-wire-compat";
+
 /**
  * Model-family predicates, re-exported so the rest of the tree classifies models
  * through the SAME catalogue the request builder classifies them with.
@@ -76,11 +81,11 @@ export {
  * than on the wire.
  *
  * Shape: `{ KEY: { featureKey, header } }`, deep-frozen by the package. It is
- * pinned to 2.1.233 rather than derived from `WIRE_PROFILE` because the package
+ * pinned to 2.1.280 rather than derived from `WIRE_PROFILE` because the package
  * exports no profile->registry accessor; if the emulated baseline moves, this
  * binding and `WIRE_PROFILE` move together.
  */
-export { BETA_REGISTRY_2_1_233 };
+export { BETA_REGISTRY_2_1_280 };
 
 /**
  * 1M-context eligibility under the profile the plugin actually emulates.
@@ -89,7 +94,7 @@ export { BETA_REGISTRY_2_1_233 };
  * PROFILE-DEPENDENT: its second parameter selects the model catalogue, and it
  * defaults to the package's own baseline (2.1.195), not to ours. The two
  * disagree in practice — `claude-mythos-5` is ineligible under 2.1.195 and
- * eligible under 2.1.233 — so calling it bare would gate the plugin's context
+ * eligible under 2.1.280 — so calling it bare would gate the plugin's context
  * decisions on a profile the plugin does not emulate anywhere else.
  *
  * This wrapper binds `WIRE_PROFILE`, so eligibility follows the emulated
@@ -113,14 +118,118 @@ export function isEligibleFor1MContextWire(model) {
  * `mimicryBaseline` reported by `lib/diagnose.mjs` — reads it from here instead
  * of re-declaring a hand-maintained copy.
  *
- * NOTE: this is a BASELINE, not the profile the request path uses. The
- * composition path deliberately passes no explicit `profile` so it inherits the
- * package's `DEFAULT_PROFILE` (see `lib/mimicry/adapter-input.mjs`); naming a
- * profile here only pins what the plugin reports about itself.
+ * THIS IS ALSO THE PROFILE THE REQUEST PATH ACTUALLY USES, not merely a
+ * reporting baseline. `buildWireCompatibleRequest` and
+ * `buildWireCompatibleCountTokensRequest` both pass this constant as the
+ * explicit `profile` argument to `buildClaudeCodeRequest` /
+ * `buildClaudeCodeCountTokensRequest` (see the package's own 0.6.0 CHANGELOG:
+ * "the pin has to be passed on every call to each of the three entry points
+ * that read the default seam -- pinning the builders alone is not enough").
+ *
+ * WHY AN EXPLICIT PASS, RATHER THAN LETTING THE CALL INHERIT THE PACKAGE'S
+ * `DEFAULT_PROFILE`. The dependency is pinned to the `latest` dist-tag
+ * (`docs/shared-package-provenance.md`) precisely so package releases --
+ * fixes, new opt-in fields -- reach the plugin without a code change. Before
+ * this constant was threaded through, an unnamed `profile` argument meant the
+ * EMULATED CLIENT VERSION floated on that same tag: 0.6.0 moved
+ * `DEFAULT_PROFILE` to 2.1.280 in a minor release and broke 48 plugin tests
+ * that were still asserting 2.1.233 bytes. Passing `WIRE_PROFILE` explicitly on
+ * every entry point decouples the two axes: `latest` keeps bringing library
+ * fixes, and the emulated profile now moves only when this binding is
+ * deliberately repointed at a different exported profile singleton -- a
+ * one-line change reviewed like any other wire change, not a side effect of
+ * `npm update`.
  *
  * @type {import('@tormentalabs/claude-code-wire-compat').ClaudeCodeProtocolProfile}
  */
-export const WIRE_PROFILE = CLAUDE_CODE_2_1_233_PROFILE;
+export const WIRE_PROFILE = CLAUDE_CODE_2_1_280_PROFILE;
+
+/**
+ * Version of `@tormentalabs/claude-code-wire-compat` baked in at BUILD time by
+ * `scripts/build.mjs`'s esbuild `define`, read from the package that was
+ * actually installed in `node_modules` when the bundle was produced.
+ *
+ * WHY THIS EXISTS. `getWireCompatPackageVersion` below resolves the version at
+ * RUNTIME through `import.meta.resolve`, which requires the package to still
+ * be a separate, independently resolvable module -- true for an unbundled
+ * import (tests, `node cli.mjs`, a host importing `index.mjs` directly) but
+ * false for the bundles `scripts/build.mjs` produces: esbuild INLINES the
+ * package's source into the single output file, so there is no
+ * `node_modules/@tormentalabs/claude-code-wire-compat` for the bundle to
+ * resolve at its own runtime, and the resolution silently degrades to
+ * "unknown" -- defeating the diagnostic bundle's whole point of reporting what
+ * the running process actually built against.
+ *
+ * `__WIRE_COMPAT_PACKAGE_VERSION__` is a bare, undeclared global identifier,
+ * not an import and not `process.env`, because esbuild's `define` performs a
+ * textual substitution of exactly that shape at bundle time. `typeof` never
+ * throws on an undeclared identifier, so referencing it this way is exactly as
+ * safe unbundled as it is bundled: unbundled, esbuild never touched this file,
+ * the identifier stays undeclared, `typeof` reads `"undefined"`, and this
+ * constant is `undefined` -- `getWireCompatPackageVersion` then falls through
+ * to the runtime resolution exactly as it did before this constant existed.
+ *
+ * @type {string | undefined}
+ */
+/* global __WIRE_COMPAT_PACKAGE_VERSION__:readonly */
+const BUNDLED_WIRE_COMPAT_PACKAGE_VERSION =
+  typeof __WIRE_COMPAT_PACKAGE_VERSION__ === "string" ? __WIRE_COMPAT_PACKAGE_VERSION__ : undefined;
+
+/**
+ * The version of @tormentalabs/claude-code-wire-compat this process actually
+ * runs against: the build-time injected version when bundled (see
+ * `BUNDLED_WIRE_COMPAT_PACKAGE_VERSION` above), otherwise the version
+ * resolved fresh from `node_modules` on every call rather than cached at
+ * module load.
+ *
+ * WHY THE RUNTIME FALLBACK EXISTS. `package.json` pins the dependency to the
+ * `latest` dist-tag (see docs/shared-package-provenance.md), so the version an
+ * UNBUNDLED run actually runs against is whatever `package-lock.json` resolved
+ * at install time -- it is not a literal anywhere in this source tree. A
+ * diagnostic bundle that wants to say what wire the running process is
+ * actually built against (as opposed to `WIRE_PROFILE.cliVersion`, the
+ * BASELINE this file pins) has to read it off disk.
+ *
+ * Deliberately resolves through `node_modules`, not `package-lock.json`: the
+ * lock says what a future `npm ci` WOULD install, `node_modules` says what
+ * THIS process actually loaded, and the two can disagree after an `npm
+ * install` that has not been re-run (see `scripts/check-wire-compat-drift.mjs`,
+ * which checks exactly that disagreement).
+ *
+ * Resolution failure degrades to "unknown" rather than throwing -- a
+ * diagnostic bundle must never fail to build over a missing package.json.
+ *
+ * Resolves via `import.meta.resolve`, not `createRequire(...).resolve`: the
+ * package is ESM-only (its `exports` map declares an `import` condition and
+ * no `require` one), so the CJS resolver fails it with "No 'exports' main
+ * defined" even though the package is genuinely installed.
+ *
+ * @returns {string}
+ */
+export function getWireCompatPackageVersion() {
+  if (BUNDLED_WIRE_COMPAT_PACKAGE_VERSION) return BUNDLED_WIRE_COMPAT_PACKAGE_VERSION;
+  try {
+    let directory = path.dirname(fileURLToPath(import.meta.resolve(WIRE_COMPAT_PACKAGE_NAME)));
+    // Walk up from the package's resolved entry file (e.g. .../dist/index.js)
+    // to the package.json alongside its root -- the entry file is not
+    // guaranteed to be a direct sibling of it.
+    for (let depth = 0; depth < 6; depth += 1) {
+      const candidate = path.join(directory, "package.json");
+      if (existsSync(candidate)) {
+        const manifest = JSON.parse(readFileSync(candidate, "utf8"));
+        if (manifest.name === WIRE_COMPAT_PACKAGE_NAME && typeof manifest.version === "string") {
+          return manifest.version;
+        }
+      }
+      const parent = path.dirname(directory);
+      if (parent === directory) break;
+      directory = parent;
+    }
+  } catch {
+    // Fall through to "unknown".
+  }
+  return "unknown";
+}
 
 const PROFILE_OVERRIDE_ENV = "OPENCODE_ANTHROPIC_PROFILE_OVERRIDE";
 
@@ -408,7 +517,11 @@ export async function buildWireCompatibleRequest(body, transport) {
   stripStainlessHelperMarkers(parsed?.tools, parsed?.messages);
   let built;
   try {
-    built = await buildClaudeCodeRequest(toClaudeCodeRequestInput(parsed, transport));
+    // `WIRE_PROFILE` is passed EXPLICITLY rather than omitted -- see its own
+    // doc comment above for why an omitted argument here would let a future
+    // package release move the emulated client profile out from under the
+    // `latest` dist-tag.
+    built = await buildClaudeCodeRequest(toClaudeCodeRequestInput(parsed, transport), WIRE_PROFILE);
   } catch (error) {
     throw foldSafeDetailsIntoMessage(error);
   }
@@ -501,9 +614,10 @@ export function toClaudeCodeCountTokensInput(body, transport) {
 
 /**
  * Build a Claude Code `/v1/messages/count_tokens` request from the JSON body
- * received from the host. Mirrors `buildWireCompatibleRequest`, including the
- * deliberate absence of an explicit `profile` argument so the count turn
- * inherits the package's `DEFAULT_PROFILE` exactly like the main turn does.
+ * received from the host. Mirrors `buildWireCompatibleRequest`, including
+ * passing `WIRE_PROFILE` as the explicit `profile` argument so the count turn
+ * is pinned to the same emulated client profile as the main turn, rather than
+ * inheriting whatever the installed package declares as its `DEFAULT_PROFILE`.
  *
  * @param {string | undefined} body
  * @param {Parameters<typeof toClaudeCodeCountTokensInput>[1]} transport
@@ -519,7 +633,10 @@ export async function buildWireCompatibleCountTokensRequest(body, transport) {
   stripStainlessHelperMarkers(parsed?.tools, parsed?.messages);
   let built;
   try {
-    built = await buildClaudeCodeCountTokensRequest(toClaudeCodeCountTokensInput(parsed, transport));
+    // See `buildWireCompatibleRequest`'s equivalent comment: explicit on
+    // purpose, so the count-tokens surface cannot silently move to a different
+    // profile than the main turn on a package bump.
+    built = await buildClaudeCodeCountTokensRequest(toClaudeCodeCountTokensInput(parsed, transport), WIRE_PROFILE);
   } catch (error) {
     throw foldSafeDetailsIntoMessage(error);
   }

package/lib/oauth-constants.mjs

@@ -0,0 +1,109 @@
+/**
+ * Every value here is transcribed from docs/oauth-2.1.280-contract.md, the local
+ * contract for the genuine Claude Code 2.1.280 OAuth surface, recorded from
+ * section 13.8 of the bundle analysis. No value may be guessed or interpolated
+ * from another release.
+ *
+ * Scope: this module holds only the constants this plugin actually emits. The
+ * contract also records the OIDC federation surface (contract §2.4, §3), which
+ * this plugin deliberately does not implement — see divergence D12. Its
+ * constants are intentionally absent here rather than exported unused, so that
+ * every export in this file has a live consumer and a conformance assertion.
+ */
+
+/**
+ * Genuine OAuth client identifier.
+ * @see docs/oauth-2.1.280-contract.md §1.1
+ */
+export const OAUTH_CLIENT_ID = "9d1c250a-e61b-44d9-88ed-5944d1962f5e";
+
+/**
+ * Console authorization endpoint.
+ * @see docs/oauth-2.1.280-contract.md §1
+ */
+export const OAUTH_CONSOLE_AUTHORIZE_URL = "https://platform.claude.com/oauth/authorize";
+
+/**
+ * Genuine consumer authorize page on claude.com/cai/, not claude.ai.
+ * This URL and OAUTH_CLAUDE_AI_ORIGIN are different and must never be collapsed.
+ * @see docs/oauth-2.1.280-contract.md §1
+ */
+export const OAUTH_CLAUDE_AI_AUTHORIZE_URL = "https://claude.com/cai/oauth/authorize";
+
+/**
+ * Consumer origin, distinct from the consumer authorize page on claude.com/cai/.
+ * This origin and OAUTH_CLAUDE_AI_AUTHORIZE_URL must never be collapsed.
+ * @see docs/oauth-2.1.280-contract.md §1
+ */
+export const OAUTH_CLAUDE_AI_ORIGIN = "https://claude.ai";
+
+/**
+ * Attested absolute token URL. The contract marks the host binding
+ * [unattested-bind]: which request uses this URL is not attested. Do not fix the host.
+ * @see docs/oauth-2.1.280-contract.md §1, §2.6
+ */
+export const OAUTH_TOKEN_URL = "https://platform.claude.com/v1/oauth/token";
+
+/**
+ * OAuth code callback URI.
+ * @see docs/oauth-2.1.280-contract.md §1.1
+ */
+export const OAUTH_REDIRECT_URI = "https://platform.claude.com/oauth/code/callback";
+
+/**
+ * OAuth API key creation endpoint.
+ * @see docs/oauth-2.1.280-contract.md §1
+ */
+export const OAUTH_API_KEY_URL = "https://api.anthropic.com/api/oauth/claude_cli/create_api_key";
+
+/**
+ * SDK version embedded in the genuine release.
+ * @see docs/oauth-2.1.280-contract.md §3
+ */
+export const OAUTH_SDK_VERSION = "0.112.1";
+
+/**
+ * User OAuth provider SDK user agent.
+ * @see docs/oauth-2.1.280-contract.md §3
+ */
+export const OAUTH_SDK_USER_AGENT = `anthropic-sdk-typescript/${OAUTH_SDK_VERSION} userOAuthProvider`;
+
+/**
+ * OAuth beta identifier. Sent on every token request.
+ * @see docs/oauth-2.1.280-contract.md §3
+ */
+export const OAUTH_BETA = "oauth-2025-04-20";
+
+/**
+ * OAuth expiry skew in seconds.
+ * @see docs/oauth-2.1.280-contract.md §3
+ */
+export const OAUTH_EXPIRY_SKEW_SECONDS = 30;
+
+/**
+ * Approved custom OAuth endpoints, frozen to preserve the attested allowlist.
+ * @see docs/oauth-2.1.280-contract.md §5.1
+ */
+export const OAUTH_CUSTOM_URL_ALLOWLIST = Object.freeze([
+  "https://beacon.claude-ai.staging.ant.dev",
+  "https://claude.fedstart.com",
+  "https://claude-staging.fedstart.com",
+]);
+
+/**
+ * Default local apps base URL.
+ * @see docs/oauth-2.1.280-contract.md §5
+ */
+export const OAUTH_LOCAL_APPS_BASE_DEFAULT = "http://localhost:4000";
+
+/**
+ * Default local console base URL.
+ * @see docs/oauth-2.1.280-contract.md §5
+ */
+export const OAUTH_LOCAL_CONSOLE_BASE_DEFAULT = "http://localhost:3000";
+
+/**
+ * Must match the genuine rejection string byte-for-byte, including its trailing full stop.
+ * @see docs/oauth-2.1.280-contract.md §5.1
+ */
+export const OAUTH_CUSTOM_URL_REJECTION_MESSAGE = "CLAUDE_CODE_CUSTOM_OAUTH_URL is not an approved endpoint.";

package/lib/oauth-env.mjs

@@ -0,0 +1,187 @@
+/**
+ * OAuth environment surface from docs/oauth-2.1.280-contract.md §5: the
+ * allowlist and two local bases (evidence bytes 4657393 and 4656690).
+ * Comparison semantics are [unattested]; exact equality is the narrowest
+ * defensible reading. The rejection message is byte-exact because it is
+ * attested verbatim.
+ */
+import {
+  OAUTH_CLIENT_ID,
+  OAUTH_CUSTOM_URL_ALLOWLIST,
+  OAUTH_CUSTOM_URL_REJECTION_MESSAGE,
+  OAUTH_LOCAL_APPS_BASE_DEFAULT,
+  OAUTH_LOCAL_CONSOLE_BASE_DEFAULT,
+} from "./oauth-constants.mjs";
+import { CLAUDE_AI_BASE_SCOPES, missingBaseScopes } from "./oauth-scopes.mjs";
+
+/**
+ * Read one environment entry as a trimmed string.
+ *
+ * A non-string value is treated as absent rather than thrown on: `env` is an
+ * arbitrary caller-supplied object in tests and a `ProcessEnv` in production,
+ * and the two disagree about what a "set" variable can hold.
+ *
+ * @param {Record<string, string | undefined> | undefined} env
+ * @param {string} key
+ * @returns {string} the trimmed value, or `""` when absent or not a string
+ */
+function readEnv(env, key) {
+  const raw = env?.[key];
+  return typeof raw === "string" ? raw.trim() : "";
+}
+
+/**
+ * Reject anything outside the exact, unnormalised allowlist.
+ * @param {string} url
+ * @returns {string}
+ */
+export function assertApprovedOAuthUrl(url) {
+  if (!OAUTH_CUSTOM_URL_ALLOWLIST.includes(url)) {
+    throw new Error(OAUTH_CUSTOM_URL_REJECTION_MESSAGE);
+  }
+  return url;
+}
+
+/**
+ * An absent or blank variable is not configured; otherwise validate the raw value.
+ * @param {Record<string, string | undefined>} env
+ * @returns {string | undefined}
+ */
+export function resolveCustomOAuthUrl(env) {
+  if (readEnv(env, "CLAUDE_CODE_CUSTOM_OAUTH_URL") === "") return undefined;
+  // The RAW value is compared, never the trimmed one: normalising here would
+  // widen the allowlist beyond what the genuine client accepts.
+  return assertApprovedOAuthUrl(env.CLAUDE_CODE_CUSTOM_OAUTH_URL);
+}
+
+/**
+ * This activation predicate is [unattested]: §13.8 records the two variables
+ * and their defaults but not what activates them. Setting either variable to
+ * a non-blank value is itself the opt-in, so an entirely unset environment
+ * can never silently redirect a production login to localhost. The documented
+ * defaults are only reachable once the mode is already active, which is why
+ * they cannot leak on their own.
+ * @param {Record<string, string | undefined>} env
+ * @returns {boolean}
+ */
+export function isLocalOAuthDevMode(env) {
+  return Boolean(readEnv(env, "CLAUDE_LOCAL_OAUTH_APPS_BASE") || readEnv(env, "CLAUDE_LOCAL_OAUTH_CONSOLE_BASE"));
+}
+
+/** Origins a CLAUDE_LOCAL_OAUTH_*_BASE may name. @see docs/oauth-2.1.280-contract.md §5 */
+const LOOPBACK_ORIGIN = /^http:\/\/(?:localhost|127\.0\.0\.1|\[::1\])(?::\d{1,5})?$/;
+
+/**
+ * Refuse a local-dev base that is not a loopback origin.
+ *
+ * §13.8 records the two variables and their localhost defaults but nothing about
+ * validation, so this guard is [unattested]. It exists because the alternative is
+ * strictly worse: an unvalidated base lets any environment that can set one
+ * variable redirect a production OAuth flow to an arbitrary host, which is the
+ * exact class of defect the CLAUDE_CODE_CUSTOM_OAUTH_URL allowlist exists to
+ * prevent. Refusing a non-loopback value is the narrowest reading of "LOCAL".
+ *
+ * @param {string} base
+ * @param {string} varName
+ * @returns {string}
+ */
+function assertLoopbackBase(base, varName) {
+  if (!LOOPBACK_ORIGIN.test(base)) {
+    throw new Error(
+      `${varName} must be a loopback origin such as http://localhost:4000, http://127.0.0.1:4000 or http://[::1]:4000. Received: ${base}`,
+    );
+  }
+  return base;
+}
+
+/**
+ * @param {Record<string, string | undefined>} env
+ * @returns {string | undefined}
+ */
+export function resolveAppsBase(env) {
+  if (!isLocalOAuthDevMode(env)) return undefined;
+  // Console-only opt-in deliberately selects the documented apps default, not production.
+  return assertLoopbackBase(
+    readEnv(env, "CLAUDE_LOCAL_OAUTH_APPS_BASE") || OAUTH_LOCAL_APPS_BASE_DEFAULT,
+    "CLAUDE_LOCAL_OAUTH_APPS_BASE",
+  );
+}
+
+/**
+ * @param {Record<string, string | undefined>} env
+ * @returns {string | undefined}
+ */
+export function resolveConsoleBase(env) {
+  if (!isLocalOAuthDevMode(env)) return undefined;
+  // Apps-only opt-in likewise selects the documented console default, not production.
+  return assertLoopbackBase(
+    readEnv(env, "CLAUDE_LOCAL_OAUTH_CONSOLE_BASE") || OAUTH_LOCAL_CONSOLE_BASE_DEFAULT,
+    "CLAUDE_LOCAL_OAUTH_CONSOLE_BASE",
+  );
+}
+
+/** Environment variable carrying a pre-issued refresh token. @see docs/oauth-2.1.280-contract.md §5.2 */
+export const HEADLESS_REFRESH_TOKEN_VAR = "CLAUDE_CODE_OAUTH_REFRESH_TOKEN";
+
+/** Environment variable declaring the scopes that token was granted. @see docs/oauth-2.1.280-contract.md §5.2 */
+export const HEADLESS_SCOPES_VAR = "CLAUDE_CODE_OAUTH_SCOPES";
+
+/** Environment variable overriding the OAuth client id. @see docs/oauth-2.1.280-contract.md §5.2 */
+export const HEADLESS_CLIENT_ID_VAR = "CLAUDE_CODE_OAUTH_CLIENT_ID";
+
+/** One-shot latch: an incomplete headless scope declaration warns once per process, not once per load. */
+let headlessScopeWarningEmitted = false;
+
+/** Reset the one-shot scope warning. Exported for tests only. */
+export function resetHeadlessScopeWarning() {
+  headlessScopeWarningEmitted = false;
+}
+
+/**
+ * Resolve a headless (non-interactive) login declared entirely by environment.
+ *
+ * ATTESTATION. §13.8 records the three variable NAMES (contract §5.2). It does
+ * NOT record the parsing rules, the required-ness of the scope list, or any
+ * error text. Those are this plugin's choices, recorded as divergence D10.
+ *
+ * WHY THE SCOPE LIST IS REQUIRED. The operator, not this plugin, knows which
+ * scopes the injected token actually carries. Defaulting it would be an
+ * invention, and a token silently missing `user:inference` would fail at the
+ * first request instead of at boot.
+ *
+ * WHERE THE SCOPES ARE USED. Verbatim, and only as a boot-time declaration
+ * check. They are never re-composed through `composeScopes()` and they MUST
+ * NEVER reach a refresh body: the attested refresh body (byte 4429828) has
+ * exactly three keys and no `scope` — contract §2.3 and divergence D5.
+ *
+ * @param {Record<string, string | undefined> | undefined} env
+ * @returns {{refreshToken: string, scopes: string[], clientId: string} | undefined}
+ *   `undefined` when no refresh token is declared.
+ * @throws {Error} when a refresh token is declared without a usable scope list.
+ */
+export function resolveHeadlessLogin(env) {
+  const refreshToken = readEnv(env, HEADLESS_REFRESH_TOKEN_VAR);
+  if (!refreshToken) return undefined;
+
+  const scopes = readEnv(env, HEADLESS_SCOPES_VAR).split(/\s+/).filter(Boolean);
+  if (scopes.length === 0) {
+    throw new Error(
+      `${HEADLESS_REFRESH_TOKEN_VAR} is set but ${HEADLESS_SCOPES_VAR} is missing. Set ${HEADLESS_SCOPES_VAR} to the space-separated scope list that token was granted, for example: ${CLAUDE_AI_BASE_SCOPES.join(" ")}`,
+    );
+  }
+
+  // An incomplete declaration warns rather than throwing. The scope list is a
+  // declaration about a token this plugin did not issue: it may legitimately be
+  // a console-issued token with a different set, and refusing to start would
+  // take every unrelated stored account down with it.
+  const missing = missingBaseScopes(scopes);
+  if (missing.length > 0 && !headlessScopeWarningEmitted) {
+    headlessScopeWarningEmitted = true;
+    console.warn(
+      `[anthropic-auth] ${HEADLESS_SCOPES_VAR} does not declare every scope this plugin normally requires. Missing: ${missing.join(", ")}. Requests needing those scopes will fail at the server.`,
+    );
+  }
+
+  const trimmedClientId = readEnv(env, HEADLESS_CLIENT_ID_VAR);
+  return { refreshToken, scopes, clientId: trimmedClientId || OAUTH_CLIENT_ID };
+}

package/lib/oauth-scopes.mjs

@@ -0,0 +1,119 @@
+/**
+ * OAuth scope sets and conditional extensions transcribed from
+ * docs/oauth-2.1.280-contract.md §4 (evidence: byte 4654950 of the 2.1.280 analysis).
+ *
+ * WHAT IS ATTESTED: the two base arrays and their element order, the *names* of
+ * the three conditional extensions, and the condition under which each is added.
+ *
+ * WHAT IS NOT ATTESTED, and is this plugin's own choice:
+ *   - the position of `user:plugins` relative to the project scopes when both
+ *     gates fire;
+ *   - the order of `user:projects:read` against `user:projects:write`;
+ *   - the space-join into the `scope` query parameter.
+ * All three are wire-visible. They are recorded as divergence D13 in §7 of the
+ * contract doc so that a future maintainer does not mistake them for evidence.
+ *
+ * Base-set order is offset-attested and must never be sorted.
+ * @module oauth-scopes
+ */
+
+/** Offset-attested console base scopes, in wire order (byte 4654950). */
+export const CONSOLE_BASE_SCOPES = Object.freeze(["org:create_api_key", "user:profile"]);
+
+/** Offset-attested claude.ai base scopes, in wire order (byte 4654950). */
+export const CLAUDE_AI_BASE_SCOPES = Object.freeze([
+  "user:profile",
+  "user:inference",
+  "user:sessions:claude_code",
+  "user:mcp_servers",
+  "user:file_upload",
+]);
+
+/**
+ * Conditional plugin scope. §13.8 attests the name and the gate; it does not
+ * attest the append position. Appending last is this plugin's choice (D13).
+ */
+export const PLUGINS_SCOPE = "user:plugins";
+
+/**
+ * Conditional project scopes. §13.8 attests both names and that they are added
+ * only when requested and allowed; the read-before-write order is this plugin's
+ * choice (D13), made so that the emitted string is deterministic.
+ */
+export const PROJECT_SCOPES = Object.freeze(["user:projects:read", "user:projects:write"]);
+
+/**
+ * Return a fresh claude.ai scope list. The genuine client's default state of
+ * PLUGINS_SCOPE_REGISTERED is unattested, so this plugin defaults it off;
+ * this choice is divergence D9 in the contract doc.
+ * @param {{ pluginsRegistered?: unknown }} [options]
+ * @returns {string[]}
+ */
+export function claudeAiScopes({ pluginsRegistered } = {}) {
+  return pluginsRegistered === true ? [...CLAUDE_AI_BASE_SCOPES, PLUGINS_SCOPE] : [...CLAUDE_AI_BASE_SCOPES];
+}
+
+/**
+ * Select supported project scopes in the canonical order, ignoring unknown input.
+ *
+ * Iteration is over PROJECT_SCOPES, never over `requested`, so caller order and
+ * caller duplicates cannot reach the wire.
+ * @param {unknown} [requested]
+ * @returns {string[]}
+ */
+export function requestedProjectScopes(requested) {
+  if (!Array.isArray(requested)) return [];
+  return PROJECT_SCOPES.filter((scope) => requested.includes(scope));
+}
+
+/**
+ * Single composition seam. The default (no options) output, when serialized,
+ * must be byte-identical to the pre-Wave-2 five-scope string: the no-regression
+ * guarantee.
+ *
+ * An unrecognised `mode` throws rather than falling through to the claude.ai
+ * set: silently emitting consumer scopes for a mode the caller mistyped would
+ * send a wrong scope string to a real authorize endpoint.
+ * @param {{ mode?: string, pluginsRegistered?: unknown, projectScopes?: unknown } | null} [options]
+ * @returns {string[]}
+ */
+export function composeScopes(options) {
+  const { mode, pluginsRegistered, projectScopes } = options ?? {};
+  if (mode !== undefined && mode !== "max" && mode !== "console") {
+    throw new Error(`Unknown OAuth mode "${mode}" (expected "max" or "console")`);
+  }
+  // Project scopes must never leak into a console authorize URL; ignore both extensions.
+  if (mode === "console") return [...CONSOLE_BASE_SCOPES];
+  const scopes = [...claudeAiScopes({ pluginsRegistered }), ...requestedProjectScopes(projectScopes)];
+  // The three scope pools are disjoint today, so this dedupe is a no-op — it is
+  // kept as a structural guarantee that the seam can never emit a repeated
+  // scope if a future extension overlaps. `Set` iterates in insertion order, so
+  // the first occurrence keeps its position. A test pins the disjointness.
+  return [...new Set(scopes)];
+}
+
+/**
+ * The only place the authorize `scope` parameter is serialised: one seam means
+ * the wire format has one owner. Space-join serialisation is [unattested] (§4.1).
+ * @param {readonly string[] | null} [list]
+ * @returns {string}
+ */
+export function serializeScopes(list) {
+  return list == null ? "" : list.join(" ");
+}
+
+/**
+ * Which of the five attested claude.ai base scopes are absent from `scopes`.
+ *
+ * Single seam so the refresh-time check (`hasRequiredScopes`) and the headless
+ * boot-time check cannot drift apart. Returns entries in `CLAUDE_AI_BASE_SCOPES`
+ * order, never caller order, so the resulting message is deterministic.
+ *
+ * @param {string[] | undefined | null} scopes
+ * @returns {string[]}
+ * @see docs/oauth-2.1.280-contract.md §4.1
+ */
+export function missingBaseScopes(scopes) {
+  const granted = new Set(Array.isArray(scopes) ? scopes : []);
+  return CLAUDE_AI_BASE_SCOPES.filter((scope) => !granted.has(scope));
+}