You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs-internal/friction.md
+7Lines changed: 7 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,5 +1,12 @@
1
1
# Sandboxed Node Friction Log
2
2
3
+
## 2026-03-10
4
+
5
+
1.**[resolved]** TypeScript compilation needed sandboxing without baking compiler behavior into the core runtime.
6
+
- Symptom: keeping TypeScript handling inside `NodeRuntime` blurred the runtime contract, risked host-memory pressure during compilation, and forced browser/runtime surfaces to inherit TypeScript-specific policy.
7
+
- Fix: core `secure-exec` now stays JavaScript-only, while sandboxed TypeScript typecheck/compile flows move to the separate `@secure-exec/typescript` package.
8
+
- Compatibility trade-off: callers that want TypeScript must perform an explicit compile/typecheck step before executing emitted JavaScript in the runtime.
|`systemDriver`|`SystemDriver`| Compiler runtime capabilities and filesystem view. |
55
+
|`runtimeDriverFactory`|`NodeRuntimeDriverFactory`| Creates the compiler sandbox runtime. |
56
+
|`memoryLimit`|`number`| Compiler sandbox isolate memory cap in MB. Default `512`. |
57
+
|`cpuTimeLimitMs`|`number`| Compiler sandbox CPU time budget in ms. |
58
+
|`compilerSpecifier`|`string`| Module specifier used to load the TypeScript compiler. Default `"typescript"`. |
59
+
60
+
**Methods**
61
+
62
+
| Method | Returns | Description |
63
+
|---|---|---|
64
+
|`typecheckProject(options?)`|`Promise<TypeCheckResult>`| Type-check a filesystem-backed TypeScript project using `tsconfig` discovery or `configFilePath`. |
65
+
|`compileProject(options?)`|`Promise<ProjectCompileResult>`| Compile a filesystem-backed project and write emitted files through the configured filesystem like `tsc`. |
66
+
|`typecheckSource(options)`|`Promise<TypeCheckResult>`| Type-check one TypeScript source string without mutating the filesystem. |
67
+
|`compileSource(options)`|`Promise<SourceCompileResult>`| Compile one TypeScript source string and return JavaScript text. |
68
+
69
+
---
70
+
40
71
### `PythonRuntime`
41
72
42
73
Sandboxed Python runtime using Pyodide in a Worker thread.
- Sandboxed TypeScript type checking and compilation belong in the separate `@secure-exec/typescript` package.
67
+
63
68
## Node-Modules Overlay Behavior
64
69
65
70
- Node runtime composes a read-only `/app/node_modules` overlay from `<cwd>/node_modules` (default `cwd` is host `process.cwd()`, configurable via `moduleAccess.cwd`).
Copy file name to clipboardExpand all lines: docs/quickstart.mdx
+11-3Lines changed: 11 additions & 3 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -9,6 +9,12 @@ description: Get secure-exec running in a few minutes.
9
9
pnpm add secure-exec
10
10
```
11
11
12
+
Optional TypeScript tooling:
13
+
14
+
```bash
15
+
pnpm add @secure-exec/typescript
16
+
```
17
+
12
18
## Create a runtime
13
19
14
20
A runtime needs two things: a **system driver** that provides host capabilities (filesystem, network, permissions) and a **runtime driver** that manages the sandboxed execution environment.
@@ -51,7 +57,7 @@ Use `exec()` to run code in the sandbox. Console output is streamed through the
51
57
```ts
52
58
const logs:string[] = [];
53
59
54
-
const result =awaitruntime.exec("console.log('hello from secure-exec')", {
60
+
const result =awaitruntime.exec("const value = 'hello from secure-exec'; console.log(value)", {
Use `run()` to execute code and get an exported value back.
65
71
66
72
```ts
67
-
const result =awaitruntime.run<number>("export default 2 + 2");
68
-
console.log(result.exports); // 4
73
+
const result =awaitruntime.run<{ default:number }>("export default 2 + 2");
74
+
console.log(result.exports?.default); // 4
69
75
```
70
76
77
+
If you want sandboxed TypeScript type checking or compilation before execution, use the separate `@secure-exec/typescript` package and pass its emitted JavaScript into `secure-exec`.
78
+
71
79
## Clean up
72
80
73
81
Dispose the runtime when you're done to free resources.
Copy file name to clipboardExpand all lines: docs/runtimes/node.mdx
+146-4Lines changed: 146 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -3,7 +3,7 @@ title: Node Runtime
3
3
description: Sandboxed JavaScript execution in a V8 isolate.
4
4
---
5
5
6
-
`NodeRuntime` runs JavaScript in an isolated V8 isolate. It supports memory limits, CPU time budgets, and timing side-channel mitigation. The sandbox provides Node.js-compatible APIs through a bridge layer.
6
+
`NodeRuntime` runs JavaScript code in an isolated V8 isolate. The sandbox supports memory limits, CPU time budgets, and timing side-channel mitigation.
7
7
8
8
## Creating a runtime
9
9
@@ -27,15 +27,15 @@ const runtime = new NodeRuntime({
27
27
Use `exec()` when you care about side effects (logging, file writes) but don't need a return value.
28
28
29
29
```ts
30
-
const result =awaitruntime.exec("console.log('done')");
30
+
const result =awaitruntime.exec("const label = 'done'; console.log(label)");
31
31
console.log(result.code); // 0
32
32
```
33
33
34
34
Use `run()` when you need a value back. The sandboxed code should use `export default`.
35
35
36
36
```ts
37
-
const result =awaitruntime.run<number>("export default 40 + 2");
38
-
console.log(result.exports); // 42
37
+
const result =awaitruntime.run<{ default:number }>("export default 40 + 2");
`NodeRuntime` executes JavaScript only. For sandboxed TypeScript type checking or compilation, use the separate `@secure-exec/typescript` package. See [TypeScript support](#typescript-support).
56
+
53
57
## Resource limits
54
58
55
59
You can cap memory and CPU time to prevent runaway code from exhausting host resources.
@@ -67,3 +71,141 @@ const runtime = new NodeRuntime({
67
71
## Module loading
68
72
69
73
The sandbox provides a read-only overlay of the host's `node_modules` at `/app/node_modules`. Sandboxed code can `import` or `require()` packages installed on the host without any additional configuration.
74
+
75
+
## TypeScript support
76
+
77
+
TypeScript support lives in the companion `@secure-exec/typescript` package. It runs the TypeScript compiler inside a dedicated sandbox so untrusted inputs cannot consume host CPU or memory during type checking or compilation.
Use `typecheckSource(...)` when you want to quickly validate AI-generated code before running it:
101
+
102
+
```ts
103
+
const result =awaitts.typecheckSource({
104
+
filePath: "/root/snippet.ts",
105
+
sourceText: `
106
+
export function greet(name: string) {
107
+
return "hello " + missingValue;
108
+
}
109
+
`,
110
+
});
111
+
112
+
console.log(result.success); // false
113
+
console.log(result.diagnostics[0]?.message);
114
+
```
115
+
116
+
### Type check project
117
+
118
+
Use `typecheckProject(...)` when you want to validate a full TypeScript project from the filesystem exposed by the system driver. That means `tsconfig.json`, source files, and any other project inputs are read from that sandbox filesystem view.
119
+
120
+
```ts
121
+
awaitfilesystem.mkdir("/root/src");
122
+
awaitfilesystem.writeFile(
123
+
"/root/tsconfig.json",
124
+
JSON.stringify({
125
+
compilerOptions: {
126
+
module: "nodenext",
127
+
moduleResolution: "nodenext",
128
+
target: "es2022",
129
+
},
130
+
include: ["src/**/*.ts"],
131
+
}),
132
+
);
133
+
awaitfilesystem.writeFile(
134
+
"/root/src/index.ts",
135
+
"export const value: string = 123;\n",
136
+
);
137
+
138
+
const result =awaitts.typecheckProject({ cwd: "/root" });
139
+
140
+
console.log(result.success); // false
141
+
console.log(result.diagnostics[0]?.message);
142
+
```
143
+
144
+
### Compile source
145
+
146
+
Use `compileSource(...)` when you want to transpile one TypeScript source string and then hand the emitted JavaScript to `NodeRuntime`:
Use `compileProject(...)` when you want TypeScript to read a real project from the filesystem exposed by the system driver and write emitted files back into that same sandbox filesystem view.
0 commit comments