@omnicross/subscriptions 0.3.1 → 0.4.1

package/dist/oauth.d.cts

@@ -2,6 +2,171 @@ import { FetchLike } from '@omnicross/core/auth/GeminiCodeAssistProjectResolver'
 export { FetchLike } from '@omnicross/core/auth/GeminiCodeAssistProjectResolver';
 import { TokenExchangeRequest, OAuthParams } from '@omnicross/contracts/account-tokens-types';
 
+/**
+ * GitHub Copilot OAuth flow — RFC 8628 device grant against the official
+ * Copilot CLI app at `github.com` (scope `read:user`).
+ *
+ * The minted `ghu_` token is LONG-LIVED: refresh is a LOCAL no-op (access and
+ * refresh are the same token; a far-future expiry keeps every generic
+ * near-expiry path idle). After the user approves, the flow (a) reads the
+ * GitHub identity (`/user` → login + email), (b) discovers the plan-advertised
+ * Copilot API endpoint (`api.github.com/copilot_internal/user` →
+ * `endpoints.api`), and (c) best-effort sweeps the model roster's
+ * `POST /models/{id}/policy {"state":"enabled"}` — the Claude/Grok models are
+ * policy-gated until enabled.
+ *
+ * Every Copilot API request carries the mirrored Copilot CLI identity
+ * (`copilot/1.0.82` UA + Editor-Version, Copilot-Integration-Id, Copilot-
+ * Harness-Id, Openai-Intent) plus `X-GitHub-Api-Version: 2026-08-01` — without
+ * the version header the endpoint serves default-tier context limits only
+ * (e.g. 264k instead of 1M). NEVER send the API version header to
+ * `api.github.com` REST endpoints (they validate it against the REST
+ * vocabulary). Relay traffic is agent-initiated CLI traffic, so the per-request
+ * dynamic `X-Initiator: agent` / `X-Interaction-Type: conversation-agent`
+ * pair is STATIC here — the same classification the official CLI sends, and
+ * the one GitHub bills at a 0 premium multiplier.
+ *
+ * GitHub Enterprise domains ride the SAME device flow on the enterprise host
+ * (`https://<domain>/login/{device/code,oauth/access_token}`); the stored
+ * `enterpriseUrl` additionally routes inference through `copilot-api.<domain>`
+ * and the REST probes (identity/quota) through `api.<domain>`.
+ *
+ * @module @omnicross/subscriptions/oauth/flows/copilot
+ */
+
+/** The official Copilot CLI OAuth app (public client). */
+declare const COPILOT_OAUTH_CONFIG: {
+    readonly clientId: "Ov23ctDVkRmgkPke0Mmm";
+    readonly scope: "read:user";
+    readonly deviceEndpoint: "https://github.com/login/device/code";
+    readonly tokenEndpoint: "https://github.com/login/oauth/access_token";
+};
+/**
+ * Normalize an operator-supplied GitHub Enterprise domain: accept a bare host
+ * or a full URL and keep ONLY the lowercase hostname. Empty input and the
+ * public github.com hosts mean the personal flow (`undefined`); anything that
+ * does not parse as a host THROWS (the caller surfaces the message).
+ */
+declare function normalizeCopilotEnterpriseDomain(input: string | undefined): string | undefined;
+/**
+ * Device-flow endpoints for a login — the GHE host, or the github.com default
+ * when `enterpriseUrl` is absent/normalized-away.
+ */
+declare function copilotOAuthUrls(enterpriseUrl?: string): {
+    deviceEndpoint: string;
+    tokenEndpoint: string;
+};
+/** GitHub's device-poll pacing: each wait scales ×1.2 (×1.4 after slow_down). */
+declare const COPILOT_POLL_INITIAL_MULTIPLIER = 1.2;
+declare const COPILOT_POLL_SLOW_DOWN_MULTIPLIER = 1.4;
+/** Headers for `api.github.com` REST/user endpoints (NO Copilot API version). */
+declare const COPILOT_GITHUB_HEADERS: Record<string, string>;
+/**
+ * The STATIC Copilot API identity every inference request carries
+ * (mirror of the official CLI's request layer).
+ */
+declare const COPILOT_API_HEADERS: Record<string, string>;
+/** Far-future expiry (10 years) — ghu_ tokens have no refresh lifecycle. */
+declare const COPILOT_FAR_FUTURE_MS: number;
+/** Device-authorization response (RFC 8628 §3.2). */
+interface CopilotDeviceAuthorization {
+    userCode: string;
+    deviceCode: string;
+    verificationUri: string;
+    /** Poll interval in seconds. */
+    interval: number;
+    /** Lifetime in seconds. */
+    expiresIn: number;
+}
+/** One polled token attempt's outcome. */
+type CopilotDevicePoll = {
+    state: 'pending';
+} | {
+    state: 'slowDown';
+    intervalSeconds?: number;
+} | {
+    state: 'done';
+    accessToken: string;
+} | {
+    state: 'failed';
+    message: string;
+};
+/** Request a device code the user approves at `verification_uri`. */
+declare function requestCopilotDeviceAuthorization(fetchImpl: FetchLike, enterpriseUrl?: string): Promise<CopilotDeviceAuthorization>;
+/** Poll the token endpoint ONCE (RFC 8628 §3.5 semantics). */
+declare function pollCopilotDeviceToken(deviceCode: string, fetchImpl: FetchLike, enterpriseUrl?: string): Promise<CopilotDevicePoll>;
+/**
+ * Drive the device-code login to completion. GitHub's pacing multiplies each
+ * wait (×1.2 baseline, ×1.4 once a slow_down arrives) — deliberately more
+ * conservative than the RFC's flat +5s. `onPending` fires after each poll.
+ */
+declare function awaitCopilotDeviceToken(authorization: CopilotDeviceAuthorization, fetchImpl: FetchLike, options?: {
+    deadlineMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    onPending?: () => void;
+    /** GHE host — routes the token poll off github.com. */
+    enterpriseUrl?: string;
+}): Promise<{
+    accessToken: string;
+}>;
+/** The GitHub identity for the minted token (login = the account id). */
+declare function fetchCopilotIdentity(accessToken: string, fetchImpl: FetchLike, enterpriseUrl?: string): Promise<{
+    accountId?: string;
+    email?: string;
+}>;
+/**
+ * Resolve the plan-advertised Copilot API endpoint
+ * (`copilot_internal/user` → `endpoints.api`); `undefined` falls back to the
+ * canonical personal host at dispatch time.
+ */
+declare function discoverCopilotApiEndpoint(accessToken: string, fetchImpl: FetchLike, enterpriseUrl?: string): Promise<string | undefined>;
+/**
+ * Enable one policy-gated model (`POST /models/{id}/policy`). Best-effort —
+ * the response is ignored and failures never fail the login.
+ */
+declare function enableCopilotModel(accessToken: string, modelId: string, baseUrl: string, fetchImpl: FetchLike): Promise<boolean>;
+/**
+ * Sweep the model roster's policy-enable endpoint (batched ×5). Best-effort:
+ * every failure is swallowed (already-enabled models return non-2xx too).
+ */
+declare function enableAllCopilotModels(accessToken: string, config: {
+    apiEndpoint?: string;
+    enterpriseUrl?: string;
+} | undefined, fetchImpl: FetchLike, onProgress?: (modelId: string, ok: boolean) => void): Promise<void>;
+/**
+ * "Refresh" a Copilot token — a LOCAL no-op. GitHub OAuth device tokens are
+ * long-lived with no exchange endpoint; the stored access token IS the
+ * credential. Returns the same pair with a far-future expiry so every generic
+ * refresh path stays a no-network success.
+ */
+declare function refreshCopilotToken(accessToken: string): {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+};
+
+declare const copilot_COPILOT_API_HEADERS: typeof COPILOT_API_HEADERS;
+declare const copilot_COPILOT_FAR_FUTURE_MS: typeof COPILOT_FAR_FUTURE_MS;
+declare const copilot_COPILOT_GITHUB_HEADERS: typeof COPILOT_GITHUB_HEADERS;
+declare const copilot_COPILOT_OAUTH_CONFIG: typeof COPILOT_OAUTH_CONFIG;
+declare const copilot_COPILOT_POLL_INITIAL_MULTIPLIER: typeof COPILOT_POLL_INITIAL_MULTIPLIER;
+declare const copilot_COPILOT_POLL_SLOW_DOWN_MULTIPLIER: typeof COPILOT_POLL_SLOW_DOWN_MULTIPLIER;
+type copilot_CopilotDeviceAuthorization = CopilotDeviceAuthorization;
+type copilot_CopilotDevicePoll = CopilotDevicePoll;
+declare const copilot_awaitCopilotDeviceToken: typeof awaitCopilotDeviceToken;
+declare const copilot_copilotOAuthUrls: typeof copilotOAuthUrls;
+declare const copilot_discoverCopilotApiEndpoint: typeof discoverCopilotApiEndpoint;
+declare const copilot_enableAllCopilotModels: typeof enableAllCopilotModels;
+declare const copilot_enableCopilotModel: typeof enableCopilotModel;
+declare const copilot_fetchCopilotIdentity: typeof fetchCopilotIdentity;
+declare const copilot_normalizeCopilotEnterpriseDomain: typeof normalizeCopilotEnterpriseDomain;
+declare const copilot_pollCopilotDeviceToken: typeof pollCopilotDeviceToken;
+declare const copilot_refreshCopilotToken: typeof refreshCopilotToken;
+declare const copilot_requestCopilotDeviceAuthorization: typeof requestCopilotDeviceAuthorization;
+declare namespace copilot {
+  export { copilot_COPILOT_API_HEADERS as COPILOT_API_HEADERS, copilot_COPILOT_FAR_FUTURE_MS as COPILOT_FAR_FUTURE_MS, copilot_COPILOT_GITHUB_HEADERS as COPILOT_GITHUB_HEADERS, copilot_COPILOT_OAUTH_CONFIG as COPILOT_OAUTH_CONFIG, copilot_COPILOT_POLL_INITIAL_MULTIPLIER as COPILOT_POLL_INITIAL_MULTIPLIER, copilot_COPILOT_POLL_SLOW_DOWN_MULTIPLIER as COPILOT_POLL_SLOW_DOWN_MULTIPLIER, type copilot_CopilotDeviceAuthorization as CopilotDeviceAuthorization, type copilot_CopilotDevicePoll as CopilotDevicePoll, copilot_awaitCopilotDeviceToken as awaitCopilotDeviceToken, copilot_copilotOAuthUrls as copilotOAuthUrls, copilot_discoverCopilotApiEndpoint as discoverCopilotApiEndpoint, copilot_enableAllCopilotModels as enableAllCopilotModels, copilot_enableCopilotModel as enableCopilotModel, copilot_fetchCopilotIdentity as fetchCopilotIdentity, copilot_normalizeCopilotEnterpriseDomain as normalizeCopilotEnterpriseDomain, copilot_pollCopilotDeviceToken as pollCopilotDeviceToken, copilot_refreshCopilotToken as refreshCopilotToken, copilot_requestCopilotDeviceAuthorization as requestCopilotDeviceAuthorization };
+}
+
 /**
  * Kimi Code OAuth flow — RFC 8628 device authorization grant (host-clean).
  *
@@ -240,4 +405,132 @@ declare namespace gemini {
   export { gemini_exchangeCodeForTokens as exchangeCodeForTokens, gemini_generateAuthParams as generateAuthParams, gemini_refreshAccessToken as refreshAccessToken };
 }
 
-export { claude as claudeOAuth, codex as codexOAuth, gemini as geminiOAuth, kimiFingerprintHeaders, kimi as kimiOAuth };
+/**
+ * Grok (xAI SuperGrok) OAuth flow — RFC 8628 device authorization grant.
+ *
+ * Mirrors the public Grok CLI client at `auth.x.ai` (client id reverse-derived
+ * from the official CLI, same as the audit source): a form-encoded
+ * device-authorization request with the CLI scopes, the user approving at
+ * `verification_uri`, and a polled token request whose RFC error codes arrive
+ * as HTTP 400 JSON bodies (hence the raw-form POST helper — the shared
+ * `postForm` rejects on any `error` body). Refresh is a standard
+ * `refresh_token` grant on the same endpoint.
+ *
+ * The token endpoint is NOT hard-coded: it is resolved through xAI's OIDC
+ * discovery document and pinned to HTTPS `x.ai` / `*.x.ai` (the discovery
+ * response is long-lived and its endpoint receives every future refresh
+ * token, so a drifted document must not redirect credentials off-origin).
+ * The discovery result is cached process-wide for an hour.
+ *
+ * The access token is a JWT; its `sub` claim is the account id. Inference
+ * rides `api.x.ai/v1/responses` (the codex-style Responses wire); the weekly
+ * credits / unified monthly quota lives behind `cli-chat-proxy.grok.com/v1/
+ * billing` (see `GrokAllowanceCollector`).
+ *
+ * Escape hatches: `GROK_OAUTH_DEVICE_ENDPOINT` / `GROK_OAUTH_DISCOVERY_URL`
+ * override the two endpoints (host-pinning still applies to the discovery
+ * result).
+ *
+ * @module @omnicross/subscriptions/oauth/flows/grok
+ */
+
+/** Grok CLI OAuth configuration (public client, mirrors the official CLI). */
+declare const GROK_OAUTH_CONFIG: {
+    readonly clientId: "b1a00492-073a-47ea-816f-4c329264a828";
+    readonly deviceAuthorizationEndpoint: string;
+    readonly discoveryUrl: string;
+    /** The CLI's full scope set — the token must carry `grok-cli:access` for inference. */
+    readonly scopes: readonly ["openid", "profile", "email", "offline_access", "grok-cli:access", "api:access"];
+};
+/** Device-authorization response (RFC 8628 §3.2). */
+interface GrokDeviceAuthorization {
+    userCode: string;
+    deviceCode: string;
+    /** Preferred: pre-fills the code when opened in the user's browser. */
+    verificationUri: string;
+    verificationUriComplete?: string;
+    /** Poll interval in seconds (RFC default 5). */
+    interval?: number;
+    /** Lifetime in seconds. */
+    expiresIn?: number;
+}
+/** One polled token attempt's outcome. */
+type GrokDevicePoll = {
+    state: 'pending';
+    intervalSeconds?: number;
+} | {
+    state: 'done';
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+} | {
+    state: 'failed';
+    message: string;
+};
+/** `x.ai` or any `*.x.ai` host — the only origins a token endpoint may live on. */
+declare function isGrokAuthHostname(host: string): boolean;
+/**
+ * Validate an endpoint URL against the token-endpoint contract: HTTPS and an
+ * `x.ai` / `*.x.ai` host. Throws a descriptive error otherwise.
+ */
+declare function validateGrokAuthEndpoint(url: string, field: string): string;
+/** Test seam: drop the discovery cache (the cache is process-level). */
+declare function resetGrokDiscoveryCache(): void;
+/**
+ * Resolve the OIDC token endpoint via discovery (cached 1h). The document's
+ * `token_endpoint` is host-pinned so a compromised or drifted discovery
+ * response can never redirect credentials off the xAI origin.
+ */
+declare function resolveGrokTokenEndpoint(fetchImpl: FetchLike, timeoutMs?: number): Promise<string>;
+/** Request a device code the user approves at `verification_uri`. */
+declare function requestGrokDeviceAuthorization(fetchImpl: FetchLike): Promise<GrokDeviceAuthorization>;
+/**
+ * Poll the token endpoint ONCE. RFC 8628 §3.5 semantics: `authorization_pending`
+ * keeps polling, `slow_down` adds 5s to the interval, anything else fails.
+ */
+declare function pollGrokDeviceToken(deviceCode: string, tokenEndpoint: string, fetchImpl: FetchLike): Promise<GrokDevicePoll>;
+/**
+ * Drive the device-code login to completion: poll at the device flow's
+ * interval (`slow_down` +5s each time, applied BEFORE the next wait) until
+ * done/expired/denied or `deadlineMs` elapses. `onPending` fires after each
+ * pending poll (so a CLI can render a spinner).
+ */
+declare function awaitGrokDeviceToken(authorization: GrokDeviceAuthorization, tokenEndpoint: string, fetchImpl: FetchLike, options?: {
+    intervalMs?: number;
+    deadlineMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    onPending?: () => void;
+}): Promise<{
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+}>;
+/** Refresh the access token with a `refresh_token` grant. */
+declare function refreshGrokAccessToken(refreshToken: string, tokenEndpoint: string, fetchImpl: FetchLike): Promise<{
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+}>;
+/**
+ * Decode the access-token JWT's `sub` claim (no verification — the issuer is
+ * trusted; we only read an id).
+ */
+declare function grokAccountIdFromAccessToken(accessToken: string): string | undefined;
+
+declare const grok_GROK_OAUTH_CONFIG: typeof GROK_OAUTH_CONFIG;
+type grok_GrokDeviceAuthorization = GrokDeviceAuthorization;
+type grok_GrokDevicePoll = GrokDevicePoll;
+declare const grok_awaitGrokDeviceToken: typeof awaitGrokDeviceToken;
+declare const grok_grokAccountIdFromAccessToken: typeof grokAccountIdFromAccessToken;
+declare const grok_isGrokAuthHostname: typeof isGrokAuthHostname;
+declare const grok_pollGrokDeviceToken: typeof pollGrokDeviceToken;
+declare const grok_refreshGrokAccessToken: typeof refreshGrokAccessToken;
+declare const grok_requestGrokDeviceAuthorization: typeof requestGrokDeviceAuthorization;
+declare const grok_resetGrokDiscoveryCache: typeof resetGrokDiscoveryCache;
+declare const grok_resolveGrokTokenEndpoint: typeof resolveGrokTokenEndpoint;
+declare const grok_validateGrokAuthEndpoint: typeof validateGrokAuthEndpoint;
+declare namespace grok {
+  export { grok_GROK_OAUTH_CONFIG as GROK_OAUTH_CONFIG, type grok_GrokDeviceAuthorization as GrokDeviceAuthorization, type grok_GrokDevicePoll as GrokDevicePoll, grok_awaitGrokDeviceToken as awaitGrokDeviceToken, grok_grokAccountIdFromAccessToken as grokAccountIdFromAccessToken, grok_isGrokAuthHostname as isGrokAuthHostname, grok_pollGrokDeviceToken as pollGrokDeviceToken, grok_refreshGrokAccessToken as refreshGrokAccessToken, grok_requestGrokDeviceAuthorization as requestGrokDeviceAuthorization, grok_resetGrokDiscoveryCache as resetGrokDiscoveryCache, grok_resolveGrokTokenEndpoint as resolveGrokTokenEndpoint, grok_validateGrokAuthEndpoint as validateGrokAuthEndpoint };
+}
+
+export { COPILOT_GITHUB_HEADERS, claude as claudeOAuth, codex as codexOAuth, copilot as copilotOAuth, gemini as geminiOAuth, grok as grokOAuth, kimiFingerprintHeaders, kimi as kimiOAuth };

package/dist/oauth.d.ts

@@ -2,6 +2,171 @@ import { FetchLike } from '@omnicross/core/auth/GeminiCodeAssistProjectResolver'
 export { FetchLike } from '@omnicross/core/auth/GeminiCodeAssistProjectResolver';
 import { TokenExchangeRequest, OAuthParams } from '@omnicross/contracts/account-tokens-types';
 
+/**
+ * GitHub Copilot OAuth flow — RFC 8628 device grant against the official
+ * Copilot CLI app at `github.com` (scope `read:user`).
+ *
+ * The minted `ghu_` token is LONG-LIVED: refresh is a LOCAL no-op (access and
+ * refresh are the same token; a far-future expiry keeps every generic
+ * near-expiry path idle). After the user approves, the flow (a) reads the
+ * GitHub identity (`/user` → login + email), (b) discovers the plan-advertised
+ * Copilot API endpoint (`api.github.com/copilot_internal/user` →
+ * `endpoints.api`), and (c) best-effort sweeps the model roster's
+ * `POST /models/{id}/policy {"state":"enabled"}` — the Claude/Grok models are
+ * policy-gated until enabled.
+ *
+ * Every Copilot API request carries the mirrored Copilot CLI identity
+ * (`copilot/1.0.82` UA + Editor-Version, Copilot-Integration-Id, Copilot-
+ * Harness-Id, Openai-Intent) plus `X-GitHub-Api-Version: 2026-08-01` — without
+ * the version header the endpoint serves default-tier context limits only
+ * (e.g. 264k instead of 1M). NEVER send the API version header to
+ * `api.github.com` REST endpoints (they validate it against the REST
+ * vocabulary). Relay traffic is agent-initiated CLI traffic, so the per-request
+ * dynamic `X-Initiator: agent` / `X-Interaction-Type: conversation-agent`
+ * pair is STATIC here — the same classification the official CLI sends, and
+ * the one GitHub bills at a 0 premium multiplier.
+ *
+ * GitHub Enterprise domains ride the SAME device flow on the enterprise host
+ * (`https://<domain>/login/{device/code,oauth/access_token}`); the stored
+ * `enterpriseUrl` additionally routes inference through `copilot-api.<domain>`
+ * and the REST probes (identity/quota) through `api.<domain>`.
+ *
+ * @module @omnicross/subscriptions/oauth/flows/copilot
+ */
+
+/** The official Copilot CLI OAuth app (public client). */
+declare const COPILOT_OAUTH_CONFIG: {
+    readonly clientId: "Ov23ctDVkRmgkPke0Mmm";
+    readonly scope: "read:user";
+    readonly deviceEndpoint: "https://github.com/login/device/code";
+    readonly tokenEndpoint: "https://github.com/login/oauth/access_token";
+};
+/**
+ * Normalize an operator-supplied GitHub Enterprise domain: accept a bare host
+ * or a full URL and keep ONLY the lowercase hostname. Empty input and the
+ * public github.com hosts mean the personal flow (`undefined`); anything that
+ * does not parse as a host THROWS (the caller surfaces the message).
+ */
+declare function normalizeCopilotEnterpriseDomain(input: string | undefined): string | undefined;
+/**
+ * Device-flow endpoints for a login — the GHE host, or the github.com default
+ * when `enterpriseUrl` is absent/normalized-away.
+ */
+declare function copilotOAuthUrls(enterpriseUrl?: string): {
+    deviceEndpoint: string;
+    tokenEndpoint: string;
+};
+/** GitHub's device-poll pacing: each wait scales ×1.2 (×1.4 after slow_down). */
+declare const COPILOT_POLL_INITIAL_MULTIPLIER = 1.2;
+declare const COPILOT_POLL_SLOW_DOWN_MULTIPLIER = 1.4;
+/** Headers for `api.github.com` REST/user endpoints (NO Copilot API version). */
+declare const COPILOT_GITHUB_HEADERS: Record<string, string>;
+/**
+ * The STATIC Copilot API identity every inference request carries
+ * (mirror of the official CLI's request layer).
+ */
+declare const COPILOT_API_HEADERS: Record<string, string>;
+/** Far-future expiry (10 years) — ghu_ tokens have no refresh lifecycle. */
+declare const COPILOT_FAR_FUTURE_MS: number;
+/** Device-authorization response (RFC 8628 §3.2). */
+interface CopilotDeviceAuthorization {
+    userCode: string;
+    deviceCode: string;
+    verificationUri: string;
+    /** Poll interval in seconds. */
+    interval: number;
+    /** Lifetime in seconds. */
+    expiresIn: number;
+}
+/** One polled token attempt's outcome. */
+type CopilotDevicePoll = {
+    state: 'pending';
+} | {
+    state: 'slowDown';
+    intervalSeconds?: number;
+} | {
+    state: 'done';
+    accessToken: string;
+} | {
+    state: 'failed';
+    message: string;
+};
+/** Request a device code the user approves at `verification_uri`. */
+declare function requestCopilotDeviceAuthorization(fetchImpl: FetchLike, enterpriseUrl?: string): Promise<CopilotDeviceAuthorization>;
+/** Poll the token endpoint ONCE (RFC 8628 §3.5 semantics). */
+declare function pollCopilotDeviceToken(deviceCode: string, fetchImpl: FetchLike, enterpriseUrl?: string): Promise<CopilotDevicePoll>;
+/**
+ * Drive the device-code login to completion. GitHub's pacing multiplies each
+ * wait (×1.2 baseline, ×1.4 once a slow_down arrives) — deliberately more
+ * conservative than the RFC's flat +5s. `onPending` fires after each poll.
+ */
+declare function awaitCopilotDeviceToken(authorization: CopilotDeviceAuthorization, fetchImpl: FetchLike, options?: {
+    deadlineMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    onPending?: () => void;
+    /** GHE host — routes the token poll off github.com. */
+    enterpriseUrl?: string;
+}): Promise<{
+    accessToken: string;
+}>;
+/** The GitHub identity for the minted token (login = the account id). */
+declare function fetchCopilotIdentity(accessToken: string, fetchImpl: FetchLike, enterpriseUrl?: string): Promise<{
+    accountId?: string;
+    email?: string;
+}>;
+/**
+ * Resolve the plan-advertised Copilot API endpoint
+ * (`copilot_internal/user` → `endpoints.api`); `undefined` falls back to the
+ * canonical personal host at dispatch time.
+ */
+declare function discoverCopilotApiEndpoint(accessToken: string, fetchImpl: FetchLike, enterpriseUrl?: string): Promise<string | undefined>;
+/**
+ * Enable one policy-gated model (`POST /models/{id}/policy`). Best-effort —
+ * the response is ignored and failures never fail the login.
+ */
+declare function enableCopilotModel(accessToken: string, modelId: string, baseUrl: string, fetchImpl: FetchLike): Promise<boolean>;
+/**
+ * Sweep the model roster's policy-enable endpoint (batched ×5). Best-effort:
+ * every failure is swallowed (already-enabled models return non-2xx too).
+ */
+declare function enableAllCopilotModels(accessToken: string, config: {
+    apiEndpoint?: string;
+    enterpriseUrl?: string;
+} | undefined, fetchImpl: FetchLike, onProgress?: (modelId: string, ok: boolean) => void): Promise<void>;
+/**
+ * "Refresh" a Copilot token — a LOCAL no-op. GitHub OAuth device tokens are
+ * long-lived with no exchange endpoint; the stored access token IS the
+ * credential. Returns the same pair with a far-future expiry so every generic
+ * refresh path stays a no-network success.
+ */
+declare function refreshCopilotToken(accessToken: string): {
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+};
+
+declare const copilot_COPILOT_API_HEADERS: typeof COPILOT_API_HEADERS;
+declare const copilot_COPILOT_FAR_FUTURE_MS: typeof COPILOT_FAR_FUTURE_MS;
+declare const copilot_COPILOT_GITHUB_HEADERS: typeof COPILOT_GITHUB_HEADERS;
+declare const copilot_COPILOT_OAUTH_CONFIG: typeof COPILOT_OAUTH_CONFIG;
+declare const copilot_COPILOT_POLL_INITIAL_MULTIPLIER: typeof COPILOT_POLL_INITIAL_MULTIPLIER;
+declare const copilot_COPILOT_POLL_SLOW_DOWN_MULTIPLIER: typeof COPILOT_POLL_SLOW_DOWN_MULTIPLIER;
+type copilot_CopilotDeviceAuthorization = CopilotDeviceAuthorization;
+type copilot_CopilotDevicePoll = CopilotDevicePoll;
+declare const copilot_awaitCopilotDeviceToken: typeof awaitCopilotDeviceToken;
+declare const copilot_copilotOAuthUrls: typeof copilotOAuthUrls;
+declare const copilot_discoverCopilotApiEndpoint: typeof discoverCopilotApiEndpoint;
+declare const copilot_enableAllCopilotModels: typeof enableAllCopilotModels;
+declare const copilot_enableCopilotModel: typeof enableCopilotModel;
+declare const copilot_fetchCopilotIdentity: typeof fetchCopilotIdentity;
+declare const copilot_normalizeCopilotEnterpriseDomain: typeof normalizeCopilotEnterpriseDomain;
+declare const copilot_pollCopilotDeviceToken: typeof pollCopilotDeviceToken;
+declare const copilot_refreshCopilotToken: typeof refreshCopilotToken;
+declare const copilot_requestCopilotDeviceAuthorization: typeof requestCopilotDeviceAuthorization;
+declare namespace copilot {
+  export { copilot_COPILOT_API_HEADERS as COPILOT_API_HEADERS, copilot_COPILOT_FAR_FUTURE_MS as COPILOT_FAR_FUTURE_MS, copilot_COPILOT_GITHUB_HEADERS as COPILOT_GITHUB_HEADERS, copilot_COPILOT_OAUTH_CONFIG as COPILOT_OAUTH_CONFIG, copilot_COPILOT_POLL_INITIAL_MULTIPLIER as COPILOT_POLL_INITIAL_MULTIPLIER, copilot_COPILOT_POLL_SLOW_DOWN_MULTIPLIER as COPILOT_POLL_SLOW_DOWN_MULTIPLIER, type copilot_CopilotDeviceAuthorization as CopilotDeviceAuthorization, type copilot_CopilotDevicePoll as CopilotDevicePoll, copilot_awaitCopilotDeviceToken as awaitCopilotDeviceToken, copilot_copilotOAuthUrls as copilotOAuthUrls, copilot_discoverCopilotApiEndpoint as discoverCopilotApiEndpoint, copilot_enableAllCopilotModels as enableAllCopilotModels, copilot_enableCopilotModel as enableCopilotModel, copilot_fetchCopilotIdentity as fetchCopilotIdentity, copilot_normalizeCopilotEnterpriseDomain as normalizeCopilotEnterpriseDomain, copilot_pollCopilotDeviceToken as pollCopilotDeviceToken, copilot_refreshCopilotToken as refreshCopilotToken, copilot_requestCopilotDeviceAuthorization as requestCopilotDeviceAuthorization };
+}
+
 /**
  * Kimi Code OAuth flow — RFC 8628 device authorization grant (host-clean).
  *
@@ -240,4 +405,132 @@ declare namespace gemini {
   export { gemini_exchangeCodeForTokens as exchangeCodeForTokens, gemini_generateAuthParams as generateAuthParams, gemini_refreshAccessToken as refreshAccessToken };
 }
 
-export { claude as claudeOAuth, codex as codexOAuth, gemini as geminiOAuth, kimiFingerprintHeaders, kimi as kimiOAuth };
+/**
+ * Grok (xAI SuperGrok) OAuth flow — RFC 8628 device authorization grant.
+ *
+ * Mirrors the public Grok CLI client at `auth.x.ai` (client id reverse-derived
+ * from the official CLI, same as the audit source): a form-encoded
+ * device-authorization request with the CLI scopes, the user approving at
+ * `verification_uri`, and a polled token request whose RFC error codes arrive
+ * as HTTP 400 JSON bodies (hence the raw-form POST helper — the shared
+ * `postForm` rejects on any `error` body). Refresh is a standard
+ * `refresh_token` grant on the same endpoint.
+ *
+ * The token endpoint is NOT hard-coded: it is resolved through xAI's OIDC
+ * discovery document and pinned to HTTPS `x.ai` / `*.x.ai` (the discovery
+ * response is long-lived and its endpoint receives every future refresh
+ * token, so a drifted document must not redirect credentials off-origin).
+ * The discovery result is cached process-wide for an hour.
+ *
+ * The access token is a JWT; its `sub` claim is the account id. Inference
+ * rides `api.x.ai/v1/responses` (the codex-style Responses wire); the weekly
+ * credits / unified monthly quota lives behind `cli-chat-proxy.grok.com/v1/
+ * billing` (see `GrokAllowanceCollector`).
+ *
+ * Escape hatches: `GROK_OAUTH_DEVICE_ENDPOINT` / `GROK_OAUTH_DISCOVERY_URL`
+ * override the two endpoints (host-pinning still applies to the discovery
+ * result).
+ *
+ * @module @omnicross/subscriptions/oauth/flows/grok
+ */
+
+/** Grok CLI OAuth configuration (public client, mirrors the official CLI). */
+declare const GROK_OAUTH_CONFIG: {
+    readonly clientId: "b1a00492-073a-47ea-816f-4c329264a828";
+    readonly deviceAuthorizationEndpoint: string;
+    readonly discoveryUrl: string;
+    /** The CLI's full scope set — the token must carry `grok-cli:access` for inference. */
+    readonly scopes: readonly ["openid", "profile", "email", "offline_access", "grok-cli:access", "api:access"];
+};
+/** Device-authorization response (RFC 8628 §3.2). */
+interface GrokDeviceAuthorization {
+    userCode: string;
+    deviceCode: string;
+    /** Preferred: pre-fills the code when opened in the user's browser. */
+    verificationUri: string;
+    verificationUriComplete?: string;
+    /** Poll interval in seconds (RFC default 5). */
+    interval?: number;
+    /** Lifetime in seconds. */
+    expiresIn?: number;
+}
+/** One polled token attempt's outcome. */
+type GrokDevicePoll = {
+    state: 'pending';
+    intervalSeconds?: number;
+} | {
+    state: 'done';
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+} | {
+    state: 'failed';
+    message: string;
+};
+/** `x.ai` or any `*.x.ai` host — the only origins a token endpoint may live on. */
+declare function isGrokAuthHostname(host: string): boolean;
+/**
+ * Validate an endpoint URL against the token-endpoint contract: HTTPS and an
+ * `x.ai` / `*.x.ai` host. Throws a descriptive error otherwise.
+ */
+declare function validateGrokAuthEndpoint(url: string, field: string): string;
+/** Test seam: drop the discovery cache (the cache is process-level). */
+declare function resetGrokDiscoveryCache(): void;
+/**
+ * Resolve the OIDC token endpoint via discovery (cached 1h). The document's
+ * `token_endpoint` is host-pinned so a compromised or drifted discovery
+ * response can never redirect credentials off the xAI origin.
+ */
+declare function resolveGrokTokenEndpoint(fetchImpl: FetchLike, timeoutMs?: number): Promise<string>;
+/** Request a device code the user approves at `verification_uri`. */
+declare function requestGrokDeviceAuthorization(fetchImpl: FetchLike): Promise<GrokDeviceAuthorization>;
+/**
+ * Poll the token endpoint ONCE. RFC 8628 §3.5 semantics: `authorization_pending`
+ * keeps polling, `slow_down` adds 5s to the interval, anything else fails.
+ */
+declare function pollGrokDeviceToken(deviceCode: string, tokenEndpoint: string, fetchImpl: FetchLike): Promise<GrokDevicePoll>;
+/**
+ * Drive the device-code login to completion: poll at the device flow's
+ * interval (`slow_down` +5s each time, applied BEFORE the next wait) until
+ * done/expired/denied or `deadlineMs` elapses. `onPending` fires after each
+ * pending poll (so a CLI can render a spinner).
+ */
+declare function awaitGrokDeviceToken(authorization: GrokDeviceAuthorization, tokenEndpoint: string, fetchImpl: FetchLike, options?: {
+    intervalMs?: number;
+    deadlineMs?: number;
+    sleep?: (ms: number) => Promise<void>;
+    onPending?: () => void;
+}): Promise<{
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+}>;
+/** Refresh the access token with a `refresh_token` grant. */
+declare function refreshGrokAccessToken(refreshToken: string, tokenEndpoint: string, fetchImpl: FetchLike): Promise<{
+    accessToken: string;
+    refreshToken: string;
+    expiresIn: number;
+}>;
+/**
+ * Decode the access-token JWT's `sub` claim (no verification — the issuer is
+ * trusted; we only read an id).
+ */
+declare function grokAccountIdFromAccessToken(accessToken: string): string | undefined;
+
+declare const grok_GROK_OAUTH_CONFIG: typeof GROK_OAUTH_CONFIG;
+type grok_GrokDeviceAuthorization = GrokDeviceAuthorization;
+type grok_GrokDevicePoll = GrokDevicePoll;
+declare const grok_awaitGrokDeviceToken: typeof awaitGrokDeviceToken;
+declare const grok_grokAccountIdFromAccessToken: typeof grokAccountIdFromAccessToken;
+declare const grok_isGrokAuthHostname: typeof isGrokAuthHostname;
+declare const grok_pollGrokDeviceToken: typeof pollGrokDeviceToken;
+declare const grok_refreshGrokAccessToken: typeof refreshGrokAccessToken;
+declare const grok_requestGrokDeviceAuthorization: typeof requestGrokDeviceAuthorization;
+declare const grok_resetGrokDiscoveryCache: typeof resetGrokDiscoveryCache;
+declare const grok_resolveGrokTokenEndpoint: typeof resolveGrokTokenEndpoint;
+declare const grok_validateGrokAuthEndpoint: typeof validateGrokAuthEndpoint;
+declare namespace grok {
+  export { grok_GROK_OAUTH_CONFIG as GROK_OAUTH_CONFIG, type grok_GrokDeviceAuthorization as GrokDeviceAuthorization, type grok_GrokDevicePoll as GrokDevicePoll, grok_awaitGrokDeviceToken as awaitGrokDeviceToken, grok_grokAccountIdFromAccessToken as grokAccountIdFromAccessToken, grok_isGrokAuthHostname as isGrokAuthHostname, grok_pollGrokDeviceToken as pollGrokDeviceToken, grok_refreshGrokAccessToken as refreshGrokAccessToken, grok_requestGrokDeviceAuthorization as requestGrokDeviceAuthorization, grok_resetGrokDiscoveryCache as resetGrokDiscoveryCache, grok_resolveGrokTokenEndpoint as resolveGrokTokenEndpoint, grok_validateGrokAuthEndpoint as validateGrokAuthEndpoint };
+}
+
+export { COPILOT_GITHUB_HEADERS, claude as claudeOAuth, codex as codexOAuth, copilot as copilotOAuth, gemini as geminiOAuth, grok as grokOAuth, kimiFingerprintHeaders, kimi as kimiOAuth };

package/dist/oauth.js

@@ -1,15 +1,21 @@
 import {
+  COPILOT_GITHUB_HEADERS,
   claude_exports,
   codex_exports,
+  copilot_exports,
   gemini_exports,
+  grok_exports,
   kimiFingerprintHeaders,
   kimi_exports
-} from "./chunk-ZB3GA2Y2.js";
+} from "./chunk-L77HJY6V.js";
 import "./chunk-MLKGABMK.js";
 export {
+  COPILOT_GITHUB_HEADERS,
   claude_exports as claudeOAuth,
   codex_exports as codexOAuth,
+  copilot_exports as copilotOAuth,
   gemini_exports as geminiOAuth,
+  grok_exports as grokOAuth,
   kimiFingerprintHeaders,
   kimi_exports as kimiOAuth
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omnicross/subscriptions",
-  "version": "0.3.1",
+  "version": "0.4.1",
   "description": "Omnicross subscription-as-provider auth strategies, OAuth flows, and the OpenCodeGo scenario dispatcher.",
   "license": "MIT",
   "author": "Sayo (https://github.com/Dumoedss)",
@@ -52,8 +52,8 @@
     "typecheck": "tsc -p tsconfig.typecheck.json --noEmit"
   },
   "dependencies": {
-    "@omnicross/contracts": "^0.3.1",
-    "@omnicross/core": "^0.3.1",
+    "@omnicross/contracts": "^0.4.1",
+    "@omnicross/core": "^0.4.1",
     "js-tiktoken": "^1.0.21",
     "sharp": "^0.35.4"
   }