codex-xai-oauth 0.1.0

package/dist/openai-compat/server.d.ts

@@ -0,0 +1,10 @@
+export type CompatServer = {
+    readonly baseUrl: string;
+    readonly close: () => Promise<void>;
+    readonly port: number;
+};
+export declare function startOpenAiCompatServer(options?: {
+    readonly host?: string;
+    readonly port?: number;
+}): Promise<CompatServer>;
+//# sourceMappingURL=server.d.ts.map

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const PACKAGE_VERSION = "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/xai/browser-oauth.d.ts

@@ -0,0 +1,24 @@
+import type { StoredAuth } from "./types.js";
+type CallbackResult = {
+    readonly code?: string;
+    readonly error?: string;
+    readonly error_description?: string;
+    readonly state?: string;
+};
+export declare function startCallbackServer(options?: {
+    readonly port?: number;
+}): Promise<{
+    readonly close: () => Promise<void>;
+    readonly redirectUri: string;
+    readonly waitForCallback: () => Promise<CallbackResult>;
+}>;
+export declare function beginOAuth(options?: {
+    readonly port?: number;
+}): Promise<{
+    readonly complete: () => Promise<StoredAuth>;
+    readonly redirectUri: string;
+    readonly state: string;
+    readonly url: string;
+}>;
+export {};
+//# sourceMappingURL=browser-oauth.d.ts.map

package/dist/xai/codex-config.d.ts

@@ -0,0 +1,9 @@
+export type CodexModelProviderCredentials = {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly configFile: string;
+    readonly providerName: string;
+};
+export declare function codexConfigPath(): string;
+export declare function readCodexModelProviderCredentials(path?: string): CodexModelProviderCredentials | undefined;
+//# sourceMappingURL=codex-config.d.ts.map

package/dist/xai/constants.d.ts

@@ -0,0 +1,17 @@
+export declare const XAI_BASE_URL = "https://api.x.ai/v1";
+export declare const XAI_OAUTH_ISSUER = "https://auth.x.ai";
+export declare const XAI_OAUTH_AUTHORIZE_URL = "https://auth.x.ai/oauth2/authorize";
+export declare const XAI_OAUTH_TOKEN_URL = "https://auth.x.ai/oauth2/token";
+export declare const XAI_OAUTH_DEVICE_AUTHORIZATION_URL = "https://auth.x.ai/oauth2/device/code";
+export declare const XAI_OAUTH_DISCOVERY_URL = "https://auth.x.ai/.well-known/openid-configuration";
+export declare const XAI_OAUTH_CLIENT_ID = "b1a00492-073a-47ea-816f-4c329264a828";
+export declare const XAI_OAUTH_SCOPE = "openid profile email offline_access grok-cli:access api:access";
+export declare const XAI_REDIRECT_HOST = "127.0.0.1";
+export declare const XAI_REDIRECT_PORT = 56121;
+export declare const XAI_REDIRECT_PATH = "/callback";
+export declare const OPENAI_COMPAT_HOST = "127.0.0.1";
+export declare const OPENAI_COMPAT_PORT = 8787;
+export declare const REFRESH_SKEW_MS: number;
+export declare const USER_AGENT = "codex-xai-oauth/0.1.0";
+export declare function xaiBaseUrl(): string;
+//# sourceMappingURL=constants.d.ts.map

package/dist/xai/credentials.d.ts

@@ -0,0 +1,4 @@
+import type { CredentialStatus, XaiCredentials } from "./types.js";
+export declare function resolveXaiCredentials(): Promise<XaiCredentials>;
+export declare function credentialStatus(): Promise<CredentialStatus>;
+//# sourceMappingURL=credentials.d.ts.map

package/dist/xai/device-oauth.d.ts

@@ -0,0 +1,9 @@
+import type { DeviceCodeResponse, StoredAuth, TokenPayload } from "./types.js";
+export declare function requestDeviceCode(endpoint: string): Promise<DeviceCodeResponse>;
+export declare function pollDeviceToken(device: DeviceCodeResponse, tokenEndpoint: string): Promise<TokenPayload>;
+export declare function beginDeviceOAuth(): Promise<{
+    readonly complete: () => Promise<StoredAuth>;
+    readonly instructions: string;
+    readonly url: string;
+}>;
+//# sourceMappingURL=device-oauth.d.ts.map

package/dist/xai/guards.d.ts

@@ -0,0 +1,4 @@
+export declare function isRecord(value: unknown): value is Record<string, unknown>;
+export declare function stringField(record: Record<string, unknown>, key: string): string | undefined;
+export declare function numberField(record: Record<string, unknown>, key: string): number | undefined;
+//# sourceMappingURL=guards.d.ts.map

package/dist/xai/http.d.ts

@@ -0,0 +1,7 @@
+export declare function xaiRequest(path: string, options: {
+    readonly body?: Record<string, unknown>;
+    readonly headers?: Record<string, string>;
+    readonly method: "GET" | "POST";
+    readonly timeoutMs?: number;
+}): Promise<Response>;
+//# sourceMappingURL=http.d.ts.map

package/dist/xai/index.d.ts

@@ -0,0 +1,9 @@
+export { beginOAuth, startCallbackServer } from "./browser-oauth.js";
+export { credentialStatus, resolveXaiCredentials } from "./credentials.js";
+export { beginDeviceOAuth, pollDeviceToken, requestDeviceCode, } from "./device-oauth.js";
+export { xaiImageGenerate, xaiTts, xaiVideoGenerate } from "./media.js";
+export { buildAuthorizeUrl, discoverXaiOAuth, exchangeCodeForToken, pkcePair, refreshAccessToken, storedAuthFromToken, } from "./oauth.js";
+export { xaiChatCompletions, xaiResponses } from "./responses.js";
+export { authPath, defaultAuthPath, defaultGrokAuthPath, grokAuthPath, readGrokStoredAuth, readStoredAuth, writeStoredAuth, } from "./storage.js";
+export type { CredentialStatus, DeviceCodeResponse, OpenAiChatCompletionRequest, OpenAiChatMessage, ReasoningEffort, StoredAuth, XaiCredentials, XaiResponseResult, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/xai/media.d.ts

@@ -0,0 +1,35 @@
+export declare function xaiImageGenerate(args: {
+    readonly model?: string;
+    readonly n?: number;
+    readonly prompt: string;
+    readonly resolution?: "1k" | "2k";
+    readonly response_format?: "url" | "b64_json";
+    readonly size?: string;
+}): Promise<Record<string, unknown>>;
+export declare function xaiTts(args: {
+    readonly bit_rate?: number;
+    readonly codec?: string;
+    readonly format?: string;
+    readonly input: string;
+    readonly language?: string;
+    readonly sample_rate?: number;
+    readonly text_normalization?: boolean;
+    readonly voice?: string;
+    readonly voice_id?: string;
+}): Promise<{
+    readonly bytes: Buffer;
+    readonly contentType: string;
+}>;
+export declare function xaiVideoGenerate(args: {
+    readonly aspect_ratio?: string;
+    readonly duration?: number;
+    readonly image_url?: string;
+    readonly model?: string;
+    readonly prompt: string;
+    readonly reference_image_urls?: readonly string[];
+    readonly resolution?: "480p" | "720p";
+}, options?: {
+    readonly maxWaitMs?: number;
+    readonly pollIntervalMs?: number;
+}): Promise<Record<string, unknown>>;
+//# sourceMappingURL=media.d.ts.map

package/dist/xai/oauth.d.ts

@@ -0,0 +1,28 @@
+import type { StoredAuth, TokenPayload } from "./types.js";
+type Discovery = {
+    readonly authorization_endpoint: string;
+    readonly device_authorization_endpoint?: string;
+    readonly token_endpoint: string;
+};
+export declare function pkcePair(): {
+    readonly challenge: string;
+    readonly verifier: string;
+};
+export declare function buildAuthorizeUrl(args: {
+    readonly authorizationEndpoint: string;
+    readonly challenge: string;
+    readonly nonce: string;
+    readonly redirectUri: string;
+    readonly state: string;
+}): string;
+export declare function discoverXaiOAuth(): Promise<Discovery>;
+export declare function refreshAccessToken(refreshToken: string, tokenEndpoint: string): Promise<TokenPayload>;
+export declare function exchangeCodeForToken(input: {
+    readonly code: string;
+    readonly redirectUri: string;
+    readonly tokenEndpoint: string;
+    readonly verifier: string;
+}): Promise<StoredAuth>;
+export declare function storedAuthFromToken(token: TokenPayload, tokenEndpoint: string): StoredAuth;
+export {};
+//# sourceMappingURL=oauth.d.ts.map

package/dist/xai/responses.d.ts

@@ -0,0 +1,10 @@
+import type { OpenAiChatCompletionRequest, ReasoningEffort, XaiResponseResult } from "./types.js";
+export declare function xaiResponses(input: {
+    readonly model?: string;
+    readonly prompt: string;
+    readonly reasoningEffort?: ReasoningEffort;
+    readonly timeoutMs?: number;
+    readonly tools?: readonly Record<string, unknown>[];
+}): Promise<XaiResponseResult>;
+export declare function xaiChatCompletions(request: OpenAiChatCompletionRequest): Promise<Record<string, unknown>>;
+//# sourceMappingURL=responses.d.ts.map

package/dist/xai/storage.d.ts

@@ -0,0 +1,11 @@
+import type { StoredAuth } from "./types.js";
+export declare function defaultAuthPath(): string;
+export declare function authPath(): string;
+export declare function defaultGrokAuthPath(): string;
+export declare function grokAuthPath(): string;
+export declare function readStoredAuth(path?: string): StoredAuth | undefined;
+export declare function readGrokStoredAuth(path?: string): StoredAuth | undefined;
+export declare function writeStoredAuth(auth: StoredAuth, path?: string): void;
+export declare function oauthExpiry(timestampSeconds?: number): number;
+export declare function accessTokenIsExpiring(token: string | undefined, skewMs?: number): boolean;
+//# sourceMappingURL=storage.d.ts.map

package/dist/xai/types.d.ts

@@ -0,0 +1,58 @@
+export type StoredAuth = {
+    readonly access: string;
+    readonly expires: number;
+    readonly provider: "grok-oauth" | "xai-oauth";
+    readonly refresh: string;
+    readonly tokenEndpoint: string;
+    readonly tokenType: string;
+};
+export type XaiCredentials = {
+    readonly apiKey: string;
+    readonly baseUrl: string;
+    readonly provider: "codex-model-provider" | "grok-oauth" | "xai-oauth" | "xai";
+};
+export type CredentialStatus = {
+    readonly success: true;
+    readonly auth_file: string;
+    readonly base_url: string;
+    readonly codex_config_file?: string;
+    readonly credential_source: XaiCredentials["provider"];
+    readonly oauth_file_present: boolean;
+} | {
+    readonly success: false;
+    readonly auth_file: string;
+    readonly codex_config_file?: string;
+    readonly error: string;
+    readonly oauth_file_present: boolean;
+};
+export type ReasoningEffort = "low" | "medium" | "high";
+export type XaiResponseResult = {
+    readonly citations: unknown;
+    readonly inline_citations: readonly Record<string, unknown>[];
+    readonly payload: Record<string, unknown>;
+    readonly text: string;
+};
+export type DeviceCodeResponse = {
+    readonly device_code: string;
+    readonly expires_in?: number;
+    readonly interval?: number;
+    readonly user_code: string;
+    readonly verification_uri: string;
+    readonly verification_uri_complete?: string;
+};
+export type TokenPayload = {
+    readonly access_token?: string;
+    readonly expires_in?: number;
+    readonly refresh_token?: string;
+    readonly token_type?: string;
+};
+export type OpenAiChatMessage = {
+    readonly content?: unknown;
+    readonly role: string;
+};
+export type OpenAiChatCompletionRequest = {
+    readonly messages?: readonly OpenAiChatMessage[];
+    readonly model?: string;
+    readonly stream?: boolean;
+};
+//# sourceMappingURL=types.d.ts.map

package/package.json

@@ -0,0 +1,58 @@
+{
+  "name": "codex-xai-oauth",
+  "version": "0.1.0",
+  "description": "Codex plugin exposing xAI/Grok OAuth and API-key tools through a local MCP server.",
+  "type": "module",
+  "main": "./dist/mcp/server.js",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/islee23520/codex-xai-oauth.git"
+  },
+  "homepage": "https://github.com/islee23520/codex-xai-oauth#readme",
+  "bugs": {
+    "url": "https://github.com/islee23520/codex-xai-oauth/issues"
+  },
+  "bin": {
+    "codex-xai-oauth": "./dist/cli.js"
+  },
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\"",
+    "setup": "npm run build && node dist/cli.js setup",
+    "doctor": "npm run build && node dist/cli.js doctor",
+    "test": "tsx --test test/*.test.ts",
+    "typecheck": "tsc --noEmit",
+    "build": "npm run clean && npm run build:types && npm run build:bundle",
+    "build:types": "tsc -p tsconfig.build.json --emitDeclarationOnly",
+    "build:bundle": "esbuild src/mcp/server.ts --bundle --platform=node --format=esm --target=node20 --outfile=dist/mcp/server.js --sourcemap && esbuild src/cli.ts --bundle --platform=node --format=esm --target=node20 --outfile=dist/cli.js --sourcemap",
+    "lint": "biome check .",
+    "lint:fix": "biome check --write .",
+    "format": "biome format --write .",
+    "prepare": "npm run build",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "codex",
+    "mcp",
+    "xai",
+    "grok",
+    "oauth",
+    "image-generation"
+  ],
+  "author": {
+    "name": "ilseoblee"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "commander": "^15.0.0",
+    "ky": "^2.0.2",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "2.4.16",
+    "@types/node": "^25.0.0",
+    "esbuild": "^0.27.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3"
+  }
+}

package/skills/xai-grok/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: xai-grok
+description: Use xAI/Grok OAuth or API-key MCP tools for text generation, web search, X search, image generation, TTS, video generation, or credential status from Codex.
+---
+
+# xAI Grok
+
+Use the bundled MCP tools when the user asks for xAI, Grok, Grok Imagine, xAI image generation, xAI web search, X search, TTS, video generation, or xAI credential status.
+
+## Tools
+
+- `xai_status`: check whether OAuth or `XAI_API_KEY` credentials are available. Never expose token material.
+- `xai_login_instructions`: show local setup commands and the auth-file path.
+- `xai_generate_text`: generate text with Grok through xAI Responses.
+- `xai_web_search`: answer with xAI server-side web search.
+- `xai_x_search`: answer with xAI server-side X search. Do not pass both allowed and excluded handles.
+- `xai_image_generate`: generate images with xAI `/images/generations`.
+- `xai_tts`: generate speech audio.
+- `xai_video_generate`: generate video.
+
+## Credential Rules
+
+- Prefer existing OAuth credentials in `~/.config/codex-xai-oauth/auth.json`.
+- If package OAuth credentials are absent, use the Grok CLI OIDC session in `~/.grok/auth.json`.
+- `CODEX_XAI_OAUTH_AUTH_FILE` overrides the auth-file path.
+- `CODEX_XAI_OAUTH_GROK_AUTH_FILE` overrides the Grok CLI auth-file path.
+- `XAI_API_KEY` is the fallback credential.
+- `XAI_BASE_URL` can override the API base URL.
+- Do not print, quote, summarize, or store access tokens, refresh tokens, or API keys in chat.
+
+## Setup
+
+For OAuth device flow:
+
+```bash
+codex-xai-oauth login --device
+```
+
+For API-key fallback:
+
+```bash
+export XAI_API_KEY=xai-...
+```
+
+To check status:
+
+```bash
+codex-xai-oauth status
+```