@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
text/typescript
/**
* 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 } : {}),
},
};
}