@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
614 lines (584 loc) • 25.5 kB
text/typescript
import {
type BigIntStats,
chmodSync,
closeSync,
fchmodSync,
fsyncSync,
fstatSync,
linkSync,
lstatSync,
openSync,
realpathSync,
truncateSync,
unlinkSync,
writeFileSync,
} from "node:fs";
import { basename, dirname, join } from "node:path";
import { recordOwnedConfigPath } from "../lib/config-ownership";
import { assertNotRealCodexHomeUnderTest, assertNotRealHomeUnderTest } from "../lib/test-home-guard";
import {
forgetEphemeralSecretPath,
flushWindowsSecretAclReapsBeforeRemoval,
hardenSecretPath,
hardenSecretPathAsync,
reattributeHardenedSecretPath,
windowsSecretAclReapPendingForPath,
WindowsSecretAclSettleTimeoutError,
} from "../lib/windows-secret-acl";
import {
renameAtomicFile,
renameAtomicFileAsync,
} from "../lib/windows-atomic-replace";
import {
catalogReadOnlyRepairFor,
publishWithReadOnlyRepair,
setCatalogReadOnlyRepairForTests as setCatalogReadOnlyRepairOverride,
} from "../lib/codex-catalog-read-only";
import { getConfigDir } from "./paths";
let atomicSequence = 0;
const aclDestinations = new Map<string, Set<string>>();
/** Track overlapping writes, refusing only children retained past their timeout belt. */
function admitAtomicAclWork(target: string, temp: string, enabled: boolean): (() => void) | undefined {
if (!enabled || !windowsHardeningApplies()) return undefined;
const destination = join(realpathSync(dirname(target)), basename(target));
const key = process.platform === "win32" ? destination.toLowerCase() : destination;
const temps = aclDestinations.get(key) ?? new Set<string>();
if ([...temps].some(windowsSecretAclReapPendingForPath)) throw new WindowsSecretAclSettleTimeoutError();
temps.add(temp);
aclDestinations.set(key, temps);
const release = (): void => {
temps.delete(temp);
if (temps.size === 0) aclDestinations.delete(key);
};
return () => {
if (windowsSecretAclReapPendingForPath(temp)) {
// Caller settlement is bounded; admission resumes only after actual handle release.
void flushWindowsSecretAclReapsBeforeRemoval(temp).then(release);
} else release();
};
}
/**
* Whether this writer's Windows ACL branch applies.
*
* Deliberately a local override rather than the ACL module's
* `windowsSecretAclApplies()`. That one is flipped by many unrelated suites
* through `setPlatformForTests("win32")`, and honouring it here would make every
* such suite start running icacls against config writes on a POSIX runner. The
* gate a cost fix needs is one only the cost tests can open.
*/
let windowsHardeningOverride: boolean | null = null;
function windowsHardeningApplies(): boolean {
return windowsHardeningOverride ?? process.platform === "win32";
}
/** Test seam: drive the Windows hardening branch on a POSIX runner. Null restores. */
export function setWindowsHardeningForTests(enabled: boolean | null): void {
windowsHardeningOverride = enabled;
}
/** Shared process-wide suffix source for config-owned atomic sibling files. */
export function nextAtomicTempSequence(): number {
return ++atomicSequence;
}
/** Internal error classifier shared by config backup and atomic-write paths. */
export function isMissingPathError(error: unknown): boolean {
return (error as NodeJS.ErrnoException | undefined)?.code === "ENOENT";
}
export type { AtomicRenameIO } from "../lib/windows-atomic-replace";
export { renameAtomicFile } from "../lib/windows-atomic-replace";
export interface AtomicWriteIO {
write: (path: string, content: string) => void;
harden: (path: string) => void;
rename: (source: string, destination: string) => void;
truncate: (path: string) => void;
unlink: (path: string) => void;
}
export interface AtomicWriteHooks {
afterTempWrite?: (tempPath: string, targetPath: string) => void;
beforeRename?: (tempPath: string, targetPath: string) => void;
validateBeforeRename?: (targetPath: string) => void;
/** Publication receipt; runs before any post-rename cleanup can fail. */
afterRename?: (targetPath: string) => void;
}
/**
* Test seam for the read-only catalog repair (#8358). `null` disables it, `undefined`
* restores the production rule (win32 and the OpenCodex catalog artifact only).
*/
export function setCatalogReadOnlyRepairForTests(
repair: Parameters<typeof setCatalogReadOnlyRepairOverride>[0],
): void {
setCatalogReadOnlyRepairOverride(repair);
}
export class AtomicWriteResidualTempError extends Error {
constructor(readonly tempPath: string, readonly hardened = true, options?: ErrorOptions) {
super(`Atomic config write left a ${hardened ? "hardened " : ""}zero-byte temporary file`, options);
this.name = "AtomicWriteResidualTempError";
}
}
export class AtomicWriteSecretResidualError extends Error {
constructor(readonly tempPath: string, options?: ErrorOptions) {
super("Atomic config write could not scrub or remove a secret-bearing temporary file", options);
this.name = "AtomicWriteSecretResidualError";
}
}
/**
* Resolve a write target through any symlink before the temp+rename dance so
* dotfiles-managed links survive an atomic replacement.
*/
export function resolveWriteTarget(path: string): string {
try {
return realpathSync(path);
} catch (cause) {
let entry;
try {
entry = lstatSync(path);
} catch (error) {
if (isMissingPathError(error)) return path;
throw error;
}
if (entry.isSymbolicLink()) {
throw new Error(`refusing to replace unresolvable symlinked write target: ${path}`, { cause });
}
return path;
}
}
function assertResolvedTargetAllowed(path: string, target: string): void {
// Codex-home files (catalog, models cache, journal, config.toml, profile) are addressed through
// CODEX_HOME, which falls back to os.homedir() when a test's teardown deletes it, and os.homedir()
// ignores HOME. That is how test runs rewrote the real catalog (#6529), so every atomic write
// whose directory is the real Codex home is refused under an armed test process.
let realParent: string | null = null;
try {
realParent = realpathSync(dirname(target));
} catch {
realParent = null;
}
assertNotRealCodexHomeUnderTest(realParent ?? dirname(target));
if (target === path) {
if (realParent !== null && realParent !== dirname(target)) assertNotRealHomeUnderTest(realParent);
return;
}
assertNotRealHomeUnderTest(dirname(target));
}
// Zero dev/ino is refused only where publication relies on stable identity (exclusive
// recovery copies); ordinary saves must keep working on filesystems that report zero.
function assertPrivateTempDescriptor(path: string, descriptor: number, requireStableIdentity = false): void {
const opened = fstatSync(descriptor, { bigint: true });
const linked = lstatSync(path, { bigint: true });
if (!opened.isFile() || !linked.isFile()
|| (requireStableIdentity && (opened.dev === 0n || opened.ino === 0n))
|| opened.dev !== linked.dev || opened.ino !== linked.ino) {
throw new Error("atomic temporary file identity changed before write");
}
if (process.platform !== "win32" && (opened.mode & 0o777n) !== 0o600n) {
throw new Error("atomic temporary file permissions are not owner-only");
}
}
/**
* Carry the harden applied to the empty temp across the content write.
*
* The temp is hardened before it holds a byte, and then `atomicWriteFile` hardens
* it again before the rename. The second call used to be a full icacls sequence
* rather than a memo hit, because the ACL memo's freshness component is
* `ctimeNs` and libuv reports that from the NTFS ChangeTime, which a data write
* moves. So every secret write on Windows applied the same three-step ACL twice:
* `/grant:r`, `/inheritance:r`, `/remove:g`, plus up to three `/findsid` probes,
* all of it to arrive at the ACL the file already had.
*
* It runs after the descriptor closes, not before, because Windows may not have
* published the new ChangeTime to a path query while the handle is still open;
* refreshing to a time the next reader will not see would leave the memo missing
* and change nothing. What licenses the shortcut is the identity assertion the
* caller makes immediately before the close, which proves this path resolves to
* the object the ACL was applied to, plus the object comparison inside
* `reattributeHardenedSecretPath`, which refuses to move the memo to a different
* object. Nothing is skipped on the strength of the pathname alone, and a
* refusal costs only the second full harden this is trying to avoid.
*/
function carryHardenAcrossContentWrite(path: string): void {
if (!windowsHardeningApplies()) return;
reattributeHardenedSecretPath(path);
}
/**
* Commit the directory entry a rename just wrote.
*
* Best effort by platform, not by importance: Windows has no directory descriptor to sync and
* some filesystems refuse the open, and failing a replacement that already happened would be
* worse than reporting it. The throw that matters is the temp's own `fsync`, which runs before
* the rename and stops it.
*/
export function syncParentDirectory(target: string): void {
if (process.platform === "win32") return;
let descriptor: number | undefined;
try {
descriptor = openSync(dirname(target), "r");
fsyncSync(descriptor);
} catch {
/* the rename already landed; a directory that cannot be synced is not a reason to undo it */
} finally {
if (descriptor !== undefined) { try { closeSync(descriptor); } catch { /* already closed */ } }
}
}
function writePrivateTempFile(
path: string,
content: string,
timeoutMemoKey: string,
onCreated: (descriptor: number) => void,
requireStableIdentity = false,
): void {
const descriptor = openSync(path, "wx", 0o600);
try {
onCreated(descriptor);
if (windowsHardeningApplies()) {
hardenSecretPath(path, { required: true, timeoutMemoKey, retryTimedOutOnce: true });
}
// Keyed on the REAL platform, not the override: on a POSIX host the mode is
// the boundary and `assertPrivateTempDescriptor` demands 0o600, which an
// ambient umask can otherwise take away from the open above.
if (process.platform !== "win32") {
fchmodSync(descriptor, 0o600);
}
assertPrivateTempDescriptor(path, descriptor, requireStableIdentity);
writeFileSync(descriptor, content, { encoding: "utf-8" });
// Second assertion, after the content write: the object this path resolves
// to is still the object the ACL was applied to and the one we just wrote.
assertPrivateTempDescriptor(path, descriptor, requireStableIdentity);
} finally {
closeSync(descriptor);
}
carryHardenAcrossContentWrite(path);
}
/**
* The same private temp, filled by a writer that streams into the descriptor.
*
* For content that must not be held in memory as one string. The identity assertions, the
* ownership handshake and the hardening are the same; the difference is that the bytes arrive in
* bounded chunks and the descriptor is flushed before it closes.
*
* The `fsync` is not optional here and its failure is not swallowed. A replacement whose
* REPLACEMENT is not on disk can lose the rows it was supposed to retain, so the throw is what
* stops the rename from happening at all.
*/
function writePrivateTempFileWith(
path: string,
write: (descriptor: number) => void,
timeoutMemoKey: string,
onCreated: (descriptor: number) => void,
requireStableIdentity = false,
): void {
const descriptor = openSync(path, "wx", 0o600);
try {
onCreated(descriptor);
if (windowsHardeningApplies()) {
hardenSecretPath(path, { required: true, timeoutMemoKey, retryTimedOutOnce: true });
}
if (process.platform !== "win32") fchmodSync(descriptor, 0o600);
assertPrivateTempDescriptor(path, descriptor, requireStableIdentity);
write(descriptor);
assertPrivateTempDescriptor(path, descriptor, requireStableIdentity);
fsyncSync(descriptor);
} finally {
closeSync(descriptor);
}
carryHardenAcrossContentWrite(path);
}
async function writePrivateTempFileAsync(
path: string,
content: string,
timeoutMemoKey: string,
onCreated: (descriptor: number) => void,
): Promise<void> {
const descriptor = openSync(path, "wx", 0o600);
try {
onCreated(descriptor);
if (windowsHardeningApplies()) {
await hardenSecretPathAsync(path, { required: true, timeoutMemoKey, retryTimedOutOnce: true });
}
if (process.platform !== "win32") {
fchmodSync(descriptor, 0o600);
}
assertPrivateTempDescriptor(path, descriptor);
writeFileSync(descriptor, content, { encoding: "utf-8" });
assertPrivateTempDescriptor(path, descriptor);
} finally {
closeSync(descriptor);
}
carryHardenAcrossContentWrite(path);
}
function atomicWriteFileToTarget(
path: string,
content: string | ((descriptor: number) => void),
target: string,
io?: AtomicWriteIO,
hooks: AtomicWriteHooks = {},
recordOwnership = true,
exclusive = false,
): void {
if (recordOwnership) recordOwnedConfigPath(getConfigDir(), path);
assertResolvedTargetAllowed(path, target);
const tmp = `${target}.ocx.${process.pid}.${nextAtomicTempSequence()}.tmp`;
const releaseAcl = admitAtomicAclWork(target, tmp, io === undefined);
let hardened = false;
let ownsTemp = false;
// Cleanup must not consume the destination's recovery attempt for a later write.
let cleanupHarden = false;
let publicationAttempted = false;
let identity: BigIntStats | undefined;
const created = (descriptor: number): void => {
ownsTemp = true;
if (exclusive) identity = fstatSync(descriptor, { bigint: true });
};
const assertIdentity = (entry: string): BigIntStats => {
const current = lstatSync(entry, { bigint: true });
if (!identity?.isFile() || identity.dev === 0n || identity.ino === 0n || !current.isFile()
|| current.dev !== identity.dev || current.ino !== identity.ino) {
throw new Error("atomic exclusive publication identity changed");
}
return current;
};
const effective: AtomicWriteIO = io ?? {
write: (tempPath, value) => writePrivateTempFile(tempPath, value, path, created, exclusive),
harden: tempPath => {
// No chmod on the Windows branch: there it sets the read-only ATTRIBUTE,
// which is not the secret boundary and is not what protects this file, and
// its ChangeTime bump is what used to invalidate the harden memo one line
// later. On POSIX the mode IS the boundary, so it stays.
if (windowsHardeningApplies()) {
hardenSecretPath(tempPath, { required: true, timeoutMemoKey: path, retryTimedOutOnce: !cleanupHarden });
return;
}
try { chmodSync(tempPath, 0o600); } catch { /* platform may ignore chmod */ }
},
rename: (source, destination) => renameAtomicFile(source, destination, undefined, "config", hooks),
truncate: tempPath => truncateSync(tempPath, 0),
unlink: unlinkSync,
};
try {
if (io) ownsTemp = true;
// A streaming writer bypasses the string form of `write` and nothing else. Every later
// step -- harden, the pre-rename hooks, the rename and the whole residual-cleanup path,
// which still scrubs through `effective.write(tmp, "")` -- is shared with the string form.
if (typeof content === "function") writePrivateTempFileWith(tmp, content, path, created, exclusive);
else effective.write(tmp, content);
hooks.afterTempWrite?.(tmp, target);
if (exclusive) assertIdentity(tmp);
effective.harden(tmp);
hardened = true;
hooks.beforeRename?.(tmp, target);
hooks.validateBeforeRename?.(target);
if (exclusive) {
// link is an atomic no-replace publication on both NTFS and POSIX. A raced
// destination entry, including a symlink, is refused rather than followed.
assertIdentity(tmp);
publicationAttempted = true;
linkSync(tmp, target);
assertIdentity(target);
} else {
// The Codex catalog owner repairs its own read-only artifact (#8358); every
// other destination, and every other platform, keeps the plain rename.
const repair = catalogReadOnlyRepairFor(target);
if (repair) publishWithReadOnlyRepair(() => effective.rename(tmp, target), target, repair);
else effective.rename(tmp, target);
}
hooks.afterRename?.(target);
if (exclusive) { assertIdentity(tmp); effective.unlink(tmp); }
// The rename is only as durable as the directory entry recording it. Fsyncing the temp's
// CONTENT and then losing the entry in a power cut leaves the old file in place, or the
// directory in an indeterminate state, while the caller was told the replacement landed.
//
// Only the streaming form does this. It is the one that makes a durability claim -- a
// replacement is not an append, and losing it can lose the rows it was meant to keep -- and
// adding a directory sync to the string form would charge every config write for a promise
// its callers have never been given.
if (typeof content === "function") syncParentDirectory(target);
forgetEphemeralSecretPath(tmp);
} catch (cause) {
if (!ownsTemp) throw cause;
cleanupHarden = true;
let sharedTemp = false;
if (exclusive) {
try { sharedTemp = assertIdentity(tmp).nlink > 1n; } catch (error) {
if (isMissingPathError(error)) { forgetEphemeralSecretPath(tmp); throw cause; }
// The named entry is no longer ours. Neither truncate nor unlink it.
throw new AtomicWriteSecretResidualError(tmp, { cause });
}
}
let scrubbed = false;
try {
// A link syscall can publish and then report an error (e.g. a remote FS).
// Like initial config publication, cleanup after an attempt is unlink-only.
if (!publicationAttempted && !sharedTemp) { effective.truncate(tmp); scrubbed = true; }
} catch (error) {
if (isMissingPathError(error)) scrubbed = true;
else {
try { effective.write(tmp, ""); scrubbed = true; } catch { /* removal may still succeed */ }
}
}
let removed = false;
try {
if (exclusive) assertIdentity(tmp);
effective.unlink(tmp);
removed = true;
} catch (error) {
if (isMissingPathError(error)) removed = true;
else {
try { if (exclusive) assertIdentity(tmp); effective.unlink(tmp); removed = true; }
catch (retryError) { if (isMissingPathError(retryError)) removed = true; }
}
}
if (!removed && !scrubbed) throw new AtomicWriteSecretResidualError(tmp, { cause });
if (!removed && !hardened) {
try { effective.harden(tmp); hardened = true; } catch { /* reported below */ }
}
if (removed) forgetEphemeralSecretPath(tmp);
if (!removed) throw new AtomicWriteResidualTempError(tmp, hardened, { cause });
throw cause;
} finally { releaseAcl?.(); }
}
export function atomicWriteFile(
path: string,
content: string,
io?: AtomicWriteIO,
hooks: AtomicWriteHooks = {},
): void {
atomicWriteFileToTarget(path, content, resolveWriteTarget(path), io, hooks);
}
/**
* Atomically replace a file with bytes produced straight into the temporary descriptor.
*
* Same publication contract as {@link atomicWriteFile}: an exclusively created private temp, the
* identity assertions around the write, `hooks.validateBeforeRename` immediately before the
* rename, the platform-aware replace, and the residual cleanup on any failure. A custom
* {@link AtomicWriteIO} is not accepted, because the point of this form is that the default
* writer owns the descriptor.
*/
export function atomicWriteFileStreamed(
path: string,
write: (descriptor: number) => void,
hooks: AtomicWriteHooks = {},
): void {
atomicWriteFileToTarget(path, write, resolveWriteTarget(path), undefined, hooks);
}
/**
* Atomically replace the named directory entry without resolving a symlink at
* that entry. This is for files in directories writable by another process:
* a raced symlink is replaced, never followed to a more privileged target.
*/
export function atomicWriteFileNoFollow(
path: string,
content: string | Uint8Array,
io?: AtomicWriteIO,
hooks: AtomicWriteHooks = {},
options: { exclusive?: boolean } = {},
): void {
// Only the final entry is no-follow: the parent still resolves, because an
// OS alias above the configured root (a home junction, /tmp) is legitimate
// and Windows cannot exclusive-create a temp through a junction.
const value = typeof content === "string" ? content : (descriptor: number) => { writeFileSync(descriptor, content); };
// Recovery copies are deliberately unclaimed: uninstall must not own them.
atomicWriteFileToTarget(path, value, join(resolveWriteTarget(dirname(path)), basename(path)), io, hooks, !options.exclusive, options.exclusive);
}
/** Content fsync before rename is mandatory; parent-directory sync is best effort. */
export function atomicWriteFileNoFollowStreamed(
path: string,
write: (descriptor: number) => void,
hooks: AtomicWriteHooks = {},
): void {
atomicWriteFileToTarget(path, write, join(resolveWriteTarget(dirname(path)), basename(path)), undefined, hooks);
}
/**
* The no-follow replacement above, for rewriting a file whose uninstall ownership must stay as
* it was: it does not record the path in the owner manifest. Used to rewrite the OAuth downgrade
* backup, which a pre-registration install may have left deliberately unclaimed; claiming it
* here would let a later uninstall delete recovery data it never owned.
*/
export function atomicWriteFileNoFollowUnclaimed(path: string, content: string): void {
atomicWriteFileToTarget(path, content, join(resolveWriteTarget(dirname(path)), basename(path)), undefined, {}, false);
}
export interface AtomicWriteAsyncIO {
write: (path: string, content: string) => void | Promise<void>;
harden: (path: string) => void | Promise<void>;
rename: (source: string, destination: string) => void | Promise<void>;
truncate: (path: string) => void | Promise<void>;
unlink: (path: string) => void | Promise<void>;
}
export interface AtomicWriteAsyncTestSeam {
afterTempWrite?: (tempPath: string) => void | Promise<void>;
}
export async function atomicWriteFileAsync(
path: string,
content: string,
io?: AtomicWriteAsyncIO,
testSeam?: AtomicWriteAsyncTestSeam,
): Promise<void> {
let ownsTemp = false;
let cleanupHarden = false;
const effective: AtomicWriteAsyncIO = io ?? {
write: (tempPath, value) => writePrivateTempFileAsync(tempPath, value, path, () => { ownsTemp = true; }),
harden: async tempPath => {
// Same reasoning as the synchronous writer above.
if (windowsHardeningApplies()) {
await hardenSecretPathAsync(tempPath, { required: true, timeoutMemoKey: path, retryTimedOutOnce: !cleanupHarden });
return;
}
try { chmodSync(tempPath, 0o600); } catch { /* platform may ignore chmod */ }
},
// The read-only catalog repair (#8358) is wired only into the sync writer; no async
// caller writes the Codex catalog today. Route one through publishWithReadOnlyRepair too.
rename: renameAtomicFileAsync,
truncate: target => truncateSync(target, 0),
unlink: unlinkSync,
};
const target = resolveWriteTarget(path);
assertResolvedTargetAllowed(path, target);
const tmp = `${target}.ocx.${process.pid}.${nextAtomicTempSequence()}.tmp`;
const releaseAcl = admitAtomicAclWork(target, tmp, io === undefined);
let hardened = false;
let tempWasHardenedBeforeContent = false;
try {
if (io) ownsTemp = true;
await effective.write(tmp, content);
tempWasHardenedBeforeContent = io === undefined && windowsHardeningApplies();
await testSeam?.afterTempWrite?.(tmp);
await effective.harden(tmp);
hardened = true;
await effective.rename(tmp, target);
forgetEphemeralSecretPath(tmp);
} catch (cause) {
if (!ownsTemp) throw cause;
cleanupHarden = true;
// The async ACL belt bounds the writer, but it is not evidence that icacls released this
// path. Leave the temp in the existing residual state instead of racing an unlink against a
// live Windows handle. The default Windows writer hardens before writing secret bytes; a
// failure inside that initial harden leaves its still-empty temp behind.
if (windowsSecretAclReapPendingForPath(tmp)) {
throw new AtomicWriteResidualTempError(tmp, tempWasHardenedBeforeContent, { cause });
}
let scrubbed = false;
try {
await effective.truncate(tmp);
scrubbed = true;
} catch (error) {
if (isMissingPathError(error)) scrubbed = true;
else {
try { await effective.write(tmp, ""); scrubbed = true; } catch { /* removal may still succeed */ }
}
}
let removed = false;
try {
await effective.unlink(tmp);
removed = true;
} catch (error) {
if (isMissingPathError(error)) removed = true;
else {
try { await effective.unlink(tmp); removed = true; }
catch (retryError) { if (isMissingPathError(retryError)) removed = true; }
}
}
if (!removed && !scrubbed) throw new AtomicWriteSecretResidualError(tmp, { cause });
if (!removed && !hardened) {
try { await effective.harden(tmp); hardened = true; } catch { /* reported below */ }
}
if (removed) forgetEphemeralSecretPath(tmp);
if (!removed) throw new AtomicWriteResidualTempError(tmp, hardened, { cause });
throw cause;
} finally { releaseAcl?.(); }
}