@fitlab-ai/agent-infra 0.9.12 → 0.9.14

package/dist/lib/sandbox/control/native-file-lock.js

@@ -0,0 +1,177 @@
+import { createHash } from 'node:crypto';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+const require = createRequire(import.meta.url);
+const LOCK_ROOT_NAME = path.join('.agent-infra', 'sandbox-locks');
+function loadNative() {
+    try {
+        return require('fs-ext-extra-prebuilt');
+    }
+    catch {
+        throw new Error('SANDBOX_LOCK_UNSUPPORTED: native lock module is unavailable');
+    }
+}
+function digest(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function assertPrivateDirectory(directory, home) {
+    const resolvedHome = path.resolve(home);
+    let current = resolvedHome;
+    const relative = path.relative(resolvedHome, path.resolve(directory));
+    if (!relative || relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error('SANDBOX_LOCK_UNSUPPORTED: lock root must be below the user home');
+    }
+    for (const segment of relative.split(path.sep).filter(Boolean)) {
+        current = path.join(current, segment);
+        if (fs.existsSync(current)) {
+            const stat = fs.lstatSync(current);
+            if (stat.isSymbolicLink() || !stat.isDirectory()) {
+                throw new Error('SANDBOX_LOCK_UNSUPPORTED: lock namespace contains a link or non-directory');
+            }
+            if (process.platform !== 'win32' && typeof process.getuid === 'function'
+                && stat.uid !== process.getuid()) {
+                throw new Error('SANDBOX_LOCK_UNSUPPORTED: lock namespace owner mismatch');
+            }
+        }
+        else {
+            try {
+                fs.mkdirSync(current, { mode: 0o700 });
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+                const stat = fs.lstatSync(current);
+                if (stat.isSymbolicLink() || !stat.isDirectory()) {
+                    throw new Error('SANDBOX_LOCK_UNSUPPORTED: lock namespace contains a link or non-directory');
+                }
+            }
+        }
+        if (process.platform !== 'win32')
+            fs.chmodSync(current, 0o700);
+    }
+    const real = fs.realpathSync.native(path.resolve(directory));
+    const realRelative = path.relative(fs.realpathSync.native(resolvedHome), real);
+    if (!realRelative || realRelative.startsWith('..') || path.isAbsolute(realRelative)) {
+        throw new Error('SANDBOX_LOCK_UNSUPPORTED: lock namespace realpath escapes the user home');
+    }
+}
+export function resolveSandboxLockNamespace(carrierIdentity, options = {}) {
+    if (!carrierIdentity.trim())
+        throw new Error('SANDBOX_LOCK_IDENTITY_INVALID');
+    const home = path.resolve(options.home ?? os.homedir());
+    const lockRoot = path.join(home, LOCK_ROOT_NAME);
+    assertPrivateDirectory(lockRoot, home);
+    const primitive = process.platform === 'win32' ? 'LockFileEx' : 'flock';
+    const lockDomain = options.lockDomain ?? digest(`${process.platform}\0${process.arch}\0${primitive}`);
+    if (!/^[a-f0-9]{64}$/u.test(lockDomain))
+        throw new Error('SANDBOX_LOCK_DOMAIN_INVALID');
+    const domainDirectory = path.join(lockRoot, lockDomain);
+    assertPrivateDirectory(domainDirectory, home);
+    const carrierIdentityDigest = digest(carrierIdentity);
+    return {
+        lockRoot,
+        domainDirectory,
+        lockDomain,
+        carrierIdentityDigest,
+        lockPath: path.join(domainDirectory, `${carrierIdentityDigest}.lock`)
+    };
+}
+export function stableSandboxLockPath(carrierIdentity, lockDomain, options = {}) {
+    return resolveSandboxLockNamespace(carrierIdentity, { lockDomain, home: options.home }).lockPath;
+}
+export function probeNativeLockCapability() {
+    try {
+        const native = loadNative();
+        return {
+            supported: true,
+            primitive: process.platform === 'win32' ? 'LockFileEx' : 'flock',
+            binarySource: native.getNativeModuleSource?.() ?? null
+        };
+    }
+    catch (error) {
+        return {
+            supported: false,
+            primitive: 'unavailable',
+            binarySource: null,
+            reason: error instanceof Error ? error.message : String(error)
+        };
+    }
+}
+export function acquireSandboxResourceLock(carrierIdentity, options = {}) {
+    const native = loadNative();
+    const namespace = resolveSandboxLockNamespace(carrierIdentity, options);
+    if (fs.existsSync(namespace.lockPath)) {
+        const existing = fs.lstatSync(namespace.lockPath);
+        if (existing.isSymbolicLink() || !existing.isFile()) {
+            throw new Error('SANDBOX_LOCK_UNSUPPORTED: lock object is not a regular file');
+        }
+        if (process.platform !== 'win32' && typeof process.getuid === 'function'
+            && existing.uid !== process.getuid()) {
+            throw new Error('SANDBOX_LOCK_UNSUPPORTED: lock object owner mismatch');
+        }
+    }
+    let fd;
+    try {
+        const noFollow = process.platform !== 'win32' && typeof fs.constants.O_NOFOLLOW === 'number'
+            ? fs.constants.O_NOFOLLOW : 0;
+        fd = fs.openSync(namespace.lockPath, fs.constants.O_CREAT | fs.constants.O_RDWR | noFollow, 0o600);
+        if (process.platform !== 'win32')
+            fs.chmodSync(namespace.lockPath, 0o600);
+        if (process.platform === 'win32') {
+            native.lockFileExSync(fd, native.constants.LOCKFILE_EXCLUSIVE_LOCK | native.constants.LOCKFILE_FAIL_IMMEDIATELY, 0, 0, 1, 0);
+        }
+        else {
+            native.flockSync(fd, 'exnb');
+        }
+    }
+    catch (error) {
+        try {
+            if (fd !== undefined)
+                fs.closeSync(fd);
+        }
+        catch {
+            // Preserve the lock acquisition error.
+        }
+        const code = error && typeof error === 'object' && 'code' in error ? String(error.code) : '';
+        if (['EAGAIN', 'EACCES', 'EWOULDBLOCK'].includes(code)) {
+            throw new Error('SANDBOX_LOCK_BUSY');
+        }
+        throw new Error(`SANDBOX_LOCK_UNSUPPORTED: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    let released = false;
+    return {
+        path: namespace.lockPath,
+        lockDomain: namespace.lockDomain,
+        release() {
+            if (released)
+                return;
+            released = true;
+            let failure = null;
+            try {
+                if (fd === undefined)
+                    throw new Error('descriptor is missing');
+                if (process.platform === 'win32')
+                    native.unlockFileExSync(fd, 0, 0, 1, 0);
+                else
+                    native.flockSync(fd, 'un');
+            }
+            catch (error) {
+                failure = error;
+            }
+            finally {
+                try {
+                    if (fd !== undefined)
+                        fs.closeSync(fd);
+                }
+                catch (error) {
+                    failure ??= error;
+                }
+            }
+            if (failure)
+                throw new Error(`SANDBOX_LOCK_RELEASE_FAILED: ${failure instanceof Error ? failure.message : String(failure)}`);
+        }
+    };
+}
+//# sourceMappingURL=native-file-lock.js.map

package/dist/lib/sandbox/control/protocol.js

@@ -1,6 +1,11 @@
+import { createHash } from 'node:crypto';
 import { validateTaskCreateCandidate } from '../../task/create.js';
 import { normalizeAgentToken } from '../../agent-clients/tokens.js';
 export const SANDBOX_CONTROL_MAX_BYTES = 64 * 1024;
+export const SANDBOX_CONTROL_MAX_LOGICAL_RECORDS = 1024;
+export const SANDBOX_CONTROL_MAX_RESPONSE_BYTES = 64 * 1024 * 1024;
+export const SANDBOX_CONTROL_MAX_TERMINAL_RECORD_BYTES = 1024 * 1024;
+export const SANDBOX_CONTROL_RESERVATION_BYTES = SANDBOX_CONTROL_MAX_TERMINAL_RECORD_BYTES + 4 * 1024;
 export const SANDBOX_CONTROL_ADMISSION_WINDOW_MS = 2_000;
 export const SANDBOX_CONTROL_STATUS_INTERVAL_MS = 250;
 export const SANDBOX_CONTROL_STATUS_STALE_MS = 1_500;
@@ -26,6 +31,78 @@ export class SandboxControlProtocolError extends Error {
 function fail(code, message, retryable = false) {
     throw new SandboxControlProtocolError(code, message, retryable);
 }
+export function parseSandboxControlResultEvidence(value) {
+    const evidence = value;
+    const keys = evidence && typeof evidence === 'object' ? Object.keys(evidence).sort().join(',') : '';
+    if (keys !== 'captureState,exitCode,generation,id,stderrBytes,stderrSha256,stdoutBytes,stdoutSha256,version'
+        || evidence?.version !== 1
+        || typeof evidence.id !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(evidence.id)
+        || typeof evidence.generation !== 'string' || evidence.generation.length === 0
+        || !Number.isSafeInteger(evidence.exitCode)
+        || !Number.isSafeInteger(evidence.stdoutBytes) || evidence.stdoutBytes < 0
+        || !Number.isSafeInteger(evidence.stderrBytes) || evidence.stderrBytes < 0
+        || evidence.stdoutBytes + evidence.stderrBytes > SANDBOX_CONTROL_MAX_RESPONSE_BYTES
+        || typeof evidence.stdoutSha256 !== 'string' || !/^[a-f0-9]{64}$/u.test(evidence.stdoutSha256)
+        || typeof evidence.stderrSha256 !== 'string' || !/^[a-f0-9]{64}$/u.test(evidence.stderrSha256)
+        || evidence.captureState !== 'metadata-only') {
+        throw new Error('SANDBOX_CONTROL_RESULT_EVIDENCE_INVALID');
+    }
+    return evidence;
+}
+function validPayloadReference(value, id, generation) {
+    const payload = value;
+    const keys = payload && typeof payload === 'object' ? Object.keys(payload).sort().join(',') : '';
+    return keys === 'generation,id,stderrBytes,stderrSha256,stdoutBytes,stdoutSha256,version'
+        && payload?.version === 1
+        && payload.id === id
+        && payload.generation === generation
+        && Number.isSafeInteger(payload.stdoutBytes) && payload.stdoutBytes >= 0
+        && Number.isSafeInteger(payload.stderrBytes) && payload.stderrBytes >= 0
+        && payload.stdoutBytes + payload.stderrBytes <= SANDBOX_CONTROL_MAX_RESPONSE_BYTES
+        && typeof payload.stdoutSha256 === 'string' && /^[a-f0-9]{64}$/u.test(payload.stdoutSha256)
+        && typeof payload.stderrSha256 === 'string' && /^[a-f0-9]{64}$/u.test(payload.stderrSha256);
+}
+export function parseSandboxControlPayload(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('SANDBOX_CONTROL_PAYLOAD_INVALID');
+    const payload = value;
+    const reference = {
+        version: payload.version,
+        id: payload.id,
+        generation: payload.generation,
+        stdoutBytes: payload.stdoutBytes,
+        stderrBytes: payload.stderrBytes,
+        stdoutSha256: payload.stdoutSha256,
+        stderrSha256: payload.stderrSha256
+    };
+    const keys = Object.keys(payload).sort().join(',');
+    if (keys !== 'generation,id,stderr,stderrBytes,stderrSha256,stdout,stdoutBytes,stdoutSha256,version'
+        || !validPayloadReference(reference, reference.id, reference.generation)
+        || typeof payload.stdout !== 'string' || typeof payload.stderr !== 'string'
+        || Buffer.byteLength(payload.stdout, 'utf8') !== payload.stdoutBytes
+        || Buffer.byteLength(payload.stderr, 'utf8') !== payload.stderrBytes
+        || createHash('sha256').update(payload.stdout, 'utf8').digest('hex') !== payload.stdoutSha256
+        || createHash('sha256').update(payload.stderr, 'utf8').digest('hex') !== payload.stderrSha256) {
+        throw new Error('SANDBOX_CONTROL_PAYLOAD_INVALID');
+    }
+    return payload;
+}
+export function parseSandboxControlReservation(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('SANDBOX_CONTROL_RESERVATION_INVALID');
+    const reservation = value;
+    const keys = Object.keys(reservation).sort().join(',');
+    if (keys !== 'bytes,createdAt,generation,id,logicalRecords,version'
+        || reservation.version !== 1
+        || typeof reservation.id !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(reservation.id)
+        || typeof reservation.generation !== 'string' || reservation.generation.length === 0
+        || reservation.logicalRecords !== 1
+        || !Number.isSafeInteger(reservation.bytes) || reservation.bytes < SANDBOX_CONTROL_RESERVATION_BYTES
+        || !Number.isSafeInteger(reservation.createdAt)) {
+        throw new Error('SANDBOX_CONTROL_RESERVATION_INVALID');
+    }
+    return reservation;
+}
 export function isSandboxControlFamily(value) {
     return SANDBOX_CONTROL_FAMILIES.includes(value);
 }