API Reference

Complete reference for all secure-exec exports.

Package Structure

Package	Contents
secure-exec	Main package — NodeRuntime, system drivers, execution environment factories, filesystem, network, and permissions
@secure-exec/typescript	Sandboxed TypeScript compiler tools

---

Runtimes

NodeRuntime

_{Exported from secure-exec}

Sandboxed JavaScript runtime using a V8 isolate.

new NodeRuntime(options: NodeRuntimeOptions)

NodeRuntimeOptions

Option	Type	Description
systemDriver	SystemDriver	Host capabilities (filesystem, network, permissions). Required.
runtimeDriverFactory	NodeRuntimeDriverFactory	Creates the isolate execution environment. Required.
memoryLimit	number	Isolate memory cap in MB.
cpuTimeLimitMs	number	CPU time budget in ms.
timingMitigation	"off" | "freeze"	Timing side-channel mitigation. Default "freeze".
onStdio	StdioHook	Default console output hook.
payloadLimits	{ base64TransferBytes?: number; jsonPayloadBytes?: number }	Bridge payload size limits.

Methods

Method	Returns	Description
exec(code, options?)	Promise<ExecResult>	Execute code without a return value.
run<T>(code, filePath?)	Promise<RunResult<T>>	Execute code and return the module namespace/default export object.
network	{ fetch, dnsLookup, httpRequest }	Network access from the host side.
dispose()	void	Release resources synchronously.
terminate()	Promise<void>	Terminate the runtime.

---

TypeScript Tools (@secure-exec/typescript)

createTypeScriptTools(options)

Creates sandboxed TypeScript project/source helpers backed by a dedicated compiler runtime.

createTypeScriptTools(options: TypeScriptToolsOptions)

TypeScriptToolsOptions

Option	Type	Description
systemDriver	SystemDriver	Compiler runtime capabilities and filesystem view.
runtimeDriverFactory	NodeRuntimeDriverFactory	Creates the compiler sandbox runtime.
memoryLimit	number	Compiler sandbox isolate memory cap in MB. Default 512.
cpuTimeLimitMs	number	Compiler sandbox CPU time budget in ms.
compilerSpecifier	string	Module specifier used to load the TypeScript compiler. Default "typescript".

Methods

Method	Returns	Description
typecheckProject(options?)	Promise<TypeCheckResult>	Type-check a filesystem-backed TypeScript project using tsconfig discovery or configFilePath.
compileProject(options?)	Promise<ProjectCompileResult>	Compile a filesystem-backed project and write emitted files through the configured filesystem like tsc.
typecheckSource(options)	Promise<TypeCheckResult>	Type-check one TypeScript source string without mutating the filesystem.
compileSource(options)	Promise<SourceCompileResult>	Compile one TypeScript source string and return JavaScript text.

---

System Driver Factories

createNodeDriver(options?)

_{Exported from secure-exec}

Creates a system driver for Node.js environments.

createNodeDriver(options?: NodeDriverOptions): SystemDriver

NodeDriverOptions

Option	Type	Description
filesystem	VirtualFileSystem	Custom filesystem. Default: host fs with module overlay.
moduleAccess	ModuleAccessOptions	Node modules overlay config.
networkAdapter	NetworkAdapter	Network implementation.
commandExecutor	CommandExecutor	Child process executor.
permissions	Permissions	Access control rules. Deny-by-default.
useDefaultNetwork	boolean	Enable default Node.js network adapter.
processConfig	ProcessConfig	Process metadata (cwd, env, argv, etc.).
osConfig	OSConfig	OS metadata (platform, arch, homedir, etc.).

createBrowserDriver(options?)

_{Exported from secure-exec}

Creates a system driver for browser environments. Returns a promise because OPFS initialization is async.

createBrowserDriver(options?: BrowserDriverOptions): Promise<SystemDriver>

BrowserDriverOptions

Option	Type	Description
filesystem	"opfs" | "memory"	Filesystem backend. Default: "opfs".
permissions	Permissions	Access control rules. Deny-by-default.
useDefaultNetwork	boolean	Enable browser fetch network adapter.

---

Execution Environment Setup

createNodeRuntimeDriverFactory(options?)

_{Re-exported from secure-exec}

Creates the execution environment factory for Node.js V8 isolates. Pass the result as the runtimeDriverFactory option when constructing a NodeRuntime.

createNodeRuntimeDriverFactory(options?: {
  createIsolate?(memoryLimit: number): unknown;
}): NodeRuntimeDriverFactory

createBrowserRuntimeDriverFactory(options?)

_{Re-exported from secure-exec}

Creates the execution environment factory for browser Worker-based sandboxes. Pass the result as the runtimeDriverFactory option when constructing a NodeRuntime.

createBrowserRuntimeDriverFactory(options?: {
  workerUrl?: URL | string;
}): NodeRuntimeDriverFactory

---

Filesystem

createInMemoryFileSystem()

_{Exported from secure-exec}

Creates a fully in-memory filesystem backed by Maps.

createInMemoryFileSystem(): InMemoryFileSystem

createOpfsFileSystem()

_{Exported from secure-exec}

Creates an OPFS-backed filesystem (browser only).

createOpfsFileSystem(): Promise<VirtualFileSystem>

NodeFileSystem

Thin wrapper around Node.js fs/promises.

new NodeFileSystem()

VirtualFileSystem interface

Method	Returns	Description
readFile(path)	Promise<Uint8Array>	Read file as bytes.
readTextFile(path)	Promise<string>	Read file as text.
readDir(path)	Promise<string[]>	List directory entries.
readDirWithTypes(path)	Promise<DirEntry[]>	List entries with type info.
writeFile(path, content)	Promise<void>	Write file.
createDir(path)	Promise<void>	Create directory.
mkdir(path)	Promise<void>	Create directory (alias).
exists(path)	Promise<boolean>	Check if path exists.
stat(path)	Promise<StatInfo>	Get file metadata.
removeFile(path)	Promise<void>	Delete a file.
removeDir(path)	Promise<void>	Delete a directory.
rename(old, new)	Promise<void>	Rename a file or directory.

---

Network

createDefaultNetworkAdapter()

_{Exported from secure-exec}

Creates a network adapter with real fetch, DNS, and HTTP support (Node.js only).

createDefaultNetworkAdapter(): NetworkAdapter

createBrowserNetworkAdapter()

_{Exported from secure-exec}

Creates a fetch-only network adapter for browser environments. No DNS support.

createBrowserNetworkAdapter(): NetworkAdapter

NetworkAdapter interface

Method	Returns	Description
fetch(url, options?)	Promise<FetchResponse>	HTTP fetch.
dnsLookup(hostname)	Promise<DnsResult>	DNS resolution.
httpRequest(url, options?)	Promise<HttpResponse>	Low-level HTTP request.
httpServerListen?(options)	Promise<{ address }>	Start a loopback HTTP server.
httpServerClose?(serverId)	Promise<void>	Close a loopback HTTP server.

---

Permissions

_{Exported from secure-exec}

Pre-built helpers

Export	Description
allowAll	Allow all operations.
allowAllFs	Allow all filesystem operations.
allowAllNetwork	Allow all network operations.
allowAllChildProcess	Allow all child process spawning.
allowAllEnv	Allow all environment variable access.

Permissions type

type Permissions = {
  fs?: PermissionCheck<FsAccessRequest>;
  network?: PermissionCheck<NetworkAccessRequest>;
  childProcess?: PermissionCheck<ChildProcessAccessRequest>;
  env?: PermissionCheck<EnvAccessRequest>;
};

Each field accepts a PermissionCheck, which is either a boolean or a function (request) => boolean | Promise<boolean>.

---

Execution Types

ExecOptions

Option	Type	Description
filePath	string	Script filename for error messages.
env	Record<string, string>	Override environment variables.
cwd	string	Working directory.
stdin	string	Stdin data.
cpuTimeLimitMs	number	CPU budget override.
timingMitigation	"off" | "freeze"	Timing mitigation override.
onStdio	StdioHook	Per-execution stdio hook.

ExecResult

{ code: number; errorMessage?: string }

RunResult<T>

{ code: number; errorMessage?: string; exports?: T }

StdioHook

type StdioHook = (event: { channel: "stdout" | "stderr"; message: string }) => void;

ProjectCompilerOptions

{
  cwd?: string;
  configFilePath?: string;
}

SourceCompilerOptions

{
  sourceText: string;
  filePath?: string;
  cwd?: string;
  configFilePath?: string;
  compilerOptions?: Record<string, unknown>;
}

TypeCheckResult

{
  success: boolean;
  diagnostics: TypeScriptDiagnostic[];
}

ProjectCompileResult

{
  success: boolean;
  diagnostics: TypeScriptDiagnostic[];
  emitSkipped: boolean;
  emittedFiles: string[];
}

SourceCompileResult

{
  success: boolean;
  diagnostics: TypeScriptDiagnostic[];
  outputText?: string;
  sourceMapText?: string;
}

TypeScriptDiagnostic

{
  code: number;
  category: "error" | "warning" | "suggestion" | "message";
  message: string;
  filePath?: string;
  line?: number;
  column?: number;
}

---

Configuration Types

ProcessConfig

Field	Type	Default
platform	string
arch	string
version	string
cwd	string	"/root"
env	Record<string, string>
argv	string[]
execPath	string
pid	number
ppid	number
uid	number
gid	number
stdin	string
timingMitigation	"off" | "freeze"
frozenTimeMs	number

OSConfig

Field	Type	Default
platform	string
arch	string
type	string
release	string
version	string
homedir	string	"/root"
tmpdir	string	"/tmp"
hostname	string

SystemDriver

type SystemDriver = {
  filesystem?: VirtualFileSystem;
  network?: NetworkAdapter;
  commandExecutor?: CommandExecutor;
  permissions?: Permissions;
  runtime: DriverRuntimeConfig;
};

CommandExecutor interface

Method	Returns	Description
spawn(command, args, options?)	SpawnedProcess	Spawn a child process.