@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
173 lines (162 loc) • 8.13 kB
text/typescript
import {
closeSync, constants, fstatSync, ftruncateSync, lstatSync, openSync, readSync, writeSync,
type BigIntStats,
} from "node:fs";
import { join } from "node:path";
import { redactUserPath } from "../../lib/redact";
import { hardenSecretPath, windowsSecretAclApplies } from "../../lib/windows-secret-acl";
import type { CatalogWriteAuditEvent } from "./write-audit-contract";
export const CODEX_CATALOG_AUDIT_FILE = "opencodex-catalog-audit.jsonl";
export const CATALOG_AUDIT_MAX_BYTES = 256 * 1024;
export const CATALOG_AUDIT_KEEP_RECORDS = 400;
export const CATALOG_AUDIT_MAX_EVENT_BYTES = 2 * 1024;
const MAX_HOME_CHARACTERS = 256;
const AUDIT_ACL_DEADLINE_MS = 1000;
const WRITERS = new Set([
"convergence", "retained-sync", "cache-from-catalog", "cache-invalidate",
"catalog-pull", "catalog-restore", "codex-restore", "sync-cache", "startup-cache",
]);
export function codexCatalogAuditPath(codexHome: string): string {
return join(codexHome, CODEX_CATALOG_AUDIT_FILE);
}
function safeCount(value: number | null | undefined): number | null {
return typeof value === "number" && Number.isSafeInteger(value) && value >= 0 ? value : null;
}
function auditLine(event: CatalogWriteAuditEvent): Buffer {
const writer = WRITERS.has(event.writer) ? event.writer : "other";
// Explicit projection: no argv, arbitrary event properties, model IDs or provider names.
return Buffer.from(`${JSON.stringify({
at: new Date().toISOString(), pid: process.pid, ppid: process.ppid,
command: writer,
opencodexHome: redactUserPath(event.opencodexHome).slice(0, MAX_HOME_CHARACTERS),
target: event.target, outcome: event.outcome, reason: event.reason,
intent: event.intent, writer,
configSource: event.configSource,
routedBefore: safeCount(event.routedBefore), routedAfter: safeCount(event.routedAfter),
})}\n`);
}
function regularPrivateFile(stat: BigIntStats): boolean {
// POSIX bits cannot prove NTFS privacy. Windows requires fresh-file ACL hardening.
return !windowsSecretAclApplies() && stat.isFile() && stat.nlink === 1n
&& stat.uid === BigInt(process.getuid?.() ?? -1) && (stat.mode & 0o777n) === 0o600n;
}
function sameFile(left: BigIntStats, right: BigIntStats): boolean {
return left.dev === right.dev && left.ino === right.ino && left.size === right.size
&& left.mtimeNs === right.mtimeNs && left.ctimeNs === right.ctimeNs;
}
/** Read at most the tail budget plus one byte to locate a complete first record. */
function readTail(fd: number, size: number): Buffer {
const start = Math.max(0, size - CATALOG_AUDIT_MAX_BYTES - 1);
const bytes = Buffer.alloc(size - start);
let length = 0;
while (length < bytes.length) {
const count = readSync(fd, bytes, length, bytes.length - length, start + length);
if (count === 0) break;
length += count;
}
if (length !== bytes.length) throw new Error("audit file changed during read");
if (start === 0) return bytes;
const boundary = bytes.indexOf(10);
return boundary === -1 ? Buffer.alloc(0) : bytes.subarray(boundary + 1);
}
function completeRecords(bytes: Buffer): { records: Buffer[]; count: number; clean: boolean } {
// Keep a BOM in the decoded text so JSON.parse still rejects BOM-prefixed rows.
const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
const records: Buffer[] = [];
let start = 0;
let clean = true;
let count = 0;
for (let end = bytes.indexOf(10); end !== -1; end = bytes.indexOf(10, start)) {
const line = bytes.subarray(start, end);
try {
const text = decoder.decode(line);
JSON.parse(text);
records[count % CATALOG_AUDIT_KEEP_RECORDS] = bytes.subarray(start, end + 1);
count++;
} catch { clean = false; }
start = end + 1;
}
const pivot = count > CATALOG_AUDIT_KEEP_RECORDS ? count % CATALOG_AUDIT_KEEP_RECORDS : 0;
return { records: records.slice(pivot).concat(records.slice(0, pivot)), count,
clean: clean && start === bytes.length };
}
function writeAll(fd: number, bytes: Buffer, position: number | null): void {
let offset = 0;
while (offset < bytes.length) {
const count = writeSync(fd, bytes, offset, bytes.length - offset,
position === null ? null : position + offset);
if (count === 0) throw new Error("audit write made no progress");
offset += count;
}
}
/**
* Best-effort adapter. Caller MUST hold K, even for a refusal that has no permit.
* POSIX owners compact the descriptor; foreign callers only append within both caps.
* Windows only publishes into fresh owner files after required ACL hardening.
* This diagnostic has no replay or authorization role. Process death may leave a partial line.
*/
export function appendCatalogWriteAudit(
codexHome: string,
event: CatalogWriteAuditEvent,
options: { readonly create: boolean },
): "appended" | "created" | "skipped" {
let fd: number | undefined;
try {
const line = auditLine(event);
if (line.length > CATALOG_AUDIT_MAX_EVENT_BYTES) return "skipped";
const path = codexCatalogAuditPath(codexHome);
const windows = windowsSecretAclApplies();
let before: BigIntStats | undefined;
try { before = lstatSync(path, { bigint: true }); }
catch (error) {
if ((error as NodeJS.ErrnoException).code !== "ENOENT" || !options.create) return "skipped";
}
if (before && !regularPrivateFile(before)) return "skipped";
// No mkdir, pathname truncation or chmod. O_EXCL prevents creation over a raced path.
const flags = constants.O_RDWR | (constants.O_NOFOLLOW ?? 0) | (constants.O_NONBLOCK ?? 0)
| (before ? (options.create ? 0 : constants.O_APPEND) : constants.O_CREAT | constants.O_EXCL);
fd = openSync(path, flags, 0o600);
let opened = fstatSync(fd, { bigint: true });
if (windows) {
// Existing files have already been refused: no read-only NTFS privacy verifier exists.
if (!opened.isFile() || opened.nlink !== 1n || opened.size !== 0n
|| !sameFile(opened, lstatSync(path, { bigint: true }))) return "skipped";
if (!hardenSecretPath(path, { required: true, deadlineMs: AUDIT_ACL_DEADLINE_MS }).ok) return "skipped";
const hardened = fstatSync(fd, { bigint: true });
// ACL changes legitimately move ctime. Retain object identity, then take a fresh baseline.
if (!hardened.isFile() || hardened.nlink !== 1n || hardened.size !== 0n
|| opened.dev !== hardened.dev || opened.ino !== hardened.ino
|| !sameFile(hardened, lstatSync(path, { bigint: true }))) return "skipped";
opened = hardened;
} else if (!regularPrivateFile(opened) || (before && !sameFile(before, opened))) return "skipped";
if (!options.create && opened.size + BigInt(line.length) > CATALOG_AUDIT_MAX_BYTES) return "skipped";
const tail = readTail(fd, Number(opened.size));
const parsed = completeRecords(tail);
if (!sameFile(opened, fstatSync(fd, { bigint: true })) || !sameFile(opened, lstatSync(path, { bigint: true }))) return "skipped";
if (!options.create) {
if (!parsed.clean || parsed.count + 1 > CATALOG_AUDIT_KEEP_RECORDS) return "skipped";
writeAll(fd, line, null);
} else if (opened.size <= CATALOG_AUDIT_MAX_BYTES - line.length
&& parsed.clean && parsed.count < CATALOG_AUDIT_KEEP_RECORDS) {
writeAll(fd, line, Number(opened.size));
} else {
const retained: Buffer[] = [line];
let bytes = line.length;
for (let index = parsed.records.length - 1; index >= 0 && retained.length < CATALOG_AUDIT_KEEP_RECORDS; index--) {
const record = parsed.records[index]!;
if (bytes + record.length > CATALOG_AUDIT_MAX_BYTES) break;
retained.unshift(record);
bytes += record.length;
}
const output = Buffer.concat(retained, bytes);
writeAll(fd, output, 0);
ftruncateSync(fd, output.length);
}
return before ? "appended" : "created";
} catch {
// Deliberately best-effort: an audit IO failure never changes the catalog result.
return "skipped";
} finally {
if (fd !== undefined) { try { closeSync(fd); } catch { /* diagnostic only */ } }
}
}