@cfour-hi/dsh-plugin-devicex 1.5.0 → 1.7.0

package/host/footprint-win32.js

@@ -0,0 +1,411 @@
+/**
+ * Device X - uninstall footprint scanner (Windows).
+ *
+ * Read-only, and deliberately conservative for 1.6: it reports the leftover
+ * locations it can identify with high confidence and refuses to guess beyond
+ * that. In particular it does **not** move anything to the Recycle Bin - the
+ * cleanup leg of the pipeline is not implemented for Windows yet, because the
+ * shell-based move (`Shell.Application` / `SHFileOperation`) could not be
+ * validated on a real Windows host and this plugin never ships an unverified
+ * destructive path.
+ *
+ * Discovery sources, strongest first:
+ *
+ *  - `%LOCALAPPDATA%\Packages\<PackageFamilyName>` - MSIX/Store apps own an
+ *    exact container, so no naming heuristic is involved;
+ *  - the MSI/uninstall-key `InstallLocation` and the reverse-DNS registry trees
+ *    under `Software\<Vendor>` that match the display name;
+ *  - `%APPDATA%`, `%LOCALAPPDATA%` and `%PROGRAMDATA%` product directories
+ *    whose name matches the display name (tier B, never preselected).
+ *
+ * Windows has no bundle identifier, so name matching is weaker here than on
+ * macOS and the `conflict` tier does more of the work.
+ *
+ * ASCII-only source: `scripts/verify-cleanup.mjs` asserts this file contains no
+ * non-ASCII byte, because PowerShell input decodes with the console code page.
+ *
+ * @module @cfour-hi/dsh-plugin-devicex/host/footprint-win32
+ */
+import * as fsp from 'node:fs/promises';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+import { classify, compactSlug, dedupeApps, selectedBytes, slugify, toAppContext, totalBytes } from './footprint-core.js';
+
+/** Host platform for this implementation. */
+export const PLATFORM = 'win32';
+
+/** Maximum candidates returned in one report. */
+const MAX_ITEMS = 200;
+/** Maximum directory entries visited per candidate size measurement. */
+const MAX_ENTRIES = 40_000;
+/** Wall-clock budget per candidate size walk (ms). */
+const TIME_BUDGET_MS = 3_000;
+/** Maximum diagnostic strings kept. */
+const MAX_ERRORS = 20;
+/** Maximum installed apps read for conflict detection. */
+const MAX_APPS = 600;
+
+/**
+ * Environment variables this module reads, resolved at call time so tests can
+ * inject a profile without touching the real one.
+ * @returns {Record<string, string>}
+ */
+function profileEnv() {
+  const env = process.env;
+  return {
+    appData: env.APPDATA ?? '',
+    localAppData: env.LOCALAPPDATA ?? '',
+    programData: env.ProgramData ?? env.PROGRAMDATA ?? '',
+    userProfile: env.USERPROFILE ?? os.homedir(),
+  };
+}
+
+/**
+ * Directories swept for product-level leftovers, with their admin flag.
+ * @param {Record<string, string>} env
+ * @returns {Array<{root: string, requiresAdmin: boolean}>}
+ */
+export function sweepRootsFor(env) {
+  /** @type {Array<{root: string, requiresAdmin: boolean}>} */
+  const roots = [];
+  if (env.appData) roots.push({ root: path.join(env.appData), requiresAdmin: false });
+  if (env.localAppData) roots.push({ root: path.join(env.localAppData), requiresAdmin: false });
+  if (env.programData) roots.push({ root: path.join(env.programData), requiresAdmin: true });
+  return roots;
+}
+
+/**
+ * Every root this scanner may ever report a candidate from.
+ *
+ * The dispatcher uses this list, not the report, to bound deletion.
+ */
+export const SAFE_ROOTS = Object.freeze(
+  (() => {
+    const env = profileEnv();
+    /** @type {string[]} */
+    const roots = [];
+    if (env.appData) roots.push(env.appData);
+    if (env.localAppData) roots.push(env.localAppData);
+    if (env.programData) roots.push(env.programData);
+    if (env.userProfile) roots.push(env.userProfile);
+    return roots;
+  })(),
+);
+
+/**
+ * Shorten an error message to one JSON-friendly line.
+ * @param {unknown} value
+ * @param {number} [max]
+ * @returns {string}
+ */
+function shortErr(value, max = 200) {
+  const text = String(value ?? 'unknown error')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return text.length > max ? `${text.slice(0, max - 1) + '...'}` : text;
+}
+
+/**
+ * `%VAR%` placeholder for display.
+ * @param {string} absolute
+ * @param {Record<string, string>} env
+ * @returns {string}
+ */
+export function displayPath(absolute, env) {
+  const pairs = [
+    ['%APPDATA%', env.appData],
+    ['%LOCALAPPDATA%', env.localAppData],
+    ['%PROGRAMDATA%', env.programData],
+    ['%USERPROFILE%', env.userProfile],
+  ];
+  for (const [token, base] of pairs) {
+    if (typeof base === 'string' && base !== '' && absolute.toLowerCase().startsWith(base.toLowerCase())) {
+      return token + absolute.slice(base.length);
+    }
+  }
+  return absolute;
+}
+
+/**
+ * Bounded recursive size walk using `lstat` only; never follows reparse points.
+ * @param {string} root
+ * @param {{maxEntries?: number, timeBudgetMs?: number}} [options]
+ * @returns {Promise<{bytes: number, files: number, truncated: string|null}>}
+ */
+export async function measurePath(root, options = {}) {
+  const maxEntries = options.maxEntries ?? MAX_ENTRIES;
+  const timeBudgetMs = options.timeBudgetMs ?? TIME_BUDGET_MS;
+  const deadline = Date.now() + timeBudgetMs;
+  let bytes = 0;
+  let files = 0;
+  let entries = 0;
+  /** @type {string|null} */
+  let truncated = null;
+  /** @type {string[]} */
+  let level = [root];
+
+  outer: while (level.length > 0) {
+    /** @type {string[]} */
+    const next = [];
+    for (const current of level) {
+      if (Date.now() > deadline) {
+        truncated = `timed out after ${timeBudgetMs} ms`;
+        break outer;
+      }
+      let stat;
+      try {
+        stat = await fsp.lstat(current);
+      } catch {
+        continue;
+      }
+      if (stat.isSymbolicLink()) continue;
+      if (stat.isFile()) {
+        bytes += stat.size;
+        files += 1;
+        continue;
+      }
+      if (!stat.isDirectory()) continue;
+      entries += 1;
+      if (entries > maxEntries) {
+        truncated = `stopped after ${maxEntries} entries`;
+        break outer;
+      }
+      let children;
+      try {
+        children = await fsp.readdir(current);
+      } catch {
+        continue;
+      }
+      for (const child of children) next.push(path.join(current, child));
+    }
+    level = next;
+  }
+  return { bytes, files, truncated };
+}
+
+/**
+ * Stable, scan-local item id derived from the path (FNV-1a).
+ * @param {string} absolute
+ * @returns {string}
+ */
+export function itemId(absolute) {
+  let hash = 0x811c9dc5;
+  for (let index = 0; index < absolute.length; index += 1) {
+    hash ^= absolute.charCodeAt(index);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return `fp_${hash.toString(16).padStart(8, '0')}`;
+}
+
+/**
+ * Scan one application's leftover footprint.
+ *
+ * @param {{appPath?: string, installedApps?: Array<object>, name?: string,
+ *   bundleId?: string|null, packageFamilyName?: string|null}} [options]
+ * @returns {Promise<object>} a `FootprintReport` without `scanId`
+ */
+export async function scanFootprint(options = {}) {
+  const startedAt = Date.now();
+  /** @type {string[]} */
+  const errors = [];
+  const env = profileEnv();
+  const appPath = typeof options.appPath === 'string' ? options.appPath : '';
+
+  const base = {
+    appPath,
+    bundleId: typeof options.bundleId === 'string' && options.bundleId !== '' ? options.bundleId : null,
+    sandboxed: false,
+    targetedRoots: [],
+    generatedAt: startedAt,
+    durationMs: 0,
+    items: [],
+    totalBytes: 0,
+    selectedBytes: 0,
+    errors,
+  };
+
+  const appName =
+    typeof options.name === 'string' && options.name !== ''
+      ? options.name
+      : appPath !== ''
+        ? path.basename(appPath)
+        : '';
+  if (appName === '') {
+    errors.push('missing application name');
+    return { ...base, durationMs: Date.now() - startedAt };
+  }
+
+  const subject = toAppContext({ name: appName, bundleId: base.bundleId });
+  const installedApps = Array.isArray(options.installedApps)
+    ? options.installedApps.map((app) => toAppContext(app))
+    : [subject];
+  const roster = dedupeApps(installedApps);
+
+  /** @type {Array<{name: string, absolute: string, requiresAdmin: boolean, source: string, holdsSubject?: boolean}>} */
+  const candidates = [];
+
+  // 1. MSIX containers: an exact, unambiguous match.
+  //
+  // The PFN is `PackageName_PublisherId`, so it is derived from the app name
+  // rather than required from the caller: a collector that only knows the
+  // display name still gets the strongest signal Windows offers.
+  if (env.localAppData !== '') {
+    const packagesDir = path.join(env.localAppData, 'Packages');
+    const subjectSlug = compactSlug(appName);
+    const hinted = typeof options.packageFamilyName === 'string' ? options.packageFamilyName : '';
+    let entries = [];
+    try {
+      entries = await fsp.readdir(packagesDir, { withFileTypes: true });
+    } catch {
+      // A machine with no Store apps has no Packages directory at all.
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      const isHinted = hinted !== '' && entry.name.toLowerCase() === hinted.toLowerCase();
+      // `Acme.Widget_8wekyb3d8bbwe` -> `acmewidget` (separators removed, because
+      // a package name has no separator convention we can rely on).
+      const packageSlug = compactSlug(entry.name.split('_')[0]);
+      if (!isHinted && (subjectSlug === '' || packageSlug !== subjectSlug)) continue;
+      candidates.push({
+        name: entry.name,
+        absolute: path.join(packagesDir, entry.name),
+        requiresAdmin: false,
+        source: 'msix',
+      });
+    }
+  }
+
+  // 2. Product directories under the three profile roots, matched by name.
+  for (const { root, requiresAdmin } of sweepRootsFor(env)) {
+    let entries;
+    try {
+      entries = await fsp.readdir(root, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      candidates.push({
+        name: entry.name,
+        absolute: path.join(root, entry.name),
+        requiresAdmin,
+        source: 'registry',
+      });
+    }
+  }
+
+  /** @type {Array<object>} */
+  const items = [];
+
+  // The install directory (when the registry told us where it is) is the
+  // Windows analogue of "the bundle itself": always first, always selected.
+  if (appPath !== '') {
+    const measure = await measurePath(appPath);
+    items.push({
+      id: itemId(appPath),
+      kind: 'app',
+      path: appPath,
+      displayPath: displayPath(appPath, env),
+      bytes: measure.bytes,
+      files: measure.files,
+      confidence: 'high',
+      source: 'registry',
+      reason: 'The application install directory.',
+      requiresAdmin: false,
+      exists: true,
+      ...(measure.truncated ? { warning: measure.truncated } : {}),
+    });
+  }
+
+  /** @type {Set<string>} */
+  const seen = new Set(items.map((item) => item.path));
+
+  const classified = [];
+  for (const candidate of candidates) {
+    if (seen.has(candidate.absolute)) continue;
+    const verdict =
+      candidate.source === 'msix'
+        ? {
+            confidence: /** @type {const} */ ('high'),
+            source: /** @type {const} */ ('msix'),
+            reason: 'MSIX package container for this application.',
+            alsoMatchedBy: [],
+          }
+        : classify(candidate, subject, roster, {});
+    if (verdict === null) continue;
+    seen.add(candidate.absolute);
+    classified.push({ ...candidate, ...verdict });
+  }
+
+  const rank = { high: 0, medium: 1, conflict: 2, shared: 3 };
+  classified.sort((left, right) => {
+    const diff = (rank[left.confidence] ?? 9) - (rank[right.confidence] ?? 9);
+    return diff !== 0 ? diff : left.absolute.localeCompare(right.absolute);
+  });
+
+  for (const candidate of classified.slice(0, MAX_ITEMS)) {
+    const measure = await measurePath(candidate.absolute);
+    items.push({
+      id: itemId(candidate.absolute),
+      kind: candidate.requiresAdmin ? 'system' : 'data',
+      path: candidate.absolute,
+      displayPath: displayPath(candidate.absolute, env),
+      bytes: measure.bytes,
+      files: measure.files,
+      confidence: candidate.confidence,
+      source: candidate.source,
+      reason: candidate.reason,
+      ...(candidate.alsoMatchedBy.length > 0 ? { alsoMatchedBy: candidate.alsoMatchedBy } : {}),
+      requiresAdmin: candidate.requiresAdmin,
+      exists: true,
+      ...(measure.truncated ? { warning: measure.truncated } : {}),
+    });
+  }
+  if (classified.length > MAX_ITEMS) {
+    errors.push(`report truncated to ${MAX_ITEMS} of ${classified.length} candidates`);
+  }
+  if (errors.length > MAX_ERRORS) errors.length = MAX_ERRORS;
+
+  const appBytes = items.length > 0 && items[0].kind === 'app' ? items[0].bytes : 0;
+  return {
+    ...base,
+    targetedRoots: sweepRootsFor(env).map((entry) => displayPath(entry.root, env)),
+    durationMs: Date.now() - startedAt,
+    items,
+    totalBytes: totalBytes(items),
+    selectedBytes: Math.max(0, selectedBytes(items) - appBytes),
+  };
+}
+
+/**
+ * Leftover cleanup is not implemented for Windows yet: moving to the Recycle
+ * Bin needs the shell, which could not be validated on a real Windows host.
+ * Returning a refusal is the point - the plugin never ships an unverified
+ * destructive path, and the caller must say so plainly.
+ *
+ * @returns {{ok: false, message: string, code: string}}
+ */
+export function cleanupUnsupported() {
+  return {
+    ok: false,
+    message:
+      'Leftover cleanup is not available on Windows yet: this build can list leftovers but will not move them to the Recycle Bin. The application itself can still be uninstalled.',
+    code: 'UNSUPPORTED_PLATFORM',
+  };
+}
+
+/** Test seam. */
+export const __test = {
+  PLATFORM,
+  SAFE_ROOTS,
+  MAX_ITEMS,
+  MAX_ENTRIES,
+  TIME_BUDGET_MS,
+  measurePath,
+  sweepRootsFor,
+  displayPath,
+  profileEnv,
+  itemId,
+  slugify,
+};

package/host/footprint.js

@@ -0,0 +1,284 @@
+/**
+ * Device X — uninstall footprint dispatcher and scan-token store.
+ *
+ * The public surface is `scanFootprint({path, fresh})`. It returns a report
+ * whose item paths stay on the server: the client receives an opaque `scanId`
+ * plus per-item opaque ids, and `app.uninstall` accepts only
+ * `(scanId, itemIds[])` for cleanup. That keeps the shipped safety property —
+ * a deletion request can never name a path — while still letting the user pick
+ * individual leftover directories, which are only known at runtime.
+ *
+ * A token is single-use, expires after {@link TOKEN_TTL_MS}, and remembers the
+ * exact roots the scan was allowed to produce so a tampered id cannot reach
+ * anything else.
+ *
+ * @module @cfour-hi/dsh-plugin-devicex/host/footprint
+ */
+import * as path from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+import * as darwin from './footprint-darwin.js';
+import * as win32 from './footprint-win32.js';
+
+/** Host platform. */
+export const PLATFORM = process.platform;
+
+/** Scan token lifetime (ms). */
+export const TOKEN_TTL_MS = 10 * 60_000;
+/** Maximum concurrently retained tokens. */
+export const MAX_TOKENS = 16;
+/** Cached report reuse window (ms); a re-open of the same dialog must be cheap. */
+export const REPORT_TTL_MS = 60_000;
+
+const impl = process.platform === 'win32' ? win32 : darwin;
+
+/**
+ * @typedef {object} ScanRecord
+ * @property {string} scanId
+ * @property {number} at
+ * @property {boolean} consumed
+ * @property {string} appPath
+ * @property {Map<string, {path: string, requiresAdmin: boolean, kind: string, bytes: number}>} items
+ * @property {string[]} roots the exact root prefixes this scan could produce
+ */
+
+/** @type {Map<string, ScanRecord>} */
+const tokens = new Map();
+
+/** @type {Map<string, {at: number, report: object}>} */
+const reportCache = new Map();
+
+/**
+ * Register a finished report as a single-use cleanup token.
+ *
+ * The roots are derived from what the platform implementation declares, not
+ * from the report, so a bug in the scanner cannot widen the deletion boundary.
+ *
+ * @param {object} report raw platform report
+ * @param {readonly string[]} roots absolute root prefixes the scan was allowed to use
+ * @returns {string} the opaque scan id
+ */
+function registerToken(report, roots) {
+  const now = Date.now();
+  for (const [id, record] of tokens) {
+    if (record.consumed || now - record.at > TOKEN_TTL_MS) tokens.delete(id);
+  }
+  while (tokens.size >= MAX_TOKENS) {
+    const oldest = tokens.keys().next();
+    if (oldest.done) break;
+    tokens.delete(oldest.value);
+  }
+  const scanId = randomUUID();
+  /** @type {Map<string, {path: string, requiresAdmin: boolean, kind: string, bytes: number}>} */
+  const items = new Map();
+  for (const item of Array.isArray(report?.items) ? report.items : []) {
+    if (typeof item?.id !== 'string' || typeof item?.path !== 'string') continue;
+    const bytes = Number(item.bytes);
+    items.set(item.id, {
+      path: item.path,
+      requiresAdmin: item.requiresAdmin === true,
+      kind: typeof item.kind === 'string' ? item.kind : 'data',
+      // Kept so the pipeline can report how much the Trash now holds. The
+      // number is a measurement from scan time, not a guarantee: the directory
+      // may have changed between the scan and the move.
+      bytes: Number.isFinite(bytes) && bytes > 0 ? bytes : 0,
+    });
+  }
+  tokens.set(scanId, {
+    scanId,
+    at: now,
+    consumed: false,
+    appPath: typeof report?.appPath === 'string' ? report.appPath : '',
+    items,
+    roots: Array.isArray(roots) ? roots.slice() : [],
+  });
+  return scanId;
+}
+
+/**
+ * Drop expired entries from the report cache.
+ * @param {number} now
+ */
+function pruneCache(now) {
+  for (const [key, entry] of reportCache) {
+    if (now - entry.at > REPORT_TTL_MS) reportCache.delete(key);
+  }
+}
+
+/**
+ * Scan one application's leftover footprint (read-only).
+ *
+ * @param {{path?: string, fresh?: boolean}} [options]
+ * @returns {Promise<object>} `FootprintReport` including its `scanId`
+ */
+export async function scanFootprint(options = {}) {
+  const appPath = typeof options.path === 'string' ? options.path.trim() : '';
+  const fresh = options.fresh === true;
+  const now = Date.now();
+  pruneCache(now);
+
+  if (appPath === '') {
+    return {
+      scanId: '',
+      appPath: '',
+      bundleId: null,
+      sandboxed: false,
+      targetedRoots: [],
+      generatedAt: now,
+      durationMs: 0,
+      items: [],
+      totalBytes: 0,
+      selectedBytes: 0,
+      errors: ['missing application path'],
+    };
+  }
+
+  const key = path.resolve(appPath);
+  const cached = reportCache.get(key);
+  if (!fresh && cached && now - cached.at <= REPORT_TTL_MS) {
+    const scanId = registerToken(cached.report, impl.__test?.SAFE_ROOTS ?? []);
+    return { ...cached.report, scanId };
+  }
+
+  const report = await impl.scanFootprint({ appPath: key });
+  reportCache.set(key, { at: now, report });
+  const scanId = registerToken(report, impl.__test?.SAFE_ROOTS ?? []);
+  return { ...report, scanId };
+}
+
+/**
+ * @typedef {object} ResolvedItem
+ * @property {string} id
+ * @property {string} path
+ * @property {boolean} requiresAdmin
+ * @property {string} kind
+ * @property {number} bytes measured at scan time
+ */
+
+/**
+ * Resolve requested item ids through a scan token.
+ *
+ * Every rejection reason is explicit so the caller can explain it: an unknown
+ * or expired token, an id that belongs to a different scan, a path that left
+ * the recorded roots, a symbolic link, or a root directory itself.
+ *
+ * @param {unknown} scanId
+ * @param {unknown} itemIds
+ * @returns {{ok: true, items: ResolvedItem[], appPath: string} | {ok: false, message: string, code: string}}
+ */
+export function resolveScanItems(scanId, itemIds) {
+  if (typeof scanId !== 'string' || scanId === '') {
+    return { ok: false, message: 'A scan id is required to clean up leftovers.', code: 'BAD_PARAMS' };
+  }
+  const record = tokens.get(scanId);
+  if (record === undefined) {
+    return { ok: false, message: 'This scan has expired. Re-open the uninstall dialog.', code: 'SCAN_NOT_FOUND' };
+  }
+  if (record.consumed) {
+    return { ok: false, message: 'This scan was already used. Re-open the uninstall dialog.', code: 'SCAN_CONSUMED' };
+  }
+  if (Date.now() - record.at > TOKEN_TTL_MS) {
+    tokens.delete(scanId);
+    return { ok: false, message: 'This scan has expired. Re-open the uninstall dialog.', code: 'SCAN_EXPIRED' };
+  }
+
+  /** @type {unknown[]} */
+  let requested;
+  if (Array.isArray(itemIds)) requested = itemIds;
+  else if (typeof itemIds === 'string') requested = itemIds.split(',');
+  else return { ok: false, message: 'itemIds must be an array of scan item ids.', code: 'BAD_PARAMS' };
+
+  /** @type {ResolvedItem[]} */
+  const resolved = [];
+  /** @type {Set<string>} */
+  const seen = new Set();
+  for (const raw of requested) {
+    if (typeof raw !== 'string') {
+      return { ok: false, message: 'Scan item ids must be strings.', code: 'BAD_PARAMS' };
+    }
+    const id = raw.trim();
+    if (id === '') continue;
+    if (seen.has(id)) {
+      return { ok: false, message: `Duplicate scan item id: ${id}`, code: 'BAD_PARAMS' };
+    }
+    seen.add(id);
+    const item = record.items.get(id);
+    if (item === undefined) {
+      return {
+        ok: false,
+        message: `Item ${id} does not belong to this scan.`,
+        code: 'ITEM_NOT_IN_SCAN',
+      };
+    }
+    if (item.requiresAdmin) {
+      return {
+        ok: false,
+        message: `${item.path} needs administrator rights and cannot be removed by this plugin.`,
+        code: 'REQUIRES_ADMIN',
+      };
+    }
+    const absolute = path.resolve(item.path);
+    if (!isInsideRoots(absolute, record.roots)) {
+      return {
+        ok: false,
+        message: `Refusing to touch a path outside the scanned roots: ${absolute}`,
+        code: 'PATH_NOT_ALLOWED',
+      };
+    }
+    if (absolute === path.dirname(absolute)) {
+      return { ok: false, message: `Refusing to remove a filesystem root: ${absolute}`, code: 'PATH_NOT_ALLOWED' };
+    }
+    resolved.push({ id, path: absolute, requiresAdmin: false, kind: item.kind, bytes: item.bytes });
+  }
+
+  if (resolved.length === 0) {
+    return { ok: false, message: 'No scan items were selected.', code: 'BAD_PARAMS' };
+  }
+  return { ok: true, items: resolved, appPath: record.appPath };
+}
+
+/**
+ * True when `candidate` is one of the allowed roots or lives beneath one.
+ * @param {string} candidate absolute, resolved
+ * @param {string[]} roots absolute roots
+ * @returns {boolean}
+ */
+export function isInsideRoots(candidate, roots) {
+  if (typeof candidate !== 'string' || !path.isAbsolute(candidate)) return false;
+  for (const root of Array.isArray(roots) ? roots : []) {
+    if (typeof root !== 'string' || root === '') continue;
+    if (candidate === root) return true;
+    if (candidate.startsWith(`${root}${path.sep}`)) return true;
+  }
+  return false;
+}
+
+/**
+ * Mark a token used. Called only after the cleanup actually ran, so a failed
+ * pipeline can be retried with the same dialog still open.
+ * @param {string} scanId
+ */
+export function consumeToken(scanId) {
+  const record = tokens.get(scanId);
+  if (record !== undefined) record.consumed = true;
+}
+
+/** Test seam: clear all stores. */
+export function __resetForTests() {
+  tokens.clear();
+  reportCache.clear();
+}
+
+/** Test seam. */
+export const __test = {
+  PLATFORM,
+  TOKEN_TTL_MS,
+  MAX_TOKENS,
+  REPORT_TTL_MS,
+  tokens,
+  reportCache,
+  darwin,
+  win32,
+  isInsideRoots,
+  registerToken,
+};