opencode-anthropic-fix 0.6.0 → 2.0.0

package/lib/mimicry/wire-compat.mjs

@@ -4,9 +4,124 @@
  * NOT promised because the returned HeaderPair array is converted to Headers.
  */
 
-import { buildClaudeCodeRequest, buildClaudeCodeCountTokensRequest } from "@tormentalabs/claude-code-wire-compat";
+import {
+  BETA_REGISTRY_2_1_233,
+  buildClaudeCodeRequest,
+  buildClaudeCodeCountTokensRequest,
+  CLAUDE_CODE_2_1_233_PROFILE,
+  hasOneMillionContext,
+  isAdaptiveThinkingModel,
+  isClaude3Model,
+  isEligibleFor1MContext,
+  isFable5Model,
+  isHaikuModel,
+  isMythos5Model,
+  isOpus46Model,
+  isOpus47Model,
+  isOpus48Model,
+  supportsStructuredOutputs,
+  supportsWebSearch,
+} from "@tormentalabs/claude-code-wire-compat";
 import { stripStainlessHelperMarkers } from "./headers.mjs";
 
+/**
+ * Model-family predicates, re-exported so the rest of the tree classifies models
+ * through the SAME catalogue the request builder classifies them with.
+ *
+ * These used to be hand-written regexes in `lib/mimicry/models.mjs`, maintained
+ * in parallel with the package's model catalogue and therefore free to drift
+ * from it: a request could be composed as an adaptive-thinking model by the
+ * package while the plugin's own gating said otherwise. Sourcing both sides from
+ * one place removes that whole class of divergence. The behavioural differences
+ * this migration introduces are pinned, row by row, in
+ * `test/conformance/model-predicates-parity.test.mjs`.
+ *
+ * `isEligibleFor1MContext` is deliberately NOT re-exported raw — see
+ * `isEligibleFor1MContextWire` below.
+ *
+ * The CAPABILITY predicates (`isHaikuModel`, `supportsStructuredOutputs`,
+ * `supportsWebSearch`) join them for the same reason. `lib/mimicry/headers.mjs`
+ * still declares its own local copies, but those now feed ONLY the frozen legacy
+ * header forge; every adapter-path decision reads the package's, which are
+ * ported from the genuine client's own capability table rather than guessed from
+ * a regex. The one measured behavioural difference —
+ * `supportsStructuredOutputs("claude-haiku-4-5")` is `true` upstream and was
+ * `false` under the plugin's "haiku never supports it" heuristic — is a mimicry
+ * fidelity FIX, and is pinned by the migration harness baseline.
+ */
+export {
+  hasOneMillionContext,
+  isAdaptiveThinkingModel,
+  isClaude3Model,
+  isFable5Model,
+  isHaikuModel,
+  isMythos5Model,
+  isOpus46Model,
+  isOpus47Model,
+  isOpus48Model,
+  supportsStructuredOutputs,
+  supportsWebSearch,
+};
+
+/**
+ * The genuine client's beta registry for the profile the plugin emulates,
+ * re-exported so the host's own beta tables can be RECONCILED against it
+ * without a second import point.
+ *
+ * `lib/betas.mjs` is host policy — what the plugin adds or suppresses on top of
+ * what the package composes — and it names beta headers as literal strings. A
+ * literal is exactly the thing that rots when upstream bumps a beta's date, and
+ * nothing used to notice. `lib/betas.test.mjs` now walks this registry and fails
+ * on a header that has drifted from it, so the rot is caught at test time rather
+ * 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
+ * exports no profile->registry accessor; if the emulated baseline moves, this
+ * binding and `WIRE_PROFILE` move together.
+ */
+export { BETA_REGISTRY_2_1_233 };
+
+/**
+ * 1M-context eligibility under the profile the plugin actually emulates.
+ *
+ * Unlike its siblings, the package's `isEligibleFor1MContext` is
+ * 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
+ * decisions on a profile the plugin does not emulate anywhere else.
+ *
+ * This wrapper binds `WIRE_PROFILE`, so eligibility follows the emulated
+ * profile automatically if that baseline is ever bumped.
+ *
+ * @param {string | undefined} model
+ * @returns {boolean}
+ */
+export function isEligibleFor1MContextWire(model) {
+  return isEligibleFor1MContext(model, WIRE_PROFILE);
+}
+
+/**
+ * The protocol profile the plugin composes against, re-exported so the rest of
+ * the tree can read the baseline CLI version WITHOUT importing the package.
+ *
+ * This module is the single seam through which
+ * `@tormentalabs/claude-code-wire-compat` enters the plugin (pinned by
+ * `test/conformance/package-dependency-policy.test.mjs`), so a consumer that
+ * needs `cliVersion` — the startup value of `claudeCliVersion` in index.mjs, the
+ * `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.
+ *
+ * @type {import('@tormentalabs/claude-code-wire-compat').ClaudeCodeProtocolProfile}
+ */
+export const WIRE_PROFILE = CLAUDE_CODE_2_1_233_PROFILE;
+
 const PROFILE_OVERRIDE_ENV = "OPENCODE_ANTHROPIC_PROFILE_OVERRIDE";
 
 const BODY_FIELD_NAMES = new Set([
@@ -63,18 +178,25 @@ function normalizeSystem(system) {
  * `normalizeModelId` (dist/model-identity.js) tests `includes("claude-opus-4-7")`
  * and never the dotted spelling, because the genuine Claude Code client emits
  * dashed ids. The plugin, by contrast, deliberately TOLERATES dotted ids
- * throughout — `lib/mimicry/models.mjs` matches with the `[._-]` character class
- * — so a host can legitimately hand us `claude-opus-4.7`.
+ * throughout — the package's own family predicates re-exported above accept
+ * `claude-opus-4.7` — so a host can legitimately hand us that spelling.
+ *
+ * WHY IT SURVIVED THE PACKAGE MIGRATION. The consolidation plan predicted this
+ * rewrite could be deleted once the family predicates came from the package,
+ * on the premise that the package normalizes the id for us. Measured against
+ * the installed package, that premise is WRONG, and the distinction is:
  *
- * Passing a dotted id straight through MISCLASSIFIES it. For
- * `claude-opus-4.7` no `includes` branch matches, so the fallback
- * `/claude-opus-4(?!-\d(?!\d))/` matches (the character after `claude-opus-4`
- * is `.`, not `-`) and the model resolves to `claude-opus-4-0`. That silently
- * drops `adaptiveThinking`, `supportsEffort`, `supportsMaxEffort` and
- * `supportsXhighEffort`, and wrongly turns `supportsTemperature` ON.
+ *   - DECISIONS are dotted-tolerant. The package's own predicates classify
+ *     `claude-opus-4.7` correctly (pinned as data in
+ *     `test/conformance/model-predicates-parity.test.mjs`).
+ *   - The BODY is not normalized. The package copies the caller's model
+ *     through VERBATIM apart from stripping `[1m]`-style markers, so feeding
+ *     it `claude-opus-4.7` bare yields `body.model === "claude-opus-4.7"`.
  *
- * The tolerance belongs to the plugin, so it is spent here and the package
- * receives the dashed id it is built for. The rewrite is deliberately narrow:
+ * The real API only accepts the dashed spelling, so dropping this rewrite
+ * would put an id on the wire that Anthropic rejects. The tolerance therefore
+ * belongs to the plugin, is spent here, and the package receives the dashed id
+ * it is built for. The rewrite is deliberately narrow:
  * a dot is only replaced when it FOLLOWS a letter or digit and PRECEDES a
  * digit, i.e. when it is a version separator (`claude-opus-4.7`,
  * `claude-3.5-sonnet`). A dot before a letter is left alone, so vendor

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));
+}