@buildanagent/harness 0.0.0-stage → 0.1.0-alpha.29

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (397) hide show
  1. package/LICENSE +54 -0
  2. package/LICENSE-APACHE +202 -0
  3. package/LICENSE-MIT +21 -0
  4. package/README.md +822 -2
  5. package/dist/ablation.d.ts +2 -0
  6. package/dist/ablation.js +3 -0
  7. package/dist/ablation.js.map +1 -0
  8. package/dist/completion/check.d.ts +64 -0
  9. package/dist/completion/check.js +152 -0
  10. package/dist/completion/check.js.map +1 -0
  11. package/dist/completion/checks.d.ts +45 -0
  12. package/dist/completion/checks.js +173 -0
  13. package/dist/completion/checks.js.map +1 -0
  14. package/dist/completion/flags.d.ts +25 -0
  15. package/dist/completion/flags.js +87 -0
  16. package/dist/completion/flags.js.map +1 -0
  17. package/dist/completion/index.d.ts +8 -0
  18. package/dist/completion/index.js +9 -0
  19. package/dist/completion/index.js.map +1 -0
  20. package/dist/completion/snapshot.d.ts +33 -0
  21. package/dist/completion/snapshot.js +83 -0
  22. package/dist/completion/snapshot.js.map +1 -0
  23. package/dist/context/cap.d.ts +32 -0
  24. package/dist/context/cap.js +50 -0
  25. package/dist/context/cap.js.map +1 -0
  26. package/dist/context/estimate.d.ts +18 -0
  27. package/dist/context/estimate.js +20 -0
  28. package/dist/context/estimate.js.map +1 -0
  29. package/dist/context/file-spill.d.ts +15 -0
  30. package/dist/context/file-spill.js +40 -0
  31. package/dist/context/file-spill.js.map +1 -0
  32. package/dist/context/index.d.ts +10 -0
  33. package/dist/context/index.js +10 -0
  34. package/dist/context/index.js.map +1 -0
  35. package/dist/context/mask.d.ts +27 -0
  36. package/dist/context/mask.js +71 -0
  37. package/dist/context/mask.js.map +1 -0
  38. package/dist/context/mid-turn.d.ts +40 -0
  39. package/dist/context/mid-turn.js +82 -0
  40. package/dist/context/mid-turn.js.map +1 -0
  41. package/dist/context/policy.d.ts +9 -0
  42. package/dist/context/policy.js +140 -0
  43. package/dist/context/policy.js.map +1 -0
  44. package/dist/context/spill-ledger.d.ts +25 -0
  45. package/dist/context/spill-ledger.js +54 -0
  46. package/dist/context/spill-ledger.js.map +1 -0
  47. package/dist/context/spill.d.ts +10 -0
  48. package/dist/context/spill.js +18 -0
  49. package/dist/context/spill.js.map +1 -0
  50. package/dist/context/summarize.d.ts +53 -0
  51. package/dist/context/summarize.js +204 -0
  52. package/dist/context/summarize.js.map +1 -0
  53. package/dist/context/summary-template.d.ts +29 -0
  54. package/dist/context/summary-template.js +69 -0
  55. package/dist/context/summary-template.js.map +1 -0
  56. package/dist/context/types.d.ts +150 -0
  57. package/dist/context/types.js +2 -0
  58. package/dist/context/types.js.map +1 -0
  59. package/dist/context/write-cap.d.ts +19 -0
  60. package/dist/context/write-cap.js +41 -0
  61. package/dist/context/write-cap.js.map +1 -0
  62. package/dist/create-harness.d.ts +7 -0
  63. package/dist/create-harness.js +21 -0
  64. package/dist/create-harness.js.map +1 -0
  65. package/dist/credentials/addresses.d.ts +14 -0
  66. package/dist/credentials/addresses.js +144 -0
  67. package/dist/credentials/addresses.js.map +1 -0
  68. package/dist/credentials/allowlist.d.ts +54 -0
  69. package/dist/credentials/allowlist.js +134 -0
  70. package/dist/credentials/allowlist.js.map +1 -0
  71. package/dist/credentials/egress-policy.d.ts +69 -0
  72. package/dist/credentials/egress-policy.js +170 -0
  73. package/dist/credentials/egress-policy.js.map +1 -0
  74. package/dist/credentials/egress-proxy.d.ts +82 -0
  75. package/dist/credentials/egress-proxy.js +650 -0
  76. package/dist/credentials/egress-proxy.js.map +1 -0
  77. package/dist/credentials/git-route.d.ts +68 -0
  78. package/dist/credentials/git-route.js +288 -0
  79. package/dist/credentials/git-route.js.map +1 -0
  80. package/dist/credentials/index.d.ts +13 -0
  81. package/dist/credentials/index.js +14 -0
  82. package/dist/credentials/index.js.map +1 -0
  83. package/dist/credentials/scrub.d.ts +23 -0
  84. package/dist/credentials/scrub.js +115 -0
  85. package/dist/credentials/scrub.js.map +1 -0
  86. package/dist/errors.d.ts +60 -0
  87. package/dist/errors.js +67 -0
  88. package/dist/errors.js.map +1 -0
  89. package/dist/extensions/compose.d.ts +27 -0
  90. package/dist/extensions/compose.js +83 -0
  91. package/dist/extensions/compose.js.map +1 -0
  92. package/dist/extensions/context-files-node.d.ts +28 -0
  93. package/dist/extensions/context-files-node.js +74 -0
  94. package/dist/extensions/context-files-node.js.map +1 -0
  95. package/dist/extensions/context-files.d.ts +68 -0
  96. package/dist/extensions/context-files.js +214 -0
  97. package/dist/extensions/context-files.js.map +1 -0
  98. package/dist/extensions/digest.d.ts +6 -0
  99. package/dist/extensions/digest.js +68 -0
  100. package/dist/extensions/digest.js.map +1 -0
  101. package/dist/extensions/index.d.ts +10 -0
  102. package/dist/extensions/index.js +10 -0
  103. package/dist/extensions/index.js.map +1 -0
  104. package/dist/extensions/load.d.ts +42 -0
  105. package/dist/extensions/load.js +211 -0
  106. package/dist/extensions/load.js.map +1 -0
  107. package/dist/extensions/lock.d.ts +8 -0
  108. package/dist/extensions/lock.js +95 -0
  109. package/dist/extensions/lock.js.map +1 -0
  110. package/dist/extensions/node.d.ts +10 -0
  111. package/dist/extensions/node.js +11 -0
  112. package/dist/extensions/node.js.map +1 -0
  113. package/dist/extensions/project-dirs.d.ts +24 -0
  114. package/dist/extensions/project-dirs.js +97 -0
  115. package/dist/extensions/project-dirs.js.map +1 -0
  116. package/dist/extensions/skills-node.d.ts +34 -0
  117. package/dist/extensions/skills-node.js +123 -0
  118. package/dist/extensions/skills-node.js.map +1 -0
  119. package/dist/extensions/skills.d.ts +51 -0
  120. package/dist/extensions/skills.js +175 -0
  121. package/dist/extensions/skills.js.map +1 -0
  122. package/dist/extensions/trust-file.d.ts +3 -0
  123. package/dist/extensions/trust-file.js +62 -0
  124. package/dist/extensions/trust-file.js.map +1 -0
  125. package/dist/extensions/trust-store-node.d.ts +10 -0
  126. package/dist/extensions/trust-store-node.js +33 -0
  127. package/dist/extensions/trust-store-node.js.map +1 -0
  128. package/dist/extensions/types.d.ts +42 -0
  129. package/dist/extensions/types.js +2 -0
  130. package/dist/extensions/types.js.map +1 -0
  131. package/dist/harness.d.ts +156 -0
  132. package/dist/harness.js +2 -0
  133. package/dist/harness.js.map +1 -0
  134. package/dist/index.d.ts +4 -0
  135. package/dist/index.js +5 -0
  136. package/dist/index.js.map +1 -0
  137. package/dist/mcp/connection.d.ts +22 -0
  138. package/dist/mcp/connection.js +267 -0
  139. package/dist/mcp/connection.js.map +1 -0
  140. package/dist/mcp/content.d.ts +27 -0
  141. package/dist/mcp/content.js +177 -0
  142. package/dist/mcp/content.js.map +1 -0
  143. package/dist/mcp/errors.d.ts +19 -0
  144. package/dist/mcp/errors.js +21 -0
  145. package/dist/mcp/errors.js.map +1 -0
  146. package/dist/mcp/index.d.ts +10 -0
  147. package/dist/mcp/index.js +10 -0
  148. package/dist/mcp/index.js.map +1 -0
  149. package/dist/mcp/manager.d.ts +7 -0
  150. package/dist/mcp/manager.js +173 -0
  151. package/dist/mcp/manager.js.map +1 -0
  152. package/dist/mcp/record.d.ts +7 -0
  153. package/dist/mcp/record.js +20 -0
  154. package/dist/mcp/record.js.map +1 -0
  155. package/dist/mcp/stdio.d.ts +39 -0
  156. package/dist/mcp/stdio.js +382 -0
  157. package/dist/mcp/stdio.js.map +1 -0
  158. package/dist/mcp/types.d.ts +172 -0
  159. package/dist/mcp/types.js +2 -0
  160. package/dist/mcp/types.js.map +1 -0
  161. package/dist/memory/index.d.ts +2 -0
  162. package/dist/memory/index.js +3 -0
  163. package/dist/memory/index.js.map +1 -0
  164. package/dist/permissions/default-rules.d.ts +7 -0
  165. package/dist/permissions/default-rules.js +42 -0
  166. package/dist/permissions/default-rules.js.map +1 -0
  167. package/dist/permissions/errors.d.ts +11 -0
  168. package/dist/permissions/errors.js +14 -0
  169. package/dist/permissions/errors.js.map +1 -0
  170. package/dist/permissions/index.d.ts +9 -0
  171. package/dist/permissions/index.js +9 -0
  172. package/dist/permissions/index.js.map +1 -0
  173. package/dist/permissions/match.d.ts +33 -0
  174. package/dist/permissions/match.js +287 -0
  175. package/dist/permissions/match.js.map +1 -0
  176. package/dist/permissions/pipeline.d.ts +9 -0
  177. package/dist/permissions/pipeline.js +235 -0
  178. package/dist/permissions/pipeline.js.map +1 -0
  179. package/dist/permissions/rules.d.ts +22 -0
  180. package/dist/permissions/rules.js +74 -0
  181. package/dist/permissions/rules.js.map +1 -0
  182. package/dist/permissions/shadow.d.ts +5 -0
  183. package/dist/permissions/shadow.js +22 -0
  184. package/dist/permissions/shadow.js.map +1 -0
  185. package/dist/permissions/types.d.ts +104 -0
  186. package/dist/permissions/types.js +2 -0
  187. package/dist/permissions/types.js.map +1 -0
  188. package/dist/sandbox/base.d.ts +45 -0
  189. package/dist/sandbox/base.js +74 -0
  190. package/dist/sandbox/base.js.map +1 -0
  191. package/dist/sandbox/docker/index.d.ts +41 -0
  192. package/dist/sandbox/docker/index.js +497 -0
  193. package/dist/sandbox/docker/index.js.map +1 -0
  194. package/dist/sandbox/errors.d.ts +44 -0
  195. package/dist/sandbox/errors.js +57 -0
  196. package/dist/sandbox/errors.js.map +1 -0
  197. package/dist/sandbox/host-files.d.ts +65 -0
  198. package/dist/sandbox/host-files.js +258 -0
  199. package/dist/sandbox/host-files.js.map +1 -0
  200. package/dist/sandbox/index.d.ts +10 -0
  201. package/dist/sandbox/index.js +10 -0
  202. package/dist/sandbox/index.js.map +1 -0
  203. package/dist/sandbox/none.d.ts +17 -0
  204. package/dist/sandbox/none.js +108 -0
  205. package/dist/sandbox/none.js.map +1 -0
  206. package/dist/sandbox/policy.d.ts +49 -0
  207. package/dist/sandbox/policy.js +149 -0
  208. package/dist/sandbox/policy.js.map +1 -0
  209. package/dist/sandbox/process.d.ts +61 -0
  210. package/dist/sandbox/process.js +253 -0
  211. package/dist/sandbox/process.js.map +1 -0
  212. package/dist/sandbox/spawn-env.d.ts +20 -0
  213. package/dist/sandbox/spawn-env.js +128 -0
  214. package/dist/sandbox/spawn-env.js.map +1 -0
  215. package/dist/sandbox/srt/index.d.ts +38 -0
  216. package/dist/sandbox/srt/index.js +283 -0
  217. package/dist/sandbox/srt/index.js.map +1 -0
  218. package/dist/sandbox/srt/settings.d.ts +60 -0
  219. package/dist/sandbox/srt/settings.js +84 -0
  220. package/dist/sandbox/srt/settings.js.map +1 -0
  221. package/dist/sandbox/types.d.ts +125 -0
  222. package/dist/sandbox/types.js +6 -0
  223. package/dist/sandbox/types.js.map +1 -0
  224. package/dist/server/answers.d.ts +16 -0
  225. package/dist/server/answers.js +43 -0
  226. package/dist/server/answers.js.map +1 -0
  227. package/dist/server/connection.d.ts +99 -0
  228. package/dist/server/connection.js +309 -0
  229. package/dist/server/connection.js.map +1 -0
  230. package/dist/server/dispatcher.d.ts +86 -0
  231. package/dist/server/dispatcher.js +800 -0
  232. package/dist/server/dispatcher.js.map +1 -0
  233. package/dist/server/index.d.ts +13 -0
  234. package/dist/server/index.js +12 -0
  235. package/dist/server/index.js.map +1 -0
  236. package/dist/server/local-transport.d.ts +44 -0
  237. package/dist/server/local-transport.js +103 -0
  238. package/dist/server/local-transport.js.map +1 -0
  239. package/dist/server/outbox.d.ts +31 -0
  240. package/dist/server/outbox.js +130 -0
  241. package/dist/server/outbox.js.map +1 -0
  242. package/dist/server/params.d.ts +25 -0
  243. package/dist/server/params.js +112 -0
  244. package/dist/server/params.js.map +1 -0
  245. package/dist/server/protocol.schema.json +2448 -0
  246. package/dist/server/rpc-session.d.ts +43 -0
  247. package/dist/server/rpc-session.js +167 -0
  248. package/dist/server/rpc-session.js.map +1 -0
  249. package/dist/server/stdio-streams.d.ts +67 -0
  250. package/dist/server/stdio-streams.js +218 -0
  251. package/dist/server/stdio-streams.js.map +1 -0
  252. package/dist/server/stdio.d.ts +59 -0
  253. package/dist/server/stdio.js +189 -0
  254. package/dist/server/stdio.js.map +1 -0
  255. package/dist/server/websocket.d.ts +106 -0
  256. package/dist/server/websocket.js +327 -0
  257. package/dist/server/websocket.js.map +1 -0
  258. package/dist/session/approvals.d.ts +81 -0
  259. package/dist/session/approvals.js +217 -0
  260. package/dist/session/approvals.js.map +1 -0
  261. package/dist/session/code-call-log.d.ts +42 -0
  262. package/dist/session/code-call-log.js +63 -0
  263. package/dist/session/code-call-log.js.map +1 -0
  264. package/dist/session/code-call-result.d.ts +19 -0
  265. package/dist/session/code-call-result.js +95 -0
  266. package/dist/session/code-call-result.js.map +1 -0
  267. package/dist/session/code-call.d.ts +49 -0
  268. package/dist/session/code-call.js +345 -0
  269. package/dist/session/code-call.js.map +1 -0
  270. package/dist/session/effect-scope.d.ts +11 -0
  271. package/dist/session/effect-scope.js +10 -0
  272. package/dist/session/effect-scope.js.map +1 -0
  273. package/dist/session/errors.d.ts +19 -0
  274. package/dist/session/errors.js +27 -0
  275. package/dist/session/errors.js.map +1 -0
  276. package/dist/session/file-index.d.ts +8 -0
  277. package/dist/session/file-index.js +70 -0
  278. package/dist/session/file-index.js.map +1 -0
  279. package/dist/session/file-key-store.d.ts +16 -0
  280. package/dist/session/file-key-store.js +169 -0
  281. package/dist/session/file-key-store.js.map +1 -0
  282. package/dist/session/file-lock.d.ts +52 -0
  283. package/dist/session/file-lock.js +324 -0
  284. package/dist/session/file-lock.js.map +1 -0
  285. package/dist/session/index.d.ts +22 -0
  286. package/dist/session/index.js +20 -0
  287. package/dist/session/index.js.map +1 -0
  288. package/dist/session/jsonl-store.d.ts +37 -0
  289. package/dist/session/jsonl-store.js +386 -0
  290. package/dist/session/jsonl-store.js.map +1 -0
  291. package/dist/session/jsonl.d.ts +9 -0
  292. package/dist/session/jsonl.js +10 -0
  293. package/dist/session/jsonl.js.map +1 -0
  294. package/dist/session/lock.d.ts +19 -0
  295. package/dist/session/lock.js +2 -0
  296. package/dist/session/lock.js.map +1 -0
  297. package/dist/session/memory-store.d.ts +12 -0
  298. package/dist/session/memory-store.js +60 -0
  299. package/dist/session/memory-store.js.map +1 -0
  300. package/dist/session/migrate.d.ts +41 -0
  301. package/dist/session/migrate.js +86 -0
  302. package/dist/session/migrate.js.map +1 -0
  303. package/dist/session/pointer.d.ts +15 -0
  304. package/dist/session/pointer.js +22 -0
  305. package/dist/session/pointer.js.map +1 -0
  306. package/dist/session/rebuild.d.ts +53 -0
  307. package/dist/session/rebuild.js +230 -0
  308. package/dist/session/rebuild.js.map +1 -0
  309. package/dist/session/resume.d.ts +26 -0
  310. package/dist/session/resume.js +128 -0
  311. package/dist/session/resume.js.map +1 -0
  312. package/dist/session/retention.d.ts +97 -0
  313. package/dist/session/retention.js +702 -0
  314. package/dist/session/retention.js.map +1 -0
  315. package/dist/session/runner.d.ts +156 -0
  316. package/dist/session/runner.js +656 -0
  317. package/dist/session/runner.js.map +1 -0
  318. package/dist/session/scheduler.d.ts +47 -0
  319. package/dist/session/scheduler.js +85 -0
  320. package/dist/session/scheduler.js.map +1 -0
  321. package/dist/session/secret-key-store.d.ts +47 -0
  322. package/dist/session/secret-key-store.js +79 -0
  323. package/dist/session/secret-key-store.js.map +1 -0
  324. package/dist/session/session.d.ts +106 -0
  325. package/dist/session/session.js +353 -0
  326. package/dist/session/session.js.map +1 -0
  327. package/dist/session/sticky.d.ts +48 -0
  328. package/dist/session/sticky.js +232 -0
  329. package/dist/session/sticky.js.map +1 -0
  330. package/dist/session/store.d.ts +108 -0
  331. package/dist/session/store.js +163 -0
  332. package/dist/session/store.js.map +1 -0
  333. package/dist/telemetry/index.d.ts +2 -0
  334. package/dist/telemetry/index.js +3 -0
  335. package/dist/telemetry/index.js.map +1 -0
  336. package/dist/testing/fake-sandbox.d.ts +52 -0
  337. package/dist/testing/fake-sandbox.js +370 -0
  338. package/dist/testing/fake-sandbox.js.map +1 -0
  339. package/dist/testing/index.d.ts +10 -0
  340. package/dist/testing/index.js +11 -0
  341. package/dist/testing/index.js.map +1 -0
  342. package/dist/testing/key-store-conformance.d.ts +22 -0
  343. package/dist/testing/key-store-conformance.js +97 -0
  344. package/dist/testing/key-store-conformance.js.map +1 -0
  345. package/dist/testing/run-cases.d.ts +21 -0
  346. package/dist/testing/run-cases.js +20 -0
  347. package/dist/testing/run-cases.js.map +1 -0
  348. package/dist/testing/sandbox-conformance.d.ts +64 -0
  349. package/dist/testing/sandbox-conformance.js +468 -0
  350. package/dist/testing/sandbox-conformance.js.map +1 -0
  351. package/dist/testing/scheduler-conformance.d.ts +32 -0
  352. package/dist/testing/scheduler-conformance.js +72 -0
  353. package/dist/testing/scheduler-conformance.js.map +1 -0
  354. package/dist/testing/store-conformance.d.ts +21 -0
  355. package/dist/testing/store-conformance.js +320 -0
  356. package/dist/testing/store-conformance.js.map +1 -0
  357. package/dist/tools/builtins/bash.d.ts +9 -0
  358. package/dist/tools/builtins/bash.js +75 -0
  359. package/dist/tools/builtins/bash.js.map +1 -0
  360. package/dist/tools/builtins/builtins.d.ts +38 -0
  361. package/dist/tools/builtins/builtins.js +48 -0
  362. package/dist/tools/builtins/builtins.js.map +1 -0
  363. package/dist/tools/builtins/descriptions.d.ts +69 -0
  364. package/dist/tools/builtins/descriptions.js +94 -0
  365. package/dist/tools/builtins/descriptions.js.map +1 -0
  366. package/dist/tools/builtins/fetch.d.ts +12 -0
  367. package/dist/tools/builtins/fetch.js +157 -0
  368. package/dist/tools/builtins/fetch.js.map +1 -0
  369. package/dist/tools/builtins/files.d.ts +27 -0
  370. package/dist/tools/builtins/files.js +274 -0
  371. package/dist/tools/builtins/files.js.map +1 -0
  372. package/dist/tools/builtins/paths.d.ts +30 -0
  373. package/dist/tools/builtins/paths.js +62 -0
  374. package/dist/tools/builtins/paths.js.map +1 -0
  375. package/dist/tools/builtins/results.d.ts +15 -0
  376. package/dist/tools/builtins/results.js +31 -0
  377. package/dist/tools/builtins/results.js.map +1 -0
  378. package/dist/tools/builtins/search.d.ts +18 -0
  379. package/dist/tools/builtins/search.js +217 -0
  380. package/dist/tools/builtins/search.js.map +1 -0
  381. package/dist/tools/errors.d.ts +13 -0
  382. package/dist/tools/errors.js +17 -0
  383. package/dist/tools/errors.js.map +1 -0
  384. package/dist/tools/index.d.ts +12 -0
  385. package/dist/tools/index.js +11 -0
  386. package/dist/tools/index.js.map +1 -0
  387. package/dist/tools/registry.d.ts +3 -0
  388. package/dist/tools/registry.js +234 -0
  389. package/dist/tools/registry.js.map +1 -0
  390. package/dist/tools/tool-search.d.ts +30 -0
  391. package/dist/tools/tool-search.js +118 -0
  392. package/dist/tools/tool-search.js.map +1 -0
  393. package/dist/tools/types.d.ts +106 -0
  394. package/dist/tools/types.js +2 -0
  395. package/dist/tools/types.js.map +1 -0
  396. package/llms.txt +469 -0
  397. package/package.json +118 -3
@@ -0,0 +1,10 @@
1
+ /**
2
+ * `@buildanagent/harness/sandbox`: the sandbox interface, the unsafe `none` backend, `spawnEnv()`, and the policy
3
+ * read-back and capability helpers. The `srt` and Docker backends have their own subpaths. `fakeSandbox()` and the
4
+ * conformance suite are in `./testing`.
5
+ */
6
+ export { SandboxDeniedError, SandboxPolicyMismatchError, SandboxUnavailableError, SandboxUnsupportedError, } from "./errors.js";
7
+ export { NONE_SANDBOX_WARNING, noneSandbox } from "./none.js";
8
+ export { confirmPolicy, hasCapability, pauseSandbox, policyDifference, resumeSandbox, snapshotSandbox, stopsFor, } from "./policy.js";
9
+ export { spawnEnv } from "./spawn-env.js";
10
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/sandbox/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EACL,kBAAkB,EAClB,0BAA0B,EAC1B,uBAAuB,EACvB,uBAAuB,GACxB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,oBAAoB,EAA2B,WAAW,EAAE,MAAM,WAAW,CAAC;AACvF,OAAO,EACL,aAAa,EACb,aAAa,EACb,YAAY,EACZ,gBAAgB,EAChB,aAAa,EACb,eAAe,EACf,QAAQ,GACT,MAAM,aAAa,CAAC;AACrB,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC","sourcesContent":["/**\n * `@buildanagent/harness/sandbox`: the sandbox interface, the unsafe `none` backend, `spawnEnv()`, and the policy\n * read-back and capability helpers. The `srt` and Docker backends have their own subpaths. `fakeSandbox()` and the\n * conformance suite are in `./testing`.\n */\nexport {\n SandboxDeniedError,\n SandboxPolicyMismatchError,\n SandboxUnavailableError,\n SandboxUnsupportedError,\n} from \"./errors.js\";\nexport { NONE_SANDBOX_WARNING, type NoneSandboxOptions, noneSandbox } from \"./none.js\";\nexport {\n confirmPolicy,\n hasCapability,\n pauseSandbox,\n policyDifference,\n resumeSandbox,\n snapshotSandbox,\n stopsFor,\n} from \"./policy.js\";\nexport { spawnEnv } from \"./spawn-env.js\";\nexport type {\n ApprovalPolicy,\n ExecOptions,\n ExecResult,\n Sandbox,\n SandboxCapability,\n SandboxClient,\n SandboxDenial,\n SandboxPolicy,\n SandboxStop,\n SandboxTier,\n WorkspaceManifest,\n} from \"./types.js\";\n"]}
@@ -0,0 +1,17 @@
1
+ import type { SandboxClient } from "./types.js";
2
+ /** The options of `noneSandbox()`. */
3
+ export interface NoneSandboxOptions {
4
+ /** Must be `true`: the caller says it knows this backend confines nothing. Leaving it out is a type error. */
5
+ readonly unsafe: true;
6
+ /** Receives the start-up warning, once for each sandbox provisioned. Defaults to a line on standard error. */
7
+ readonly warn?: (message: string) => void;
8
+ }
9
+ /** The warning written when a sandbox starts. */
10
+ export declare const NONE_SANDBOX_WARNING = "WARNING: the none sandbox confines nothing. Commands run as this user with this machine's files and network.";
11
+ /**
12
+ * Builds the `none` backend. Without `unsafe: true` it is a type error, and at run time it throws a `HarnessError`,
13
+ * code `unsafe_sandbox_not_acknowledged`, so a JavaScript caller can't leave it out either. Provisioning writes the
14
+ * warning, then the manifest's files under its root, which must be an existing absolute folder. The policy is
15
+ * ignored: nothing here enforces it, which is what `stops: []` says.
16
+ */
17
+ export declare function noneSandbox(options: NoneSandboxOptions): SandboxClient;
@@ -0,0 +1,108 @@
1
+ /**
2
+ * `noneSandbox()`: the backend that confines nothing. It runs a command as the host's own user with the environment it
3
+ * is given, and it stops no mistake, no exfiltration and no hostile process, so its `stops` is empty and it refuses to
4
+ * be built without `unsafe: true` (HD4, ADR 0020). It exists for a machine that is already disposable and for tests of
5
+ * the rest of the harness. It is Node-only: it loads Node's modules by `process.getBuiltinModule()` when it is used.
6
+ * It starts each command in its own process group, so a timeout, an abort or a dispose ends the command's whole tree.
7
+ */
8
+ import { HarnessError } from "../errors.js";
9
+ import { checkCommand, checkOptions, nodeModules, ProcessRunner } from "./process.js";
10
+ /** The warning written when a sandbox starts. */
11
+ export const NONE_SANDBOX_WARNING = "WARNING: the none sandbox confines nothing. Commands run as this user with this machine's files and network.";
12
+ class NoneSandbox {
13
+ disposed = false;
14
+ root;
15
+ modules;
16
+ runner;
17
+ constructor(root, modules) {
18
+ this.root = root;
19
+ this.modules = modules;
20
+ this.runner = new ProcessRunner(modules);
21
+ }
22
+ live() {
23
+ if (this.disposed)
24
+ throw new HarnessError("sandbox_disposed", "the sandbox was disposed");
25
+ }
26
+ resolve(path) {
27
+ return this.modules.path.resolve(this.root, path);
28
+ }
29
+ /** The working directory as an absolute path, or an error when it isn't an existing folder. */
30
+ async workingDirectory(options) {
31
+ const cwd = this.resolve(options.cwd ?? ".");
32
+ const stats = await this.modules.fs.stat(cwd).catch(() => undefined);
33
+ if (!stats?.isDirectory()) {
34
+ throw new HarnessError("invalid_sandbox_options", `the working directory ${cwd} is not an existing folder`);
35
+ }
36
+ return cwd;
37
+ }
38
+ async exec(command, options) {
39
+ this.live();
40
+ checkCommand(command);
41
+ checkOptions(options);
42
+ options.signal.throwIfAborted();
43
+ const cwd = await this.workingDirectory(options);
44
+ // The sandbox or the signal may have changed while the folder was checked.
45
+ this.live();
46
+ options.signal.throwIfAborted();
47
+ const [program, ...args] = command;
48
+ const { stdoutBytes: _bytes, ...result } = await this.runner.run({ program, args, cwd, env: options.env, missingProgram: "result" }, options);
49
+ return result;
50
+ }
51
+ async readFile(path) {
52
+ this.live();
53
+ const target = this.resolve(path);
54
+ try {
55
+ return new Uint8Array(await this.modules.fs.readFile(target));
56
+ }
57
+ catch (error) {
58
+ if (error.code === "ENOENT") {
59
+ throw new HarnessError("sandbox_not_found", `no such file: ${target}`, { cause: error });
60
+ }
61
+ throw error;
62
+ }
63
+ }
64
+ async writeFile(path, data) {
65
+ this.live();
66
+ const target = this.resolve(path);
67
+ await this.modules.fs.mkdir(this.modules.path.dirname(target), { recursive: true });
68
+ await this.modules.fs.writeFile(target, data);
69
+ }
70
+ async dispose() {
71
+ this.disposed = true;
72
+ await this.runner.stopAll();
73
+ }
74
+ }
75
+ /**
76
+ * Builds the `none` backend. Without `unsafe: true` it is a type error, and at run time it throws a `HarnessError`,
77
+ * code `unsafe_sandbox_not_acknowledged`, so a JavaScript caller can't leave it out either. Provisioning writes the
78
+ * warning, then the manifest's files under its root, which must be an existing absolute folder. The policy is
79
+ * ignored: nothing here enforces it, which is what `stops: []` says.
80
+ */
81
+ export function noneSandbox(options) {
82
+ if (options?.unsafe !== true) {
83
+ throw new HarnessError("unsafe_sandbox_not_acknowledged", "noneSandbox confines nothing, so it needs { unsafe: true } to say the caller knows");
84
+ }
85
+ const warn = options.warn ?? ((message) => process.stderr.write(`${message}\n`));
86
+ return {
87
+ tier: "none",
88
+ stops: [],
89
+ async provision(manifest) {
90
+ const modules = nodeModules("none");
91
+ if (!modules.path.isAbsolute(manifest.root)) {
92
+ throw new HarnessError("invalid_sandbox_options", "a workspace manifest's root must be an absolute path");
93
+ }
94
+ const stats = await modules.fs.stat(manifest.root).catch(() => undefined);
95
+ if (!stats?.isDirectory()) {
96
+ throw new HarnessError("invalid_sandbox_options", "a workspace manifest's root must be an existing folder");
97
+ }
98
+ warn(NONE_SANDBOX_WARNING);
99
+ const sandbox = new NoneSandbox(manifest.root, modules);
100
+ const encoder = new TextEncoder();
101
+ for (const [path, data] of Object.entries(manifest.files ?? {})) {
102
+ await sandbox.writeFile(path, typeof data === "string" ? encoder.encode(data) : data);
103
+ }
104
+ return sandbox;
105
+ },
106
+ };
107
+ }
108
+ //# sourceMappingURL=none.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"none.js","sourceRoot":"","sources":["../../src/sandbox/none.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `noneSandbox()`: the backend that confines nothing. It runs a command as the host's own user with the environment it\n * is given, and it stops no mistake, no exfiltration and no hostile process, so its `stops` is empty and it refuses to\n * be built without `unsafe: true` (HD4, ADR 0020). It exists for a machine that is already disposable and for tests of\n * the rest of the harness. It is Node-only: it loads Node's modules by `process.getBuiltinModule()` when it is used.\n * It starts each command in its own process group, so a timeout, an abort or a dispose ends the command's whole tree.\n */\nimport { HarnessError } from \"../errors.js\";\nimport { checkCommand, checkOptions, type NodeModules, nodeModules, ProcessRunner } from \"./process.js\";\nimport type { ExecOptions, ExecResult, Sandbox, SandboxClient, WorkspaceManifest } from \"./types.js\";\n\n/** The options of `noneSandbox()`. */\nexport interface NoneSandboxOptions {\n /** Must be `true`: the caller says it knows this backend confines nothing. Leaving it out is a type error. */\n readonly unsafe: true;\n /** Receives the start-up warning, once for each sandbox provisioned. Defaults to a line on standard error. */\n readonly warn?: (message: string) => void;\n}\n\n/** The warning written when a sandbox starts. */\nexport const NONE_SANDBOX_WARNING =\n \"WARNING: the none sandbox confines nothing. Commands run as this user with this machine's files and network.\";\n\nclass NoneSandbox implements Sandbox {\n private disposed = false;\n private readonly root: string;\n private readonly modules: NodeModules;\n private readonly runner: ProcessRunner;\n\n constructor(root: string, modules: NodeModules) {\n this.root = root;\n this.modules = modules;\n this.runner = new ProcessRunner(modules);\n }\n\n private live(): void {\n if (this.disposed) throw new HarnessError(\"sandbox_disposed\", \"the sandbox was disposed\");\n }\n\n private resolve(path: string): string {\n return this.modules.path.resolve(this.root, path);\n }\n\n /** The working directory as an absolute path, or an error when it isn't an existing folder. */\n private async workingDirectory(options: ExecOptions): Promise<string> {\n const cwd = this.resolve(options.cwd ?? \".\");\n const stats = await this.modules.fs.stat(cwd).catch(() => undefined);\n if (!stats?.isDirectory()) {\n throw new HarnessError(\"invalid_sandbox_options\", `the working directory ${cwd} is not an existing folder`);\n }\n return cwd;\n }\n\n async exec(command: readonly string[], options: ExecOptions): Promise<ExecResult> {\n this.live();\n checkCommand(command);\n checkOptions(options);\n options.signal.throwIfAborted();\n const cwd = await this.workingDirectory(options);\n // The sandbox or the signal may have changed while the folder was checked.\n this.live();\n options.signal.throwIfAborted();\n const [program, ...args] = command as [string, ...string[]];\n const { stdoutBytes: _bytes, ...result } = await this.runner.run(\n { program, args, cwd, env: options.env, missingProgram: \"result\" },\n options,\n );\n return result;\n }\n\n async readFile(path: string): Promise<Uint8Array> {\n this.live();\n const target = this.resolve(path);\n try {\n return new Uint8Array(await this.modules.fs.readFile(target));\n } catch (error) {\n if ((error as NodeJS.ErrnoException).code === \"ENOENT\") {\n throw new HarnessError(\"sandbox_not_found\", `no such file: ${target}`, { cause: error });\n }\n throw error;\n }\n }\n\n async writeFile(path: string, data: Uint8Array): Promise<void> {\n this.live();\n const target = this.resolve(path);\n await this.modules.fs.mkdir(this.modules.path.dirname(target), { recursive: true });\n await this.modules.fs.writeFile(target, data);\n }\n\n async dispose(): Promise<void> {\n this.disposed = true;\n await this.runner.stopAll();\n }\n}\n\n/**\n * Builds the `none` backend. Without `unsafe: true` it is a type error, and at run time it throws a `HarnessError`,\n * code `unsafe_sandbox_not_acknowledged`, so a JavaScript caller can't leave it out either. Provisioning writes the\n * warning, then the manifest's files under its root, which must be an existing absolute folder. The policy is\n * ignored: nothing here enforces it, which is what `stops: []` says.\n */\nexport function noneSandbox(options: NoneSandboxOptions): SandboxClient {\n if ((options as { unsafe?: unknown } | undefined)?.unsafe !== true) {\n throw new HarnessError(\n \"unsafe_sandbox_not_acknowledged\",\n \"noneSandbox confines nothing, so it needs { unsafe: true } to say the caller knows\",\n );\n }\n const warn = options.warn ?? ((message: string) => process.stderr.write(`${message}\\n`));\n return {\n tier: \"none\",\n stops: [],\n async provision(manifest: WorkspaceManifest) {\n const modules = nodeModules(\"none\");\n if (!modules.path.isAbsolute(manifest.root)) {\n throw new HarnessError(\"invalid_sandbox_options\", \"a workspace manifest's root must be an absolute path\");\n }\n const stats = await modules.fs.stat(manifest.root).catch(() => undefined);\n if (!stats?.isDirectory()) {\n throw new HarnessError(\"invalid_sandbox_options\", \"a workspace manifest's root must be an existing folder\");\n }\n warn(NONE_SANDBOX_WARNING);\n const sandbox = new NoneSandbox(manifest.root, modules);\n const encoder = new TextEncoder();\n for (const [path, data] of Object.entries(manifest.files ?? {})) {\n await sandbox.writeFile(path, typeof data === \"string\" ? encoder.encode(data) : data);\n }\n return sandbox;\n },\n };\n}\n"]}
@@ -0,0 +1,49 @@
1
+ import type { Sandbox, SandboxCapability, SandboxClient, SandboxPolicy, SandboxStop, SandboxTier } from "./types.js";
2
+ /**
3
+ * The method by which `resumeSandbox()` sets the stops of a sandbox whose `stops` is a getter, such as a backend
4
+ * sandbox's, so that a later `confirm()` still updates what the getter reads. It is internal to the package.
5
+ */
6
+ export declare const APPLY_STOPS: unique symbol;
7
+ /**
8
+ * The stops a backend of `tier` delivers under `policy`. A `none` tier stops nothing. Any other tier stops `mistakes`
9
+ * unless a root is `/`, and `exfiltration` unless the allowlist holds an entry that opens every host (`*`, `0.0.0.0/0`
10
+ * or `::/0`). Only a `microvm` stops a `hostile_process`, because every other tier shares a kernel with the host or
11
+ * relies on one that runs in user space.
12
+ */
13
+ export declare function stopsFor(tier: SandboxTier, policy: SandboxPolicy): SandboxStop[];
14
+ /**
15
+ * The first field in which `applied` differs from `requested`, or `undefined` when they hold the same entries. The
16
+ * fields are compared as sets in the order `readRoots`, `writeRoots`, `network.allow`, `network.deny`, and a field
17
+ * that isn't a list of strings differs. Paths and hosts compare as written, so a backend reads back in the request's
18
+ * spelling.
19
+ */
20
+ export declare function policyDifference(requested: SandboxPolicy, applied: SandboxPolicy): string | undefined;
21
+ /** The options of `confirmPolicy()`. */
22
+ interface ConfirmOptions {
23
+ /** Whether a mismatch disposes the sandbox before it is thrown. Defaults to `true`. */
24
+ readonly dispose?: boolean;
25
+ }
26
+ /**
27
+ * Reads back the policy `sandbox` applied and compares it with `requested`. It resolves with the stops the applied
28
+ * policy delivers, and it throws `SandboxPolicyMismatchError` when a field differs, when the client claims a stop that
29
+ * the applied policy doesn't deliver (`stops`, with the cause in the message), or when a client that claims a stop has
30
+ * no read-back or its read-back fails (`readBack`, or the read-back's own field when it threw a mismatch). A client
31
+ * that claims no stop needs no read-back. It disposes the sandbox before it throws, unless `options.dispose` is
32
+ * `false`, which leaves the sandbox to the caller.
33
+ */
34
+ export declare function confirmPolicy(client: SandboxClient, sandbox: Sandbox, requested: SandboxPolicy, options?: ConfirmOptions): Promise<readonly SandboxStop[]>;
35
+ /** Whether `client` lists `capability`. A client that lists none has none. */
36
+ export declare function hasCapability(client: SandboxClient, capability: SandboxCapability): boolean;
37
+ /**
38
+ * Reattaches to a sandbox by its id, or starts one from a snapshot's id, then confirms its policy as `provision()`
39
+ * does and sets the sandbox's `stops` to what the confirmed policy delivers. It throws `SandboxUnsupportedError` when
40
+ * the client doesn't list `resume` or has no `resume()`, and `SandboxPolicyMismatchError` when the resumed sandbox's
41
+ * policy differs from `policy`. A mismatch does not dispose the sandbox, which may be a paused one worth keeping: the
42
+ * caller decides whether to dispose it, and must not run anything in it under the requested policy.
43
+ */
44
+ export declare function resumeSandbox(client: SandboxClient, id: string, policy: SandboxPolicy): Promise<Sandbox>;
45
+ /** Snapshots `sandbox` and resolves with the id `resumeSandbox()` takes, or throws `SandboxUnsupportedError`. */
46
+ export declare function snapshotSandbox(client: SandboxClient, sandbox: Sandbox): Promise<string>;
47
+ /** Pauses `sandbox` until `resumeSandbox()` with its `id`, or throws `SandboxUnsupportedError`. */
48
+ export declare function pauseSandbox(client: SandboxClient, sandbox: Sandbox): Promise<void>;
49
+ export {};
@@ -0,0 +1,149 @@
1
+ /**
2
+ * What a sandbox's applied policy delivers, and the checks around it: `stopsFor()` computes the stops from a tier and a
3
+ * policy, `policyDifference()` compares two policies field by field, and `confirmPolicy()` reads a provisioned
4
+ * sandbox's policy back and throws when it differs from the request. The capability helpers refuse a resume, snapshot
5
+ * or pause that the backend doesn't list. It is portable: it imports no Node module.
6
+ */
7
+ import { SandboxPolicyMismatchError, SandboxUnsupportedError } from "./errors.js";
8
+ /**
9
+ * The method by which `resumeSandbox()` sets the stops of a sandbox whose `stops` is a getter, such as a backend
10
+ * sandbox's, so that a later `confirm()` still updates what the getter reads. It is internal to the package.
11
+ */
12
+ export const APPLY_STOPS = Symbol("applyStops");
13
+ // Allowlist entries a hosted provider reads as "every host", so a policy holding one leaves egress open.
14
+ const OPEN_EGRESS = new Set(["*", "0.0.0.0/0", "::/0"]);
15
+ /** Whether a root is the whole file system, however many slashes it is written with. */
16
+ const isWholeDisk = (root) => /^\/+$/.test(root);
17
+ /**
18
+ * The stops a backend of `tier` delivers under `policy`. A `none` tier stops nothing. Any other tier stops `mistakes`
19
+ * unless a root is `/`, and `exfiltration` unless the allowlist holds an entry that opens every host (`*`, `0.0.0.0/0`
20
+ * or `::/0`). Only a `microvm` stops a `hostile_process`, because every other tier shares a kernel with the host or
21
+ * relies on one that runs in user space.
22
+ */
23
+ export function stopsFor(tier, policy) {
24
+ if (tier === "none")
25
+ return [];
26
+ const stops = [];
27
+ if (![...policy.readRoots, ...policy.writeRoots].some(isWholeDisk))
28
+ stops.push("mistakes");
29
+ if (!policy.network.allow.some((entry) => OPEN_EGRESS.has(entry.trim())))
30
+ stops.push("exfiltration");
31
+ if (tier === "microvm")
32
+ stops.push("hostile_process");
33
+ return stops;
34
+ }
35
+ /** Whether `value` is a list of strings, which is the only shape a policy's lists may have. */
36
+ const isStringList = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
37
+ /** Whether two lists hold the same entries, ignoring order and repeats. */
38
+ function sameEntries(left, right) {
39
+ const a = new Set(left);
40
+ const b = new Set(right);
41
+ return a.size === b.size && [...a].every((entry) => b.has(entry));
42
+ }
43
+ /**
44
+ * The first field in which `applied` differs from `requested`, or `undefined` when they hold the same entries. The
45
+ * fields are compared as sets in the order `readRoots`, `writeRoots`, `network.allow`, `network.deny`, and a field
46
+ * that isn't a list of strings differs. Paths and hosts compare as written, so a backend reads back in the request's
47
+ * spelling.
48
+ */
49
+ export function policyDifference(requested, applied) {
50
+ const network = applied.network;
51
+ const fields = [
52
+ ["readRoots", requested.readRoots, applied.readRoots],
53
+ ["writeRoots", requested.writeRoots, applied.writeRoots],
54
+ ["network.allow", requested.network.allow, network?.allow],
55
+ ["network.deny", requested.network.deny, network?.deny],
56
+ ];
57
+ for (const [field, wanted, got] of fields) {
58
+ if (!isStringList(got) || !sameEntries(wanted, got))
59
+ return field;
60
+ }
61
+ return undefined;
62
+ }
63
+ // Why the applied policy can't deliver each stop, in words that hold no path or host from either policy.
64
+ const UNDELIVERED = {
65
+ mistakes: "the policy reads or writes the whole disk, so the sandbox cannot stop mistakes",
66
+ exfiltration: "the policy allows all hosts, so the sandbox cannot stop exfiltration",
67
+ hostile_process: "this tier shares a kernel with the host, so the sandbox cannot stop a hostile process",
68
+ };
69
+ /**
70
+ * Reads back the policy `sandbox` applied and compares it with `requested`. It resolves with the stops the applied
71
+ * policy delivers, and it throws `SandboxPolicyMismatchError` when a field differs, when the client claims a stop that
72
+ * the applied policy doesn't deliver (`stops`, with the cause in the message), or when a client that claims a stop has
73
+ * no read-back or its read-back fails (`readBack`, or the read-back's own field when it threw a mismatch). A client
74
+ * that claims no stop needs no read-back. It disposes the sandbox before it throws, unless `options.dispose` is
75
+ * `false`, which leaves the sandbox to the caller.
76
+ */
77
+ export async function confirmPolicy(client, sandbox, requested, options = {}) {
78
+ const refuse = async (field, more) => {
79
+ if (options.dispose !== false)
80
+ await sandbox.dispose().catch(() => undefined);
81
+ throw new SandboxPolicyMismatchError(field, more);
82
+ };
83
+ if (typeof sandbox.readBack !== "function") {
84
+ if (client.stops.length === 0)
85
+ return [];
86
+ return refuse("readBack");
87
+ }
88
+ let applied;
89
+ try {
90
+ applied = await sandbox.readBack();
91
+ }
92
+ catch (error) {
93
+ // A read-back that found the mismatch itself, such as a settings file with another write root, names its field.
94
+ return refuse(error instanceof SandboxPolicyMismatchError ? error.field : "readBack", { cause: error });
95
+ }
96
+ const field = policyDifference(requested, applied);
97
+ if (field !== undefined)
98
+ return refuse(field);
99
+ const delivered = stopsFor(client.tier, applied);
100
+ const missing = client.stops.filter((stop) => !delivered.includes(stop));
101
+ if (missing.length > 0) {
102
+ return refuse("stops", { reason: [...new Set(missing)].map((stop) => UNDELIVERED[stop]).join("; ") });
103
+ }
104
+ return delivered;
105
+ }
106
+ /** Whether `client` lists `capability`. A client that lists none has none. */
107
+ export function hasCapability(client, capability) {
108
+ return Array.isArray(client.capabilities) && client.capabilities.includes(capability);
109
+ }
110
+ /**
111
+ * Reattaches to a sandbox by its id, or starts one from a snapshot's id, then confirms its policy as `provision()`
112
+ * does and sets the sandbox's `stops` to what the confirmed policy delivers. It throws `SandboxUnsupportedError` when
113
+ * the client doesn't list `resume` or has no `resume()`, and `SandboxPolicyMismatchError` when the resumed sandbox's
114
+ * policy differs from `policy`. A mismatch does not dispose the sandbox, which may be a paused one worth keeping: the
115
+ * caller decides whether to dispose it, and must not run anything in it under the requested policy.
116
+ */
117
+ export async function resumeSandbox(client, id, policy) {
118
+ if (!hasCapability(client, "resume") || typeof client.resume !== "function") {
119
+ throw new SandboxUnsupportedError("resume", client.tier);
120
+ }
121
+ const sandbox = await client.resume(id, policy);
122
+ const stops = await confirmPolicy(client, sandbox, policy, { dispose: false });
123
+ const apply = sandbox[APPLY_STOPS];
124
+ if (typeof apply === "function") {
125
+ // An own `stops` would shadow the getter, so a later confirm() could no longer change what the sandbox reports.
126
+ apply.call(sandbox, stops);
127
+ return sandbox;
128
+ }
129
+ const set = Reflect.defineProperty(sandbox, "stops", { value: stops, enumerable: true, configurable: true });
130
+ if (!set && !sameEntries(sandbox.stops ?? [], stops)) {
131
+ throw new SandboxPolicyMismatchError("stops", { reason: "the resumed sandbox's stops can't be set" });
132
+ }
133
+ return sandbox;
134
+ }
135
+ /** Snapshots `sandbox` and resolves with the id `resumeSandbox()` takes, or throws `SandboxUnsupportedError`. */
136
+ export async function snapshotSandbox(client, sandbox) {
137
+ if (!hasCapability(client, "snapshot") || typeof sandbox.snapshot !== "function") {
138
+ throw new SandboxUnsupportedError("snapshot", client.tier);
139
+ }
140
+ return sandbox.snapshot();
141
+ }
142
+ /** Pauses `sandbox` until `resumeSandbox()` with its `id`, or throws `SandboxUnsupportedError`. */
143
+ export async function pauseSandbox(client, sandbox) {
144
+ if (!hasCapability(client, "pause") || typeof sandbox.pause !== "function") {
145
+ throw new SandboxUnsupportedError("pause", client.tier);
146
+ }
147
+ await sandbox.pause();
148
+ }
149
+ //# sourceMappingURL=policy.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"policy.js","sourceRoot":"","sources":["../../src/sandbox/policy.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * What a sandbox's applied policy delivers, and the checks around it: `stopsFor()` computes the stops from a tier and a\n * policy, `policyDifference()` compares two policies field by field, and `confirmPolicy()` reads a provisioned\n * sandbox's policy back and throws when it differs from the request. The capability helpers refuse a resume, snapshot\n * or pause that the backend doesn't list. It is portable: it imports no Node module.\n */\nimport { SandboxPolicyMismatchError, SandboxUnsupportedError } from \"./errors.js\";\nimport type { Sandbox, SandboxCapability, SandboxClient, SandboxPolicy, SandboxStop, SandboxTier } from \"./types.js\";\n\n/**\n * The method by which `resumeSandbox()` sets the stops of a sandbox whose `stops` is a getter, such as a backend\n * sandbox's, so that a later `confirm()` still updates what the getter reads. It is internal to the package.\n */\nexport const APPLY_STOPS: unique symbol = Symbol(\"applyStops\");\n\n// Allowlist entries a hosted provider reads as \"every host\", so a policy holding one leaves egress open.\nconst OPEN_EGRESS = new Set([\"*\", \"0.0.0.0/0\", \"::/0\"]);\n\n/** Whether a root is the whole file system, however many slashes it is written with. */\nconst isWholeDisk = (root: string): boolean => /^\\/+$/.test(root);\n\n/**\n * The stops a backend of `tier` delivers under `policy`. A `none` tier stops nothing. Any other tier stops `mistakes`\n * unless a root is `/`, and `exfiltration` unless the allowlist holds an entry that opens every host (`*`, `0.0.0.0/0`\n * or `::/0`). Only a `microvm` stops a `hostile_process`, because every other tier shares a kernel with the host or\n * relies on one that runs in user space.\n */\nexport function stopsFor(tier: SandboxTier, policy: SandboxPolicy): SandboxStop[] {\n if (tier === \"none\") return [];\n const stops: SandboxStop[] = [];\n if (![...policy.readRoots, ...policy.writeRoots].some(isWholeDisk)) stops.push(\"mistakes\");\n if (!policy.network.allow.some((entry) => OPEN_EGRESS.has(entry.trim()))) stops.push(\"exfiltration\");\n if (tier === \"microvm\") stops.push(\"hostile_process\");\n return stops;\n}\n\n/** Whether `value` is a list of strings, which is the only shape a policy's lists may have. */\nconst isStringList = (value: unknown): value is readonly string[] =>\n Array.isArray(value) && value.every((item) => typeof item === \"string\");\n\n/** Whether two lists hold the same entries, ignoring order and repeats. */\nfunction sameEntries(left: readonly string[], right: readonly string[]): boolean {\n const a = new Set(left);\n const b = new Set(right);\n return a.size === b.size && [...a].every((entry) => b.has(entry));\n}\n\n/**\n * The first field in which `applied` differs from `requested`, or `undefined` when they hold the same entries. The\n * fields are compared as sets in the order `readRoots`, `writeRoots`, `network.allow`, `network.deny`, and a field\n * that isn't a list of strings differs. Paths and hosts compare as written, so a backend reads back in the request's\n * spelling.\n */\nexport function policyDifference(requested: SandboxPolicy, applied: SandboxPolicy): string | undefined {\n const network = (applied as { network?: unknown }).network as Partial<SandboxPolicy[\"network\"]> | undefined;\n const fields: [string, readonly string[], unknown][] = [\n [\"readRoots\", requested.readRoots, (applied as { readRoots?: unknown }).readRoots],\n [\"writeRoots\", requested.writeRoots, (applied as { writeRoots?: unknown }).writeRoots],\n [\"network.allow\", requested.network.allow, network?.allow],\n [\"network.deny\", requested.network.deny, network?.deny],\n ];\n for (const [field, wanted, got] of fields) {\n if (!isStringList(got) || !sameEntries(wanted, got)) return field;\n }\n return undefined;\n}\n\n// Why the applied policy can't deliver each stop, in words that hold no path or host from either policy.\nconst UNDELIVERED: Record<SandboxStop, string> = {\n mistakes: \"the policy reads or writes the whole disk, so the sandbox cannot stop mistakes\",\n exfiltration: \"the policy allows all hosts, so the sandbox cannot stop exfiltration\",\n hostile_process: \"this tier shares a kernel with the host, so the sandbox cannot stop a hostile process\",\n};\n\n/** The options of `confirmPolicy()`. */\ninterface ConfirmOptions {\n /** Whether a mismatch disposes the sandbox before it is thrown. Defaults to `true`. */\n readonly dispose?: boolean;\n}\n\n/**\n * Reads back the policy `sandbox` applied and compares it with `requested`. It resolves with the stops the applied\n * policy delivers, and it throws `SandboxPolicyMismatchError` when a field differs, when the client claims a stop that\n * the applied policy doesn't deliver (`stops`, with the cause in the message), or when a client that claims a stop has\n * no read-back or its read-back fails (`readBack`, or the read-back's own field when it threw a mismatch). A client\n * that claims no stop needs no read-back. It disposes the sandbox before it throws, unless `options.dispose` is\n * `false`, which leaves the sandbox to the caller.\n */\nexport async function confirmPolicy(\n client: SandboxClient,\n sandbox: Sandbox,\n requested: SandboxPolicy,\n options: ConfirmOptions = {},\n): Promise<readonly SandboxStop[]> {\n const refuse = async (field: string, more?: { cause?: unknown; reason?: string }): Promise<never> => {\n if (options.dispose !== false) await sandbox.dispose().catch(() => undefined);\n throw new SandboxPolicyMismatchError(field, more);\n };\n if (typeof sandbox.readBack !== \"function\") {\n if (client.stops.length === 0) return [];\n return refuse(\"readBack\");\n }\n let applied: SandboxPolicy;\n try {\n applied = await sandbox.readBack();\n } catch (error) {\n // A read-back that found the mismatch itself, such as a settings file with another write root, names its field.\n return refuse(error instanceof SandboxPolicyMismatchError ? error.field : \"readBack\", { cause: error });\n }\n const field = policyDifference(requested, applied);\n if (field !== undefined) return refuse(field);\n const delivered = stopsFor(client.tier, applied);\n const missing = client.stops.filter((stop) => !delivered.includes(stop));\n if (missing.length > 0) {\n return refuse(\"stops\", { reason: [...new Set(missing)].map((stop) => UNDELIVERED[stop]).join(\"; \") });\n }\n return delivered;\n}\n\n/** Whether `client` lists `capability`. A client that lists none has none. */\nexport function hasCapability(client: SandboxClient, capability: SandboxCapability): boolean {\n return Array.isArray(client.capabilities) && client.capabilities.includes(capability);\n}\n\n/**\n * Reattaches to a sandbox by its id, or starts one from a snapshot's id, then confirms its policy as `provision()`\n * does and sets the sandbox's `stops` to what the confirmed policy delivers. It throws `SandboxUnsupportedError` when\n * the client doesn't list `resume` or has no `resume()`, and `SandboxPolicyMismatchError` when the resumed sandbox's\n * policy differs from `policy`. A mismatch does not dispose the sandbox, which may be a paused one worth keeping: the\n * caller decides whether to dispose it, and must not run anything in it under the requested policy.\n */\nexport async function resumeSandbox(client: SandboxClient, id: string, policy: SandboxPolicy): Promise<Sandbox> {\n if (!hasCapability(client, \"resume\") || typeof client.resume !== \"function\") {\n throw new SandboxUnsupportedError(\"resume\", client.tier);\n }\n const sandbox = await client.resume(id, policy);\n const stops = await confirmPolicy(client, sandbox, policy, { dispose: false });\n const apply = (sandbox as { [APPLY_STOPS]?: (stops: readonly SandboxStop[]) => void })[APPLY_STOPS];\n if (typeof apply === \"function\") {\n // An own `stops` would shadow the getter, so a later confirm() could no longer change what the sandbox reports.\n apply.call(sandbox, stops);\n return sandbox;\n }\n const set = Reflect.defineProperty(sandbox, \"stops\", { value: stops, enumerable: true, configurable: true });\n if (!set && !sameEntries(sandbox.stops ?? [], stops)) {\n throw new SandboxPolicyMismatchError(\"stops\", { reason: \"the resumed sandbox's stops can't be set\" });\n }\n return sandbox;\n}\n\n/** Snapshots `sandbox` and resolves with the id `resumeSandbox()` takes, or throws `SandboxUnsupportedError`. */\nexport async function snapshotSandbox(client: SandboxClient, sandbox: Sandbox): Promise<string> {\n if (!hasCapability(client, \"snapshot\") || typeof sandbox.snapshot !== \"function\") {\n throw new SandboxUnsupportedError(\"snapshot\", client.tier);\n }\n return sandbox.snapshot();\n}\n\n/** Pauses `sandbox` until `resumeSandbox()` with its `id`, or throws `SandboxUnsupportedError`. */\nexport async function pauseSandbox(client: SandboxClient, sandbox: Sandbox): Promise<void> {\n if (!hasCapability(client, \"pause\") || typeof sandbox.pause !== \"function\") {\n throw new SandboxUnsupportedError(\"pause\", client.tier);\n }\n await sandbox.pause();\n}\n"]}
@@ -0,0 +1,61 @@
1
+ import type { ExecOptions, ExecResult } from "./types.js";
2
+ /** The Node modules the backends use. */
3
+ export type NodeModules = {
4
+ readonly cp: typeof import("node:child_process");
5
+ readonly fs: typeof import("node:fs/promises");
6
+ readonly os: typeof import("node:os");
7
+ readonly path: typeof import("node:path");
8
+ readonly url: typeof import("node:url");
9
+ };
10
+ /** Node's modules, or a `SandboxUnavailableError` for `backend` on a runtime that lacks them. */
11
+ export declare function nodeModules(backend: string): NodeModules;
12
+ /** Throws unless the options are usable. */
13
+ export declare function checkOptions(options: ExecOptions): void;
14
+ /** Throws unless the command is a non-empty list of strings. */
15
+ export declare function checkCommand(command: readonly string[]): void;
16
+ /** What one process is started with. */
17
+ export interface ProcessSpec {
18
+ readonly program: string;
19
+ readonly args: readonly string[];
20
+ readonly cwd: string;
21
+ readonly env: Readonly<Record<string, string>>;
22
+ /** Bytes to write to the process's standard input before closing it. Without it, standard input is closed at once. */
23
+ readonly input?: Uint8Array;
24
+ /** Whether a program that can't be started is a result with exit code 127, as a shell gives, or a rejection. */
25
+ readonly missingProgram: "result" | "reject";
26
+ /**
27
+ * How long a stopped process's group has to exit after a `SIGTERM`, which lets a program clean up, before a `SIGKILL`
28
+ * ends what is left. Without it the group is killed at once.
29
+ */
30
+ readonly graceMs?: number;
31
+ /**
32
+ * Runs, and is awaited, when a timeout, an abort or `stopAll()` ends the process, before its group is killed. A
33
+ * backend whose commands run outside the process's group, such as in a container, ends them here.
34
+ */
35
+ readonly onStop?: () => Promise<void>;
36
+ }
37
+ /** A finished process: the `ExecResult` fields, and the raw bytes of standard output. */
38
+ export type ProcessResult = Extract<ExecResult, {
39
+ exitCode: number;
40
+ }> & {
41
+ readonly stdoutBytes: Uint8Array;
42
+ };
43
+ /** Runs processes, each in its own group, and ends them all on `stopAll()`. */
44
+ export declare class ProcessRunner {
45
+ private readonly modules;
46
+ private readonly running;
47
+ constructor(modules: NodeModules);
48
+ /** Kills the process's whole group, or just the process where the platform has no groups. */
49
+ private kill;
50
+ /** The exit code, and the signal's name when a signal killed the process. */
51
+ private exit;
52
+ /** Ends every process still running, each one's promise rejecting with `sandbox_disposed`, and waits until they have. */
53
+ stopAll(): Promise<void>;
54
+ /** Ends the process's group: at once, or with a `SIGTERM` first and a `SIGKILL` after `graceMs` for what is left. */
55
+ private end;
56
+ /**
57
+ * Runs the process and resolves when it exits, its signal aborts it, its timeout passes (exit code 124) or `stopAll()`
58
+ * runs. An abort rejects with the signal's reason, and `stopAll()` with `sandbox_disposed`.
59
+ */
60
+ run(spec: ProcessSpec, options: ExecOptions): Promise<ProcessResult>;
61
+ }