@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
384 lines (355 loc) • 15.5 kB
text/typescript
import { configWriteLockFailureMessage, withConfigWriteLockHeld, publishConfigWrite, watchConfigWriteTargets, publishConfigWriteTarget, type LockHandle } from "./config-write-lock";
import { codexHomeIsAbsent } from "./codex-home-owner";
/**
* prompt-journal.ts — the write transaction behind the prompt-layer surface.
*
* Two files must move together: `opencodex-prompt.json` (the source of truth for
* custom layers) and `config.toml` (which carries the generated projection).
* Atomic rename makes each write individually torn-free; it does nothing about
* a crash between them, or about another writer touching a file after we read
* it. That is what this module is for.
*
* THE JOURNAL IS PREPARED INTENT, NOT A COMMIT. Commit is deleting the journal
* after both targets verify against the post-image. So a journal found on disk
* always means the transaction never committed, and recovery rolls BACK. An
* earlier design rolled forward from the post-image while also claiming a failed
* request changes nothing; an audit showed the two rules cannot both hold.
*
* RECOVERY NEVER WRITES A FILE IT DOES NOT RECOGNISE. Each target is classified
* independently against the pre- and post-image hashes, and a single
* unrecognised target aborts the whole recovery. The failure this prevents is
* concrete: crash after writing config.toml, user or Codex then edits it,
* recovery sees a mismatch and overwrites their work with a stale image.
*/
import type { AtomicWriteHooks } from "../config/atomic-write";
import { existsSync, mkdirSync, openSync, closeSync, fsyncSync, readFileSync, unlinkSync, writeFileSync } from "node:fs";
import { dirname, resolve } from "node:path";
import { createHash, randomBytes } from "node:crypto";
import { forgetEphemeralSecretPath, hardenSecretPath, windowsSecretAclApplies } from "../lib/windows-secret-acl";
import { renameAtomicFile } from "../lib/windows-atomic-replace";
const FILE_MODE = 0o600;
const DIR_MODE = 0o700;
export function hashBytes(bytes: string | null): string {
return bytes === null
? "\0absent"
: createHash("sha256").update(bytes).digest("hex");
}
function readOrNull(path: string): string | null {
try {
if (!existsSync(path)) return null;
return readFileSync(path, "utf8");
} catch {
return null;
}
}
/**
* fsync the containing directory so a rename survives a crash. Fsyncing the file
* alone does not make its directory entry durable.
*
* Windows has no directory fsync; `hardenSecretPath` covers the ACL side and the
* durability gap is documented as a WP1 acceptance item — the journal is still
* written first, so the worst case is a recovery that reports
* `recovery_required` rather than one that loses data silently.
*/
function fsyncDir(path: string): void {
if (process.platform === "win32") return;
let fd: number | undefined;
try {
fd = openSync(dirname(path), "r");
fsyncSync(fd);
} catch {
/* best effort: a filesystem may refuse to fsync a directory */
} finally {
if (fd !== undefined) {
try { closeSync(fd); } catch { /* already closed */ }
}
}
}
/** Write at mode 0600 from creation — a later chmod leaves a readable window. */
export function durableWrite(path: string, content: string, hooks: AtomicWriteHooks = {}): void {
const tmp = `${path}.ocx.${process.pid}.${randomBytes(4).toString("hex")}.tmp`;
let fd: number | undefined;
try {
writeFileSync(tmp, content, { encoding: "utf8", mode: FILE_MODE });
// The journal carries full config.toml bytes (provider credentials):
// hardening must fail closed, matching the token/tray writers.
if (windowsSecretAclApplies()) hardenSecretPath(tmp, { required: true, timeoutMemoKey: path });
fd = openSync(tmp, "r+");
fsyncSync(fd);
closeSync(fd);
fd = undefined;
// Windows can refuse the replace with EBUSY/EPERM/EACCES while a scanner
// still holds the target; the shared helper retries that briefly. Losing
// this publish breaks journal restore, so it should not fail on a blink.
hooks.beforeRename?.(tmp, path);
renameAtomicFile(tmp, path, undefined, "prompt-journal", hooks);
hooks.afterRename?.(path);
// The temp is renamed away: proven absent — release its ACL memos.
forgetEphemeralSecretPath(tmp);
fsyncDir(path);
} catch (error) {
try { if (fd !== undefined) closeSync(fd); } catch { /* ignore */ }
if (!existsSync(tmp)) {
// Explicit non-existence is proven absence — release even when the
// failure happened before/while the temp disappeared.
forgetEphemeralSecretPath(tmp);
} else {
try {
unlinkSync(tmp);
forgetEphemeralSecretPath(tmp);
} catch (cleanupError) {
if ((cleanupError as NodeJS.ErrnoException | undefined)?.code === "ENOENT") {
forgetEphemeralSecretPath(tmp);
}
/* residual temp: memos stay (fail-closed) */
}
}
throw error;
}
}
export function durableDelete(path: string, hooks: AtomicWriteHooks = {}): void {
try {
hooks.validateBeforeRename?.(path);
if (existsSync(path)) unlinkSync(path);
hooks.afterRename?.(path);
fsyncDir(path);
} catch (error) {
// Only absence is the state we wanted; every other deletion failure must
// surface — recovery and commit evidence depend on the file being gone.
if ((error as NodeJS.ErrnoException | undefined)?.code !== "ENOENT") throw error;
}
}
/**
* Exclusive create for backups: a timestamp alone can collide, and a salvage
* whose safety net silently overwrote an earlier one is not a safety net.
* Throws if the path already exists.
*/
export function durableWriteExclusive(path: string, content: string): void {
let fd: number | undefined;
try {
writeFileSync(path, content, { encoding: "utf8", mode: FILE_MODE, flag: "wx" });
if (process.platform === "win32") hardenSecretPath(path, { required: false });
fd = openSync(path, "r+");
fsyncSync(fd);
closeSync(fd);
fd = undefined;
fsyncDir(path);
} catch (error) {
try { if (fd !== undefined) closeSync(fd); } catch { /* ignore */ }
throw error;
}
}
export function ensureDir(path: string): void {
const dir = dirname(path);
if (!existsSync(dir)) mkdirSync(dir, { recursive: true, mode: DIR_MODE });
}
// ---------------------------------------------------------------------------
// Envelope
//
// Line 1 is `ocx-journal-v1 <sha256 of line 2>`; line 2 is the record. The
// checksum is verified BEFORE anything is read from it. An earlier design said
// "restore from the pre-image if it is intact" for a journal that had failed its
// own checksum — restoring from a document you have just declared untrustworthy.
// Any checksum failure or truncation is now recovery_required: nothing read,
// nothing written.
// ---------------------------------------------------------------------------
export interface JournalRecord {
configPath: string;
storePath: string;
preConfig: string;
postConfig: string;
preStore: string;
postStore: string;
/** null means the file should not exist in that image */
postConfigBytes: string | null;
postStoreBytes: string | null;
preConfigBytes: string | null;
preStoreBytes: string | null;
}
const ENVELOPE_TAG = "ocx-journal-v1";
export function encodeJournal(record: JournalRecord): string {
const body = JSON.stringify(record);
const sum = createHash("sha256").update(body).digest("hex");
return `${ENVELOPE_TAG} ${sum}\n${body}\n`;
}
/** null for absent, malformed, truncated, or checksum-mismatched journals. */
export function decodeJournal(raw: string | null): JournalRecord | null {
if (raw === null) return null;
const newline = raw.indexOf("\n");
if (newline === -1) return null;
const header = raw.slice(0, newline);
const body = raw.slice(newline + 1).replace(/\n$/, "");
const [tag, sum] = header.split(" ");
if (tag !== ENVELOPE_TAG || !sum) return null;
if (createHash("sha256").update(body).digest("hex") !== sum) return null;
try {
const parsed = JSON.parse(body) as JournalRecord;
if (typeof parsed?.configPath !== "string" || typeof parsed?.storePath !== "string") return null;
return parsed;
} catch {
return null;
}
}
// ---------------------------------------------------------------------------
// Classification — the guard that keeps recovery from destroying other work.
// ---------------------------------------------------------------------------
export type TargetState = "pre" | "post" | "unknown";
export function classify(actual: string | null, pre: string, post: string): TargetState {
const hash = hashBytes(actual);
if (hash === post) return "post";
if (hash === pre) return "pre";
return "unknown";
}
export type RecoveryOutcome =
| { ok: true; action: "none" | "committed" | "rolled-back" }
| { ok: false; error: "recovery_required" | "unsafe"; detail: string };
export interface RecoveryTargets {
configPath: string;
storePath: string;
}
/** Lexical path identity only: never resolve an untrusted journal path through the filesystem. */
export function sameRecoveryPath(
recordedPath: string,
expectedPath: string,
platform: NodeJS.Platform = process.platform,
): boolean {
const recorded = resolve(recordedPath);
const expected = resolve(expectedPath);
return platform === "win32"
? recorded.toLowerCase() === expected.toLowerCase()
: recorded === expected;
}
/**
* Run at service start and at every lock acquisition. Never from a read.
*
* A journal on disk means commit never happened, so the default is rollback.
* The single exception is not a roll-forward: when BOTH targets already hold the
* post-image the writes had finished and only the journal deletion was missing.
*
* The expected targets come from the active prompt-layer configuration, not
* from the journal. The envelope checksum detects accidental corruption, not a
* same-user forgery, so recovery binds the decoded record to those trusted
* paths before reading either target.
*/
export function recoverIfNeeded(
journalPath: string,
expectedTargets: RecoveryTargets,
heldConfigWriteLock?: LockHandle,
): RecoveryOutcome {
if (codexHomeIsAbsent(dirname(expectedTargets.configPath)) && !existsSync(journalPath)) return { ok: true, action: "none" };
const locked = withConfigWriteLockHeld(expectedTargets.configPath, heldConfigWriteLock, held => {
watchConfigWriteTargets(held, [journalPath, expectedTargets.storePath]);
const raw = readOrNull(journalPath);
if (raw === null) return { ok: true, action: "none" };
const record = decodeJournal(raw);
if (record === null) {
return {
ok: false,
error: "recovery_required",
detail: `journal at ${journalPath} failed its checksum or is truncated; nothing was read from it`,
};
}
if (
!sameRecoveryPath(record.configPath, expectedTargets.configPath)
|| !sameRecoveryPath(record.storePath, expectedTargets.storePath)
) {
return {
ok: false,
error: "recovery_required",
detail: `journal at ${journalPath} does not match the active prompt-layer paths; nothing was read from its targets`,
};
}
const config = classify(readOrNull(expectedTargets.configPath), record.preConfig, record.postConfig);
const store = classify(readOrNull(expectedTargets.storePath), record.preStore, record.postStore);
if (config === "unknown" || store === "unknown") {
const which = config === "unknown" ? expectedTargets.configPath : expectedTargets.storePath;
return {
ok: false,
error: "recovery_required",
detail: `${which} matches neither the pre- nor post-image; it was modified outside opencodex`,
};
}
if (config === "post" && store === "post") {
try {
publishConfigWriteTarget(expectedTargets.configPath, held, journalPath, (destination, hooks) => durableDelete(destination, hooks));
} catch (error) {
return {
ok: false,
error: "recovery_required",
detail: `commit confirmed but the journal could not be removed: ${error instanceof Error ? error.message : String(error)}`,
};
}
return { ok: true, action: "committed" };
}
// Revalidate each target immediately before its own restore: a target that
// changed since the initial classification must not be overwritten.
if (config === "post") {
if (classify(readOrNull(expectedTargets.configPath), record.preConfig, record.postConfig) !== "post") {
return {
ok: false,
error: "recovery_required",
detail: `${expectedTargets.configPath} changed after its first classification; refusing to overwrite it`,
};
}
try {
publishConfigWrite(expectedTargets.configPath, held, (destination, hooks) => restore(destination, record.preConfigBytes, expectingImage(hooks, record.postConfig)));
} catch (error) {
return {
ok: false,
error: "recovery_required",
detail: `rollback of ${expectedTargets.configPath} failed mid-write: ${error instanceof Error ? error.message : String(error)}`,
};
}
}
if (store === "post") {
if (classify(readOrNull(expectedTargets.storePath), record.preStore, record.postStore) !== "post") {
return {
ok: false,
error: "recovery_required",
detail: `${expectedTargets.storePath} changed after its first classification; refusing to overwrite it`,
};
}
try {
publishConfigWriteTarget(expectedTargets.configPath, held, expectedTargets.storePath, (destination, hooks) => restore(destination, record.preStoreBytes, expectingImage(hooks, record.postStore)));
} catch (error) {
return {
ok: false,
error: "recovery_required",
detail: `rollback of ${expectedTargets.storePath} failed mid-write: ${error instanceof Error ? error.message : String(error)}`,
};
}
}
try {
publishConfigWriteTarget(expectedTargets.configPath, held, journalPath, (destination, hooks) => durableDelete(destination, hooks));
} catch (error) {
return {
ok: false,
error: "recovery_required",
detail: `rollback restored but the journal could not be removed: ${error instanceof Error ? error.message : String(error)}`,
};
}
return { ok: true, action: "rolled-back" } as RecoveryOutcome;
});
return locked.ok ? locked.value as RecoveryOutcome : { ok: false, error: locked.error === "unsafe" ? "unsafe" : "recovery_required", detail: configWriteLockFailureMessage(locked) };
}
function restore(path: string, bytes: string | null, hooks: AtomicWriteHooks): void {
if (bytes === null) durableDelete(path, hooks);
else durableWrite(path, bytes, hooks);
}
/**
* Bind a write to the image the caller classified. The rename retry hooks check
* path and inode identity only; an in-place edit by another process during a
* Windows sharing-violation retry keeps the inode, so without this re-read a
* later attempt would replace newer bytes. Checked before every attempt.
*/
export function expectingImage(hooks: AtomicWriteHooks, expectedHash: string): AtomicWriteHooks {
return {
...hooks,
validateBeforeRename: (targetPath: string) => {
hooks.validateBeforeRename?.(targetPath);
if (hashBytes(readOrNull(targetPath)) !== expectedHash) {
throw new Error(targetPath + " changed during the write; refusing to overwrite it. Files and recovery evidence were preserved.");
}
},
};
}