dsh-coding-subscription-oauth 0.5.0

package/src/gateway-parse.ts

@@ -0,0 +1,224 @@
+/**
+ * Parse OpenAI / Anthropic request bodies into the gateway completion shape.
+ * @module dsh-coding-subscription-oauth/gateway-parse
+ */
+
+import { GatewayRequestError } from "./gateway-backend.ts";
+import type { GatewayChatMessage, GatewayCompletionRequest, GatewayTool, GatewayToolCall } from "./gateway-protocol.ts";
+
+export function parseOpenAiChatRequest(payload: Record<string, unknown>): GatewayCompletionRequest {
+	const model = requiredModel(payload["model"]);
+	const tools = parseOpenAiTools(payload["tools"]);
+	const reasoning = reasoningOf(payload);
+	return {
+		model,
+		messages: parseOpenAiMessages(payload["messages"]),
+		...(tools === undefined ? {} : { tools }),
+		...(reasoning === undefined ? {} : { reasoning }),
+	};
+}
+
+export function parseOpenAiResponsesRequest(payload: Record<string, unknown>): GatewayCompletionRequest {
+	const model = requiredModel(payload["model"]);
+	const input = payload["input"];
+	if (typeof input === "string") {
+		return { model, messages: [{ role: "user", content: input }] };
+	}
+	if (Array.isArray(input)) {
+		const tools = parseOpenAiTools(payload["tools"]);
+		const reasoning = reasoningOf(payload);
+		return {
+			model,
+			messages: parseOpenAiMessages(input),
+			...(tools === undefined ? {} : { tools }),
+			...(reasoning === undefined ? {} : { reasoning }),
+		};
+	}
+	throw new GatewayRequestError(400, "invalid_request", "input must be a string or message array");
+}
+
+export function parseAnthropicMessagesRequest(payload: Record<string, unknown>): GatewayCompletionRequest {
+	const model = requiredModel(payload["model"]);
+	const messages = parseAnthropicMessages(payload["messages"]);
+	const system = payload["system"];
+	if (typeof system === "string" && system.length > 0) {
+		messages.unshift({ role: "system", content: system });
+	}
+	const tools = parseAnthropicTools(payload["tools"]);
+	const reasoning = reasoningOf(payload);
+	return {
+		model,
+		messages,
+		...(tools === undefined ? {} : { tools }),
+		...(reasoning === undefined ? {} : { reasoning }),
+	};
+}
+
+export function anthropicMaxTokens(payload: Record<string, unknown>): number {
+	const value = payload["max_tokens"];
+	if (typeof value === "number" && Number.isSafeInteger(value) && value > 0) return Math.min(value, 32_768);
+	return 4096;
+}
+
+function requiredModel(value: unknown): string {
+	if (typeof value !== "string" || value.length === 0) {
+		throw new GatewayRequestError(400, "invalid_request", "model is required");
+	}
+	return value;
+}
+
+function reasoningOf(payload: Record<string, unknown>): string | undefined {
+	if (typeof payload["reasoning_effort"] === "string") return payload["reasoning_effort"];
+	if (typeof payload["reasoning"] === "string") return payload["reasoning"];
+	return undefined;
+}
+
+function parseOpenAiMessages(value: unknown): GatewayChatMessage[] {
+	if (!Array.isArray(value) || value.length === 0) {
+		throw new GatewayRequestError(400, "invalid_request", "messages must be a non-empty array");
+	}
+	return value.map((item) => {
+		if (typeof item !== "object" || item === null) {
+			throw new GatewayRequestError(400, "invalid_request", "message must be an object");
+		}
+		const record = item as Record<string, unknown>;
+		const role = record["role"];
+		if (typeof role !== "string")
+			throw new GatewayRequestError(400, "invalid_request", "message role must be a string");
+		const toolCalls = parseToolCalls(record["tool_calls"]);
+		return {
+			role,
+			content: contentToString(record["content"]),
+			...(toolCalls === undefined ? {} : { tool_calls: toolCalls }),
+			...(typeof record["reasoning_content"] === "string" ? { reasoning_content: record["reasoning_content"] } : {}),
+			...(typeof record["tool_call_id"] === "string" ? { tool_call_id: record["tool_call_id"] } : {}),
+			...(typeof record["name"] === "string" ? { tool_name: record["name"] } : {}),
+		};
+	});
+}
+
+function parseAnthropicMessages(value: unknown): GatewayChatMessage[] {
+	if (!Array.isArray(value) || value.length === 0) {
+		throw new GatewayRequestError(400, "invalid_request", "messages must be a non-empty array");
+	}
+	const mapped: GatewayChatMessage[] = [];
+	for (const item of value) {
+		if (typeof item !== "object" || item === null) {
+			throw new GatewayRequestError(400, "invalid_request", "message must be an object");
+		}
+		const record = item as Record<string, unknown>;
+		const role = record["role"];
+		if (role !== "user" && role !== "assistant") {
+			throw new GatewayRequestError(400, "invalid_request", "anthropic message role must be user or assistant");
+		}
+		const blocks = Array.isArray(record["content"]) ? record["content"] : [{ type: "text", text: record["content"] }];
+		const texts: string[] = [];
+		const toolCalls: GatewayToolCall[] = [];
+		let reasoning: string | undefined;
+		for (const block of blocks) {
+			if (typeof block !== "object" || block === null) continue;
+			const entry = block as Record<string, unknown>;
+			if (entry["type"] === "text" && typeof entry["text"] === "string") texts.push(entry["text"]);
+			if (entry["type"] === "thinking" && typeof entry["thinking"] === "string") reasoning = entry["thinking"];
+			if (entry["type"] === "tool_use" && typeof entry["id"] === "string" && typeof entry["name"] === "string") {
+				toolCalls.push({
+					id: entry["id"],
+					name: entry["name"],
+					arguments: typeof entry["input"] === "string" ? entry["input"] : JSON.stringify(entry["input"] ?? {}),
+				});
+			}
+			if (entry["type"] === "tool_result" && typeof entry["tool_use_id"] === "string") {
+				mapped.push({
+					role: "tool",
+					content: typeof entry["content"] === "string" ? entry["content"] : JSON.stringify(entry["content"] ?? ""),
+					tool_call_id: entry["tool_use_id"],
+				});
+			}
+		}
+		mapped.push({
+			role,
+			content: texts.join(""),
+			...(toolCalls.length === 0 ? {} : { tool_calls: toolCalls }),
+			...(reasoning === undefined ? {} : { reasoning_content: reasoning }),
+		});
+	}
+	return mapped;
+}
+
+function parseOpenAiTools(value: unknown): GatewayTool[] | undefined {
+	if (!Array.isArray(value) || value.length === 0) return undefined;
+	const tools: GatewayTool[] = [];
+	for (const item of value) {
+		if (typeof item !== "object" || item === null) continue;
+		const record = item as Record<string, unknown>;
+		const fn =
+			typeof record["function"] === "object" && record["function"] !== null
+				? (record["function"] as Record<string, unknown>)
+				: record;
+		if (typeof fn["name"] !== "string") continue;
+		tools.push({
+			name: fn["name"],
+			description: typeof fn["description"] === "string" ? fn["description"] : "",
+			parameters:
+				typeof fn["parameters"] === "object" && fn["parameters"] !== null
+					? (fn["parameters"] as Record<string, unknown>)
+					: {},
+		});
+	}
+	return tools.length === 0 ? undefined : tools;
+}
+
+function parseAnthropicTools(value: unknown): GatewayTool[] | undefined {
+	if (!Array.isArray(value) || value.length === 0) return undefined;
+	const tools: GatewayTool[] = [];
+	for (const item of value) {
+		if (typeof item !== "object" || item === null) continue;
+		const record = item as Record<string, unknown>;
+		if (typeof record["name"] !== "string") continue;
+		tools.push({
+			name: record["name"],
+			description: typeof record["description"] === "string" ? record["description"] : "",
+			parameters:
+				typeof record["input_schema"] === "object" && record["input_schema"] !== null
+					? (record["input_schema"] as Record<string, unknown>)
+					: {},
+		});
+	}
+	return tools.length === 0 ? undefined : tools;
+}
+
+function parseToolCalls(value: unknown): GatewayToolCall[] | undefined {
+	if (!Array.isArray(value) || value.length === 0) return undefined;
+	const calls: GatewayToolCall[] = [];
+	for (const item of value) {
+		if (typeof item !== "object" || item === null) continue;
+		const record = item as Record<string, unknown>;
+		const fn =
+			typeof record["function"] === "object" && record["function"] !== null
+				? (record["function"] as Record<string, unknown>)
+				: record;
+		if (typeof record["id"] !== "string" || typeof fn["name"] !== "string") continue;
+		calls.push({
+			id: record["id"],
+			name: fn["name"],
+			arguments: typeof fn["arguments"] === "string" ? fn["arguments"] : JSON.stringify(fn["arguments"] ?? {}),
+		});
+	}
+	return calls.length === 0 ? undefined : calls;
+}
+
+function contentToString(value: unknown): string {
+	if (typeof value === "string") return value;
+	if (Array.isArray(value)) {
+		return value
+			.map((part) => {
+				if (typeof part === "string") return part;
+				if (typeof part === "object" && part !== null && typeof (part as { text?: unknown }).text === "string") {
+					return (part as { text: string }).text;
+				}
+				return "";
+			})
+			.join("");
+	}
+	return "";
+}

package/src/gateway-protocol.ts

@@ -0,0 +1,52 @@
+/**
+ * Shared request/stream types for the local coding-subscription gateway.
+ * @module dsh-coding-subscription-oauth/gateway-protocol
+ */
+
+export interface GatewayToolCall {
+	id: string;
+	name: string;
+	arguments: string;
+}
+
+export interface GatewayTool {
+	name: string;
+	description: string;
+	parameters: Record<string, unknown>;
+}
+
+export interface GatewayChatMessage {
+	role: string;
+	content: string;
+	tool_calls?: readonly GatewayToolCall[];
+	reasoning_content?: string;
+	tool_call_id?: string;
+	tool_name?: string;
+}
+
+export interface GatewayCompletionRequest {
+	model: string;
+	messages: readonly GatewayChatMessage[];
+	tools?: readonly GatewayTool[];
+	reasoning?: string;
+}
+
+export type GatewayStreamPart =
+	| { type: "text"; text: string }
+	| { type: "thinking"; text: string }
+	| { type: "tool_call"; index: number; id: string; name: string; arguments: string }
+	| { type: "done"; finish: "stop" | "tool_calls" | "length" };
+
+export type GatewayThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+
+export function isThinkingLevel(value: string): value is GatewayThinkingLevel {
+	return (
+		value === "off" ||
+		value === "minimal" ||
+		value === "low" ||
+		value === "medium" ||
+		value === "high" ||
+		value === "xhigh" ||
+		value === "max"
+	);
+}

package/src/gateway-routes.ts

@@ -0,0 +1,152 @@
+/**
+ * Settings-facing routes for the opt-in local API gateway.
+ * @module dsh-coding-subscription-oauth/gateway-routes
+ */
+
+import type { IncomingMessage, ServerResponse } from "node:http";
+import type { CodingOAuthGatewayController } from "./gateway.ts";
+import { assertGatewayPort } from "./gateway-config.ts";
+import { readJsonRequest, requestErrorStatus } from "./http-json.ts";
+import { safeMessage } from "./redact.ts";
+import { isTrustedLoopbackWebRequest } from "./web-origin.ts";
+import { registerWebRouteSetupAtomically } from "./web-routes.ts";
+
+export const GATEWAY_SETTINGS_PATH = "/plugins/dsh-grok-build/gateway";
+export const GATEWAY_REVEAL_PATH = "/plugins/dsh-grok-build/gateway/reveal";
+export const GATEWAY_ROTATE_PATH = "/plugins/dsh-grok-build/gateway/rotate";
+
+export interface GatewayRouteContext {
+	readonly webServer: {
+		register(route: {
+			kind: "exact" | "prefix";
+			path: string;
+			handler: (req: IncomingMessage, res: ServerResponse) => void | Promise<void>;
+		}): () => void;
+	};
+	effect(callback: () => () => void | Promise<void>, label?: string): unknown;
+}
+
+export function registerGatewayRoutes(ctx: GatewayRouteContext, controller: CodingOAuthGatewayController): () => void {
+	let dispose = (): void => undefined;
+	ctx.effect(() => {
+		dispose = registerWebRouteSetupAtomically(ctx.webServer, (webServer) => {
+			webServer.register({
+				kind: "exact",
+				path: GATEWAY_SETTINGS_PATH,
+				handler: (req, res) => handleGatewaySettings(req, res, controller),
+			});
+			webServer.register({
+				kind: "exact",
+				path: GATEWAY_REVEAL_PATH,
+				handler: (req, res) => handleGatewayReveal(req, res, controller),
+			});
+			webServer.register({
+				kind: "exact",
+				path: GATEWAY_ROTATE_PATH,
+				handler: (req, res) => handleGatewayRotate(req, res, controller),
+			});
+		});
+		return dispose;
+	}, "dsh-coding-subscription-oauth: gateway settings routes");
+	return () => dispose();
+}
+
+async function handleGatewaySettings(
+	req: IncomingMessage,
+	res: ServerResponse,
+	controller: CodingOAuthGatewayController,
+): Promise<void> {
+	if (!isTrustedLoopbackWebRequest(req)) {
+		json(res, 403, { error: "forbidden" });
+		return;
+	}
+	try {
+		if (req.method === "GET") {
+			json(res, 200, await controller.status());
+			return;
+		}
+		if (req.method === "PATCH") {
+			const raw = await readJsonRequest(req);
+			const payload = typeof raw === "object" && raw !== null ? (raw as { enabled?: unknown; port?: unknown }) : {};
+			const enabled = payload.enabled;
+			const port = payload.port;
+			if (enabled === undefined && port === undefined) {
+				json(res, 400, { error: "enabled or port is required" });
+				return;
+			}
+			if (enabled !== undefined && typeof enabled !== "boolean") {
+				json(res, 400, { error: "enabled must be a boolean" });
+				return;
+			}
+			if (port !== undefined) {
+				if (typeof port !== "number" || !Number.isSafeInteger(port)) {
+					json(res, 400, { error: "port must be an integer" });
+					return;
+				}
+				try {
+					assertGatewayPort(port);
+				} catch (error) {
+					json(res, 400, { error: safeMessage(error) });
+					return;
+				}
+				await controller.setPort(port);
+			}
+			const status = typeof enabled === "boolean" ? await controller.setEnabled(enabled) : await controller.status();
+			json(res, 200, status);
+			return;
+		}
+		json(res, 405, { error: "method not allowed" });
+	} catch (error) {
+		json(res, requestErrorStatus(error, 500), { error: safeMessage(error) });
+	}
+}
+
+async function handleGatewayReveal(
+	req: IncomingMessage,
+	res: ServerResponse,
+	controller: CodingOAuthGatewayController,
+): Promise<void> {
+	if (!isTrustedLoopbackWebRequest(req)) {
+		json(res, 403, { error: "forbidden" });
+		return;
+	}
+	if (req.method !== "POST") {
+		json(res, 405, { error: "method not allowed" });
+		return;
+	}
+	try {
+		json(res, 200, await controller.revealKey());
+	} catch (error) {
+		json(res, requestErrorStatus(error, 500), { error: safeMessage(error) });
+	}
+}
+
+async function handleGatewayRotate(
+	req: IncomingMessage,
+	res: ServerResponse,
+	controller: CodingOAuthGatewayController,
+): Promise<void> {
+	if (!isTrustedLoopbackWebRequest(req)) {
+		json(res, 403, { error: "forbidden" });
+		return;
+	}
+	if (req.method !== "POST") {
+		json(res, 405, { error: "method not allowed" });
+		return;
+	}
+	try {
+		json(res, 200, await controller.rotateKey());
+	} catch (error) {
+		json(res, requestErrorStatus(error, 500), { error: safeMessage(error) });
+	}
+}
+
+function json(res: ServerResponse, status: number, value: unknown): void {
+	const body = Buffer.from(`${JSON.stringify(value)}\n`);
+	res.writeHead(status, {
+		"content-type": "application/json; charset=utf-8",
+		"content-length": body.byteLength,
+		"cache-control": "no-store",
+	});
+	res.end(body);
+}

package/src/gateway.ts

@@ -0,0 +1,242 @@
+/**
+ * Start, stop, and rotate the opt-in local coding-subscription API gateway.
+ * @module dsh-coding-subscription-oauth/gateway
+ */
+
+import type { Server } from "node:http";
+import {
+	gatewayKeyPath,
+	generateGatewayApiKey,
+	loadGatewayKeyDocument,
+	loadOrCreateGatewayApiKey,
+	maskGatewayApiKey,
+	persistGatewayKeyDocument,
+} from "./gateway-auth.ts";
+import { createSessionGatewayBackend, type GatewayBackend } from "./gateway-backend.ts";
+import { assertGatewayPort, type GatewayConfig, resolveGatewayConfig } from "./gateway-config.ts";
+import { closeGateway, createGatewayHttpServer, listenGateway } from "./gateway-http.ts";
+import type { OAuthProviderSession } from "./oauth-session.ts";
+import type { GrokBuildSession } from "./session.ts";
+
+export const GATEWAY_TOS_WARNING =
+	"local API gateway is enabled; exposing a subscription as a local API can violate provider ToS and consumes your quota";
+
+export interface StartGatewayOptions {
+	config?: Partial<GatewayConfig>;
+	dshHome?: string;
+	backend?: GatewayBackend;
+	grok?: GrokBuildSession;
+	subscriptions?: readonly OAuthProviderSession[];
+	onError?: (error: unknown) => void;
+}
+
+export interface StartedGateway {
+	close(): Promise<void>;
+	readonly bind: string;
+	readonly port: number;
+}
+
+export interface GatewayPublicStatus {
+	enabled: boolean;
+	running: boolean;
+	bind: string;
+	port: number;
+	keyHint: string;
+	warning: string;
+}
+
+export interface CodingOAuthGatewayController {
+	status(): Promise<GatewayPublicStatus>;
+	startIfEnabled(): Promise<StartedGateway | undefined>;
+	setEnabled(enabled: boolean): Promise<GatewayPublicStatus>;
+	setPort(port: number): Promise<GatewayPublicStatus>;
+	revealKey(): Promise<{ apiKey: string; keyHint: string }>;
+	rotateKey(): Promise<{ apiKey: string; keyHint: string }>;
+	stop(): Promise<void>;
+}
+
+export async function startCodingOAuthGateway(options: StartGatewayOptions): Promise<StartedGateway | undefined> {
+	const controller = createCodingOAuthGatewayController(options);
+	return controller.startIfEnabled();
+}
+
+export function createCodingOAuthGatewayController(options: StartGatewayOptions): CodingOAuthGatewayController {
+	const yaml = resolveGatewayConfig(options.config);
+	const path = gatewayKeyPath(options.dshHome);
+	const backend = (): GatewayBackend => {
+		if (options.backend !== undefined) return options.backend;
+		if (options.grok === undefined) throw new Error("gateway requires a backend or Grok session");
+		return createSessionGatewayBackend(options.grok, options.subscriptions ?? []);
+	};
+	let server: Server | undefined;
+	let apiKey = yaml.apiKey ?? "";
+	let port = yaml.port;
+	let lock: Promise<void> = Promise.resolve();
+
+	const withLock = async <T>(work: () => Promise<T>): Promise<T> => {
+		const previous = lock;
+		let release: () => void = () => undefined;
+		lock = new Promise<void>((resolve) => {
+			release = resolve;
+		});
+		await previous;
+		try {
+			return await work();
+		} finally {
+			release();
+		}
+	};
+
+	const closeServer = async (): Promise<void> => {
+		if (server === undefined) return;
+		const current = server;
+		server = undefined;
+		await closeGateway(current).catch(() => undefined);
+	};
+
+	const activeConfig = (): GatewayConfig => ({ ...yaml, port });
+
+	const snapshot = async (enabled?: boolean): Promise<GatewayPublicStatus> => ({
+		enabled: enabled ?? (await desiredEnabled()),
+		running: server !== undefined,
+		bind: yaml.bind,
+		port,
+		keyHint: apiKey.length === 0 ? "" : maskGatewayApiKey(apiKey),
+		warning: GATEWAY_TOS_WARNING,
+	});
+
+	const persistState = async (next: { enabled?: boolean; port?: number; apiKey?: string }): Promise<void> => {
+		const document = await loadGatewayKeyDocument(path);
+		const nextKey = next.apiKey ?? (apiKey.length === 0 ? document?.apiKey : apiKey);
+		if (nextKey === undefined || nextKey.length === 0) throw new Error("gateway api key is missing");
+		apiKey = nextKey;
+		const nextEnabled = next.enabled ?? document?.enabled;
+		const nextPort = next.port ?? document?.port ?? port;
+		port = nextPort;
+		await persistGatewayKeyDocument(path, {
+			version: 1,
+			apiKey: nextKey,
+			...(nextEnabled === undefined ? {} : { enabled: nextEnabled }),
+			port: nextPort,
+		});
+	};
+
+	const listen = async (): Promise<StartedGateway> => {
+		if (apiKey.length === 0) apiKey = await loadOrCreateGatewayApiKey(path, yaml.apiKey);
+		const config = activeConfig();
+		const http = createGatewayHttpServer({ config, apiKey, backend: backend() });
+		try {
+			await listenGateway(http, config);
+		} catch (error) {
+			await closeGateway(http).catch(() => undefined);
+			options.onError?.(error);
+			throw error;
+		}
+		server = http;
+		return { bind: config.bind, port: config.port, close: () => closeServer() };
+	};
+
+	const desiredEnabled = async (): Promise<boolean> => {
+		const document = await loadGatewayKeyDocument(path);
+		return document?.enabled ?? yaml.enabled;
+	};
+
+	const hydratePort = async (): Promise<void> => {
+		const document = await loadGatewayKeyDocument(path);
+		if (document?.port !== undefined) port = document.port;
+	};
+
+	return {
+		async status() {
+			await hydratePort();
+			if (apiKey.length === 0) {
+				const document = await loadGatewayKeyDocument(path);
+				apiKey = document?.apiKey ?? "";
+			}
+			return snapshot();
+		},
+		startIfEnabled() {
+			return withLock(async () => {
+				await hydratePort();
+				if (!(await desiredEnabled())) return undefined;
+				if (server !== undefined) return { bind: yaml.bind, port, close: () => closeServer() };
+				try {
+					return await listen();
+				} catch {
+					return undefined;
+				}
+			});
+		},
+		setEnabled(enabled) {
+			return withLock(async () => {
+				await hydratePort();
+				if (apiKey.length === 0) apiKey = await loadOrCreateGatewayApiKey(path, yaml.apiKey);
+				await persistState({ enabled });
+				if (enabled && server === undefined) {
+					try {
+						await listen();
+					} catch {
+						// status.running stays false; caller sees the public snapshot.
+					}
+				}
+				if (!enabled) await closeServer();
+				return snapshot(enabled);
+			});
+		},
+		setPort(nextPort) {
+			return withLock(async () => {
+				await hydratePort();
+				const wanted = assertGatewayPort(nextPort);
+				if (apiKey.length === 0) apiKey = await loadOrCreateGatewayApiKey(path, yaml.apiKey);
+				const previous = port;
+				const shouldRun = server !== undefined;
+				await persistState({ port: wanted });
+				if (!shouldRun) return snapshot();
+				await closeServer();
+				try {
+					await listen();
+					return snapshot();
+				} catch (error) {
+					port = previous;
+					await persistState({ port: previous });
+					try {
+						await listen();
+					} catch {
+						// previous port may also fail; status.running reflects reality
+					}
+					throw error;
+				}
+			});
+		},
+		revealKey() {
+			return withLock(async () => {
+				if (apiKey.length === 0) apiKey = await loadOrCreateGatewayApiKey(path, yaml.apiKey);
+				return { apiKey, keyHint: maskGatewayApiKey(apiKey) };
+			});
+		},
+		rotateKey() {
+			return withLock(async () => {
+				await hydratePort();
+				const next = generateGatewayApiKey();
+				const document = await loadGatewayKeyDocument(path);
+				await persistState({
+					apiKey: next,
+					...(document?.enabled === undefined ? {} : { enabled: document.enabled }),
+				});
+				const shouldRun = server !== undefined;
+				await closeServer();
+				if (shouldRun) {
+					try {
+						await listen();
+					} catch {
+						// rotated key is persisted even if listen fails
+					}
+				}
+				return { apiKey: next, keyHint: maskGatewayApiKey(next) };
+			});
+		},
+		stop() {
+			return withLock(() => closeServer());
+		},
+	};
+}