runline 0.3.0 → 0.3.1

package/dist/core/oauth.d.ts

@@ -1,13 +1,26 @@
 /**
  * Generic OAuth2 authorization-code flow.
  *
- * Runs the browser login dance for any plugin that declares
- * `setOAuth(config)`: opens the provider's consent URL, catches
- * the redirect on a local port, exchanges the code for tokens,
- * and returns `{accessToken, refreshToken, expiresAt, scope}`.
+ * Two surfaces:
  *
- * Provider-agnostic — the caller (the `auth` CLI command) supplies
- * the plugin's `OAuthConfig` along with the client credentials.
+ * 1. `runOAuth(config, {clientId, clientSecret})` — end-to-end CLI
+ *    flow. Opens the browser, captures the redirect on a pinned
+ *    localhost port, exchanges the code, returns tokens. Used by
+ *    `runline auth <plugin>`.
+ *
+ * 2. Primitives for callers that can't run a local callback server
+ *    (hosted apps, GUIs, anywhere the user's browser doesn't talk
+ *    back to the process driving the flow):
+ *
+ *      - `generatePKCE()` — S256 verifier + challenge
+ *      - `buildAuthUrl(config, opts)` — assemble the consent URL
+ *      - `exchangeAuthCode(config, opts)` — POST to the token
+ *        endpoint, get back tokens
+ *
+ *    The caller orchestrates: generates state + PKCE, builds the
+ *    URL, shows it to the user, receives the code back however it
+ *    wants (redirect-URI paste, browser popup with postMessage,
+ *    public HTTPS callback, …), calls exchangeAuthCode.
  */
 import type { OAuthConfig } from "../plugin/types.js";
 /**
@@ -19,6 +32,8 @@ import type { OAuthConfig } from "../plugin/types.js";
  * URI with the provider after changing it).
  */
 export declare const OAUTH_CALLBACK_PORT: number;
+/** Canonical localhost redirect URI for CLI-based flows. */
+export declare const OAUTH_CALLBACK_URI: string;
 export interface OAuthTokens {
     accessToken: string;
     refreshToken: string;
@@ -38,9 +53,50 @@ export interface RunOAuthOptions {
     /** Override the browser launcher. Defaults to OS-appropriate command. */
     openBrowser?: (url: string) => void;
 }
+export interface BuildAuthUrlOptions {
+    clientId: string;
+    redirectUri: string;
+    state: string;
+    /** S256 code challenge. Pass alongside a verifier kept by the driver. */
+    pkceChallenge?: string;
+}
+export interface ExchangeCodeOptions {
+    clientId: string;
+    clientSecret: string;
+    code: string;
+    redirectUri: string;
+    /** PKCE verifier matching the challenge sent on the auth URL. */
+    codeVerifier?: string;
+}
+export interface PKCEPair {
+    verifier: string;
+    /** Base64url SHA-256 of the verifier, for `code_challenge_method=S256`. */
+    challenge: string;
+}
+/**
+ * Generate a PKCE verifier and its SHA-256 challenge. The verifier
+ * stays with the driver until the token exchange; the challenge
+ * goes on the auth URL.
+ */
+export declare function generatePKCE(): PKCEPair;
+/**
+ * Assemble the authorization URL for a plugin's OAuth config.
+ * Pass `pkceChallenge` to include PKCE; omit for plain auth-code.
+ */
+export declare function buildAuthUrl(config: OAuthConfig, opts: BuildAuthUrlOptions): string;
+/**
+ * Exchange an authorization code for tokens. Throws if the
+ * provider doesn't return a refresh_token — that's almost always a
+ * misconfiguration (e.g. missing `access_type=offline` for Google).
+ */
+export declare function exchangeAuthCode(config: OAuthConfig, opts: ExchangeCodeOptions): Promise<OAuthTokens>;
 /**
  * Run the full OAuth2 authorization-code flow end-to-end.
  * Resolves with the exchanged tokens once the user completes the
  * browser consent and the token endpoint returns a refresh token.
+ *
+ * Uses the pinned localhost callback port. If you can't run a
+ * local callback server, drive the flow yourself with
+ * `buildAuthUrl` + `exchangeAuthCode`.
  */
 export declare function runOAuth(config: OAuthConfig, options: RunOAuthOptions): Promise<OAuthTokens>;

package/dist/core/oauth.js

@@ -1,15 +1,29 @@
 /**
  * Generic OAuth2 authorization-code flow.
  *
- * Runs the browser login dance for any plugin that declares
- * `setOAuth(config)`: opens the provider's consent URL, catches
- * the redirect on a local port, exchanges the code for tokens,
- * and returns `{accessToken, refreshToken, expiresAt, scope}`.
+ * Two surfaces:
  *
- * Provider-agnostic — the caller (the `auth` CLI command) supplies
- * the plugin's `OAuthConfig` along with the client credentials.
+ * 1. `runOAuth(config, {clientId, clientSecret})` — end-to-end CLI
+ *    flow. Opens the browser, captures the redirect on a pinned
+ *    localhost port, exchanges the code, returns tokens. Used by
+ *    `runline auth <plugin>`.
+ *
+ * 2. Primitives for callers that can't run a local callback server
+ *    (hosted apps, GUIs, anywhere the user's browser doesn't talk
+ *    back to the process driving the flow):
+ *
+ *      - `generatePKCE()` — S256 verifier + challenge
+ *      - `buildAuthUrl(config, opts)` — assemble the consent URL
+ *      - `exchangeAuthCode(config, opts)` — POST to the token
+ *        endpoint, get back tokens
+ *
+ *    The caller orchestrates: generates state + PKCE, builds the
+ *    URL, shows it to the user, receives the code back however it
+ *    wants (redirect-URI paste, browser popup with postMessage,
+ *    public HTTPS callback, …), calls exchangeAuthCode.
  */
 import { spawn } from "node:child_process";
+import { createHash, randomBytes } from "node:crypto";
 import { createServer, } from "node:http";
 /**
  * Fixed callback port for OAuth redirects. Pinned so users can
@@ -28,40 +42,116 @@ export const OAUTH_CALLBACK_PORT = (() => {
     }
     return 47823;
 })();
+/** Canonical localhost redirect URI for CLI-based flows. */
+export const OAUTH_CALLBACK_URI = `http://127.0.0.1:${OAUTH_CALLBACK_PORT}/callback`;
+// ─── Primitives ──────────────────────────────────────────────────
+/**
+ * Generate a PKCE verifier and its SHA-256 challenge. The verifier
+ * stays with the driver until the token exchange; the challenge
+ * goes on the auth URL.
+ */
+export function generatePKCE() {
+    const verifier = base64urlEncode(randomBytes(32));
+    const challenge = base64urlEncode(createHash("sha256").update(verifier).digest());
+    return { verifier, challenge };
+}
+/**
+ * Assemble the authorization URL for a plugin's OAuth config.
+ * Pass `pkceChallenge` to include PKCE; omit for plain auth-code.
+ */
+export function buildAuthUrl(config, opts) {
+    const url = new URL(config.authUrl);
+    url.searchParams.set("client_id", opts.clientId);
+    url.searchParams.set("redirect_uri", opts.redirectUri);
+    url.searchParams.set("response_type", "code");
+    url.searchParams.set("scope", config.scopes.join(" "));
+    url.searchParams.set("state", opts.state);
+    if (opts.pkceChallenge) {
+        url.searchParams.set("code_challenge", opts.pkceChallenge);
+        url.searchParams.set("code_challenge_method", "S256");
+    }
+    for (const [k, v] of Object.entries(config.authParams ?? {})) {
+        url.searchParams.set(k, v);
+    }
+    return url.toString();
+}
+/**
+ * Exchange an authorization code for tokens. Throws if the
+ * provider doesn't return a refresh_token — that's almost always a
+ * misconfiguration (e.g. missing `access_type=offline` for Google).
+ */
+export async function exchangeAuthCode(config, opts) {
+    const body = new URLSearchParams({
+        code: opts.code,
+        client_id: opts.clientId,
+        client_secret: opts.clientSecret,
+        redirect_uri: opts.redirectUri,
+        grant_type: "authorization_code",
+    });
+    if (opts.codeVerifier)
+        body.set("code_verifier", opts.codeVerifier);
+    const res = await fetch(config.tokenUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: body.toString(),
+    });
+    if (!res.ok) {
+        throw new Error(`OAuth: token exchange failed (${res.status}): ${await res.text()}`);
+    }
+    const data = (await res.json());
+    if (!data.refresh_token) {
+        throw new Error("OAuth: provider did not return a refresh token. This usually means a prior consent is cached — revoke access with the provider and retry. For Google, set authParams: { access_type: 'offline', prompt: 'consent' }.");
+    }
+    return {
+        accessToken: data.access_token,
+        refreshToken: data.refresh_token,
+        expiresAt: Date.now() + data.expires_in * 1000,
+        scope: data.scope,
+        tokenType: data.token_type,
+    };
+}
+// ─── End-to-end CLI flow ─────────────────────────────────────────
 /**
  * Run the full OAuth2 authorization-code flow end-to-end.
  * Resolves with the exchanged tokens once the user completes the
  * browser consent and the token endpoint returns a refresh token.
+ *
+ * Uses the pinned localhost callback port. If you can't run a
+ * local callback server, drive the flow yourself with
+ * `buildAuthUrl` + `exchangeAuthCode`.
  */
 export async function runOAuth(config, options) {
-    const port = OAUTH_CALLBACK_PORT;
-    const redirectUri = `http://127.0.0.1:${port}/callback`;
+    const redirectUri = OAUTH_CALLBACK_URI;
     const state = randomState();
-    const authUrl = new URL(config.authUrl);
-    authUrl.searchParams.set("client_id", options.clientId);
-    authUrl.searchParams.set("redirect_uri", redirectUri);
-    authUrl.searchParams.set("response_type", "code");
-    authUrl.searchParams.set("scope", config.scopes.join(" "));
-    authUrl.searchParams.set("state", state);
-    for (const [k, v] of Object.entries(config.authParams ?? {})) {
-        authUrl.searchParams.set(k, v);
+    const { verifier, challenge } = generatePKCE();
+    const authUrl = buildAuthUrl(config, {
+        clientId: options.clientId,
+        redirectUri,
+        state,
+        pkceChallenge: challenge,
+    });
+    // Always make the URL visible. `onAuthUrl` is the preferred
+    // channel (CLI formats it inline); if absent, fall back to
+    // stderr so headless invocations (SSH, CI) aren't left waiting
+    // on a browser that never opens.
+    if (options.onAuthUrl) {
+        options.onAuthUrl(authUrl);
     }
-    options.onAuthUrl?.(authUrl.toString());
-    const open = options.openBrowser ?? defaultOpenBrowser;
-    open(authUrl.toString());
-    const { code } = await captureCode(port, state);
-    const tokens = await exchangeCode(config.tokenUrl, code, options.clientId, options.clientSecret, redirectUri);
-    if (!tokens.refresh_token) {
-        throw new Error("OAuth: provider did not return a refresh token. This usually means a prior consent is cached — revoke access with the provider and retry. For Google, set authParams: { access_type: 'offline', prompt: 'consent' }.");
+    else {
+        console.error(`Open this URL to authorize:\n  ${authUrl}`);
     }
-    return {
-        accessToken: tokens.access_token,
-        refreshToken: tokens.refresh_token,
-        expiresAt: Date.now() + tokens.expires_in * 1000,
-        scope: tokens.scope,
-        tokenType: tokens.token_type,
-    };
+    const open = options.openBrowser ?? defaultOpenBrowser;
+    open(authUrl);
+    const { code } = await captureCode(OAUTH_CALLBACK_PORT, state);
+    return exchangeAuthCode(config, {
+        clientId: options.clientId,
+        clientSecret: options.clientSecret,
+        code,
+        redirectUri,
+        codeVerifier: verifier,
+    });
 }
+// ─── Local callback server ───────────────────────────────────────
 function captureCode(port, expectedState) {
     return new Promise((resolve, reject) => {
         const server = createServer((req, res) => {
@@ -106,26 +196,16 @@ function captureCode(port, expectedState) {
         server.listen(port, "127.0.0.1");
     });
 }
-async function exchangeCode(tokenUrl, code, clientId, clientSecret, redirectUri) {
-    const body = new URLSearchParams({
-        code,
-        client_id: clientId,
-        client_secret: clientSecret,
-        redirect_uri: redirectUri,
-        grant_type: "authorization_code",
-    });
-    const res = await fetch(tokenUrl, {
-        method: "POST",
-        headers: { "Content-Type": "application/x-www-form-urlencoded" },
-        body: body.toString(),
-    });
-    if (!res.ok) {
-        throw new Error(`OAuth: token exchange failed (${res.status}): ${await res.text()}`);
-    }
-    return (await res.json());
-}
+// ─── Helpers ─────────────────────────────────────────────────────
 function randomState() {
-    return (Math.random().toString(36).slice(2) + Math.random().toString(36).slice(2));
+    return base64urlEncode(randomBytes(16));
+}
+function base64urlEncode(buf) {
+    return buf
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/, "");
 }
 function defaultOpenBrowser(url) {
     const cmd = process.platform === "darwin"

package/dist/index.d.ts

@@ -3,8 +3,8 @@ export type { RunlineConfig } from "./config/types.js";
 export { DEFAULT_CONFIG } from "./config/types.js";
 export type { EngineOptions, ExecuteResult } from "./core/engine.js";
 export { ExecutionEngine } from "./core/engine.js";
-export type { OAuthTokens, RunOAuthOptions } from "./core/oauth.js";
-export { OAUTH_CALLBACK_PORT, runOAuth } from "./core/oauth.js";
+export type { BuildAuthUrlOptions, ExchangeCodeOptions, OAuthTokens, PKCEPair, RunOAuthOptions, } from "./core/oauth.js";
+export { buildAuthUrl, exchangeAuthCode, generatePKCE, OAUTH_CALLBACK_PORT, OAUTH_CALLBACK_URI, runOAuth, } from "./core/oauth.js";
 export type { ActionDefinition, PluginFunction, RunlinePluginAPI, SchemaField, } from "./plugin/api.js";
 export { createPluginAPI, isPluginFunction, resolvePluginExport, } from "./plugin/api.js";
 export type { InstalledPlugin, PluginSource } from "./plugin/installer.js";

package/dist/index.js

@@ -1,7 +1,7 @@
 export { addConnection, findConfigDir, getConnection, loadConfig, removeConnection, saveConfig, updateConnectionConfig, } from "./config/loader.js";
 export { DEFAULT_CONFIG } from "./config/types.js";
 export { ExecutionEngine } from "./core/engine.js";
-export { OAUTH_CALLBACK_PORT, runOAuth } from "./core/oauth.js";
+export { buildAuthUrl, exchangeAuthCode, generatePKCE, OAUTH_CALLBACK_PORT, OAUTH_CALLBACK_URI, runOAuth, } from "./core/oauth.js";
 export { createPluginAPI, isPluginFunction, resolvePluginExport, } from "./plugin/api.js";
 export { installPlugin, listInstalled, parsePluginSource, removePlugin, } from "./plugin/installer.js";
 export { discoverPlugins, loadAllPlugins, loadPluginFromPath, loadPluginsFromConfig, } from "./plugin/loader.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "runline",
-  "version": "0.3.0",
+  "version": "0.3.1",
   "description": "Code mode for agents — turn any API or command into a callable action",
   "type": "module",
   "main": "dist/index.js",