@clinebot/core 0.0.0

package/src/auth/server.ts

@@ -0,0 +1,216 @@
+export interface OAuthCallbackPayload {
+	url: URL;
+	code?: string;
+	state?: string;
+	provider?: string;
+	error?: string;
+}
+
+type Deferred<T> = {
+	promise: Promise<T>;
+	resolve: (value: T) => void;
+};
+
+function createDeferred<T>(): Deferred<T> {
+	let resolve!: (value: T) => void;
+	const promise = new Promise<T>((res) => {
+		resolve = res;
+	});
+	return { promise, resolve };
+}
+
+export interface LocalOAuthServerOptions {
+	host?: string;
+	ports: number[];
+	callbackPath: string;
+	timeoutMs?: number;
+	expectedState?: string;
+	successHtml?: string;
+}
+
+export interface LocalOAuthServer {
+	callbackUrl: string;
+	waitForCallback: () => Promise<OAuthCallbackPayload | null>;
+	cancelWait: () => void;
+	close: () => void;
+}
+
+export async function startLocalOAuthServer(
+	options: LocalOAuthServerOptions,
+): Promise<LocalOAuthServer> {
+	const http = await import("node:http");
+
+	const host = options.host ?? "127.0.0.1";
+	const timeoutMs = options.timeoutMs ?? 5 * 60 * 1000;
+	const successHtml = options.successHtml ?? HTML_CONTENT;
+
+	const deferred = createDeferred<OAuthCallbackPayload | null>();
+	let settled = false;
+	let timeout: ReturnType<typeof setTimeout> | null = null;
+	let activeServer: import("node:http").Server | null = null;
+
+	const settle = (value: OAuthCallbackPayload | null) => {
+		if (settled) return;
+		settled = true;
+		deferred.resolve(value);
+	};
+
+	const close = () => {
+		if (timeout) {
+			clearTimeout(timeout);
+			timeout = null;
+		}
+		if (activeServer) {
+			activeServer.close();
+			activeServer = null;
+		}
+	};
+
+	const waitForCallback = async () => {
+		timeout = setTimeout(() => {
+			close();
+			settle(null);
+		}, timeoutMs);
+		return deferred.promise;
+	};
+
+	for (const port of options.ports) {
+		const server = http.createServer((req, res) => {
+			try {
+				const requestUrl = new URL(req.url || "", `http://${host}:${port}`);
+				if (requestUrl.pathname !== options.callbackPath) {
+					res.statusCode = 404;
+					res.end("Not found");
+					return;
+				}
+
+				const payload: OAuthCallbackPayload = {
+					url: requestUrl,
+					code: requestUrl.searchParams.get("code") ?? undefined,
+					state: requestUrl.searchParams.get("state") ?? undefined,
+					provider: requestUrl.searchParams.get("provider") ?? undefined,
+					error: requestUrl.searchParams.get("error") ?? undefined,
+				};
+
+				if (payload.error) {
+					res.statusCode = 400;
+					res.end(`Authentication failed: ${payload.error}`);
+					close();
+					settle(payload);
+					return;
+				}
+
+				if (!payload.code) {
+					res.statusCode = 400;
+					res.end("Missing authorization code");
+					return;
+				}
+
+				if (options.expectedState && payload.state !== options.expectedState) {
+					res.statusCode = 400;
+					res.end("State mismatch");
+					return;
+				}
+
+				res.statusCode = 200;
+				res.setHeader("Content-Type", "text/html; charset=utf-8");
+				res.end(successHtml);
+				close();
+				settle(payload);
+			} catch {
+				res.statusCode = 500;
+				res.end("Internal error");
+			}
+		});
+
+		const bindResult = await new Promise<{
+			bound: boolean;
+			error?: NodeJS.ErrnoException;
+		}>((resolve) => {
+			const onError = (error: NodeJS.ErrnoException) => {
+				server.off("error", onError);
+				resolve({ bound: false, error });
+			};
+
+			server.once("error", onError);
+			server.listen(port, host, () => {
+				server.off("error", onError);
+				activeServer = server;
+				resolve({ bound: true });
+			});
+		});
+
+		if (bindResult.error) {
+			if (bindResult.error.code === "EADDRINUSE") {
+				continue;
+			}
+			close();
+			throw bindResult.error;
+		}
+
+		if (bindResult.bound) {
+			return {
+				callbackUrl: `http://${host}:${port}${options.callbackPath}`,
+				waitForCallback,
+				cancelWait: () => {
+					close();
+					settle(null);
+				},
+				close: () => {
+					close();
+					settle(null);
+				},
+			};
+		}
+	}
+
+	return {
+		callbackUrl: "",
+		waitForCallback: async () => null,
+		cancelWait: () => {},
+		close: () => {},
+	};
+}
+
+const HTML_CONTENT = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Authentication Successful</title>
+<style>
+  * { margin: 0; padding: 0; box-sizing: border-box; }
+  body {
+    font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, Oxygen, Ubuntu, sans-serif;
+    min-height: 100vh;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    background: linear-gradient(135deg, #1a1a2e 0%, #16213e 100%);
+    color: #fff;
+  }
+  .container { text-align: center; padding: 48px; max-width: 420px; }
+  .icon {
+    width: 72px; height: 72px; margin: 0 auto 24px;
+    background: linear-gradient(135deg, #10a37f 0%, #1a7f64 100%);
+    border-radius: 50%;
+    display: flex; align-items: center; justify-content: center;
+  }
+  .icon svg { width: 36px; height: 36px; stroke: #fff; stroke-width: 3; fill: none; }
+  h1 { font-size: 24px; font-weight: 600; margin-bottom: 12px; }
+  p { font-size: 15px; color: rgba(255,255,255,0.7); line-height: 1.5; }
+  .closing { margin-top: 32px; font-size: 13px; color: rgba(255,255,255,0.5); }
+</style>
+</head>
+<body>
+<div class="container">
+  <div class="icon">
+    <svg viewBox="0 0 24 24"><polyline points="20 6 9 17 4 12"></polyline></svg>
+  </div>
+  <h1>Authentication Successful</h1>
+  <p>You're now signed in. You can close this window.</p>
+  <p class="closing">This window will close automatically...</p>
+</div>
+<script>setTimeout(() => window.close(), 3000);</script>
+</body>
+</html>`;

package/src/auth/types.ts

@@ -0,0 +1,78 @@
+export interface OAuthPrompt {
+	message: string;
+	defaultValue?: string;
+}
+
+export interface OAuthCredentials {
+	access: string;
+	refresh: string;
+	/**
+	 * Expiration timestamp in milliseconds since epoch.
+	 */
+	expires: number;
+	/**
+	 * Optional provider-specific account identifier.
+	 */
+	accountId?: string;
+	/**
+	 * Optional email for display/telemetry.
+	 */
+	email?: string;
+	/**
+	 * Provider-specific metadata (user info, provider hint, etc).
+	 */
+	metadata?: Record<string, unknown>;
+}
+
+export interface OAuthLoginCallbacks {
+	onAuth: (info: { url: string; instructions?: string }) => void;
+	onPrompt: (prompt: OAuthPrompt) => Promise<string>;
+	onProgress?: (message: string) => void;
+	onManualCodeInput?: () => Promise<string>;
+}
+
+export interface OAuthProviderInterface {
+	id: string;
+	name: string;
+	usesCallbackServer: boolean;
+	login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials>;
+	refreshToken(credentials: OAuthCredentials): Promise<OAuthCredentials>;
+	getApiKey(credentials: OAuthCredentials): string;
+}
+
+export type OcaMode = "internal" | "external";
+
+export interface OcaOAuthEnvironmentConfig {
+	clientId: string;
+	idcsUrl: string;
+	scopes: string;
+	baseUrl: string;
+}
+
+export interface OcaOAuthConfig {
+	internal: OcaOAuthEnvironmentConfig;
+	external: OcaOAuthEnvironmentConfig;
+}
+
+export interface OcaClientMetadata {
+	client?: string;
+	clientVersion?: string;
+	clientIde?: string;
+	clientIdeVersion?: string;
+}
+
+export interface OcaOAuthProviderOptions {
+	config?: Partial<OcaOAuthConfig>;
+	mode?: OcaMode | (() => OcaMode);
+	callbackPath?: string;
+	callbackPorts?: number[];
+	requestTimeoutMs?: number;
+	refreshBufferMs?: number;
+	retryableTokenGraceMs?: number;
+}
+
+export interface OcaTokenResolution {
+	forceRefresh?: boolean;
+	refreshBufferMs?: number;
+	retryableTokenGraceMs?: number;
+}

package/src/auth/utils.test.ts

@@ -0,0 +1,128 @@
+import { describe, expect, it, vi } from "vitest";
+import {
+	decodeJwtPayload,
+	isCredentialLikelyExpired,
+	parseAuthorizationInput,
+	parseOAuthError,
+	resolveAuthorizationCodeInput,
+	resolveUrl,
+} from "./utils.js";
+
+function toBase64Url(value: string): string {
+	return Buffer.from(value, "utf8").toString("base64url");
+}
+
+function createJwt(payload: Record<string, unknown>): string {
+	return `${toBase64Url(JSON.stringify({ alg: "none", typ: "JWT" }))}.${toBase64Url(JSON.stringify(payload))}.sig`;
+}
+
+describe("auth/utils", () => {
+	it("parses auth input from full URL with provider", () => {
+		const parsed = parseAuthorizationInput(
+			"http://localhost/callback?code=test-code&state=s1&provider=google",
+			{
+				includeProvider: true,
+			},
+		);
+		expect(parsed).toEqual({
+			code: "test-code",
+			state: "s1",
+			provider: "google",
+		});
+	});
+
+	it("parses auth input from hash format when enabled", () => {
+		const parsed = parseAuthorizationInput("abc123#state1", {
+			allowHashCodeState: true,
+		});
+		expect(parsed).toEqual({ code: "abc123", state: "state1" });
+	});
+
+	it("builds resolved URLs from base + path", () => {
+		expect(resolveUrl("https://example.com/", "/token")).toBe(
+			"https://example.com/token",
+		);
+	});
+
+	it("decodes JWT payload", () => {
+		const token = createJwt({ sub: "account-1", exp: 123 });
+		expect(decodeJwtPayload(token)).toMatchObject({
+			sub: "account-1",
+			exp: 123,
+		});
+		expect(decodeJwtPayload("invalid")).toBeNull();
+	});
+
+	it("parses OAuth error payloads from string and object forms", () => {
+		expect(
+			parseOAuthError(
+				JSON.stringify({
+					error: "invalid_grant",
+					error_description: "expired",
+				}),
+			),
+		).toEqual({
+			code: "invalid_grant",
+			message: "expired",
+		});
+		expect(
+			parseOAuthError(
+				JSON.stringify({ error: { type: "unauthorized", message: "denied" } }),
+			),
+		).toEqual({
+			code: "unauthorized",
+			message: "denied",
+		});
+	});
+
+	it("resolves code from callback result", async () => {
+		const result = await resolveAuthorizationCodeInput({
+			waitForCallback: async () => ({
+				url: new URL("http://localhost"),
+				code: "from-callback",
+				state: "s1",
+			}),
+			cancelWait: () => {},
+		});
+		expect(result).toEqual({
+			code: "from-callback",
+			state: "s1",
+			provider: undefined,
+			error: undefined,
+		});
+	});
+
+	it("resolves code from manual input when callback does not provide one", async () => {
+		const cancelWait = vi.fn();
+		const result = await resolveAuthorizationCodeInput({
+			waitForCallback: async () => null,
+			cancelWait,
+			onManualCodeInput: async () => "code=manual&state=manual-state",
+		});
+		expect(cancelWait).toHaveBeenCalled();
+		expect(result).toEqual({
+			code: "manual",
+			state: "manual-state",
+			provider: undefined,
+		});
+	});
+
+	it("throws when manual input rejects", async () => {
+		await expect(
+			resolveAuthorizationCodeInput({
+				waitForCallback: async () => null,
+				cancelWait: () => {},
+				onManualCodeInput: async () => {
+					throw new Error("cancelled");
+				},
+			}),
+		).rejects.toThrow("cancelled");
+	});
+
+	it("checks token expiry with configurable buffer", () => {
+		const nowSpy = vi.spyOn(Date, "now").mockReturnValue(1_000);
+		expect(isCredentialLikelyExpired({ expires: 1_500 }, 600)).toBe(true);
+		expect(isCredentialLikelyExpired({ expires: 3_000 }, 600)).toBe(false);
+		nowSpy.mockRestore();
+	});
+});

package/src/auth/utils.ts

@@ -0,0 +1,247 @@
+import type { OAuthCallbackPayload } from "./server.js";
+import type { OAuthCredentials } from "./types.js";
+
+function base64UrlEncode(input: Uint8Array): string {
+	let binary = "";
+	for (let i = 0; i < input.length; i += 1) {
+		binary += String.fromCharCode(input[i] ?? 0);
+	}
+	return btoa(binary)
+		.replace(/\+/g, "-")
+		.replace(/\//g, "_")
+		.replace(/=+$/g, "");
+}
+
+async function sha256(value: string): Promise<Uint8Array> {
+	const encoder = new TextEncoder();
+	const data = encoder.encode(value);
+	const digest = await crypto.subtle.digest("SHA-256", data);
+	return new Uint8Array(digest);
+}
+
+function createVerifier(byteLength = 32): string {
+	const randomBytes = new Uint8Array(byteLength);
+	crypto.getRandomValues(randomBytes);
+	return base64UrlEncode(randomBytes);
+}
+
+export async function getProofKey(): Promise<{
+	verifier: string;
+	challenge: string;
+}> {
+	const verifier = createVerifier();
+	const challenge = base64UrlEncode(await sha256(verifier));
+	return { verifier, challenge };
+}
+
+export function normalizeBaseUrl(value: string): string {
+	return value.endsWith("/") ? value.slice(0, -1) : value;
+}
+
+export function resolveUrl(baseUrl: string, path: string): string {
+	return new URL(path, `${normalizeBaseUrl(baseUrl)}/`).toString();
+}
+
+export type ParsedAuthorizationInput = {
+	code?: string;
+	state?: string;
+	provider?: string;
+};
+
+export type ParseAuthorizationInputOptions = {
+	includeProvider?: boolean;
+	allowHashCodeState?: boolean;
+};
+
+export function parseAuthorizationInput(
+	input: string,
+	options: ParseAuthorizationInputOptions = {},
+): ParsedAuthorizationInput {
+	const value = input.trim();
+	if (!value) {
+		return {};
+	}
+
+	try {
+		const url = new URL(value);
+		return {
+			code: url.searchParams.get("code") ?? undefined,
+			state: url.searchParams.get("state") ?? undefined,
+			provider: options.includeProvider
+				? (url.searchParams.get("provider") ?? undefined)
+				: undefined,
+		};
+	} catch {
+		// not a URL
+	}
+
+	if (options.allowHashCodeState && value.includes("#")) {
+		const [code, state] = value.split("#", 2);
+		return {
+			code: code || undefined,
+			state: state || undefined,
+		};
+	}
+
+	if (value.includes("code=")) {
+		const params = new URLSearchParams(value);
+		return {
+			code: params.get("code") ?? undefined,
+			state: params.get("state") ?? undefined,
+			provider: options.includeProvider
+				? (params.get("provider") ?? undefined)
+				: undefined,
+		};
+	}
+
+	return { code: value };
+}
+
+function decodeBase64(value: string): string | null {
+	if (typeof atob === "function") {
+		try {
+			return atob(value);
+		} catch {
+			return null;
+		}
+	}
+
+	if (typeof Buffer !== "undefined") {
+		try {
+			return Buffer.from(value, "base64").toString("utf8");
+		} catch {
+			return null;
+		}
+	}
+
+	return null;
+}
+
+export function decodeJwtPayload(
+	token?: string,
+): Record<string, unknown> | null {
+	if (!token) {
+		return null;
+	}
+
+	try {
+		const parts = token.split(".");
+		if (parts.length !== 3) {
+			return null;
+		}
+
+		const payload = parts[1];
+		if (!payload) {
+			return null;
+		}
+
+		const normalized = payload.replace(/-/g, "+").replace(/_/g, "/");
+		const padded = normalized.padEnd(
+			normalized.length + ((4 - (normalized.length % 4)) % 4),
+			"=",
+		);
+		const decoded = decodeBase64(padded);
+		if (!decoded) {
+			return null;
+		}
+		return JSON.parse(decoded) as Record<string, unknown>;
+	} catch {
+		return null;
+	}
+}
+
+export function parseOAuthError(text: string): {
+	code?: string;
+	message?: string;
+} {
+	try {
+		const json = JSON.parse(text) as Record<string, unknown>;
+		const error = json.error;
+		const code =
+			typeof error === "string"
+				? error
+				: error &&
+						typeof error === "object" &&
+						typeof (error as Record<string, unknown>).type === "string"
+					? ((error as Record<string, unknown>).type as string)
+					: undefined;
+		const message =
+			typeof json.error_description === "string"
+				? json.error_description
+				: typeof json.message === "string"
+					? json.message
+					: error &&
+							typeof error === "object" &&
+							typeof (error as Record<string, unknown>).message === "string"
+						? ((error as Record<string, unknown>).message as string)
+						: undefined;
+		return { code, message };
+	} catch {
+		return {};
+	}
+}
+
+export function isCredentialLikelyExpired(
+	credentials: Pick<OAuthCredentials, "expires">,
+	refreshBufferMs: number,
+): boolean {
+	return Date.now() >= credentials.expires - refreshBufferMs;
+}
+
+export async function resolveAuthorizationCodeInput(input: {
+	waitForCallback: () => Promise<OAuthCallbackPayload | null>;
+	cancelWait: () => void;
+	onManualCodeInput?: () => Promise<string>;
+	parseOptions?: ParseAuthorizationInputOptions;
+}): Promise<ParsedAuthorizationInput & { error?: string }> {
+	if (!input.onManualCodeInput) {
+		const callbackResult = await input.waitForCallback();
+		return {
+			code: callbackResult?.code,
+			state: callbackResult?.state,
+			provider: callbackResult?.provider,
+			error: callbackResult?.error,
+		};
+	}
+
+	let manualInput: string | undefined;
+	let manualError: Error | undefined;
+	const manualPromise = input
+		.onManualCodeInput()
+		.then((value) => {
+			manualInput = value;
+			input.cancelWait();
+		})
+		.catch((error: unknown) => {
+			manualError = error instanceof Error ? error : new Error(String(error));
+			input.cancelWait();
+		});
+
+	const callbackResult = await input.waitForCallback();
+	if (manualError) {
+		throw manualError;
+	}
+
+	if (callbackResult?.code || callbackResult?.error) {
+		return {
+			code: callbackResult.code,
+			state: callbackResult.state,
+			provider: callbackResult.provider,
+			error: callbackResult.error,
+		};
+	}
+
+	if (manualInput) {
+		return parseAuthorizationInput(manualInput, input.parseOptions);
+	}
+
+	await manualPromise;
+	if (manualError) {
+		throw manualError;
+	}
+	if (manualInput) {
+		return parseAuthorizationInput(manualInput, input.parseOptions);
+	}
+
+	return {};
+}