dsh-coding-subscription-oauth 0.5.0

package/src/provider.ts

@@ -0,0 +1,128 @@
+/**
+ * Grok Build provider: a pi-ai provider pointed at the official Grok CLI
+ * coding backend (`cli-chat-proxy.grok.com`) carrying the CLI fingerprint
+ * headers the risk-control middleware requires.
+ * @module dsh-coding-subscription-oauth/provider
+ */
+
+import type { Api, Model, Provider, ThinkingLevelMap } from "@earendil-works/pi-ai";
+import { createProvider } from "@earendil-works/pi-ai";
+import { openAIResponsesApi } from "@earendil-works/pi-ai/api/openai-responses.lazy";
+import { GROK_BUILD_ROUTE } from "./ids.ts";
+
+/**
+ * Grok Build cannot disable reasoning (`reasoning_effort: "none"` is 400).
+ * pi-ai treats an absent `xhigh`/`max` key as unsupported, so those levels
+ * must be declared explicitly when the model offers them.
+ */
+export function grokBuildReasoningMap(levels: readonly ("low" | "medium" | "high" | "xhigh")[]): ThinkingLevelMap {
+	const offered = new Set(levels);
+	return {
+		off: null,
+		minimal: null,
+		low: offered.has("low") ? "low" : null,
+		medium: offered.has("medium") ? "medium" : null,
+		high: offered.has("high") ? "high" : null,
+		xhigh: offered.has("xhigh") ? "xhigh" : null,
+		max: null,
+	};
+}
+
+/** Inference backend base URL (Responses API lives under `${baseUrl}/responses`). */
+export const GROK_BUILD_BASE_URL = "https://cli-chat-proxy.grok.com/v1";
+
+/** Account model catalog endpoint fetched by the official CLI. */
+export const GROK_BUILD_MODELS_URL = `${GROK_BUILD_BASE_URL}/models-v2`;
+
+/**
+ * Official Grok CLI version this plugin fingerprints as.
+ * Track the `@xai-official/grok` npm release stream; make overridable via
+ * GROK_BUILD_CLIENT_VERSION for urgent drift fixes without a release.
+ */
+export const GROK_CLIENT_VERSION: string = process.env["GROK_BUILD_CLIENT_VERSION"] ?? "0.1.220";
+
+/**
+ * Fingerprint headers required by the Grok Build middleware. Missing headers
+ * are a known 403 trigger (codex-app-transfer field notes, 2026-07).
+ */
+export function grokBuildFingerprintHeaders(): Record<string, string> {
+	return {
+		"X-XAI-Token-Auth": "xai-grok-cli",
+		"x-grok-client-identifier": "grok-shell",
+		"x-grok-client-version": GROK_CLIENT_VERSION,
+		"User-Agent": `grok-shell/${GROK_CLIENT_VERSION}`,
+	};
+}
+
+/** Static baseline catalog, used until a live `/models-v2` listing succeeds. */
+export function grokBuildBaselineModels(): Model<"openai-responses">[] {
+	return [
+		{
+			id: "grok-4.5",
+			name: "Grok 4.5",
+			api: "openai-responses",
+			provider: GROK_BUILD_ROUTE,
+			baseUrl: GROK_BUILD_BASE_URL,
+			reasoning: true,
+			// Official xAI docs + live /models-v2: grok-4.5 is low/medium/high only.
+			thinkingLevelMap: grokBuildReasoningMap(["low", "medium", "high"]),
+			input: ["text", "image"],
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+			contextWindow: 500_000,
+			maxTokens: 128_000,
+		},
+		{
+			id: "grok-4.6",
+			name: "Grok 4.6",
+			api: "openai-responses",
+			provider: GROK_BUILD_ROUTE,
+			baseUrl: GROK_BUILD_BASE_URL,
+			reasoning: true,
+			// grok-4.6 and later advertise xhigh. pi-ai hides xhigh unless this key
+			// is an explicit non-null mapping (absent !== supported).
+			thinkingLevelMap: grokBuildReasoningMap(["low", "medium", "high", "xhigh"]),
+			input: ["text", "image"],
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+			contextWindow: 500_000,
+			maxTokens: 128_000,
+		},
+		{
+			id: "grok-composer-2.5-fast",
+			name: "Grok Composer 2.5 Fast",
+			api: "openai-responses",
+			provider: GROK_BUILD_ROUTE,
+			baseUrl: GROK_BUILD_BASE_URL,
+			reasoning: false,
+			input: ["text"],
+			cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+			contextWindow: 200_000,
+			maxTokens: 64_000,
+		},
+	];
+}
+
+/**
+ * Build the Grok Build pi-ai provider. Auth is apiKey-shaped: the OAuth
+ * access token is injected as the bearer key by the surrounding adapter
+ * (`Models.getAuth` on the login provider performs refresh under the store
+ * lock before the key ever reaches here).
+ */
+export function grokBuildProvider(models: readonly Model<Api>[]): Provider {
+	return createProvider({
+		id: GROK_BUILD_ROUTE,
+		name: "xAI Grok Build",
+		baseUrl: GROK_BUILD_BASE_URL,
+		headers: grokBuildFingerprintHeaders(),
+		auth: {
+			apiKey: {
+				name: "Grok Build OAuth access token",
+				async resolve({ credential }) {
+					const apiKey = credential?.key;
+					return apiKey === undefined || apiKey.length === 0 ? undefined : { auth: { apiKey }, source: "OAuth" };
+				},
+			},
+		},
+		models,
+		api: { "openai-responses": openAIResponsesApi() },
+	});
+}

package/src/proxy.ts

@@ -0,0 +1,99 @@
+/**
+ * Scoped egress proxy for coding-subscription OAuth and inference traffic.
+ * @module dsh-coding-subscription-oauth/proxy
+ */
+
+import { Dispatcher, getGlobalDispatcher, ProxyAgent, setGlobalDispatcher } from "undici";
+
+const DEFAULT_PROXIED_HOSTS = [
+	"auth.x.ai",
+	"cli-chat-proxy.grok.com",
+	"auth.openai.com",
+	"chatgpt.com",
+	"claude.ai",
+	"platform.claude.com",
+	"api.anthropic.com",
+	"accounts.google.com",
+	"oauth2.googleapis.com",
+	"cloudcode-pa.googleapis.com",
+	"www.googleapis.com",
+] as const;
+
+const KIMI_PROXIED_HOSTS = ["auth.kimi.com", "api.kimi.com"] as const;
+
+class CodingOAuthDispatcher extends Dispatcher {
+	constructor(
+		private readonly proxied: Dispatcher,
+		private readonly fallback: Dispatcher,
+		private readonly hosts: ReadonlySet<string>,
+	) {
+		super();
+	}
+
+	dispatch(options: Dispatcher.DispatchOptions, handler: Dispatcher.DispatchHandler): boolean {
+		const origin = options.origin;
+		const host = origin instanceof URL ? origin.hostname : typeof origin === "string" ? new URL(origin).hostname : "";
+		if (this.hosts.has(host)) return this.proxied.dispatch(options, handler);
+		return this.fallback.dispatch(options, handler);
+	}
+
+	override async close(): Promise<void> {
+		await this.proxied.close();
+	}
+
+	override async destroy(): Promise<void> {
+		await this.proxied.destroy();
+	}
+}
+
+let installedProxy: string | undefined;
+let installed = false;
+
+function firstEnv(names: readonly string[]): string | undefined {
+	for (const name of names) {
+		const value = process.env[name];
+		if (value !== undefined && value.length > 0) return value;
+	}
+	return undefined;
+}
+
+export interface CodingOAuthProxyOptions {
+	proxyKimi?: boolean;
+}
+
+/** Install one process-wide dispatcher that proxies only the audited host list. */
+export function ensureCodingOAuthProxy(explicit?: string, options: CodingOAuthProxyOptions = {}): string | undefined {
+	if (installed) return installedProxy;
+	const url =
+		explicit ??
+		firstEnv(["CODING_OAUTH_PROXY", "GROK_BUILD_PROXY", "HTTPS_PROXY", "https_proxy", "HTTP_PROXY", "http_proxy"]);
+	if (url === undefined) return undefined;
+	const hosts = new Set<string>(DEFAULT_PROXIED_HOSTS);
+	if (options.proxyKimi === true) {
+		for (const host of KIMI_PROXIED_HOSTS) hosts.add(host);
+	}
+	const fallback = getGlobalDispatcher();
+	setGlobalDispatcher(new CodingOAuthDispatcher(new ProxyAgent(url), fallback, hosts));
+	installed = true;
+	installedProxy = url;
+	return url;
+}
+
+/** Backward-compatible name retained for existing callers. */
+export function ensureGrokBuildProxy(explicit?: string): string | undefined {
+	return ensureCodingOAuthProxy(explicit);
+}
+
+export function codingOAuthProxyInEffect(): string | undefined {
+	return installedProxy;
+}
+
+/** Appended to Grok discovery/token/catalog transport errors when a scoped proxy is installed. */
+export function codingOAuthProxyUnreachableHint(): string {
+	return installedProxy === undefined ? "" : "; check that CODING_OAUTH_PROXY is reachable";
+}
+
+/** Backward-compatible status accessor. */
+export function grokBuildProxyInEffect(): string | undefined {
+	return codingOAuthProxyInEffect();
+}

package/src/redact.ts

@@ -0,0 +1,72 @@
+/** Remove token-like strings from an external OAuth diagnostic. */
+
+/**
+ * An opaque credential value run. We require the surrounding label to be one of
+ * the known credential field names AND the value to be at least this many
+ * characters so that ordinary prose ("code is fun", "token missing") is left
+ * alone. The minimum also keeps the regex from matching in code-style
+ * strings like `code: a`.
+ */
+const OPAQUE_TOKEN_MIN_LENGTH = 16;
+
+/** The opaque-value class: at least the minimum chars of URL-safe alphabet. */
+const OPAQUE_TOKEN_RUN = `[A-Za-z0-9_\\-.+]{${OPAQUE_TOKEN_MIN_LENGTH},}`;
+
+/** Known sensitive field names that may precede an opaque credential value. */
+const SENSITIVE_LABEL =
+	"(?:token|bearer|code|user_code|access_token|refresh_token|id_token|api[_-]?key|secret|password|client[_-]?secret|authorization)";
+
+/**
+ * Sweep additional opaque tokens that follow a known credential label. We
+ * require the value to be long and URL-safe-shaped so that ordinary prose
+ * ("code is fun", "token missing") is left alone. This complements the short
+ * and structured sweep above — it catches longer opaque tokens that survive
+ * the more specific regexes.
+ */
+function redactOpaqueTokens(input: string): string {
+	let output = input.replace(
+		new RegExp(`(["']?${SENSITIVE_LABEL}["']?\\s*:\\s*["'])(${OPAQUE_TOKEN_RUN})(["'])`, "giu"),
+		`$1[redacted]$3`,
+	);
+	output = output.replace(
+		new RegExp(`\\b(${SENSITIVE_LABEL})=(${OPAQUE_TOKEN_RUN})(?=[&\\s"']|$)`, "giu"),
+		`$1=[redacted]`,
+	);
+	output = output.replace(
+		new RegExp(`\\b(${SENSITIVE_LABEL}\\s*:\\s*)(${OPAQUE_TOKEN_RUN})(?=[\\s"',}]|$)`, "giu"),
+		`$1[redacted]`,
+	);
+	output = output.replace(new RegExp(`\\b(Authorization)\\s+(${OPAQUE_TOKEN_RUN})\\b`, "giu"), `$1 [redacted]`);
+	return output;
+}
+
+/** Strip userinfo from a proxy URL so CLI/logs never print `user:pass@`. */
+export function redactProxyUrl(value: string): string {
+	try {
+		const parsed = new URL(value);
+		if (parsed.username === "" && parsed.password === "") return value;
+		parsed.username = "";
+		parsed.password = "";
+		const href = parsed.href;
+		if (!value.endsWith("/") && href.endsWith("/") && parsed.pathname === "/") return href.slice(0, -1);
+		return href;
+	} catch {
+		return value.replace(/^([a-z][a-z0-9+.-]*:\/\/)[^/@\s]+@/iu, "$1");
+	}
+}
+
+export function safeMessage(error: unknown): string {
+	let text = (error instanceof Error ? error.message : String(error))
+		.replace(/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/gu, "[redacted token]")
+		.replace(/\bsk-ant-oat[A-Za-z0-9_-]*\b/giu, "[redacted token]")
+		.replace(/\bsk-[A-Za-z0-9_-]{16,}\b/gu, "[redacted token]")
+		.replace(/\bxai-[A-Za-z0-9._-]{8,}\b/gu, "[redacted token]")
+		.replace(/(\bBearer\s+)[^\s"',}]+/giu, "$1[redacted]")
+		.replace(/(\b(?:code|user_code|token|id_token|refresh_token|access_token)=)[^&\s]+/giu, "$1[redacted]")
+		.replace(/(["']?(?:code|user_code|id_token|refresh_token|access_token)["']?\s*:\s*["'])[^"']+/giu, "$1[redacted]");
+	// Generic opaque sweep catches long values preceded by labels such as
+	// client_secret, api_key, password, or Authorization. The minimum length
+	// guards against ordinary prose and the case-insensitive pass handles repeats.
+	text = redactOpaqueTokens(text);
+	return text.slice(0, 1000);
+}

package/src/session.ts

@@ -0,0 +1,218 @@
+/**
+ * Shared OAuth store + live catalog for the host plugin and CLI.
+ * @module dsh-coding-subscription-oauth/session
+ */
+
+import { mkdir, readFile, rm } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { writeFileAtomic } from "@deepseek-ai/dsh-atomic-write";
+import { resolveDshHome } from "@deepseek-ai/dsh-home-paths";
+import type { Api, Model, MutableModels, Provider } from "@earendil-works/pi-ai";
+import { createModels } from "@earendil-works/pi-ai";
+import { xaiProvider } from "@earendil-works/pi-ai/providers/xai";
+import {
+	type CatalogSource,
+	fetchLiveModels,
+	type LiveModelDescriptor,
+	materializeLiveModel,
+	mergeLiveCatalog,
+} from "./catalog.ts";
+import { GROK_BUILD_MODELS_CACHE_FILENAME, GROK_BUILD_ROUTE, XAI_PI_PROVIDER } from "./ids.ts";
+import { grokBuildBaselineModels, grokBuildProvider } from "./provider.ts";
+import { safeMessage } from "./redact.ts";
+import { GrokBuildCredentialStore } from "./store.ts";
+
+const MODELS_CACHE_VERSION = 2;
+
+interface ModelsCacheDocument {
+	version: typeof MODELS_CACHE_VERSION;
+	ids: string[];
+	selected?: string[];
+	fetchedAt: number;
+}
+
+interface ParsedCache {
+	ids: string[];
+	selected?: string[];
+}
+
+function isENOENT(error: unknown): boolean {
+	return (error as NodeJS.ErrnoException | null)?.code === "ENOENT";
+}
+
+function modelsCachePath(dshHome?: string): string {
+	return resolve(join(resolveDshHome(dshHome), GROK_BUILD_MODELS_CACHE_FILENAME));
+}
+
+function parseIdList(value: unknown): string[] {
+	if (!Array.isArray(value)) return [];
+	return [...new Set(value.filter((id): id is string => typeof id === "string" && id.length > 0))];
+}
+
+function parseCache(text: string): ParsedCache | undefined {
+	let value: unknown;
+	try {
+		value = JSON.parse(text);
+	} catch {
+		return undefined;
+	}
+	if (typeof value !== "object" || value === null || Array.isArray(value)) return undefined;
+	const document = value as Record<string, unknown>;
+	if (document["version"] !== 1 && document["version"] !== MODELS_CACHE_VERSION) return undefined;
+	const ids = parseIdList(document["ids"]);
+	const selected = parseIdList(document["selected"]);
+	if (ids.length === 0 && selected.length === 0) return undefined;
+	return {
+		ids,
+		...(selected.length === 0 ? {} : { selected }),
+	};
+}
+
+function asHarnessModels(models: readonly Model<Api>[]): Model<Api>[] {
+	return models.map((model) =>
+		model.provider === GROK_BUILD_ROUTE ? model : { ...model, provider: GROK_BUILD_ROUTE },
+	);
+}
+
+/** One process-local owner of the credential and the account model list. */
+export class GrokBuildSession {
+	readonly store: GrokBuildCredentialStore;
+	readonly models: MutableModels;
+	private readonly baselineCatalog: readonly Model<Api>[];
+	private liveIds: string[] | undefined;
+	private liveModels: readonly LiveModelDescriptor[] | undefined;
+	private selectedIds: string[] | undefined;
+	private source: CatalogSource = "fallback";
+	private listingError: string | undefined;
+	private readonly cacheFile: string;
+	private onCatalogChange: (() => void) | undefined;
+
+	constructor(store: GrokBuildCredentialStore = new GrokBuildCredentialStore(), onCatalogChange?: () => void) {
+		this.store = store;
+		this.cacheFile = modelsCachePath();
+		this.baselineCatalog = grokBuildBaselineModels();
+		// The built-in xai provider owns login/refresh (device flow today); the
+		// credential lives in this plugin's own file via the store above.
+		this.models = createModels({ credentials: store });
+		this.models.setProvider(xaiProvider());
+		this.onCatalogChange = onCatalogChange;
+	}
+
+	/** Secret-free listing diagnostic from the last refresh. */
+	get catalogError(): string | undefined {
+		return this.listingError;
+	}
+
+	get catalogSource(): CatalogSource {
+		return this.source;
+	}
+
+	availableModels(): Model<Api>[] {
+		return mergeLiveCatalog(this.baselineCatalog, this.liveIds, this.liveModels);
+	}
+
+	selectedModelIds(): string[] | undefined {
+		return this.selectedIds;
+	}
+
+	visibleModels(): Model<Api>[] {
+		const available = this.availableModels();
+		if (this.selectedIds === undefined || this.selectedIds.length === 0) return available;
+		const byId = new Map(available.map((model) => [model.id, model]));
+		return this.selectedIds.map((id) => byId.get(id) ?? materializeLiveModel(id, this.baselineCatalog));
+	}
+
+	/** Provider whose id matches the harness route so PiAiAdapter can list models. */
+	provider(): Provider {
+		const visible = this.visibleModels();
+		const base = grokBuildProvider(visible);
+		return {
+			...base,
+			getModels: () => asHarnessModels(this.visibleModels()),
+		};
+	}
+
+	async loadCachedCatalog(): Promise<void> {
+		try {
+			const cache = parseCache(await readFile(this.cacheFile, "utf8"));
+			if (cache === undefined) return;
+			if (cache.ids.length > 0) {
+				this.liveIds = cache.ids;
+				this.liveModels = undefined;
+				this.source = "cache";
+			}
+			this.selectedIds = cache.selected;
+		} catch (error) {
+			if (!isENOENT(error)) throw error;
+		}
+	}
+
+	async refreshLiveCatalog(signal?: AbortSignal): Promise<void> {
+		try {
+			const auth = await this.models.getAuth(XAI_PI_PROVIDER);
+			const access = auth?.auth.apiKey;
+			if (access === undefined || access.length === 0) {
+				this.listingError = undefined;
+				return;
+			}
+			const live = await fetchLiveModels(access, signal);
+			this.liveIds = live.map((model) => model.id);
+			this.liveModels = live;
+			this.source = "live";
+			this.listingError = undefined;
+			await this.writeCache();
+		} catch (error) {
+			this.listingError = safeMessage(error);
+			if (this.liveIds === undefined) this.source = "fallback";
+		} finally {
+			// Login must reveal the fallback catalog even when auth refresh or live listing fails.
+			this.onCatalogChange?.();
+		}
+	}
+
+	async setSelectedModels(ids: readonly string[]): Promise<void> {
+		const unique = [...new Set(ids.filter((id) => id.length > 0))];
+		this.selectedIds = unique.length === 0 ? undefined : unique;
+		await this.writeCache();
+		this.onCatalogChange?.();
+	}
+
+	/**
+	 * Backdate the stored token's expiry so the next `getAuth()` refreshes.
+	 * Called after an upstream 401 rejected a locally-valid token.
+	 */
+	async invalidateAccessToken(): Promise<void> {
+		await this.store.invalidate(XAI_PI_PROVIDER);
+	}
+
+	async logout(): Promise<void> {
+		try {
+			await this.store.delete(XAI_PI_PROVIDER);
+			this.liveIds = undefined;
+			this.liveModels = undefined;
+			this.selectedIds = undefined;
+			this.source = "fallback";
+			this.listingError = undefined;
+			await mkdir(dirname(this.cacheFile), { recursive: true, mode: 0o700 });
+			await rm(this.cacheFile, { force: true });
+		} finally {
+			// Credential deletion may succeed before cache cleanup fails. Always
+			// refresh discovery so an open selector cannot retain stale models.
+			this.onCatalogChange?.();
+		}
+	}
+
+	private async writeCache(): Promise<void> {
+		const document: ModelsCacheDocument = {
+			version: MODELS_CACHE_VERSION,
+			ids: this.liveIds === undefined ? [] : [...this.liveIds],
+			fetchedAt: Date.now(),
+			...(this.selectedIds === undefined ? {} : { selected: [...this.selectedIds] }),
+		};
+		await mkdir(dirname(this.cacheFile), { recursive: true, mode: 0o700 });
+		await writeFileAtomic(this.cacheFile, `${JSON.stringify(document)}\n`, {
+			mode: 0o600,
+			dirMode: 0o700,
+		});
+	}
+}