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

package/src/http/interceptor/HttpInterceptorClient.ts

@@ -16,7 +16,6 @@ import validateURLProtocol from '@zimic/utils/url/validateURLProtocol';
 import { isServerSide } from '@/utils/environment';
 
 import HttpInterceptorWorker from '../interceptorWorker/HttpInterceptorWorker';
-import LocalHttpInterceptorWorker from '../interceptorWorker/LocalHttpInterceptorWorker';
 import HttpRequestHandlerClient, { AnyHttpRequestHandlerClient } from '../requestHandler/HttpRequestHandlerClient';
 import LocalHttpRequestHandler from '../requestHandler/LocalHttpRequestHandler';
 import RemoteHttpRequestHandler from '../requestHandler/RemoteHttpRequestHandler';
@@ -38,11 +37,13 @@ class HttpInterceptorClient<
   Schema extends HttpSchema,
   HandlerConstructor extends HttpRequestHandlerConstructor = HttpRequestHandlerConstructor,
 > {
-  private worker: HttpInterceptorWorker;
   private store: HttpInterceptorStore;
-
   private _baseURL!: URL;
 
+  private createWorker: () => HttpInterceptorWorker;
+  private deleteWorker: () => void;
+  private worker?: HttpInterceptorWorker;
+
   requestSaving: HttpInterceptorRequestSaving;
   private numberOfSavedRequests = 0;
 
@@ -67,18 +68,20 @@ class HttpInterceptorClient<
   };
 
   constructor(options: {
-    worker: HttpInterceptorWorker;
     store: HttpInterceptorStore;
     baseURL: URL;
+    createWorker: () => HttpInterceptorWorker;
+    deleteWorker: () => void;
     requestSaving?: Partial<HttpInterceptorRequestSaving>;
     onUnhandledRequest?: UnhandledRequestStrategy;
     Handler: HandlerConstructor;
   }) {
-    this.worker = options.worker;
     this.store = options.store;
-
     this.baseURL = options.baseURL;
 
+    this.createWorker = options.createWorker;
+    this.deleteWorker = options.deleteWorker;
+
     this.requestSaving = {
       enabled: options.requestSaving?.enabled ?? this.getDefaultRequestSavingEnabled(),
       safeLimit: options.requestSaving?.safeLimit ?? DEFAULT_REQUEST_SAVING_SAFE_LIMIT,
@@ -108,6 +111,7 @@ class HttpInterceptorClient<
 
     validateURLProtocol(newBaseURL, SUPPORTED_BASE_URL_PROTOCOLS);
     excludeURLParams(newBaseURL);
+
     this._baseURL = newBaseURL;
   }
 
@@ -118,29 +122,48 @@ class HttpInterceptorClient<
     return this.baseURL.href;
   }
 
+  private get workerOrThrow() {
+    if (!this.worker) {
+      throw new NotRunningHttpInterceptorError();
+    }
+    return this.worker;
+  }
+
   get platform() {
-    return this.worker.platform;
+    return this.worker?.platform ?? null;
   }
 
   async start() {
-    await this.worker.start();
+    try {
+      this.worker = this.createWorker();
 
-    this.worker.registerRunningInterceptor(this);
-    this.markAsRunning(true);
+      await this.worker.start();
+      this.worker.registerRunningInterceptor(this);
+
+      this.markAsRunning(true);
+    } catch (error) {
+      await this.stop();
+      throw error;
+    }
   }
 
   async stop() {
-    this.markAsRunning(false);
-    this.worker.unregisterRunningInterceptor(this);
+    this.worker?.unregisterRunningInterceptor(this);
 
-    const wasLastRunningInterceptor = this.numberOfRunningInterceptors() === 0;
-    if (wasLastRunningInterceptor) {
-      await this.worker.stop();
+    // The number of interceptors will be 0 if the first client could not start due to an error.
+    const isLastRunningInterceptor = this.numberOfRunningInterceptors === 0 || this.numberOfRunningInterceptors === 1;
+
+    if (isLastRunningInterceptor) {
+      await this.worker?.stop();
+      this.deleteWorker();
     }
+
+    this.markAsRunning(false);
+    this.worker = undefined;
   }
 
   private markAsRunning(isRunning: boolean) {
-    if (this.worker instanceof LocalHttpInterceptorWorker) {
+    if (this.workerOrThrow.type === 'local') {
       this.store.markLocalInterceptorAsRunning(this, isRunning);
     } else {
       this.store.markRemoteInterceptorAsRunning(this, isRunning, this.baseURL);
@@ -148,8 +171,12 @@ class HttpInterceptorClient<
     this.isRunning = isRunning;
   }
 
-  private numberOfRunningInterceptors() {
-    if (this.worker instanceof LocalHttpInterceptorWorker) {
+  get numberOfRunningInterceptors() {
+    if (!this.isRunning) {
+      return 0;
+    }
+
+    if (this.workerOrThrow.type === 'local') {
       return this.store.numberOfRunningLocalInterceptors;
     } else {
       return this.store.numberOfRunningRemoteInterceptors(this.baseURL);
@@ -222,7 +249,7 @@ class HttpInterceptorClient<
     const url = joinURL(this.baseURLAsString, handler.path);
     const urlRegex = createRegExpFromURL(url);
 
-    const registrationResult = this.worker.use(this, handler.method, url, async (context) => {
+    const registrationResult = this.workerOrThrow.use(this, handler.method, url, async (context) => {
       const response = await this.handleInterceptedRequest(
         urlRegex,
         handler.method,
@@ -316,11 +343,9 @@ class HttpInterceptorClient<
   }
 
   clear(options: { onCommitSuccess?: () => void; onCommitError?: () => void } = {}) {
-    if (!this.isRunning) {
-      throw new NotRunningHttpInterceptorError();
-    }
-
-    const clearResults: PossiblePromise<AnyHttpRequestHandlerClient | void>[] = [];
+    const clearResults: PossiblePromise<AnyHttpRequestHandlerClient | void>[] = [
+      this.workerOrThrow.clearInterceptorHandlers(this),
+    ];
 
     for (const method of HTTP_METHODS) {
       const newClearResults = this.clearMethodHandlers(method);
@@ -333,9 +358,6 @@ class HttpInterceptorClient<
       handlersByPath.clear();
     }
 
-    const clearResult = this.worker.clearInterceptorHandlers(this);
-    clearResults.push(clearResult);
-
     if (options.onCommitSuccess) {
       void Promise.all(clearResults).then(options.onCommitSuccess, options.onCommitError);
     }

package/src/http/interceptor/HttpInterceptorStore.ts

@@ -7,6 +7,10 @@ import {
 } from '../interceptorWorker/types/options';
 import { AnyHttpInterceptorClient } from './HttpInterceptorClient';
 
+interface RemoteWorkerKeyOptions {
+  auth: RemoteHttpInterceptorWorkerOptions['auth'];
+}
+
 class HttpInterceptorStore {
   private static _localWorker?: LocalHttpInterceptorWorker;
   private static runningLocalInterceptors = new Set<AnyHttpInterceptorClient>();
@@ -20,8 +24,16 @@ class HttpInterceptorStore {
     return this.class._localWorker;
   }
 
-  remoteWorker(baseURL: URL) {
-    return this.class.remoteWorkers.get(baseURL.origin);
+  private getRemoteWorkerKey(baseURL: URL, options: RemoteWorkerKeyOptions) {
+    if (!options.auth) {
+      return baseURL.origin;
+    }
+    return `${baseURL.origin}:${options.auth.token}`;
+  }
+
+  remoteWorker(baseURL: URL, options: RemoteWorkerKeyOptions) {
+    const remoteWorkerKey = this.getRemoteWorkerKey(baseURL, options);
+    return this.class.remoteWorkers.get(remoteWorkerKey);
   }
 
   get numberOfRunningLocalInterceptors() {
@@ -70,23 +82,27 @@ class HttpInterceptorStore {
     return createdWorker;
   }
 
+  deleteLocalWorker() {
+    this.class._localWorker = undefined;
+  }
+
   getOrCreateRemoteWorker(workerOptions: Omit<RemoteHttpInterceptorWorkerOptions, 'type'>) {
-    const existingWorker = this.class.remoteWorkers.get(workerOptions.serverURL.origin);
+    const remoteWorkerKey = this.getRemoteWorkerKey(workerOptions.serverURL, { auth: workerOptions.auth });
+    const existingWorker = this.class.remoteWorkers.get(remoteWorkerKey);
+
     if (existingWorker) {
       return existingWorker;
     }
 
     const createdWorker = createHttpInterceptorWorker({ ...workerOptions, type: 'remote' });
-    this.class.remoteWorkers.set(workerOptions.serverURL.origin, createdWorker);
+    this.class.remoteWorkers.set(remoteWorkerKey, createdWorker);
 
     return createdWorker;
   }
 
-  clear() {
-    this.class._localWorker = undefined;
-    this.class.runningLocalInterceptors.clear();
-    this.class.remoteWorkers.clear();
-    this.class.runningRemoteInterceptors.clear();
+  deleteRemoteWorker(baseURL: URL, options: RemoteWorkerKeyOptions) {
+    const remoteWorkerKey = this.getRemoteWorkerKey(baseURL, options);
+    this.class.remoteWorkers.delete(remoteWorkerKey);
   }
 }
 

package/src/http/interceptor/LocalHttpInterceptor.ts

@@ -15,12 +15,15 @@ class LocalHttpInterceptor<Schema extends HttpSchema> implements PublicLocalHttp
   constructor(options: LocalHttpInterceptorOptions) {
     const baseURL = new URL(options.baseURL);
 
-    const worker = this.store.getOrCreateLocalWorker({});
-
     this.client = new HttpInterceptorClient<Schema, typeof LocalHttpRequestHandler>({
-      worker,
       store: this.store,
       baseURL,
+      createWorker() {
+        return this.store.getOrCreateLocalWorker({});
+      },
+      deleteWorker() {
+        this.store.deleteLocalWorker();
+      },
       Handler: LocalHttpRequestHandler,
       onUnhandledRequest: options.onUnhandledRequest,
       requestSaving: options.requestSaving,

package/src/http/interceptor/RemoteHttpInterceptor.ts

@@ -15,13 +15,18 @@ class RemoteHttpInterceptor<Schema extends HttpSchema> implements PublicRemoteHt
   constructor(options: RemoteHttpInterceptorOptions) {
     const baseURL = new URL(options.baseURL);
 
-    const serverURL = new URL(baseURL.origin);
-    const worker = this.store.getOrCreateRemoteWorker({ serverURL });
-
     this.client = new HttpInterceptorClient<Schema, typeof RemoteHttpRequestHandler>({
-      worker,
       store: this.store,
       baseURL,
+      createWorker() {
+        return this.store.getOrCreateRemoteWorker({
+          serverURL: new URL(baseURL.origin),
+          auth: options.auth,
+        });
+      },
+      deleteWorker() {
+        this.store.deleteRemoteWorker(baseURL, { auth: options.auth });
+      },
       Handler: RemoteHttpRequestHandler,
       onUnhandledRequest: options.onUnhandledRequest,
       requestSaving: options.requestSaving,

package/src/http/interceptor/types/options.ts

@@ -160,6 +160,21 @@ export interface LocalHttpInterceptorOptions extends SharedHttpInterceptorOption
 export interface RemoteHttpInterceptorOptions extends SharedHttpInterceptorOptions {
   type: 'remote';
 
+  /**
+   * Options to authenticate the interceptor when connecting to an interceptor server. This is required if the
+   * interceptor server was started with the `--tokens-dir` option.
+   *
+   * @see {@link https://github.com/zimicjs/zimic/wiki/cli‐zimic‐interceptor‐server#authentication Interceptor server authentication}
+   */
+  auth?: {
+    /**
+     * The authentication token to use.
+     *
+     * @see {@link https://github.com/zimicjs/zimic/wiki/cli‐zimic‐interceptor‐server#authentication Interceptor server authentication}
+     */
+    token: string;
+  };
+
   /**
    * The strategy to use for unhandled requests. If a request starts with the base URL of the interceptor, but no
    * matching handler exists, this strategy will be used. If a function is provided, it will be called with the

package/src/http/interceptorWorker/HttpInterceptorWorker.ts

@@ -16,9 +16,9 @@ import { Default, PossiblePromise } from '@zimic/utils/types';
 import color from 'picocolors';
 
 import { removeArrayElement } from '@/utils/arrays';
-import { formatValueToLog, logWithPrefix } from '@/utils/console';
 import { isClientSide } from '@/utils/environment';
 import { methodCanHaveResponseBody } from '@/utils/http';
+import { formatValueToLog, logger } from '@/utils/logging';
 
 import HttpInterceptorClient, { AnyHttpInterceptorClient } from '../interceptor/HttpInterceptorClient';
 import { HttpInterceptorPlatform, HttpInterceptorType, UnhandledRequestStrategy } from '../interceptor/types/options';
@@ -35,10 +35,11 @@ import {
 import { DEFAULT_UNHANDLED_REQUEST_STRATEGY } from './constants';
 import InvalidFormDataError from './errors/InvalidFormDataError';
 import InvalidJSONError from './errors/InvalidJSONError';
+import { HttpInterceptorWorkerType } from './types/options';
 import { HttpResponseFactory } from './types/requests';
 
 abstract class HttpInterceptorWorker {
-  abstract readonly type: 'local' | 'remote';
+  abstract get type(): HttpInterceptorWorkerType;
 
   platform: HttpInterceptorPlatform | null = null;
   isRunning = false;
@@ -474,20 +475,17 @@ abstract class HttpInterceptorWorker {
       formatValueToLog(request.body),
     ]);
 
-    logWithPrefix(
-      [
-        `${action === 'bypass' ? 'Warning:' : 'Error:'} Request was not handled and was ` +
-          `${action === 'bypass' ? color.yellow('bypassed') : color.red('rejected')}.\n\n `,
-        `${request.method} ${request.url}`,
-        '\n    Headers:',
-        formattedHeaders,
-        '\n    Search params:',
-        formattedSearchParams,
-        '\n    Body:',
-        formattedBody,
-        '\n\nLearn more: https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#unhandled-requests',
-      ],
-      { method: action === 'bypass' ? 'warn' : 'error' },
+    logger[action === 'bypass' ? 'warn' : 'error'](
+      `${action === 'bypass' ? 'Warning:' : 'Error:'} Request was not handled and was ` +
+        `${action === 'bypass' ? color.yellow('bypassed') : color.red('rejected')}.\n\n `,
+      `${request.method} ${request.url}`,
+      '\n    Headers:',
+      formattedHeaders,
+      '\n    Search params:',
+      formattedSearchParams,
+      '\n    Body:',
+      formattedBody,
+      '\n\nLearn more: https://github.com/zimicjs/zimic/wiki/api‐zimic‐interceptor‐http#unhandled-requests',
     );
   }
 }

package/src/http/interceptorWorker/RemoteHttpInterceptorWorker.ts

@@ -6,7 +6,7 @@ import { HttpHandlerCommit, InterceptorServerWebSocketSchema } from '@/server/ty
 import { importCrypto } from '@/utils/crypto';
 import { isClientSide, isServerSide } from '@/utils/environment';
 import { deserializeRequest, serializeResponse } from '@/utils/fetch';
-import { WebSocket } from '@/webSocket/types';
+import { WebSocketEventMessage } from '@/webSocket/types';
 import WebSocketClient from '@/webSocket/WebSocketClient';
 
 import NotRunningHttpInterceptorError from '../interceptor/errors/NotRunningHttpInterceptorError';
@@ -26,24 +26,26 @@ interface HttpHandler {
 }
 
 class RemoteHttpInterceptorWorker extends HttpInterceptorWorker {
-  webSocketClient: WebSocketClient<InterceptorServerWebSocketSchema>;
-
   private httpHandlers = new Map<HttpHandler['id'], HttpHandler>();
 
+  webSocketClient: WebSocketClient<InterceptorServerWebSocketSchema>;
+  private auth?: RemoteHttpInterceptorWorkerOptions['auth'];
+
   constructor(options: RemoteHttpInterceptorWorkerOptions) {
     super();
 
-    const webSocketServerURL = this.deriveWebSocketServerURL(options.serverURL);
     this.webSocketClient = new WebSocketClient({
-      url: webSocketServerURL.toString(),
+      url: this.getWebSocketServerURL(options.serverURL).toString(),
     });
+
+    this.auth = options.auth;
   }
 
   get type() {
     return 'remote' as const;
   }
 
-  private deriveWebSocketServerURL(serverURL: URL) {
+  private getWebSocketServerURL(serverURL: URL) {
     const webSocketServerURL = new URL(serverURL);
     webSocketServerURL.protocol = serverURL.protocol.replace(/^http(s)?:$/, 'ws$1:');
     return webSocketServerURL;
@@ -51,7 +53,10 @@ class RemoteHttpInterceptorWorker extends HttpInterceptorWorker {
 
   async start() {
     await super.sharedStart(async () => {
-      await this.webSocketClient.start();
+      await this.webSocketClient.start({
+        parameters: this.auth ? { token: this.auth.token } : undefined,
+        waitForAuthentication: true,
+      });
 
       this.webSocketClient.onEvent('interceptors/responses/create', this.createResponse);
       this.webSocketClient.onEvent('interceptors/responses/unhandled', this.handleUnhandledServerRequest);
@@ -62,7 +67,7 @@ class RemoteHttpInterceptorWorker extends HttpInterceptorWorker {
   }
 
   private createResponse = async (
-    message: WebSocket.ServiceEventMessage<InterceptorServerWebSocketSchema, 'interceptors/responses/create'>,
+    message: WebSocketEventMessage<InterceptorServerWebSocketSchema, 'interceptors/responses/create'>,
   ) => {
     const { handlerId, request: serializedRequest } = message.data;
 
@@ -87,7 +92,7 @@ class RemoteHttpInterceptorWorker extends HttpInterceptorWorker {
   };
 
   private handleUnhandledServerRequest = async (
-    message: WebSocket.ServiceEventMessage<InterceptorServerWebSocketSchema, 'interceptors/responses/unhandled'>,
+    message: WebSocketEventMessage<InterceptorServerWebSocketSchema, 'interceptors/responses/unhandled'>,
   ) => {
     const { request: serializedRequest } = message.data;
     const request = deserializeRequest(serializedRequest);
@@ -156,7 +161,7 @@ class RemoteHttpInterceptorWorker extends HttpInterceptorWorker {
 
     this.httpHandlers.set(handler.id, handler);
 
-    await this.webSocketClient.request('interceptors/workers/use/commit', {
+    await this.webSocketClient.request('interceptors/workers/commit', {
       id: handler.id,
       url: handler.url,
       method,
@@ -171,7 +176,7 @@ class RemoteHttpInterceptorWorker extends HttpInterceptorWorker {
     this.httpHandlers.clear();
 
     if (this.webSocketClient.isRunning) {
-      await this.webSocketClient.request('interceptors/workers/use/reset', undefined);
+      await this.webSocketClient.request('interceptors/workers/reset', undefined);
     }
   }
 
@@ -193,7 +198,7 @@ class RemoteHttpInterceptorWorker extends HttpInterceptorWorker {
         method: handler.method,
       }));
 
-      await this.webSocketClient.request('interceptors/workers/use/reset', groupsToRecommit);
+      await this.webSocketClient.request('interceptors/workers/reset', groupsToRecommit);
     }
   }
 

package/src/http/interceptorWorker/types/options.ts

@@ -5,6 +5,7 @@ export interface LocalHttpInterceptorWorkerOptions {
 export interface RemoteHttpInterceptorWorkerOptions {
   type: 'remote';
   serverURL: URL;
+  auth?: { token: string };
 }
 
 export type HttpInterceptorWorkerOptions = LocalHttpInterceptorWorkerOptions | RemoteHttpInterceptorWorkerOptions;

package/src/http/requestHandler/errors/TimesCheckError.ts

@@ -3,7 +3,7 @@ import { Range } from '@zimic/utils/types';
 import color from 'picocolors';
 
 import { HttpInterceptorRequestSaving } from '@/http/interceptor/types/public';
-import { stringifyValueToLog } from '@/utils/console';
+import { stringifyValueToLog } from '@/utils/logging';
 
 import { UnmatchedHttpInterceptorRequestGroup } from '../types/restrictions';
 import TimesDeclarationPointer from './TimesDeclarationPointer';

package/src/server/InterceptorServer.ts

@@ -10,8 +10,8 @@ import { removeArrayIndex } from '@/utils/arrays';
 import { deserializeResponse, SerializedHttpRequest, serializeRequest } from '@/utils/fetch';
 import { getHttpServerPort, startHttpServer, stopHttpServer } from '@/utils/http';
 import { WebSocketMessageAbortError } from '@/utils/webSocket';
-import { WebSocket } from '@/webSocket/types';
-import WebSocketServer from '@/webSocket/WebSocketServer';
+import { WebSocketEventMessage } from '@/webSocket/types';
+import WebSocketServer, { WebSocketServerAuthenticate } from '@/webSocket/WebSocketServer';
 
 import {
   DEFAULT_ACCESS_CONTROL_HEADERS,
@@ -24,6 +24,7 @@ import RunningInterceptorServerError from './errors/RunningInterceptorServerErro
 import { InterceptorServerOptions } from './types/options';
 import { InterceptorServer as PublicInterceptorServer } from './types/public';
 import { HttpHandlerCommit, InterceptorServerWebSocketSchema } from './types/schema';
+import { validateInterceptorToken } from './utils/auth';
 import { getFetchAPI } from './utils/fetch';
 
 interface HttpHandler {
@@ -42,6 +43,7 @@ class InterceptorServer implements PublicInterceptorServer {
   _hostname: string;
   _port: number | undefined;
   logUnhandledRequests: boolean;
+  tokensDirectory?: string;
 
   private httpHandlerGroups: {
     [Method in HttpMethod]: HttpHandler[];
@@ -61,6 +63,7 @@ class InterceptorServer implements PublicInterceptorServer {
     this._hostname = options.hostname ?? DEFAULT_HOSTNAME;
     this._port = options.port;
     this.logUnhandledRequests = options.logUnhandledRequests ?? DEFAULT_LOG_UNHANDLED_REQUESTS;
+    this.tokensDirectory = options.tokensDirectory;
   }
 
   get hostname() {
@@ -120,10 +123,48 @@ class InterceptorServer implements PublicInterceptorServer {
 
     this.webSocketServer = new WebSocketServer({
       httpServer: this.httpServer,
+      authenticate: this.authenticateWebSocketConnection,
     });
+
     this.startWebSocketServer();
   }
 
+  private authenticateWebSocketConnection: WebSocketServerAuthenticate = async (_socket, request) => {
+    if (!this.tokensDirectory) {
+      return { isValid: true };
+    }
+
+    const tokenValue = this.getWebSocketRequestTokenValue(request);
+
+    if (!tokenValue) {
+      return { isValid: false, message: 'An interceptor token is required, but none was provided.' };
+    }
+
+    try {
+      await validateInterceptorToken(tokenValue, { tokensDirectory: this.tokensDirectory });
+      return { isValid: true };
+    } catch (error) {
+      console.error(error);
+      return { isValid: false, message: 'The interceptor token is not valid.' };
+    }
+  };
+
+  private getWebSocketRequestTokenValue(request: IncomingMessage) {
+    const protocols = request.headers['sec-websocket-protocol'] ?? '';
+    const parametersAsString = decodeURIComponent(protocols).split(', ');
+
+    for (const parameterAsString of parametersAsString) {
+      const tokenValueMatch = /^token=(?<tokenValue>.+?)$/.exec(parameterAsString);
+      const tokenValue = tokenValueMatch?.groups?.tokenValue;
+
+      if (tokenValue) {
+        return tokenValue;
+      }
+    }
+
+    return undefined;
+  }
+
   private async startHttpServer() {
     await startHttpServer(this.httpServerOrThrow, {
       hostname: this.hostname,
@@ -136,22 +177,25 @@ class InterceptorServer implements PublicInterceptorServer {
 
   private startWebSocketServer() {
     this.webSocketServerOrThrow.start();
-    this.webSocketServerOrThrow.onEvent('interceptors/workers/use/commit', this.commitWorker);
-    this.webSocketServerOrThrow.onEvent('interceptors/workers/use/reset', this.resetWorker);
+
+    this.webSocketServerOrThrow.onEvent('interceptors/workers/commit', this.commitWorker);
+    this.webSocketServerOrThrow.onEvent('interceptors/workers/reset', this.resetWorker);
   }
 
   private commitWorker = (
-    message: WebSocket.ServiceEventMessage<InterceptorServerWebSocketSchema, 'interceptors/workers/use/commit'>,
+    message: WebSocketEventMessage<InterceptorServerWebSocketSchema, 'interceptors/workers/commit'>,
     socket: Socket,
   ) => {
     const commit = message.data;
+
     this.registerHttpHandler(commit, socket);
     this.registerWorkerSocketIfUnknown(socket);
+
     return {};
   };
 
   private resetWorker = (
-    message: WebSocket.ServiceEventMessage<InterceptorServerWebSocketSchema, 'interceptors/workers/use/reset'>,
+    message: WebSocketEventMessage<InterceptorServerWebSocketSchema, 'interceptors/workers/reset'>,
     socket: Socket,
   ) => {
     this.removeHttpHandlersBySocket(socket);
@@ -226,8 +270,8 @@ class InterceptorServer implements PublicInterceptorServer {
   }
 
   private async stopWebSocketServer() {
-    this.webSocketServerOrThrow.offEvent('interceptors/workers/use/commit', this.commitWorker);
-    this.webSocketServerOrThrow.offEvent('interceptors/workers/use/reset', this.resetWorker);
+    this.webSocketServerOrThrow.offEvent('interceptors/workers/commit', this.commitWorker);
+    this.webSocketServerOrThrow.offEvent('interceptors/workers/reset', this.resetWorker);
 
     await this.webSocketServerOrThrow.stop();
 

package/src/server/constants.ts

@@ -22,7 +22,7 @@ export const DEFAULT_ACCESS_CONTROL_HEADERS = Object.freeze({
   'access-control-allow-methods': ALLOWED_ACCESS_CONTROL_HTTP_METHODS,
   'access-control-allow-headers': '*',
   'access-control-expose-headers': '*',
-  'access-control-max-age': process.env.SERVER_ACCESS_CONTROL_MAX_AGE,
+  'access-control-max-age': process.env.INTERCEPTOR_SERVER_ACCESS_CONTROL_MAX_AGE,
 }) satisfies AccessControlHeaders;
 
 /** The default status code for the preflight request. */

package/src/server/errors/InvalidInterceptorTokenError.ts

@@ -0,0 +1,13 @@
+/**
+ * Error thrown when an interceptor token is invalid.
+ *
+ * @see {@link https://github.com/zimicjs/zimic/wiki/cli‐zimic‐interceptor‐server#authentication Interceptor server authentication}
+ */
+class InvalidInterceptorTokenError extends Error {
+  constructor(tokenId: string) {
+    super(`Invalid interceptor token: ${tokenId}`);
+    this.name = 'InvalidInterceptorTokenError';
+  }
+}
+
+export default InvalidInterceptorTokenError;

package/src/server/errors/InvalidInterceptorTokenFileError.ts

@@ -0,0 +1,13 @@
+/**
+ * Error thrown when an interceptor token file is invalid.
+ *
+ * @see {@link https://github.com/zimicjs/zimic/wiki/cli‐zimic‐interceptor‐server#authentication Interceptor server authentication}
+ */
+class InvalidInterceptorTokenFileError extends Error {
+  constructor(tokenFilePath: string, validationErrorMessage: string) {
+    super(`Invalid interceptor token file ${tokenFilePath}: ${validationErrorMessage}`);
+    this.name = 'InvalidInterceptorTokenFileError';
+  }
+}
+
+export default InvalidInterceptorTokenFileError;

package/src/server/errors/InvalidInterceptorTokenValueError.ts

@@ -0,0 +1,13 @@
+/**
+ * Error thrown when an interceptor token value is invalid.
+ *
+ * @see {@link https://github.com/zimicjs/zimic/wiki/cli‐zimic‐interceptor‐server#authentication Interceptor server authentication}
+ */
+class InvalidInterceptorTokenValueError extends Error {
+  constructor(tokenValue: string) {
+    super(`Invalid interceptor token value: ${tokenValue}`);
+    this.name = 'InvalidInterceptorTokenValueError';
+  }
+}
+
+export default InvalidInterceptorTokenValueError;

package/src/server/types/options.ts

@@ -21,4 +21,13 @@ export interface InterceptorServerOptions {
    * @default true
    */
   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;
 }