@claude-flow/security 3.0.0-alpha.1 → 3.0.0-alpha.11

package/src/oauth/browser.ts

@@ -0,0 +1,58 @@
+/**
+ * Opens the system default browser for the `ruflo auth login` flow. A
+ * TypeScript port of meta-proxy's `src/oauth/browser.rs`.
+ *
+ * Deliberately does NOT go through `SafeExecutor.execute()`: `SafeExecutor`'s
+ * blocked-argument patterns (`safe-executor.ts`'s `DEFAULT_BLOCKED_PATTERNS`)
+ * include a bare `&`, which is meant to catch shell-metacharacter injection in
+ * command-line-style arguments — but it also appears in every real OAuth
+ * authorize URL's query string (`?a=1&b=2&...`), so passing one through would
+ * false-positive-reject on every real invocation. That blocklist is the wrong
+ * tool for a URL argument: with `shell: false` (used here, same as
+ * `SafeExecutor`), a single argv element containing `&` is inert — there's no
+ * shell to interpret it. The actual safety property that matters is "the URL
+ * was constructed by us from validated components, never from raw external
+ * input" (this module's `authorizeUrl()` in `client.ts` is the only caller),
+ * which `assertSafeUrl` below checks directly instead.
+ *
+ * @module v3/security/oauth/browser
+ */
+
+import { execFile } from 'node:child_process';
+
+/** Throws if `url` isn't a well-formed https/http URL — the one check that matters here. */
+function assertSafeUrl(url: string): void {
+  const parsed = new URL(url); // throws on malformed input
+  if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+    throw new Error(`refusing to open non-http(s) URL scheme: ${parsed.protocol}`);
+  }
+}
+
+/**
+ * Attempts to open `url` in the system default browser. Resolves whether or
+ * not a browser window actually appeared — this cannot be confirmed in
+ * general, which is why the caller always also prints the URL as a fallback.
+ */
+export function openBrowser(url: string): Promise<void> {
+  assertSafeUrl(url);
+
+  const { cmd, args } = browserCommand(url);
+
+  return new Promise((resolve) => {
+    execFile(cmd, args, { shell: false, windowsHide: true }, () => resolve());
+  });
+}
+
+/** Pure command selection, exported for platform regression tests. */
+export function browserCommand(url: string, platform: NodeJS.Platform = process.platform): { cmd: string; args: string[] } {
+  assertSafeUrl(url);
+  if (platform === 'darwin') {
+    return { cmd: 'open', args: [url] };
+  } else if (platform === 'win32') {
+    // cmd.exe treats OAuth query-string `&` separators as command operators,
+    // truncating the URL before client_id. Use the URL handler without a shell.
+    return { cmd: 'rundll32.exe', args: ['url.dll,FileProtocolHandler', url] };
+  } else {
+    return { cmd: 'xdg-open', args: [url] };
+  }
+}

package/src/oauth/callback-server.ts

@@ -0,0 +1,97 @@
+/**
+ * Ephemeral-port localhost callback server for the browser-based OAuth flow
+ * (ADR-306). A minimal single-request HTTP server — deliberately not a full
+ * framework for one GET route that lives for one request and then shuts
+ * down. A TypeScript port of meta-proxy's `src/oauth/callback_server.rs`.
+ *
+ * @module v3/security/oauth/callback-server
+ */
+
+import { createServer, type Server } from 'node:http';
+import type { AddressInfo } from 'node:net';
+
+export interface CallbackResult {
+  code: string | null;
+  state: string | null;
+  error: string | null;
+}
+
+const SUCCESS_PAGE = `<html>
+<body style="background:#0a0a0a; color:#f5f5f5; font-family:sans-serif;
+    display:flex; align-items:center; justify-content:center;
+    height:100vh; margin:0;">
+    <div style="text-align:center;">
+    <h1>&#10003; ruflo login successful</h1>
+    <p>You can close this tab and return to your terminal.</p>
+    </div>
+</body>
+</html>`;
+
+const DEFAULT_TIMEOUT_MS = 5 * 60 * 1000; // 5 minutes, matches meta-proxy's CALLBACK_TIMEOUT
+
+export class CallbackTimeoutError extends Error {
+  constructor() {
+    super('timed out waiting for OAuth callback');
+    this.name = 'CallbackTimeoutError';
+  }
+}
+
+export class CallbackServer {
+  private constructor(
+    private readonly server: Server,
+    public readonly redirectUri: string,
+    public readonly port: number,
+  ) {}
+
+  /**
+   * Binds `127.0.0.1:0` (OS-assigned ephemeral port) and returns the server
+   * plus the exact `redirect_uri` to send in the authorize request — must be
+   * the `http://127.0.0.1:<port>/oauth/callback` shape identity's
+   * `validate_redirect_uri` accepts.
+   */
+  static async bind(): Promise<CallbackServer> {
+    return new Promise((resolve, reject) => {
+      const server = createServer();
+      server.once('error', reject);
+      server.listen(0, '127.0.0.1', () => {
+        server.removeListener('error', reject);
+        const addr = server.address() as AddressInfo;
+        const redirectUri = `http://127.0.0.1:${addr.port}/oauth/callback`;
+        resolve(new CallbackServer(server, redirectUri, addr.port));
+      });
+    });
+  }
+
+  /**
+   * Waits for exactly one `GET /oauth/callback?...` request, replies with the
+   * browser success page, closes the server, and returns the parsed query
+   * parameters. Times out after `waitForMs` so a login attempt the user
+   * abandons in the browser doesn't hang the CLI forever.
+   */
+  async awaitCallback(waitForMs = DEFAULT_TIMEOUT_MS): Promise<CallbackResult> {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this.server.close();
+        reject(new CallbackTimeoutError());
+      }, waitForMs);
+
+      this.server.once('request', (req, res) => {
+        clearTimeout(timer);
+        const url = new URL(req.url ?? '/oauth/callback', 'http://127.0.0.1');
+        const result: CallbackResult = {
+          code: url.searchParams.get('code'),
+          state: url.searchParams.get('state'),
+          error: url.searchParams.get('error'),
+        };
+        res.writeHead(200, {
+          'content-type': 'text/html; charset=utf-8',
+          connection: 'close',
+        });
+        res.end(SUCCESS_PAGE, () => {
+          this.server.close();
+          resolve(result);
+        });
+      });
+    });
+  }
+}

package/src/oauth/client.ts

@@ -0,0 +1,153 @@
+/**
+ * HTTP client for `auth.cognitum.one`'s OAuth surface (ADR-306): authorize
+ * URL construction, `POST /oauth/token` (`authorization_code` and
+ * `refresh_token` grants), and `POST /v1/oauth/code-exchange` (OOB fallback).
+ *
+ * A TypeScript port of meta-proxy's `src/oauth/client.rs`
+ * (cognitum-one/meta-proxy) — same base URL, same endpoints, same
+ * form/query parameter names, confirmed live 2026-07-16 (a real
+ * `GET /oauth/authorize?...&client_id=meta-proxy&redirect_uri=<ruflo-controlled
+ * loopback>` returns a working consent page, not a redirect_uri-mismatch
+ * error — so this client reuses meta-proxy's registered `client_id` rather
+ * than requiring a new one).
+ *
+ * Deliberately NOT `api.cognitum.one/v1/auth/*` — that's what ruflo's own
+ * checked-in OpenAPI spec (v3/docs/api/cognitum-v1.openapi.yaml, ADR-308)
+ * describes, but it does not match what the real identity server serves.
+ * This client targets the proven, live surface instead.
+ *
+ * @module v3/security/oauth/client
+ */
+
+export const CLIENT_ID = 'meta-proxy';
+export const SCOPE = 'inference';
+/** RFC 8252 out-of-band sentinel — the OOB/manual-paste flow's `redirect_uri`. */
+export const OOB_REDIRECT_URI = 'urn:ietf:wg:oauth:2.0:oob';
+
+function authBaseUrl(): string {
+  const override = process.env.COGNITUM_AUTH_URL;
+  return override && override.trim() ? override : 'https://auth.cognitum.one';
+}
+
+export interface TokenResponse {
+  access_token: string;
+  token_type: string;
+  account_email?: string;
+  refresh_token?: string;
+  expires_in?: number;
+}
+
+interface OAuthErrorBody {
+  error: string;
+  error_description: string;
+}
+
+export class OAuthError extends Error {
+  constructor(
+    message: string,
+    public readonly code: 'network' | 'protocol' | 'unexpected_shape',
+    public readonly oauthError?: string,
+    public readonly oauthDescription?: string,
+  ) {
+    super(message);
+    this.name = 'OAuthError';
+  }
+}
+
+/** Builds the `/oauth/authorize` URL for the standard loopback-redirect flow. */
+export function authorizeUrl(redirectUri: string, state: string, codeChallenge: string): string {
+  const url = new URL(`${authBaseUrl()}/oauth/authorize`);
+  url.searchParams.set('response_type', 'code');
+  url.searchParams.set('client_id', CLIENT_ID);
+  url.searchParams.set('redirect_uri', redirectUri);
+  url.searchParams.set('scope', SCOPE);
+  url.searchParams.set('state', state);
+  url.searchParams.set('code_challenge', codeChallenge);
+  url.searchParams.set('code_challenge_method', 'S256');
+  return url.toString();
+}
+
+async function parseTokenResponse(resp: Response): Promise<TokenResponse> {
+  if (resp.ok) {
+    try {
+      return (await resp.json()) as TokenResponse;
+    } catch {
+      throw new OAuthError('unexpected response shape from the server', 'unexpected_shape');
+    }
+  }
+  try {
+    const body = (await resp.json()) as OAuthErrorBody;
+    throw new OAuthError(
+      `oauth error: ${body.error} — ${body.error_description}`,
+      'protocol',
+      body.error,
+      body.error_description,
+    );
+  } catch (e) {
+    if (e instanceof OAuthError) throw e;
+    throw new OAuthError('unexpected response shape from the server', 'unexpected_shape');
+  }
+}
+
+async function postForm(path: string, form: Record<string, string>, base = authBaseUrl()): Promise<TokenResponse> {
+  let resp: Response;
+  try {
+    resp = await fetch(`${base}${path}`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/x-www-form-urlencoded' },
+      body: new URLSearchParams(form).toString(),
+    });
+  } catch (e) {
+    throw new OAuthError(`network error: ${e instanceof Error ? e.message : String(e)}`, 'network');
+  }
+  return parseTokenResponse(resp);
+}
+
+/** `POST /oauth/token` with `grant_type=authorization_code`. */
+export async function exchangeCode(
+  code: string,
+  codeVerifier: string,
+  redirectUri: string,
+  base = authBaseUrl(),
+): Promise<TokenResponse> {
+  return postForm(
+    '/oauth/token',
+    { grant_type: 'authorization_code', code, code_verifier: codeVerifier, client_id: CLIENT_ID, redirect_uri: redirectUri },
+    base,
+  );
+}
+
+/**
+ * `POST /oauth/token` with `grant_type=refresh_token`. identity rotates
+ * refresh tokens with reuse detection: presenting a refresh token returns a
+ * NEW refresh token and revokes the old one, and re-presenting a spent one
+ * revokes the whole session family. Callers MUST persist the returned
+ * `refresh_token` atomically before using the new access token, and must
+ * never retry a failed refresh with the same token.
+ */
+export async function refreshToken(refreshTokenValue: string, base = authBaseUrl()): Promise<TokenResponse> {
+  return postForm('/oauth/token', { grant_type: 'refresh_token', refresh_token: refreshTokenValue, client_id: CLIENT_ID }, base);
+}
+
+/**
+ * `POST /v1/oauth/code-exchange` — the OOB manual-entry fallback for
+ * headless/SSH/container environments where no browser round-trip to
+ * `127.0.0.1` is reachable.
+ */
+export async function exchangeManualCode(
+  code: string,
+  codeVerifier: string,
+  base = authBaseUrl(),
+): Promise<TokenResponse> {
+  let resp: Response;
+  try {
+    resp = await fetch(`${base}/v1/oauth/code-exchange`, {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ code, code_verifier: codeVerifier, client_id: CLIENT_ID }),
+    });
+  } catch (e) {
+    throw new OAuthError(`network error: ${e instanceof Error ? e.message : String(e)}`, 'network');
+  }
+  return parseTokenResponse(resp);
+}

package/src/oauth/pkce.ts

@@ -0,0 +1,45 @@
+/**
+ * OAuth 2.0 + PKCE (RFC 7636) client-side generation (ADR-306).
+ *
+ * A TypeScript port of meta-proxy's `src/oauth/pkce.rs` (cognitum-one/meta-proxy,
+ * itself ported from `dashboard/apps/cli/src/pkce.rs`) so a verifier generated
+ * here validates against the same `services/identity` authorization server
+ * meta-proxy already talks to successfully — same byte lengths, same encoding,
+ * same hash. Intentionally duplicated rather than imported from
+ * `@claude-flow/mcp/src/oauth.ts` (a different, unrelated OAuth client in this
+ * monorepo) — ADR-306 assigns PKCE ownership to this package specifically.
+ *
+ * @module v3/security/oauth/pkce
+ */
+
+import { randomBytes, createHash } from 'crypto';
+
+export interface PkceRequest {
+  state: string;
+  codeVerifier: string;
+  codeChallenge: string;
+}
+
+/**
+ * 32 random bytes, base64url-encoded (no padding) — comfortably within RFC
+ * 7636's 43-128 character verifier length requirement (32 bytes -> 43 chars).
+ * Matches the Rust port's `random_url_safe_token(32)` exactly.
+ */
+function randomUrlSafeToken(byteLen: number): string {
+  return randomBytes(byteLen).toString('base64url');
+}
+
+export function challengeFromVerifier(verifier: string): string {
+  return createHash('sha256').update(verifier).digest('base64url');
+}
+
+/**
+ * Generates a fresh `state` + PKCE verifier/challenge pair for one login
+ * attempt.
+ */
+export function generate(): PkceRequest {
+  const state = randomUrlSafeToken(32);
+  const codeVerifier = randomUrlSafeToken(32);
+  const codeChallenge = challengeFromVerifier(codeVerifier);
+  return { state, codeVerifier, codeChallenge };
+}