@rayrun/cli 0.1.0 → 0.3.0

package/src/oauth.js

@@ -0,0 +1,599 @@
+import { atomicWrite, assertNoSymbolicLinkComponents } from './setup.js';
+// cspell:ignore nosniff rundll
+/* eslint-disable node/no-process-env -- the OAuth client intentionally uses the invoking user's Rayrun configuration */
+import {
+  Client,
+  StreamableHTTPClientTransport,
+  UnauthorizedError,
+} from '@modelcontextprotocol/client';
+import { spawn } from 'node:child_process';
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
+import { chmod, lstat, mkdir, readFile, readdir, rename, rm } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import os from 'node:os';
+import path from 'node:path';
+
+const AUTHORIZATION_TIMEOUT_MILLISECONDS = 5 * 60 * 1_000;
+const LOCK_ACQUIRE_ATTEMPTS = 5;
+const LOCK_CLAIM_REGEX = /^(active|waiting)-([A-Za-z\d_-]+)\.json$/u;
+const SESSION_VERSION = 1;
+
+const isFileSystemError = (error, code) => {
+  return error && typeof error === 'object' && 'code' in error && error.code === code;
+};
+
+const executionRoot = ({
+  environment = process.env,
+  homeDirectory = os.homedir(),
+  platform = process.platform,
+} = {}) => {
+  const configuredRoot = environment.RAYRUN_CONFIG_HOME;
+  const root = configuredRoot ?? path.join(homeDirectory, '.rayrun');
+  if (!path.isAbsolute(root)) throw new Error('RAYRUN_CONFIG_HOME must be an absolute path.');
+  if (platform === 'win32' && configuredRoot !== undefined) {
+    const relative = path.relative(homeDirectory, root);
+    if (relative === '..' || relative.startsWith(`..${path.sep}`) || path.isAbsolute(relative)) {
+      throw new Error('On Windows, RAYRUN_CONFIG_HOME must stay inside the current user profile.');
+    }
+  }
+  return path.join(root, 'execution');
+};
+
+const endpointKey = (endpoint) => createHash('sha256').update(endpoint).digest('hex');
+
+const sessionPath = (endpoint, options) => {
+  return path.join(executionRoot(options), 'sessions', `${endpointKey(endpoint)}.json`);
+};
+
+const ensurePrivateDirectory = async (directory) => {
+  await assertNoSymbolicLinkComponents(directory);
+  await mkdir(directory, { mode: 0o700, recursive: true });
+  await assertNoSymbolicLinkComponents(directory);
+  await chmod(directory, 0o700);
+};
+
+const readPrivateJson = async (target, { platform = process.platform } = {}) => {
+  await assertNoSymbolicLinkComponents(target);
+
+  try {
+    const metadata = await lstat(target);
+    if (!metadata.isFile() || (platform !== 'win32' && (metadata.mode & 0o077) !== 0)) {
+      throw new Error(`Refusing to read OAuth credentials without 0600 permissions: ${target}`);
+    }
+
+    return JSON.parse(await readFile(target, 'utf8'));
+  } catch (error) {
+    if (isFileSystemError(error, 'ENOENT')) return null;
+    throw error;
+  }
+};
+
+const emptySession = (endpoint) => ({
+  clientInformationByIssuer: {},
+  discoveryState: null,
+  endpoint,
+  latestClientIssuer: null,
+  latestTokenIssuer: null,
+  tokensByIssuer: {},
+  verifier: null,
+  version: SESSION_VERSION,
+});
+
+const isValidSession = (stored, endpoint) => {
+  return (
+    stored &&
+    typeof stored === 'object' &&
+    stored.version === SESSION_VERSION &&
+    stored.endpoint === endpoint &&
+    stored.clientInformationByIssuer &&
+    typeof stored.clientInformationByIssuer === 'object' &&
+    !Array.isArray(stored.clientInformationByIssuer) &&
+    stored.tokensByIssuer &&
+    typeof stored.tokensByIssuer === 'object' &&
+    !Array.isArray(stored.tokensByIssuer)
+  );
+};
+
+const readSession = async (endpoint, options) => {
+  const stored = await readPrivateJson(sessionPath(endpoint, options), options);
+  if (stored === null) return emptySession(endpoint);
+
+  if (!isValidSession(stored, endpoint)) {
+    throw new Error('The saved Rayrun CLI OAuth session is invalid. Run rayrun logout and retry.');
+  }
+
+  return stored;
+};
+
+const writeSession = async (session, options) => {
+  const target = sessionPath(session.endpoint, options);
+  await ensurePrivateDirectory(path.dirname(target));
+  await atomicWrite({
+    contents: Buffer.from(`${JSON.stringify(session, null, 2)}\n`),
+    mode: 0o600,
+    target,
+  });
+};
+
+const processIsRunning = (processId) => {
+  try {
+    process.kill(processId, 0);
+    return true;
+  } catch (error) {
+    return !isFileSystemError(error, 'ESRCH');
+  }
+};
+
+class LockCollisionError extends Error {}
+
+const readLockClaim = async (target) => {
+  try {
+    const parsed = JSON.parse(await readFile(target, 'utf8'));
+    return parsed &&
+      typeof parsed === 'object' &&
+      Number.isSafeInteger(parsed.processId) &&
+      parsed.processId > 0 &&
+      typeof parsed.hostname === 'string' &&
+      typeof parsed.nonce === 'string'
+      ? parsed
+      : null;
+  } catch (error) {
+    if (isFileSystemError(error, 'ENOENT') || error instanceof SyntaxError) return null;
+    throw error;
+  }
+};
+
+const acquireSessionLock = async (
+  endpoint,
+  options,
+  {
+    afterActivation = async () => {},
+    afterActivationScan = async () => {},
+    beforeActivation = async () => {},
+    createNonce = () => randomBytes(16).toString('base64url'),
+    hostname = os.hostname(),
+    isProcessRunning = processIsRunning,
+    processId = process.pid,
+    waitForRetry = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds)),
+  } = {},
+) => {
+  const locksDirectory = path.join(executionRoot(options), 'locks');
+  const lockDirectory = path.join(locksDirectory, endpointKey(endpoint));
+  await ensurePrivateDirectory(lockDirectory);
+
+  const liveClaims = async () => {
+    const live = [];
+    for (const name of await readdir(lockDirectory)) {
+      const match = LOCK_CLAIM_REGEX.exec(name);
+      if (!match) continue;
+      const target = path.join(lockDirectory, name);
+      let metadata;
+      let stored;
+      try {
+        metadata = await lstat(target);
+        stored = await readLockClaim(target);
+        if (stored === null) {
+          await lstat(target);
+        }
+      } catch (error) {
+        if (isFileSystemError(error, 'ENOENT')) continue;
+        throw error;
+      }
+      const claimIsValid =
+        metadata.isFile() && stored?.nonce === match[2] && stored?.hostname !== undefined;
+      if (!claimIsValid) {
+        throw new Error(`Rayrun CLI lock claim is invalid; remove it before retrying: ${target}`);
+      }
+      if (stored.hostname !== hostname) {
+        throw new Error(
+          'Rayrun CLI execution storage must be local to one host. Use a local per-host RAYRUN_CONFIG_HOME.',
+        );
+      }
+      const claimIsLive = isProcessRunning(stored.processId);
+      if (!claimIsLive) {
+        // Claim filenames contain never-reused random generations, so cleanup cannot unlink a
+        // replacement created by another process (the ABA flaw of a canonical lock path).
+        await rm(target, { force: true });
+        continue;
+      }
+      live.push({ kind: match[1], name, target });
+    }
+    return live;
+  };
+
+  for (let attempt = 0; attempt < LOCK_ACQUIRE_ATTEMPTS; attempt += 1) {
+    const claim = { hostname, nonce: createNonce(), processId };
+    const waitingName = `waiting-${claim.nonce}.json`;
+    const activeName = `active-${claim.nonce}.json`;
+    const waitingPath = path.join(lockDirectory, waitingName);
+    const activePath = path.join(lockDirectory, activeName);
+    try {
+      await atomicWrite({
+        contents: Buffer.from(`${JSON.stringify(claim)}\n`),
+        mode: 0o600,
+        target: waitingPath,
+      });
+      const initialClaims = await liveClaims();
+      const activeClaim = initialClaims.find(({ kind }) => kind === 'active');
+      if (activeClaim) {
+        throw new Error(
+          `Another Rayrun CLI execution command is using this endpoint. If none is running, remove the stale claim and retry: ${activeClaim.target}`,
+        );
+      }
+      const elected = initialClaims
+        .filter(({ kind }) => kind === 'waiting')
+        .sort((left, right) => left.name.localeCompare(right.name))[0];
+      if (elected.name !== waitingName) {
+        throw new Error(
+          `Another Rayrun CLI execution command is using this endpoint. If none is running, remove the stale claim and retry: ${elected.target}`,
+        );
+      }
+
+      await beforeActivation({ attempt });
+      await rename(waitingPath, activePath);
+      await afterActivation({ attempt });
+      const activeClaims = (await liveClaims()).filter(({ kind }) => kind === 'active');
+      await afterActivationScan({ activeClaims, attempt });
+      if (activeClaims.some(({ name }) => name !== activeName)) {
+        throw new LockCollisionError();
+      }
+
+      let released = false;
+      return async () => {
+        if (released) return;
+        released = true;
+        await rm(activePath, { force: true });
+      };
+    } catch (error) {
+      await rm(waitingPath, { force: true });
+      await rm(activePath, { force: true });
+      if (error instanceof LockCollisionError && attempt + 1 < LOCK_ACQUIRE_ATTEMPTS) {
+        await waitForRetry(5 + ((claim.nonce.codePointAt(0) ?? 0) % 20));
+        continue;
+      }
+      if (error instanceof LockCollisionError) {
+        throw new Error('Another Rayrun CLI execution command is using this endpoint.');
+      }
+      throw error;
+    }
+  }
+  throw new Error('Another Rayrun CLI execution command is using this endpoint.');
+};
+
+const secureEqual = (left, right) => {
+  const leftBuffer = Buffer.from(left);
+  const rightBuffer = Buffer.from(right);
+  return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+};
+
+const callbackPage = (response, status, message) => {
+  response.writeHead(status, {
+    'cache-control': 'no-store',
+    'content-security-policy': "default-src 'none'; style-src 'unsafe-inline'",
+    'content-type': 'text/html; charset=utf-8',
+    'x-content-type-options': 'nosniff',
+  });
+  response.end(
+    `<!doctype html><meta charset="utf-8"><title>Rayrun CLI</title><style>body{font:16px system-ui;max-width:42rem;margin:10vh auto;padding:1rem}</style><h1>Rayrun CLI</h1><p>${message}</p>`,
+  );
+};
+
+export const createLoopbackAuthorizationReceiver = async ({
+  createServerImplementation = createServer,
+  timeoutMilliseconds = AUTHORIZATION_TIMEOUT_MILLISECONDS,
+} = {}) => {
+  let callbackSettled = false;
+  let expectedState;
+  let rejectCallback;
+  let resolveCallback;
+  let timeout;
+  let closed = false;
+  const callback = new Promise((resolve, reject) => {
+    rejectCallback = reject;
+    resolveCallback = resolve;
+  });
+  // The rejection is observed by waitForCallback, but a browser may cancel before connect reaches it.
+  void callback.catch(() => {});
+
+  const server = createServerImplementation((request, response) => {
+    if (request.method !== 'GET') {
+      callbackPage(response, 405, 'This callback accepts GET requests only.');
+      return;
+    }
+
+    const requestUrl = new URL(request.url ?? '/', 'http://127.0.0.1');
+    if (requestUrl.pathname !== '/oauth/callback') {
+      callbackPage(response, 404, 'This is not the Rayrun authorization callback.');
+      return;
+    }
+    if (!expectedState || !secureEqual(requestUrl.searchParams.get('state') ?? '', expectedState)) {
+      callbackPage(response, 400, 'The authorization state did not match. Return to the terminal.');
+      return;
+    }
+    if (callbackSettled) {
+      callbackPage(response, 409, 'This authorization callback was already used.');
+      return;
+    }
+
+    callbackSettled = true;
+    clearTimeout(timeout);
+    if (requestUrl.searchParams.has('error') || !requestUrl.searchParams.has('code')) {
+      callbackPage(response, 400, 'Authorization was not completed. Return to the terminal.');
+      rejectCallback(new Error('Rayrun authorization was not completed.'));
+      return;
+    }
+
+    callbackPage(response, 200, 'Authorization received. You can close this window.');
+    resolveCallback(requestUrl.searchParams);
+  });
+
+  await new Promise((resolve, reject) => {
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      server.off('error', reject);
+      resolve();
+    });
+  });
+  const address = server.address();
+  if (!address || typeof address === 'string') {
+    server.close();
+    throw new Error('Rayrun CLI could not open a loopback OAuth callback.');
+  }
+
+  return {
+    close: async () => {
+      if (closed) return;
+      closed = true;
+      clearTimeout(timeout);
+      await new Promise((resolve, reject) => {
+        server.close((error) => {
+          if (error && error.code !== 'ERR_SERVER_NOT_RUNNING') reject(error);
+          else resolve();
+        });
+      });
+    },
+    redirectUrl: `http://127.0.0.1:${String(address.port)}/oauth/callback`,
+    waitForCallback: async (state) => {
+      expectedState = state;
+      timeout = setTimeout(() => {
+        if (callbackSettled) return;
+        callbackSettled = true;
+        rejectCallback(new Error('Rayrun authorization timed out after 5 minutes.'));
+      }, timeoutMilliseconds);
+      timeout.unref?.();
+      return await callback;
+    },
+  };
+};
+
+export const openExternalUrl = async (
+  url,
+  {
+    errorOutput = process.stderr,
+    noOpen = false,
+    platform = process.platform,
+    spawnImplementation = spawn,
+  } = {},
+) => {
+  errorOutput.write(`Open: ${url}\n`);
+  if (noOpen) return false;
+
+  const command =
+    platform === 'darwin'
+      ? { arguments_: [url], executable: 'open' }
+      : platform === 'win32'
+        ? { arguments_: ['url.dll,FileProtocolHandler', url], executable: 'rundll32.exe' }
+        : { arguments_: [url], executable: 'xdg-open' };
+
+  return await new Promise((resolve) => {
+    const child = spawnImplementation(command.executable, command.arguments_, {
+      detached: true,
+      stdio: 'ignore',
+    });
+    child.once('error', () => resolve(false));
+    child.once('spawn', () => {
+      child.unref();
+      resolve(true);
+    });
+  });
+};
+
+export class FileOAuthClientProvider {
+  constructor({ onAuthorization, redirectUrl, session, state, storageOptions }) {
+    this.onAuthorization = onAuthorization;
+    this.redirectUrlValue = redirectUrl;
+    this.session = session;
+    this.stateValue = state;
+    this.storageOptions = storageOptions;
+  }
+
+  get redirectUrl() {
+    return this.redirectUrlValue;
+  }
+
+  get clientMetadata() {
+    return {
+      application_type: 'native',
+      client_name: 'Rayrun CLI',
+      grant_types: ['authorization_code', 'refresh_token'],
+      redirect_uris: [this.redirectUrlValue],
+      response_types: ['code'],
+      scope: 'mcp:tools',
+      token_endpoint_auth_method: 'none',
+    };
+  }
+
+  state() {
+    return this.stateValue;
+  }
+
+  clientInformation(context) {
+    const issuer = context?.issuer ?? this.session.latestClientIssuer;
+    return issuer ? this.session.clientInformationByIssuer[issuer] : undefined;
+  }
+
+  async saveClientInformation(clientInformation, context) {
+    const issuer = context?.issuer ?? clientInformation.issuer;
+    if (!issuer) throw new Error('Rayrun OAuth client registration did not identify its issuer.');
+    this.session.clientInformationByIssuer[issuer] = clientInformation;
+    this.session.latestClientIssuer = issuer;
+    await writeSession(this.session, this.storageOptions);
+  }
+
+  tokens(context) {
+    const issuer = context?.issuer ?? this.session.latestTokenIssuer;
+    return issuer ? this.session.tokensByIssuer[issuer] : undefined;
+  }
+
+  async saveTokens(tokens, context) {
+    const issuer = context?.issuer ?? tokens.issuer;
+    if (!issuer) throw new Error('Rayrun OAuth tokens did not identify their issuer.');
+    this.session.tokensByIssuer[issuer] = tokens;
+    this.session.latestTokenIssuer = issuer;
+    this.session.verifier = null;
+    await writeSession(this.session, this.storageOptions);
+  }
+
+  async redirectToAuthorization(authorizationUrl) {
+    await this.onAuthorization(authorizationUrl);
+  }
+
+  async saveCodeVerifier(verifier) {
+    this.session.verifier = verifier;
+    await writeSession(this.session, this.storageOptions);
+  }
+
+  codeVerifier() {
+    if (!this.session.verifier) throw new Error('The Rayrun OAuth verifier is missing.');
+    return this.session.verifier;
+  }
+
+  async saveDiscoveryState(discoveryState) {
+    this.session.discoveryState = discoveryState;
+    await writeSession(this.session, this.storageOptions);
+  }
+
+  discoveryState() {
+    return this.session.discoveryState ?? undefined;
+  }
+
+  async invalidateCredentials(scope) {
+    if (scope === 'all' || scope === 'client') {
+      this.session.clientInformationByIssuer = {};
+      this.session.latestClientIssuer = null;
+    }
+    if (scope === 'all' || scope === 'tokens') {
+      this.session.tokensByIssuer = {};
+      this.session.latestTokenIssuer = null;
+    }
+    if (scope === 'all' || scope === 'verifier') this.session.verifier = null;
+    if (scope === 'all' || scope === 'discovery') this.session.discoveryState = null;
+    await writeSession(this.session, this.storageOptions);
+  }
+}
+
+const createMcpClient = ({ version }) => {
+  const client = new Client(
+    { name: 'rayrun-cli', version },
+    {
+      inputRequired: { autoFulfill: false },
+      versionNegotiation: { mode: 'auto' },
+    },
+  );
+  client.registerCapabilities({ elicitation: { url: {} } });
+  return client;
+};
+
+export const connectExecutionMcp = async ({
+  createClient = createMcpClient,
+  createReceiver = createLoopbackAuthorizationReceiver,
+  createTransport = ({ endpoint: transportEndpoint, provider }) =>
+    new StreamableHTTPClientTransport(new URL(transportEndpoint), { authProvider: provider }),
+  endpoint,
+  errorOutput = process.stderr,
+  lockOptions,
+  noOpen = false,
+  openUrl = openExternalUrl,
+  storageOptions,
+  version,
+}) => {
+  const releaseLock = await acquireSessionLock(endpoint, storageOptions, lockOptions);
+  let receiver;
+  let client;
+  let transport;
+
+  try {
+    const session = await readSession(endpoint, storageOptions);
+    receiver = await createReceiver();
+    const state = randomBytes(32).toString('base64url');
+    const provider = new FileOAuthClientProvider({
+      onAuthorization: async (authorizationUrl) => {
+        await openUrl(String(authorizationUrl), { errorOutput, noOpen });
+      },
+      redirectUrl: receiver.redirectUrl,
+      session,
+      state,
+      storageOptions,
+    });
+    client = createClient({ version });
+    transport = createTransport({ endpoint, provider });
+    // Arm the state check before the browser can complete an already-authenticated redirect.
+    const callback = receiver.waitForCallback(state);
+    void callback.catch(() => {});
+
+    try {
+      await client.connect(transport);
+    } catch (error) {
+      if (!(error instanceof UnauthorizedError)) throw error;
+      const callbackParameters = await callback;
+      await transport.finishAuth(callbackParameters);
+      await transport.close().catch(() => {});
+      transport = createTransport({ endpoint, provider });
+      await client.connect(transport);
+    }
+
+    await receiver.close();
+    receiver = undefined;
+    let closed = false;
+
+    return {
+      client,
+      close: async () => {
+        if (closed) return;
+        closed = true;
+        try {
+          await transport.terminateSession().catch(() => {});
+          await client.close();
+        } finally {
+          await releaseLock();
+        }
+      },
+    };
+  } catch (error) {
+    await receiver?.close().catch(() => {});
+    await client?.close().catch(() => {});
+    await releaseLock();
+    throw error;
+  }
+};
+
+export const clearOAuthSession = async (endpoint, options = {}, whileLocked) => {
+  const releaseLock = await acquireSessionLock(endpoint, options);
+  try {
+    const target = sessionPath(endpoint, options);
+    let stored;
+    try {
+      stored = await readPrivateJson(target, options);
+    } catch (error) {
+      if (!(error instanceof SyntaxError)) throw error;
+      stored = null;
+    }
+    const session = isValidSession(stored, endpoint) ? stored : emptySession(endpoint);
+    await assertNoSymbolicLinkComponents(target);
+    await rm(target, { force: true });
+    await whileLocked?.();
+    return session;
+  } finally {
+    await releaseLock();
+  }
+};

package/src/setup.js

@@ -9,7 +9,7 @@ import path from 'node:path';
 
 const checksum = (value) => createHash('sha256').update(value).digest('hex');
 
-const assertNoSymbolicLinkComponents = async (target) => {
+export const assertNoSymbolicLinkComponents = async (target) => {
   const absoluteTarget = path.resolve(target);
   const root = path.parse(absoluteTarget).root;
   const components = path.relative(root, absoluteTarget).split(path.sep).filter(Boolean);
@@ -52,7 +52,7 @@ const readSnapshot = async (target) => {
   }
 };
 
-const atomicWrite = async ({ contents, mode, target }) => {
+export const atomicWrite = async ({ contents, mode, target }) => {
   await assertNoSymbolicLinkComponents(target);
   await mkdir(path.dirname(target), { mode: 0o700, recursive: true });
   await assertNoSymbolicLinkComponents(path.dirname(target));