@zimic/interceptor 0.17.0-canary.1 → 0.17.0-canary.3

package/src/server/types/public.ts

@@ -29,6 +29,15 @@ export interface InterceptorServer {
    */
   logUnhandledRequests: boolean;
 
+  /**
+   * The directory where the authorized interceptor authentication tokens are saved. If provided, only remote
+   * interceptors bearing a valid token will be accepted. This option is essential if you are exposing your interceptor
+   * server publicly. For local development and testing, though, `--tokens-dir` is optional.
+   *
+   * @default undefined
+   */
+  tokensDirectory?: string;
+
   /**
    * Whether the server is running.
    *

package/src/server/types/schema.ts

@@ -1,7 +1,7 @@
 import { HttpMethod } from '@zimic/http';
 
 import { SerializedHttpRequest, SerializedResponse } from '@/utils/fetch';
-import { WebSocket } from '@/webSocket/types';
+import { WebSocketSchema } from '@/webSocket/types';
 
 export interface HttpHandlerCommit {
   id: string;
@@ -9,13 +9,13 @@ export interface HttpHandlerCommit {
   method: HttpMethod;
 }
 
-export type InterceptorServerWebSocketSchema = WebSocket.ServiceSchema<{
-  'interceptors/workers/use/commit': {
+export type InterceptorServerWebSocketSchema = WebSocketSchema<{
+  'interceptors/workers/commit': {
     event: HttpHandlerCommit;
     reply: {};
   };
 
-  'interceptors/workers/use/reset': {
+  'interceptors/workers/reset': {
     event?: HttpHandlerCommit[];
     reply: {};
   };

package/src/server/utils/auth.ts

@@ -0,0 +1,301 @@
+import crypto from 'crypto';
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import color from 'picocolors';
+import util from 'util';
+import { z } from 'zod';
+
+import {
+  BASE64URL_REGEX,
+  convertHexLengthToBase64urlLength,
+  convertHexLengthToByteLength,
+  HEX_REGEX,
+} from '@/utils/data';
+import { pathExists } from '@/utils/files';
+import { logger } from '@/utils/logging';
+
+import InvalidInterceptorTokenError from '../errors/InvalidInterceptorTokenError';
+import InvalidInterceptorTokenFileError from '../errors/InvalidInterceptorTokenFileError';
+import InvalidInterceptorTokenValueError from '../errors/InvalidInterceptorTokenValueError';
+
+export const DEFAULT_INTERCEPTOR_TOKENS_DIRECTORY = path.join(
+  '.zimic',
+  'interceptor',
+  'server',
+  `tokens${process.env.VITEST_POOL_ID}`,
+);
+
+export const INTERCEPTOR_TOKEN_ID_HEX_LENGTH = 32;
+
+export const INTERCEPTOR_TOKEN_SECRET_HEX_LENGTH = 64;
+export const INTERCEPTOR_TOKEN_VALUE_HEX_LENGTH = INTERCEPTOR_TOKEN_ID_HEX_LENGTH + INTERCEPTOR_TOKEN_SECRET_HEX_LENGTH;
+export const INTERCEPTOR_TOKEN_VALUE_BASE64URL_LENGTH = convertHexLengthToBase64urlLength(
+  INTERCEPTOR_TOKEN_VALUE_HEX_LENGTH,
+);
+
+export const INTERCEPTOR_TOKEN_SALT_HEX_LENGTH = 64;
+export const INTERCEPTOR_TOKEN_HASH_ITERATIONS = Number(process.env.INTERCEPTOR_TOKEN_HASH_ITERATIONS);
+export const INTERCEPTOR_TOKEN_HASH_HEX_LENGTH = 128;
+export const INTERCEPTOR_TOKEN_HASH_ALGORITHM = 'sha512';
+
+const pbkdf2 = util.promisify(crypto.pbkdf2);
+
+async function hashInterceptorToken(plainToken: string, salt: string) {
+  const hashBuffer = await pbkdf2(
+    plainToken,
+    salt,
+    INTERCEPTOR_TOKEN_HASH_ITERATIONS,
+    convertHexLengthToByteLength(INTERCEPTOR_TOKEN_HASH_HEX_LENGTH),
+    INTERCEPTOR_TOKEN_HASH_ALGORITHM,
+  );
+
+  const hash = hashBuffer.toString('hex');
+  return hash;
+}
+
+interface InterceptorTokenSecret {
+  hash: string;
+  salt: string;
+  value: string;
+}
+
+export interface InterceptorToken {
+  id: string;
+  name?: string;
+  secret: InterceptorTokenSecret;
+  value: string;
+  createdAt: Date;
+}
+
+export function createInterceptorTokenId() {
+  return crypto.randomUUID().replace(/[^a-z0-9]/g, '');
+}
+
+export function isValidInterceptorTokenId(tokenId: string) {
+  return tokenId.length === INTERCEPTOR_TOKEN_ID_HEX_LENGTH && HEX_REGEX.test(tokenId);
+}
+
+function isValidInterceptorTokenValue(tokenValue: string) {
+  return tokenValue.length === INTERCEPTOR_TOKEN_VALUE_BASE64URL_LENGTH && BASE64URL_REGEX.test(tokenValue);
+}
+
+export async function createInterceptorTokensDirectory(tokensDirectory: string) {
+  try {
+    const parentTokensDirectory = path.dirname(tokensDirectory);
+    await fs.promises.mkdir(parentTokensDirectory, { recursive: true });
+    await fs.promises.mkdir(tokensDirectory, { mode: 0o700, recursive: true });
+    await fs.promises.appendFile(path.join(tokensDirectory, '.gitignore'), `*${os.EOL}`, { encoding: 'utf-8' });
+  } catch (error) {
+    logger.error(
+      `${color.red(color.bold('✖'))} Failed to create the tokens directory: ${color.magenta(tokensDirectory)}`,
+    );
+    throw error;
+  }
+}
+
+const interceptorTokenFileContentSchema = z.object({
+  version: z.literal(1),
+  token: z.object({
+    id: z.string().length(INTERCEPTOR_TOKEN_ID_HEX_LENGTH).regex(HEX_REGEX),
+    name: z.string().optional(),
+    secret: z.object({
+      hash: z.string().length(INTERCEPTOR_TOKEN_HASH_HEX_LENGTH).regex(HEX_REGEX),
+      salt: z.string().length(INTERCEPTOR_TOKEN_SALT_HEX_LENGTH).regex(HEX_REGEX),
+    }),
+    createdAt: z
+      .string()
+      .datetime()
+      .transform((value) => new Date(value)),
+  }),
+});
+
+export type InterceptorTokenFileContent = z.infer<typeof interceptorTokenFileContentSchema>;
+
+export namespace InterceptorTokenFileContent {
+  export type Input = z.input<typeof interceptorTokenFileContentSchema>;
+}
+
+export type PersistedInterceptorToken = InterceptorTokenFileContent['token'];
+
+namespace PersistedInterceptorToken {
+  export type Input = InterceptorTokenFileContent.Input['token'];
+}
+
+export async function saveInterceptorTokenToFile(tokensDirectory: string, token: InterceptorToken) {
+  const tokeFilePath = path.join(tokensDirectory, token.id);
+
+  const persistedToken: PersistedInterceptorToken.Input = {
+    id: token.id,
+    name: token.name,
+    secret: {
+      hash: token.secret.hash,
+      salt: token.secret.salt,
+    },
+    createdAt: token.createdAt.toISOString(),
+  };
+
+  const tokenFileContent = interceptorTokenFileContentSchema.parse({
+    version: 1,
+    token: persistedToken,
+  } satisfies InterceptorTokenFileContent.Input);
+
+  await fs.promises.writeFile(tokeFilePath, JSON.stringify(tokenFileContent, null, 2), {
+    mode: 0o600,
+    encoding: 'utf-8',
+  });
+
+  return tokeFilePath;
+}
+
+export async function readInterceptorTokenFromFile(
+  tokenId: InterceptorToken['id'],
+  options: { tokensDirectory: string },
+): Promise<PersistedInterceptorToken | null> {
+  if (!isValidInterceptorTokenId(tokenId)) {
+    throw new InvalidInterceptorTokenError(tokenId);
+  }
+
+  const tokenFilePath = path.join(options.tokensDirectory, tokenId);
+  const tokenFileExists = await pathExists(tokenFilePath);
+
+  if (!tokenFileExists) {
+    return null;
+  }
+
+  const tokenFileContentAsString = await fs.promises.readFile(tokenFilePath, { encoding: 'utf-8' });
+
+  const validation = interceptorTokenFileContentSchema.safeParse(JSON.parse(tokenFileContentAsString) as unknown);
+
+  if (!validation.success) {
+    throw new InvalidInterceptorTokenFileError(tokenFilePath, validation.error.message);
+  }
+
+  return validation.data.token;
+}
+
+export async function createInterceptorToken(options: {
+  name?: string;
+  tokensDirectory: string;
+}): Promise<InterceptorToken> {
+  const { name, tokensDirectory } = options;
+
+  const tokensDirectoryExists = await pathExists(tokensDirectory);
+
+  if (!tokensDirectoryExists) {
+    await createInterceptorTokensDirectory(tokensDirectory);
+  }
+
+  const tokenId = createInterceptorTokenId();
+
+  /* istanbul ignore if -- @preserve
+   * This should never happen, but let's check that the token identifier is valid after generated. */
+  if (!isValidInterceptorTokenId(tokenId)) {
+    throw new InvalidInterceptorTokenError(tokenId);
+  }
+
+  const tokenSecretSizeInBytes = convertHexLengthToByteLength(INTERCEPTOR_TOKEN_SECRET_HEX_LENGTH);
+  const tokenSecret = crypto.randomBytes(tokenSecretSizeInBytes).toString('hex');
+
+  const tokenSecretSaltSizeInBytes = convertHexLengthToByteLength(INTERCEPTOR_TOKEN_SALT_HEX_LENGTH);
+  const tokenSecretSalt = crypto.randomBytes(tokenSecretSaltSizeInBytes).toString('hex');
+  const tokenSecretHash = await hashInterceptorToken(tokenSecret, tokenSecretSalt);
+
+  const tokenValue = Buffer.from(`${tokenId}${tokenSecret}`, 'hex').toString('base64url');
+
+  /* istanbul ignore if -- @preserve
+   * This should never happen, but let's check that the token value is valid after generated. */
+  if (!isValidInterceptorTokenValue(tokenValue)) {
+    throw new InvalidInterceptorTokenValueError(tokenValue);
+  }
+
+  const token: InterceptorToken = {
+    id: tokenId,
+    name,
+    secret: {
+      hash: tokenSecretHash,
+      salt: tokenSecretSalt,
+      value: tokenSecret,
+    },
+    value: tokenValue,
+    createdAt: new Date(),
+  };
+
+  await saveInterceptorTokenToFile(tokensDirectory, token);
+
+  return token;
+}
+
+export async function listInterceptorTokens(options: { tokensDirectory: string }) {
+  const tokensDirectoryExists = await pathExists(options.tokensDirectory);
+
+  if (!tokensDirectoryExists) {
+    return [];
+  }
+
+  const files = await fs.promises.readdir(options.tokensDirectory);
+
+  const tokenReadPromises = files.map(async (file) => {
+    if (!isValidInterceptorTokenId(file)) {
+      return null;
+    }
+
+    const tokenId = file;
+    const token = await readInterceptorTokenFromFile(tokenId, options);
+    return token;
+  });
+
+  const tokenCandidates = await Promise.allSettled(tokenReadPromises);
+
+  const tokens: PersistedInterceptorToken[] = [];
+
+  for (const tokenCandidate of tokenCandidates) {
+    if (tokenCandidate.status === 'rejected') {
+      console.error(tokenCandidate.reason);
+    } else if (tokenCandidate.value !== null) {
+      tokens.push(tokenCandidate.value);
+    }
+  }
+
+  tokens.sort((token, otherToken) => token.createdAt.getTime() - otherToken.createdAt.getTime());
+
+  return tokens;
+}
+
+export async function validateInterceptorToken(tokenValue: string, options: { tokensDirectory: string }) {
+  if (!isValidInterceptorTokenValue(tokenValue)) {
+    throw new InvalidInterceptorTokenValueError(tokenValue);
+  }
+
+  const decodedTokenValue = Buffer.from(tokenValue, 'base64url').toString('hex');
+
+  const tokenId = decodedTokenValue.slice(0, INTERCEPTOR_TOKEN_ID_HEX_LENGTH);
+  const tokenSecret = decodedTokenValue.slice(
+    INTERCEPTOR_TOKEN_ID_HEX_LENGTH,
+    INTERCEPTOR_TOKEN_ID_HEX_LENGTH + INTERCEPTOR_TOKEN_VALUE_HEX_LENGTH,
+  );
+
+  const tokenFromFile = await readInterceptorTokenFromFile(tokenId, options);
+
+  if (!tokenFromFile) {
+    throw new InvalidInterceptorTokenValueError(tokenValue);
+  }
+
+  const tokenSecretHash = await hashInterceptorToken(tokenSecret, tokenFromFile.secret.salt);
+
+  if (tokenSecretHash !== tokenFromFile.secret.hash) {
+    throw new InvalidInterceptorTokenValueError(tokenValue);
+  }
+}
+
+export async function removeInterceptorToken(tokenId: string, options: { tokensDirectory: string }) {
+  /* istanbul ignore if -- @preserve
+   * At this point, we should have a valid tokenId. This is just a sanity check. */
+  if (!isValidInterceptorTokenId(tokenId)) {
+    throw new InvalidInterceptorTokenError(tokenId);
+  }
+
+  const tokenFilePath = path.join(options.tokensDirectory, tokenId);
+
+  await fs.promises.rm(tokenFilePath, { force: true });
+}

package/src/server/utils/fetch.ts

@@ -3,6 +3,8 @@ import { FetchAPI } from '@whatwg-node/server';
 import { importFile } from '@/utils/files';
 
 export async function getFetchAPI(): Promise<FetchAPI> {
+  const File = await importFile();
+
   return {
     fetch,
     Request,
@@ -17,7 +19,7 @@ export async function getFetchAPI(): Promise<FetchAPI> {
     TextDecoderStream,
     TextEncoderStream,
     Blob,
-    File: await importFile(),
+    File,
     crypto: globalThis.crypto,
     btoa,
     TextEncoder,

package/src/utils/data.ts

@@ -26,3 +26,16 @@ export function convertBase64ToArrayBuffer(base64Value: string) {
     return Buffer.from(base64Value, 'base64');
   }
 }
+
+export const HEX_REGEX = /^[a-z0-9]+$/;
+
+export function convertHexLengthToByteLength(hexLength: number) {
+  return Math.ceil(hexLength / 2); // 1 byte = 2 hex characters
+}
+
+export const BASE64URL_REGEX = /^[a-zA-Z0-9-_]+$/;
+
+export function convertHexLengthToBase64urlLength(hexLength: number) {
+  const byteLength = convertHexLengthToByteLength(hexLength);
+  return Math.ceil((byteLength * 4) / 3); // 1 byte = 4/3 base64url characters
+}

package/src/utils/files.ts

@@ -1,4 +1,5 @@
 import createCachedDynamicImport from '@zimic/utils/import/createCachedDynamicImport';
+import type fs from 'fs';
 
 export const importFile = createCachedDynamicImport(
   /* istanbul ignore next -- @preserve
@@ -11,3 +12,16 @@ export function isGlobalFileAvailable() {
   // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition
   return globalThis.File !== undefined;
 }
+
+export const importFilesystem = createCachedDynamicImport<typeof fs>(() => import('fs'));
+
+export async function pathExists(path: string) {
+  const fs = await importFilesystem();
+
+  try {
+    await fs.promises.access(path);
+    return true;
+  } catch {
+    return false;
+  }
+}

package/src/utils/{console.ts → logging.ts}

@@ -1,10 +1,15 @@
 import { HttpFormData, HttpHeaders, HttpSearchParams } from '@zimic/http';
 import createCachedDynamicImport from '@zimic/utils/import/createCachedDynamicImport';
+import Logger from '@zimic/utils/logging/Logger';
 import color from 'picocolors';
 
 import { isClientSide } from './environment';
 import { isGlobalFileAvailable } from './files';
 
+export const logger = new Logger({
+  prefix: color.cyan('[@zimic/interceptor]'),
+});
+
 function stringifyJSONToLog(value: unknown): string {
   return JSON.stringify(
     value,
@@ -79,10 +84,3 @@ export async function formatValueToLog(value: unknown, options: { colors?: boole
     sorted: true,
   });
 }
-
-export function logWithPrefix(messageOrMessages: unknown, options: { method?: 'log' | 'warn' | 'error' } = {}) {
-  const { method = 'log' } = options;
-
-  const messages = Array.isArray(messageOrMessages) ? messageOrMessages : [messageOrMessages];
-  console[method](color.cyan('[@zimic/interceptor]'), ...messages);
-}

package/src/utils/webSocket.ts

@@ -1,5 +1,8 @@
 import ClientSocket, { type WebSocketServer as ServerSocket } from 'isomorphic-ws';
 
+import { WebSocketControlMessage } from '@/webSocket/constants';
+import UnauthorizedWebSocketConnectionError from '@/webSocket/errors/UnauthorizedWebSocketConnectionError';
+
 class WebSocketTimeoutError extends Error {}
 
 export class WebSocketOpenTimeoutError extends WebSocketTimeoutError {
@@ -37,9 +40,10 @@ export async function waitForOpenClientSocket(
   socket: ClientSocket,
   options: {
     timeout?: number;
+    waitForAuthentication?: boolean;
   } = {},
 ) {
-  const { timeout: timeoutDuration = DEFAULT_WEB_SOCKET_LIFECYCLE_TIMEOUT } = options;
+  const { timeout: timeoutDuration = DEFAULT_WEB_SOCKET_LIFECYCLE_TIMEOUT, waitForAuthentication = false } = options;
 
   const isAlreadyOpen = socket.readyState === socket.OPEN;
 
@@ -48,24 +52,60 @@ export async function waitForOpenClientSocket(
   }
 
   await new Promise<void>((resolve, reject) => {
-    function handleOpenError(error: unknown) {
+    function removeAllSocketListeners() {
+      socket.removeEventListener('message', handleSocketMessage); // eslint-disable-line @typescript-eslint/no-use-before-define
       socket.removeEventListener('open', handleOpenSuccess); // eslint-disable-line @typescript-eslint/no-use-before-define
+      socket.removeEventListener('error', handleOpenError); // eslint-disable-line @typescript-eslint/no-use-before-define
+      socket.removeEventListener('close', handleClose); // eslint-disable-line @typescript-eslint/no-use-before-define
+    }
+
+    function handleOpenError(error: unknown) {
+      removeAllSocketListeners();
       reject(error);
     }
 
+    function handleClose(event: ClientSocket.CloseEvent) {
+      const isUnauthorized = event.code === 1008;
+
+      /* istanbul ignore else -- @preserve
+       * An unauthorized close event is the only one we expect to happen here. */
+      if (isUnauthorized) {
+        const unauthorizedError = new UnauthorizedWebSocketConnectionError(event);
+        handleOpenError(unauthorizedError);
+      } else {
+        handleOpenError(event);
+      }
+    }
+
     const openTimeout = setTimeout(() => {
       const timeoutError = new WebSocketOpenTimeoutError(timeoutDuration);
       handleOpenError(timeoutError);
     }, timeoutDuration);
 
     function handleOpenSuccess() {
-      socket.removeEventListener('error', handleOpenError);
+      removeAllSocketListeners();
       clearTimeout(openTimeout);
       resolve();
     }
 
-    socket.addEventListener('open', handleOpenSuccess);
+    function handleSocketMessage(message: ClientSocket.MessageEvent) {
+      const hasValidAuth = message.data === ('socket:auth:valid' satisfies WebSocketControlMessage);
+
+      /* istanbul ignore else -- @preserve
+       * We currently only support the 'socket:auth:valid' message and it is the only possible control message here. */
+      if (hasValidAuth) {
+        handleOpenSuccess();
+      }
+    }
+
+    if (waitForAuthentication) {
+      socket.addEventListener('message', handleSocketMessage);
+    } else {
+      socket.addEventListener('open', handleOpenSuccess);
+    }
+
     socket.addEventListener('error', handleOpenError);
+    socket.addEventListener('close', handleClose);
   });
 }
 
@@ -78,24 +118,30 @@ export async function closeClientSocket(socket: ClientSocket, options: { timeout
   }
 
   await new Promise<void>((resolve, reject) => {
-    function handleCloseError(error: unknown) {
-      socket.removeEventListener('close', handleCloseSuccess); // eslint-disable-line @typescript-eslint/no-use-before-define
+    function removeAllSocketListeners() {
+      socket.removeEventListener('error', handleError); // eslint-disable-line @typescript-eslint/no-use-before-define
+      socket.removeEventListener('close', handleClose); // eslint-disable-line @typescript-eslint/no-use-before-define
+    }
+
+    function handleError(error: unknown) {
+      removeAllSocketListeners();
       reject(error);
     }
 
     const closeTimeout = setTimeout(() => {
       const timeoutError = new WebSocketCloseTimeoutError(timeoutDuration);
-      handleCloseError(timeoutError);
+      handleError(timeoutError);
     }, timeoutDuration);
 
-    function handleCloseSuccess() {
-      socket.removeEventListener('error', handleCloseError);
+    function handleClose() {
+      removeAllSocketListeners();
       clearTimeout(closeTimeout);
       resolve();
     }
 
-    socket.addEventListener('error', handleCloseError);
-    socket.addEventListener('close', handleCloseSuccess);
+    socket.addEventListener('error', handleError);
+    socket.addEventListener('close', handleClose);
+
     socket.close();
   });
 }

package/src/webSocket/WebSocketClient.ts

@@ -1,7 +1,7 @@
 import validateURLProtocol from '@zimic/utils/url/validateURLProtocol';
 import ClientSocket from 'isomorphic-ws';
 
-import { WebSocket } from './types';
+import { WebSocketSchema } from './types';
 import WebSocketHandler from './WebSocketHandler';
 
 const SUPPORTED_WEB_SOCKET_PROTOCOLS = ['ws', 'wss'];
@@ -12,7 +12,7 @@ interface WebSocketClientOptions {
   messageTimeout?: number;
 }
 
-class WebSocketClient<Schema extends WebSocket.ServiceSchema> extends WebSocketHandler<Schema> {
+class WebSocketClient<Schema extends WebSocketSchema> extends WebSocketHandler<Schema> {
   private url: URL;
 
   private socket?: ClientSocket;
@@ -31,11 +31,17 @@ class WebSocketClient<Schema extends WebSocket.ServiceSchema> extends WebSocketH
     return this.socket !== undefined && this.socket.readyState === this.socket.OPEN;
   }
 
-  async start() {
-    this.socket = new ClientSocket(this.url);
+  async start(options: { parameters?: Record<string, string>; waitForAuthentication?: boolean } = {}) {
+    const parametersAsString = options.parameters
+      ? Object.entries(options.parameters)
+          .map(([key, value]) => `${key}=${value}`)
+          .map(encodeURIComponent)
+      : [];
+
+    this.socket = new ClientSocket(this.url, parametersAsString);
 
     try {
-      await super.registerSocket(this.socket);
+      await super.registerSocket(this.socket, options);
     } catch (error) {
       await this.stop();
       throw error;