@datadome/module-nextjs/src/middleware.ts

DataDome module for Next.js applications

import { NextRequest, NextResponse } from 'next/server';
import {
    DEFAULT_SERVER_SIDE_URL,
    DEFAULT_TIMEOUT,
    DEFAULT_URI_REGEX_EXCLUSION,
    MODULE_NAME,
    MODULE_VERSION,
} from './constants';
import { getCookieData, getAuthorizationLength, getHeadersList, stringify, convertHeadersToMap } from './utils';

/**
 * Request properties to be sent to the Protection API for validation
 */
export interface RequestData {
    Accept?: string | null;
    AcceptCharset?: string | null;
    AcceptEncoding?: string | null;
    AcceptLanguage?: string | null;
    APIConnectionState?: string | null;
    AuthorizationLen?: number | null;
    CacheControl?: string | null;
    ClientID?: string | null;
    Connection?: string | null;
    ContentType?: string | null;
    CookiesLen?: number | null;
    From?: string | null;
    HeadersList?: string | null;
    Host?: string | null;
    IP: string;
    JA4?: string | null;
    Key: string;
    Method?: string | null;
    ModuleVersion?: string | null;
    Origin?: string | null;
    Port?: number | null;
    PostParamLen?: string | null;
    Pragma?: string | null;
    Protocol?: string | null;
    Referer?: string | null;
    Request?: string | null;
    RequestModuleName?: string | null;
    SecCHDeviceMemory?: string | null;
    SecCHUA?: string | null;
    SecCHUAArch?: string | null;
    SecCHUAFullVersionList?: string | null;
    SecCHUAMobile?: string | null;
    SecCHUAModel?: string | null;
    SecCHUAPlatform?: string | null;
    SecFetchDest?: string | null;
    SecFetchMode?: string | null;
    SecFetchSite?: string | null;
    SecFetchUser?: string | null;
    ServerHostname?: string | null;
    ServerName?: string | null;
    ServerRegion?: string | null;
    TimeRequest?: number | null;
    TrueClientIP?: string | null;
    UserAgent?: string | null;
    Via?: string | null;
    'X-Real-IP'?: string | null;
    'X-Requested-With'?: string | null;
    XForwardedForIP?: string | null;
}

export interface Logger {
    debug: (message: string) => void;
    info: (message: string) => void;
    warn: (message: string) => void;
    error: (message: string) => void;
}

/**
 * The options to customize the {@link DataDomeMiddleware} behavior
 */
export interface DataDomeMiddlewareOptions {
    endpointHost?: string;
    urlPatternExclusion?: string;
    logger?: Logger;
    timeout?: number;
}

/**
 * @returns {DataDomeMiddlewareOptions} default module and connection parameters
 */
function getModuleDefaults() {
    return {
        endpointHost: DEFAULT_SERVER_SIDE_URL,
        logger: console,
        moduleName: MODULE_NAME,
        moduleVersion: MODULE_VERSION,
        timeout: DEFAULT_TIMEOUT,
        urlPatternExclusion: DEFAULT_URI_REGEX_EXCLUSION,
    };
}

/**
 * The DataDome's middleware that will be used to protect the traffic.
 */
export class DataDomeMiddleware {
    serverSideKey: string;
    moduleName: string;
    moduleVersion: string;
    logger: Logger;
    endpointHost: string;
    urlPatternExclusion: RegExp;
    timeout: number;

    constructor(serverSideKey: string, parameters?: DataDomeMiddlewareOptions) {
        const finalParameters = Object.assign({}, getModuleDefaults(), parameters);

        const { moduleName, moduleVersion, urlPatternExclusion, logger } = finalParameters;
        let { endpointHost, timeout } = finalParameters;

        if (serverSideKey == null || serverSideKey === '') {
            throw new Error('Missing API key');
        }
        if (timeout <= 0) {
            timeout = DEFAULT_TIMEOUT;
            logger.warn(`[DataDome] using default timeout of ${timeout}ms`);
        }
        if (!/https?:\/\//i.test(endpointHost)) {
            endpointHost = 'https://' + endpointHost;
        }
        logger.info(`[DataDome] using endpoint url: ${endpointHost}`);

        this.serverSideKey = serverSideKey;
        this.moduleName = moduleName;
        this.moduleVersion = moduleVersion;
        this.logger = logger;
        this.endpointHost = endpointHost;
        this.urlPatternExclusion = new RegExp(urlPatternExclusion, 'i');
        this.timeout = timeout;
    }

    /**
     * Extract the fingerprint from the request, build a request to the Protection API, and returns the response
     * @memberof DataDomeMiddleware
     * @param req - The incoming request.
     * @returns The response of the Protection API.
     */
    async handleRequest(req: NextRequest, res: NextResponse = NextResponse.next()): Promise<NextResponse> {
        if (!this.isRequestProtected(req)) {
            return res;
        }
        const requestData = this.buildRequestPayload(req);
        const datadomeRes = await this.sendRequest(req, requestData);
        if (!datadomeRes) {
            return res;
        }
        return this.handleResponse(req, res, datadomeRes);
    }

    /**
     * @private
     * @param req - The incoming request.
     * @returns Returns true if the request must be protected. It returns false otherwise.
     */
    private isRequestProtected(req: NextRequest): boolean {
        return !this.urlPatternExclusion.test(req.nextUrl.pathname);
    }

    /**
     * This function extracts the information from the incoming request and returns the body payload for the Protection API.
     * @private
     * @param key - The server-side key of the user.
     * @param req - The incoming request.
     * @returns The {@link RequestData} payload for the Protection API.
     */
    private buildRequestPayload(req: NextRequest): RequestData {
        const clientId = getCookieData(req.cookies);
        const cookiesLength = req.headers.get('cookie')?.length ?? 0;
        return {
            Key: this.serverSideKey,
            // this should be `x-real-ip` but it doesn't currently work on Edge Middleware
            // localhost won't likely be blocked by Datadome unless you use your real IP
            // IP: 'YOUR IP',
            IP: (req.headers.get('x-forwarded-for') || '127.0.0.1').split(',')[0],
            RequestModuleName: this.moduleName,
            ModuleVersion: this.moduleVersion,
            AuthorizationLen: getAuthorizationLength(req),
            Accept: req.headers.get('accept'),
            AcceptEncoding: req.headers.get('accept-encoding'),
            AcceptLanguage: req.headers.get('accept-language'),
            AcceptCharset: req.headers.get('accept-charset'),
            CacheControl: req.headers.get('cache-control'),
            ClientID: clientId,
            Connection: req.headers.get('connection'),
            ContentType: req.headers.get('content-type'),
            CookiesLen: cookiesLength,
            From: req.headers.get('from'),
            HeadersList: getHeadersList(req),
            Host: req.headers.get('host'),
            JA4: req.headers.get('x-vercel-ja4-digest'),
            Method: req.method,
            Origin: req.headers.get('origin'),
            Port: 0,
            Pragma: req.headers.get('pragma'),
            PostParamLen: req.headers.get('content-length'),
            Protocol: req.headers.get('x-forwarded-proto'),
            Referer: req.headers.get('referer'),
            Request: req.nextUrl.pathname + req.nextUrl.search,
            ServerHostname: req.headers.get('host'),
            ServerName: 'vercel',
            ServerRegion: req.headers.get('x-vercel-edge-region') || 'sfo1',
            TimeRequest: Date.now() * 1000,
            TrueClientIP: req.headers.get('true-client-ip'),
            UserAgent: req.headers.get('user-agent'),
            Via: req.headers.get('via'),
            XForwardedForIP: req.headers.get('x-forwarded-for'),
            SecCHDeviceMemory: req.headers.get('sec-ch-device-memory'),
            SecCHUA: req.headers.get('sec-ch-ua'),
            SecCHUAArch: req.headers.get('sec-ch-ua-arch'),
            SecCHUAFullVersionList: req.headers.get('sec-ch-ua-full-version-list'),
            SecCHUAMobile: req.headers.get('sec-ch-ua-mobile'),
            SecCHUAModel: req.headers.get('sec-ch-ua-model'),
            SecCHUAPlatform: req.headers.get('sec-ch-ua-platform'),
            SecFetchDest: req.headers.get('sec-fetch-dest'),
            SecFetchMode: req.headers.get('sec-fetch-mode'),
            SecFetchSite: req.headers.get('sec-fetch-site'),
            SecFetchUser: req.headers.get('sec-fetch-user'),
            'X-Real-IP': req.headers.get('x-real-ip'),
            'X-Requested-With': req.headers.get('x-requested-with'),
        };
    }

    /**
     * This function performs the request to the Protection API and returns its result.
     * @private
     * @param req - The incoming request.
     * @param requestData - The truncated body payload for the Protection API.
     * @returns It returns the response of the Protection API, or `null` if an error occured.
     */
    private async sendRequest(req: NextRequest, requestData: RequestData): Promise<Response | null> {
        const options: RequestInit = {
            method: 'POST',
            headers: {
                'Content-Type': 'application/x-www-form-urlencoded',
                'User-Agent': 'DataDome',
                Connection: 'keep-alive',
            },
        };
        if (req.headers.get('x-datadome-clientid')?.length) {
            this.logger.debug('[DataDome] Using SessionByHeader');
            (options.headers as Record<string, string>)['X-DataDome-X-Set-Cookie'] = 'true';
            requestData.ClientID = req.headers.get('x-datadome-clientid') as string;
        }
        options.body = stringify(this.truncateRequestData(requestData));

        const dataDomeReq = fetch(this.endpointHost + '/validate-request/', options);

        const timeoutPromise = new Promise((resolve, reject) => {
            setTimeout(() => {
                reject(new Error('Datadome timeout'));
            }, this.timeout);
        });

        try {
            return (await Promise.race([dataDomeReq, timeoutPromise])) as Response;
        } catch (err) {
            if (err instanceof Error) {
                this.logger.warn(
                    `[DataDome] ${err.message} - no response within configured timeout of ${this.timeout}ms for request ${req.method} ${req.nextUrl.pathname}`,
                );
            } else {
                this.logger.warn(
                    `[DataDome] no response within configured timeout of ${this.timeout}ms for request ${req.method} ${req.nextUrl.pathname}`,
                );
            }
            return null;
        }
    }

    /**
     * This functions interprets the response of the Protection API and returns a NextResponse.
     * @param req - The incoming request.
     * @param res - The outcoming next response.
     * @param datadomeRes - The response from the Protection API.
     * @returns It returns the {@link NextResponse} for the middleware.
     */
    private async handleResponse(req: NextRequest, res: NextResponse, datadomeRes: Response): Promise<NextResponse> {
        switch (datadomeRes.status) {
            case 400:
                // Something is wrong with our authentication
                this.logger.error(
                    `[DataDome] ERROR returned 400 ${datadomeRes.statusText}, ${await datadomeRes.text()}`,
                );
                break;
            case 200:
            case 301:
            case 302:
            case 401:
            case 403:
                if (
                    datadomeRes.status !== 200 &&
                    datadomeRes.status.toString() == datadomeRes.headers.get('X-DataDomeResponse')
                ) {
                    // Request blocked - build the challenge response

                    // We need to clone headers as they are not replicated by spreading the `res` object
                    // We also need to exclude `x-middleware-next` header to display the captcha.
                    const clonedHeaders = new Headers();
                    res.headers.forEach((value, key) => {
                        if (key.toLowerCase() !== 'x-middleware-next') {
                            clonedHeaders.set(key, value);
                        }
                    });
                    res = new NextResponse(datadomeRes.body, {
                        ...res,
                        headers: clonedHeaders,
                        status: datadomeRes.status,
                    });
                } else {
                    // Add DataDome request headers to the response
                    convertHeadersToMap(req.headers, datadomeRes.headers, 'x-datadome-request-headers').forEach(
                        (value, key) => {
                            res.headers.set(key, value);
                        },
                    );
                }

                // Add DataDome headers to the response
                convertHeadersToMap(req.headers, datadomeRes.headers, 'x-datadome-headers').forEach((value, key) => {
                    res.headers.set(key, value);
                });
                this.logger.debug(
                    `[DataDome] response:${res.status}: ${JSON.stringify(Object.fromEntries(res.headers.entries()), null, 2)}`,
                );
        }
        return res;
    }

    /**
     * This function is used to truncate the fields of the payload of the Protection API.
     * @param requestData - The payload for the Protection API.
     * @returns The truncated payload for the Protection API.
     */
    private truncateRequestData(requestData: RequestData): RequestData {
        const limits: Record<string, number> = {
            secfetchuser: 8,
            secchdevicememory: 8,
            secchuamobile: 8,
            tlsprotocol: 8,
            secchuaarch: 16,
            contenttype: 64,
            secchuaplatform: 32,
            secfetchdest: 32,
            secfetchmode: 32,
            serverregion: 32,
            secfetchsite: 64,
            tlscipher: 64,
            clientid: 128,
            from: 128,
            'x-requested-with': 128,
            'x-real-ip': 128,
            acceptcharset: 128,
            acceptencoding: 128,
            connection: 128,
            pragma: 128,
            cachecontrol: 128,
            secchua: 128,
            secchuamodel: 128,
            trueclientip: 128,
            secchuafullversionlist: 256,
            acceptlanguage: 256,
            via: 256,
            headerslist: 512,
            origin: 512,
            serverhostname: 512,
            servername: 512,
            xforwardedforip: -512,
            accept: 512,
            host: 512,
            useragent: 768,
            referer: 1024,
            request: 2048,
        };

        for (const key in requestData) {
            const k = key as keyof RequestData;
            const value = requestData[k];
            const limit = limits[k.toLowerCase()];
            if (limit && value && typeof value == 'string' && value.length > Math.abs(limit)) {
                this.logger.debug(`[DataDome] truncating header[${limit}]: ${key} - value:${value}`);
                if (limit > 0) {
                    (requestData[k] as RequestData[keyof RequestData]) = value.substring(0, limit);
                } else {
                    (requestData[k] as RequestData[keyof RequestData]) = value.slice(limit);
                }
            }
        }
        return requestData;
    }
}