runline 0.3.0 → 0.3.2

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/dist/plugin/loader.d.ts

@@ -1,11 +1,33 @@
 import type { PluginDef } from "./types.js";
 export declare function loadPluginFromPath(path: string): Promise<PluginDef>;
 export declare function loadPluginsFromConfig(configDir: string): Promise<PluginDef[]>;
+export interface DiscoverOptions {
+    /**
+     * When supplied, only built-in plugins whose name is in this set
+     * are loaded. Plugins discovered in the project dir, `plugins.json`,
+     * or `~/.runline/plugins` are always loaded — users put them there
+     * deliberately — but the 188 bundled builtins are gated so agents
+     * don't see every possible action regardless of configuration.
+     *
+     * Omit to load every builtin (CLI default: `runline actions` etc.
+     * surfaces the full catalog).
+     */
+    builtinAllowlist?: Set<string> | null;
+    /**
+     * Override the directory where bundled plugins live. Default is
+     * `<loader>/../plugins`, which resolves to `dist/plugins/` at
+     * runtime. Tests set this so they can exercise allowlist logic
+     * without depending on the real bundled catalog.
+     */
+    builtinDir?: string;
+}
+/** Default path to the bundled plugin directory. */
+export declare function defaultBuiltinDir(): string;
 /**
  * Discover and return all plugins from a config directory and global dir.
  * Does NOT mutate any global state.
  */
-export declare function discoverPlugins(configDir?: string | null): Promise<PluginDef[]>;
+export declare function discoverPlugins(configDir?: string | null, options?: DiscoverOptions): Promise<PluginDef[]>;
 /**
  * Load all plugins and register them into the global registry.
  * Used by the CLI.

package/dist/plugin/loader.js

@@ -118,11 +118,15 @@ export async function loadPluginsFromConfig(configDir) {
     }
     return plugins;
 }
+/** Default path to the bundled plugin directory. */
+export function defaultBuiltinDir() {
+    return join(__dirname, "..", "plugins");
+}
 /**
  * Discover and return all plugins from a config directory and global dir.
  * Does NOT mutate any global state.
  */
-export async function discoverPlugins(configDir) {
+export async function discoverPlugins(configDir, options = {}) {
     const loaded = new Set();
     const result = [];
     function addIfNew(plugin) {
@@ -144,11 +148,14 @@ export async function discoverPlugins(configDir) {
     const globalPlugins = await loadFromDirectory(globalDir);
     for (const p of globalPlugins)
         addIfNew(p);
-    // Built-in plugins shipped with the package
-    const builtinDir = join(__dirname, "..", "plugins");
+    const builtinDir = options.builtinDir ?? defaultBuiltinDir();
     const builtinPlugins = await loadFromDirectory(builtinDir);
-    for (const p of builtinPlugins)
+    for (const p of builtinPlugins) {
+        if (options.builtinAllowlist && !options.builtinAllowlist.has(p.name)) {
+            continue;
+        }
         addIfNew(p);
+    }
     return result;
 }
 /**

package/dist/sdk.d.ts

@@ -34,8 +34,26 @@ export declare class Runline {
     connections(): ConnectionConfig[];
     /**
      * Load runline from a project directory.
-     * Discovers .runline/ config and installed plugins, just like the CLI.
+     *
+     * Discovers the `.runline/` config and registers:
+     *   - every plugin dropped into `.runline/plugins/`,
+     *   - every plugin listed in `.runline/plugins.json`,
+     *   - every plugin in `~/.runline/plugins/`,
+     *   - and — from the 188 builtins shipped with the package — only
+     *     the ones named in `config.connections[].plugin`.
+     *
+     * Gating the builtins keeps `runline.actions()` scoped to what the
+     * project actually configured. Without this, a project with a
+     * single connection would still expose every bundled action to an
+     * agent, which is both noisy and a privacy problem (the agent sees
+     * surface area it has no credentials for).
+     *
+     * `options.builtinDir` is a test-only hook; production callers
+     * should rely on the default path to the bundled plugins.
+     *
      * Fully self-contained — does not mutate global state.
      */
-    static fromProject(cwd?: string): Promise<Runline | null>;
+    static fromProject(cwd?: string, options?: {
+        builtinDir?: string;
+    }): Promise<Runline | null>;
 }

package/dist/sdk.js

@@ -63,16 +63,36 @@ export class Runline {
     }
     /**
      * Load runline from a project directory.
-     * Discovers .runline/ config and installed plugins, just like the CLI.
+     *
+     * Discovers the `.runline/` config and registers:
+     *   - every plugin dropped into `.runline/plugins/`,
+     *   - every plugin listed in `.runline/plugins.json`,
+     *   - every plugin in `~/.runline/plugins/`,
+     *   - and — from the 188 builtins shipped with the package — only
+     *     the ones named in `config.connections[].plugin`.
+     *
+     * Gating the builtins keeps `runline.actions()` scoped to what the
+     * project actually configured. Without this, a project with a
+     * single connection would still expose every bundled action to an
+     * agent, which is both noisy and a privacy problem (the agent sees
+     * surface area it has no credentials for).
+     *
+     * `options.builtinDir` is a test-only hook; production callers
+     * should rely on the default path to the bundled plugins.
+     *
      * Fully self-contained — does not mutate global state.
      */
-    static async fromProject(cwd) {
+    static async fromProject(cwd, options = {}) {
         const dir = cwd ?? process.cwd();
         const configDir = findRunlineDir(dir);
         if (!configDir)
             return null;
         const config = loadConfigFrom(configDir);
-        const plugins = await discoverPlugins(configDir);
+        const builtinAllowlist = new Set(config.connections.map((c) => c.plugin));
+        const plugins = await discoverPlugins(configDir, {
+            builtinAllowlist,
+            builtinDir: options.builtinDir,
+        });
         const rl = new Runline({
             connections: config.connections,
             timeoutMs: config.timeoutMs,

package/package.json

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