pi-oracle 0.7.4 → 0.7.6

package/extensions/oracle/lib/tools.ts

@@ -4,9 +4,13 @@
 // Usage: Imported by the oracle extension entrypoint and sanity tests to register tools against the pi API.
 // Invariants/Assumptions: The pi runtime validates TypeBox schemas before execute, while execute owns semantic normalization.
 import { randomUUID } from "node:crypto";
-import { lstat, mkdtemp, readdir, rename, rm, stat, writeFile } from "node:fs/promises";
+import { spawn } from "node:child_process";
+import { once } from "node:events";
+import { createReadStream } from "node:fs";
+import { lstat, mkdtemp, readdir, readlink, rename, rm, stat, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
-import { basename, join, posix } from "node:path";
+import { basename, dirname, join, posix } from "node:path";
+import { sweetCookieSafeStoragePasswordScrubbedEnv } from "../shared/browser-profile-helpers.mjs";
 import { runOracleAuthBootstrap } from "./auth.js";
 import type { ExtensionAPI, ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
@@ -125,6 +129,8 @@ const DEFAULT_ARCHIVE_EXCLUDED_DIR_NAMES_ANYWHERE = new Set([
   ".pi",
   ".oracle-context",
   ".cursor",
+  ".artifacts",
+  ".crabbox",
   "node_modules",
   "target",
   ".venv",
@@ -386,6 +392,99 @@ function formatArchiveOversizeError(args: {
     .join("\n");
 }
 
+function writeOctal(value: number, width: number): Buffer {
+  const text = Math.max(0, Math.floor(value)).toString(8).slice(-(width - 1)).padStart(width - 1, "0") + "\0";
+  return Buffer.from(text, "ascii");
+}
+
+function writeTarName(header: Buffer, name: string): void {
+  const normalized = name.replaceAll("\\", "/");
+  const nameBytes = Buffer.byteLength(normalized);
+  if (nameBytes <= 100) {
+    header.write(normalized, 0, 100, "utf8");
+    return;
+  }
+  const parts = normalized.split("/");
+  const fileName = parts.pop() || "";
+  const prefix = parts.join("/");
+  if (Buffer.byteLength(fileName) > 100 || Buffer.byteLength(prefix) > 155) {
+    throw new Error(`archive path is too long for portable tar header: ${normalized}`);
+  }
+  header.write(fileName, 0, 100, "utf8");
+  header.write(prefix, 345, 155, "utf8");
+}
+
+function buildTarHeader(name: string, options: { mode: number; size: number; mtimeMs: number; type: "file" | "directory" | "symlink"; linkName?: string }): Buffer {
+  const header = Buffer.alloc(512);
+  writeTarName(header, options.type === "directory" && !name.endsWith("/") ? `${name}/` : name);
+  writeOctal(options.mode & 0o7777, 8).copy(header, 100);
+  writeOctal(0, 8).copy(header, 108);
+  writeOctal(0, 8).copy(header, 116);
+  writeOctal(options.size, 12).copy(header, 124);
+  writeOctal(Math.floor(options.mtimeMs / 1000), 12).copy(header, 136);
+  Buffer.from("        ", "ascii").copy(header, 148);
+  header[156] = options.type === "directory" ? 53 : options.type === "symlink" ? 50 : 48;
+  if (options.linkName) header.write(options.linkName.replaceAll("\\", "/"), 157, 100, "utf8");
+  header.write("ustar", 257, 6, "ascii");
+  header.write("00", 263, 2, "ascii");
+  let checksum = 0;
+  for (const byte of header) checksum += byte;
+  const checksumText = checksum.toString(8).padStart(6, "0");
+  header.write(`${checksumText}\0 `, 148, 8, "ascii");
+  return header;
+}
+
+async function writeChunk(stream: NodeJS.WritableStream, chunk: Buffer): Promise<void> {
+  if (!stream.write(chunk)) await once(stream, "drain");
+}
+
+async function writeWindowsTarArchiveToZstd(cwd: string, entries: string[], archivePath: string, timeout: AbortSignal): Promise<void> {
+  const scrubbedEnv = sweetCookieSafeStoragePasswordScrubbedEnv(process.env);
+  const zstd = spawn("zstd", ["-19", "-T0", "-f", "-o", archivePath], {
+    cwd,
+    env: scrubbedEnv,
+    stdio: ["pipe", "ignore", "pipe"],
+    signal: timeout,
+  });
+  let stderr = "";
+  zstd.stderr?.on("data", (chunk) => {
+    stderr += String(chunk);
+  });
+  try {
+    for (const entry of entries) {
+      const normalizedEntry = entry.replaceAll("\\", "/");
+      const absolutePath = join(cwd, normalizedEntry);
+      const info = await lstat(absolutePath);
+      if (info.isSymbolicLink()) {
+        await writeChunk(zstd.stdin, buildTarHeader(normalizedEntry, { mode: info.mode, size: 0, mtimeMs: info.mtimeMs, type: "symlink", linkName: await readlink(absolutePath) }));
+        continue;
+      }
+      if (info.isDirectory()) {
+        await writeChunk(zstd.stdin, buildTarHeader(normalizedEntry, { mode: info.mode, size: 0, mtimeMs: info.mtimeMs, type: "directory" }));
+        continue;
+      }
+      if (!info.isFile()) continue;
+      await writeChunk(zstd.stdin, buildTarHeader(normalizedEntry, { mode: info.mode, size: info.size, mtimeMs: info.mtimeMs, type: "file" }));
+      for await (const chunk of createReadStream(absolutePath)) {
+        await writeChunk(zstd.stdin, Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      }
+      const padding = info.size % 512 === 0 ? 0 : 512 - (info.size % 512);
+      if (padding > 0) await writeChunk(zstd.stdin, Buffer.alloc(padding));
+    }
+    await writeChunk(zstd.stdin, Buffer.alloc(1024));
+    zstd.stdin.end();
+  } catch (error) {
+    zstd.stdin.destroy();
+    zstd.kill();
+    throw error;
+  }
+  const code = await new Promise<number | null>((resolve, reject) => {
+    zstd.once("error", reject);
+    zstd.once("close", resolve);
+  });
+  if (code !== 0) throw new Error(`zstd archive compression failed with status ${code}: ${stderr.trim()}`);
+}
+
 async function writeArchiveFile(
   cwd: string,
   entries: string[],
@@ -396,13 +495,32 @@ async function writeArchiveFile(
   await writeFile(listPath, Buffer.from(`${entries.join("\0")}\0`), { mode: 0o600 });
   await rm(archivePath, { force: true }).catch(() => undefined);
 
-  const { spawn } = await import("node:child_process");
+  if (process.platform === "win32") {
+    const timeoutController = new AbortController();
+    const timeout = setTimeout(() => timeoutController.abort(), options?.commandTimeoutMs ?? ARCHIVE_COMMAND_TIMEOUT_MS);
+    try {
+      await writeWindowsTarArchiveToZstd(cwd, entries, archivePath, timeoutController.signal);
+      return (await stat(archivePath)).size;
+    } catch (error) {
+      if (timeoutController.signal.aborted) {
+        throw new Error(`Oracle archive subprocess timed out after ${options?.commandTimeoutMs ?? ARCHIVE_COMMAND_TIMEOUT_MS}ms`);
+      }
+      throw error;
+    } finally {
+      clearTimeout(timeout);
+    }
+  }
+
   await new Promise<void>((resolvePromise, rejectPromise) => {
-    const tar = spawn("tar", ["--null", "-cf", "-", "-T", listPath], {
-      cwd,
+    const scrubbedEnv = sweetCookieSafeStoragePasswordScrubbedEnv();
+    const tarArgs = ["--null", "-cf", "-", "-C", cwd, "-T", basename(listPath)];
+    const tar = spawn(process.env.PI_ORACLE_TEST_TAR_BIN ?? "tar", tarArgs, {
+      cwd: dirname(listPath),
+      env: scrubbedEnv,
       stdio: ["ignore", "pipe", "pipe"],
     });
-    const zstd = spawn("zstd", ["-19", "-T0", "-f", "-o", archivePath], {
+    const zstd = spawn(process.env.PI_ORACLE_TEST_ZSTD_BIN ?? "zstd", ["-19", "-T0", "-f", "-o", archivePath], {
+      env: scrubbedEnv,
       stdio: ["pipe", "ignore", "pipe"],
     });
 
@@ -832,6 +950,14 @@ function buildOracleToolErrorDetails(toolName: OracleToolErrorSource, error: unk
     };
   }
 
+  if (/^Oracle (auth seed profile|runtime profile|runtime profiles) path is unsafe: /.test(message)) {
+    return {
+      code: "oracle_profile_path_unsafe",
+      message,
+      suggestedNextStep: "Move browser.authSeedProfileDir/browser.runtimeProfilesDir outside real browser profile directories and retry.",
+    };
+  }
+
   if (message.startsWith("Oracle runtime profiles directory is not writable: ")) {
     return {
       code: "runtime_profiles_dir_unwritable",
@@ -964,10 +1090,10 @@ function buildOracleToolErrorDetails(toolName: OracleToolErrorSource, error: unk
 function buildOracleToolErrorResult(
   toolName: OracleToolName,
   error: unknown,
-  params: Record<string, unknown>,
+  params: unknown,
   options?: { job?: NonNullable<ReturnType<typeof readJob>>; jobDetails?: OracleToolJobDetailsOptions },
 ) {
-  const errorDetails = buildOracleToolErrorDetails(toolName, error, params);
+  const errorDetails = buildOracleToolErrorDetails(toolName, error, asRecord(params) ?? {});
   return {
     content: [{
       type: "text" as const,
@@ -1430,7 +1556,7 @@ export function registerOracleTools(pi: ExtensionAPI, workerPath: string, authWo
             await appendCleanupWarnings(job.id, cleanupReport.warnings).catch(() => undefined);
           }
           if (ctx.hasUI) refreshOracleStatus(ctx);
-          return buildOracleToolErrorResult("oracle_submit", error, params as unknown as Record<string, unknown>, {
+          return buildOracleToolErrorResult("oracle_submit", error, params, {
             job: latest ?? job,
             jobDetails: {
               queue: latest ? buildOracleQueueSnapshot(latest, latest.status === "queued" ? getQueuePosition(latest.id) : undefined) : undefined,
@@ -1443,7 +1569,7 @@ export function registerOracleTools(pi: ExtensionAPI, workerPath: string, authWo
           await rm(tempArchivePath, { force: true }).catch(() => undefined);
         }
       } catch (error) {
-        return buildOracleToolErrorResult("oracle_submit", error, params as unknown as Record<string, unknown>);
+        return buildOracleToolErrorResult("oracle_submit", error, params);
       }
     },
   });
@@ -1503,7 +1629,7 @@ export function registerOracleTools(pi: ExtensionAPI, workerPath: string, authWo
           },
         };
       } catch (error) {
-        return buildOracleToolErrorResult("oracle_read", error, params as unknown as Record<string, unknown>);
+        return buildOracleToolErrorResult("oracle_read", error, params);
       }
     },
   });
@@ -1538,7 +1664,7 @@ export function registerOracleTools(pi: ExtensionAPI, workerPath: string, authWo
           details: { job: redactJobDetails(cancelled, { queue: buildOracleQueueSnapshot(cancelled, cancelled.status === "queued" ? getQueuePosition(cancelled.id) : undefined) }) },
         };
       } catch (error) {
-        return buildOracleToolErrorResult("oracle_cancel", error, params as unknown as Record<string, unknown>);
+        return buildOracleToolErrorResult("oracle_cancel", error, params);
       }
     },
   });

package/extensions/oracle/shared/browser-profile-helpers.d.mts

@@ -0,0 +1,59 @@
+export type OraclePlatform = NodeJS.Platform;
+
+export interface BrowserPathOptions {
+  env?: NodeJS.ProcessEnv;
+  homeDir?: string;
+}
+
+export interface ExecutableSearchOptions {
+  pathValue?: string;
+  pathDelimiter?: string;
+}
+
+export const SWEET_COOKIE_SAFE_STORAGE_PASSWORD_ENV_NAMES: readonly [
+  "SWEET_COOKIE_CHROME_SAFE_STORAGE_PASSWORD",
+  "SWEET_COOKIE_BRAVE_SAFE_STORAGE_PASSWORD",
+  "SWEET_COOKIE_EDGE_SAFE_STORAGE_PASSWORD",
+];
+
+export function expandHomePath(value: string, homeDir?: string): string;
+export function normalizedAbsolutePath(value: string, options?: BrowserPathOptions): string;
+export function linuxConfigHome(options?: BrowserPathOptions): string;
+export function linuxChromiumCookieImportUserDataDirs(options?: BrowserPathOptions): string[];
+export function linuxBrowserSafetyUserDataDirs(options?: BrowserPathOptions): string[];
+export function browserUserDataDirsForPlatform(
+  platform?: OraclePlatform,
+  options?: BrowserPathOptions & { includeUnsupported?: boolean },
+): string[];
+export function defaultCloneStrategyForPlatform(platform?: OraclePlatform): "apfs-clone" | "copy";
+export function chromiumKeychainSupportedOnPlatform(platform?: OraclePlatform): boolean;
+export function chromeUserAgentPlatformToken(platform?: OraclePlatform): string | undefined;
+export function pathInsideOrEqual(childPath: string, parentPath: string): boolean;
+export function resolvePathThroughExistingAncestorsSync(pathValue: string): string | undefined;
+export function protectedCookieSourcePaths(cookieSources?: { chromeProfile?: string; chromeCookiePath?: string }): string[];
+export function knownBrowserUserDataPathMatch(
+  pathValue: string,
+  options?: BrowserPathOptions & {
+    platform?: OraclePlatform;
+    includeUnsupported?: boolean;
+    extraProtectedPaths?: string[];
+    cookieSources?: { chromeProfile?: string; chromeCookiePath?: string };
+  },
+): string | undefined;
+export function assertNotKnownBrowserUserDataPath(
+  pathValue: string,
+  label: string,
+  options?: BrowserPathOptions & {
+    platform?: OraclePlatform;
+    includeUnsupported?: boolean;
+    extraProtectedPaths?: string[];
+    cookieSources?: { chromeProfile?: string; chromeCookiePath?: string };
+  },
+): void;
+export function isExecutableFileSync(pathValue: string): boolean;
+export function findExecutableOnPathSync(names: readonly string[], options?: ExecutableSearchOptions): string | undefined;
+export function detectDefaultLinuxChromeExecutablePath(options?: ExecutableSearchOptions): string | undefined;
+export function detectDefaultLinuxCookieProfileSource(options?: BrowserPathOptions): string | undefined;
+export function detectDefaultBrowserProfileSource(platform?: OraclePlatform, options?: BrowserPathOptions): string;
+export function scrubSweetCookieSafeStoragePasswordEnv(env?: NodeJS.ProcessEnv): void;
+export function sweetCookieSafeStoragePasswordScrubbedEnv(env?: NodeJS.ProcessEnv): NodeJS.ProcessEnv;

package/extensions/oracle/shared/browser-profile-helpers.mjs

@@ -0,0 +1,395 @@
+// Purpose: Centralize platform-specific browser profile paths, executable discovery, and profile-safety checks for oracle auth/runtime code.
+// Responsibilities: Resolve Chromium-family user-data roots, choose platform defaults, find executable files safely, and block oracle profile paths that point into real browser data.
+// Scope: Local filesystem/path policy only; cookie import, browser automation, and config loading stay in higher-level modules.
+// Usage: Imported by config.ts, runtime.ts, auth-bootstrap.mjs, run-job.mjs, and sanity tests.
+// Invariants/Assumptions: Real browser profile roots must never be used as oracle seed/runtime profile destinations, even through symlinked ancestors.
+
+import { accessSync, constants as fsConstants, existsSync, realpathSync, readFileSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { basename, delimiter, dirname, isAbsolute, join, normalize, resolve } from "node:path";
+
+/** @typedef {import("./browser-profile-helpers.d.mts").OraclePlatform} OraclePlatform */
+/** @typedef {import("./browser-profile-helpers.d.mts").BrowserPathOptions} BrowserPathOptions */
+/** @typedef {import("./browser-profile-helpers.d.mts").ExecutableSearchOptions} ExecutableSearchOptions */
+
+export const SWEET_COOKIE_SAFE_STORAGE_PASSWORD_ENV_NAMES = Object.freeze([
+  "SWEET_COOKIE_CHROME_SAFE_STORAGE_PASSWORD",
+  "SWEET_COOKIE_BRAVE_SAFE_STORAGE_PASSWORD",
+  "SWEET_COOKIE_EDGE_SAFE_STORAGE_PASSWORD",
+]);
+
+const LINUX_COOKIE_IMPORT_USER_DATA_RELATIVE_DIRS = Object.freeze([
+  ["google-chrome"],
+  ["chromium"],
+  ["chromium-browser"],
+  ["BraveSoftware", "Brave-Browser"],
+]);
+
+const LINUX_SAFETY_EXTRA_USER_DATA_RELATIVE_DIRS = Object.freeze([
+  ["google-chrome-beta"],
+  ["google-chrome-unstable"],
+  ["microsoft-edge"],
+  ["microsoft-edge-beta"],
+  ["microsoft-edge-dev"],
+  ["vivaldi"],
+  ["opera"],
+]);
+
+const MAC_CHROMIUM_USER_DATA_RELATIVE_DIRS = Object.freeze([
+  ["Library", "Application Support", "Google", "Chrome"],
+  ["Library", "Application Support", "Chromium"],
+  ["Library", "Application Support", "BraveSoftware", "Brave-Browser"],
+  ["Library", "Application Support", "Microsoft Edge"],
+  ["Library", "Application Support", "Arc", "User Data"],
+  ["Library", "Application Support", "Vivaldi"],
+  ["Library", "Application Support", "com.operasoftware.Opera"],
+  ["Library", "Application Support", "Google", "Chrome for Testing"],
+]);
+
+const WINDOWS_CHROMIUM_USER_DATA_RELATIVE_DIRS = Object.freeze([
+  ["AppData", "Local", "Google", "Chrome", "User Data"],
+  ["AppData", "Local", "Chromium", "User Data"],
+  ["AppData", "Local", "BraveSoftware", "Brave-Browser", "User Data"],
+  ["AppData", "Local", "Microsoft", "Edge", "User Data"],
+  ["AppData", "Local", "Vivaldi", "User Data"],
+  ["AppData", "Roaming", "Opera Software", "Opera Stable"],
+]);
+
+const LINUX_CHROME_EXECUTABLE_NAMES = Object.freeze(["google-chrome", "google-chrome-stable", "chromium", "chromium-browser", "brave-browser", "brave"]);
+
+/**
+ * @param {string} value
+ * @param {string} [homeDir]
+ * @returns {string}
+ */
+export function expandHomePath(value, homeDir = homedir()) {
+  if (value === "~") return homeDir;
+  if (value.startsWith("~/")) return join(homeDir, value.slice(2));
+  return value;
+}
+
+/**
+ * @param {string} value
+ * @param {BrowserPathOptions} [options]
+ * @returns {string}
+ */
+export function normalizedAbsolutePath(value, options = {}) {
+  const expanded = expandHomePath(value, options.homeDir ?? homedir());
+  return normalize(isAbsolute(expanded) ? expanded : resolve(expanded));
+}
+
+/**
+ * @param {BrowserPathOptions} [options]
+ * @returns {string}
+ */
+export function linuxConfigHome(options = {}) {
+  const env = options.env ?? process.env;
+  const configured = env.XDG_CONFIG_HOME?.trim();
+  return configured ? normalizedAbsolutePath(configured, options) : join(options.homeDir ?? homedir(), ".config");
+}
+
+/**
+ * @param {BrowserPathOptions} [options]
+ * @returns {string[]}
+ */
+export function linuxChromiumCookieImportUserDataDirs(options = {}) {
+  const configHome = linuxConfigHome(options);
+  return LINUX_COOKIE_IMPORT_USER_DATA_RELATIVE_DIRS.map((segments) => join(configHome, ...segments));
+}
+
+/**
+ * @param {BrowserPathOptions} [options]
+ * @returns {string[]}
+ */
+export function linuxBrowserSafetyUserDataDirs(options = {}) {
+  const configHome = linuxConfigHome(options);
+  return [
+    ...LINUX_COOKIE_IMPORT_USER_DATA_RELATIVE_DIRS,
+    ...LINUX_SAFETY_EXTRA_USER_DATA_RELATIVE_DIRS,
+  ].map((segments) => join(configHome, ...segments));
+}
+
+/**
+ * @param {OraclePlatform} [platform]
+ * @param {BrowserPathOptions & { includeUnsupported?: boolean }} [options]
+ * @returns {string[]}
+ */
+export function browserUserDataDirsForPlatform(platform = process.platform, options = {}) {
+  const homeDir = options.homeDir ?? homedir();
+  if (platform === "darwin") return MAC_CHROMIUM_USER_DATA_RELATIVE_DIRS.map((segments) => join(homeDir, ...segments));
+  if (platform === "linux") return options.includeUnsupported === false ? linuxChromiumCookieImportUserDataDirs({ ...options, homeDir }) : linuxBrowserSafetyUserDataDirs({ ...options, homeDir });
+  if (platform === "win32") return WINDOWS_CHROMIUM_USER_DATA_RELATIVE_DIRS.map((segments) => join(homeDir, ...segments));
+  return [];
+}
+
+/**
+ * @param {OraclePlatform} [platform]
+ * @returns {"apfs-clone" | "copy"}
+ */
+export function defaultCloneStrategyForPlatform(platform = process.platform) {
+  return platform === "darwin" ? "apfs-clone" : "copy";
+}
+
+/**
+ * @param {OraclePlatform} [platform]
+ * @returns {boolean}
+ */
+export function chromiumKeychainSupportedOnPlatform(platform = process.platform) {
+  return platform === "darwin";
+}
+
+/**
+ * @param {OraclePlatform} [platform]
+ * @returns {string | undefined}
+ */
+export function chromeUserAgentPlatformToken(platform = process.platform) {
+  if (platform === "darwin") return "Macintosh; Intel Mac OS X 10_15_7";
+  if (platform === "linux") return "X11; Linux x86_64";
+  return undefined;
+}
+
+/**
+ * @param {string} childPath
+ * @param {string} parentPath
+ * @returns {boolean}
+ */
+export function pathInsideOrEqual(childPath, parentPath) {
+  const child = normalize(childPath);
+  const parent = normalize(parentPath);
+  if (child === parent) return true;
+  if (!parent) return false;
+  const parentWithSeparator = /[/\\]$/.test(parent) ? parent : `${parent}/`;
+  const alternateParentWithSeparator = parentWithSeparator.includes("/")
+    ? parentWithSeparator.replaceAll("/", "\\")
+    : parentWithSeparator.replaceAll("\\", "/");
+  return child.startsWith(parentWithSeparator) || child.startsWith(alternateParentWithSeparator);
+}
+
+/**
+ * Resolve a path as far as its existing ancestors allow. If the final path does
+ * not exist yet, any non-existing suffix is appended to the nearest existing
+ * ancestor's realpath so symlinked ancestors are still accounted for.
+ *
+ * @param {string} pathValue
+ * @returns {string | undefined}
+ */
+export function resolvePathThroughExistingAncestorsSync(pathValue) {
+  const absolute = normalizedAbsolutePath(pathValue);
+  const suffix = [];
+  let current = absolute;
+  while (true) {
+    if (existsSync(current)) {
+      try {
+        return normalize(join(realpathSync(current), ...suffix.reverse()));
+      } catch {
+        return undefined;
+      }
+    }
+    const parent = dirname(current);
+    if (parent === current) return undefined;
+    suffix.push(basename(current));
+    current = parent;
+  }
+}
+
+/**
+ * @param {string} pathValue
+ * @returns {boolean}
+ */
+function looksLikeFilesystemPath(pathValue) {
+  return pathValue.startsWith("/") || pathValue.startsWith("~/") || pathValue === "~" || pathValue.startsWith(".");
+}
+
+/**
+ * @param {string} pathValue
+ * @returns {boolean}
+ */
+function isCookiesDbPath(pathValue) {
+  return basename(pathValue) === "Cookies";
+}
+
+/**
+ * @param {string} cookiePath
+ * @returns {string[]}
+ */
+function protectedPathsForCookieDb(cookiePath) {
+  const normalized = normalizedAbsolutePath(cookiePath);
+  const cookieParent = dirname(normalized);
+  const profileDir = basename(cookieParent) === "Network" ? dirname(cookieParent) : cookieParent;
+  return [profileDir, dirname(profileDir)];
+}
+
+/**
+ * @param {{ chromeProfile?: string; chromeCookiePath?: string } | undefined} cookieSources
+ * @returns {string[]}
+ */
+export function protectedCookieSourcePaths(cookieSources) {
+  if (!cookieSources) return [];
+  const roots = [];
+  const cookiePath = typeof cookieSources.chromeCookiePath === "string" && cookieSources.chromeCookiePath.trim()
+    ? cookieSources.chromeCookiePath.trim()
+    : undefined;
+  if (cookiePath) roots.push(...protectedPathsForCookieDb(cookiePath));
+
+  const profile = typeof cookieSources.chromeProfile === "string" && cookieSources.chromeProfile.trim()
+    ? cookieSources.chromeProfile.trim()
+    : undefined;
+  if (profile && looksLikeFilesystemPath(profile)) {
+    const normalizedProfile = normalizedAbsolutePath(profile);
+    if (isCookiesDbPath(normalizedProfile)) roots.push(...protectedPathsForCookieDb(normalizedProfile));
+    else roots.push(normalizedProfile, dirname(normalizedProfile));
+  }
+
+  return [...new Set(roots.map((root) => normalize(root)))];
+}
+
+/**
+ * @param {string} pathValue
+ * @param {BrowserPathOptions & { platform?: OraclePlatform; includeUnsupported?: boolean; extraProtectedPaths?: string[]; cookieSources?: { chromeProfile?: string; chromeCookiePath?: string } }} [options]
+ * @returns {string | undefined}
+ */
+export function knownBrowserUserDataPathMatch(pathValue, options = {}) {
+  const platform = options.platform ?? process.platform;
+  const normalizedPath = normalizedAbsolutePath(pathValue, options);
+  const resolvedPath = resolvePathThroughExistingAncestorsSync(normalizedPath);
+  const roots = [
+    ...browserUserDataDirsForPlatform(platform, { ...options, includeUnsupported: options.includeUnsupported ?? true }),
+    ...protectedCookieSourcePaths(options.cookieSources),
+    ...((options.extraProtectedPaths ?? [])),
+  ];
+  for (const root of roots) {
+    const normalizedRoot = normalizedAbsolutePath(root, options);
+    if (pathInsideOrEqual(normalizedPath, normalizedRoot)) return normalizedRoot;
+    const resolvedRoot = resolvePathThroughExistingAncestorsSync(normalizedRoot) ?? normalizedRoot;
+    if (resolvedPath && pathInsideOrEqual(resolvedPath, resolvedRoot)) return resolvedRoot;
+  }
+  return undefined;
+}
+
+/**
+ * @param {string} pathValue
+ * @param {string} label
+ * @param {BrowserPathOptions & { platform?: OraclePlatform; includeUnsupported?: boolean; extraProtectedPaths?: string[]; cookieSources?: { chromeProfile?: string; chromeCookiePath?: string } }} [options]
+ * @returns {void}
+ */
+export function assertNotKnownBrowserUserDataPath(pathValue, label, options = {}) {
+  const match = knownBrowserUserDataPathMatch(pathValue, options);
+  if (match) {
+    throw new Error(`${label} must not point into a real browser user-data directory (${match}): ${pathValue}`);
+  }
+}
+
+/**
+ * @param {string} pathValue
+ * @returns {boolean}
+ */
+export function isExecutableFileSync(pathValue) {
+  try {
+    const stats = statSync(pathValue);
+    if (!stats.isFile()) return false;
+    accessSync(pathValue, fsConstants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * @param {readonly string[]} names
+ * @param {ExecutableSearchOptions} [options]
+ * @returns {string | undefined}
+ */
+export function findExecutableOnPathSync(names, options = {}) {
+  const pathValue = options.pathValue ?? process.env.PATH ?? "";
+  const pathDelimiter = options.pathDelimiter ?? delimiter;
+  for (const name of names) {
+    for (const dir of pathValue.split(pathDelimiter).filter(Boolean)) {
+      const candidate = join(dir, name);
+      if (isExecutableFileSync(candidate)) return candidate;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * @param {ExecutableSearchOptions} [options]
+ * @returns {string | undefined}
+ */
+export function detectDefaultLinuxChromeExecutablePath(options = {}) {
+  return findExecutableOnPathSync(LINUX_CHROME_EXECUTABLE_NAMES, options);
+}
+
+/**
+ * @param {string} userDataDir
+ * @returns {string | undefined}
+ */
+function readLastUsedProfileName(userDataDir) {
+  const localStatePath = join(userDataDir, "Local State");
+  if (!existsSync(localStatePath)) return undefined;
+  try {
+    const localState = JSON.parse(readFileSync(localStatePath, "utf8"));
+    const lastUsed = localState?.profile?.last_used;
+    if (typeof lastUsed !== "string") return undefined;
+    const trimmed = lastUsed.trim();
+    if (!trimmed || trimmed === "." || trimmed === ".." || trimmed.includes("/") || trimmed.includes("\\")) return undefined;
+    return trimmed;
+  } catch {
+    return undefined;
+  }
+}
+
+/**
+ * Return an absolute Linux Chrome/Chromium-family profile directory for the
+ * default cookie importer. Sweet Cookie's Linux `chrome` backend only resolves
+ * non-path profile names under google-chrome, so non-Google roots must be
+ * passed as absolute paths.
+ *
+ * @param {BrowserPathOptions} [options]
+ * @returns {string | undefined}
+ */
+export function detectDefaultLinuxCookieProfileSource(options = {}) {
+  for (const userDataDir of linuxChromiumCookieImportUserDataDirs(options)) {
+    const lastUsed = readLastUsedProfileName(userDataDir);
+    if (lastUsed) {
+      const profilePath = join(userDataDir, lastUsed);
+      if (pathInsideOrEqual(profilePath, userDataDir) && existsSync(profilePath)) return profilePath;
+    }
+    const defaultProfile = join(userDataDir, "Default");
+    if (existsSync(defaultProfile)) return defaultProfile;
+  }
+  return undefined;
+}
+
+/**
+ * @param {OraclePlatform} [platform]
+ * @param {BrowserPathOptions} [options]
+ * @returns {string}
+ */
+export function detectDefaultBrowserProfileSource(platform = process.platform, options = {}) {
+  if (platform === "linux") return detectDefaultLinuxCookieProfileSource(options) ?? "Default";
+  if (platform === "darwin") {
+    const userDataDir = browserUserDataDirsForPlatform("darwin", options)[0];
+    return readLastUsedProfileName(userDataDir) ?? "Default";
+  }
+  return "Default";
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {void}
+ */
+export function scrubSweetCookieSafeStoragePasswordEnv(env = process.env) {
+  for (const name of SWEET_COOKIE_SAFE_STORAGE_PASSWORD_ENV_NAMES) {
+    delete env[name];
+  }
+}
+
+/**
+ * @param {NodeJS.ProcessEnv} [env]
+ * @returns {NodeJS.ProcessEnv}
+ */
+export function sweetCookieSafeStoragePasswordScrubbedEnv(env = process.env) {
+  const childEnv = { ...env };
+  scrubSweetCookieSafeStoragePasswordEnv(childEnv);
+  return childEnv;
+}