create-harness-vibe-coding 0.8.17 → 0.8.19

package/src/wf-ui-server/session-registry.mjs

@@ -0,0 +1,204 @@
+import crypto from 'node:crypto';
+import { RUNTIME_IDS } from './runtime-detector.mjs';
+
+/**
+ * Set of allowed agent runtimes for PTY sessions.
+ * No fake agents in product code.
+ */
+export const ALLOWED_RUNTIMES = RUNTIME_IDS;
+
+/**
+ * Generate a short peer ID from a runtime name.
+ * @param {string} runtime
+ * @returns {string}
+ */
+function generatePeerId(runtime) {
+  const suffix = crypto.randomBytes(4).toString('hex');
+  return `${runtime}-${suffix}`;
+}
+
+/**
+ * Generate a session ID (UUID v4).
+ * @returns {string}
+ */
+export function generateSessionId() {
+  return crypto.randomUUID();
+}
+
+/**
+ * SessionRegistry manages PTY sessions for peer agents.
+ *
+ * Each session tracks: agent runtime, terminal dimensions, lifecycle status,
+ * process info, and optional WebSocket attach state.
+ */
+export class SessionRegistry {
+  constructor() {
+    /** @type {Map<string, object>} */
+    this._sessions = new Map();
+    /** @type {Map<string, Promise<void>>} */
+    this._locks = new Map();
+  }
+
+  async withLock(sessionId, fn) {
+    const key = String(sessionId || '__global__');
+    const previous = this._locks.get(key) || Promise.resolve();
+    let release;
+    const current = new Promise((resolve) => { release = resolve; });
+    const chain = previous.then(() => current, () => current);
+    this._locks.set(key, chain);
+
+    await previous.catch(() => {});
+    try {
+      return await fn();
+    } finally {
+      release();
+      if (this._locks.get(key) === chain) {
+        this._locks.delete(key);
+      }
+    }
+  }
+
+  /**
+   * Create a new session.
+   * @param {object} opts
+   * @param {string} opts.taskId
+   * @param {string} opts.runtime - Must be in ALLOWED_RUNTIMES
+   * @param {number} [opts.cols=120]
+   * @param {number} [opts.rows=32]
+   * @param {string} [opts.projectRoot]
+   * @returns {object} The created session object
+   * @throws {Error} If runtime is not in ALLOWED_RUNTIMES
+   */
+  create({
+    taskId = null,
+    runtime,
+    role = 'terminal-agent',
+    objective = '',
+    cols = 120,
+    rows = 32,
+    projectRoot = '',
+    subagentMode = 'wf-subagents',
+    workflowMode = null,
+    model = '',
+    provider = '',
+    ceoPrompt = '',
+  }) {
+    if (!ALLOWED_RUNTIMES.has(runtime)) {
+      throw new Error(`Invalid runtime '${runtime}'. Must be one of: ${[...ALLOWED_RUNTIMES].join(', ')}`);
+    }
+
+    const now = new Date().toISOString();
+    const sessionId = generateSessionId();
+    const peerId = generatePeerId(runtime);
+
+    const session = {
+      sessionId,
+      taskId: taskId || null,
+      peerId,
+      runtime,
+      role,
+      objective,
+      subagentMode,
+      workflowMode,
+      model,
+      provider,
+      ceoPrompt,
+      status: 'starting',
+      cols,
+      rows,
+      attachMode: false,
+      startedAt: now,
+      updatedAt: now,
+      lastActivityAt: now,
+      pid: null,
+      exitCode: null,
+      blockedReason: null,
+      blockedHint: null,
+      ptyProvider: null,
+      agentSessionId: null,
+      resumeCommand: null,
+      terminalSeq: 0,
+      transcriptRing: '',
+      wsClientCount: 0,
+    };
+
+    this._sessions.set(sessionId, session);
+    return session;
+  }
+
+  /**
+   * Get a session by ID.
+   * @param {string} sessionId
+   * @returns {object|undefined}
+   */
+  get(sessionId) {
+    return this._sessions.get(sessionId);
+  }
+
+  /**
+   * Get all sessions as an array.
+   * @returns {object[]}
+   */
+  getAll() {
+    return [...this._sessions.values()];
+  }
+
+  /**
+   * Get all sessions for a given task ID.
+   * @param {string} taskId
+   * @returns {object[]}
+   */
+  getAllForTask(taskId) {
+    return [...this._sessions.values()].filter(s => s.taskId === taskId);
+  }
+
+  /**
+   * Update session fields. Merges the patch into the session and sets updatedAt.
+   * @param {string} sessionId
+   * @param {object} patch - Fields to merge (status, cols, rows, pid, exitCode, attachMode, wsClientCount, transcriptRing)
+   */
+  update(sessionId, patch) {
+    const session = this._sessions.get(sessionId);
+    if (!session) return;
+
+    for (const [key, value] of Object.entries(patch)) {
+      if (value !== undefined && key in session) {
+        session[key] = value;
+      }
+    }
+    session.updatedAt = new Date().toISOString();
+  }
+
+  /**
+   * Remove a session from the registry.
+   * @param {string} sessionId
+   */
+  remove(sessionId) {
+    this._sessions.delete(sessionId);
+  }
+
+  /**
+   * Stop and remove a web-owned session. Persisted recovery metadata lives on disk.
+   * @param {string} sessionId
+   * @returns {object|null} The removed session when found
+   */
+  stop(sessionId) {
+    const session = this._sessions.get(sessionId);
+    if (!session) return null;
+    this._sessions.delete(sessionId);
+    return {
+      ...session,
+      status: 'saved',
+      stoppedAt: new Date().toISOString(),
+      updatedAt: new Date().toISOString(),
+    };
+  }
+
+  /**
+   * Number of active sessions.
+   * @returns {number}
+   */
+  count() {
+    return this._sessions.size;
+  }
+}

package/src/wf-ui-server/settings.mjs

@@ -0,0 +1,100 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { RUNTIME_DEFINITIONS } from './runtime-detector.mjs';
+
+/**
+ * Default settings for the wf-ui server.
+ * These are the baseline values overridden by project settings.
+ */
+export const DEFAULT_SETTINGS = {
+  server: { host: '127.0.0.1', port: 0 },
+  terminal: { enabled: false, attachMode: false, defaultRuntime: 'codex' },
+  peers: { allowlist: RUNTIME_DEFINITIONS.map((runtime) => runtime.id) },
+  ui: { theme: 'auto', language: 'en', reducedMotion: false },
+};
+
+/**
+ * Deep-merge two plain objects. Only known keys from the defaults
+ * structure are accepted; unknown keys in the override are silently ignored.
+ *
+ * @param {object} defaults - Default settings object
+ * @param {object} override - Project override settings object
+ * @returns {object} Merged result
+ */
+function deepMerge(defaults, override) {
+  const result = { ...defaults };
+
+  for (const key of Object.keys(override)) {
+    if (!Object.hasOwn(defaults, key)) {
+      // Silently ignore unknown keys
+      continue;
+    }
+
+    const defVal = defaults[key];
+    const ovrVal = override[key];
+
+    if (defVal !== null && typeof defVal === 'object' && !Array.isArray(defVal) &&
+        ovrVal !== null && typeof ovrVal === 'object' && !Array.isArray(ovrVal)) {
+      result[key] = deepMerge(defVal, ovrVal);
+    } else {
+      result[key] = ovrVal;
+    }
+  }
+
+  return result;
+}
+
+/**
+ * Read project settings from Harness/settings.json relative to projectRoot.
+ * Merges project settings over defaults. Non-existent settings.json produces
+ * defaults. Unknown keys in project settings are silently ignored.
+ *
+ * @param {string} projectRoot - Absolute path to the project root directory
+ * @returns {object} Merged settings object
+ */
+export function loadSettings(projectRoot) {
+  if (!projectRoot) {
+    return JSON.parse(JSON.stringify(DEFAULT_SETTINGS));
+  }
+
+  const settingsPath = path.join(projectRoot, 'Harness', 'settings.json');
+
+  if (!fs.existsSync(settingsPath)) {
+    return JSON.parse(JSON.stringify(DEFAULT_SETTINGS));
+  }
+
+  let raw;
+  try {
+    raw = fs.readFileSync(settingsPath, 'utf8');
+  } catch {
+    return JSON.parse(JSON.stringify(DEFAULT_SETTINGS));
+  }
+
+  let projectSettings;
+  try {
+    projectSettings = JSON.parse(raw);
+  } catch {
+    return JSON.parse(JSON.stringify(DEFAULT_SETTINGS));
+  }
+
+  return deepMerge(DEFAULT_SETTINGS, projectSettings);
+}
+
+/**
+ * Resolve settings with explicit precedence.
+ * The precedence object may specify a projectRoot; project settings
+ * override defaults.
+ *
+ * @param {object} precedence - Precedence configuration
+ * @param {string} [precedence.projectRoot] - Project root for settings lookup
+ * @returns {object} Merged settings object
+ */
+export function resolveSettings(precedence = {}) {
+  const projectRoot = precedence.projectRoot;
+
+  if (projectRoot) {
+    return loadSettings(projectRoot);
+  }
+
+  return JSON.parse(JSON.stringify(DEFAULT_SETTINGS));
+}

package/src/wf-ui-server/task-parser.mjs

@@ -0,0 +1,133 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+function readState(taskDir) {
+  const statePath = path.join(taskDir, 'STATE.json');
+  if (!fs.existsSync(statePath)) return null;
+  try { return JSON.parse(fs.readFileSync(statePath, 'utf8')); }
+  catch (err) { throw new Error(`STATE.json at ${statePath} contains malformed JSON: ${err.message}`); }
+}
+
+function normalizeAcceptance(acceptance) {
+  if (!Array.isArray(acceptance)) return [];
+  return acceptance.map((ac) => {
+    if (typeof ac === 'string') return { id: '', text: ac, status: 'pending' };
+    if (ac && typeof ac === 'object') return {
+      id: ac.id || '',
+      text: ac.text || JSON.stringify(ac),
+      status: ac.status || 'pending',
+    };
+    return { id: '', text: String(ac), status: 'pending' };
+  });
+}
+
+export function parseTaskCapsule(taskDir) {
+  const state = readState(taskDir);
+  if (!state) return null;
+  if (state.schemaVersion === undefined || state.schemaVersion === null) {
+    throw new Error(`STATE.json at ${taskDir} is missing required field: schemaVersion`);
+  }
+  const links = state.links || { dependsOn: [], blocks: [], related: [] };
+  return {
+    taskId: state.taskId || path.basename(taskDir),
+    status: state.status || 'unknown',
+    phase: state.phase || null,
+    gate: state.gate || null,
+    tier: state.tier || null,
+    mode: state.mode || null,
+    updatedAt: state.updatedAt || null,
+    activeQuestion: state.activeQuestion || null,
+    nextAction: state.nextAction || null,
+    defaultRuntime: state.defaultRuntime || state.defaultAgentRuntime || state.agentRuntime || state.cliAgent || null,
+    acceptance: normalizeAcceptance(state.acceptance),
+    dependsOn: Array.isArray(links.dependsOn) ? links.dependsOn : [],
+    blocks: Array.isArray(links.blocks) ? links.blocks : [],
+    hasPlan: fs.existsSync(path.join(taskDir, 'PLAN.md')),
+    hasProgress: fs.existsSync(path.join(taskDir, 'PROGRESS.md')),
+  };
+}
+
+export function parseTaskList(tasksRoot) {
+  let entries;
+  try { entries = fs.readdirSync(tasksRoot, { withFileTypes: true }); }
+  catch { return []; }
+  const capsules = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory() || entry.name.startsWith('_')) continue;
+    try {
+      const c = parseTaskCapsule(path.join(tasksRoot, entry.name));
+      if (c) capsules.push(c);
+    } catch { /* skip unparseable */ }
+  }
+  capsules.sort((a, b) => {
+    const da = a.updatedAt ? new Date(a.updatedAt).getTime() : 0;
+    const db = b.updatedAt ? new Date(b.updatedAt).getTime() : 0;
+    return db - da;
+  });
+  return capsules;
+}
+
+/** Parse archived tasks from _archive/YYYY/task-name/ */
+export function parseArchivedTasks(tasksRoot) {
+  const archiveRoot = path.join(tasksRoot, '_archive');
+  if (!fs.existsSync(archiveRoot)) return [];
+  const capsules = [];
+  let years;
+  try { years = fs.readdirSync(archiveRoot, { withFileTypes: true }); }
+  catch { return []; }
+
+  function addArchivedTask(taskDir, archivedYear, archivedPath) {
+    try {
+      const c = parseTaskCapsule(taskDir);
+      if (c) {
+        c.archivedYear = archivedYear;
+        c.archivedPath = archivedPath;
+        capsules.push(c);
+      }
+    } catch { /* skip */ }
+  }
+
+  for (const y of years) {
+    if (!y.isDirectory()) continue;
+    const yearDir = path.join(archiveRoot, y.name);
+    let yearEntries;
+    try { yearEntries = fs.readdirSync(yearDir, { withFileTypes: true }); }
+    catch { continue; }
+    const monthDirs = yearEntries.filter(e => e.isDirectory() && /^\d{2}$/.test(e.name));
+    for (const month of monthDirs) {
+      const monthDir = path.join(yearDir, month.name);
+      let dayEntries;
+      try { dayEntries = fs.readdirSync(monthDir, { withFileTypes: true }); }
+      catch { continue; }
+      for (const day of dayEntries.filter(e => e.isDirectory() && /^\d{2}$/.test(e.name))) {
+        const dayDir = path.join(monthDir, day.name);
+        let taskEntries;
+        try { taskEntries = fs.readdirSync(dayDir, { withFileTypes: true }); }
+        catch { continue; }
+        for (const t of taskEntries.filter(e => e.isDirectory())) {
+          addArchivedTask(path.join(dayDir, t.name), y.name, `${y.name}/${month.name}/${day.name}`);
+        }
+      }
+    }
+
+    for (const t of yearEntries.filter(e => e.isDirectory() && !/^\d{2}$/.test(e.name))) {
+      addArchivedTask(path.join(yearDir, t.name), y.name, y.name);
+    }
+  }
+  capsules.sort((a, b) => {
+    const da = a.updatedAt ? new Date(a.updatedAt).getTime() : 0;
+    const db = b.updatedAt ? new Date(b.updatedAt).getTime() : 0;
+    return db - da;
+  });
+  return capsules;
+}
+
+/** Read a task file content (STATE.json, PLAN.md, PROGRESS.md) */
+export function readTaskFile(taskDir, filename) {
+  const safe = path.basename(filename);
+  const filePath = path.join(taskDir, safe);
+  if (!fs.existsSync(filePath)) return null;
+  try {
+    return { filename: safe, content: fs.readFileSync(filePath, 'utf8') };
+  } catch { return null; }
+}

package/src/wf-ui-server/terminal-store.mjs

@@ -0,0 +1,225 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { validateTaskId } from './security.mjs';
+
+const MAX_READ_LIMIT = 2000;
+
+function validateSessionId(sessionId) {
+  return validateTaskId(sessionId);
+}
+
+function isBoundTaskId(taskId) {
+  return Boolean(taskId && validateTaskId(taskId));
+}
+
+function sessionsRoot(projectRoot, taskId) {
+  if (isBoundTaskId(taskId)) {
+    return path.join(projectRoot, 'Harness', 'tasks', taskId, 'sessions');
+  }
+  return path.join(projectRoot, 'Harness', 'a2a', 'sessions');
+}
+
+function sessionDir(projectRoot, taskId, sessionId) {
+  if (taskId && !validateTaskId(taskId)) throw new Error(`Invalid taskId: ${taskId}`);
+  if (!validateSessionId(sessionId)) throw new Error(`Invalid sessionId: ${sessionId}`);
+  return path.join(sessionsRoot(projectRoot, taskId), sessionId);
+}
+
+function readJson(filePath, fallback) {
+  try {
+    if (!fs.existsSync(filePath)) return fallback;
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch {
+    return fallback;
+  }
+}
+
+function writeJson(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.writeFileSync(filePath, `${JSON.stringify(data, null, 2)}\n`, 'utf8');
+}
+
+function readJsonl(filePath) {
+  try {
+    if (!fs.existsSync(filePath)) return [];
+    return fs.readFileSync(filePath, 'utf8')
+      .split(/\r?\n/)
+      .filter(Boolean)
+      .map((line) => JSON.parse(line));
+  } catch {
+    return [];
+  }
+}
+
+function appendJsonl(filePath, data) {
+  fs.mkdirSync(path.dirname(filePath), { recursive: true });
+  fs.appendFileSync(filePath, `${JSON.stringify(data)}\n`, 'utf8');
+}
+
+export function persistSession(projectRoot, session, patch = {}) {
+  const dir = sessionDir(projectRoot, session.taskId, session.sessionId);
+  const current = readJson(path.join(dir, 'STATE.json'), {});
+  const state = {
+    ...current,
+    ...session,
+    ...patch,
+    updatedAt: new Date().toISOString(),
+  };
+  writeJson(path.join(dir, 'STATE.json'), state);
+  return state;
+}
+
+export function appendSessionEvent(projectRoot, session, event) {
+  const dir = sessionDir(projectRoot, session.taskId, session.sessionId);
+  appendJsonl(path.join(dir, 'events.jsonl'), {
+    ts: new Date().toISOString(),
+    taskId: session.taskId || null,
+    sessionId: session.sessionId,
+    runtime: session.runtime,
+    ...event,
+  });
+}
+
+export function appendTerminalData(projectRoot, session, data, stream = 'stdout') {
+  const dir = sessionDir(projectRoot, session.taskId, session.sessionId);
+  const statePath = path.join(dir, 'STATE.json');
+  const state = readJson(statePath, session);
+  const nextSeq = Number(state.terminalSeq || 0) + 1;
+  const entry = {
+    seq: nextSeq,
+    ts: new Date().toISOString(),
+    taskId: session.taskId || null,
+    sessionId: session.sessionId,
+    runtime: session.runtime,
+    stream,
+    data: String(data || ''),
+  };
+  appendJsonl(path.join(dir, 'terminal.jsonl'), entry);
+  writeJson(statePath, {
+    ...state,
+    terminalSeq: nextSeq,
+    lastActivityAt: entry.ts,
+    updatedAt: entry.ts,
+  });
+  return entry;
+}
+
+function allSessionDirs(projectRoot) {
+  const tasksRoot = path.join(projectRoot, 'Harness', 'tasks');
+  let taskEntries = [];
+  try {
+    taskEntries = fs.readdirSync(tasksRoot, { withFileTypes: true });
+  } catch {
+    taskEntries = [];
+  }
+  const dirs = [];
+  for (const taskEntry of taskEntries) {
+    if (!taskEntry.isDirectory() || taskEntry.name.startsWith('_')) continue;
+    const root = path.join(tasksRoot, taskEntry.name, 'sessions');
+    let sessionEntries = [];
+    try {
+      sessionEntries = fs.readdirSync(root, { withFileTypes: true });
+    } catch {
+      continue;
+    }
+    for (const sessionEntry of sessionEntries) {
+      if (sessionEntry.isDirectory()) {
+        dirs.push({
+          taskId: taskEntry.name,
+          sessionId: sessionEntry.name,
+          dir: path.join(root, sessionEntry.name),
+          relRoot: `Harness/tasks/${taskEntry.name}/sessions/${sessionEntry.name}`,
+        });
+      }
+    }
+  }
+
+  const a2aSessionsRoot = path.join(projectRoot, 'Harness', 'a2a', 'sessions');
+  try {
+    for (const sessionEntry of fs.readdirSync(a2aSessionsRoot, { withFileTypes: true })) {
+      if (sessionEntry.isDirectory()) {
+        dirs.push({
+          taskId: null,
+          sessionId: sessionEntry.name,
+          dir: path.join(a2aSessionsRoot, sessionEntry.name),
+          relRoot: `Harness/a2a/sessions/${sessionEntry.name}`,
+        });
+      }
+    }
+  } catch {
+    // No unbound A2A sessions yet.
+  }
+  return dirs;
+}
+
+export function listTerminalSessions(projectRoot) {
+  return allSessionDirs(projectRoot)
+    .map(({ dir }) => readJson(path.join(dir, 'STATE.json'), null))
+    .filter(Boolean)
+    .sort((a, b) => String(b.updatedAt || '').localeCompare(String(a.updatedAt || '')));
+}
+
+export function findTerminalSession(projectRoot, sessionId) {
+  if (!validateSessionId(sessionId)) return null;
+  return allSessionDirs(projectRoot).find((entry) => entry.sessionId === sessionId) || null;
+}
+
+export function readTerminalRange(projectRoot, { sessionId, fromSeq, toSeq, tail } = {}) {
+  const found = findTerminalSession(projectRoot, sessionId);
+  if (!found) return { sessionId, entries: [] };
+  let entries = readJsonl(path.join(found.dir, 'terminal.jsonl'));
+  if (Number.isFinite(fromSeq)) entries = entries.filter((entry) => entry.seq >= fromSeq);
+  if (Number.isFinite(toSeq)) entries = entries.filter((entry) => entry.seq <= toSeq);
+  if (Number.isFinite(tail) && tail > 0) entries = entries.slice(-Math.min(tail, MAX_READ_LIMIT));
+  else entries = entries.slice(0, MAX_READ_LIMIT);
+  return { sessionId, taskId: found.taskId, entries };
+}
+
+function globToRegex(pattern) {
+  const safe = String(pattern || '**/*')
+    .replace(/[.+^${}()|[\]\\]/g, '\\$&')
+    .replace(/\*\*/g, '::DOUBLE_STAR::')
+    .replace(/\*/g, '[^/]*')
+    .replace(/::DOUBLE_STAR::/g, '.*');
+  return new RegExp(`^${safe}$`);
+}
+
+export function globTerminalEvents(projectRoot, { pattern = '**/*', since, limit = 200 } = {}) {
+  const regex = globToRegex(pattern.replace(/\\/g, '/'));
+  const max = Math.min(Math.max(Number(limit) || 200, 1), MAX_READ_LIMIT);
+  const sinceMs = since ? new Date(since).getTime() : null;
+  const events = [];
+  for (const found of allSessionDirs(projectRoot)) {
+    for (const filename of ['events.jsonl', 'terminal.jsonl', 'input-requests.jsonl']) {
+      const rel = `${found.relRoot}/${filename}`;
+      if (!regex.test(rel)) continue;
+      const rows = readJsonl(path.join(found.dir, filename));
+      for (const row of rows) {
+        const tsMs = row.ts ? new Date(row.ts).getTime() : 0;
+        if (sinceMs && tsMs < sinceMs) continue;
+        events.push({ source: rel, ...row });
+      }
+    }
+  }
+  return events
+    .sort((a, b) => String(a.ts || '').localeCompare(String(b.ts || '')))
+    .slice(-max);
+}
+
+export function recordInputRequest(projectRoot, sessionId, text) {
+  const found = findTerminalSession(projectRoot, sessionId);
+  if (!found) throw new Error(`Session not found: ${sessionId}`);
+  const state = readJson(path.join(found.dir, 'STATE.json'), null);
+  if (!state?.attachMode) {
+    throw new Error('Input rejected: session is in watch mode. Enable attach mode first.');
+  }
+  const event = {
+    ts: new Date().toISOString(),
+    type: 'terminal.input.requested',
+    taskId: found.taskId || null,
+    sessionId,
+    data: String(text || ''),
+  };
+  appendJsonl(path.join(found.dir, 'input-requests.jsonl'), event);
+  return event;
+}

package/src/wf-ui-server/token.mjs

@@ -0,0 +1,41 @@
+import crypto from 'node:crypto';
+
+/**
+ * Generate a cryptographically random token as a hex string.
+ * @returns {string} Hex string of at least 32 characters (128 bits).
+ */
+export function generateToken() {
+  return crypto.randomBytes(32).toString('hex');
+}
+
+/**
+ * Timing-safe comparison of two tokens using `crypto.timingSafeEqual`.
+ *
+ * Both arguments are coerced to strings. If lengths differ, or either value
+ * is null/undefined, returns false without leaking the length mismatch
+ * source in the return path (the comparison still runs via a synthetic buffer).
+ *
+ * @param {string} token - The token to validate.
+ * @param {string} expectedToken - The expected token to compare against.
+ * @returns {boolean} True if both tokens are equal; false otherwise.
+ */
+export function validateToken(token, expectedToken) {
+  if (typeof token !== 'string' || typeof expectedToken !== 'string') {
+    return false;
+  }
+
+  // Use timingSafeEqual even on different-length inputs to avoid leaking
+  // length information through the return path. We compare the provided
+  // token against itself when lengths don't match, so the crypto call
+  // always takes the same form.
+  const bufToken = Buffer.from(token, 'utf8');
+  const bufExpected = Buffer.from(expectedToken, 'utf8');
+
+  if (bufToken.length !== bufExpected.length) {
+    // Dummy comparison to maintain timing invariants (no data leak)
+    crypto.timingSafeEqual(bufToken, bufToken);
+    return false;
+  }
+
+  return crypto.timingSafeEqual(bufToken, bufExpected);
+}