opencode-anthropic-fix 1.0.0 → 2.0.0

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