Module kimi_code 

Kimi Code OAuth (RFC 8628 device authorization; direct bearer, no mint).

Experimental. Flow verified against the official Kimi Code CLI (v0.31.1): its embedded packages/oauth sources pin the same endpoints, client id, grant type, error codes, and refresh semantics implemented here. The endpoints are not published as a stable third-party API; do not describe them as officially supported.

Flow shape (differences from GitHub Copilot):

• No session mint: the device-flow access_token is used directly as the API bearer for https://api.kimi.com/coding/v1.
• Access tokens are short-lived (~15 min) and refresh tokens rotate on every refresh — the rotated pair must always be persisted.
• A refresh rejected with HTTP 401/403 or invalid_grant means the stored refresh token is dead; the user must re-login.
• Upstream sends X-Msh-* device-identity headers on every OAuth and API request; we mirror that conventional surface with an honest User-Agent.

Credential mapping:

• OAuthCredentials.refresh = rotating Kimi refresh token (broker-owned)
• OAuthCredentials.access = short-lived Kimi access token
• OAuthCredentials.expires = access expiry (ms, with refresh margin)

Structs

DeviceAuthorization

InjectedHttpResponse

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

KimiTokenSet

Successful token grant (poll or refresh). Secret-bearing — never logged.

LoginHooks

Enums

DevicePollOutcome

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

KimiAuthError

Failures from the Kimi auth chain. Variants intentionally store no device codes, user codes, or tokens so Display/Debug cannot leak them.

RefreshDisposition

Whether one refresh attempt should be retried or surfaced.

Constants

API_BASE_URL

Managed Kimi Code API base (bearer = OAuth access token).

CLIENT_ID

Public native-client id shipped inside the official Kimi Code CLI (KIMI_CODE_FLOW_CONFIG.clientId). Not a client secret.

CONNECT_TIMEOUT

Connect timeout for production OAuth HTTP.

DEVICE_AUTH_URL

Device-authorization endpoint (RFC 8628 §3.1, Kimi path shape).

DEVICE_GRANT_TYPE

Device-code grant type (RFC 8628).

MAX_RESPONSE_BODY_BYTES

Maximum response body bytes accepted from OAuth endpoints.

MSH_PLATFORM

Conventional platform tag sent by the official CLI (X-Msh-Platform).

MSH_SURFACE_VERSION

Kimi Code surface version this flow was verified against (X-Msh-Version).

OAUTH_HOST

OAuth host pinned by the official CLI (https://auth.kimi.com).

PROVIDER

Canonical storage / broker / model-prefix id.

REQUEST_TIMEOUT

Full request timeout for production OAuth HTTP.

TOKEN_URL

Token endpoint — device-code polling AND refresh grants.

USER_AGENT

Honest User-Agent (matches the Copilot mint precedent).

Traits

KimiBrowser

Injectable browser opener (production uses open_browser).

KimiCancel

Injectable cancellation signal for device-flow polling.

KimiClock

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

KimiHttp

Injectable HTTP surface so tests never touch the network.

Functions

apply_slow_down

classify_refresh_response

Classify one refresh response. Pure; drives the retry loop.

credentials_from_token

Map a granted token set onto broker credentials.

device_id_path

Path of the persistent Kimi device id (kept beside auth.json, mode 0600).

identity_request_headers

Device-identity headers sent on every OAuth and managed-API request.

load_or_create_device_id

Load the stable device id, creating (and best-effort persisting) a fresh UUIDv4 on first use. Upstream parity: createKimiDeviceId.

login

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

login_with

Device start → user prompt → poll → atomic persist.

parse_device_code_response

parse_device_poll_response

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: rotate the token pair (no browser). The caller persists the rotated credentials via the provider single-flight gate.

refresh_with

Refresh with upstream retry semantics: up to 3 attempts, exponential backoff on 429/5xx, immediate failure on 401/403/invalid_grant.

start_device_authorization

Start device authorization (POST /api/oauth/device_authorization).

validate_oauth_endpoint

Accept only the exact pinned HTTPS auth.kimi.com OAuth endpoints.

validate_verification_uri

Accept only an HTTPS kimi.com / *.kimi.com verification destination with no userinfo, no fragment, and no explicit port. The exact path is server-assigned (not a documented constant), so the host is the pin.

wait_for_device_authorization

Poll until authorized, denied, expired, cancelled, or deadline.

Type Aliases

UserCodeHook