UNPKG

@bitkyc08/opencodex

Version:

Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code

507 lines (484 loc) • 20.9 kB
/** * Meta Muse Code device-authorization login. * * `./meta-muse` imports the credential the vendor's CLI already minted. This module * produces one: Meta's OIDC device grant, then the subscription key mint that turns the * resulting account token into the `LLM|` Model API key our request path sends as a * bearer. * * Protocol source: devlog/_fin/260912_muse_device_oauth/001_reference_measurements.md. * It is second-party, not vendor documentation, so every response is parsed defensively * and every failure names a kind instead of throwing a bare string. * * Two properties are load-bearing and easy to lose in a later edit: * * 1. NO RESPONSE BODY REACHES AN ERROR MESSAGE. These endpoints can echo request * material, the mint response literally contains the API key, and these messages reach * CLI output, the dashboard and issue reports. Status codes only — the same discipline * as `deviceError` in ./chatgpt-device. * 2. THE ACCOUNT TOKEN IS NOT A BEARER FOR THE MODEL API. Measured 2026-09-03: it 401s * with `invalid_api_key` while the sibling key returns 200 * (devlog/_fin/260903_muse_spark_plan_oauth/003 §B). It exists here only to mint and * to read subscription usage. */ import type { OAuthController, OAuthCredentials } from "./types"; import { sanitizeApiKeyValue } from "../providers/api-keys"; import { BOUNDED_BODY_MAX_BYTES, readBoundedResponseBytes } from "../lib/bounded-body"; /** Meta's own Muse Code client. Public in its device-approval URL; not a secret. */ const CLIENT_ID = "1031625952748946"; const DEVICE_AUTHORIZATION_URL = "https://auth.meta.com/oidc/device/authorization/"; const DEVICE_TOKEN_URL = "https://auth.meta.com/oidc/device/token/"; const MUSE_KEY_URL = "https://api.meta.ai/muse-code/key"; const DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code"; const API_VERSION = "1.0.0"; /** Shown when the response omits a verification URI. Observed 2026-09-03 from `muse login`. */ const VERIFICATION_FALLBACK_URL = "https://auth.meta.com/oauth/device/"; const REQUEST_TIMEOUT_MS = 20_000; const DEFAULT_FLOW_TTL_MS = 15 * 60_000; /** A hostile or corrupt `expires_in` must not park a login for hours. */ const MAX_FLOW_TTL_MS = 30 * 60_000; const DEFAULT_POLL_INTERVAL_MS = 5_000; /** Floor: a zero or string interval would otherwise hot-loop an auth endpoint. */ const MIN_POLL_INTERVAL_MS = 1_000; const SLOW_DOWN_INCREMENT_MS = 5_000; const MAX_POLL_INTERVAL_MS = 60_000; export type MuseDeviceErrorKind = | "device-authorization" | "device-token" | "device-denied" | "device-expired" | "cancelled" | "mint-http" | "mint-rate-limited" | "mint-invalid" | "subscription-inactive" | "entitlement-required" | "missing-api-key" | "missing-identity"; export class MuseDeviceLoginError extends Error { readonly kind: MuseDeviceErrorKind; readonly status?: number; /** Where the user resolves an entitlement problem. Vendor-supplied, never a local path. */ readonly actionUrl?: string; readonly retryAfterMs?: number; constructor( kind: MuseDeviceErrorKind, message: string, extra: { status?: number; actionUrl?: string; retryAfterMs?: number; cause?: unknown } = {}, ) { super(message, extra.cause === undefined ? undefined : { cause: extra.cause }); // Set here rather than as a class field, matching src/oauth/nous.ts:160 and :383. this.name = "MuseDeviceLoginError"; this.kind = kind; if (extra.status !== undefined) this.status = extra.status; if (extra.actionUrl !== undefined) this.actionUrl = extra.actionUrl; if (extra.retryAfterMs !== undefined) this.retryAfterMs = extra.retryAfterMs; } } /** Injected so tests never touch the network or a real clock. */ export interface MuseDeviceDeps { fetchImpl?: typeof fetch; sleep?: (ms: number, signal?: AbortSignal) => Promise<void>; now?: () => number; } export interface MuseDeviceAuthorization { deviceCode: string; userCode: string; verificationUri: string; verificationUriComplete?: string; intervalMs: number; expiresAtMs: number; } export interface MuseKeyPayload { apiKey?: string; requirePayment?: boolean; actionUrl?: string; userEmail?: string; userId?: string; isSubsActive?: boolean; subsTierName?: string; /** Raw `subs_usage` object, api_key-free by construction. Parsed by muse-key-quota. */ subsUsage?: Record<string, unknown>; } function text(value: unknown): string | undefined { if (typeof value !== "string") return undefined; const trimmed = value.trim(); return trimmed.length > 0 ? trimmed : undefined; } function record(value: unknown): Record<string, unknown> | undefined { return value && typeof value === "object" && !Array.isArray(value) ? (value as Record<string, unknown>) : undefined; } /** * Upstream may send `interval` as a number or a string. A string reaches `setTimeout` as * 0 and turns the poll into a hot loop, so coerce, floor and cap it. */ function normalizeIntervalMs(raw: unknown): number { const seconds = typeof raw === "number" ? raw : typeof raw === "string" ? Number(raw) : NaN; if (!Number.isFinite(seconds) || seconds <= 0) return DEFAULT_POLL_INTERVAL_MS; return Math.min(MAX_POLL_INTERVAL_MS, Math.max(MIN_POLL_INTERVAL_MS, Math.round(seconds * 1000))); } function normalizeTtlMs(raw: unknown): number { const seconds = typeof raw === "number" ? raw : typeof raw === "string" ? Number(raw) : NaN; if (!Number.isFinite(seconds) || seconds <= 0) return DEFAULT_FLOW_TTL_MS; return Math.min(MAX_FLOW_TTL_MS, Math.round(seconds * 1000)); } /** RFC 7231 `Retry-After`: delta-seconds or an HTTP date. Clamped to the poll ceiling. */ function retryAfterMs(header: string | null, now: number): number | undefined { const raw = text(header ?? undefined); if (!raw) return undefined; const seconds = Number(raw); if (Number.isFinite(seconds) && seconds >= 0) { return Math.min(MAX_POLL_INTERVAL_MS, Math.round(seconds * 1000)); } const at = Date.parse(raw); if (!Number.isFinite(at)) return undefined; return Math.min(MAX_POLL_INTERVAL_MS, Math.max(0, at - now)); } async function defaultSleep(ms: number, signal?: AbortSignal): Promise<void> { if (signal?.aborted) throw cancelled(); await new Promise<void>((resolve, reject) => { const timer = setTimeout(() => { signal?.removeEventListener("abort", onAbort); resolve(); }, ms); const onAbort = (): void => { clearTimeout(timer); reject(cancelled()); }; signal?.addEventListener("abort", onAbort, { once: true }); }); } function cancelled(): MuseDeviceLoginError { return new MuseDeviceLoginError("cancelled", "Muse Code login cancelled"); } function requestSignal(signal: AbortSignal | undefined): AbortSignal { const timeout = AbortSignal.timeout(REQUEST_TIMEOUT_MS); return signal ? AbortSignal.any([signal, timeout]) : timeout; } async function readMuseJson( response: Response, signal: AbortSignal, kind: "device-authorization" | "device-token" | "mint-invalid", ): Promise<Record<string, unknown> | undefined> { const declaredLength = response.headers.get("content-length"); if (declaredLength && /^\d+$/.test(declaredLength) && Number(declaredLength) > BOUNDED_BODY_MAX_BYTES) { void response.body?.cancel().catch(() => undefined); throw new MuseDeviceLoginError( kind, `Muse Code response exceeded the ${BOUNDED_BODY_MAX_BYTES}-byte limit`, { status: response.status }, ); } const { bytes, oversized } = await readBoundedResponseBytes(response, { maxBytes: BOUNDED_BODY_MAX_BYTES, signal, }); if (oversized) { throw new MuseDeviceLoginError( kind, `Muse Code response exceeded the ${BOUNDED_BODY_MAX_BYTES}-byte limit`, { status: response.status }, ); } try { return record(JSON.parse(new TextDecoder("utf-8", { fatal: true }).decode(bytes))); } catch { return undefined; } } /** Step 1: ask Meta for a user code. */ export async function requestMuseDeviceAuthorization( deps: MuseDeviceDeps = {}, signal?: AbortSignal, ): Promise<MuseDeviceAuthorization> { const now = deps.now ?? Date.now; const request = requestSignal(signal); const response = await (deps.fetchImpl ?? fetch)(DEVICE_AUTHORIZATION_URL, { method: "POST", headers: { Accept: "application/json", "Content-Type": "application/x-www-form-urlencoded", "x-api-version": API_VERSION, }, body: new URLSearchParams({ client_id: CLIENT_ID }).toString(), redirect: "error", signal: request, }); if (!response.ok) { // The error body is never parsed, but it still has to be released: an unread // response body keeps the underlying connection occupied. void response.body?.cancel().catch(() => undefined); throw new MuseDeviceLoginError( "device-authorization", `Muse Code device authorization request failed: HTTP ${response.status}`, { status: response.status }, ); } const payload = await readMuseJson(response, request, "device-authorization"); const deviceCode = text(payload?.device_code); const userCode = text(payload?.user_code); if (!deviceCode || !userCode) { throw new MuseDeviceLoginError( "device-authorization", "Muse Code device authorization response is missing the device or user code", { status: response.status }, ); } return { deviceCode, userCode, verificationUri: text(payload?.verification_uri) ?? VERIFICATION_FALLBACK_URL, ...(text(payload?.verification_uri_complete) ? { verificationUriComplete: text(payload?.verification_uri_complete) as string } : {}), intervalMs: normalizeIntervalMs(payload?.interval), expiresAtMs: now() + normalizeTtlMs(payload?.expires_in), }; } /** * Step 2: poll until approval. * * RFC 8628 signals state with an `error` code in a non-2xx body, so the CODE decides, not * the status. An unrecognized code is terminal: retrying a permanent failure just hammers * an auth endpoint until the grant expires. A 429 is treated as `slow_down` with * `Retry-After` honoured, because that is what it means here. */ export async function pollMuseDeviceToken( authorization: MuseDeviceAuthorization, deps: MuseDeviceDeps = {}, signal?: AbortSignal, ): Promise<string> { const now = deps.now ?? Date.now; const sleep = deps.sleep ?? defaultSleep; let intervalMs = authorization.intervalMs; while (true) { if (signal?.aborted) throw cancelled(); // [W4] Poll FIRST, then decide whether there is time to sleep again. The previous // shape checked the deadline at the top, so a sleep ending exactly at the deadline // skipped the final poll and discarded an approval the user had already completed // inside that window. const request = requestSignal(signal); const response = await (deps.fetchImpl ?? fetch)(DEVICE_TOKEN_URL, { method: "POST", headers: { Accept: "application/json", "Content-Type": "application/x-www-form-urlencoded", "x-api-version": API_VERSION, }, body: new URLSearchParams({ client_id: CLIENT_ID, device_code: authorization.deviceCode, grant_type: DEVICE_GRANT_TYPE, }).toString(), redirect: "error", signal: request, }); const payload = await readMuseJson(response, request, "device-token"); if (response.ok) { // [W3] No deadline re-check here. If Meta answered 200 with a token, Meta accepted // the device code; its clock is authoritative and ours is not. Discarding an issued // token because a local deadline just passed would force the user to redo an // approval that already succeeded. const accessToken = text(payload?.access_token); if (!accessToken) { throw new MuseDeviceLoginError( "device-token", "Muse Code device token response is missing an access token", { status: response.status }, ); } return accessToken; } const code = text(payload?.error)?.toLowerCase(); if (code === "access_denied") { throw new MuseDeviceLoginError("device-denied", "Muse Code login was denied in the browser", { status: response.status, }); } if (code === "expired_token") { throw new MuseDeviceLoginError("device-expired", "Muse Code device code expired; start the login again", { status: response.status, }); } if (code === "slow_down" || response.status === 429) { const advised = retryAfterMs(response.headers.get("retry-after"), now()); intervalMs = Math.min( MAX_POLL_INTERVAL_MS, Math.max(advised ?? 0, intervalMs + SLOW_DOWN_INCREMENT_MS), ); } else if (code !== "authorization_pending") { throw new MuseDeviceLoginError( "device-token", `Muse Code device token poll failed: HTTP ${response.status}`, { status: response.status }, ); } // [W4] The deadline is checked ONLY here, before sleeping. Reaching it means the // grant is spent: the loop has just polled and been told to wait longer than the // grant has left. Never sleep past it, which is how a 15-minute grant becomes a // 20-minute wait. const remaining = authorization.expiresAtMs - now(); if (remaining <= 0) { throw new MuseDeviceLoginError("device-expired", "Muse Code device authorization expired before approval"); } await sleep(Math.min(intervalMs, remaining), signal); } } /** * Step 3: mint the subscription key. * * `onboard` is sent only during an interactive login. Meta's key endpoint is rate-limited * and returns the SAME key for an account, so any caller that already holds one must not * come back here (`020` enforces that on refresh; `030` reuses this function read-only). */ export async function mintMuseApiKey( accountAccessToken: string, options: { onboard?: boolean } = {}, deps: MuseDeviceDeps = {}, signal?: AbortSignal, ): Promise<MuseKeyPayload> { const now = deps.now ?? Date.now; const request = requestSignal(signal); const response = await (deps.fetchImpl ?? fetch)(MUSE_KEY_URL, { method: "POST", headers: { Accept: "application/json", Authorization: `Bearer ${accountAccessToken}`, "Content-Type": "application/json", "x-api-version": API_VERSION, }, body: JSON.stringify(options.onboard ? { onboard: true } : {}), redirect: "error", signal: request, }); if (response.status === 429) { void response.body?.cancel().catch(() => undefined); const wait = retryAfterMs(response.headers.get("retry-after"), now()); throw new MuseDeviceLoginError( "mint-rate-limited", wait === undefined ? "Meta rate-limited the Muse Code key request; wait a minute and retry" : `Meta rate-limited the Muse Code key request; retry in about ${Math.ceil(wait / 1000)}s`, { status: 429, ...(wait === undefined ? {} : { retryAfterMs: wait }) }, ); } if (!response.ok) { // Status only. The body of this endpoint can carry the key itself, so it is // never parsed — but it is still cancelled so the connection is released. void response.body?.cancel().catch(() => undefined); throw new MuseDeviceLoginError( "mint-http", `Muse Code key exchange failed: HTTP ${response.status}`, { status: response.status }, ); } const payload = await readMuseJson(response, request, "mint-invalid"); if (!payload) { throw new MuseDeviceLoginError("mint-invalid", "Muse Code key exchange returned an unreadable response", { status: response.status, }); } return { ...(text(payload.api_key) ? { apiKey: text(payload.api_key) as string } : {}), ...(typeof payload.require_payment === "boolean" ? { requirePayment: payload.require_payment } : {}), ...(text(payload.action_url) ?? text(payload.require_payment_action_url) ? { actionUrl: (text(payload.action_url) ?? text(payload.require_payment_action_url)) as string } : {}), ...(text(payload.user_email) ? { userEmail: (text(payload.user_email) as string).toLowerCase() } : {}), ...(text(payload.user_id) ? { userId: text(payload.user_id) as string } : {}), ...(typeof payload.is_subs_active === "boolean" ? { isSubsActive: payload.is_subs_active } : {}), ...(text(payload.subs_tier_name) ? { subsTierName: text(payload.subs_tier_name) as string } : {}), ...(record(payload.subs_usage) ? { subsUsage: record(payload.subs_usage) as Record<string, unknown> } : {}), }; } /** * Turn a mint payload into the error it deserves, or return the validated key. * * Four distinct outcomes the reference collapses into fewer: an inactive subscription is * not a missing key, a payment requirement is not an auth failure, and a key that fails * the `LLM|` grammar is not a server error. */ export function museApiKeyFromPayload(payload: MuseKeyPayload): string { if (payload.isSubsActive === false) { throw new MuseDeviceLoginError( "subscription-inactive", "This Meta account has no active Muse Code subscription. Subscribe at https://dev.meta.ai, then log in again.", { status: 403 }, ); } const apiKey = sanitizeApiKeyValue(payload.apiKey); if (!apiKey) { if (payload.requirePayment === true || payload.actionUrl) { throw new MuseDeviceLoginError( "entitlement-required", payload.actionUrl ? `Meta requires a subscription or payment method before it will issue a Muse Code key: ${payload.actionUrl}` : "Meta requires a subscription or payment method before it will issue a Muse Code key.", { ...(payload.actionUrl ? { actionUrl: payload.actionUrl } : {}) }, ); } throw new MuseDeviceLoginError("missing-api-key", "Meta returned no Muse Code API key for this account"); } if (!/^LLM\|\d+\|[A-Za-z0-9_-]{10,}$/.test(apiKey)) { throw new MuseDeviceLoginError( "mint-invalid", "Meta returned a Muse Code key in an unexpected format; log in again", ); } return apiKey; } /** Run the whole grant. */ export async function loginMetaMuseDevice( ctrl: OAuthController = {}, deps: MuseDeviceDeps = {}, ): Promise<OAuthCredentials> { const authorization = await requestMuseDeviceAuthorization(deps, ctrl.signal); ctrl.onAuth?.({ url: authorization.verificationUriComplete ?? authorization.verificationUri, instructions: `Enter code: ${authorization.userCode}`, deviceCode: authorization.userCode, }); const accountAccessToken = await pollMuseDeviceToken(authorization, deps, ctrl.signal); ctrl.onProgress?.("Approved. Requesting the Muse Code subscription key..."); const payload = await mintMuseApiKey(accountAccessToken, { onboard: true }, deps, ctrl.signal); const apiKey = museApiKeyFromPayload(payload); if (payload.requirePayment === true || payload.actionUrl) { // [W5] A usable key AND a payment signal. Meta issued a credential but is saying the // plan does not cover it. The key is returned, because refusing a working credential // would be worse, but the warning is not swallowed: this is the difference between a // user who knows calls may be billed per token and one who finds out on an invoice. ctrl.onProgress?.(payload.actionUrl ? `Meta reports this account needs a subscription or payment method: ${payload.actionUrl}` : "Meta reports this account needs a subscription or payment method; treat every call as billable."); } const email = payload.userEmail; // [W2] email FIRST, user_id only as a fallback. The store keys a slot on // `accountId ?? email` (src/oauth/store.ts:744,752), and this provider import path has // always supplied email alone, so promoting user_id to accountId here would make a // device login MISS the row an imported login already created and hand one human two // accounts. user_id is still retained, in muse.userId, where it identifies the account // for the quota probe without participating in slot identity. if (!email && !payload.userId) { throw new MuseDeviceLoginError( "missing-identity", "Meta returned no stable account identity for this Muse Code key", ); } return { access: apiKey, // Static key: there is nothing to exchange, so refresh carries the same value. Meta // rejects refresh_token grants on this client (001 §A). refresh: apiKey, expires: Number.MAX_SAFE_INTEGER, ...(email ? { email } : { accountId: payload.userId as string }), source: "oauth", muse: { oauthAccessToken: accountAccessToken, ...(payload.userId ? { userId: payload.userId } : {}), mintedAt: (deps.now ?? Date.now)(), ...(payload.subsTierName ? { tierName: payload.subsTierName } : {}), }, }; }