@bitkyc08/opencodex
Version:
Universal provider proxy for OpenAI Codex & Claude Code — use any LLM with Codex CLI/App/SDK and Claude Code
477 lines (431 loc) • 15.6 kB
text/typescript
/**
* Descriptor/handle-bound, no-follow artifact I/O for the Compatibility Lab store.
*
* POSIX runtimes use directory-relative `dir` opens. Windows uses the same pinned
* directory identity checks as other reviewed OpenCodex bounded readers, because
* directory-relative child opens are not durable there.
*/
import {
closeSync,
constants as fsConstants,
existsSync,
fstatSync,
fsyncSync,
lstatSync,
mkdirSync,
openSync,
readSync,
renameSync,
unlinkSync,
writeSync,
type Stats,
type BigIntStats,
} from "node:fs";
import { join } from "node:path";
import { fileIdentityKey, sameFileIdentity, type FileIdentity } from "../../lib/file-identity";
import {
ARTIFACT_FILENAME_EXT,
MAX_BYTES_PER_ARTIFACT,
} from "../constants";
import { artifactBytesDigest, isSha256Hex } from "../digest";
export class ArtifactFsError extends Error {
readonly code: string;
constructor(code: string, message: string) {
super(message);
this.name = "ArtifactFsError";
this.code = code;
}
}
export function harnessFailure(message: string, code = "harness_failure"): never {
throw new ArtifactFsError(code, message);
}
const O_RDONLY = fsConstants.O_RDONLY;
const O_RDWR = fsConstants.O_RDWR;
const O_CREAT = fsConstants.O_CREAT;
const O_EXCL = fsConstants.O_EXCL;
const O_NOFOLLOW = (fsConstants as { O_NOFOLLOW?: number }).O_NOFOLLOW;
const O_DIRECTORY = (fsConstants as { O_DIRECTORY?: number }).O_DIRECTORY;
type ArtifactIoMode = "dirfd" | "win32_pinned";
let artifactIoMode: ArtifactIoMode | null = null;
export function assertDigestName(digest: string): string {
if (!isSha256Hex(digest)) harnessFailure("artifact digest must be lowercase sha256 hex");
if (digest.includes("/") || digest.includes("\\") || digest.includes(":") || digest.includes("..")) {
harnessFailure("artifact digest must not contain path separators");
}
return digest;
}
export function digestFileName(digest: string): string {
return `${assertDigestName(digest)}${ARTIFACT_FILENAME_EXT}`;
}
function platformSupportsNoFollow(): boolean {
return typeof O_NOFOLLOW === "number" && O_NOFOLLOW !== 0;
}
function openFlags(base: number, noFollow: boolean): number {
if (noFollow && platformSupportsNoFollow()) return base | O_NOFOLLOW!;
return base;
}
function assertRegularFileStats(stats: Stats | BigIntStats, label: string): void {
if (
!stats.isFile() ||
stats.isSymbolicLink() ||
stats.isDirectory() ||
stats.isFIFO() ||
stats.isSocket() ||
stats.isCharacterDevice() ||
stats.isBlockDevice()
) {
harnessFailure(`${label}: not a regular file`, "artifact_unsafe_target");
}
if (Number(stats.nlink) !== 1) {
harnessFailure(`${label}: hard links prohibited (nlink=${stats.nlink})`, "artifact_unsafe_target");
}
}
function assertDirectoryStats(stats: Stats | BigIntStats, label: string): void {
if (!stats.isDirectory() || stats.isSymbolicLink()) {
harnessFailure(`${label}: must be a real directory (no symlink/reparse redirection)`, "artifact_unsafe_target");
}
}
function identityOf(stats: FileIdentity): string {
return fileIdentityKey(stats);
}
function assertRelativeName(name: string): void {
if (name.includes("..") || name.includes("/") || name.includes("\\") || name.includes("\0")) {
harnessFailure("invalid relative artifact name", "artifact_unsafe_target");
}
}
export interface TrustedArtifactDir {
path: string;
fd: number;
identity: string;
}
type OpenSyncWithDir = (
path: string,
flags: number,
mode: number,
options: { dir: number },
) => number;
type RenameSyncWithDir = (from: string, to: string, options: { dir: number }) => void;
type UnlinkSyncWithDir = (path: string, options: { dir: number }) => void;
function detectArtifactIoMode(dir: TrustedArtifactDir): ArtifactIoMode {
if (artifactIoMode !== null) return artifactIoMode;
if (process.platform === "win32") {
artifactIoMode = "win32_pinned";
return artifactIoMode;
}
const probe = `.dirfd-probe-${process.pid}`;
const finalName = `${probe}.ok`;
try {
const openWithDir = openSync as unknown as OpenSyncWithDir;
const fd = openWithDir(probe, O_CREAT | O_EXCL | O_RDWR, 0o600, { dir: dir.fd });
closeSync(fd);
(renameSync as unknown as RenameSyncWithDir)(probe, finalName, { dir: dir.fd });
if (!existsSync(join(dir.path, finalName))) {
artifactIoMode = "win32_pinned";
return artifactIoMode;
}
(unlinkSync as unknown as UnlinkSyncWithDir)(finalName, { dir: dir.fd });
artifactIoMode = "dirfd";
} catch {
artifactIoMode = "win32_pinned";
}
return artifactIoMode;
}
function childPath(dir: TrustedArtifactDir, name: string): string {
revalidateDir(dir);
assertRelativeName(name);
return join(dir.path, name);
}
function assertOpenedPathMatchesDescriptor(dir: TrustedArtifactDir, name: string, fd: number): void {
if (detectArtifactIoMode(dir) !== "win32_pinned") return;
const opened = fstatSync(fd, { bigint: true });
assertRegularFileStats(opened, "artifact fd");
const pathEntry = lstatSync(childPath(dir, name), { bigint: true });
if (
!pathEntry.isFile() ||
pathEntry.isSymbolicLink() ||
!sameFileIdentity(pathEntry, opened)
) {
closeSync(fd);
harnessFailure("artifact path identity mismatch after open", "artifact_unsafe_target");
}
}
function openAtDir(dir: TrustedArtifactDir, name: string, flags: number, mode = 0): number {
revalidateDir(dir);
assertRelativeName(name);
const mode_ = detectArtifactIoMode(dir);
if (mode_ === "dirfd") {
return (openSync as unknown as OpenSyncWithDir)(name, flags, mode, { dir: dir.fd });
}
const fd = openSync(childPath(dir, name), flags, mode);
assertOpenedPathMatchesDescriptor(dir, name, fd);
return fd;
}
function renameAtDir(dir: TrustedArtifactDir, from: string, to: string): void {
revalidateDir(dir);
assertRelativeName(from);
assertRelativeName(to);
if (detectArtifactIoMode(dir) === "dirfd") {
(renameSync as unknown as RenameSyncWithDir)(from, to, { dir: dir.fd });
return;
}
renameSync(childPath(dir, from), childPath(dir, to));
}
function unlinkAtDir(dir: TrustedArtifactDir, name: string): void {
revalidateDir(dir);
assertRelativeName(name);
if (detectArtifactIoMode(dir) === "dirfd") {
(unlinkSync as unknown as UnlinkSyncWithDir)(name, { dir: dir.fd });
return;
}
unlinkSync(childPath(dir, name));
}
function revalidateDir(dir: TrustedArtifactDir): void {
const stats = fstatSync(dir.fd, { bigint: true });
assertDirectoryStats(stats, "artifacts dir");
if (identityOf(stats) !== dir.identity) {
harnessFailure("artifacts directory identity changed", "artifact_unsafe_target");
}
}
export function openTrustedArtifactDir(artifactsDir: string): TrustedArtifactDir {
const abs = artifactsDir.replace(/[\\/]+$/, "");
if (abs.includes("\0")) harnessFailure("NUL in artifacts path", "artifact_unsafe_target");
mkdirSync(abs, { recursive: true, mode: 0o700 });
let fd: number;
if (typeof O_DIRECTORY === "number") {
try {
fd = openSync(abs, openFlags(O_RDONLY | O_DIRECTORY, true));
} catch {
harnessFailure("failed to open artifacts directory with O_DIRECTORY", "artifact_unsafe_target");
}
} else {
fd = openSync(abs, O_RDONLY);
}
const stats = fstatSync(fd, { bigint: true });
assertDirectoryStats(stats, "artifacts dir");
const trusted = { path: abs, fd, identity: identityOf(stats) };
detectArtifactIoMode(trusted);
return trusted;
}
export function closeTrustedArtifactDir(dir: TrustedArtifactDir): void {
try {
closeSync(dir.fd);
} catch {
/* ignore */
}
}
export interface StoredArtifactBytes {
digest: string;
bytes: Uint8Array;
byteCount: number;
}
export interface ReadArtifactOptions {
expectedByteCount?: number;
contentDigest?: (bytes: Uint8Array) => string;
}
function readAllFromFd(fd: number, size: number): Buffer {
const buf = Buffer.alloc(size);
let offset = 0;
while (offset < buf.length) {
const n = readSync(fd, buf, offset, buf.length - offset, offset);
if (n <= 0) break;
offset += n;
}
if (offset !== size) harnessFailure("short read from artifact descriptor", "artifact_mismatch");
return buf;
}
function isRawMissingError(err: unknown): boolean {
return !!err && typeof err === "object" && "code" in err && (err as { code: string }).code === "ENOENT";
}
function isMissingArtifactError(err: unknown): boolean {
return isRawMissingError(err) || (err instanceof ArtifactFsError && err.code === "artifact_missing");
}
/**
* Returns true when a clean regular digest target appeared after the caller's
* missing read. The final readback still verifies byte count and digest, so a
* concurrent or hostile wrong-content regular file fails closed.
*/
function artifactTargetAlreadyPublished(dir: TrustedArtifactDir, name: string): boolean {
revalidateDir(dir);
assertRelativeName(name);
try {
const stats = lstatSync(childPath(dir, name));
if (stats.isSymbolicLink()) {
harnessFailure("artifact target is a symbolic link", "artifact_unsafe_target");
}
assertRegularFileStats(stats, "artifact create target");
return true;
} catch (err) {
if (isRawMissingError(err)) return false;
if (err instanceof ArtifactFsError) throw err;
harnessFailure(
`artifact create target check failed: ${err instanceof Error ? err.message : String(err)}`,
"artifact_unsafe_target",
);
}
}
function writeAll(fd: number, bytes: Uint8Array): void {
let offset = 0;
while (offset < bytes.byteLength) {
const n = writeSync(fd, bytes, offset, bytes.byteLength - offset);
if (n <= 0) harnessFailure("artifact write made no progress", "artifact_mismatch");
offset += n;
}
}
function writeTempArtifact(
dir: TrustedArtifactDir,
tmpName: string,
bytes: Uint8Array,
digest: string,
contentDigest: (b: Uint8Array) => string,
): void {
let fd: number | null = null;
try {
fd = openAtDir(dir, tmpName, openFlags(O_RDWR | O_CREAT | O_EXCL, true), 0o600);
writeAll(fd, bytes);
fsyncSync(fd);
const stats = fstatSync(fd);
assertRegularFileStats(stats, "artifact temp");
if (stats.size !== bytes.byteLength) {
harnessFailure("size mismatch after write", "artifact_mismatch");
}
const buf = readAllFromFd(fd, bytes.byteLength);
if (contentDigest(buf) !== digest) {
harnessFailure("digest mismatch on same descriptor", "artifact_mismatch");
}
closeSync(fd);
fd = null;
renameAtDir(dir, tmpName, digestFileName(digest));
} catch (err) {
if (fd !== null) {
try { closeSync(fd); } catch { /* ignore */ }
}
try {
unlinkAtDir(dir, tmpName);
} catch {
/* ignore cleanup */
}
if (err instanceof ArtifactFsError) throw err;
harnessFailure(`artifact write failed: ${err instanceof Error ? err.message : String(err)}`);
}
}
export function readArtifactBytes(
dir: TrustedArtifactDir,
digest: string,
expectedByteCountOrOpts?: number | ReadArtifactOptions,
): StoredArtifactBytes {
const opts: ReadArtifactOptions =
typeof expectedByteCountOrOpts === "number"
? { expectedByteCount: expectedByteCountOrOpts }
: expectedByteCountOrOpts ?? {};
const contentDigest = opts.contentDigest ?? artifactBytesDigest;
revalidateDir(dir);
assertDigestName(digest);
const name = digestFileName(digest);
let fd: number | null = null;
try {
fd = openAtDir(dir, name, openFlags(O_RDONLY, true));
const stats = fstatSync(fd);
assertRegularFileStats(stats, "artifact fd");
if (opts.expectedByteCount !== undefined && stats.size !== opts.expectedByteCount) {
harnessFailure("artifact size mismatch on descriptor", "artifact_mismatch");
}
if (stats.size > MAX_BYTES_PER_ARTIFACT) {
harnessFailure("artifact exceeds ceiling", "artifact_mismatch");
}
const buf = readAllFromFd(fd, stats.size);
const got = contentDigest(buf);
if (got !== digest) harnessFailure("artifact digest mismatch on descriptor", "artifact_mismatch");
return { digest, bytes: new Uint8Array(buf), byteCount: stats.size };
} catch (err) {
if (isRawMissingError(err)) {
harnessFailure(`artifact missing: ${digest}`, "artifact_missing");
}
if (err instanceof ArtifactFsError) throw err;
harnessFailure(`artifact read failed: ${err instanceof Error ? err.message : String(err)}`);
} finally {
if (fd !== null) closeSync(fd);
}
harnessFailure("artifact read failed");
}
export function putArtifactBytes(
dir: TrustedArtifactDir,
bytes: Uint8Array,
expectedDigest?: string,
): StoredArtifactBytes {
revalidateDir(dir);
if (bytes.byteLength > MAX_BYTES_PER_ARTIFACT) {
harnessFailure(`artifact exceeds ${MAX_BYTES_PER_ARTIFACT} bytes`);
}
const digest = artifactBytesDigest(bytes);
if (expectedDigest !== undefined) {
assertDigestName(expectedDigest);
if (digest !== expectedDigest) {
harnessFailure("artifact digest mismatch before write", "artifact_mismatch");
}
}
try {
return readArtifactBytes(dir, digest, bytes.byteLength);
} catch (err) {
if (!isMissingArtifactError(err)) throw err;
}
if (!artifactTargetAlreadyPublished(dir, digestFileName(digest))) {
const tmpName = `.tmp-${digest}-${process.pid}-${Date.now()}.partial`;
writeTempArtifact(dir, tmpName, bytes, digest, artifactBytesDigest);
}
return readArtifactBytes(dir, digest, bytes.byteLength);
}
export function putNamedDigestBytes(
dir: TrustedArtifactDir,
digest: string,
bytes: Uint8Array,
contentDigest: (b: Uint8Array) => string,
): StoredArtifactBytes {
revalidateDir(dir);
assertDigestName(digest);
if (bytes.byteLength > MAX_BYTES_PER_ARTIFACT) {
harnessFailure(`artifact exceeds ${MAX_BYTES_PER_ARTIFACT} bytes`);
}
if (contentDigest(bytes) !== digest) {
harnessFailure("named artifact content digest mismatch before write", "artifact_mismatch");
}
try {
return readArtifactBytes(dir, digest, { expectedByteCount: bytes.byteLength, contentDigest });
} catch (err) {
if (!isMissingArtifactError(err)) throw err;
}
if (!artifactTargetAlreadyPublished(dir, digestFileName(digest))) {
const tmpName = `.tmp-${digest}-${process.pid}-${Date.now()}.partial`;
writeTempArtifact(dir, tmpName, bytes, digest, contentDigest);
}
return readArtifactBytes(dir, digest, { expectedByteCount: bytes.byteLength, contentDigest });
}
export function deleteArtifactBytes(dir: TrustedArtifactDir, digest: string): void {
revalidateDir(dir);
assertDigestName(digest);
const name = digestFileName(digest);
try {
unlinkAtDir(dir, name);
} catch (err) {
if (isRawMissingError(err)) return;
if (err instanceof ArtifactFsError) throw err;
harnessFailure(`artifact delete failed: ${err instanceof Error ? err.message : String(err)}`);
}
}
export function artifactExists(dir: TrustedArtifactDir, digest: string): boolean {
revalidateDir(dir);
assertDigestName(digest);
try {
const fd = openAtDir(dir, digestFileName(digest), openFlags(O_RDONLY, true));
try {
const stats = fstatSync(fd);
assertRegularFileStats(stats, "artifact exists");
return true;
} finally {
closeSync(fd);
}
} catch (err) {
if (isMissingArtifactError(err)) return false;
if (err instanceof ArtifactFsError) throw err;
harnessFailure(`artifact exists check failed: ${err instanceof Error ? err.message : String(err)}`);
}
}