@gajae-code/ai 0.1.1

package/src/utils/oauth/perplexity.ts

@@ -0,0 +1,206 @@
+/**
+ * Perplexity login and token refresh.
+ *
+ * Login paths (in priority order):
+ * 1. macOS native app: reads JWT from NSUserDefaults (`defaults read ai.perplexity.mac authToken`)
+ * 2. HTTP email OTP: `GET /api/auth/csrf` → `POST /api/auth/signin-email` → `POST /api/auth/signin-otp`
+ *
+ * No browser or manual cookie paste required.
+ * Refresh: Socket.IO `refreshJWT` RPC over authenticated WebSocket connection.
+ *
+ * Protocol: Engine.IO v4 + Socket.IO v4 over WebSocket (bypasses Cloudflare managed challenge).
+ * Architecture reverse-engineered from Perplexity macOS app (ai.perplexity.mac).
+ */
+import * as os from "node:os";
+import { $env } from "@gajae-code/utils";
+import { $ } from "bun";
+import type { OAuthController, OAuthCredentials } from "./types";
+
+const API_VERSION = "2.18";
+const NATIVE_APP_BUNDLE = "ai.perplexity.mac";
+const APP_USER_AGENT = "Perplexity/641 CFNetwork/1568 Darwin/25.2.0";
+
+// ---------------------------------------------------------------------------
+// JWT helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Extract expiry from a JWT. Perplexity tokens generally lack an `exp` claim
+ * (their sessions are server-side and effectively non-expiring from the client's
+ * point of view), so we return a far-future sentinel when no `exp` is present.
+ * When `exp` IS present, subtract a 5-minute safety margin.
+ */
+const NEVER_EXPIRES = 8.64e15; // max safe Date value
+function getJwtExpiry(token: string): number {
+	try {
+		const parts = token.split(".");
+		if (parts.length !== 3) return NEVER_EXPIRES;
+		const payload = parts[1] ?? "";
+		const decoded = JSON.parse(atob(payload.replace(/-/g, "+").replace(/_/g, "/")));
+		if (typeof decoded?.exp === "number" && Number.isFinite(decoded.exp)) {
+			return decoded.exp * 1000 - 5 * 60_000;
+		}
+	} catch {
+		// Ignore decode errors
+	}
+	return NEVER_EXPIRES;
+}
+
+/** Build OAuthCredentials from a Perplexity JWT string. */
+function jwtToCredentials(jwt: string, email?: string): OAuthCredentials {
+	return {
+		access: jwt,
+		refresh: jwt,
+		expires: getJwtExpiry(jwt),
+		email,
+	};
+}
+
+// ---------------------------------------------------------------------------
+// Desktop app extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * Read the Perplexity JWT from the native macOS Catalyst app's UserDefaults.
+ * Tokens are stored in NSUserDefaults (not Keychain), readable by any same-UID process.
+ */
+async function extractFromNativeApp(): Promise<string | null> {
+	if (os.platform() !== "darwin") return null;
+
+	try {
+		const result = await $`defaults read ${NATIVE_APP_BUNDLE} authToken`.quiet().nothrow();
+		if (result.exitCode !== 0) return null;
+		const token = result.text().trim();
+		if (!token || token === "(null)") return null;
+		return token;
+	} catch {
+		return null;
+	}
+}
+
+// ---------------------------------------------------------------------------
+// Socket.IO email OTP login
+// ---------------------------------------------------------------------------
+
+/**
+ * Send email OTP and exchange it for a Perplexity JWT via HTTP endpoints.
+ */
+async function httpEmailLogin(ctrl: OAuthController): Promise<OAuthCredentials> {
+	if (!ctrl.onPrompt) {
+		throw new Error("Perplexity login requires onPrompt callback");
+	}
+	const email = await ctrl.onPrompt({
+		message: "Enter your Perplexity email address",
+		placeholder: "user@example.com",
+	});
+	const trimmedEmail = email.trim();
+	if (!trimmedEmail) throw new Error("Email is required for Perplexity login");
+	if (ctrl.signal?.aborted) throw new Error("Login cancelled");
+
+	ctrl.onProgress?.("Fetching Perplexity CSRF token...");
+	const csrfResponse = await fetch("https://www.perplexity.ai/api/auth/csrf", {
+		headers: {
+			"User-Agent": APP_USER_AGENT,
+			"X-App-ApiVersion": API_VERSION,
+		},
+		signal: ctrl.signal,
+	});
+
+	if (!csrfResponse.ok) {
+		throw new Error(`Perplexity CSRF request failed: ${csrfResponse.status}`);
+	}
+
+	const csrfData = (await csrfResponse.json()) as { csrfToken?: string };
+	if (!csrfData.csrfToken) {
+		throw new Error("Perplexity CSRF response missing csrfToken");
+	}
+	ctrl.onProgress?.("Sending login code to your email...");
+	const sendResponse = await fetch("https://www.perplexity.ai/api/auth/signin-email", {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			"User-Agent": APP_USER_AGENT,
+			"X-App-ApiVersion": API_VERSION,
+		},
+		body: JSON.stringify({
+			email: trimmedEmail,
+			csrfToken: csrfData.csrfToken,
+		}),
+		signal: ctrl.signal,
+	});
+
+	if (!sendResponse.ok) {
+		const body = await sendResponse.text();
+		throw new Error(`Perplexity send login code failed (${sendResponse.status}): ${body}`);
+	}
+	const otp = await ctrl.onPrompt({
+		message: "Enter the code sent to your email",
+		placeholder: "123456",
+	});
+	const trimmedOtp = otp.trim();
+	if (!trimmedOtp) throw new Error("OTP code is required");
+	if (ctrl.signal?.aborted) throw new Error("Login cancelled");
+	ctrl.onProgress?.("Verifying login code...");
+	const verifyResponse = await fetch("https://www.perplexity.ai/api/auth/signin-otp", {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			"User-Agent": APP_USER_AGENT,
+			"X-App-ApiVersion": API_VERSION,
+		},
+		body: JSON.stringify({
+			email: trimmedEmail,
+			otp: trimmedOtp,
+			csrfToken: csrfData.csrfToken,
+		}),
+		signal: ctrl.signal,
+	});
+
+	const verifyData = (await verifyResponse.json()) as {
+		token?: string;
+		status?: string;
+		error_code?: string;
+		text?: string;
+	};
+
+	if (!verifyResponse.ok) {
+		const reason = verifyData.text ?? verifyData.error_code ?? verifyData.status ?? "OTP verification failed";
+		throw new Error(`Perplexity OTP verification failed: ${reason}`);
+	}
+
+	if (!verifyData.token) {
+		throw new Error("Perplexity OTP verification response missing token");
+	}
+
+	return jwtToCredentials(verifyData.token, trimmedEmail);
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Login to Perplexity.
+ *
+ * Tries auto-extraction from the desktop app, then runs HTTP email OTP login.
+ *
+ * No browser/manual token paste fallback is used.
+ */
+export async function loginPerplexity(ctrl: OAuthController): Promise<OAuthCredentials> {
+	if (!ctrl.onPrompt) {
+		throw new Error("Perplexity login requires onPrompt callback");
+	}
+
+	// Path 1: Native macOS app JWT (skip if PI_AUTH_NO_BORROW=1)
+	if (!$env.PI_AUTH_NO_BORROW) {
+		ctrl.onProgress?.("Checking for Perplexity desktop app...");
+		const nativeJwt = await extractFromNativeApp();
+		if (nativeJwt) {
+			ctrl.onProgress?.("Found Perplexity JWT from native app");
+			return jwtToCredentials(nativeJwt);
+		}
+	}
+
+	// Path 2: HTTP email OTP
+	return httpEmailLogin(ctrl);
+}

package/src/utils/oauth/pkce.ts

@@ -0,0 +1,18 @@
+/**
+ * Generate PKCE code verifier and challenge.
+ * Uses Web Crypto API for cross-platform compatibility.
+ */
+export async function generatePKCE(): Promise<{ verifier: string; challenge: string }> {
+	// Generate random verifier
+	const verifierBytes = new Uint8Array(96);
+	crypto.getRandomValues(verifierBytes);
+	const verifier = Buffer.from(verifierBytes).toString("base64url");
+
+	// Compute SHA-256 challenge
+	const encoder = new TextEncoder();
+	const data = encoder.encode(verifier);
+	const hashBuffer = await crypto.subtle.digest("SHA-256", data);
+	const challenge = Buffer.from(hashBuffer).toString("base64url");
+
+	return { verifier, challenge };
+}

package/src/utils/oauth/qianfan.ts

@@ -0,0 +1,58 @@
+/**
+ * Qianfan login flow.
+ *
+ * Qianfan provides an OpenAI-compatible API endpoint.
+ * Login is API-key based:
+ * 1. Open browser to Qianfan API key console
+ * 2. User copies API key
+ * 3. User pastes key into CLI prompt
+ */
+
+import { validateOpenAICompatibleApiKey } from "./api-key-validation";
+import type { OAuthController } from "./types";
+
+const AUTH_URL = "https://console.bce.baidu.com/qianfan/ais/console/apiKey";
+const API_BASE_URL = "https://qianfan.baidubce.com/v2";
+const VALIDATION_MODEL = "deepseek-v3.2";
+
+/**
+ * Login to Qianfan.
+ *
+ * Opens browser to API key page, prompts user to paste their API key.
+ * Returns the API key directly (not OAuthCredentials - this isn't OAuth).
+ */
+export async function loginQianfan(options: OAuthController): Promise<string> {
+	if (!options.onPrompt) {
+		throw new Error("Qianfan login requires onPrompt callback");
+	}
+
+	options.onAuth?.({
+		url: AUTH_URL,
+		instructions: "Copy your Qianfan API key from the console",
+	});
+
+	const apiKey = await options.onPrompt({
+		message: "Paste your Qianfan API key",
+		placeholder: "bce-v3/ALTAK-...",
+	});
+
+	if (options.signal?.aborted) {
+		throw new Error("Login cancelled");
+	}
+
+	const trimmed = apiKey.trim();
+	if (!trimmed) {
+		throw new Error("API key is required");
+	}
+
+	options.onProgress?.("Validating API key...");
+	await validateOpenAICompatibleApiKey({
+		provider: "qianfan",
+		apiKey: trimmed,
+		baseUrl: API_BASE_URL,
+		model: VALIDATION_MODEL,
+		signal: options.signal,
+	});
+
+	return trimmed;
+}

package/src/utils/oauth/qwen-portal.ts

@@ -0,0 +1,60 @@
+/**
+ * Qwen Portal login flow.
+ *
+ * Qwen Portal exposes an OpenAI-compatible endpoint at https://portal.qwen.ai/v1
+ * and accepts OAuth bearer tokens or API keys.
+ *
+ * This is a token/API-key flow:
+ * 1. Open Qwen Portal
+ * 2. Copy either your OAuth token or API key
+ * 3. Paste it into the CLI
+ */
+
+import { validateOpenAICompatibleApiKey } from "./api-key-validation";
+import type { OAuthController } from "./types";
+
+const AUTH_URL = "https://chat.qwen.ai";
+const API_BASE_URL = "https://portal.qwen.ai/v1";
+const VALIDATION_MODEL = "coder-model";
+
+/**
+ * Login to Qwen Portal.
+ *
+ * Prompts for either `QWEN_OAUTH_TOKEN` or `QWEN_PORTAL_API_KEY` value.
+ * Returns the value directly (stored as api_key credential in auth storage).
+ */
+export async function loginQwenPortal(options: OAuthController): Promise<string> {
+	if (!options.onPrompt) {
+		throw new Error("Qwen Portal login requires onPrompt callback");
+	}
+
+	options.onAuth?.({
+		url: AUTH_URL,
+		instructions: "Copy your Qwen OAuth token or API key",
+	});
+
+	const token = await options.onPrompt({
+		message: "Paste your Qwen OAuth token or API key",
+		placeholder: "sk-...",
+	});
+
+	if (options.signal?.aborted) {
+		throw new Error("Login cancelled");
+	}
+
+	const trimmed = token.trim();
+	if (!trimmed) {
+		throw new Error("Qwen token/API key is required");
+	}
+
+	options.onProgress?.("Validating credentials...");
+	await validateOpenAICompatibleApiKey({
+		provider: "qwen-portal",
+		apiKey: trimmed,
+		baseUrl: API_BASE_URL,
+		model: VALIDATION_MODEL,
+		signal: options.signal,
+	});
+
+	return trimmed;
+}

package/src/utils/oauth/synthetic.ts

@@ -0,0 +1,16 @@
+/** Synthetic login flow (API key paste against https://api.synthetic.new/openai/v1). */
+import { createApiKeyLogin } from "./api-key-login";
+
+export const loginSynthetic = createApiKeyLogin({
+	providerLabel: "Synthetic",
+	authUrl: "https://dev.synthetic.new/docs/api/overview",
+	instructions: "Copy your API key from the Synthetic dashboard",
+	promptMessage: "Paste your Synthetic API key",
+	placeholder: "sk-...",
+	validation: {
+		kind: "chat-completions",
+		provider: "Synthetic",
+		baseUrl: "https://api.synthetic.new/openai/v1",
+		model: "hf:moonshotai/Kimi-K2.5",
+	},
+});

package/src/utils/oauth/tavily.ts

@@ -0,0 +1,46 @@
+/**
+ * Tavily login flow.
+ *
+ * Tavily web search uses an API key from the account settings page.
+ * This is an API key flow:
+ * 1. Open browser to Tavily settings
+ * 2. User copies API key
+ * 3. User pastes key into CLI
+ */
+
+import type { OAuthController } from "./types";
+
+const AUTH_URL = "https://app.tavily.com/home";
+
+/**
+ * Login to Tavily.
+ *
+ * Opens browser to API keys page and prompts user to paste their API key.
+ * Returns the API key directly (not OAuthCredentials - this isn't OAuth).
+ */
+export async function loginTavily(options: OAuthController): Promise<string> {
+	if (!options.onPrompt) {
+		throw new Error("Tavily login requires onPrompt callback");
+	}
+
+	options.onAuth?.({
+		url: AUTH_URL,
+		instructions: "Copy your Tavily API key from the API Keys page.",
+	});
+
+	const apiKey = await options.onPrompt({
+		message: "Paste your Tavily API key",
+		placeholder: "tvly-...",
+	});
+
+	if (options.signal?.aborted) {
+		throw new Error("Login cancelled");
+	}
+
+	const trimmed = apiKey.trim();
+	if (!trimmed) {
+		throw new Error("API key is required");
+	}
+
+	return trimmed;
+}

package/src/utils/oauth/together.ts

@@ -0,0 +1,16 @@
+/** Together login flow (API key paste against https://api.together.xyz/v1). */
+import { createApiKeyLogin } from "./api-key-login";
+
+export const loginTogether = createApiKeyLogin({
+	providerLabel: "Together",
+	authUrl: "https://api.together.xyz/settings/api-keys",
+	instructions: "Copy your API key from the Together dashboard",
+	promptMessage: "Paste your Together API key",
+	placeholder: "sk-...",
+	validation: {
+		kind: "chat-completions",
+		provider: "together",
+		baseUrl: "https://api.together.xyz/v1",
+		model: "moonshotai/Kimi-K2.5",
+	},
+});

package/src/utils/oauth/types.ts

@@ -0,0 +1,94 @@
+export type OAuthCredentials = {
+	refresh: string;
+	access: string;
+	expires: number;
+	enterpriseUrl?: string;
+	projectId?: string;
+	email?: string;
+	accountId?: string;
+};
+
+export type OAuthProvider =
+	| "alibaba-coding-plan"
+	| "anthropic"
+	| "cerebras"
+	| "cloudflare-ai-gateway"
+	| "cursor"
+	| "deepseek"
+	| "fireworks"
+	| "firepass"
+	| "github-copilot"
+	| "google-gemini-cli"
+	| "google-antigravity"
+	| "gitlab-duo"
+	| "huggingface"
+	| "kimi-code"
+	| "kilo"
+	| "kagi"
+	| "litellm"
+	| "lm-studio"
+	| "minimax-code"
+	| "minimax-code-cn"
+	| "moonshot"
+	| "nvidia"
+	| "nanogpt"
+	| "ollama"
+	| "ollama-cloud"
+	| "openai-codex"
+	| "openai-codex-device"
+	| "opencode-go"
+	| "opencode-zen"
+	| "parallel"
+	| "perplexity"
+	| "qianfan"
+	| "qwen-portal"
+	| "synthetic"
+	| "tavily"
+	| "together"
+	| "venice"
+	| "vercel-ai-gateway"
+	| "vllm"
+	| "xiaomi"
+	| "zenmux"
+	| "zai";
+
+export type OAuthProviderId = OAuthProvider | (string & {});
+
+export type OAuthPrompt = {
+	message: string;
+	placeholder?: string;
+	allowEmpty?: boolean;
+};
+
+export type OAuthAuthInfo = {
+	url: string;
+	instructions?: string;
+};
+
+export interface OAuthProviderInfo {
+	id: OAuthProviderId;
+	name: string;
+	available: boolean;
+}
+
+export interface OAuthController {
+	onAuth?(info: OAuthAuthInfo): void;
+	onProgress?(message: string): void;
+	onManualCodeInput?(): Promise<string>;
+	onPrompt?(prompt: OAuthPrompt): Promise<string>;
+	signal?: AbortSignal;
+}
+
+export interface OAuthLoginCallbacks extends OAuthController {
+	onAuth: (info: OAuthAuthInfo) => void;
+	onPrompt: (prompt: OAuthPrompt) => Promise<string>;
+}
+
+export interface OAuthProviderInterface {
+	readonly id: OAuthProviderId;
+	readonly name: string;
+	readonly sourceId?: string;
+	login(callbacks: OAuthLoginCallbacks): Promise<OAuthCredentials | string>;
+	refreshToken?(credentials: OAuthCredentials): Promise<OAuthCredentials>;
+	getApiKey?(credentials: OAuthCredentials): string;
+}

package/src/utils/oauth/venice.ts

@@ -0,0 +1,59 @@
+/**
+ * Venice login flow.
+ *
+ * Venice provides OpenAI-compatible models via https://api.venice.ai/api/v1.
+ *
+ * This is not OAuth - it's a simple API key flow:
+ * 1. Open browser to Venice API key settings
+ * 2. User copies their API key
+ * 3. User pastes the API key into the CLI
+ */
+
+import { validateOpenAICompatibleApiKey } from "./api-key-validation";
+import type { OAuthController } from "./types";
+
+const AUTH_URL = "https://venice.ai/settings/api";
+const API_BASE_URL = "https://api.venice.ai/api/v1";
+const VALIDATION_MODEL = "qwen3-4b";
+
+/**
+ * Login to Venice.
+ *
+ * Opens browser to API keys page, prompts user to paste their API key.
+ * Returns the API key directly (not OAuthCredentials - this isn't OAuth).
+ */
+export async function loginVenice(options: OAuthController): Promise<string> {
+	if (!options.onPrompt) {
+		throw new Error("Venice login requires onPrompt callback");
+	}
+
+	options.onAuth?.({
+		url: AUTH_URL,
+		instructions: "Copy your API key from the Venice dashboard",
+	});
+
+	const apiKey = await options.onPrompt({
+		message: "Paste your Venice API key",
+		placeholder: "vapi_...",
+	});
+
+	if (options.signal?.aborted) {
+		throw new Error("Login cancelled");
+	}
+
+	const trimmed = apiKey.trim();
+	if (!trimmed) {
+		throw new Error("API key is required");
+	}
+
+	options.onProgress?.("Validating API key...");
+	await validateOpenAICompatibleApiKey({
+		provider: "Venice",
+		apiKey: trimmed,
+		baseUrl: API_BASE_URL,
+		model: VALIDATION_MODEL,
+		signal: options.signal,
+	});
+
+	return trimmed;
+}

package/src/utils/oauth/vercel-ai-gateway.ts

@@ -0,0 +1,47 @@
+/**
+ * Vercel AI Gateway login flow.
+ *
+ * Vercel AI Gateway proxies upstream model providers through a unified endpoint.
+ *
+ * This is not OAuth - it's a simple API key flow:
+ * 1. Open Vercel AI Gateway docs
+ * 2. User copies their API key
+ * 3. User pastes the API key into the CLI
+ */
+
+import type { OAuthController } from "./types";
+
+const AUTH_URL = "https://vercel.com/d?to=%2F%5Bteam%5D%2F%7E%2Fai-gateway%2Fapi-keys&title=AI+Gateway+API+Keys";
+
+/**
+ * Login to Vercel AI Gateway.
+ *
+ * Opens browser to Vercel AI Gateway docs and prompts for an API key.
+ * Returns the API key directly (not OAuthCredentials - this isn't OAuth).
+ */
+export async function loginVercelAiGateway(options: OAuthController): Promise<string> {
+	if (!options.onPrompt) {
+		throw new Error("Vercel AI Gateway login requires onPrompt callback");
+	}
+
+	options.onAuth?.({
+		url: AUTH_URL,
+		instructions: "Copy your Vercel AI Gateway API key from the Vercel dashboard",
+	});
+
+	const apiKey = await options.onPrompt({
+		message: "Paste your Vercel AI Gateway API key",
+		placeholder: "vck_...",
+	});
+
+	if (options.signal?.aborted) {
+		throw new Error("Login cancelled");
+	}
+
+	const trimmed = apiKey.trim();
+	if (!trimmed) {
+		throw new Error("API key is required");
+	}
+
+	return trimmed;
+}

package/src/utils/oauth/vllm.ts

@@ -0,0 +1,40 @@
+/**
+ * vLLM login flow.
+ *
+ * vLLM is commonly self-hosted with an OpenAI-compatible API at a local base URL.
+ * Some deployments require a bearer token, others allow unauthenticated access.
+ *
+ * This flow stores an API-key-style credential used by `/login` and auth storage.
+ */
+
+import type { OAuthController, OAuthProvider } from "./types";
+
+const PROVIDER_ID: OAuthProvider = "vllm";
+const AUTH_URL = "https://docs.vllm.ai/en/latest/serving/openai_compatible_server.html";
+const DEFAULT_LOCAL_BASE_URL = "http://127.0.0.1:8000/v1";
+const DEFAULT_LOCAL_TOKEN = "vllm-local";
+/**
+ * Login to vLLM.
+ *
+ * Opens vLLM OpenAI-compatible auth docs, prompts for an optional token,
+ * and returns a stored key value.
+ */
+export async function loginVllm(options: OAuthController): Promise<string> {
+	if (!options.onPrompt) {
+		throw new Error(`${PROVIDER_ID} login requires onPrompt callback`);
+	}
+	options.onAuth?.({
+		url: AUTH_URL,
+		instructions: `Paste your vLLM API key if your server requires auth. Leave empty for local no-auth mode (default base URL: ${DEFAULT_LOCAL_BASE_URL}).`,
+	});
+	const apiKey = await options.onPrompt({
+		message: "Paste your vLLM API key (optional for local no-auth)",
+		placeholder: DEFAULT_LOCAL_TOKEN,
+		allowEmpty: true,
+	});
+	if (options.signal?.aborted) {
+		throw new Error("Login cancelled");
+	}
+	const trimmed = apiKey.trim();
+	return trimmed || DEFAULT_LOCAL_TOKEN;
+}