@redocly/cli 1.29.0 → 1.31.0

package/src/auth/__tests__/oauth-client.test.ts

@@ -0,0 +1,117 @@
+import { RedoclyOAuthClient } from '../oauth-client';
+import { RedoclyOAuthDeviceFlow } from '../device-flow';
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+jest.mock('node:fs');
+jest.mock('node:os');
+jest.mock('../device-flow');
+
+describe('RedoclyOAuthClient', () => {
+  const mockClientName = 'test-client';
+  const mockVersion = '1.0.0';
+  const mockBaseUrl = 'https://test.redocly.com';
+  const mockHomeDir = '/mock/home/dir';
+  const mockRedoclyDir = path.join(mockHomeDir, '.redocly');
+  let client: RedoclyOAuthClient;
+
+  beforeEach(() => {
+    jest.resetAllMocks();
+    (os.homedir as jest.Mock).mockReturnValue(mockHomeDir);
+    process.env.HOME = mockHomeDir;
+    client = new RedoclyOAuthClient(mockClientName, mockVersion);
+  });
+
+  describe('login', () => {
+    it('successfully logs in and saves token', async () => {
+      const mockToken = { access_token: 'test-token' };
+      const mockDeviceFlow = {
+        run: jest.fn().mockResolvedValue(mockToken),
+      };
+      (RedoclyOAuthDeviceFlow as jest.Mock).mockImplementation(() => mockDeviceFlow);
+
+      await client.login(mockBaseUrl);
+
+      expect(mockDeviceFlow.run).toHaveBeenCalled();
+      expect(fs.writeFileSync).toHaveBeenCalled();
+    });
+
+    it('throws error when login fails', async () => {
+      const mockDeviceFlow = {
+        run: jest.fn().mockResolvedValue(null),
+      };
+      (RedoclyOAuthDeviceFlow as jest.Mock).mockImplementation(() => mockDeviceFlow);
+
+      await expect(client.login(mockBaseUrl)).rejects.toThrow('Failed to login');
+    });
+  });
+
+  describe('logout', () => {
+    it('removes token file if it exists', async () => {
+      (fs.existsSync as jest.Mock).mockReturnValue(true);
+
+      await client.logout();
+
+      expect(fs.rmSync).toHaveBeenCalledWith(path.join(mockRedoclyDir, 'auth.json'));
+    });
+
+    it('silently fails if token file does not exist', async () => {
+      (fs.existsSync as jest.Mock).mockReturnValue(false);
+
+      await expect(client.logout()).resolves.not.toThrow();
+      expect(fs.rmSync).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('isAuthorized', () => {
+    it('verifies API key if provided', async () => {
+      const mockDeviceFlow = {
+        verifyApiKey: jest.fn().mockResolvedValue(true),
+      };
+      (RedoclyOAuthDeviceFlow as jest.Mock).mockImplementation(() => mockDeviceFlow);
+
+      const result = await client.isAuthorized(mockBaseUrl, 'test-api-key');
+
+      expect(result).toBe(true);
+      expect(mockDeviceFlow.verifyApiKey).toHaveBeenCalledWith('test-api-key');
+    });
+
+    it('verifies access token if no API key provided', async () => {
+      const mockToken = { access_token: 'test-token' };
+      const mockDeviceFlow = {
+        verifyToken: jest.fn().mockResolvedValue(true),
+      };
+      (RedoclyOAuthDeviceFlow as jest.Mock).mockImplementation(() => mockDeviceFlow);
+      (fs.readFileSync as jest.Mock).mockReturnValue(
+        client['cipher'].update(JSON.stringify(mockToken), 'utf8', 'hex') +
+          client['cipher'].final('hex')
+      );
+
+      const result = await client.isAuthorized(mockBaseUrl);
+
+      expect(result).toBe(true);
+      expect(mockDeviceFlow.verifyToken).toHaveBeenCalledWith('test-token');
+    });
+
+    it('returns false if token refresh fails', async () => {
+      const mockToken = {
+        access_token: 'old-token',
+        refresh_token: 'refresh-token',
+      };
+      const mockDeviceFlow = {
+        verifyToken: jest.fn().mockResolvedValue(false),
+        refreshToken: jest.fn().mockRejectedValue(new Error('Refresh failed')),
+      };
+      (RedoclyOAuthDeviceFlow as jest.Mock).mockImplementation(() => mockDeviceFlow);
+      (fs.readFileSync as jest.Mock).mockReturnValue(
+        client['cipher'].update(JSON.stringify(mockToken), 'utf8', 'hex') +
+          client['cipher'].final('hex')
+      );
+
+      const result = await client.isAuthorized(mockBaseUrl);
+
+      expect(result).toBe(false);
+    });
+  });
+});

package/src/auth/device-flow.ts

@@ -0,0 +1,175 @@
+import { blue, green } from 'colorette';
+import * as childProcess from 'child_process';
+import { ReuniteApiClient } from '../reunite/api/api-client';
+
+export type AuthToken = {
+  access_token: string;
+  refresh_token?: string;
+  token_type?: string;
+  expires_in?: number;
+};
+
+export class RedoclyOAuthDeviceFlow {
+  private apiClient: ReuniteApiClient;
+
+  constructor(private baseUrl: string, private clientName: string, private version: string) {
+    this.apiClient = new ReuniteApiClient(this.version, 'login');
+  }
+
+  async run() {
+    const code = await this.getDeviceCode();
+    process.stdout.write(
+      'Attempting to automatically open the SSO authorization page in your default browser.\n'
+    );
+    process.stdout.write(
+      'If the browser does not open or you wish to use a different device to authorize this request, open the following URL:\n\n'
+    );
+    process.stdout.write(blue(code.verificationUri));
+    process.stdout.write(`\n\n`);
+    process.stdout.write(`Then enter the code:\n\n`);
+    process.stdout.write(blue(code.userCode));
+    process.stdout.write(`\n\n`);
+
+    this.openBrowser(code.verificationUriComplete);
+
+    const accessToken = await this.pollingAccessToken(
+      code.deviceCode,
+      code.interval,
+      code.expiresIn
+    );
+    process.stdout.write(green('✅ Logged in\n\n'));
+
+    return accessToken;
+  }
+
+  private openBrowser(url: string) {
+    try {
+      const cmd =
+        process.platform === 'win32'
+          ? `start ${url}`
+          : process.platform === 'darwin'
+          ? `open ${url}`
+          : `xdg-open ${url}`;
+
+      childProcess.execSync(cmd);
+    } catch {
+      // silently fail if browser cannot be opened
+    }
+  }
+
+  async verifyToken(accessToken: string) {
+    try {
+      const response = await this.sendRequest('/session', 'GET', undefined, {
+        Cookie: `accessToken=${accessToken};`,
+      });
+
+      return !!response.user;
+    } catch {
+      return false;
+    }
+  }
+
+  async verifyApiKey(apiKey: string) {
+    try {
+      const response = await this.sendRequest('/api-keys-verify', 'POST', {
+        apiKey,
+      });
+      return !!response.success;
+    } catch {
+      return false;
+    }
+  }
+
+  async refreshToken(refreshToken: string) {
+    const response = await this.sendRequest(`/device-rotate-token`, 'POST', {
+      grant_type: 'refresh_token',
+      client_name: this.clientName,
+      refresh_token: refreshToken,
+    });
+
+    if (!response.access_token) {
+      throw new Error('Failed to refresh token');
+    }
+    return {
+      access_token: response.access_token,
+      refresh_token: response.refresh_token,
+      expires_in: response.expires_in,
+    };
+  }
+
+  private async pollingAccessToken(
+    deviceCode: string,
+    interval: number,
+    expiresIn: number
+  ): Promise<AuthToken> {
+    return new Promise((resolve, reject) => {
+      const intervalId = setInterval(async () => {
+        const response = await this.getAccessToken(deviceCode);
+        if (response.access_token) {
+          clearInterval(intervalId);
+          clearTimeout(timeoutId);
+          resolve(response);
+        }
+        if (response.error && response.error !== 'authorization_pending') {
+          clearInterval(intervalId);
+          clearTimeout(timeoutId);
+          reject(response.error_description);
+        }
+      }, interval * 1000);
+
+      const timeoutId = setTimeout(async () => {
+        clearInterval(intervalId);
+        clearTimeout(timeoutId);
+        reject('Authorization has expired. Please try again.');
+      }, expiresIn * 1000);
+    });
+  }
+
+  private async getAccessToken(deviceCode: string) {
+    return await this.sendRequest('/device-token', 'POST', {
+      client_name: this.clientName,
+      device_code: deviceCode,
+      grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+    });
+  }
+
+  private async getDeviceCode() {
+    const {
+      device_code: deviceCode,
+      user_code: userCode,
+      verification_uri: verificationUri,
+      verification_uri_complete: verificationUriComplete,
+      interval = 10,
+      expires_in: expiresIn = 300,
+    } = await this.sendRequest('/device-authorize', 'POST', {
+      client_name: this.clientName,
+    });
+
+    return {
+      deviceCode,
+      userCode,
+      verificationUri,
+      verificationUriComplete,
+      interval,
+      expiresIn,
+    };
+  }
+
+  private async sendRequest(
+    url: string,
+    method: string = 'GET',
+    body: Record<string, unknown> | undefined = undefined,
+    headers: Record<string, string> = {}
+  ) {
+    url = `${this.baseUrl}${url}`;
+    const response = await this.apiClient.request(url, {
+      body: body ? JSON.stringify(body) : body,
+      method,
+      headers: { 'Content-Type': 'application/json', ...headers },
+    });
+    if (response.status === 204) {
+      return { success: true };
+    }
+    return await response.json();
+  }
+}

package/src/auth/oauth-client.ts

@@ -0,0 +1,111 @@
+import { homedir } from 'node:os';
+import * as path from 'node:path';
+import { mkdirSync, existsSync, writeFileSync, readFileSync, rmSync } from 'node:fs';
+import * as crypto from 'node:crypto';
+import { Buffer } from 'node:buffer';
+import { type AuthToken, RedoclyOAuthDeviceFlow } from './device-flow';
+
+const SALT = '4618dbc9-8aed-4e27-aaf0-225f4603e5a4';
+const CRYPTO_ALGORITHM = 'aes-256-cbc';
+
+export class RedoclyOAuthClient {
+  private dir: string;
+  private cipher: crypto.Cipher;
+  private decipher: crypto.Decipher;
+
+  constructor(private clientName: string, private version: string) {
+    this.dir = path.join(homedir(), '.redocly');
+    if (!existsSync(this.dir)) {
+      mkdirSync(this.dir);
+    }
+
+    const homeDirPath = process.env.HOME as string;
+    const hash = crypto.createHash('sha256');
+    hash.update(`${homeDirPath}${SALT}`);
+    const hashHex = hash.digest('hex');
+
+    const key = Buffer.alloc(
+      32,
+      Buffer.from(hashHex).toString('base64')
+    ).toString() as crypto.CipherKey;
+    const iv = Buffer.alloc(
+      16,
+      Buffer.from(process.env.HOME as string).toString('base64')
+    ).toString() as crypto.BinaryLike;
+    this.cipher = crypto.createCipheriv(CRYPTO_ALGORITHM, key, iv);
+    this.decipher = crypto.createDecipheriv(CRYPTO_ALGORITHM, key, iv);
+  }
+
+  async login(baseUrl: string) {
+    const deviceFlow = new RedoclyOAuthDeviceFlow(baseUrl, this.clientName, this.version);
+
+    const token = await deviceFlow.run();
+    if (!token) {
+      throw new Error('Failed to login');
+    }
+    this.saveToken(token);
+  }
+
+  async logout() {
+    try {
+      this.removeToken();
+    } catch (err) {
+      // do nothing
+    }
+  }
+
+  async isAuthorized(baseUrl: string, apiKey?: string) {
+    const deviceFlow = new RedoclyOAuthDeviceFlow(baseUrl, this.clientName, this.version);
+
+    if (apiKey) {
+      return await deviceFlow.verifyApiKey(apiKey);
+    }
+
+    const token = await this.readToken();
+    if (!token) {
+      return false;
+    }
+
+    const isValidAccessToken = await deviceFlow.verifyToken(token.access_token);
+
+    if (isValidAccessToken) {
+      return true;
+    }
+
+    try {
+      const newToken = await deviceFlow.refreshToken(token.refresh_token);
+      await this.saveToken(newToken);
+    } catch {
+      return false;
+    }
+
+    return true;
+  }
+
+  private async saveToken(token: AuthToken) {
+    try {
+      const encrypted =
+        this.cipher.update(JSON.stringify(token), 'utf8', 'hex') + this.cipher.final('hex');
+      writeFileSync(path.join(this.dir, 'auth.json'), encrypted);
+    } catch (error) {
+      process.stderr.write('Error saving tokens:', error);
+    }
+  }
+
+  private async readToken() {
+    try {
+      const token = readFileSync(path.join(this.dir, 'auth.json'), 'utf8');
+      const decrypted = this.decipher.update(token, 'hex', 'utf8') + this.decipher.final('utf8');
+      return decrypted ? JSON.parse(decrypted) : null;
+    } catch {
+      return null;
+    }
+  }
+
+  private async removeToken() {
+    const tokenPath = path.join(this.dir, 'auth.json');
+    if (existsSync(tokenPath)) {
+      rmSync(tokenPath);
+    }
+  }
+}

package/src/commands/auth.ts

@@ -0,0 +1,66 @@
+import { blue, green, gray, yellow } from 'colorette';
+import { RedoclyClient } from '@redocly/openapi-core';
+import { exitWithError, promptUser } from '../utils/miscellaneous';
+import { RedoclyOAuthClient } from '../auth/oauth-client';
+import { getReuniteUrl } from '../reunite/api';
+
+import type { CommandArgs } from '../wrapper';
+import type { Region } from '@redocly/openapi-core';
+
+export function promptClientToken(domain: string) {
+  return promptUser(
+    green(
+      `\n  🔑 Copy your API key from ${blue(`https://app.${domain}/profile`)} and paste it below`
+    ) + yellow(' (if you want to log in with Reunite, please run `redocly login --next` instead)'),
+    true
+  );
+}
+
+export type LoginOptions = {
+  verbose?: boolean;
+  residency?: string;
+  config?: string;
+  next?: boolean;
+};
+
+export async function handleLogin({ argv, config, version }: CommandArgs<LoginOptions>) {
+  if (argv.next) {
+    try {
+      const reuniteUrl = getReuniteUrl(argv.residency);
+      const oauthClient = new RedoclyOAuthClient('redocly-cli', version);
+      await oauthClient.login(reuniteUrl);
+    } catch {
+      if (argv.residency) {
+        const reuniteUrl = getReuniteUrl(argv.residency);
+        exitWithError(`❌ Connection to ${reuniteUrl} failed.`);
+      } else {
+        exitWithError(`❌ Login failed. Please check your credentials and try again.`);
+      }
+    }
+  } else {
+    try {
+      const region = (argv.residency as Region) || config.region;
+      const client = new RedoclyClient(region);
+      const clientToken = await promptClientToken(client.domain);
+      process.stdout.write(gray('\n  Logging in...\n'));
+      await client.login(clientToken, argv.verbose);
+      process.stdout.write(green('  Authorization confirmed. ✅\n\n'));
+    } catch (err) {
+      exitWithError('  ' + err?.message);
+    }
+  }
+}
+
+export type LogoutOptions = {
+  config?: string;
+};
+
+export async function handleLogout({ version }: CommandArgs<LogoutOptions>) {
+  const client = new RedoclyClient();
+  client.logout();
+
+  const oauthClient = new RedoclyOAuthClient('redocly-cli', version);
+  oauthClient.logout();
+
+  process.stdout.write('Logged out from the Redocly account. ✋ \n');
+}

package/src/commands/push.ts

@@ -19,9 +19,9 @@ import {
   getFallbackApisOrExit,
   dumpBundle,
 } from '../utils/miscellaneous';
-import { promptClientToken } from './login';
-import { handlePush as handleCMSPush } from '../cms/commands/push';
-import { streamToBuffer } from '../cms/api/api-client';
+import { promptClientToken } from './auth';
+import { handlePush as handleCMSPush } from '../reunite/commands/push';
+import { streamToBuffer } from '../reunite/api/api-client';
 
 import type { Readable } from 'node:stream';
 import type { Agent } from 'node:http';

package/src/index.ts

@@ -1,18 +1,18 @@
 #!/usr/bin/env node
-
+import * as path from 'path';
+import * as dotenv from 'dotenv';
 import './utils/assert-node-version';
 import * as yargs from 'yargs';
 import * as colors from 'colorette';
-import { RedoclyClient } from '@redocly/openapi-core';
 import { outputExtensions, regionChoices } from './types';
 import { previewDocs } from './commands/preview-docs';
 import { handleStats } from './commands/stats';
 import { handleSplit } from './commands/split';
 import { handleJoin } from './commands/join';
-import { handlePushStatus } from './cms/commands/push-status';
+import { handlePushStatus } from './reunite/commands/push-status';
 import { handleLint } from './commands/lint';
 import { handleBundle } from './commands/bundle';
-import { handleLogin } from './commands/login';
+import { handleLogin, handleLogout } from './commands/auth';
 import { handlerBuildCommand } from './commands/build-docs';
 import {
   cacheLatestVersion,
@@ -28,11 +28,14 @@ import { commonPushHandler } from './commands/push';
 
 import type { Arguments } from 'yargs';
 import type { OutputFormat, RuleSeverity } from '@redocly/openapi-core';
+import type { GenerateArazzoFileOptions, RespectOptions } from '@redocly/respect-core';
 import type { BuildDocsArgv } from './commands/build-docs/types';
-import type { PushStatusOptions } from './cms/commands/push-status';
+import type { PushStatusOptions } from './reunite/commands/push-status';
 import type { PushArguments } from './types';
 import type { EjectOptions } from './commands/eject';
 
+dotenv.config({ path: path.resolve(process.cwd(), './.env') });
+
 if (!('replaceAll' in String.prototype)) {
   require('core-js/actual/string/replace-all');
 }
@@ -605,23 +608,27 @@ yargs
   )
   .command(
     'login',
-    'Login to the Redocly API registry with an access token.',
+    'Log in to Redocly.',
     async (yargs) =>
       yargs.options({
         verbose: {
           description: 'Include additional output.',
           type: 'boolean',
         },
-        region: {
-          description: 'Specify a region.',
-          alias: 'r',
-          choices: regionChoices,
+        residency: {
+          description: 'Residency of the application. Defaults to `us`.',
+          alias: ['r', 'region'],
+          type: 'string',
         },
         config: {
           description: 'Path to the config file.',
           requiresArg: true,
           type: 'string',
         },
+        next: {
+          description: 'Use Reunite application to login.',
+          type: 'boolean',
+        },
       }),
     (argv) => {
       process.env.REDOCLY_CLI_COMMAND = 'login';
@@ -632,13 +639,9 @@ yargs
     'logout',
     'Clear your stored credentials for the Redocly API registry.',
     (yargs) => yargs,
-    async (argv) => {
+    (argv) => {
       process.env.REDOCLY_CLI_COMMAND = 'logout';
-      await commandWrapper(async () => {
-        const client = new RedoclyClient();
-        client.logout();
-        process.stdout.write('Logged out from the Redocly account. ✋\n');
-      })(argv);
+      commandWrapper(handleLogout)(argv);
     }
   )
   .command(
@@ -864,6 +867,102 @@ yargs
       commandWrapper(handleEject)(argv as Arguments<EjectOptions>);
     }
   )
+  .command(
+    'respect [files...]',
+    'Run Arazzo tests.',
+    (yargs) => {
+      return yargs
+        .positional('files', {
+          describe: 'Test files or glob pattern.',
+          type: 'string',
+          array: true,
+          default: [],
+        })
+        .env('REDOCLY_CLI_RESPECT')
+        .options({
+          input: {
+            alias: 'i',
+            describe: 'Input parameters.',
+            type: 'string',
+          },
+          server: {
+            alias: 'S',
+            describe: 'Server parameters.',
+            type: 'string',
+          },
+          workflow: {
+            alias: 'w',
+            describe: 'Workflow name.',
+            type: 'string',
+            array: true,
+          },
+          skip: {
+            alias: 's',
+            describe: 'Workflow to skip.',
+            type: 'string',
+            array: true,
+          },
+          verbose: {
+            alias: 'v',
+            describe: 'Apply verbose mode.',
+            type: 'boolean',
+          },
+          'har-output': {
+            describe: 'Har file output name.',
+            type: 'string',
+          },
+          'json-output': {
+            describe: 'JSON file output name.',
+            type: 'string',
+          },
+          'client-cert': {
+            describe: 'Mutual TLS client certificate.',
+            type: 'string',
+          },
+          'client-key': {
+            describe: 'Mutual TLS client key.',
+            type: 'string',
+          },
+          'ca-cert': {
+            describe: 'Mutual TLS CA certificate.',
+            type: 'string',
+          },
+          severity: {
+            describe: 'Severity of the check.',
+            type: 'string',
+          },
+        });
+    },
+    async (argv) => {
+      process.env.REDOCLY_CLI_COMMAND = 'respect';
+      const { handleRun } = await import('@redocly/respect-core');
+      commandWrapper(handleRun)(argv as Arguments<RespectOptions>);
+    }
+  )
+  .command(
+    'generate-arazzo <descriptionPath>',
+    'Auto-generate arazzo description file from an API description.',
+    (yargs) => {
+      return yargs
+        .positional('descriptionPath', {
+          describe: 'Description file path.',
+          type: 'string',
+        })
+        .env('REDOCLY_CLI_RESPECT')
+        .options({
+          'output-file': {
+            alias: 'o',
+            describe: 'Output File name.',
+            type: 'string',
+          },
+        });
+    },
+    async (argv) => {
+      process.env.REDOCLY_CLI_COMMAND = 'generate-arazzo';
+      const { handleGenerate } = await import('@redocly/respect-core');
+      commandWrapper(handleGenerate)(argv as Arguments<GenerateArazzoFileOptions>);
+    }
+  )
   .completion('completion', 'Generate autocomplete script for `redocly` command.')
   .demandCommand(1)
   .middleware([notifyUpdateCliVersion])