Module muse 

Meta Muse Code OAuth (RFC 8628 device authorization + Model API key mint).

Experimental. Flow verified against the official Muse Code CLI (muse 1.4.6-R6000.1, installed via dev.meta.ai/install.sh) by driving it against local mock servers and reading its embedded constants. The endpoints are not published as a stable third-party API; do not describe them as officially supported.

Flow shape (differences from Kimi Code / GitHub Copilot):

• Device authorization at auth.meta.com/oidc/device/{authorization,token}/ with a public client id, no PKCE and no scope parameter.
• The OAuth access token is NOT the inference bearer. It is exchanged once at POST api.meta.ai/muse-code/key ({"onboard":false}) for a Model API key, and that key is the Authorization: Bearer for api.meta.ai/v1/responses (OpenAI Responses wire). An API key created at dev.meta.ai is the same kind of credential (META_API_KEY).
• The CLI never refreshes the OAuth token and never proactively re-mints: the key is used until the API answers 401, then re-minted ONCE with the stored OAuth access token and the request retried once. A mint 401 means the login itself is dead — the user must log in again. We mirror this.

Credential mapping:

• OAuthCredentials.refresh = Meta OAuth access token (broker-owned; used only to re-mint; never vended, logged, or sent to the inference host)
• OAuthCredentials.access = minted Model API key (the inference bearer)
• OAuthCredentials.expires = nominal re-validation horizon (see API_KEY_NOMINAL_LIFETIME_MS); real invalidation is 401-driven.

The OAuth refresh token is deliberately not stored: the official client never uses it, so keeping it would only widen what a leaked auth.json exposes.

Structs

DeviceAuthorization

LoginHooks

MintedKey

A minted Model API key plus the non-secret account facts the mint echoes.

MuseHttpResponse

Minimal HTTP response used by the device-flow / mint state machine.

Enums

DevicePollOutcome

Outcome of one device-token poll (secret-safe; token only on Authorized).

MuseAuthError

Failures from the Muse auth chain. Variants store no device codes, user codes, tokens, keys, or upstream bodies, so Display/Debug cannot leak them.

Constants

API_BASE_URL

OpenAI Responses base ({API_BASE_URL}/responses).

API_HOST

Inference/API host (TBH_MINT_BASE_URL default).

API_KEY_ENV

Environment override honoured by the official CLI: a Model API key here takes precedence over the account login.

API_KEY_NOMINAL_LIFETIME_MS

Minted keys carry no expiry. The official CLI uses a key until the API answers 401 and never re-mints proactively; this horizon only keeps the repo-wide expiry check from ever forcing a needless re-mint (each mint is a server-side side effect). Invalidation is 401-driven via the broker’s rejected-token recovery.

API_ORIGIN

Origin the broker pins for every Muse request. Paths are allowlisted broker-side (/v1/responses, /muse-code/models).

CLIENT_ID

Public native-client id shipped in the official Muse Code CLI. Not a client secret.

CONNECT_TIMEOUT

Connect timeout for production device/poll/mint HTTP.

DEVICE_AUTH_URL

Device-authorization endpoint (RFC 8628 §3.1). Trailing slash is part of the path the official CLI sends.

DEVICE_GRANT_TYPE

Device-code grant type (RFC 8628).

MAX_RESPONSE_BODY_BYTES

Maximum response body bytes accepted from device/poll/mint endpoints.

MINT_API_VERSION

x-api-version the official CLI sends on the mint request.

MINT_BODY

Exact mint body the official CLI sends for a returning login.

MINT_URL

Model-API-key mint endpoint (bearer = OAuth access token).

OAUTH_HOST

Meta OAuth host pinned by the official CLI (TBH_AUTH_BASE_URL default).

ONBOARDING_REQUIRED_CODE

Upstream error code returned by the mint when the account has not finished Model API onboarding.

ONBOARDING_URL

Where a Meta account finishes Model API onboarding / billing.

PROVIDER

Canonical storage / broker / model-prefix id.

REQUEST_TIMEOUT

Full request timeout for production device/poll/mint HTTP.

TOKEN_URL

Device-code token endpoint (RFC 8628 §3.4).

USER_AGENT

Honest User-Agent.

Traits

MuseBrowser

Injectable browser opener (production uses open_browser).

MuseClock

Injectable clock (now + cancellable sleep) for deterministic poll tests.

MuseHttp

Injectable HTTP surface so tests never touch the network.

Functions

api_key_from_env

Model API key from the environment override, if set and non-blank.

apply_slow_down

credentials_from_mint

OAuth access token → refresh; minted key → access (the bearer).

env_api_key_present

Presence-only check for the META_API_KEY override (the value never leaves this module). Used by pickers: Muse is usable without a stored login when the override is set.

login

Production login entry (real network + system browser + auth.json).

login_into

Production login; Some(key) persists ONLY into that slot, None returns the credential unsaved.

login_with_into

Device start → user prompt → poll → mint → persist into persist_key (muse or muse@<label>) when given; None returns it unsaved.

mint_api_key

Exchange the Meta OAuth access token for a Model API key. The OAuth token is sent only to the pinned mint URL. Callers must never log it.

mint_credentials

Mint and build the stored credential.

mint_request_headers

Non-secret headers attached to the pinned mint request (bearer is set by the HTTP adapter and can never be overridden through this list).

parse_device_code_response

parse_device_poll_response

parse_mint_response

Classify a mint response. Upstream bytes never enter the error: the onboarding code is matched as a fixed token, everything else maps to a static variant.

poll_device_token

One poll against the token endpoint.

read_body_capped

Read a response body with a hard byte cap. Fail closed if exceeded.

refresh_token

Broker refresh: re-mint a Model API key from the stored OAuth access token (no browser). The OAuth token is carried over unchanged, so the compare-and-swap save in the token store matches.

start_device_authorization

Start device authorization (POST device/authorization/).

validate_device_endpoint

Accept only the exact pinned HTTPS auth.meta.com device endpoints.

validate_mint_endpoint

Accept only the pinned mint host+path (no query, no alternate host).

validate_verification_uri

Verification destinations must be plain HTTPS pages on a Meta-owned host (meta.com / *.meta.com, meta.ai / *.meta.ai). Rejects userinfo, explicit ports, fragments, and look-alike hosts. Path/query are left to the server (the device page shape is not part of the pinned contract).

wait_for_device_authorization

Poll until authorized, denied, expired, cancelled, or deadline. Returns the OAuth access token.

Type Aliases

UserCodeHook