OpenAI's Codex Security CLI and TypeScript SDK for finding, validating, and fixing security vulnerabilities. npm: https://www.npmjs.com/package/@openai/codex-security
TypeScript ai-securityapplication-securityclicode-scanningcodexcodex-securitycybersecuritydevsecopsnodejsnpmopenaisdksecuritytypescriptvulnerability-scanning
import {
configuredExecutableValue,
executablePathForSpawn,
isExplicitPathWithTrailingWhitespace,
isExecutableFile,
} from "./executable-path.js";
import { retryWindowsRename } from "./retry-windows-rename.js";
export { executablePathForSpawn } from "./executable-path.js";
import { bundledPluginRoot, hasPluginManifest } from "./bundled-plugin.js";
export {
bundledPluginCandidates,
bundledPluginRoot,
} from "./bundled-plugin.js";
import {
PLUGIN_PYTHON_PROBE,
PLUGIN_PYTHON_PROBE_TIMEOUT_MS,
PLUGIN_PYTHON_READY,
} from "./plugin-python-probe.js";
import { resolveBundledCodexExecutable } from "./codex-sdk-environment.js";
import { abortable, gitProtectionRoots, resolveTargetPath } from "./targets.js";
import type { AbsolutePath } from "./config-path.js";
import { isNonEmptyString, notify } from "./value.js";
import {
execFile as execFileCallback,
spawn,
type ChildProcessWithoutNullStreams,
type SpawnOptionsWithoutStdio,
} from "node:child_process";
import { createHash, randomUUID, type Hash } from "node:crypto";
import { shortArchivePrefix } from "./scan-archive-path.js";
import {
chmodSync,
close as closeCallback,
constants,
createWriteStream,
fstat as fstatCallback,
open as openCallback,
read as readCallback,
type BigIntStats,
type Stats,
} from "node:fs";
import {
access,
chmod,
cp,
copyFile,
link,
lstat,
mkdir,
mkdtemp,
open,
readFile,
readdir,
readlink,
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 { promisify } from "node:util";
import type { Duplex } from "node:stream";
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,
InvalidTargetError,
OutputDirectoryError,
OutputDirectoryNotEmptyError,
OutputInsideProtectedRootError,
PluginBootstrapError,
LocalPluginBootstrapError,
PluginPythonUnavailableError,
type ProtectedScanPathKind,
SandboxUnavailableError,
errorMessage,
abortReason,
} from "./errors.js";
import {
writeCodexConfig,
writePrivateConfig,
type JsonObject,
} from "./config.js";
import { isRecord } from "./record.js";
import {
campaignExecutable,
inspectTrustedExecutable,
isWithin,
resolveTrustedExecutable,
type InspectedExecutable,
} from "./trusted-executable.js";
import {
isWindowsUnsafePathComponent,
sqliteFilename,
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 KEYRING_LOGIN = ".codex-security-keyring-login";
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",
"HF_TOKEN",
]);
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[];
/** @internal Additional roots excluded only from ambient interpreter discovery. */
discoveryProtectedRoots?: readonly string[];
/** @internal Ambient PATH lookup requires a known boundary for saved Git targets. */
allowPathLookup?: boolean;
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",
process.platform !== "win32",
);
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;
const code = nodeErrorCode(error);
const recovery =
code === "EACCES" || code === "EPERM" || code === "EROFS"
? "\nCheck permissions or set CODEX_SECURITY_STATE_DIR to a private, writable directory outside the repository."
: "";
throw new OutputDirectoryError(
`Unable to prepare the Codex Security credential home: ${path}\n${errorMessage(error)}${recovery}`,
{ 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,
);
}
export 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_ACCOUNT_SID = /^S-1-5-21-(?:\d+-){3}\d+$/u;
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>>;
currentGroupSids?: ReadonlySet<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" ||
// OWNER RIGHTS applies to the owner already verified above. Every
// descendant is inspected with its own security descriptor.
(principal !== WINDOWS_OWNER_RIGHTS_SID &&
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 if (
principal === currentUserSid ||
!WINDOWS_ACCOUNT_SID.test(principal) ||
(options.currentGroupSids?.has(principal) ?? true)
) {
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",
);
}
}
// win32.parse stops at the UNC marker for extended-length share paths.
const WINDOWS_CREDENTIAL_UNC_ROOT =
/^[\\/]{2}[?.][\\/]UNC[\\/][^\\/]+[\\/][^\\/]+[\\/]?/iu;
function windowsCredentialRootLength(path: string): number {
const root =
WINDOWS_CREDENTIAL_UNC_ROOT.exec(path)?.[0] ?? win32.parse(path).root;
if (win32.isAbsolute(path) && win32.relative(root, path) === "") {
throw new Error(
"A private Windows directory must be below a volume or share root",
);
}
return root.length;
}
export function windowsCredentialAncestorAclScript(path: string): string {
const rootLength = windowsCredentialRootLength(path);
return [
"$path = $env:CODEX_SECURITY_CREDENTIAL_ACL_PATH",
// Stop at the drive or UNC share root, then inspect the outermost ancestor first.
`$ancestors = @(while ($path.Length -gt ${rootLength}) { $parent = Microsoft.PowerShell.Management\\Split-Path -Path $path -Parent; if (-not $parent -or $parent -eq $path) { break }; $parent; $path = $parent })`,
"for ($i = $ancestors.Count - 1; $i -ge 0; $i--) { Write-CredentialAcl $ancestors[$i] }",
].join("\n");
}
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>;
currentGroupSids?: ReadonlySet<string>;
},
): Promise<{
home: WindowsCredentialAcl;
descendantsArePrivate: boolean;
}> {
const rootLength = windowsCredentialRootLength(path);
const ancestors: string[] = [];
let ancestor = win32.dirname(path);
while (true) {
ancestors.push(ancestor);
const parent = win32.dirname(ancestor);
if (ancestor.length <= rootLength || ancestor === parent) break;
ancestor = parent;
}
ancestors.reverse();
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,
{
currentGroupSids: options.currentGroupSids,
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) {
let guidance =
"Choose a location outside this ancestor with trusted ownership and permissions.";
if (index === 0) {
guidance = WINDOWS_CREDENTIAL_UNC_ROOT.test(
win32.toNamespacedPath(ancestorPath),
)
? "This share root is unsupported. Choose a location outside this share with trusted ownership and permissions."
: "This volume root is unsupported. Choose a location on a volume with trusted ancestry; another directory on the same volume will not resolve this.";
}
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, {
currentGroupSids: options.currentGroupSids,
resolvedAliases: options.resolvedAliases,
});
} catch (error) {
if (error instanceof UntrustedWindowsCredentialOwnerError) {
throw new RepairableWindowsCredentialOwnerError(error);
}
throw new RepairableWindowsCredentialAclError(error);
}
return;
}
const descendant = inspectWindowsCredentialAcl(
descriptor,
currentUserSid,
{
currentGroupSids: options.currentGroupSids,
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");
}
/** A file server may add its own groups to the client's token. */
export async function isLocalWindowsCredentialVolume(
path: string,
readDriveType: (drive: string) => Promise<string>,
): Promise<boolean> {
const drive = /^\\\\[?.]\\([A-Z]:)\\/iu.exec(
win32.toNamespacedPath(path),
)?.[1];
if (!drive) return false;
// Win32_LogicalDisk reports removable, local disk, and RAM disk as 2, 3, 6.
return ["2", "3", "6"].includes((await readDriveType(drive)).trim());
}
/** Keep every token group, including groups used only for deny ACEs. */
export function parseWindowsTokenGroupSids(output: string): Set<string> {
const groups = new Set<string>();
for (const row of output.trim().split(/\r?\n/u)) {
const sid =
/^"(?:[^"]|"")*","(?:[^"]|"")*","(S-1-(?:\d+-)*\d+)","(?:[^"]|"")*"$/u.exec(
row,
)?.[1];
if (!sid) throw new Error("Unable to identify Windows token group SIDs");
groups.add(sid);
}
return groups;
}
async function secureWindowsCredentialHome(path: string): Promise<void> {
const ancestorAclScript = windowsCredentialAncestorAclScript(path);
const treePath = win32.toNamespacedPath(path);
const systemRoot = process.env["SystemRoot"] ?? "C:\\Windows";
const systemDirectory = join(systemRoot, "System32");
const powershellDirectory = join(
systemDirectory,
"WindowsPowerShell",
"v1.0",
);
const powershell = join(powershellDirectory, "powershell.exe");
const powershellArgs = [
"-NoLogo",
"-NoProfile",
"-NonInteractive",
"-Command",
];
const inheritedEnvironment = Object.fromEntries(
Object.entries(process.env).filter(
([name]) => name.toUpperCase() !== "PSMODULEPATH",
),
);
const processOptions = {
env: {
...inheritedEnvironment,
CODEX_SECURITY_CREDENTIAL_ACL_PATH: path,
CODEX_SECURITY_CREDENTIAL_TREE_PATH: treePath,
PSModulePath: join(powershellDirectory, "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) {",
" $descriptors = @(Microsoft.PowerShell.Security\\Get-Acl -LiteralPath $path | Microsoft.PowerShell.Utility\\Select-Object -ExpandProperty Sddl)",
" if ($descriptors.Count -ne @($path).Count) { throw 'Windows credential ACL could not be verified' }",
" foreach ($descriptor in $descriptors) { 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_TREE_PATH -and $_.CategoryInfo.Category -eq 'ObjectNotFound') { return }",
" throw",
" }",
" $children = @(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' }",
// Keep the extended-length path when Windows PowerShell returns child names.
' "$path\\$($entry.Name)"',
" })",
" if ($children.Count -eq 0) { return }",
" try { Write-CredentialAcl $children } catch {",
// A vanished path is the only reason to retry the batch one child at a time.
" if ($_.FullyQualifiedErrorId -notlike 'GetAcl_PathNotFound,*') { throw }",
" for ($i = 0; $i -lt $children.Count; $i++) {",
" try { Write-CredentialAcl $children[$i] } catch {",
" if ($_.FullyQualifiedErrorId -notlike 'GetAcl_PathNotFound,*') { throw }",
" $children[$i] = $null",
" }",
" }",
" }",
" for ($i = 0; $i -lt $children.Count; $i++) {",
" if ($children[$i] -and $entries[$i].PSIsContainer) { Read-CredentialDescendants $children[$i] }",
" }",
"}",
ancestorAclScript,
"Write-CredentialAcl $env:CODEX_SECURITY_CREDENTIAL_ACL_PATH",
"try { Read-CredentialDescendants $env:CODEX_SECURITY_CREDENTIAL_TREE_PATH } catch {",
// Either a batch or a single-child Get-Acl may report an incomplete listing.
` if ($_.FullyQualifiedErrorId -in @('System.IO.FileNotFoundException,Microsoft.PowerShell.Commands.GetAclCommand', 'GetAcl_PathNotFound_Exception,Microsoft.PowerShell.Commands.GetAclCommand')) { exit ${WINDOWS_CREDENTIAL_DESCENDANTS_CHANGED_EXIT_CODE} }`,
" throw",
"}",
`"${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> = {};
function requireNumericSid(value: string): string {
if (!WINDOWS_SID.test(value))
throw new Error(
"Windows credential ACL contains an unresolvable identity",
);
return value;
}
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,
[...powershellArgs, resolvePrincipalScript],
{
...processOptions,
env: {
...processOptions.env,
CODEX_SECURITY_CREDENTIAL_PRINCIPAL: principal,
},
},
);
resolvedAliases[principal] = requireNumericSid(resolved.stdout.trim());
};
const loadLocalGroupSids = async (): Promise<Set<string> | null> => {
const local = await isLocalWindowsCredentialVolume(
treePath,
async (drive) => {
const volume = await execFile(
powershell,
[
...powershellArgs,
`$ErrorActionPreference = 'Stop'; (CimCmdlets\\Get-CimInstance -ClassName Win32_LogicalDisk -Filter "DeviceID = '${drive}'").DriveType`,
],
processOptions,
);
return volume.stdout;
},
);
if (!local) return null;
const groups = await execFile(
join(systemDirectory, "whoami.exe"),
["/groups", "/fo", "csv", "/nh"],
processOptions,
);
return parseWindowsTokenGroupSids(groups.stdout);
};
let currentGroupSids: Set<string> | null | undefined;
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 fields = rule.split(";");
const principal = fields[5];
if (principal !== undefined) {
await resolvePrincipal(principal);
const trustee = resolvedAliases[principal] ?? principal;
if (
currentGroupSids === undefined &&
["D", "OD", "XD"].includes(fields[0]!) &&
trustee !== sid &&
WINDOWS_ACCOUNT_SID.test(trustee)
) {
currentGroupSids = await loadLocalGroupSids();
}
}
remaining = rest;
}
};
let descendantsArePrivate = true;
const readAcl = async (): Promise<WindowsCredentialAcl> => {
const snapshot = await inspectWindowsCredentialAclSnapshot(path, sid, {
command: powershell,
args: [...powershellArgs, script],
environment: processOptions.env,
get currentGroupSids() {
return currentGroupSids ?? undefined;
},
resolvedAliases,
resolveDescriptorAliases,
});
descendantsArePrivate = snapshot.descendantsArePrivate;
return snapshot.home;
};
const icacls = (target: string, ...args: string[]) =>
execFile(
join(systemDirectory, "icacls.exe"),
[target, ...args],
processOptions,
);
const installTrustedAcl = () =>
icacls(
path,
"/inheritance:r",
"/grant:r",
`*${sid}:(OI)(CI)F`,
`*${WINDOWS_SYSTEM_SID}:(OI)(CI)F`,
`*${WINDOWS_ADMINISTRATORS_SID}:(OI)(CI)F`,
);
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 icacls(path, "/setowner", `*${sid}`);
} 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 icacls(path, "/inheritance:d");
existing = await readAcl();
}
let verified = existing;
if (
!verified.protected ||
!verified.grantsCurrentUserAccess ||
verified.untrustedPrincipals.length !== 0
) {
await installTrustedAcl();
verified = await readAcl();
for (const [remove, principals] of [
["/remove:g", verified.untrustedPrincipals],
["/remove:d", verified.deniedPrincipals],
] as const) {
for (const principal of principals)
await icacls(path, remove, `*${requireNumericSid(principal)}`);
}
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 icacls(join(treePath, "*"), "/reset", "/t", "/q");
await readAcl();
if (!descendantsArePrivate) {
throw new Error("Windows credential descendants remain accessible");
}
}
}
export interface RuntimeDatabase {
exec(sql: string): unknown;
prepare(sql: string): {
all(...parameters: (string | number)[]): unknown[];
finalize?(): void;
};
close(): void;
}
export function sqliteDatabaseOpener(
access: "read-existing" | "read-write" = "read-write",
) {
const require = createRequire(import.meta.url);
const bun = process.versions["bun"] !== undefined;
const Database = (
bun ? require("bun:sqlite").Database : require("node:sqlite").DatabaseSync
) as new (filename: string, options?: object) => RuntimeDatabase;
return (path: string): RuntimeDatabase => {
const filename = sqliteFilename(path);
if (access === "read-write") return new Database(filename);
// Apple's SQLite requires write access to initialize missing WAL sidecars.
// The history reader sets PRAGMA query_only on this existing-file connection.
return new Database(
filename,
bun
? {
readonly: process.platform !== "darwin",
readwrite: process.platform === "darwin",
create: false,
}
: { readOnly: true },
);
};
}
function sqliteBusy(error: unknown): boolean {
return (
isRecord(error) &&
(error["errcode"] === 5 || error["code"] === "SQLITE_BUSY")
);
}
export async function acquireScanExecutionLock(
stateDirectory: string,
scanDirectory: string,
): Promise<() => void> {
const directory = join(stateDirectory, "scan-locks");
await mkdir(directory, { recursive: true, mode: 0o700 });
await requirePrivateDirectory(await stat(directory), directory, "scan locks");
const identity = createHash("sha256").update(scanDirectory).digest("hex");
const path = join(directory, `${identity}.sqlite3`);
const database = sqliteDatabaseOpener()(path);
try {
if (process.platform !== "win32") await chmod(path, 0o600);
database.exec("PRAGMA busy_timeout = 0");
database.exec("BEGIN EXCLUSIVE");
} catch (error) {
database.close();
if (sqliteBusy(error)) {
throw new CodexSecurityError(
"This scan is already running in another CLI or SDK call.",
);
}
throw error;
}
return () => database.close();
}
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 openDatabase = sqliteDatabaseOpener();
// 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 = openDatabase(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 (!sqliteBusy(error)) {
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}`,
);
}
}
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;
}
function sameInode(left: BigIntStats, right: BigIntStats): boolean {
return left.dev === right.dev && left.ino === right.ino;
}
/** Distinguish two hard links from two paths to the same directory entry. */
async function hasSeparateAmbientLink(
localPath: string,
ambientHome: string,
): Promise<boolean> {
try {
const local = await lstat(localPath, { bigint: true });
if (!local.isFile() || local.nlink < 2n || local.ino === 0n) return false;
const ambient = await lstat(join(ambientHome, "auth.json"), {
bigint: true,
});
if (!ambient.isFile() || !sameInode(local, ambient)) return false;
const [localDir, ambientDir] = await Promise.all([
stat(dirname(localPath), { bigint: true }),
stat(ambientHome, { bigint: true }),
]);
return (
localDir.ino !== 0n &&
ambientDir.ino !== 0n &&
!sameInode(localDir, ambientDir)
);
} catch {
// Without a verified second link, leave logout to the configured native store.
return false;
}
}
/** Native Codex defaults to file storage when the managed home has no setting. */
async function credentialStore(home: string): Promise<unknown> {
const contents = await readFile(join(home, "config.toml"), "utf8").catch(
nullIfMissingFileError,
);
return contents === null
? "file"
: (parse(contents, { integersAsBigInt: "asNeeded" })[
"cli_auth_credentials_store"
] ?? "file");
}
async function hasCredentialFile(home: string): Promise<boolean> {
const file = await lstat(join(home, "auth.json")).catch(
nullIfMissingFileError,
);
return file?.isFile() === true;
}
function savedKeyringHistory(home: string) {
return readFile(join(home, KEYRING_LOGIN), "utf8").catch(
nullIfMissingFileError,
);
}
function canUseKeyring(store: unknown): boolean {
return store === "auto" || store === "keyring";
}
function keyringHistory(
saved: string | null,
store: unknown,
hasFile: boolean,
) {
if (saved === "keyring" || saved === "pending") return "keyring";
// On upgrade, a prior keyring login may exist. Auto can also move a file
// credential into the keyring on refresh, removing auth.json.
if (
(saved === null && canUseKeyring(store)) ||
(saved === "file" && store === "auto" && !hasFile)
)
return "keyring";
return hasFile ? "file" : "none";
}
async function rememberStoredFile(home: string) {
if ((await savedKeyringHistory(home)) === "none") {
await writePrivateConfig(join(home, KEYRING_LOGIN), "file");
}
}
/** Arm logout before a native login can persist a keyring grant and be interrupted. */
export async function beginCredentialLogin(home: string): Promise<void> {
const store = await credentialStore(home);
if (!canUseKeyring(store)) return;
const marker = join(home, KEYRING_LOGIN);
const saved = await savedKeyringHistory(home);
const present = await hasCredentialFile(home);
const previous = keyringHistory(saved, store, present);
// Only this login's successful file fallback can discharge a new pending marker.
const next = previous === "keyring" ? "keyring" : "pending";
if (next !== saved) await writePrivateConfig(marker, next);
}
/** Is the managed file the active login, or a known-empty file destination for an ambient import? */
export async function credentialHomeUsesFileStorage(
home: string,
options: { allowAmbientImport?: boolean } = {},
): Promise<boolean> {
const store = await credentialStore(home);
if (store !== "auto") return store === "file";
const saved = await savedKeyringHistory(home);
const hasFile = await hasCredentialFile(home);
return hasFile
? saved === "file"
: options.allowAmbientImport === true && saved === "none";
}
/** Preserve credential provenance before a scan or sign-in replaces the shared config. */
export async function writeCredentialHomeConfig(
home: string,
config: JsonObject,
): Promise<void> {
const old = await credentialStore(home);
if (
canUseKeyring(old) ||
canUseKeyring(config["cli_auth_credentials_store"])
) {
const marker = join(home, KEYRING_LOGIN);
const saved = await savedKeyringHistory(home);
const hasFile = await hasCredentialFile(home);
const observed = keyringHistory(saved, old, hasFile);
if (observed !== saved) await writePrivateConfig(marker, observed);
}
await writeCodexConfig(join(home, "config.toml"), config);
}
/** Run under the credential-home lock so status cannot reimport the sign-in during logout. */
export async function logoutCredentialHome<T extends number | void>(
home: string,
ambientHome: string,
nativeLogout: (store?: string) => Promise<T>,
onLoggedOut?: () => void,
): Promise<T> {
const localPath = join(home, "auth.json");
const shared = await hasSeparateAmbientLink(localPath, ambientHome);
let recorded = false;
const recordLogout = async () => {
if (recorded) return;
await setCodexSecurityCredentialLogout(home, true);
if (shared) await rm(localPath);
onLoggedOut?.();
recorded = true;
};
// Detach before native logout can revoke a shared token, even if native cleanup fails.
if (shared) await recordLogout();
const marker = join(home, KEYRING_LOGIN);
const previous = await savedKeyringHistory(home);
const active = await credentialStore(home);
const hasFile = await hasCredentialFile(home);
const keyring =
keyringHistory(previous, active, hasFile || shared) === "keyring";
if (keyring && hasFile) {
// Native keyring logout also unlinks the file, but only revokes the token it loads.
const status = await nativeLogout(active === "file" ? undefined : "file");
if (status !== undefined && status !== 0) return status;
// A retry must not re-import ambient credentials after the file was revoked.
await recordLogout();
}
let override: string | undefined;
if (keyring && !canUseKeyring(active)) override = "keyring";
else if (!keyring && active !== "file" && (hasFile || canUseKeyring(active)))
override = "file";
const status = await nativeLogout(override);
if (status === undefined || status === 0) {
await recordLogout();
if (canUseKeyring(active)) await writePrivateConfig(marker, "none");
else await rm(marker, { force: true });
}
return status;
}
export async function setCodexSecurityCredentialLogout(
codexHome: string,
loggedOut: boolean,
): Promise<void> {
await requireSecureCredentialHome(codexHome);
const marker = join(codexHome, CREDENTIAL_LOGOUT_MARKER);
if (!loggedOut) {
// Native auto removes auth.json on keyring success and leaves it on file fallback.
const store = await credentialStore(codexHome);
const history = join(codexHome, KEYRING_LOGIN);
if (
store === "keyring" ||
(store === "auto" && !(await hasCredentialFile(codexHome)))
) {
await writePrivateConfig(history, "keyring");
} else if (
store === "auto" &&
(await savedKeyringHistory(codexHome)) === "pending"
) {
await writePrivateConfig(history, "file");
}
await rm(marker, { force: true });
return;
}
await writePrivateConfig(marker, "logged out\n");
}
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" || pathKind === "state") &&
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);
}
/** Check where the scan will create state and default artifacts without creating them. */
export async function checkScanStorage(
stateDirectory: string,
defaultOutputRepository?: string,
): Promise<void> {
try {
let root = await canonicalConfigPath(stateDirectory);
await requireWritableDirectoryOrParent(root);
if (defaultOutputRepository === undefined) return;
for (const name of ["scans", safePrefix(defaultOutputRepository)]) {
root = join(root, name);
const metadata = await lstat(root).catch(nullIfMissingFileError);
if (metadata !== null && !metadata.isDirectory()) {
throw new OutputDirectoryError(
`Persistent scan output must use real directories: ${root}`,
);
}
}
await requireWritableDirectoryOrParent(root);
// New per-scan directories are created beneath this root.
await requireSecureOutputAncestry(
join(root, `codex-security-${randomUUID()}`),
);
} catch (error) {
throw new OutputDirectoryError(
`Cannot use scan state directory ${stateDirectory}. Check CODEX_SECURITY_STATE_DIR: ${errorMessage(error)}`,
{ cause: error },
);
}
}
async function requireWritableDirectoryOrParent(path: string): Promise<void> {
const metadata = await lstat(path).catch(nullIfMissingFileError);
if (metadata === null) {
const parent = dirname(path);
if (parent === path)
throw new OutputDirectoryError(`Directory does not exist: ${path}`);
return requireWritableDirectoryOrParent(parent);
}
if (!metadata.isDirectory())
throw new OutputDirectoryError(`Expected a directory: ${path}`);
await access(path, constants.W_OK | constants.X_OK);
}
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 WORKBENCH_REGISTRATION_PROGRAM = String.raw`
import os, runpy, sys
sys.argv = sys.argv[1:]
def before_output_change():
with os.fdopen(3, "r+b", buffering=0) as control:
control.write(b"?")
if control.read(1) != b"!":
raise SystemExit("Scan registration canceled before changing the output.")
sys._codex_security_before_output_change = before_output_change
if "--archive-existing" in sys.argv[1:] and "--archived-scan-dir" not in sys.argv[1:]:
# Released workbenches accept this callback before moving an existing output.
runpy.run_path(sys.argv[0])["main"](before_archive=before_output_change)
else:
# A selected plugin keeps its script entrypoint, argv, stdin and stdout.
runpy.run_path(sys.argv[0], run_name="__main__")
`;
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;
// Explicitly selected external plugins retain their own workbench protocol.
const nativeLocalDedupe =
args[0] === "local-dedupe" &&
(await sameFile(options.pluginRoot, await bundledPluginRoot()));
const run = async (
arguments_: readonly string[],
input?: string,
registrationHandshake = false,
): Promise<string> => {
const native =
nativeLocalDedupe ||
[
"database-info",
"store-findings",
"list-stored-findings",
"store-external-findings",
"read-external-findings",
"list-external-imports",
"record-external-finding-publications",
"list-external-finding-publications",
"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;
// Validate one JSON document before framing its unchanged source as payload.
if (nativeLocalDedupe && input !== undefined) JSON.parse(input);
const result = await runCodexCommand(
{ command },
native
? [join(options.pluginRoot, "mcp", "helpers.mjs"), ...arguments_]
: [
"-I",
"-X",
"utf8",
"-B",
"-c",
WORKBENCH_ARGUMENTS_PROGRAM +
(registrationHandshake
? WORKBENCH_REGISTRATION_PROGRAM
: WORKBENCH_SCRIPT_PROGRAM),
script,
],
pluginHelperEnvironment({
...(node?.environment ?? options.environment),
// Python's compressed-rollout reader needs the selected Node even when
// this SDK was launched by absolute path without Node on PATH.
...(!native &&
!process.versions["bun"] &&
environmentValue(options.environment, "CODEX_MCP_NODE_PATH") ===
undefined
? { CODEX_MCP_NODE_PATH: process.execPath }
: {}),
}),
// The SDK owns configuration normalization; the helper receives its resolved location.
nativeLocalDedupe
? `{"stateDirectory":${JSON.stringify(stateDirectory)},"payload":${input ?? "null"}}`
: native
? JSON.stringify(
arguments_[0] === "database-info"
? stateDirectory
: {
stateDirectory,
payload:
input === undefined ? undefined : JSON.parse(input),
},
)
: input,
signal,
{
registrationHandshake,
// Frame Python arguments on stdin to preserve NUL and long diagnostics.
stdinPrefix: native
? undefined
: `${JSON.stringify(arguments_.map((argument) => argument.toWellFormed()))}\n`,
},
);
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 registrationHandshake =
signal !== undefined &&
args[0] === "register-cli-scan" &&
(process.platform === "win32" ||
(args.includes("--archive-existing") &&
!args.includes("--archived-scan-dir")));
try {
stdout = await run(args, input, registrationHandshake);
} catch (error) {
const focusedIndex = args.indexOf("--after-scan-id");
if (
args[0] !== "list-unmatched-scan-pairs" ||
focusedIndex === -1 ||
!/unrecognized arguments: --after-scan-id(?:\s+\S+)?$/u.test(
processErrorDetail(error),
)
)
throw error;
options.signal?.throwIfAborted();
const legacyArgs = [...args];
legacyArgs.splice(focusedIndex, 2);
stdout = await run(legacyArgs, input, registrationHandshake);
}
} 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 async function resolveScanOutputPath(
outputDirectory: string,
validateTraversalLink?: (path: string) => void,
): Promise<string> {
try {
const requested = resolveInputPath(outputDirectory);
const path = await resolveParentTraversal(requested, {
allowMissing: true,
});
requireModelSafeOutputDir(path);
if (validateTraversalLink && path !== resolve(requested)) {
await validateDirectoryLinks(requested, validateTraversalLink);
}
return path;
} catch (error) {
throw outputInspectionError(outputDirectory, error);
}
}
export async function validateOutputDir(
outputDirectory?: string,
archiveExisting = false,
validateTraversalLink?: (path: string) => void,
): Promise<string | null> {
if (outputDirectory === undefined) {
return null;
}
try {
const path = await resolveScanOutputPath(
outputDirectory,
validateTraversalLink,
);
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);
const writableLeaf =
!archiveExisting ||
(process.platform === "win32" && (await readdir(path)).length === 0);
const canonical = await checkedOutputPath(path, writableLeaf).catch(
rethrowOutputPathValidationError,
);
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).catch(
rethrowOutputPathValidationError,
);
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) {
throw outputInspectionError(outputDirectory, error);
}
}
function outputInspectionError(
outputDirectory: string,
cause: unknown,
): OutputDirectoryError {
return cause instanceof OutputDirectoryError
? cause
: new OutputDirectoryError(
`Unable to inspect scan output directory: ${outputDirectory}`,
{ cause },
);
}
/** Check each traversed directory link at its physical location, including linked targets. */
export async function validateDirectoryLinks(
requested: string,
validateLocation: (path: string) => void,
): Promise<void> {
const directories = [dirname(requested)];
const visited = new Set<string>();
while (directories.length > 0) {
let directory = directories.pop()!;
while (dirname(directory) !== directory && !visited.has(directory)) {
visited.add(directory);
if (
(await lstat(directory).catch(nullIfMissingFileError))?.isSymbolicLink()
) {
const parent = await realpath(
await resolveParentTraversal(dirname(directory)),
);
validateLocation(join(parent, basename(directory)));
directories.push(resolveTargetPath(await readlink(directory), parent));
}
directory = dirname(directory);
}
}
}
function rethrowOutputPathValidationError(error: unknown): never {
if (
process.platform !== "win32" ||
nodeErrorCode(error) !== "ERR_DLOPEN_FAILED"
)
throw error;
const blocked =
error instanceof Error &&
/^(?:LoadLibrary failed: )?An Application Control policy has blocked this file\.(?:\s|$)/u.test(
error.message,
);
throw new OutputDirectoryError(
blocked
? "Windows Application Control blocked the bundled Codex Security filesystem module (windows.node). Check the CodeIntegrity Operational log in Event Viewer."
: "Could not load the bundled Codex Security filesystem module (windows.node) on Windows.",
{ 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;
const id = randomUUID().slice(0, 8);
const archive = `${outputDirectory}${outputArchiveSuffix(id)}`;
if (process.platform === "win32" || !(await archiveNameTooLong(archive)))
return archive;
// The workbench reserves a sibling with an eight-character random suffix.
const sibling = `${outputDirectory}.previous-${id}`;
if (!(await archiveNameTooLong(sibling))) return sibling;
return join(
dirname(outputDirectory),
shortArchivePrefix(basename(outputDirectory)) + id,
);
}
async function archiveNameTooLong(path: string): Promise<boolean> {
try {
await lstat(path);
return false;
} catch (error) {
return nodeErrorCode(error) === "ENAMETOOLONG";
}
}
function outputArchiveSuffix(id = randomUUID().slice(0, 8)): string {
return `.previous-${new Date()
.toISOString()
.replaceAll(/[-:]/g, "")
.replace(/\.\d{3}Z$/, "")}-${id}`;
}
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,
{ verifyIdentity = false }: { verifyIdentity?: boolean } = {},
): Promise<string> {
let existing = resolve(path);
const missing: string[] = [];
while (true) {
try {
const canonical = await realpath(existing);
if (verifyIdentity && !(await sameFile(existing, canonical)))
throw new InvalidTargetError(`Repository path changed: ${existing}`);
return join(canonical, ...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> {
const path = await validateOutputDir(
outputDirectory,
existingOutput !== "reject",
validateLocation,
);
if (path === null) {
requireModelSafeOutputDir(temporaryRoot);
const canonicalRoot = await realpath(temporaryRoot);
requireModelSafeOutputDir(canonicalRoot);
validateLocation?.(canonicalRoot);
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(
canonicalRoot,
`${prefix.slice(0, prefixLength)}${suffix}`,
);
await createWindowsOutputDirectory(created, false);
} else {
try {
created = await mkdtemp(join(canonicalRoot, `${prefix}-`));
} catch (error) {
if (nodeErrorCode(error) !== "ENAMETOOLONG") throw error;
// The repository name itself can fill a filesystem component.
created = await mkdtemp(join(canonicalRoot, "codex-security-"));
}
}
try {
if ((process.umask() & 0o700) !== 0) await chmod(created, 0o700);
return await validatePreparedOutputDir(created, validateLocation);
} catch (error) {
await rmdir(created).catch(() => undefined);
throw error;
}
}
validateLocation?.(path);
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);
}
// Registration retains a populated scan for archival. An empty Windows
// directory must still satisfy the checks for a writable scan output.
const preserveContents =
existingOutput === "preserve" &&
(process.platform !== "win32" || (await readdir(path)).length !== 0);
return await validatePreparedOutputDir(
path,
validateLocation,
preserveContents,
);
} 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,
},
);
}
}
async function windowsOutputBinding() {
return createRequire(import.meta.url)(
join(
await bundledPluginRoot(),
"mcp",
"native",
`win32-${process.arch}`,
"windows.node",
),
) as {
createPrivateWindowsDirectory(path: Buffer, checkOutput: boolean): number;
validateWindowsOutputPath(
path: Buffer,
writableLeaf?: boolean,
retainedDirectory?: string,
): number;
};
}
export async function requireWindowsOutputPath(
path: string,
writableLeaf?: boolean,
retainedDirectory?: string,
): Promise<void> {
const native = await windowsOutputBinding();
const error = native.validateWindowsOutputPath(
Buffer.from(win32.toNamespacedPath(path), "utf16le"),
writableLeaf,
retainedDirectory,
);
if (error !== 0)
throw new OutputDirectoryError(
`Scan output directory or its parent could not be trusted (Windows error ${error}): ${path}`,
);
}
export async function createWindowsOutputDirectory(
path: string,
recursive: boolean,
): Promise<string | undefined> {
const native = await windowsOutputBinding();
const create = async (target: string): Promise<string | undefined> => {
const createOne = () =>
native.createPrivateWindowsDirectory(
Buffer.from(win32.toNamespacedPath(target), "utf16le"),
true,
);
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()) {
await requireWindowsOutputPath(target, target === path);
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 checkedOutputPath(path, !allowNonempty);
requireModelSafeOutputDir(canonical);
validateLocation?.(canonical);
if (!allowNonempty && (await readdir(canonical)).length !== 0) {
throw new OutputDirectoryError(
`Scan output directory must be empty: ${path}`,
);
}
requireOutputDirectoryOwnership(metadata, path);
return canonical;
}
async function checkedOutputPath(
path: string,
writableLeaf: boolean,
): Promise<string> {
if (process.platform === "win32") {
// Keep the selected leaf for the no-follow check, including across an
// in-place directory change between lstat and canonicalization.
const directory = dirname(path);
const parent = await realpath(directory);
const selected = join(parent, relative(directory, path));
await requireWindowsOutputPath(selected, writableLeaf);
const canonical = await realpath(selected);
if (canonical === selected) return selected;
// Accept a canonical leaf spelling (case or short name) within the checked parent.
if (dirname(canonical) === parent) {
const [leaf, resolved] = await Promise.all([
lstat(selected, { bigint: true }),
lstat(canonical, { bigint: true }),
]);
if (leaf.isDirectory() && leaf.ino !== 0n && sameInode(leaf, resolved)) {
return canonical;
}
}
throw new OutputDirectoryError(
`Scan output directory changed during preparation: ${path}`,
);
}
await requireSecureOutputAncestry(path);
const canonical = await realpath(path);
if (canonical !== 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 requireWindowsOutputPath(path);
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);
await rememberStoredFile(isolatedHome);
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> {
return extractValidatedPluginZip(archive, destination, signal);
}
async function extractValidatedPluginZip(
archive: string,
destination: string,
signal?: AbortSignal,
digest?: Hash,
): Promise<string> {
const archivePath = resolve(expandHome(archive));
const parent = dirname(destination);
await mkdir(parent, { recursive: true, mode: 0o700 });
// Windows mkdtemp otherwise fails at 248 UTF-16 units, including its suffix.
const stagingParent =
process.platform === "win32"
? win32.toNamespacedPath(await realpath(parent))
: parent;
const staging = await realpath(
await mkdtemp(join(stagingParent, ".codex-security-plugin-")),
);
let publishingOnWindows = false;
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;
digest?.update(JSON.stringify([path, directory, permissions]));
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}`,
);
}
digest?.update(createHash("sha256").update(bytes).digest());
}
const pluginRoot = await discoverPluginRoot(staging);
throwIfSignalAborted(signal);
const relativeRoot = relative(staging, pluginRoot);
if (process.platform === "win32") {
publishingOnWindows = true;
await retryWindowsRename(
async () => {
throwIfSignalAborted(signal);
if (await lstat(destination).catch(nullIfMissingFileError))
throw new Error(`Destination already exists: ${destination}`);
await rename(staging, destination);
},
undefined,
signal,
);
publishingOnWindows = false;
} else {
await rename(staging, destination);
}
return await validatePluginRoot(join(destination, relativeRoot));
} catch (error) {
let cleanupDiagnostic = "";
await rm(staging, { recursive: true, force: true }).catch(
(cleanupError) => {
cleanupDiagnostic = `\nCould not remove staging directory ${staging}: ${errorMessage(cleanupError)}`;
},
);
throwIfSignalAborted(signal);
if (publishingOnWindows)
throw new PluginBootstrapError(
`Could not publish extracted plugin ZIP: ${errorMessage(error)}${cleanupDiagnostic}`,
{ cause: error },
);
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> {
return (await resolvePluginSource(pluginPath, workspace, signal)).root;
}
/** @internal */
export interface PluginZipSource {
path: string;
digest: string;
}
/** @internal */
export async function resolvePluginSource(
pluginPath: string | undefined,
workspace: string,
signal?: AbortSignal,
pinZip = false,
): Promise<{ root: string; zip?: PluginZipSource }> {
try {
if (pluginPath === undefined) {
return { root: await bundledPluginRoot() };
}
const path = resolve(expandHome(pluginPath));
const metadata = await lstat(path).catch(() => null);
if (metadata?.isFile() && extname(path).toLowerCase() === ".zip") {
const digest = pinZip ? createHash("sha256") : undefined;
const archive = digest ? await realpath(path) : path;
const root = await extractValidatedPluginZip(
archive,
join(workspace, "extracted-plugin"),
signal,
digest,
);
return {
root,
...(digest && { zip: { path: archive, digest: digest.digest("hex") } }),
};
}
if (metadata?.isDirectory()) {
throwIfSignalAborted(signal);
return { root: 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 });
}
}
/** @internal */
export async function prepareWindowsScanPluginZip(
source: PluginZipSource,
scanDirectory: string,
protectedDirectories: readonly string[],
validateLocation: (path: string) => void,
signal?: AbortSignal,
): Promise<{ workspace: string; root: string } | undefined> {
throwIfSignalAborted(signal);
const protectedPath = (path: string) =>
protectedDirectories.some((directory) => isWithin(directory, path));
if (protectedPath(source.path)) return;
const metadata = await lstat(source.path).catch(nullIfMissingFileError);
if (metadata === null) return;
const changed = "The selected plugin ZIP changed after runtime preparation.";
if (!metadata.isFile()) throw new LocalPluginBootstrapError(changed);
const canonicalSource = await realpath(source.path).catch(
nullIfMissingFileError,
);
if (canonicalSource === null) return;
if (protectedPath(canonicalSource))
throw new LocalPluginBootstrapError(changed);
let workspace: string | undefined;
const parents = [...new Set([dirname(scanDirectory), tmpdir()])].filter(
(parent) => !protectedPath(parent) && !isWithin(scanDirectory, parent),
);
// PowerShell may fail to launch the selected plugin's .cmd at a long path.
// Prefer the shorter canonical parent, retaining the output parent on ties.
const candidates = await abortable(
() => Promise.allSettled(parents.map((path) => realpath(path))),
signal,
);
const length = (candidate: PromiseSettledResult<string>) =>
candidate.status === "fulfilled" ? candidate.value.length : Infinity;
for (const candidate of candidates.sort((a, b) => length(a) - length(b))) {
throwIfSignalAborted(signal);
try {
if (candidate.status === "rejected") throw candidate.reason;
const canonical = candidate.value;
if (protectedPath(canonical) || isWithin(scanDirectory, canonical))
continue;
// Host-side plugin helpers may execute from this copy. A sibling keeps it
// outside the writable scan, and the native creator verifies its parents.
workspace = await prepareOutputDir(
undefined,
"plugin-input",
canonical,
validateLocation,
);
break;
} catch (error) {
if (
!(error instanceof OutputDirectoryError) &&
!["EACCES", "EPERM", "ENOENT"].includes(nodeErrorCode(error) ?? "")
)
throw error;
}
}
// Keep existing plugin handling where neither scan input location is usable.
if (workspace === undefined) return;
try {
throwIfSignalAborted(signal);
const digest = createHash("sha256");
const root = await extractValidatedPluginZip(
source.path,
join(workspace, "plugin"),
signal,
digest,
);
throwIfSignalAborted(signal);
if (digest.digest("hex") !== source.digest) {
throw new LocalPluginBootstrapError(changed);
}
return { workspace, root };
} catch (error) {
try {
await cleanupSdkDirectory(workspace);
} catch (cleanupError) {
throwIfSignalAborted(signal);
throw new LocalPluginBootstrapError(
`${errorMessage(error)}\nCould not remove scan input directory ${workspace}: ${errorMessage(cleanupError)}`,
{ cause: error },
);
}
throwIfSignalAborted(signal);
const cause =
error instanceof PluginBootstrapError ? error.cause : undefined;
if (
isRecord(cause) &&
cause["code"] === "ENOENT" &&
cause["syscall"] === "open" &&
cause["path"] === source.path
)
return;
throw 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 }>;
};
// Private handoff to the staged SDK launcher and shell-invoked helpers.
export const SDK_NODE_SEARCH_PATH = "_CODEX_SECURITY_SDK_NODE_SEARCH_PATH";
export async function sdkNodeSearchPath(
roots: readonly string[],
): Promise<string> {
let fallback = "/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin";
const current = dirname(process.execPath);
if (
process.release.name === "node" &&
!process.versions["bun"] &&
!process.versions["electron"] &&
basename(process.execPath) === "node" &&
!current.includes(":")
)
fallback += `:${current}`;
const inspected = await inspectTrustedExecutable(
"node",
{ PATH: fallback },
roots,
);
return inspected.environment["PATH"] ?? "";
}
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;
server["env_vars"] = [
...(environment ?? []),
...["CODEX_SECURITY_PLUGIN_ROOT", "CODEX_SECURITY_REPOSITORY"].filter(
(name) => !environment?.includes(name),
),
];
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 "$(command -p 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 = configuredExecutableValue(
environmentValue(environment, "CODEX_CLI_PATH", true),
process.platform,
(value) => isExecutableFile(expandHomeForLookup(value, environment)),
);
const expanded =
configured === undefined
? undefined
: expandHomeForLookup(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 matchesSelected = (
destination: string,
allowExtraFiles = false,
generatedDirectory?: string,
) =>
pluginContentsMatch(
root,
destination,
options.signal,
allowExtraFiles,
projection,
generatedDirectory,
);
const stagedMatches =
staged?.version === version && (await matchesSelected(stagedRoot));
const matchesNativeInstall = async (
installedRoot: string,
allowRuntimeFiles = false,
) =>
(await matchesSelected(stagedRoot)) &&
// Ordinary reuse permits runtime files when all selected bytes are present.
// The native receipt still verifies the complete generated command output.
((allowRuntimeFiles && (await matchesSelected(installedRoot, true))) ||
(await matchesSelected(
installedRoot,
false,
migratedCommands(installedRoot),
)));
const nativeMigration = (installedRoot: string, allowRuntimeFiles = false) =>
verifiedCommandMigration(
installedRoot,
(path) => matchesNativeInstall(path, allowRuntimeFiles),
options.signal,
);
const matchesReceipt = async (installedRoot: string, migration: unknown) => {
if (
typeof migration === "string" &&
options.runCodex === undefined &&
(await isBundledPluginInstaller(command))
) {
return (await nativeMigration(installedRoot, true)) === migration;
}
return matchesSelected(installedRoot, true);
};
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) => {
const code = nodeErrorCode(error);
if (code === "ENOENT" || error instanceof SyntaxError) {
return null;
}
if (
process.platform === "win32" &&
error instanceof Error &&
(code === "EACCES" || code === "EPERM")
) {
// Keep the original system error, including its path, code and syscall.
error.message +=
" If the SDK created this plugin installation receipt but cannot reopen it, " +
"check its read permissions and the permissions new files inherit from the sdk-marketplace directory.";
}
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 matchesReceipt(
previous["installedPath"],
previous["nativeCommandMigration"],
))
) {
return {
pluginRoot: root,
marketplaceRoot: marketplace,
installedRoot: previous["installedPath"],
marketplaceName: MARKETPLACE_NAME,
name,
version,
};
}
const addPlugin = () =>
run(
command,
["plugin", "add", "--json", `${PLUGIN_NAME}@${MARKETPLACE_NAME}`],
environment,
options.signal,
);
let output: string;
let retried = false;
try {
output = await addPlugin();
} catch (first) {
if (!isRolledBackPluginActivation(first)) throw first;
throwIfSignalAborted(options.signal);
if (!(await isBundledPluginInstaller(command))) throw first;
// The bundled CLI restored the old cache. A short-lived Windows reader
// of the new tree can release it before a fresh installation attempt.
try {
await delay(100, undefined, { signal: options.signal });
throwIfSignalAborted(options.signal);
if (!(await matchesSelected(stagedRoot))) {
throw new LocalPluginBootstrapError(
"The selected plugin or its marketplace changed before the native installation could be retried.",
{ cause: first },
);
}
throwIfSignalAborted(options.signal);
output = await addPlugin();
retried = true;
} catch (second) {
throwIfSignalAborted(options.signal);
throw isRolledBackPluginActivation(second) ? first : second;
}
}
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.",
);
}
// The bundled installer removes stale command skills before regenerating them.
const bundledInstaller =
retried ||
(options.runCodex === undefined &&
(await isBundledPluginInstaller(command)));
const hasSourceMigration =
bundledInstaller &&
(
await lstat(migratedCommands(root)).catch(nullIfMissingFileError)
)?.isDirectory() === true;
const nativeCommandMigration = hasSourceMigration
? await nativeMigration(installed["installedPath"])
: undefined;
if (
retried &&
!(hasSourceMigration
? nativeCommandMigration !== undefined
: await matchesNativeInstall(installed["installedPath"]))
) {
throw new PluginBootstrapError(
"The retried Codex plugin install did not install the selected plugin contents.",
);
}
await writeFile(
installRecord,
JSON.stringify({
installedPath: installed["installedPath"],
version,
...(nativeCommandMigration ? { nativeCommandMigration } : {}),
}),
{ mode: 0o600, signal: options.signal },
);
return {
pluginRoot: root,
marketplaceRoot: marketplace,
installedRoot: installed["installedPath"],
marketplaceName: MARKETPLACE_NAME,
name,
version,
};
}
async function isBundledPluginInstaller(
command: CodexCommand,
): Promise<boolean> {
try {
return await sameFile(command.command, resolveBundledCodexExecutable());
} catch {
return false;
}
}
function migratedCommands(plugin: string): string {
return join(plugin, ".codex-plugin", "migrated-command-skills");
}
// Bind a receipt to the generated files observed in this installation.
// Entry names come from its directories, never from the saved digest.
async function verifiedCommandMigration(
installedRoot: string,
matchesSelected: (installedRoot: string) => Promise<boolean>,
signal?: AbortSignal,
): Promise<string | undefined> {
const digest = createHash("sha256");
const record = (...fields: (string | number)[]) =>
digest.update(JSON.stringify(fields)).update("\n");
async function visit(path: string, name: string): Promise<boolean> {
throwIfSignalAborted(signal);
const metadata = await lstat(path, { bigint: true });
if (
metadata.isSymbolicLink() ||
relative(path, await realpath(path)) !== ""
)
return false;
if (metadata.isDirectory()) {
record("directory", name);
for (const entry of (await readdir(path)).sort()) {
const child = join(path, entry);
if (!(await visit(child, name ? `${name}/${entry}` : entry)))
return false;
}
return sameInode(metadata, await lstat(path, { bigint: true }));
}
if (!metadata.isFile()) return false;
const file = await open(
path,
constants.O_RDONLY |
(constants.O_NOFOLLOW ?? 0) |
(constants.O_NONBLOCK ?? 0),
);
try {
const opened = await file.stat({ bigint: true });
if (!opened.isFile()) return false;
if (!sameInode(metadata, opened)) {
if (process.platform !== "win32") return false;
// Some Windows Node versions report a different device on an open handle.
const { sameCheckedFileDevice } = await import("./contract.js");
if (!(await sameCheckedFileDevice(file, { path, metadata }, opened)))
return false;
}
const contents = createHash("sha256")
.update(await file.readFile({ signal }))
.digest("hex");
record("file", name, Number(opened.mode & 0o111n), contents);
} finally {
await file.close();
}
return true;
}
throwIfSignalAborted(signal);
const installation = await lstat(installedRoot, { bigint: true }).catch(
nullIfMissingFileError,
);
if (
!installation?.isDirectory() ||
installation.ino === 0n ||
!(await matchesSelected(installedRoot))
)
return;
try {
const directory = migratedCommands(await realpath(installedRoot));
const parent = dirname(directory);
if (
!(await lstat(parent)).isDirectory() ||
relative(parent, await realpath(parent)) !== ""
)
return;
const root = await lstat(directory, { bigint: true }).catch(
nullIfMissingFileError,
);
if (root && (!root.isDirectory() || !(await visit(directory, "")))) return;
// Native activation replaces the installed directory even at the same version.
if (!sameInode(installation, await lstat(installedRoot, { bigint: true })))
return;
throwIfSignalAborted(signal);
return root ? `sha256:${digest.digest("hex")}` : "absent";
} catch (error) {
throwIfSignalAborted(signal);
if (
!["ENOENT", "ENOTDIR", "ELOOP", "EISDIR", "EACCES", "EPERM"].includes(
nodeErrorCode(error) ?? "",
)
)
throw error;
}
}
async function pluginContentsMatch(
source: string,
destination: string,
signal?: AbortSignal,
allowExtraFiles = false,
projection?: PluginRuntimeProjection,
generatedDirectory?: string,
): 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;
}
let entries = await readdir(source);
let nativeOutputs = 0;
if (generatedDirectory) {
const parent = dirname(generatedDirectory);
if (
parent === destination ||
(relative(parent, destination) === "" &&
(await sameFile(parent, destination)))
) {
// The installer removes old command output before regenerating it. Resolve
// its source spelling on volumes that preserve case but ignore it on lookup.
const path = join(source, basename(generatedDirectory));
const original = await lstat(path).catch(nullIfMissingFileError);
if (original?.isSymbolicLink()) return false;
if (original) {
const name = basename(await realpath(path));
entries = entries.filter((entry) => entry !== name);
}
const installed = await lstat(generatedDirectory).catch(
nullIfMissingFileError,
);
if (installed) {
if (!installed.isDirectory()) return false;
nativeOutputs = 1;
}
}
}
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 + nativeOutputs !==
(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,
generatedDirectory,
))
) {
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 cwd = process.cwd();
const requestedRoots = options.protectedRoot ?? cwd;
const protectedRoot =
typeof requestedRoots === "string" ? [requestedRoots] : [...requestedRoots];
const callerDirectories = new Set([cwd, options.currentDirectory ?? 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,
...(options.discoveryProtectedRoots ?? []),
];
for (const directory of callerDirectories) {
const physical =
directory === cwd
? cwd
: await realpath(directory).catch(() => undefined);
// A filesystem-root launch directory also contains the operator's installed tools.
// Explicit scan roots and enclosing checkouts are already in protectedRoot.
if (
protectedRoot.length === 0 ||
physical === undefined ||
dirname(physical) !== physical
)
discoveryRoots.push(directory);
}
const missingBoundaryMessage =
"Could not establish the saved checkout boundary for Python discovery. Set PYTHON to an absolute trusted interpreter.";
if (options.configuredPath !== undefined) {
if (
!isPythonPathCandidate(options.configuredPath) &&
options.allowPathLookup === false
)
throw new PluginPythonUnavailableError(missingBoundaryMessage);
return await requirePython(
options.configuredPath,
"configured plugin Python",
environment,
isPythonPathCandidate(options.configuredPath)
? protectedRoot
: discoveryRoots,
options.signal,
);
}
const inherited = environmentValue(environment, "PYTHON", true);
if (inherited) {
if (!isPythonPathCandidate(inherited) && options.allowPathLookup === false)
throw new PluginPythonUnavailableError(missingBoundaryMessage);
const roots = isPythonPathCandidate(inherited)
? protectedRoot
: discoveryRoots;
// Check an explicit literal path with the same repository protections as the launch.
const candidate =
isExplicitPathWithTrailingWhitespace(inherited, process.platform) &&
(await resolveTrustedExecutable(
expandHomeForLookup(inherited, environment),
environment,
roots,
))
? inherited
: inherited.trim();
return await requirePython(
candidate,
"PYTHON",
environment,
roots,
options.signal,
);
}
let managedRoots = options.managedRuntimeRoots;
if (managedRoots === undefined) {
try {
const cache =
environmentValue(environment, "XDG_CACHE_HOME", true) ||
join(options.homeDirectory ?? homedir(), ".cache");
managedRoots = [join(cache, "codex-runtimes", "codex-primary-runtime")];
} catch (error) {
// A numeric Linux UID can lack a home for the optional managed cache.
if (
process.platform !== "linux" ||
(error as { info?: NodeJS.ErrnoException }).info?.code !== "ENOENT"
)
throw error;
managedRoots = [];
}
}
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;
}
}
if (options.allowPathLookup === false)
throw new PluginPythonUnavailableError(missingBoundaryMessage);
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 {
return {
...pythonUtf8Environment(environment),
PYTHON: python,
CODEX_SECURITY_PYTHON_COMMAND: python,
CODEX_CLI_PATH: resolveCodexCommand(environment).command,
};
}
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 });
}
// A child can finish or reject a request before the parent finishes writing it.
export function isDisconnectedChildStdin(
error: NodeJS.ErrnoException,
): boolean {
return [
"EPIPE",
"ECONNRESET",
"ENOTCONN",
"EOF",
"ERR_STREAM_DESTROYED",
].includes(error.code ?? "");
}
export async function runCodexCommand(
command: CodexCommand,
args: readonly string[] | ((executable: string) => readonly string[]),
environment: ProcessEnvironment,
input?: string | Uint8Array,
launchSignal?: AbortSignal | (() => AbortSignal),
{
registrationHandshake = false,
stdinPrefix,
cwd,
}: {
registrationHandshake?: boolean;
stdinPrefix?: string;
cwd?: string;
} = {},
): Promise<CodexCommandResult> {
const campaign = campaignExecutable(command.command, environment);
const selected = campaign && (await campaign);
const executable = selected?.executable ?? command.command;
const commandArgs = typeof args === "function" ? args(executable) : args;
const signal =
typeof launchSignal === "function" ? launchSignal() : launchSignal;
const cancellation = registrationHandshake
? new AbortController()
: undefined;
const abort = () => cancellation?.abort(signal?.reason);
const commandSignal = cancellation?.signal ?? signal;
const child = spawn(
executablePathForSpawn(executable),
[...(command.args ?? []), ...commandArgs],
{
cwd,
env: selected?.environment ?? environment,
stdio: registrationHandshake
? ["pipe", "pipe", "pipe", "pipe"]
: ["pipe", "pipe", "pipe"],
windowsHide: true,
signal: commandSignal,
},
);
let stdout = "";
let stderr = "";
let processError: Error | undefined;
const control = child.stdio[3] as Duplex | undefined;
control?.once("data", () => {
// The helper cannot change the output until the host allows the transaction.
signal?.removeEventListener("abort", abort);
if (signal?.aborted) abort();
else control.end("!");
});
control?.on("error", (error: NodeJS.ErrnoException) => {
if (!isDisconnectedChildStdin(error)) processError = error;
});
child.stdout.setEncoding("utf8");
child.stderr.setEncoding("utf8");
child.stdout.on("data", (chunk: string) => {
stdout += chunk;
});
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 (!isDisconnectedChildStdin(error)) processError = error;
});
child.once("close", (exitCode) =>
processError === undefined
? resolve({ success: exitCode === 0, exitCode, stdout, stderr })
: reject(processError),
);
});
let forceTermination: ReturnType<typeof setTimeout> | undefined;
const settleCanceledChild = () => {
if (!commandSignal?.aborted) return;
if (child.exitCode === null && child.signalCode === null) {
// spawn already sent SIGTERM. Give the command time to exit cleanly.
forceTermination ??= setTimeout(() => child.kill("SIGKILL"), 1_000);
return;
}
child.stdin.destroy();
child.stdout.destroy();
child.stderr.destroy();
control?.destroy();
};
commandSignal?.addEventListener("abort", settleCanceledChild, { once: true });
child.once("exit", settleCanceledChild);
if (commandSignal?.aborted) settleCanceledChild();
if (registrationHandshake) {
signal?.addEventListener("abort", abort, { once: true });
if (signal?.aborted) abort();
}
try {
if (stdinPrefix !== undefined) child.stdin.write(stdinPrefix);
child.stdin.end(input);
return await completion;
} finally {
if (registrationHandshake) signal?.removeEventListener("abort", abort);
control?.destroy();
clearTimeout(forceTermination);
commandSignal?.removeEventListener("abort", settleCanceledChild);
child.removeListener("exit", settleCanceledChild);
}
}
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 = (executable: string) => [
"sandbox",
"--",
executable,
"--version",
];
signal?.throwIfAborted();
let timeout: AbortSignal | undefined;
let detail: string;
try {
const result = await runCodexCommand(
command,
args,
environment,
undefined,
() => {
// Campaign tool selection happens before the sandbox process starts.
signal?.throwIfAborted();
timeout = AbortSignal.timeout(SANDBOX_PROBE_TIMEOUT_MILLISECONDS);
return 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();
if (timeout?.aborted)
throw new SandboxUnavailableError(
`Codex sandbox probe timed out after ${SANDBOX_PROBE_TIMEOUT_MILLISECONDS / 1000} seconds.`,
{ cause: error },
);
detail = processErrorDetail(error);
}
const guidance =
process.platform === "linux"
? "\nOn 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."
: "";
throw new SandboxUnavailableError(
`Codex could not run a command in its sandbox: ${detail}\nTo reproduce, run '${command.command} ${args(command.command).join(" ")}'.${guidance}`,
);
}
class RolledBackPluginActivationError extends Error {}
function isRolledBackPluginActivation(error: unknown): boolean {
return (
error instanceof PluginBootstrapError &&
error.cause instanceof RolledBackPluginActivationError
);
}
async function runPluginCommand(
command: CodexCommand,
args: readonly string[],
environment: ProcessEnvironment,
signal?: AbortSignal,
): Promise<string> {
try {
const run = (argv: readonly string[], cwd?: string) =>
runCodexCommand(command, argv, environment, undefined, signal, { cwd });
let result = await run(args);
const source = args[1] === "marketplace" ? args[3] : undefined;
if (
result.exitCode === 1 &&
source?.includes("#") &&
result.stderr
.split(/\r?\n/u)
.includes("Error: --ref is only supported for git marketplace sources")
) {
// Native Codex parsed a literal hash in the local path as a Git ref.
result = await run(["plugin", "marketplace", "add", "."], source);
}
const { success, exitCode, stdout, stderr } = result;
if (!success) {
const detail =
stderr.trim() ||
stdout.trim() ||
`Codex exited with status ${exitCode}.`;
// This native headline is emitted only after the previous entry was
// restored. The Windows message itself may be localized.
if (
process.platform === "win32" &&
args[0] === "plugin" &&
args[1] === "add" &&
exitCode === 1 &&
/^Error: failed to activate updated plugin cache entry: [^\r\n]+ \(os error 5\)(?:\r?\n|$)/u.test(
stderr,
) &&
!stderr.includes("failed to restore previous cache entry")
)
throw new RolledBackPluginActivationError(detail);
throw new Error(detail);
}
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);
}
export 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)
? expandHomeForLookup(candidate, environment)
: candidate,
environment,
protectedRoot,
);
if (command === null) return null;
try {
const { stdout } = await execFile(
command.executable,
["-I", "-c", PLUGIN_PYTHON_PROBE],
{
env: command.environment,
encoding: "utf8",
timeout: PLUGIN_PYTHON_PROBE_TIMEOUT_MS,
windowsHide: true,
signal,
},
);
return stdout.trim() === PLUGIN_PYTHON_READY ? command.executable : null;
} catch (error) {
if (signal?.aborted) throw error;
return null;
}
}
export function isPythonPathCandidate(candidate: string): boolean {
return candidate.includes("/") || candidate.includes("\\");
}
/** @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]) => sameInode(leftMetadata, rightMetadata),
() => false,
);
}
export function resolveInputPath(
value: string,
directory = process.cwd(),
environment: ProcessEnvironment = process.env,
): AbsolutePath {
if (value === "~") value = expandHome("~", environment);
else if (value.startsWith("~/") || value.startsWith("~\\")) {
const home = expandHome("~", environment);
const suffix = value.startsWith("~\\")
? value.slice(2).split("\\").filter(Boolean).join(sep)
: value.slice(2);
value = home === "" ? suffix : `${home}${sep}${suffix}`;
}
return resolveTargetPath(value, directory) as AbsolutePath;
}
/** Resolve through the last parent traversal while retaining aliases in the remaining path. */
export async function resolveParentTraversal(
path: string,
{ allowMissing = false }: { allowMissing?: boolean } = {},
): Promise<string> {
const parts = path.split(sep);
const parent = parts.lastIndexOf("..");
if (parent === -1) return path;
const prefix = parts.slice(0, parent + 1).join(sep);
// A new output directory can be spelled missing/../scan before its parent exists.
if (
allowMissing &&
(await stat(prefix).catch(nullIfMissingFileError)) === null
) {
return resolve(path);
}
// Resolve each directory before moving to its parent. Some runtimes collapse
// a literal ".." inside realpath before consulting the filesystem.
const before =
parts.slice(0, parent).join(sep) || (isAbsolute(path) ? sep : ".");
const physical = dirname(
await realpath(await resolveParentTraversal(before)),
);
if (!(await sameFile(prefix, physical)))
throw new InvalidTargetError(`Repository path changed: ${prefix}`);
return join(physical, ...parts.slice(parent + 1));
}
export function expandHomeForLookup(
value: string,
environment: ProcessEnvironment = process.env,
): 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()]);