fingerprintApis.mjs

/**
 * Implementation of `gulp update-codeql`;
 * this fetches duckduckgo's "fingerprinting score" of browser APIs
 * and generates codeQL classes (essentially data tables) containing info about
 * the APIs, used by codeQL queries to scan for their usage in the codebase.
 */

import _ from 'lodash';

const weightsUrl = `https://raw.githubusercontent.com/duckduckgo/tracker-radar/refs/heads/main/build-data/generated/api_fingerprint_weights.json`;
import fs from 'fs/promises';
import path from 'path';

const MIN_WEIGHT = 15;
const QUERY_DIR = path.join(import.meta.dirname, '.github/codeql/queries');
const TYPE_FILE_PREFIX = 'autogen_';

async function fetchWeights() {
  const weights = await fetch(weightsUrl).then(res => res.json());
  return Object.fromEntries(
    Object.entries(weights).filter(([api, weight]) => weight >= MIN_WEIGHT)
  );
}

const TUPLE_TPL = _.template(`// this file is autogenerated, see fingerprintApis.mjs

class <%= name %> extends string {
<% fields.forEach(([type, name]) => {%>
  <%= type %> <%= name %>; <%}) %>
  
  <%= name %>() {<% values.forEach((vals, i) => { %>
      <% if(i > 0) {%> or <% }%>
      (<% vals.forEach(([name, value], j) => { %> <% if(j > 0) {%> and <% }%><%= name %> = <%= value %><%})%> )<%})%>
  }  
<% fields.forEach(([type, name]) => {%>
  <%= type %> get<%= name.charAt(0).toUpperCase() + name.substring(1) %>() {
    result = <%= name %>
  }
  <% }) %>
} 
`);

/**
 * Generate source for a codeQL class containing a set of API names and other data
 * that may be necessary to query for them.
 *
 * The generated type has at least
 *
 *  "string this" set to the API name,
 *  "float weight" set to the fingerprinting weight.
 *
 * @param name Class name
 * @param fields Additional fields, provided a list of [type, name] pairs.
 * @param values A list of values each provided as a [weight, ...fieldValues, apiName] tuple.
 *   `fieldValues` must map onto `fields`.
 */
function makeTupleType(name, fields, values) {
  const quote = (val)  => typeof val === 'string' ? `"${val}"` : val;
  fields.unshift(['float', 'weight']);
  values = values.map((vals) => {
    return [
      ['this', quote(vals.pop())],
      ...fields.map(([_, name], i) => ([name, quote(vals[i])]))
    ]
  })
  return [
    name,
    TUPLE_TPL({
      name, fields, values
    })
  ];
}

/**
 * Global names - no other metadata necessary
 */
function globalConstructor(matches) {
  return makeTupleType('GlobalConstructor', [], matches)
}

/**
 * Global names - no other metadata necessary
 */
function globalVar(matches) {
  return makeTupleType(
    'GlobalVar',
    [],
    matches
  );
}


/**
 * Property of some globally available type.
 * this = property name
 * global0...globalN: names used to reach the type from the global; last is the type itself.
 *  e.g. `Intl.DateTimeFormat` has global0 = 'Intl', global1 = 'DateTimeFormat'.
 */
function globalTypeProperty(depth = 0) {
  const fields = Array.from(Array(depth + 1).keys()).map(i => (['string', `global${i}`]))
  return function (matches) {
    return makeTupleType(`GlobalTypeProperty${depth}`, fields, matches)
  }
}

/**
 * Property of some globally available object.
 * this = property name
 * global0...globalN: path to reach the object (as in globalTypeProperty)
 */
function globalObjectProperty(depth, getPath) {
  const fields = Array.from(Array(depth + 1).keys()).map((i) => (['string', `global${i}`]))
  return function (matches) {
    return makeTupleType(
      `GlobalObjectProperty${depth}`,
      fields,
      matches.map(([weight, ...values]) => [weight, ...getPath(values), values[values.length - 1]])
    )
  }
}

/**
 * Property of a canvas' RenderingContext.
 *
 * this = property name
 * contextType = the argument passed to `getContext`.
 */
function renderingContextProperty(matches) {
  const fields = [['string', 'contextType']];
  const contextMap = {
    'WebGLRenderingContext': 'webgl',
    'WebGL2RenderingContext': 'webgl2',
    'CanvasRenderingContext2D': '2d'
  }
  matches = matches.map(([weight, contextType, prop]) => [
    weight, contextMap[contextType], prop
  ]);
  return makeTupleType('RenderingContextProperty', fields, matches);
}

/**
 * Property of an event object.
 *
 *  this = property name
 *  event = event type
 */
function eventProperty(matches) {
  const fields = [['string', 'event']];
  const eventMap = {
    'RTCPeerConnectionIce': 'icecandidate'
  }
  matches = matches.map(([weight, eventType, prop]) => [weight, eventMap[eventType] ?? eventType.toLowerCase(), prop])
  return makeTupleType('EventProperty', fields, matches);
}

/**
 * Property of a sensor object.
 */
function sensorProperty(matches) {
  return makeTupleType('SensorProperty', [], matches);
}

/**
 * Method of some type.
 * this =  method name
 * type = prototype name
 */
function domMethod(matches) {
  return makeTupleType('DOMMethod', [['string', 'type']], matches)
}

const API_MATCHERS = [
  [/^([^.]+)\.prototype.constructor$/, globalConstructor],
  [/^(Date|Gyroscope)\.prototype\.(.*)$/, globalTypeProperty()],
  [/^(Intl)\.(DateTimeFormat)\.prototype\.(.*)$/, globalTypeProperty(1)],
  [/^(Screen\.prototype|Notification|Navigator\.prototype)\.(.*)$/, globalObjectProperty(0,
    ([name]) => ({
      'Screen.prototype': ['screen'],
      'Notification': ['Notification'],
      'Navigator.prototype': ['navigator']
    }[name])
  )],
  [/^window\.(.*)$/, globalVar],
  [/^(WebGL2?RenderingContext|CanvasRenderingContext2D)\.prototype\.(.*)$/, renderingContextProperty],
  [/^(DeviceOrientation|DeviceMotion|RTCPeerConnectionIce)Event\.prototype\.(.*)$/, eventProperty],
  [/^MediaDevices\.prototype\.(.*)$/, globalObjectProperty(1, () => ['navigator', 'mediaDevices'])],
  [/^Sensor.prototype\.(.*)$/, sensorProperty],
  [/^(HTMLCanvasElement|AudioBuffer)\.prototype\.(toDataURL|getChannelData)/, domMethod],
];

async function generateTypes() {
  const weights = await fetchWeights();
  const matches = new Map();
  Object.entries(weights).filter(([identifier, weight]) => {
    for (const [matcher, queryGen] of API_MATCHERS) {
      const match = matcher.exec(identifier);
      if (match) {
        if (!matches.has(matcher)) {
          matches.set(matcher, [queryGen, []]);
        }
        matches.get(matcher)[1].push([weight, ...match.slice(1)]);
        delete weights[identifier];
        break;
      }
    }
  });
  if (Object.keys(weights).length > 0) {
    console.warn(`The following APIs are weighed more than ${MIN_WEIGHT}, but no types were generated for them:`, JSON.stringify(weights, null, 2));
  }
  return Object.fromEntries(
    Array.from(matches.values())
      .map(([queryGen, matches]) => queryGen(matches))
  );
}

async function clearFiles() {
  for (const file of await fs.readdir(QUERY_DIR)) {
    if (file.startsWith(TYPE_FILE_PREFIX)) {
      await fs.rm(path.join(QUERY_DIR, file));
    }
  }
}

async function generateTypeFiles() {
  for (const [name, query] of Object.entries(await generateTypes())) {
    await fs.writeFile(path.join(QUERY_DIR, `autogen_fp${name}.qll`), query);
  }
}

export async function updateQueries() {
  await clearFiles();
  await generateTypeFiles();
}