runtime.ts

import { forwardExternalImportSetting } from "./external-imports-feature.js";
import { executablePathForSpawn } from "./executable-path.js";
export { executablePathForSpawn } from "./executable-path.js";
import { resolveBundledCodexExecutable } from "./codex-sdk-environment.js";
import { gitProtectionRoots } from "./targets.js";
import { isNonEmptyString, notify } from "./value.js";
import {
  execFile as execFileCallback,
  spawn,
  type ChildProcessWithoutNullStreams,
  type SpawnOptionsWithoutStdio,
} from "node:child_process";
import { randomUUID } from "node:crypto";
import {
  chmodSync,
  close as closeCallback,
  constants,
  createWriteStream,
  fstat as fstatCallback,
  open as openCallback,
  read as readCallback,
  type BigIntStats,
  type Stats,
} from "node:fs";
import {
  chmod,
  cp,
  copyFile,
  link,
  lstat,
  mkdir,
  mkdtemp,
  open,
  readFile,
  readdir,
  realpath,
  rename,
  rm,
  rmdir,
  stat,
  utimes,
  writeFile,
} from "node:fs/promises";
import { homedir, tmpdir } from "node:os";
import { createRequire } from "node:module";
import {
  basename,
  dirname,
  extname,
  isAbsolute,
  join,
  relative,
  resolve,
  sep,
  win32,
} from "node:path";
import { fileURLToPath } from "node:url";
import { promisify } from "node:util";
import { pipeline } from "node:stream/promises";
import { crc32 } from "node:zlib";
import { setTimeout as delay } from "node:timers/promises";
import { fromFdPromise, type ZipFile } from "yauzl";
import { parse } from "smol-toml";
import {
  CodexSecurityError,
  OutputDirectoryError,
  OutputDirectoryNotEmptyError,
  OutputInsideProtectedRootError,
  PluginBootstrapError,
  LocalPluginBootstrapError,
  PluginPythonUnavailableError,
  type ProtectedScanPathKind,
  SandboxUnavailableError,
  errorMessage,
  abortReason,
} from "./errors.js";
import type { JsonObject } from "./config.js";
import { isRecord } from "./record.js";
import {
  isWithin,
  resolveTrustedExecutable,
  type InspectedExecutable,
} from "./trusted-executable.js";
import {
  isWindowsUnsafePathComponent,
  windowsUnsafePathComponent,
} from "./windows-path.js";

const execFile = promisify(execFileCallback);

export type StartCodex = (
  command: string,
  args: readonly string[],
  options: SpawnOptionsWithoutStdio & { stdio: ["pipe", "pipe", "pipe"] },
) => ChildProcessWithoutNullStreams;

export const MARKETPLACE_NAME = "codex-security-sdk";
export const PLUGIN_NAME = "codex-security";
const MARKETPLACE_MANIFEST = `${JSON.stringify(
  {
    name: MARKETPLACE_NAME,
    interface: { displayName: "Codex Security SDK" },
    plugins: [
      {
        name: PLUGIN_NAME,
        source: { source: "local", path: `./plugins/${PLUGIN_NAME}` },
        policy: { installation: "AVAILABLE", authentication: "ON_INSTALL" },
        category: "Security",
      },
    ],
  },
  null,
  2,
)}\n`;

const MAX_ZIP_ENTRIES = 4_096;
const MAX_ZIP_CENTRAL_DIRECTORY = 16 * 1024 * 1024;
const MAX_ZIP_ENTRY_SIZE = 128 * 1024 * 1024;
const MAX_ZIP_EXPANDED_SIZE = 512 * 1024 * 1024;
const MODEL_UNSAFE_PATH = /[\u0000-\u001f\u007f-\u009f\u2028\u2029]/u;
const CREDENTIAL_LOCK_NAME = ".codex-security-scan.lock";
const CREDENTIAL_LOCK_DATABASE = ".codex-security-scan.sqlite3";
const CREDENTIAL_LOGOUT_MARKER = ".codex-security-logged-out";
const CREDENTIAL_LOCK_HEARTBEAT_MILLISECONDS = 5_000;
const CREDENTIAL_LOCK_POLL_MILLISECONDS = 25;
const INCOMPLETE_CREDENTIAL_LOCK_MILLISECONDS = 30_000;
const MAX_PROCESS_ID = 2_147_483_647;
const SANDBOX_PROBE_TIMEOUT_MILLISECONDS = 10_000;
const PLUGIN_HELPER_SECRET_ENVIRONMENT_VARIABLES = new Set([
  "OPENAI_API_KEY",
  "CODEX_API_KEY",
  "OPENROUTER_API_KEY",
  "FIREWORKS_API_KEY",
  "CHEAPER_INFERENCE_API_KEY",
]);
const PREPARE_SCAN_ARTIFACT_RESTORER_PROGRAM = `
from pathlib import Path
from runpy import run_path
import json
import sys

module = run_path(sys.argv[1])
canonical_path, root_identity = module["scan_root_identity"](Path(sys.argv[2]))
print(json.dumps({
    "canonicalPath": str(canonical_path),
    "dev": str(root_identity[0]),
    "ino": str(root_identity[1]),
}, ensure_ascii=False))
`.trim();
const RESTORE_SCAN_ARTIFACT_PROGRAM = `
from pathlib import Path
from runpy import run_path
import sys

module = run_path(sys.argv[1])
try:
    module["write_scan_local_bytes"](
        Path(sys.argv[2]),
        sys.argv[3],
        sys.stdin.buffer.read(),
        expected_root_identity=(int(sys.argv[4]), int(sys.argv[5])),
    )
except (module["ContractError"], OSError) as error:
    raise SystemExit(str(error))
`.trim();
const WINDOWS_CREDENTIAL_ACL_COMPLETE_PREFIX = "CODEX_SECURITY_ACL_COMPLETE:";
const WINDOWS_CREDENTIAL_DESCENDANTS_CHANGED_EXIT_CODE = 2;

export interface PluginInstall {
  pluginRoot: string;
  marketplaceRoot: string;
  installedRoot: string;
  marketplaceName: typeof MARKETPLACE_NAME;
  name: typeof PLUGIN_NAME;
  version: string;
}

export interface CodexCommand {
  command: string;
  args?: readonly string[];
}

interface CodexCommandResult {
  success: boolean;
  exitCode: number | null;
  stdout: string;
  stderr: string;
}

export type ProcessEnvironment = Record<string, string | undefined>;

export interface PluginPythonOptions {
  configuredPath?: string;
  environment?: ProcessEnvironment;
  homeDirectory?: string;
  managedRuntimeRoots?: readonly string[];
  protectedRoot?: string | readonly string[];
  currentDirectory?: string;
  signal?: AbortSignal;
}

export interface WorkbenchCommandOptions {
  python: string;
  pluginRoot: string;
  environment: ProcessEnvironment;
  stateDirectory?: string;
  protectedRoot?: string | readonly string[];
  currentDirectory?: string;
  signal?: AbortSignal;
  failureMessage?: string;
}

export interface ScanArtifactRestorer {
  restore(relativePath: string, contents: Uint8Array): Promise<void>;
}

function environmentValue(
  environment: ProcessEnvironment,
  requested: string,
  preserveWhitespace = false,
): string | undefined {
  const exact = environment[requested];
  const value = exact?.trim()
    ? exact
    : Object.entries(environment).find(
        ([name, value]) => name.toUpperCase() === requested && value?.trim(),
      )?.[1];
  return preserveWhitespace ? value : value?.trim();
}

export function codexSecurityStateDirectory(
  environment: ProcessEnvironment = process.env,
): string {
  const configured = environmentValue(environment, "CODEX_SECURITY_STATE_DIR");
  const path =
    configured !== undefined
      ? resolve(expandHome(configured, environment))
      : resolve(
          expandHome(
            environmentValue(environment, "CODEX_HOME", true) ??
              join(homedir(), ".codex"),
            environment,
          ),
          "state",
          "plugins",
          "codex-security",
        );
  requireModelSafeOutputDir(path);
  return path;
}

export function codexSecurityCredentialHome(
  environment: ProcessEnvironment = process.env,
): string {
  return join(codexSecurityStateDirectory(environment), "codex-home");
}

export async function prepareCodexSecurityCredentialHome(
  environment: ProcessEnvironment = process.env,
  validateLocation?: (path: string) => void,
): Promise<string> {
  const path = codexSecurityCredentialHome(environment);
  try {
    try {
      await mkdir(path, { recursive: true, mode: 0o700 });
    } catch (error) {
      if (nodeErrorCode(error) === "EEXIST") {
        if ((await lstat(path).catch(() => null))?.isDirectory() === false) {
          throw new OutputDirectoryError(
            `Codex Security credential home is not a directory: ${path}`,
            { cause: error },
          );
        }
      }
      throw error;
    }
    if ((process.umask() & 0o700) !== 0) await chmod(path, 0o700);
    const metadata = await lstat(path, { bigint: true });
    if (!metadata.isDirectory()) {
      throw new OutputDirectoryError(
        `Codex Security credential home is not a directory: ${path}`,
      );
    }
    const canonical = await realpath(path);
    requireModelSafeOutputDir(canonical);
    validateLocation?.(canonical);
    await requireSecureCredentialHome(canonical, {
      metadata,
    });
    return canonical;
  } catch (error) {
    if (error instanceof OutputDirectoryError) throw error;
    throw new OutputDirectoryError(
      `Unable to prepare the Codex Security credential home: ${path}`,
      { cause: error },
    );
  }
}

/**
 * Re-verify the credential home before every use.
 *
 * Durable cross-process `(st_dev, st_ino)` pins are deferred: there is no
 * workbench row for credential homes, and path+mode+trusted-ancestry checks on
 * each use already close the cross-user rename/replace class. Lock acquisition
 * still pins identity for the duration of a single lock session.
 */
export async function requireSecureCredentialHome(
  path: string,
  options: Parameters<typeof requirePrivateDirectory>[3] & {
    metadata?: BigIntStats;
    expectedDevice?: bigint;
    expectedInode?: bigint;
    validateWindowsAcl?: boolean;
  } = {},
): Promise<BigIntStats> {
  const platform = options.platform ?? process.platform;
  let metadata = options.metadata;
  if (metadata === undefined) {
    try {
      metadata = await lstat(path, { bigint: true });
    } catch (error) {
      throw new OutputDirectoryError(
        `Unable to inspect the Codex Security credential home: ${path}`,
        { cause: error },
      );
    }
  }
  if (!metadata.isDirectory() || metadata.isSymbolicLink()) {
    throw new OutputDirectoryError(
      `Codex Security credential home is not a directory: ${path}`,
    );
  }
  const canonical = await realpath(path);
  requireModelSafeOutputDir(canonical);
  const canonicalMetadata = await lstat(canonical, { bigint: true });
  if (
    canonicalMetadata.dev !== metadata.dev ||
    canonicalMetadata.ino !== metadata.ino
  ) {
    throw new OutputDirectoryError(
      `Codex Security credential home was replaced: ${canonical}`,
    );
  }
  metadata = canonicalMetadata;
  if (!metadata.isDirectory()) {
    throw new OutputDirectoryError(
      `Codex Security credential home is not a directory: ${path}`,
    );
  }
  if (
    options.expectedDevice !== undefined &&
    options.expectedInode !== undefined &&
    (metadata.dev !== options.expectedDevice ||
      metadata.ino !== options.expectedInode)
  ) {
    throw new OutputDirectoryError(
      `Codex Security credential home was replaced: ${canonical}`,
    );
  }
  if (platform !== "win32" || options.validateWindowsAcl !== false) {
    await requirePrivateCredentialHome(
      { mode: Number(metadata.mode), uid: Number(metadata.uid) },
      canonical,
      {
        platform,
        secureWindowsHome: options.secureWindowsHome,
      },
    );
  }
  if (platform !== "win32") {
    await requireSecureOutputAncestry(canonical);
  }
  return metadata;
}

export async function requirePrivateCredentialHome(
  metadata: Pick<Stats, "mode" | "uid">,
  path: string,
  options: Parameters<typeof requirePrivateDirectory>[3] = {},
): Promise<void> {
  await requirePrivateDirectory(metadata, path, "credential home", options);
}

export async function preparePolicyOutputDirectory(
  path: string,
  options: Parameters<typeof requirePrivateDirectory>[3] = {},
): Promise<void> {
  const metadata = await lstat(path);
  if ((options.platform ?? process.platform) !== "win32") {
    requireOutputDirectoryOwnership(metadata, path);
    return;
  }
  await requirePrivateDirectory(
    metadata,
    path,
    "policy output directory",
    options,
  );
}

async function requirePrivateDirectory(
  metadata: Pick<Stats, "mode" | "uid">,
  path: string,
  description: string,
  options: {
    platform?: NodeJS.Platform;
    secureWindowsHome?: (path: string) => Promise<void>;
  },
): Promise<void> {
  if ((options.platform ?? process.platform) !== "win32") {
    requirePrivateOutputDirectory(metadata, path);
    return;
  }

  try {
    await (options.secureWindowsHome ?? secureWindowsCredentialHome)(path);
  } catch (error) {
    const detail = windowsCredentialAclFailure(error);
    throw new OutputDirectoryError(
      `Unable to create a private Windows ${description}: ${path}${detail}`,
      { cause: error },
    );
  }
}

function windowsCredentialAclFailure(error: unknown): string {
  const stderr =
    typeof error === "object" && error !== null && "stderr" in error
      ? error.stderr
      : undefined;
  const detail =
    typeof stderr === "string" && stderr.trim() !== ""
      ? stderr
      : errorMessage(error);
  const normalized = errorMessage(detail).replace(/\s+/gu, " ").trim();
  return normalized === "" ? "" : `. ${normalized}`;
}

const WINDOWS_SYSTEM_SID = "S-1-5-18";
const WINDOWS_ADMINISTRATORS_SID = "S-1-5-32-544";
const WINDOWS_TRUSTED_INSTALLER_SID =
  "S-1-5-80-956008885-3418522649-1831038044-1853292631-2271478464";
const WINDOWS_LOCAL_SERVICE_SID = "S-1-5-19";
const WINDOWS_NETWORK_SERVICE_SID = "S-1-5-20";
const WINDOWS_EVERYONE_SID = "S-1-1-0";
const WINDOWS_AUTHENTICATED_USERS_SID = "S-1-5-11";
const WINDOWS_USERS_SID = "S-1-5-32-545";
const WINDOWS_CREATOR_OWNER_SID = "S-1-3-0";
const WINDOWS_CREATOR_GROUP_SID = "S-1-3-1";
const WINDOWS_OWNER_RIGHTS_SID = "S-1-3-4";
const WINDOWS_ALL_APPLICATION_PACKAGES_SID = "S-1-15-2-1";
const WINDOWS_PRINCIPAL_ALIASES: Readonly<Record<string, string>> = {
  SY: WINDOWS_SYSTEM_SID,
  BA: WINDOWS_ADMINISTRATORS_SID,
  LS: WINDOWS_LOCAL_SERVICE_SID,
  NS: WINDOWS_NETWORK_SERVICE_SID,
  WD: WINDOWS_EVERYONE_SID,
  AU: WINDOWS_AUTHENTICATED_USERS_SID,
  BU: WINDOWS_USERS_SID,
  CO: WINDOWS_CREATOR_OWNER_SID,
  CG: WINDOWS_CREATOR_GROUP_SID,
  OW: WINDOWS_OWNER_RIGHTS_SID,
  AC: WINDOWS_ALL_APPLICATION_PACKAGES_SID,
  AN: "S-1-5-7",
  IU: "S-1-5-4",
  NU: "S-1-5-2",
  SU: "S-1-5-6",
  RC: "S-1-5-12",
  ED: "S-1-5-9",
  BG: "S-1-5-32-546",
  PU: "S-1-5-32-547",
  AO: "S-1-5-32-548",
  SO: "S-1-5-32-549",
  PO: "S-1-5-32-550",
  BO: "S-1-5-32-551",
  RE: "S-1-5-32-552",
  RU: "S-1-5-32-554",
  RD: "S-1-5-32-555",
  NO: "S-1-5-32-556",
  MU: "S-1-5-32-558",
  LU: "S-1-5-32-559",
  IS: "S-1-5-32-568",
  CY: "S-1-5-32-569",
  ER: "S-1-5-32-573",
  CD: "S-1-5-32-574",
  RA: "S-1-5-32-575",
  ES: "S-1-5-32-576",
  HA: "S-1-5-32-578",
  AA: "S-1-5-32-579",
};
const WINDOWS_SID = /^S-1-(?:\d+-)*\d+$/u;
const WINDOWS_GUID =
  /^[\da-f]{8}-[\da-f]{4}-[\da-f]{4}-[\da-f]{4}-[\da-f]{12}$/iu;
const WINDOWS_SDDL_SID = "(?:S-1-(?:\\d+-)*\\d+|[A-Z]{2})";
const WINDOWS_SECURITY_DESCRIPTOR = new RegExp(
  `^O:(${WINDOWS_SDDL_SID})(?:G:${WINDOWS_SDDL_SID})?D:([A-Z_]*)(.*)$`,
  "u",
);

export interface WindowsCredentialAcl {
  owner: string;
  protected: boolean;
  grantsCurrentUserAccess: boolean;
  untrustedPrincipals: string[];
  deniedPrincipals: string[];
}

class UntrustedWindowsCredentialOwnerError extends Error {
  public constructor(owner: string) {
    super(`Windows credential ACL owner is not a trusted principal: ${owner}`);
  }
}

class RepairableWindowsCredentialAclError extends Error {
  public constructor(cause: unknown) {
    super("Windows credential ACL requires repair", { cause });
  }
}

class RepairableWindowsCredentialOwnerError extends Error {
  public constructor(cause: UntrustedWindowsCredentialOwnerError) {
    super(cause.message, { cause });
  }
}

class WindowsCredentialDescendantsChangedError extends Error {}

/** Inspect a Windows DACL without translating locale-specific account names. */
export function inspectWindowsCredentialAcl(
  descriptor: string,
  currentUserSid: string,
  options: {
    resolvedAliases?: Readonly<Record<string, string>>;
    scope?: "directory" | "file" | "ancestor";
  } = {},
): WindowsCredentialAcl {
  if (!WINDOWS_SID.test(currentUserSid)) {
    throw new Error("Unable to identify the current Windows user SID");
  }
  const match = WINDOWS_SECURITY_DESCRIPTOR.exec(descriptor.trim());
  if (match === null) {
    throw new Error("Windows credential ACL has no owner or DACL");
  }

  const principalAliases: Readonly<Record<string, string>> = {
    ...WINDOWS_PRINCIPAL_ALIASES,
    ...options.resolvedAliases,
  };
  const trustedPrincipals = new Set([
    currentUserSid,
    WINDOWS_SYSTEM_SID,
    WINDOWS_ADMINISTRATORS_SID,
    principalAliases["LA"] ?? "LA",
  ]);
  if (options.scope === "ancestor") {
    trustedPrincipals.add(WINDOWS_TRUSTED_INSTALLER_SID);
  }
  const normalizePrincipal = (principal: string): string =>
    principalAliases[principal] ?? principal;
  const trustedPrincipal = (principal: string): boolean =>
    trustedPrincipals.has(principal);
  const owner = normalizePrincipal(match[1]!);
  if (!trustedPrincipal(owner)) {
    throw new UntrustedWindowsCredentialOwnerError(owner);
  }
  const flags = match[2]!;
  if (flags.includes("NO_ACCESS_CONTROL")) {
    throw new Error("Windows credential ACL grants unrestricted access");
  }

  let remaining = match[3]!;
  let grantsCurrentDirectoryAccess = false;
  let grantsCurrentFileAccess = false;
  let grantsCurrentContainerAccess = false;
  let hasAccessRules = false;
  const untrustedPrincipals = new Set<string>();
  const deniedPrincipals = new Set<string>();
  while (remaining.startsWith("(")) {
    const { rule, rest } = windowsSecurityDescriptorRule(remaining);
    const fields = rule.split(";");
    const callback = ["XA", "XD", "ZA"].includes(fields[0]!);
    if ((callback && fields.length < 7) || (!callback && fields.length !== 6)) {
      throw new Error("Windows credential ACL has a malformed access rule");
    }
    const [
      type,
      inheritance,
      rights,
      objectGuid,
      inheritObjectGuid,
      rawPrincipal,
    ] = fields;
    if (!["A", "OA", "D", "OD", "XA", "XD", "ZA"].includes(type!)) {
      throw new Error("Windows credential ACL has an unsupported access rule");
    }
    if (rawPrincipal === "" || rights === "") {
      throw new Error("Windows credential ACL has an incomplete access rule");
    }
    const objectRule = type === "OA" || type === "OD" || type === "ZA";
    for (const guid of [objectGuid!, inheritObjectGuid!]) {
      if (guid !== "" && (!objectRule || !WINDOWS_GUID.test(guid))) {
        throw new Error("Windows credential ACL has a malformed object rule");
      }
    }
    const inheritanceFlags = windowsAceFlags(inheritance!);
    hasAccessRules = true;
    const principal = normalizePrincipal(rawPrincipal!);
    if (type === "A" || type === "OA" || type === "XA" || type === "ZA") {
      if (!trustedPrincipal(principal)) {
        if (
          options.scope !== "ancestor" ||
          windowsAceAllowsAncestorReplacement(rights!, inheritanceFlags)
        ) {
          untrustedPrincipals.add(principal);
        }
      } else if (
        !callback &&
        objectGuid === "" &&
        inheritObjectGuid === "" &&
        principal === currentUserSid &&
        windowsAceGrantsFullControl(rights!)
      ) {
        if (!inheritanceFlags.has("IO")) {
          grantsCurrentDirectoryAccess = true;
        }
        if (inheritanceFlags.has("OI") && !inheritanceFlags.has("NP")) {
          grantsCurrentFileAccess = true;
        }
        if (inheritanceFlags.has("CI") && !inheritanceFlags.has("NP")) {
          grantsCurrentContainerAccess = true;
        }
      }
    } else {
      deniedPrincipals.add(principal);
    }
    remaining = rest;
  }
  if (!hasAccessRules || (remaining !== "" && !remaining.startsWith("S:"))) {
    throw new Error("Windows credential ACL has an invalid access-rule list");
  }

  return {
    owner,
    protected: flags.includes("P"),
    grantsCurrentUserAccess:
      grantsCurrentDirectoryAccess &&
      (options.scope === "file" ||
        (grantsCurrentFileAccess && grantsCurrentContainerAccess)) &&
      deniedPrincipals.size === 0,
    untrustedPrincipals: [...untrustedPrincipals],
    deniedPrincipals: [...deniedPrincipals],
  };
}

function windowsSecurityDescriptorRule(value: string) {
  let depth = 0;
  let quoted = false;
  let escaped = false;
  for (let index = 0; index < value.length; index += 1) {
    const character = value[index]!;
    if (quoted) {
      if (!escaped && character === '"') quoted = false;
      escaped = character === "\\" && !escaped;
      continue;
    }
    if (character === '"') {
      quoted = true;
    } else if (character === "(") {
      depth += 1;
    } else if (character === ")") {
      depth -= 1;
      if (depth === 0) {
        return { rule: value.slice(1, index), rest: value.slice(index + 1) };
      }
    }
  }
  throw new Error("Windows credential ACL has a malformed rule");
}

function windowsAceFlags(value: string): ReadonlySet<string> {
  if (value.length % 2 !== 0) {
    throw new Error("Windows credential ACL has malformed inheritance flags");
  }
  const flags = new Set<string>();
  for (let offset = 0; offset < value.length; offset += 2) {
    const flag = value.slice(offset, offset + 2);
    if (!["OI", "CI", "NP", "IO", "ID"].includes(flag)) {
      throw new Error(
        "Windows credential ACL has unsupported inheritance flags",
      );
    }
    flags.add(flag);
  }
  return flags;
}

function windowsAceGrantsFullControl(rights: string): boolean {
  if (rights === "FA" || rights === "GA") return true;
  if (!/^0x[\da-f]+$/iu.test(rights)) return false;
  const mask = BigInt(rights);
  return (mask & 0x1f01ffn) === 0x1f01ffn || (mask & 0x10000000n) !== 0n;
}

function windowsAceAllowsAncestorReplacement(
  rights: string,
  inheritanceFlags: ReadonlySet<string>,
): boolean {
  if (inheritanceFlags.has("IO")) return false;
  if (/^0x[\da-f]+$/iu.test(rights)) {
    return (BigInt(rights) & 0x100d0040n) !== 0n;
  }
  // Rights tokens stay aligned to pairs of UTF-16 code units.
  for (const [right] of rights.matchAll(/[\s\S]{2}/g)) {
    if (["FA", "GA", "FW", "GW", "SD", "WD", "WO", "DC", "DT"].includes(right))
      return true;
  }
  return false;
}

export async function streamWindowsCredentialAclDescriptors(
  command: string,
  args: readonly string[],
  inspectDescriptor: (descriptor: string) => Promise<void>,
  options: { environment?: NodeJS.ProcessEnv } = {},
): Promise<void> {
  const child = spawn(command, [...args], {
    env: options.environment,
    stdio: ["ignore", "pipe", "pipe"],
    windowsHide: true,
  });
  let stderr = "";
  child.stderr.setEncoding("utf8");
  child.stderr.on("data", (chunk: string) => {
    stderr += chunk;
  });

  let descendantsChanged = false;
  const completion = new Promise<void>((resolve, reject) => {
    child.once("error", reject);
    child.once("close", (code, signal) => {
      if (code === 0) {
        resolve();
        return;
      }
      if (code === WINDOWS_CREDENTIAL_DESCENDANTS_CHANGED_EXIT_CODE) {
        descendantsChanged = true;
        resolve();
        return;
      }
      const reason = signal === null ? `exit code ${code}` : `signal ${signal}`;
      reject(
        Object.assign(
          new Error(`Windows credential ACL inspection failed with ${reason}`),
          { code, signal, stderr },
        ),
      );
    });
  });

  try {
    await Promise.all([
      completion,
      (async () => {
        // Consume chunks directly: readline can resume its queued-line
        // iterator after EOF and throw instead of draining the last lines.
        child.stdout.setEncoding("utf8");
        let pending = "";
        for await (const chunk of child.stdout) {
          const lines = (pending + chunk).split(/[\r\n]/u);
          pending = lines.pop()!;
          for (const descriptor of lines) {
            if (descriptor === "") continue;
            await inspectDescriptor(descriptor);
          }
        }
        if (pending !== "") {
          await inspectDescriptor(pending);
        }
      })(),
    ]);
  } catch (error) {
    if (child.exitCode === null && child.signalCode === null) child.kill();
    throw error;
  }

  if (descendantsChanged) {
    // Finish descriptor callbacks before allowing another snapshot attempt.
    throw new WindowsCredentialDescendantsChangedError(
      "Windows credential descendants changed during ACL inspection",
    );
  }
}

export async function inspectWindowsCredentialAclSnapshot(
  path: string,
  currentUserSid: string,
  options: {
    command: string;
    args: readonly string[];
    environment?: NodeJS.ProcessEnv;
    resolvedAliases?: Readonly<Record<string, string>>;
    resolveDescriptorAliases?: (descriptor: string) => Promise<void>;
  },
): Promise<{
  home: WindowsCredentialAcl;
  descendantsArePrivate: boolean;
}> {
  const ancestors: string[] = [];
  for (let ancestor = dirname(path); ; ancestor = dirname(ancestor)) {
    ancestors.push(ancestor);
    if (ancestor === dirname(ancestor)) break;
  }

  for (let attempt = 0; attempt < 3; attempt += 1) {
    let home: WindowsCredentialAcl | undefined;
    let descendantsArePrivate = true;
    let inspected = 0;
    let completed = false;
    try {
      await streamWindowsCredentialAclDescriptors(
        options.command,
        options.args,
        async (descriptor) => {
          if (completed) {
            throw new Error(
              "Windows credential ACL inspection continued after completion",
            );
          }
          if (descriptor.startsWith(WINDOWS_CREDENTIAL_ACL_COMPLETE_PREFIX)) {
            if (
              descriptor !==
              `${WINDOWS_CREDENTIAL_ACL_COMPLETE_PREFIX}${inspected}`
            ) {
              throw new Error(
                "Windows credential descendants could not be verified",
              );
            }
            completed = true;
            return;
          }
          const index = inspected;
          inspected += 1;
          await options.resolveDescriptorAliases?.(descriptor);

          if (index < ancestors.length) {
            const ancestorPath = ancestors[index]!;
            try {
              const ancestor = inspectWindowsCredentialAcl(
                descriptor,
                currentUserSid,
                {
                  resolvedAliases: options.resolvedAliases,
                  scope: "ancestor",
                },
              );
              if (ancestor.untrustedPrincipals.length !== 0) {
                throw new Error(
                  "Windows credential-home ancestor allows another identity to replace the directory",
                );
              }
            } catch (error) {
              const guidance =
                ancestorPath === dirname(ancestorPath)
                  ? "This volume root is unsupported. Choose a location on a volume with trusted ancestry; another directory on the same volume will not resolve this."
                  : "Choose a location outside this ancestor with trusted ownership and permissions.";
              throw new Error(
                `Windows private-directory ancestor could not be trusted: ${ancestorPath}. ${errorMessage(error)}. ${guidance}`,
                { cause: error },
              );
            }
            return;
          }

          if (index === ancestors.length) {
            try {
              home = inspectWindowsCredentialAcl(descriptor, currentUserSid, {
                resolvedAliases: options.resolvedAliases,
              });
            } catch (error) {
              if (error instanceof UntrustedWindowsCredentialOwnerError) {
                throw new RepairableWindowsCredentialOwnerError(error);
              }
              throw new RepairableWindowsCredentialAclError(error);
            }
            return;
          }

          const descendant = inspectWindowsCredentialAcl(
            descriptor,
            currentUserSid,
            {
              resolvedAliases: options.resolvedAliases,
              scope: "file",
            },
          );
          if (
            !descendant.grantsCurrentUserAccess ||
            descendant.untrustedPrincipals.length !== 0
          ) {
            descendantsArePrivate = false;
          }
        },
        { environment: options.environment },
      );
    } catch (error) {
      if (error instanceof WindowsCredentialDescendantsChangedError) continue;
      throw error;
    }
    if (inspected <= ancestors.length) {
      throw new Error("Windows credential-home ancestry could not be verified");
    }
    if (!completed) {
      throw new Error("Windows credential descendants could not be verified");
    }
    if (home === undefined) {
      throw new Error("Windows credential ACL could not be verified");
    }
    return { home, descendantsArePrivate };
  }
  throw new Error("Windows credential descendants could not be verified");
}

async function secureWindowsCredentialHome(path: string): Promise<void> {
  const systemRoot = process.env["SystemRoot"] ?? "C:\\Windows";
  const systemDirectory = join(systemRoot, "System32");
  const powershell = join(
    systemDirectory,
    "WindowsPowerShell",
    "v1.0",
    "powershell.exe",
  );
  const inheritedEnvironment = Object.fromEntries(
    Object.entries(process.env).filter(
      ([name]) => name.toUpperCase() !== "PSMODULEPATH",
    ),
  );
  const processOptions = {
    env: {
      ...inheritedEnvironment,
      CODEX_SECURITY_CREDENTIAL_ACL_PATH: path,
      PSModulePath: join(
        systemDirectory,
        "WindowsPowerShell",
        "v1.0",
        "Modules",
      ),
    },
    encoding: "utf8" as const,
    windowsHide: true,
    maxBuffer: 1024 * 1024,
  };
  const identity = await execFile(
    join(systemDirectory, "whoami.exe"),
    ["/user", "/fo", "csv", "/nh"],
    processOptions,
  );
  const sid = /^"(?:[^"]|"")*","(S-1-(?:\d+-)*\d+)"$/u.exec(
    identity.stdout.trim(),
  )?.[1];
  if (sid === undefined) {
    throw new Error("Unable to identify the current Windows user SID");
  }

  // Signed built-in cmdlets remain available under ConstrainedLanguage;
  // arbitrary .NET constructors, static methods, and SID translation do not.
  // Enumerate and count ACLs in the same process: parallel startup can create
  // or remove private cache and lock files while this traversal is running.
  const script = [
    "$ErrorActionPreference = 'Stop'",
    "$script:descriptorCount = 0",
    "function Write-CredentialAcl($path) { $descriptor = Microsoft.PowerShell.Security\\Get-Acl -LiteralPath $path | Microsoft.PowerShell.Utility\\Select-Object -ExpandProperty Sddl; if (-not $descriptor) { throw 'Windows credential ACL could not be verified' }; $script:descriptorCount += 1; $descriptor }",
    "function Read-CredentialDescendants($path) {",
    "  try { $entries = @(Microsoft.PowerShell.Management\\Get-ChildItem -LiteralPath $path -Force) } catch {",
    // A child can disappear while an existing directory is being enumerated.
    // Retry that incomplete listing before accepting a vanished descendant.
    `    if ($_.FullyQualifiedErrorId -eq 'System.IO.FileNotFoundException,Microsoft.PowerShell.Commands.GetChildItemCommand') { exit ${WINDOWS_CREDENTIAL_DESCENDANTS_CHANGED_EXIT_CODE} }`,
    "    if ($path -ne $env:CODEX_SECURITY_CREDENTIAL_ACL_PATH -and $_.CategoryInfo.Category -eq 'ObjectNotFound') { return }",
    "    throw",
    "  }",
    "  foreach ($entry in $entries) {",
    "    if (($entry.Attributes -band 1024) -and ($entry.LinkType -in @('SymbolicLink', 'Junction'))) { throw 'Windows credential home contains a symbolic link or junction' }",
    "    if ($entry.PSObject.TypeNames -notcontains 'System.IO.DirectoryInfo' -and $entry.PSObject.TypeNames -notcontains 'System.IO.FileInfo') { throw 'Windows credential home contains an unsafe entry' }",
    "    try { Write-CredentialAcl $entry.FullName } catch {",
    // A descendant can disappear inside Get-Acl after it was enumerated.
    `      if ($_.FullyQualifiedErrorId -eq 'System.IO.FileNotFoundException,Microsoft.PowerShell.Commands.GetAclCommand' -or $_.FullyQualifiedErrorId -eq 'GetAcl_PathNotFound_Exception,Microsoft.PowerShell.Commands.GetAclCommand') { exit ${WINDOWS_CREDENTIAL_DESCENDANTS_CHANGED_EXIT_CODE} }`,
    "      if ($_.FullyQualifiedErrorId -like 'GetAcl_PathNotFound,*') { continue }",
    "      throw",
    "    }",
    "    if ($entry.PSIsContainer) { Read-CredentialDescendants $entry.FullName }",
    "  }",
    "}",
    "$path = $env:CODEX_SECURITY_CREDENTIAL_ACL_PATH",
    "while ($true) { $parent = Microsoft.PowerShell.Management\\Split-Path -Path $path -Parent; if (-not $parent -or $parent -eq $path) { break }; Write-CredentialAcl $parent; $path = $parent }",
    "Write-CredentialAcl $env:CODEX_SECURITY_CREDENTIAL_ACL_PATH",
    "Read-CredentialDescendants $env:CODEX_SECURITY_CREDENTIAL_ACL_PATH",
    `"${WINDOWS_CREDENTIAL_ACL_COMPLETE_PREFIX}$script:descriptorCount"`,
  ].join("\n");
  const resolvePrincipalScript = [
    "$ErrorActionPreference = 'Stop'",
    "$descriptor = 'O:' + $env:CODEX_SECURITY_CREDENTIAL_PRINCIPAL + 'G:SYD:(A;;GA;;;SY)'",
    "Microsoft.PowerShell.Utility\\ConvertFrom-SddlString -Sddl $descriptor | Microsoft.PowerShell.Utility\\Select-Object -ExpandProperty RawDescriptor | Microsoft.PowerShell.Utility\\Select-Object -ExpandProperty Owner | Microsoft.PowerShell.Utility\\Select-Object -ExpandProperty Value",
  ].join("; ");
  const resolvedAliases: Record<string, string> = {};
  const resolvePrincipal = async (principal: string): Promise<void> => {
    if (
      !/^[A-Z]{2}$/u.test(principal) ||
      WINDOWS_PRINCIPAL_ALIASES[principal] !== undefined ||
      resolvedAliases[principal] !== undefined
    ) {
      return;
    }
    const resolved = await execFile(
      powershell,
      [
        "-NoLogo",
        "-NoProfile",
        "-NonInteractive",
        "-Command",
        resolvePrincipalScript,
      ],
      {
        ...processOptions,
        env: {
          ...processOptions.env,
          CODEX_SECURITY_CREDENTIAL_PRINCIPAL: principal,
        },
      },
    );
    const numeric = resolved.stdout.trim();
    if (!WINDOWS_SID.test(numeric)) {
      throw new Error(
        "Windows credential ACL contains an unresolvable identity",
      );
    }
    resolvedAliases[principal] = numeric;
  };
  const resolveDescriptorAliases = async (
    descriptor: string,
  ): Promise<void> => {
    const header = WINDOWS_SECURITY_DESCRIPTOR.exec(descriptor.trim());
    if (header === null) return;
    await resolvePrincipal(header[1]!);
    let remaining = header[3]!;
    while (remaining.startsWith("(")) {
      const { rule, rest } = windowsSecurityDescriptorRule(remaining);
      const principal = rule.split(";")[5];
      if (principal !== undefined) await resolvePrincipal(principal);
      remaining = rest;
    }
  };
  let descendantsArePrivate = true;
  const readAcl = async (): Promise<WindowsCredentialAcl> => {
    const snapshot = await inspectWindowsCredentialAclSnapshot(path, sid, {
      command: powershell,
      args: ["-NoLogo", "-NoProfile", "-NonInteractive", "-Command", script],
      environment: processOptions.env,
      resolvedAliases,
      resolveDescriptorAliases,
    });
    descendantsArePrivate = snapshot.descendantsArePrivate;
    return snapshot.home;
  };

  const icacls = join(systemDirectory, "icacls.exe");
  const installTrustedAcl = async (target = path): Promise<void> => {
    await execFile(
      icacls,
      [
        target,
        "/inheritance:r",
        "/grant:r",
        `*${sid}:(OI)(CI)F`,
        `*${WINDOWS_SYSTEM_SID}:(OI)(CI)F`,
        `*${WINDOWS_ADMINISTRATORS_SID}:(OI)(CI)F`,
      ],
      processOptions,
    );
  };
  let existing: WindowsCredentialAcl | undefined;
  for (let attempt = 0; existing === undefined && attempt < 3; attempt += 1) {
    try {
      existing = await readAcl();
    } catch (error) {
      if (error instanceof RepairableWindowsCredentialOwnerError) {
        await execFile(icacls, [path, "/setowner", `*${sid}`], processOptions);
      } else if (error instanceof RepairableWindowsCredentialAclError) {
        await installTrustedAcl();
      } else {
        throw error;
      }
    }
  }
  if (existing === undefined) {
    throw new Error("Windows credential ACL could not be repaired");
  }
  if (
    existing.grantsCurrentUserAccess &&
    existing.untrustedPrincipals.length === 0 &&
    !existing.protected
  ) {
    await execFile(icacls, [path, "/inheritance:d"], processOptions);
    existing = await readAcl();
  }

  let verified = existing;
  if (
    !verified.protected ||
    !verified.grantsCurrentUserAccess ||
    verified.untrustedPrincipals.length !== 0
  ) {
    await installTrustedAcl();
    verified = await readAcl();
    for (const principal of verified.untrustedPrincipals) {
      if (!WINDOWS_SID.test(principal)) {
        throw new Error(
          "Windows credential ACL contains an unresolvable identity",
        );
      }
      await execFile(
        icacls,
        [path, "/remove:g", `*${principal}`],
        processOptions,
      );
    }
    for (const principal of verified.deniedPrincipals) {
      if (!WINDOWS_SID.test(principal)) {
        throw new Error(
          "Windows credential ACL contains an unresolvable identity",
        );
      }
      await execFile(
        icacls,
        [path, "/remove:d", `*${principal}`],
        processOptions,
      );
    }
    if (
      verified.untrustedPrincipals.length !== 0 ||
      verified.deniedPrincipals.length !== 0
    ) {
      verified = await readAcl();
    }
  }
  if (!verified.protected) {
    throw new Error("Windows credential ACL still inherits access rules");
  }
  if (!verified.grantsCurrentUserAccess) {
    throw new Error(
      "Windows credential ACL does not grant the current user access",
    );
  }
  if (verified.untrustedPrincipals.length !== 0) {
    throw new Error("Windows credential ACL grants access to another identity");
  }
  if (!descendantsArePrivate) {
    await execFile(
      icacls,
      [join(path, "*"), "/reset", "/t", "/q"],
      processOptions,
    );
    await readAcl();
    if (!descendantsArePrivate) {
      throw new Error("Windows credential descendants remain accessible");
    }
  }
}

export async function withCredentialHomeLock<T>(
  codexHome: string,
  operation: () => Promise<T>,
  signal?: AbortSignal,
): Promise<T> {
  const release = await acquireCodexSecurityCredentialHomeLock(
    codexHome,
    signal,
  );
  try {
    return await operation();
  } finally {
    await release();
  }
}

export async function acquireCodexSecurityCredentialHomeLock(
  codexHome: string,
  signal?: AbortSignal,
  securityOptions: Parameters<typeof requirePrivateDirectory>[3] = {},
): Promise<() => Promise<void>> {
  throwIfSignalAborted(signal);
  const homeMetadata = await requireSecureCredentialHome(
    codexHome,
    securityOptions,
  );
  const expectedDevice = homeMetadata.dev;
  const expectedInode = homeMetadata.ino;
  const lock = join(codexHome, CREDENTIAL_LOCK_NAME);
  const ownerPath = join(lock, "owner.json");
  const token = randomUUID();
  const databasePath = join(codexHome, CREDENTIAL_LOCK_DATABASE);
  const existingDatabaseMetadata = await lstat(databasePath).catch(
    nullIfMissingFileError,
  );
  if (existingDatabaseMetadata !== null) {
    requireCredentialLockDatabaseFile(existingDatabaseMetadata, databasePath);
  }
  const require = createRequire(import.meta.url);
  // Both supported runtimes bundle SQLite. Keep the transaction in the process
  // doing the protected work, so pausing it cannot expire its lock.
  const Database = process.versions["bun"]
    ? (require("bun:sqlite") as { Database: CredentialLockDatabaseConstructor })
        .Database
    : (
        require("node:sqlite") as {
          DatabaseSync: CredentialLockDatabaseConstructor;
        }
      ).DatabaseSync;
  // Let SQLite create a missing guard so no separate descriptor can close after
  // another connection acquires its process-owned POSIX lock. Keep the guard
  // across releases so every contender locks the same inode.
  const database = new Database(databasePath);
  let databaseLocked = false;

  try {
    // SQLite creates new databases with the process umask. Tighten or repair
    // the guard synchronously before yielding so concurrent first-time callers
    // cannot reject its transient mode. The credential home is already private,
    // and the pre-open check above rejects linked existing files.
    if (process.platform !== "win32") chmodSync(databasePath, 0o600);
    const databaseMetadata = await lstat(databasePath);
    requireCredentialLockDatabaseFile(databaseMetadata, databasePath);
    if (
      existingDatabaseMetadata !== null &&
      (databaseMetadata.dev !== existingDatabaseMetadata.dev ||
        databaseMetadata.ino !== existingDatabaseMetadata.ino)
    ) {
      throw new OutputDirectoryError(
        `Codex Security credential-home lock changed while opening it: ${databasePath}`,
      );
    }
    requirePrivateCredentialFile(databaseMetadata, databasePath);

    database.exec("PRAGMA busy_timeout = 0");
    while (true) {
      throwIfSignalAborted(signal);
      await requireSecureCredentialHome(codexHome, {
        ...securityOptions,
        expectedDevice,
        expectedInode,
        validateWindowsAcl: false,
      });
      if (!databaseLocked) {
        try {
          database.exec("BEGIN EXCLUSIVE");
        } catch (error) {
          if (
            !isRecord(error) ||
            (error["errcode"] !== 5 && error["code"] !== "SQLITE_BUSY")
          ) {
            throw error;
          }
          await delay(CREDENTIAL_LOCK_POLL_MILLISECONDS, undefined, { signal });
          continue;
        }
        const currentDatabase = await lstat(databasePath);
        if (
          currentDatabase.dev !== databaseMetadata.dev ||
          currentDatabase.ino !== databaseMetadata.ino
        ) {
          throw new OutputDirectoryError(
            `Codex Security credential-home lock changed while acquiring it: ${databasePath}`,
          );
        }
        databaseLocked = true;
      }
      if ((await lstat(lock).catch(nullIfMissingFileError)) !== null) {
        if (await recoverStaleCredentialHomeLock(lock)) continue;
        await delay(CREDENTIAL_LOCK_POLL_MILLISECONDS, undefined, { signal });
        continue;
      }
      await requireSecureCredentialHome(codexHome, {
        ...securityOptions,
        expectedDevice,
        expectedInode,
      });
      try {
        await mkdir(lock, { mode: 0o700 });
      } catch (error) {
        if (nodeErrorCode(error) !== "EEXIST") throw error;
        if (await recoverStaleCredentialHomeLock(lock)) continue;
        await delay(CREDENTIAL_LOCK_POLL_MILLISECONDS, undefined, { signal });
        continue;
      }

      try {
        await writeFile(
          ownerPath,
          `${JSON.stringify({ pid: process.pid, token, protocol: "sqlite" })}\n`,
          { encoding: "utf8", flag: "wx", mode: 0o600 },
        );
      } catch (error) {
        await rm(lock, { recursive: true, force: true }).catch(() => undefined);
        throw error;
      }

      // Released clients use the directory heartbeat instead of the SQLite lock.
      const heartbeat = setInterval(async () => {
        try {
          const now = new Date();
          await utimes(lock, now, now);
        } catch {}
      }, CREDENTIAL_LOCK_HEARTBEAT_MILLISECONDS);
      heartbeat.unref();

      let released = false;
      return async () => {
        if (released) return;
        released = true;
        try {
          await requireSecureCredentialHome(codexHome, {
            ...securityOptions,
            expectedDevice,
            expectedInode,
          });
          const owner = JSON.parse(await readFile(ownerPath, "utf8")) as {
            token?: unknown;
          };
          if (owner.token !== token) {
            throw new PluginBootstrapError(
              "The Codex Security credential-home lock is no longer owned by this scan.",
            );
          }
          await rm(lock, { recursive: true, force: true });
        } finally {
          clearInterval(heartbeat);
          database.close();
        }
      };
    }
  } catch (error) {
    database.close();
    throw error;
  }
}

function requireCredentialLockDatabaseFile(
  metadata: Stats,
  path: string,
): void {
  if (!metadata.isFile() || metadata.nlink !== 1) {
    throw new OutputDirectoryError(
      `Codex Security credential-home lock must be a regular file, not a symlink or hard link: ${path}`,
    );
  }
}

interface CredentialLockDatabaseConstructor {
  new (path: string): {
    exec(sql: string): unknown;
    close(): void;
  };
}

async function recoverStaleCredentialHomeLock(lock: string): Promise<boolean> {
  const metadata = await lstat(lock).catch(nullIfMissingFileError);
  if (metadata === null) return true;
  if (!metadata.isDirectory()) {
    throw new OutputDirectoryError(
      `Codex Security credential-home lock is not a directory: ${lock}`,
    );
  }

  let owner: unknown;
  try {
    owner = JSON.parse(await readFile(join(lock, "owner.json"), "utf8"));
  } catch (error) {
    if (nodeErrorCode(error) !== "ENOENT" && !(error instanceof SyntaxError)) {
      throw error;
    }
  }

  // We hold the SQLite transaction, so a record from that protocol is orphaned.
  // Older clients only record a PID: a live one must be respected at any age.
  if (!isRecord(owner) || owner["protocol"] !== "sqlite") {
    // Only positive signed-32-bit PIDs identify an owner. Other values can name
    // process groups or fail argument validation, so use the stale-age check.
    const ownerPid = isRecord(owner) ? owner["pid"] : undefined;
    if (
      typeof ownerPid === "number" &&
      Number.isInteger(ownerPid) &&
      ownerPid > 0 &&
      ownerPid <= MAX_PROCESS_ID
    ) {
      try {
        process.kill(ownerPid, 0);
        return false;
      } catch (error) {
        if (nodeErrorCode(error) === "EPERM") return false;
        if (nodeErrorCode(error) !== "ESRCH") throw error;
      }
    } else if (
      Date.now() - metadata.mtimeMs <
      INCOMPLETE_CREDENTIAL_LOCK_MILLISECONDS
    ) {
      return false;
    }
  }

  const quarantine = `${lock}.stale-${randomUUID()}`;
  try {
    await rename(lock, quarantine);
  } catch (error) {
    if (nodeErrorCode(error) === "ENOENT") return true;
    throw error;
  }
  await rm(quarantine, { recursive: true, force: true });
  return true;
}

export async function setCodexSecurityCredentialLogout(
  codexHome: string,
  loggedOut: boolean,
): Promise<void> {
  await requireSecureCredentialHome(codexHome);
  const marker = join(codexHome, CREDENTIAL_LOGOUT_MARKER);
  if (!loggedOut) {
    await rm(marker, { force: true });
    return;
  }

  const temporary = join(
    codexHome,
    `.codex-security-logout-${randomUUID()}.tmp`,
  );
  try {
    const handle = await open(temporary, "wx", 0o600);
    try {
      await handle.chmod(0o600);
      await handle.writeFile("logged out\n", "utf8");
      await handle.sync();
    } finally {
      await handle.close();
    }
    await rename(temporary, marker);
  } finally {
    await rm(temporary, { force: true });
  }
}

export async function codexSecurityCredentialAllowsAmbientImport(
  codexHome: string,
): Promise<boolean> {
  await requireSecureCredentialHome(codexHome);
  try {
    if (!(await lstat(join(codexHome, CREDENTIAL_LOGOUT_MARKER))).isFile()) {
      throw new OutputDirectoryError(
        `Codex Security logout marker is not a regular file: ${codexHome}`,
      );
    }
    return false;
  } catch (error) {
    if (nodeErrorCode(error) === "ENOENT") return true;
    throw error;
  }
}

export async function codexSecurityHasStoredFileCredentials(
  codexHome: string,
): Promise<boolean> {
  await requireSecureCredentialHome(codexHome);
  const path = join(codexHome, "auth.json");
  let metadata: Stats;
  try {
    metadata = await lstat(path);
  } catch (error) {
    if (nodeErrorCode(error) === "ENOENT") return false;
    throw error;
  }
  if (!metadata.isFile()) {
    throw new OutputDirectoryError(
      `Codex Security stored authentication is not a regular file: ${path}`,
    );
  }
  requirePrivateCredentialFile(metadata, path);
  return true;
}

export function requirePrivateCredentialFile(
  metadata: Pick<Stats, "mode" | "uid">,
  path: string,
  effectiveUid = process.geteuid?.(),
): void {
  if (process.platform === "win32") return;
  if ((metadata.mode & 0o077) !== 0) {
    throw new OutputDirectoryError(
      `Codex Security stored authentication must not be accessible to other users: ${path}`,
    );
  }
  if (effectiveUid !== undefined && metadata.uid !== effectiveUid) {
    throw new OutputDirectoryError(
      `Codex Security stored authentication must be owned by the current user: ${path}`,
    );
  }
}

export async function preserveCodexSecurityPluginRegistration(
  codexHome: string,
  config: JsonObject,
): Promise<JsonObject> {
  let existing: unknown;
  try {
    existing = parse(await readFile(join(codexHome, "config.toml"), "utf8"));
  } catch (error) {
    if (nodeErrorCode(error) === "ENOENT") return config;
    throw new PluginBootstrapError(
      "Unable to read the existing Codex Security plugin registration.",
      { cause: error },
    );
  }

  const marketplaces = isRecord(existing)
    ? existing["marketplaces"]
    : undefined;
  const plugins = isRecord(existing) ? existing["plugins"] : undefined;
  const marketplace = isRecord(marketplaces)
    ? marketplaces[MARKETPLACE_NAME]
    : undefined;
  const plugin = isRecord(plugins)
    ? plugins[`${PLUGIN_NAME}@${MARKETPLACE_NAME}`]
    : undefined;
  const source = isRecord(marketplace) ? marketplace["source"] : undefined;
  if (
    !isRecord(marketplace) ||
    marketplace["source_type"] !== "local" ||
    typeof source !== "string" ||
    !(await sameFile(source, join(codexHome, "sdk-marketplace"))) ||
    !isRecord(plugin) ||
    plugin["enabled"] !== true
  ) {
    return config;
  }

  return {
    ...config,
    marketplaces: {
      [MARKETPLACE_NAME]: { source_type: "local", source },
    },
    plugins: {
      [`${PLUGIN_NAME}@${MARKETPLACE_NAME}`]: { enabled: true },
    },
  };
}

export function requireOutputOutsideRepository(
  repository: string,
  outputDirectory: string,
  pathKind: ProtectedScanPathKind = "output",
): void {
  if (
    isWithin(repository, outputDirectory) ||
    (pathKind === "output" && isWithin(outputDirectory, repository))
  ) {
    throw new OutputInsideProtectedRootError(
      outputDirectory,
      repository,
      pathKind,
    );
  }
}

export function requireOutputOutsideRepositories(
  repositories: readonly string[],
  outputDirectory: string,
  pathKind: ProtectedScanPathKind = "output",
): void {
  for (const repository of repositories)
    requireOutputOutsideRepository(repository, outputDirectory, pathKind);
}

export async function preparePersistentOutputRoot(
  stateDirectory: string,
  category: "scans" | "policies" | "validations" | "imports",
  repositoryName: string,
): Promise<string> {
  requireModelSafeOutputDir(stateDirectory);
  await mkdir(stateDirectory, { recursive: true, mode: 0o700 });
  let root = await realpath(stateDirectory);
  for (const directory of [category, safePrefix(repositoryName)]) {
    root = join(root, directory);
    await mkdir(root, { recursive: true, mode: 0o700 });
    if (!(await lstat(root)).isDirectory()) {
      throw new OutputDirectoryError(
        `Persistent ${category === "scans" ? "scan" : category === "policies" ? "policy" : category === "imports" ? "import" : "validation"} output must use real directories: ${root}`,
      );
    }
  }
  return root;
}

const WORKBENCH_ARGUMENTS_PROGRAM = String.raw`
import json, sys
sys.argv[2:] = json.loads(sys.stdin.buffer.readline())
`;
const WORKBENCH_SCRIPT_PROGRAM = String.raw`
import runpy, sys
sys.argv = sys.argv[1:]
runpy.run_path(sys.argv[0], run_name="__main__")
`;

const ARCHIVE_READY = "codex-security-archive-ready\n";
const ARCHIVE_REGISTRATION_PROGRAM = String.raw`
import io, json, runpy, sys
control = sys.stdin
payload = json.loads(control.readline())
sys.stdin = io.TextIOWrapper(io.BytesIO(payload.encode("utf-8")), encoding="utf-8")
sys.argv = sys.argv[1:]
workbench = runpy.run_path(sys.argv[0])
def before_archive():
    sys.stdout.buffer.write(b"codex-security-archive-ready\n")
    sys.stdout.buffer.flush()
    if control.readline() != "\n":
        raise SystemExit("Scan registration canceled before archival.")
workbench["main"](before_archive=before_archive)
`;

export async function runWorkbench(
  options: Omit<WorkbenchCommandOptions, "python"> & { python?: string },
  args: readonly string[],
  input?: string,
): Promise<JsonObject> {
  const script = join(options.pluginRoot, "scripts", "workbench_db.py");
  const signal = options.signal;
  const run = async (
    arguments_: readonly string[],
    input?: string,
    archiveHandshake = false,
  ): Promise<string> => {
    const native = [
      "database-info",
      "store-findings",
      "list-stored-findings",
      "store-external-findings",
      "list-external-findings",
      "find-potential-duplicates",
      "store-dedupe-groups",
      "list-dedupe-groups",
      "dashboard",
      "severity-classification",
      "read-severity-classification",
    ].includes(arguments_[0] ?? "");
    const node =
      native && process.versions["bun"]
        ? await resolveTrustedExecutable("node", options.environment, [
            process.cwd(),
            options.currentDirectory ?? process.cwd(),
            ...(typeof options.protectedRoot === "string"
              ? [options.protectedRoot]
              : (options.protectedRoot ?? [])),
          ])
        : undefined;
    if (node === null) {
      throw new Error("Node.js is not available on a trusted PATH.");
    }
    const command = native
      ? (node?.executable ?? process.execPath)
      : (options.python ??= await resolvePluginPython({
          environment: options.environment,
          protectedRoot: options.protectedRoot,
          currentDirectory: options.currentDirectory,
          signal: options.signal,
        }));
    const stateDirectory = native
      ? (options.stateDirectory ??
        codexSecurityStateDirectory(options.environment))
      : undefined;
    // Workbench text fields can contain NUL or exceed OS command-line limits.
    const framedArguments = !native;
    let program = archiveHandshake ? ARCHIVE_REGISTRATION_PROGRAM : undefined;
    if (framedArguments)
      program =
        WORKBENCH_ARGUMENTS_PROGRAM + (program ?? WORKBENCH_SCRIPT_PROGRAM);
    const result = await runCodexCommand(
      { command },
      native
        ? [join(options.pluginRoot, "mcp", "helpers.mjs"), ...arguments_]
        : [
            "-I",
            "-X",
            "utf8",
            "-B",
            ...(program === undefined ? [] : ["-c", program]),
            script,
            ...(framedArguments ? [] : arguments_),
          ],
      pluginHelperEnvironment(node?.environment ?? options.environment),
      // The SDK owns configuration normalization; the helper receives its resolved location.
      native
        ? JSON.stringify(
            arguments_[0] === "database-info"
              ? stateDirectory
              : {
                  stateDirectory,
                  payload: input === undefined ? undefined : JSON.parse(input),
                },
          )
        : input,
      signal,
      archiveHandshake,
      // Match native argv's UTF-8 encoding for the private argument frame.
      framedArguments
        ? `${JSON.stringify(arguments_.map((argument) => argument.toWellFormed()))}\n`
        : undefined,
    );
    if (!result.success) {
      throw new Error(
        result.stderr.trim() ||
          result.stdout.trim() ||
          `Workbench exited with status ${result.exitCode}.`,
      );
    }
    return result.stdout;
  };
  let stdout: string;
  try {
    const archiveHandshake =
      signal !== undefined &&
      args[0] === "register-cli-scan" &&
      args.includes("--archive-existing") &&
      !args.includes("--archived-scan-dir");
    stdout = await run(args, input, archiveHandshake);
  } catch (error) {
    if (options.signal?.aborted) throw error;
    const detail = processErrorDetail(error);
    const failure =
      options.failureMessage ?? "Could not run the Codex Security workbench";
    throw new CodexSecurityError(`${failure}: ${detail}`, { cause: error });
  }
  let result: unknown;
  try {
    result = JSON.parse(stdout);
  } catch (error) {
    throw new CodexSecurityError(
      "The Codex Security workbench returned invalid JSON.",
      { cause: error },
    );
  }
  if (!isRecord(result)) {
    throw new CodexSecurityError(
      "The Codex Security workbench returned an invalid response.",
    );
  }
  return result as JsonObject;
}

export function bundledPluginCandidates(moduleDirectory: string): string[] {
  return [
    resolve(moduleDirectory, "_bundled_plugin"),
    resolve(moduleDirectory, "../_bundled_plugin"),
  ];
}

export async function bundledPluginRoot(): Promise<string> {
  const moduleDirectory = dirname(fileURLToPath(import.meta.url));
  for (const candidate of bundledPluginCandidates(moduleDirectory)) {
    if (await hasPluginManifest(candidate)) {
      return await realpath(candidate);
    }
  }
  throw new PluginBootstrapError(
    "The bundled Codex Security plugin is missing.",
  );
}

export async function validateOutputDir(
  outputDirectory?: string,
  archiveExisting = false,
): Promise<string | null> {
  if (outputDirectory === undefined) {
    return null;
  }
  const path = resolve(expandHome(outputDirectory));
  requireModelSafeOutputDir(path);
  try {
    const metadata = await lstat(path).catch(nullIfMissingFileError);
    if (metadata !== null) {
      if (!metadata.isDirectory()) {
        throw new OutputDirectoryError(
          `Scan output is not a directory: ${path}`,
        );
      }
      if (!archiveExisting && (await readdir(path)).length !== 0) {
        throw new OutputDirectoryNotEmptyError(path);
      }
      requireOutputDirectoryOwnership(metadata, path);
      await requireSecureOutputAncestry(path);
      const canonical = await realpath(path);
      requireModelSafeOutputDir(canonical);
      return canonical;
    }

    let parent = dirname(path);
    while (true) {
      try {
        if ((await stat(parent)).isDirectory()) {
          const canonical = resolve(
            await realpath(parent),
            relative(parent, path),
          );
          requireModelSafeOutputDir(canonical);
          await requireSecureOutputAncestry(canonical);
          return canonical;
        }
        break;
      } catch (error) {
        if (nodeErrorCode(error) !== "ENOENT") throw error;
        const next = dirname(parent);
        if (next === parent) break;
        parent = next;
      }
    }
    throw new OutputDirectoryError(
      `Unable to create scan output directory: ${path}`,
    );
  } catch (error) {
    if (error instanceof OutputDirectoryError) throw error;
    throw new OutputDirectoryError(
      `Unable to inspect scan output directory: ${outputDirectory}`,
      { cause: error },
    );
  }
}

export async function prepareScanArtifactRestorer(
  options: WorkbenchCommandOptions,
  scanDirectory: string,
): Promise<ScanArtifactRestorer> {
  let helperPath: string;
  let canonicalPath: string;
  let dev: string;
  let ino: string;
  try {
    // Recovery uses the SDK-owned writer, even if the scan selected a custom plugin.
    helperPath = join(
      await bundledPluginRoot(),
      "scripts",
      "finalize_scan_contract.py",
    );
    const result = await runCodexCommand(
      { command: options.python },
      [
        "-I",
        "-X",
        "utf8",
        "-B",
        "-c",
        PREPARE_SCAN_ARTIFACT_RESTORER_PROGRAM,
        helperPath,
        scanDirectory,
      ],
      pluginHelperEnvironment(options.environment),
      undefined,
      options.signal,
    );
    if (!result.success) {
      throw new Error(
        result.stderr.trim() ||
          result.stdout.trim() ||
          `Artifact restoration setup exited with status ${result.exitCode}.`,
      );
    }
    const prepared: unknown = JSON.parse(result.stdout);
    if (
      !isRecord(prepared) ||
      !isNonEmptyString(prepared["canonicalPath"]) ||
      typeof prepared["dev"] !== "string" ||
      !/^(?:0|[1-9]\d*)$/u.test(prepared["dev"]) ||
      typeof prepared["ino"] !== "string" ||
      !/^(?:0|[1-9]\d*)$/u.test(prepared["ino"])
    ) {
      throw new Error("Artifact restoration setup returned invalid output.");
    }
    canonicalPath = prepared["canonicalPath"];
    dev = prepared["dev"];
    ino = prepared["ino"];
  } catch (error) {
    if (options.signal?.aborted) throw error;
    throw new OutputDirectoryError(
      "Could not securely prepare completed scan artifact restoration.",
      { cause: error },
    );
  }

  return {
    async restore(relativePath, contents) {
      try {
        const result = await runCodexCommand(
          { command: options.python },
          [
            "-I",
            "-X",
            "utf8",
            "-B",
            "-c",
            RESTORE_SCAN_ARTIFACT_PROGRAM,
            helperPath,
            canonicalPath,
            relativePath,
            dev,
            ino,
          ],
          pluginHelperEnvironment(options.environment),
          contents,
        );
        if (!result.success) {
          throw new Error(
            result.stderr.trim() ||
              result.stdout.trim() ||
              `Artifact restoration exited with status ${result.exitCode}.`,
          );
        }
      } catch (error) {
        throw new OutputDirectoryError(
          "Could not safely restore a completed scan artifact.",
          { cause: error },
        );
      }
    },
  };
}

export async function planOutputArchive(
  outputDirectory: string | null,
): Promise<string | null> {
  if (outputDirectory === null) return null;
  const entries = await readdir(outputDirectory).catch(nullIfMissingFileError);
  if (entries === null || entries.length === 0) return null;
  return `${outputDirectory}${outputArchiveSuffix()}`;
}

function outputArchiveSuffix(): string {
  return `.previous-${new Date()
    .toISOString()
    .replaceAll(/[-:]/g, "")
    .replace(/\.\d{3}Z$/, "")}-${randomUUID().slice(0, 8)}`;
}

export function requireModelSafeOutputDir(path: string): void {
  if (MODEL_UNSAFE_PATH.test(path)) {
    throw new OutputDirectoryError(
      "Scan output directory must not contain control or line-separator characters.",
    );
  }
  const ambiguous =
    process.platform === "win32" ? windowsUnsafePathComponent(path) : undefined;
  if (ambiguous !== undefined) {
    throw new OutputDirectoryError(
      `Codex Security paths must not contain Windows-ambiguous components: ${ambiguous}`,
    );
  }
}

export async function canonicalizeModelSafePath(
  input: string,
): Promise<string> {
  const path = resolve(expandHome(input));
  requireModelSafeOutputDir(path);
  const canonical = await canonicalConfigPath(path);
  requireModelSafeOutputDir(canonical);
  return canonical;
}

export async function canonicalConfigPath(path: string): Promise<string> {
  let existing = resolve(path);
  const missing: string[] = [];
  while (true) {
    try {
      return join(await realpath(existing), ...missing);
    } catch (error) {
      const parent = dirname(existing);
      if (
        (error as NodeJS.ErrnoException).code !== "ENOENT" ||
        parent === existing
      )
        throw error;
      missing.unshift(basename(existing));
      existing = parent;
    }
  }
}

export async function prepareOutputDir(
  outputDirectory: string | undefined,
  repositoryName: string,
  temporaryRoot: string = tmpdir(),
  validateLocation?: (path: string) => void,
  archiveExisting = false,
  onOutputArchived?: (archiveDir: string) => void,
): Promise<string> {
  return prepareOutputDirectory(
    outputDirectory,
    repositoryName,
    temporaryRoot,
    validateLocation,
    archiveExisting ? "archive" : "reject",
    onOutputArchived,
  );
}

/** Leave archival to the scan registration transaction. */
export async function prepareScanRegistrationOutput(
  outputDirectory: string | undefined,
  repositoryName: string,
  temporaryRoot: string = tmpdir(),
  validateLocation?: (path: string) => void,
  archiveExisting = false,
): Promise<string> {
  return prepareOutputDirectory(
    outputDirectory,
    repositoryName,
    temporaryRoot,
    validateLocation,
    archiveExisting ? "preserve" : "reject",
  );
}

async function prepareOutputDirectory(
  outputDirectory: string | undefined,
  repositoryName: string,
  temporaryRoot: string,
  validateLocation: ((path: string) => void) | undefined,
  existingOutput: "reject" | "archive" | "preserve",
  onOutputArchived?: (archiveDir: string) => void,
): Promise<string> {
  if (outputDirectory === undefined) {
    requireModelSafeOutputDir(temporaryRoot);
    requireModelSafeOutputDir(await realpath(temporaryRoot));
  }
  const path = await validateOutputDir(
    outputDirectory,
    existingOutput !== "reject",
  );
  validateLocation?.(path ?? (await realpath(temporaryRoot)));
  if (path === null) {
    const prefix = `codex-security-${safePrefix(repositoryName)}`;
    let created: string;
    if (process.platform === "win32") {
      const suffix = `-${randomUUID()}`;
      // Reserve room within NTFS's 255-unit component limit for later archival.
      // The SDK suffix is longer than the workbench's .previous-<tempname> suffix.
      const prefixLength = 255 - suffix.length - outputArchiveSuffix().length;
      created = join(
        temporaryRoot,
        `${prefix.slice(0, prefixLength)}${suffix}`,
      );
      await createWindowsOutputDirectory(created, false);
    } else {
      created = await mkdtemp(join(temporaryRoot, `${prefix}-`));
    }
    try {
      if ((process.umask() & 0o700) !== 0) await chmod(created, 0o700);
      return await validatePreparedOutputDir(created, validateLocation);
    } catch (error) {
      await rmdir(created).catch(() => undefined);
      throw error;
    }
  }
  let createdRoot: string | undefined;
  try {
    let existing = await lstat(path).catch(nullIfMissingFileError);
    if (existing !== null && existingOutput === "archive") {
      const archiveDir = await planOutputArchive(path);
      if (archiveDir !== null) {
        await rename(path, archiveDir);
        notify(() => onOutputArchived?.(archiveDir));
        existing = null;
      }
    }
    if (existing === null) {
      createdRoot =
        process.platform === "win32"
          ? await createWindowsOutputDirectory(path, true)
          : await mkdir(path, { recursive: true, mode: 0o700 });
      if ((process.umask() & 0o700) !== 0) await chmod(path, 0o700);
    }
    return await validatePreparedOutputDir(
      path,
      validateLocation,
      existingOutput === "preserve",
    );
  } catch (error) {
    if (createdRoot !== undefined) {
      await removeEmptyDirectories(path, createdRoot);
    }
    if (error instanceof OutputDirectoryError) throw error;
    throw new OutputDirectoryError(
      `Unable to create scan output directory: ${path}`,
      {
        cause: error,
      },
    );
  }
}

export async function createWindowsOutputDirectory(
  path: string,
  recursive: boolean,
): Promise<string | undefined> {
  const native = createRequire(import.meta.url)(
    join(
      await bundledPluginRoot(),
      "mcp",
      "native",
      `win32-${process.arch}`,
      "windows.node",
    ),
  ) as { createPrivateWindowsDirectory(path: Buffer): number };
  const create = async (target: string): Promise<string | undefined> => {
    const createOne = () =>
      native.createPrivateWindowsDirectory(
        Buffer.from(win32.toNamespacedPath(target), "utf16le"),
      );
    let error = createOne();
    let firstCreated: string | undefined;
    if (
      recursive &&
      (error === 2 || error === 3) &&
      dirname(target) !== target
    ) {
      firstCreated = await create(dirname(target));
      error = createOne();
    }
    if (error === 0) return firstCreated ?? target;
    if (recursive && error === 183 && (await stat(target)).isDirectory())
      return firstCreated;
    throw new OutputDirectoryError(
      `Unable to create private Windows output directory (Windows error ${error}): ${target}`,
    );
  };
  return create(path);
}

export async function validatePreparedOutputDir(
  path: string,
  validateLocation?: (path: string) => void,
  allowNonempty = false,
): Promise<string> {
  const metadata = await lstat(path);
  if (!metadata.isDirectory()) {
    throw new OutputDirectoryError(`Scan output is not a directory: ${path}`);
  }
  const canonical = await realpath(path);
  requireModelSafeOutputDir(canonical);
  validateLocation?.(canonical);
  const entries = await readdir(canonical);
  if (!allowNonempty && entries.length !== 0) {
    throw new OutputDirectoryError(
      `Scan output directory must be empty: ${path}`,
    );
  }
  requireOutputDirectoryOwnership(metadata, path);
  await requireSecureOutputAncestry(canonical);
  return canonical;
}

export function requirePrivateOutputDirectory(
  metadata: Pick<Stats, "mode" | "uid">,
  path: string,
  effectiveUid = process.geteuid?.(),
): void {
  if (process.platform === "win32") return;
  if ((metadata.mode & 0o077) !== 0) {
    throw new OutputDirectoryError(
      `Scan output directory must not be accessible to other users (chmod 700): ${path}`,
    );
  }
  requireOutputDirectoryOwnership(metadata, path, effectiveUid);
}

export function requireOutputDirectoryOwnership(
  metadata: Pick<Stats, "uid">,
  path: string,
  effectiveUid = process.geteuid?.(),
): void {
  if (process.platform === "win32") return;
  if (effectiveUid !== undefined && metadata.uid !== effectiveUid) {
    throw new OutputDirectoryError(
      `Scan output directory must be owned by the current user: ${path}`,
    );
  }
}

/** Reject shared parents whose owner can rename or replace scan output. */
export async function requireSecureOutputAncestry(
  path: string,
  effectiveUid = process.geteuid?.(),
): Promise<void> {
  if (process.platform === "win32") return;
  let current = dirname(resolve(path));
  while (true) {
    try {
      current = await realpath(current);
      break;
    } catch (error) {
      if (nodeErrorCode(error) !== "ENOENT") {
        throw new OutputDirectoryError(
          `Unable to inspect scan output parent directory: ${current}`,
          { cause: error },
        );
      }
      const parent = dirname(current);
      if (parent === current) {
        throw new OutputDirectoryError(
          `Unable to inspect scan output parent directory: ${current}`,
          { cause: error },
        );
      }
      current = parent;
    }
  }
  while (true) {
    let metadata: Stats;
    try {
      metadata = await lstat(current);
    } catch (error) {
      throw new OutputDirectoryError(
        `Unable to inspect scan output parent directory: ${current}`,
        { cause: error },
      );
    }
    if (!metadata.isDirectory()) {
      throw new OutputDirectoryError(
        `Scan output parent must be a non-symlink directory: ${current}`,
      );
    }
    requireTrustedOutputAncestor(metadata, current, effectiveUid);
    const parent = dirname(current);
    if (parent === current) return;
    current = parent;
  }
}

export function requireTrustedOutputAncestor(
  metadata: Pick<Stats, "mode" | "uid">,
  path: string,
  effectiveUid = process.geteuid?.(),
): void {
  if (
    effectiveUid !== undefined &&
    metadata.uid !== 0 &&
    metadata.uid !== effectiveUid
  ) {
    throw new OutputDirectoryError(
      `Scan output parent must have a trusted owner: ${path}`,
    );
  }
  if ((metadata.mode & 0o022) === 0) return;
  if ((metadata.mode & 0o1000) === 0) {
    throw new OutputDirectoryError(
      `Scan output parent must not be group- or world-writable without the sticky bit: ${path}`,
    );
  }
}

async function removeEmptyDirectories(
  path: string,
  root: string,
): Promise<void> {
  let current = path;
  while (true) {
    try {
      await rmdir(current);
    } catch {
      return;
    }
    if (current === root) return;
    current = dirname(current);
  }
}

export async function createIsolatedHome(
  temporaryRoot: string = tmpdir(),
  validateLocation?: (path: string) => void,
): Promise<string> {
  const path = await mkdtemp(
    join(temporaryRoot, "openai-codex-security-home-"),
  );
  try {
    if ((process.umask() & 0o700) !== 0) await chmod(path, 0o700);
    return await validatePreparedOutputDir(path, validateLocation);
  } catch (error) {
    await rmdir(path).catch(() => undefined);
    throw error;
  }
}

export async function importAmbientAuth(
  ambientHome: string,
  isolatedHome: string,
): Promise<boolean> {
  const source = join(expandHome(ambientHome), "auth.json");
  let metadata;
  try {
    metadata = await stat(source);
  } catch (error) {
    if (nodeErrorCode(error) === "ENOENT") return false;
    throw new PluginBootstrapError(
      `Unable to inspect ambient Codex authentication: ${source}`,
      {
        cause: error,
      },
    );
  }
  if (!metadata.isFile()) {
    return false;
  }
  await mkdir(isolatedHome, { recursive: true, mode: 0o700 });
  if (process.platform !== "win32" && (process.umask() & 0o700) !== 0) {
    await chmod(isolatedHome, 0o700);
  }
  if (await codexSecurityHasStoredFileCredentials(isolatedHome)) return true;
  const destination = join(isolatedHome, "auth.json");
  const temporary = join(isolatedHome, `.auth-${randomUUID()}.tmp`);
  try {
    await copyFile(source, temporary, constants.COPYFILE_EXCL);
    await chmod(temporary, 0o600);
    try {
      try {
        await link(temporary, destination);
      } catch (error) {
        if (
          !["EPERM", "ENOTSUP", "EOPNOTSUPP", "EXDEV", "EMLINK"].includes(
            nodeErrorCode(error) ?? "",
          )
        ) {
          throw error;
        }
        await copyFile(temporary, destination, constants.COPYFILE_EXCL);
      }
    } catch (error) {
      if (
        nodeErrorCode(error) === "EEXIST" &&
        (await codexSecurityHasStoredFileCredentials(isolatedHome))
      ) {
        return true;
      }
      throw error;
    }
    await chmod(destination, 0o600);
    return true;
  } catch (error) {
    throw new PluginBootstrapError(
      "Unable to copy ambient Codex authentication.",
      {
        cause: error,
      },
    );
  } finally {
    await rm(temporary, { force: true }).catch(() => undefined);
  }
}

export async function extractPluginZip(
  archive: string,
  destination: string,
  signal?: AbortSignal,
): Promise<string> {
  const archivePath = resolve(expandHome(archive));
  await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
  const staging = await realpath(
    await mkdtemp(join(dirname(destination), ".codex-security-plugin-")),
  );
  try {
    throwIfSignalAborted(signal);
    let expandedSize = 0;
    const paths = new Set<string>();
    const checksums: Array<{ path: string; checksum: number }> = [];
    const zip = await openPluginZip(archivePath, signal);
    try {
      for await (const entry of zip.eachEntry()) {
        throwIfSignalAborted(signal);
        if (zip.entryCount > MAX_ZIP_ENTRIES) {
          throw new PluginBootstrapError(
            `Plugin ZIP contains too many entries: ${zip.entryCount}.`,
          );
        }
        if (entry.fileName.startsWith("__MACOSX/")) continue;
        const path = safeArchivePath(entry.fileName);
        const collisionKey = path.toLowerCase();
        if (paths.has(collisionKey)) {
          throw new PluginBootstrapError(
            `Plugin ZIP contains a duplicate path: ${entry.fileName}`,
          );
        }
        paths.add(collisionKey);
        if (((entry.externalFileAttributes >>> 16) & 0o170000) === 0o120000) {
          throw new PluginBootstrapError(
            `Plugin ZIP contains an unsafe path: ${entry.fileName}`,
          );
        }
        if (entry.uncompressedSize > MAX_ZIP_ENTRY_SIZE) {
          throw new PluginBootstrapError(
            `Plugin ZIP entry exceeds the safety limit: ${entry.fileName}`,
          );
        }
        expandedSize += entry.uncompressedSize;
        if (expandedSize > MAX_ZIP_EXPANDED_SIZE) {
          throw new PluginBootstrapError(
            "Plugin ZIP expanded size exceeds the safety limit.",
          );
        }
        const mode = (entry.externalFileAttributes >>> 16) & 0o170000;
        const directory =
          entry.fileName.endsWith("/") ||
          mode === 0o040000 ||
          (entry.versionMadeBy >>> 8 === 0 &&
            entry.externalFileAttributes === 16);
        const output = join(staging, ...path.split("/"));
        const entryMode = (entry.externalFileAttributes >>> 16) & 0xffff;
        const permissions = (entryMode || (directory ? 0o700 : 0o600)) & 0o777;
        await mkdir(directory ? output : dirname(output), {
          recursive: true,
          ...(directory ? { mode: permissions } : {}),
        });
        if (directory) continue;
        const stream = await zip.openReadStreamPromise(entry);
        await pipeline(
          stream,
          createWriteStream(output, { mode: permissions, flags: "wx" }),
          { signal },
        );
        checksums.push({ path, checksum: entry.crc32 >>> 0 });
      }
    } finally {
      zip.close();
    }
    for (const { path, checksum } of checksums) {
      throwIfSignalAborted(signal);
      const bytes = await readFile(join(staging, ...path.split("/")));
      if (crc32(bytes) !== checksum) {
        throw new PluginBootstrapError(
          `Plugin ZIP entry failed CRC-32 validation: ${path}`,
        );
      }
    }
    const pluginRoot = await discoverPluginRoot(staging);
    throwIfSignalAborted(signal);
    const relativeRoot = relative(staging, pluginRoot);
    await rename(staging, destination);
    return await validatePluginRoot(join(destination, relativeRoot));
  } catch (error) {
    await rm(staging, { recursive: true, force: true }).catch(() => undefined);
    throwIfSignalAborted(signal);
    if (error instanceof PluginBootstrapError) throw error;
    throw new PluginBootstrapError(`Invalid plugin ZIP: ${archivePath}`, {
      cause: error,
    });
  }
}

async function openPluginZip(
  path: string,
  signal?: AbortSignal,
): Promise<ZipFile> {
  const fd = await promisify(openCallback)(
    path,
    constants.O_RDONLY |
      (process.platform === "win32" ? 0 : constants.O_NONBLOCK),
  );
  try {
    const metadata = await promisify(fstatCallback)(fd);
    if (!metadata.isFile() || metadata.size < 22) {
      throw new Error("missing end of central directory");
    }
    const tailSize = Math.min(metadata.size, 65_557);
    const tail = await readExactly(
      fd,
      tailSize,
      metadata.size - tailSize,
      signal,
    );
    let end = tail.byteLength - 22;
    while (
      end >= 0 &&
      (tail.readUInt32LE(end) !== 0x06054b50 ||
        end + 22 + tail.readUInt16LE(end + 20) !== tail.byteLength)
    ) {
      end -= 1;
    }
    if (end < 0) throw new Error("missing end of central directory");
    const entries = tail.readUInt16LE(end + 10);
    const centralSize = tail.readUInt32LE(end + 12);
    const centralOffset = tail.readUInt32LE(end + 16);
    if (
      entries === 0xffff ||
      centralSize === 0xffffffff ||
      centralOffset === 0xffffffff
    ) {
      throw new Error("unsupported ZIP64 archive");
    }
    if (entries > MAX_ZIP_ENTRIES) {
      throw new PluginBootstrapError(
        `Plugin ZIP contains too many entries: ${entries}.`,
      );
    }
    if (centralSize > MAX_ZIP_CENTRAL_DIRECTORY) {
      throw new PluginBootstrapError(
        "Plugin ZIP central directory exceeds the safety limit.",
      );
    }
    const endOffset = metadata.size - tailSize + end;
    if (centralOffset + centralSize > endOffset) {
      throw new Error("invalid central directory bounds");
    }
    const central = await readExactly(fd, centralSize, centralOffset, signal);
    let offset = 0;
    for (let index = 0; index < entries; index += 1) {
      if (
        offset + 46 > central.byteLength ||
        central.readUInt32LE(offset) !== 0x02014b50
      ) {
        throw new Error("invalid central directory");
      }
      const nameLength = central.readUInt16LE(offset + 28);
      const extraLength = central.readUInt16LE(offset + 30);
      const commentLength = central.readUInt16LE(offset + 32);
      const nameStart = offset + 46;
      const nameEnd = nameStart + nameLength;
      if (nameEnd > central.byteLength) {
        throw new Error("invalid central directory name");
      }
      if (central.subarray(nameStart, nameEnd).includes(0x5c)) {
        throw new PluginBootstrapError(
          "Plugin ZIP contains a backslash-qualified path.",
        );
      }
      offset = nameEnd + extraLength + commentLength;
    }
    if (offset !== central.byteLength) {
      throw new Error("invalid central directory size");
    }
    // Yauzl owns the descriptor only after construction succeeds.
    return await fromFdPromise(fd, {
      autoClose: true,
      strictFileNames: true,
    });
  } catch (error) {
    await promisify(closeCallback)(fd);
    throw error;
  }
}

export async function resolvePluginPath(
  pluginPath: string | undefined,
  workspace: string,
  signal?: AbortSignal,
): Promise<string> {
  try {
    if (pluginPath === undefined) {
      return await bundledPluginRoot();
    }

    const path = resolve(expandHome(pluginPath));
    const metadata = await lstat(path).catch(() => null);
    if (metadata?.isFile() && extname(path).toLowerCase() === ".zip") {
      return await extractPluginZip(
        path,
        join(workspace, "extracted-plugin"),
        signal,
      );
    }
    if (metadata?.isDirectory()) {
      throwIfSignalAborted(signal);
      return await validatePluginRoot(path);
    }
    throw new PluginBootstrapError(
      `Plugin path must be a directory or ZIP: ${path}`,
    );
  } catch (error) {
    if (signal?.aborted || error instanceof LocalPluginBootstrapError)
      throw error;
    throw new LocalPluginBootstrapError(errorMessage(error), { cause: error });
  }
}

export async function createMarketplace(
  codexHome: string,
  pluginRoot: string,
  signal?: AbortSignal,
): Promise<string> {
  try {
    throwIfSignalAborted(signal);
    const root = await realpath(pluginRoot);
    const marketplace = join(codexHome, "sdk-marketplace");
    const pluginDestination = join(marketplace, "plugins", PLUGIN_NAME);
    await copyPluginTree(root, pluginDestination, signal);
    const projection = await pluginRuntimeProjection(pluginDestination, signal);
    for (const [path, file] of projection?.files ?? []) {
      const destination = join(pluginDestination, path);
      await mkdir(dirname(destination), { recursive: true });
      await writeFile(destination, file.contents, { mode: file.mode, signal });
      if (file.mode !== undefined) await chmod(destination, file.mode);
    }
    await writeMarketplaceManifest(marketplace, signal);
    return marketplace;
  } catch (error) {
    if (signal?.aborted || error instanceof LocalPluginBootstrapError)
      throw error;
    throw new LocalPluginBootstrapError(errorMessage(error), { cause: error });
  }
}

async function writeMarketplaceManifest(
  marketplace: string,
  signal?: AbortSignal,
): Promise<void> {
  throwIfSignalAborted(signal);
  const manifestPath = join(
    marketplace,
    ".agents",
    "plugins",
    "marketplace.json",
  );
  await mkdir(dirname(manifestPath), { recursive: true, mode: 0o700 });
  const temporary = `${manifestPath}.${randomUUID()}.tmp`;
  try {
    await writeFile(temporary, MARKETPLACE_MANIFEST, {
      encoding: "utf8",
      flag: "wx",
      mode: 0o600,
      signal,
    });
    throwIfSignalAborted(signal);
    try {
      await rename(temporary, manifestPath);
    } catch (error) {
      // Concurrent replacement can fail on Windows after another repair wins.
      const published = await readFile(manifestPath, "utf8").catch(() => null);
      if (published !== MARKETPLACE_MANIFEST) throw error;
    }
    throwIfSignalAborted(signal);
  } finally {
    await rm(temporary, { force: true });
  }
}

type PluginRuntimeProjection = {
  root: string;
  files: Map<string, { contents: Buffer; mode?: number }>;
};

async function pluginRuntimeProjection(
  root: string,
  signal?: AbortSignal,
): Promise<PluginRuntimeProjection | undefined> {
  const path = join(root, ".mcp.json");
  // Keep the source link checks ahead of any configuration read.
  if (!(await lstat(path).catch(nullIfMissingFileError))?.isFile()) return;
  const configuration: unknown = JSON.parse(
    await readFile(path, { encoding: "utf8", signal }),
  );
  const servers = isRecord(configuration)
    ? configuration["mcpServers"]
    : undefined;
  const server = isRecord(servers) ? servers[PLUGIN_NAME] : undefined;
  if (
    !isRecord(server) ||
    (server["command"] !== "./scripts/launch_codex_security_mcp" &&
      server["command"] !== "./scripts/launch_codex_security_mcp.cmd")
  ) {
    return;
  }
  const environment = server["env_vars"];
  if (environment !== undefined && !Array.isArray(environment)) return;
  if (
    !Array.isArray(environment) ||
    !environment.includes("CODEX_SECURITY_PLUGIN_ROOT")
  ) {
    server["env_vars"] = [
      ...(Array.isArray(environment) ? environment : []),
      "CODEX_SECURITY_PLUGIN_ROOT",
    ];
  }
  const files: PluginRuntimeProjection["files"] = new Map();
  server["command"] =
    server["command"] === "./scripts/launch_codex_security_mcp.cmd"
      ? "./scripts/launch_codex_security_mcp_sdk.cmd"
      : "./scripts/launch_codex_security_mcp_sdk";
  files.set("scripts/launch_codex_security_mcp_sdk", {
    contents: Buffer.from(
      "#!/bin/sh\n" +
        'if [ -n "${CODEX_SECURITY_PLUGIN_ROOT:-}" ]; then\n' +
        '  exec "$CODEX_SECURITY_PLUGIN_ROOT/scripts/launch_codex_security_mcp" "$@"\n' +
        "fi\n" +
        'exec "$(dirname "$0")/launch_codex_security_mcp" "$@"\n',
    ),
    mode: 0o755,
  });
  files.set("scripts/launch_codex_security_mcp_sdk.cmd", {
    contents: Buffer.from(
      "@echo off\r\nsetlocal DisableDelayedExpansion\r\n" +
        "if not defined CODEX_SECURITY_PLUGIN_ROOT goto codex_security_sdk_original\r\n" +
        '"%CODEX_SECURITY_PLUGIN_ROOT%\\scripts\\launch_codex_security_mcp.cmd" %*\r\n' +
        "exit /b\r\n:codex_security_sdk_original\r\n" +
        '"%~dp0launch_codex_security_mcp.cmd" %*\r\n',
    ),
    mode: 0o755,
  });
  files.set(".mcp.json", {
    contents: Buffer.from(`${JSON.stringify(configuration, null, 2)}\n`),
  });
  return { root, files };
}

export function resolveCodexCommand(
  environment: ProcessEnvironment = process.env,
): CodexCommand {
  const configured = environmentValue(environment, "CODEX_CLI_PATH");
  const expanded =
    configured === undefined
      ? undefined
      : expandExecutableHome(configured, environment);
  if (
    expanded &&
    (process.platform !== "win32" || /\.(?:exe|com)$/iu.test(expanded))
  ) {
    return {
      command:
        process.platform === "win32"
          ? resolve(expanded)
          : isAbsolute(expanded)
            ? expanded
            : `${process.cwd()}${sep}${expanded}`,
    };
  }

  return { command: resolveBundledCodexExecutable() };
}

export async function codexExecutableReadPaths(
  command: string,
): Promise<string[]> {
  const executable = await realpath(command);
  const packageJson = resolve(dirname(executable), "..", "package.json");
  try {
    const metadata = JSON.parse(await readFile(packageJson, "utf8"));
    if (
      metadata?.name !== "@openai/codex" ||
      typeof metadata.bin?.codex !== "string"
    )
      return [executable];
    const launcher = await realpath(
      resolve(dirname(packageJson), metadata.bin.codex),
    );
    if (launcher !== executable) return [executable];
  } catch {
    // A custom executable need not belong to a readable, valid npm package.
    return [executable];
  }

  // npm's entrypoint launches a native binary, which Linux re-executes in the sandbox.
  return [
    executable,
    await realpath(resolveBundledCodexExecutable(packageJson)),
  ];
}

export async function bootstrapPlugin(
  codexHome: string,
  pluginRoot: string,
  options: {
    codexCommand?: CodexCommand;
    runCodex?: (
      command: CodexCommand,
      args: readonly string[],
      environment: ProcessEnvironment,
      signal?: AbortSignal,
    ) => Promise<string>;
    environment?: ProcessEnvironment;
    signal?: AbortSignal;
  } = {},
): Promise<PluginInstall> {
  const root = await realpath(pluginRoot);
  const { name, version } = await pluginMetadata(root);
  const projection = await pluginRuntimeProjection(root, options.signal).catch(
    (error: unknown) => {
      if (options.signal?.aborted) throw error;
      throw new LocalPluginBootstrapError(errorMessage(error), {
        cause: error,
      });
    },
  );
  const marketplace = join(codexHome, "sdk-marketplace");
  throwIfSignalAborted(options.signal);
  const command =
    options.codexCommand ?? resolveCodexCommand(options.environment);
  const environment = {
    ...(options.environment ?? process.env),
    CODEX_HOME: codexHome,
  };
  const run = options.runCodex ?? runPluginCommand;
  const existing = await lstat(marketplace).catch(nullIfMissingFileError);
  if (existing !== null && !existing.isDirectory()) {
    throw new LocalPluginBootstrapError(
      `Codex Security plugin marketplace path must be a directory: ${marketplace}`,
    );
  }

  const staged =
    existing === null
      ? null
      : await pluginMetadata(join(marketplace, "plugins", PLUGIN_NAME)).catch(
          () => null,
        );
  const stagedRoot = join(marketplace, "plugins", PLUGIN_NAME);
  const stagedMatches =
    staged?.version === version &&
    (await pluginContentsMatch(
      root,
      stagedRoot,
      options.signal,
      false,
      projection,
    ));

  if (!stagedMatches) {
    if (existing !== null) {
      await rm(marketplace, { recursive: true, force: true });
    }
    await createMarketplace(codexHome, root, options.signal);
  } else if (
    (await readFile(
      join(marketplace, ".agents", "plugins", "marketplace.json"),
      "utf8",
    ).catch(nullIfMissingFileError)) !== MARKETPLACE_MANIFEST
  ) {
    await writeMarketplaceManifest(marketplace, options.signal);
  }

  const config = await readFile(join(codexHome, "config.toml"), "utf8").catch(
    (error: unknown) => {
      if (nodeErrorCode(error) === "ENOENT") return "";
      throw error;
    },
  );
  const configuration = parse(config);
  const marketplaces = configuration["marketplaces"];
  const registration = isRecord(marketplaces)
    ? marketplaces[MARKETPLACE_NAME]
    : undefined;

  const registered =
    isRecord(registration) &&
    registration["source_type"] === "local" &&
    typeof registration["source"] === "string" &&
    (await sameFile(registration["source"], marketplace));

  if (!registered) {
    await run(
      command,
      ["plugin", "marketplace", "add", marketplace],
      environment,
      options.signal,
    );
  }

  const installRecord = join(marketplace, "installed-plugin.json");
  const previous: unknown = await readFile(installRecord, "utf8")
    .then((value) => JSON.parse(value) as unknown)
    .catch((error: unknown) => {
      if (nodeErrorCode(error) === "ENOENT" || error instanceof SyntaxError) {
        return null;
      }
      throw error;
    });

  const plugins = configuration["plugins"];
  const plugin = isRecord(plugins)
    ? plugins[`${PLUGIN_NAME}@${MARKETPLACE_NAME}`]
    : undefined;

  // Codex replaces the shared install even at the same version. Reuse it so
  // workers from an earlier scan can keep using their plugin files.
  if (
    stagedMatches &&
    registered &&
    isRecord(plugin) &&
    plugin["enabled"] === true &&
    isRecord(previous) &&
    typeof previous["installedPath"] === "string" &&
    previous["version"] === version &&
    (await pluginContentsMatch(
      root,
      previous["installedPath"],
      options.signal,
      true,
      projection,
    ))
  ) {
    return {
      pluginRoot: root,
      marketplaceRoot: marketplace,
      installedRoot: previous["installedPath"],
      marketplaceName: MARKETPLACE_NAME,
      name,
      version,
    };
  }

  const output = await run(
    command,
    ["plugin", "add", "--json", `${PLUGIN_NAME}@${MARKETPLACE_NAME}`],
    environment,
    options.signal,
  );

  let installed: unknown;
  try {
    installed = JSON.parse(output);
  } catch (error) {
    throw new PluginBootstrapError(
      "Codex plugin install did not return a valid JSON result.",
      { cause: error },
    );
  }

  if (
    !isRecord(installed) ||
    typeof installed["installedPath"] !== "string" ||
    installed["version"] !== version
  ) {
    throw new PluginBootstrapError(
      "Codex plugin install did not return the selected plugin path and version.",
    );
  }

  await writeFile(
    installRecord,
    JSON.stringify({
      installedPath: installed["installedPath"],
      version,
    }),
    { mode: 0o600, signal: options.signal },
  );

  return {
    pluginRoot: root,
    marketplaceRoot: marketplace,
    installedRoot: installed["installedPath"],
    marketplaceName: MARKETPLACE_NAME,
    name,
    version,
  };
}

async function pluginContentsMatch(
  source: string,
  destination: string,
  signal?: AbortSignal,
  allowExtraFiles = false,
  projection?: PluginRuntimeProjection,
): Promise<boolean> {
  throwIfSignalAborted(signal);

  const sourceMetadata = await lstat(source);
  const destinationMetadata = await lstat(destination).catch(
    (error: unknown) => {
      if (["ENOENT", "ENOTDIR"].includes(nodeErrorCode(error) ?? "")) {
        return null;
      }
      throw error;
    },
  );

  if (destinationMetadata === null) return false;

  if (sourceMetadata.isFile() && destinationMetadata.isFile()) {
    const projected = projection?.files.get(
      relative(projection.root, source).split(sep).join("/"),
    );
    if (
      (projected === undefined &&
        sourceMetadata.size !== destinationMetadata.size) ||
      ((projected?.mode === undefined || process.platform !== "win32") &&
        ((projected?.mode ?? sourceMetadata.mode) & 0o111) !==
          (destinationMetadata.mode & 0o111))
    ) {
      return false;
    }
    const [sourceBytes, destinationBytes] = await Promise.all([
      readFile(source, { signal }),
      readFile(destination, { signal }),
    ]);
    return (projected?.contents ?? sourceBytes).equals(destinationBytes);
  }

  if (!sourceMetadata.isDirectory() || !destinationMetadata.isDirectory()) {
    return false;
  }

  const entries = await readdir(source);
  const projectedDirectory =
    projection === undefined
      ? undefined
      : relative(projection.root, source).split(sep).join("/") || ".";
  const generated = [...(projection?.files ?? [])].filter(
    ([path]) =>
      dirname(path) === projectedDirectory && !entries.includes(basename(path)),
  );
  if (
    !allowExtraFiles &&
    entries.length + generated.length !== (await readdir(destination)).length
  ) {
    return false;
  }
  for (const [path, file] of generated) {
    const generatedPath = join(destination, basename(path));
    const metadata = await lstat(generatedPath).catch(nullIfMissingFileError);
    if (
      !metadata?.isFile() ||
      (process.platform !== "win32" &&
        (metadata.mode & 0o111) !== ((file.mode ?? 0o644) & 0o111)) ||
      !file.contents.equals(await readFile(generatedPath, { signal }))
    ) {
      return false;
    }
  }

  for (const entry of entries) {
    if (
      !(await pluginContentsMatch(
        join(source, entry),
        join(destination, entry),
        signal,
        allowExtraFiles,
        projection,
      ))
    ) {
      return false;
    }
  }

  return true;
}

export async function pluginMetadata(
  root: string,
): Promise<{ name: typeof PLUGIN_NAME; version: string }> {
  const manifestPath = join(root, ".codex-plugin", "plugin.json");
  let manifest: unknown;
  try {
    if (!(await lstat(manifestPath)).isFile()) {
      throw new Error("plugin manifest is not a regular file");
    }
    manifest = JSON.parse(await readFile(manifestPath, "utf8"));
  } catch (error) {
    throw new LocalPluginBootstrapError(
      `Invalid Codex plugin directory: ${root}`,
      {
        cause: error,
      },
    );
  }
  if (!isRecord(manifest) || manifest["name"] !== PLUGIN_NAME) {
    throw new LocalPluginBootstrapError(
      "Plugin manifest must have name 'codex-security'.",
    );
  }
  const version = manifest["version"];
  if (typeof version !== "string" || version.trim().length === 0) {
    throw new LocalPluginBootstrapError(
      "Plugin manifest must have a non-empty version.",
    );
  }
  return { name: PLUGIN_NAME, version };
}

export async function resolvePluginPython(
  options: PluginPythonOptions = {},
): Promise<string> {
  const environment = options.environment ?? process.env;
  const requestedRoots = options.protectedRoot ?? process.cwd();
  const protectedRoot =
    typeof requestedRoots === "string" ? [requestedRoots] : [...requestedRoots];
  const callerDirectories = [
    process.cwd(),
    options.currentDirectory ?? process.cwd(),
  ];
  // Preserve target and enclosing-checkout protection for every interpreter.
  for (const directory of new Set([...callerDirectories, ...protectedRoot])) {
    for (const checkout of await gitProtectionRoots(directory, options.signal))
      if (!protectedRoot.includes(checkout)) protectedRoot.push(checkout);
  }
  // Named interpreters are ambient PATH discovery, even when PYTHON names one.
  // Explicit trusted paths and managed runtimes retain their existing precedence.
  const discoveryRoots = [...protectedRoot, ...callerDirectories];
  if (options.configuredPath !== undefined) {
    return await requirePython(
      options.configuredPath,
      "configured plugin Python",
      environment,
      isPythonPathCandidate(options.configuredPath)
        ? protectedRoot
        : discoveryRoots,
      options.signal,
    );
  }
  const inherited = environmentValue(environment, "PYTHON");
  if (inherited) {
    return await requirePython(
      inherited,
      "PYTHON",
      environment,
      isPythonPathCandidate(inherited) ? protectedRoot : discoveryRoots,
      options.signal,
    );
  }

  const home = options.homeDirectory ?? homedir();
  const cacheDirectory =
    environmentValue(environment, "XDG_CACHE_HOME", true) ||
    join(home, ".cache");
  const managedRoots = options.managedRuntimeRoots ?? [
    join(cacheDirectory, "codex-runtimes", "codex-primary-runtime"),
  ];
  const relativeCandidates =
    process.platform === "win32"
      ? [
          join("dependencies", "python", "python.exe"),
          join("dependencies", "python", "python", "python.exe"),
          join("dependencies", "python", "bin", "python.exe"),
        ]
      : [
          join("dependencies", "python", "bin", "python3"),
          join("dependencies", "python", "bin", "python"),
        ];
  for (const root of managedRoots) {
    for (const relativeCandidate of relativeCandidates) {
      const candidate = join(root, relativeCandidate);
      const resolved = await usablePython(
        candidate,
        environment,
        protectedRoot,
        options.signal,
      );
      if (resolved !== null) return resolved;
    }
  }

  for (const candidate of process.platform === "win32"
    ? ["python", "python3", "py"]
    : ["python3", "python"]) {
    const resolved = await usablePython(
      candidate,
      environment,
      discoveryRoots,
      options.signal,
    );
    if (resolved !== null) return resolved;
  }
  throw new PluginPythonUnavailableError(
    "The bundled Codex Security plugin requires Python 3.10 or later (Python 3.10 also requires tomli), but no usable interpreter was found. " +
      "Set pythonPath, --python, or PYTHON, install the Codex managed runtime, or add python3/python (py on Windows) to PATH.",
  );
}

export function pluginExecutionEnvironment(
  python: string,
  environment: ProcessEnvironment = process.env,
): ProcessEnvironment {
  const child = {
    ...pythonUtf8Environment(environment),
    PYTHON: python,
    CODEX_SECURITY_PYTHON_COMMAND: python,
    CODEX_CLI_PATH: resolveCodexCommand(environment).command,
  };
  forwardExternalImportSetting(environment, child);
  return child;
}

export function environmentWithGit(
  environment: ProcessEnvironment,
  git?: InspectedExecutable,
): ProcessEnvironment {
  if (git === undefined) return environment;
  const result = { ...environment };
  for (const name of Object.keys(result)) {
    const normalized = name.toUpperCase();
    if (normalized === "CODEX_SECURITY_GIT" || normalized === "PATH") {
      delete result[name];
    }
  }
  result["CODEX_SECURITY_GIT"] = git.executable ?? "";
  result["PATH"] = git.environment["PATH"] ?? "";
  return result;
}

export function pythonUtf8Environment(
  environment: ProcessEnvironment,
): ProcessEnvironment {
  const normalized = { ...environment };
  for (const name of Object.keys(normalized)) {
    if (name.toUpperCase() === "PYTHONUTF8") delete normalized[name];
  }
  normalized["PYTHONUTF8"] = "1";
  return normalized;
}

function pluginHelperEnvironment(
  environment: ProcessEnvironment,
): ProcessEnvironment {
  return pythonUtf8Environment(
    Object.fromEntries(
      Object.entries(environment).filter(
        ([name]) =>
          !PLUGIN_HELPER_SECRET_ENVIRONMENT_VARIABLES.has(name.toUpperCase()),
      ),
    ),
  );
}

export async function cleanupSdkDirectory(path: string): Promise<void> {
  await rm(path, { recursive: true, force: true });
}

export async function runCodexCommand(
  command: CodexCommand,
  args: readonly string[],
  environment: ProcessEnvironment,
  input?: string | Uint8Array,
  signal?: AbortSignal,
  archiveHandshake = false,
  stdinPrefix?: string,
): Promise<CodexCommandResult> {
  const cancellation = archiveHandshake ? new AbortController() : undefined;
  const abort = () => cancellation?.abort(signal?.reason);
  const commandSignal = cancellation?.signal ?? signal;
  let awaitingArchive = archiveHandshake;
  const child = spawn(
    executablePathForSpawn(command.command),
    [...(command.args ?? []), ...args],
    {
      env: environment,
      stdio: ["pipe", "pipe", "pipe"],
      windowsHide: true,
      signal: commandSignal,
    },
  );
  let stdout = "";
  let stderr = "";
  let processError: Error | undefined;
  child.stdout.setEncoding("utf8");
  child.stderr.setEncoding("utf8");
  child.stdout.on("data", (chunk: string) => {
    stdout += chunk;
    if (awaitingArchive && stdout.startsWith(ARCHIVE_READY)) {
      awaitingArchive = false;
      stdout = stdout.slice(ARCHIVE_READY.length);
      signal?.removeEventListener("abort", abort);
      // The helper cannot rename until this acknowledgement. Detach and check
      // cancellation before allowing the filesystem/database transaction.
      if (signal?.aborted) abort();
      else child.stdin.end("\n");
    }
  });
  child.stderr.on("data", (chunk: string) => {
    stderr += chunk;
  });
  const completion = new Promise<CodexCommandResult>((resolve, reject) => {
    child.once("error", (error) => {
      processError = error;
    });
    child.stdin.on("error", (error: NodeJS.ErrnoException) => {
      if (
        !["EPIPE", "ECONNRESET", "EOF", "ERR_STREAM_DESTROYED"].includes(
          error.code ?? "",
        )
      )
        processError = error;
    });
    child.once("close", (exitCode) =>
      processError === undefined
        ? resolve({ success: exitCode === 0, exitCode, stdout, stderr })
        : reject(processError),
    );
  });
  const releaseCanceledPipes = () => {
    if (!commandSignal?.aborted) return;
    if (child.exitCode === null && child.signalCode === null) return;
    child.stdin.destroy();
    child.stdout.destroy();
    child.stderr.destroy();
  };
  commandSignal?.addEventListener("abort", releaseCanceledPipes, {
    once: true,
  });
  child.once("exit", releaseCanceledPipes);
  if (archiveHandshake) {
    signal?.addEventListener("abort", abort, { once: true });
    if (signal?.aborted) abort();
  }
  try {
    if (stdinPrefix !== undefined) child.stdin.write(stdinPrefix);
    if (archiveHandshake) child.stdin.write(`${JSON.stringify(input ?? "")}\n`);
    else child.stdin.end(input);
    return await completion;
  } finally {
    if (archiveHandshake) signal?.removeEventListener("abort", abort);
    commandSignal?.removeEventListener("abort", releaseCanceledPipes);
    child.removeListener("exit", releaseCanceledPipes);
  }
}

export async function probeCodexSandbox(
  command: CodexCommand,
  environment: ProcessEnvironment,
  signal?: AbortSignal,
): Promise<void> {
  // This preflight covers the Unix sandbox backends.
  if (process.platform === "win32") return;
  // Reuse the resolved Codex executable instead of looking up a probe on PATH.
  const args = ["sandbox", "--", command.command, "--version"];
  const timeout = AbortSignal.timeout(SANDBOX_PROBE_TIMEOUT_MILLISECONDS);
  let detail: string;
  try {
    const result = await runCodexCommand(
      command,
      args,
      environment,
      undefined,
      signal === undefined ? timeout : AbortSignal.any([signal, timeout]),
    );
    if (result.success) return;
    detail =
      result.stderr.trim() ||
      result.stdout.trim() ||
      `Codex exited with status ${result.exitCode}.`;
  } catch (error) {
    signal?.throwIfAborted();
    detail = processErrorDetail(error);
  }
  throw new SandboxUnavailableError(
    `Codex could not run a command in its sandbox; reproduce with '${command.command} ${args.join(" ")}'. On Linux this usually means unprivileged user namespaces are restricted (kernel.apparmor_restrict_unprivileged_userns=1 on Ubuntu 24.04 and later), which Bubblewrap needs; inside the container image, use the AppArmor profile and Compose override from the SDK README. Codex reported: ${detail}`,
  );
}

async function runPluginCommand(
  command: CodexCommand,
  args: readonly string[],
  environment: ProcessEnvironment,
  signal?: AbortSignal,
): Promise<string> {
  try {
    const { success, exitCode, stdout, stderr } = await runCodexCommand(
      command,
      args,
      environment,
      undefined,
      signal,
    );
    if (!success) {
      throw new Error(
        stderr.trim() ||
          stdout.trim() ||
          `Codex exited with status ${exitCode}.`,
      );
    }
    return stdout;
  } catch (error) {
    const detail = processErrorDetail(error);
    throw new PluginBootstrapError(`Codex plugin bootstrap failed: ${detail}`, {
      cause: error,
    });
  }
}

async function discoverPluginRoot(root: string): Promise<string> {
  if (await hasPluginManifest(root)) return await validatePluginRoot(root);
  const children = (await readdir(root, { withFileTypes: true })).filter(
    (entry) => entry.isDirectory(),
  );
  if (children.length === 1) {
    const candidate = join(root, children[0]!.name);
    if (await hasPluginManifest(candidate))
      return await validatePluginRoot(candidate);
  }
  throw new PluginBootstrapError(
    "Plugin ZIP must contain Codex Security at its root or in one top-level directory.",
  );
}

async function validatePluginRoot(root: string): Promise<string> {
  await pluginMetadata(root);
  return await realpath(root);
}

async function copyPluginTree(
  source: string,
  destination: string,
  signal?: AbortSignal,
): Promise<void> {
  await mkdir(dirname(destination), { recursive: true, mode: 0o700 });
  try {
    await cp(source, destination, {
      recursive: true,
      force: false,
      filter: async (path) => {
        throwIfSignalAborted(signal);
        const metadata = await lstat(path);
        if (
          (!metadata.isDirectory() && !metadata.isFile()) ||
          (await realpath(path)) !== path
        ) {
          throw new PluginBootstrapError(
            `Plugin contains an unsafe source path: ${path}`,
          );
        }
        throwIfSignalAborted(signal);
        return true;
      },
    });
  } catch (error) {
    await rm(destination, { recursive: true, force: true });
    throw error;
  }
}

async function readExactly(
  fd: number,
  length: number,
  position: number,
  signal?: AbortSignal,
): Promise<Buffer> {
  const buffer = Buffer.alloc(length);
  let offset = 0;
  while (offset < length) {
    throwIfSignalAborted(signal);
    const { bytesRead } = await promisify(readCallback)(
      fd,
      buffer,
      offset,
      length - offset,
      position + offset,
    );
    if (bytesRead === 0) throw new Error("unexpected end of plugin file");
    offset += bytesRead;
  }
  return buffer;
}

function safeArchivePath(value: string): string {
  const parts = value.split("/");
  const normalized = parts
    .filter((part) => part !== "" && part !== ".")
    .join("/");
  if (
    value.length === 0 ||
    value.startsWith("/") ||
    value.startsWith("//") ||
    /^[A-Za-z]:/.test(value) ||
    parts.includes("..") ||
    value.includes("\\") ||
    value.includes("\0") ||
    parts.some(isWindowsUnsafePathComponent) ||
    normalized.length === 0
  ) {
    throw new PluginBootstrapError(
      `Plugin ZIP contains an unsafe path: ${value}`,
    );
  }
  return normalized;
}

async function requirePython(
  candidate: string,
  source: string,
  environment: ProcessEnvironment,
  protectedRoot: string | readonly string[],
  signal?: AbortSignal,
): Promise<string> {
  const resolved = await usablePython(
    candidate,
    environment,
    protectedRoot,
    signal,
  );
  if (resolved !== null) return resolved;
  throw new PluginPythonUnavailableError(
    `The ${source} interpreter is unavailable or unusable: ${candidate}. ` +
      "The bundled Codex Security plugin requires Python 3.10 or later for scan execution; Python 3.10 also requires tomli.",
  );
}

async function usablePython(
  candidate: string,
  environment: ProcessEnvironment = process.env,
  protectedRoot: string | readonly string[] = process.cwd(),
  signal?: AbortSignal,
): Promise<string | null> {
  const command = await resolveTrustedExecutable(
    isPythonPathCandidate(candidate)
      ? expandExecutableHome(candidate, environment)
      : candidate,
    environment,
    protectedRoot,
  );
  if (command === null) return null;
  try {
    const { stdout } = await execFile(
      command.executable,
      [
        "-I",
        "-c",
        "import importlib.util,sys\nif sys.version_info < (3, 10): raise SystemExit(1)\nif sys.version_info < (3, 11) and importlib.util.find_spec('tomli') is None: raise SystemExit(1)\nprint('codex-security-python-ok')",
      ],
      {
        env: command.environment,
        encoding: "utf8",
        // Cold Python startup can exceed five seconds on busy Windows hosts.
        timeout: 30_000,
        windowsHide: true,
        signal,
      },
    );
    return stdout.trim() === "codex-security-python-ok"
      ? command.executable
      : null;
  } catch (error) {
    if (signal?.aborted) throw error;
    return null;
  }
}

export function isPythonPathCandidate(candidate: string): boolean {
  return candidate.includes("/") || candidate.includes("\\");
}

async function hasPluginManifest(root: string): Promise<boolean> {
  return await lstat(join(root, ".codex-plugin", "plugin.json")).then(
    (metadata) => metadata.isFile(),
    () => false,
  );
}

/** @internal Compare filesystem identity without depending on path spelling. */
export function sameFile(left: string, right: string): Promise<boolean> {
  // NTFS file IDs can exceed JavaScript's safe integer range.
  return Promise.all([
    stat(left, { bigint: true }),
    stat(right, { bigint: true }),
  ]).then(
    ([leftMetadata, rightMetadata]) =>
      leftMetadata.dev === rightMetadata.dev &&
      leftMetadata.ino === rightMetadata.ino,
    () => false,
  );
}

function expandExecutableHome(
  value: string,
  environment: ProcessEnvironment,
): string {
  const path = value.startsWith("~\\") ? value.replaceAll("\\", "/") : value;
  // Expand only the home prefix; joining the suffix would collapse symlink/.. paths.
  return path.startsWith("~/")
    ? `${expandHome("~", environment)}${sep}${path.slice(2)}`
    : expandHome(path, environment);
}

export function expandHome(
  value: string,
  environment: ProcessEnvironment = process.env,
): string {
  const home =
    (process.platform === "win32"
      ? (environmentValue(environment, "USERPROFILE") ??
        environmentValue(environment, "HOME"))
      : (environmentValue(environment, "HOME") ??
        environmentValue(environment, "USERPROFILE"))) ?? homedir();
  if (value === "~") return home;
  if (value.startsWith("~/")) return join(home, value.slice(2));
  if (value.startsWith("~\\")) {
    return join(home, ...value.slice(2).split("\\"));
  }
  return value;
}

function safePrefix(value: string): string {
  return basename(value).replace(/[^A-Za-z0-9._-]/g, "-") || "repository";
}

function processErrorDetail(error: unknown): string {
  if (isRecord(error)) {
    for (const key of ["stderr", "stdout", "message"] as const) {
      const value = error[key];
      if (typeof value === "string" && value.trim()) return value.trim();
      if (value instanceof Uint8Array) {
        const decoded = new TextDecoder().decode(value).trim();
        if (decoded) return decoded;
      }
    }
  }
  return String(error) || "unknown error";
}

function nodeErrorCode(error: unknown): string | undefined {
  return isRecord(error) && typeof error["code"] === "string"
    ? error["code"]
    : undefined;
}

function throwIfSignalAborted(signal?: AbortSignal): void {
  if (signal?.aborted) throw abortReason(signal);
}

function nullIfMissingFileError(error: unknown): null {
  if (nodeErrorCode(error) === "ENOENT") return null;
  throw error;
}

/** @internal */
export function workbenchEnvironment(environment: ProcessEnvironment) {
  return {
    ...environment,
    CODEX_SECURITY_STATE_DIR: codexSecurityStateDirectory(environment),
  };
}

/** @internal */
export const resolveWorkbenchRuntime = (options: PluginPythonOptions) =>
  Promise.all([resolvePluginPython(options), bundledPluginRoot()]);