@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,170 @@
1
+ /**
2
+ * `EgressPolicy`: what a sandbox may reach, as plain data that names its credentials but never holds them, so a
3
+ * backend can compile it, store it or send it to a hosted provider without carrying a secret. `compileEgressPolicy()`
4
+ * compiles it for the local proxy, `startEgressProxy()`. It is portable: it imports no Node module.
5
+ */
6
+ import { HarnessError } from "../errors.js";
7
+ import { isAddressLiteral } from "./addresses.js";
8
+ import { gitHostOverlap, parseAllow, parseRoutes } from "./allowlist.js";
9
+ import { checkGitFilter } from "./git-route.js";
10
+ const CREDENTIAL_NAME = /^[A-Z][A-Z0-9_]{0,63}$/;
11
+ // Well-known credential formats, matched at the start of a value or of a token in it. Each prefix must be followed by a
12
+ // body as long as a real token's, so a token pasted where its name belongs is refused while an ordinary name that
13
+ // merely starts with such letters, such as sk-labs/app, sk-api.example.com or a route named sk-proxy, is not. An AWS
14
+ // key id is matched only as a whole token, because its prefix starts ordinary upper-case names too.
15
+ const CREDENTIAL_SHAPED = new RegExp([
16
+ "^gh[pousr]_[A-Za-z0-9]{30,}",
17
+ "^github_pat_[A-Za-z0-9_]{20,}",
18
+ "^xox[abposr]-[A-Za-z0-9-]{10,}",
19
+ "^sk-[A-Za-z0-9_-]{20,}",
20
+ "^sk_(live|test)_[A-Za-z0-9]{20,}",
21
+ "^glpat-[A-Za-z0-9_-]{20,}",
22
+ "^AIza[A-Za-z0-9_-]{30,}",
23
+ "^(AKIA|ASIA)[0-9A-Z]{16}$",
24
+ ].join("|"));
25
+ const AUTH_SCHEME = /^(Bearer|Basic) /i;
26
+ // What separates a pasted token from the text around it: white space, and the punctuation of `key=value`, `user:pass`,
27
+ // `user@host`, lists and quotes. A repository's `/` and a host's `.` are not separators.
28
+ const TOKEN_SEPARATOR = /[\s=:@,;"'`]+/;
29
+ /** Whether `text` looks like a credential, or carries one in a token or after an auth scheme. */
30
+ const credentialShaped = (text) => AUTH_SCHEME.test(text) || text.split(TOKEN_SEPARATOR).some((token) => CREDENTIAL_SHAPED.test(token));
31
+ const HEADER_FIELDS = new Set(["kind", "route", "host", "methods", "header", "credential"]);
32
+ const GIT_FIELDS = new Set(["kind", "route", "host", "repositories", "pushRefs", "fetch", "username", "credential"]);
33
+ const DEFAULT_GIT_USERNAME = "x-access-token";
34
+ const invalid = (message) => new HarnessError("invalid_egress_options", message);
35
+ /** Every string anywhere in `value`, for the scan that refuses a credential-shaped one. */
36
+ function strings(value) {
37
+ if (typeof value === "string")
38
+ return [value];
39
+ if (Array.isArray(value))
40
+ return value.flatMap(strings);
41
+ if (typeof value === "object" && value !== null)
42
+ return Object.values(value).flatMap(strings);
43
+ return [];
44
+ }
45
+ /** Throws unless `entry` is an exact host name, with an optional port. The message names only its place. */
46
+ function checkHost(entry, where) {
47
+ const text = typeof entry === "string" ? entry : "";
48
+ const name = text.replace(/:[0-9]+$/, "");
49
+ if (text.includes("*") || name.startsWith("[") || isAddressLiteral(name)) {
50
+ throw invalid(`${where} must be an exact host name, not a wildcard or an address`);
51
+ }
52
+ try {
53
+ parseAllow([text]);
54
+ }
55
+ catch {
56
+ // The proxy's own message quotes the entry, which this one must not.
57
+ throw invalid(`${where} must be a host name, such as example.com`);
58
+ }
59
+ }
60
+ /** Throws unless `route` has only its kind's fields and names its credential. */
61
+ function checkRoute(route, index) {
62
+ if (typeof route !== "object" || route === null)
63
+ throw invalid(`route ${index} is not an object`);
64
+ const kind = route.kind;
65
+ const fields = kind === "header" ? HEADER_FIELDS : kind === "git" ? GIT_FIELDS : undefined;
66
+ if (fields === undefined)
67
+ throw invalid(`route ${index} must have the kind header or git`);
68
+ if (Object.keys(route).some((key) => !fields.has(key))) {
69
+ throw invalid(`route ${index} has a field an egress route doesn't have, such as a credential's value`);
70
+ }
71
+ const credential = route.credential;
72
+ if (typeof credential !== "string" || !CREDENTIAL_NAME.test(credential)) {
73
+ throw invalid(`route ${index} must name its credential in upper case, such as GITHUB_TOKEN, not hold it`);
74
+ }
75
+ checkHost(route.host, `the host of route ${index}`);
76
+ const { route: name, methods, pushRefs } = route;
77
+ const listed = (value) => Array.isArray(value) && value.every((item) => typeof item === "string");
78
+ if (typeof name !== "string" || (kind === "header" && !listed(methods))) {
79
+ throw invalid(`route ${index} needs a name and, for a header route, a list of methods`);
80
+ }
81
+ if (kind === "git" && pushRefs !== undefined && !listed(pushRefs))
82
+ throw invalid(`route ${index}'s pushRefs is not a list`);
83
+ }
84
+ /** The proxy's filter for a git route, with its defaults filled in. */
85
+ function gitFilter(route) {
86
+ return {
87
+ repositories: Array.isArray(route.repositories) ? [...route.repositories] : [],
88
+ pushRefs: [...(route.pushRefs ?? [])],
89
+ fetch: route.fetch ?? false,
90
+ username: route.username ?? DEFAULT_GIT_USERNAME,
91
+ };
92
+ }
93
+ /** The local proxy's route for one checked egress route. */
94
+ function toCredentialRoute(route, options) {
95
+ const secret = () => options.secret(route.credential);
96
+ if (route.kind === "header") {
97
+ return { route: route.route, host: route.host, methods: [...route.methods], header: route.header, secret };
98
+ }
99
+ return {
100
+ route: route.route,
101
+ host: route.host,
102
+ methods: ["GET", "POST"],
103
+ header: "authorization",
104
+ secret,
105
+ git: gitFilter(route),
106
+ };
107
+ }
108
+ /** Throws unless each git route's filter is usable and no tunnel or other route reaches its host. */
109
+ function checkGitRoutes(routes, allow) {
110
+ const overlap = gitHostOverlap(routes.map((route) => ({ host: route.host, ...(route.kind === "git" ? { git: gitFilter(route) } : {}) })), parseAllow(allow));
111
+ if (overlap?.with === "allow") {
112
+ throw invalid(`the host of git route ${overlap.index} is also in allow, so a tunnel could go around its ref filter`);
113
+ }
114
+ if (overlap?.with === "route") {
115
+ throw invalid(`the host of git route ${overlap.index} is another route's host, so that route could go around its ref filter`);
116
+ }
117
+ for (const [index, route] of routes.entries()) {
118
+ if (route.kind !== "git")
119
+ continue;
120
+ try {
121
+ checkGitFilter(gitFilter(route));
122
+ }
123
+ catch (error) {
124
+ // The filter's messages name a field and its place, never its value.
125
+ throw invalid(`git route ${index} is not usable: ${error.message}`);
126
+ }
127
+ }
128
+ }
129
+ /**
130
+ * Checks `policy` and compiles it for `startEgressProxy()`: pass the result's `allow` and `routes` with a `log`.
131
+ * Everything is refused that isn't plainly allowed, with `HarnessError` code `invalid_egress_options`, and the
132
+ * message names the entry's place, never its value:
133
+ *
134
+ * - a field a route kind doesn't have, such as `secret` or `token`, and a credential that is not an upper-case name;
135
+ * - any string in the policy that looks like a credential, such as one starting `ghp_` or `sk-`;
136
+ * - a wildcard or an address literal in `allow` or a route's host;
137
+ * - a git route whose host is also in `allow`, because a tunnel to it would go around the ref filter, and a git route
138
+ * whose host is another route's host, because that route would carry a credential there without the ref filter;
139
+ * - a git route with no repository, a push ref outside `refs/heads/`, or neither a push nor a fetch.
140
+ *
141
+ * The compiled routes read each credential through `options.secret` at every request, so a rotated one is used at once.
142
+ */
143
+ export function compileEgressPolicy(policy, options) {
144
+ if (typeof options?.secret !== "function")
145
+ throw invalid("compileEgressPolicy needs a secret function");
146
+ const { allow, routes } = (policy ?? {});
147
+ if (!Array.isArray(allow) || !Array.isArray(routes))
148
+ throw invalid("an egress policy has an allow and a routes list");
149
+ if (Object.keys(policy).some((key) => key !== "allow" && key !== "routes")) {
150
+ throw invalid("an egress policy has only allow and routes");
151
+ }
152
+ if (strings(policy).some(credentialShaped)) {
153
+ throw invalid("the egress policy holds what looks like a credential; name it in a route's credential instead");
154
+ }
155
+ for (const [index, entry] of allow.entries())
156
+ checkHost(entry, `allow entry ${index}`);
157
+ for (const [index, route] of routes.entries())
158
+ checkRoute(route, index);
159
+ checkGitRoutes(routes, allow);
160
+ const compiled = routes.map((route) => toCredentialRoute(route, options));
161
+ try {
162
+ parseRoutes(compiled, parseAllow(allow));
163
+ }
164
+ catch {
165
+ // The proxy's own message quotes the route's name or header, which this one must not.
166
+ throw invalid("a route's name, methods or header is not usable, or two routes share a name");
167
+ }
168
+ return { allow: [...allow], routes: compiled };
169
+ }
170
+ //# sourceMappingURL=egress-policy.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"egress-policy.js","sourceRoot":"","sources":["../../src/credentials/egress-policy.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * `EgressPolicy`: what a sandbox may reach, as plain data that names its credentials but never holds them, so a\n * backend can compile it, store it or send it to a hosted provider without carrying a secret. `compileEgressPolicy()`\n * compiles it for the local proxy, `startEgressProxy()`. It is portable: it imports no Node module.\n */\nimport { HarnessError } from \"../errors.js\";\nimport { isAddressLiteral } from \"./addresses.js\";\nimport { type CredentialRoute, gitHostOverlap, parseAllow, parseRoutes } from \"./allowlist.js\";\nimport { checkGitFilter, type GitRouteFilter } from \"./git-route.js\";\n\n/** A route that swaps the sentinel in one request header for a credential, as `startEgressProxy()`'s routes do. */\nexport interface HeaderEgressRoute {\n readonly kind: \"header\";\n /** The first part of the path the sandbox requests, such as `github`. Lower case letters, digits, `-` and `_`. */\n readonly route: string;\n /** The HTTPS host the request is forwarded to, such as `api.github.com`, with `:port` when it isn't 443. */\n readonly host: string;\n /** The methods the route accepts, such as `[\"GET\"]`. */\n readonly methods: readonly string[];\n /** The request header that carries the credential, such as `authorization`. */\n readonly header: string;\n /** The name of the credential the host injects, in upper case, such as `GITHUB_TOKEN`. Never the credential. */\n readonly credential: string;\n}\n\n/**\n * A route for git over HTTPS: git's smart HTTP requests for the listed repositories only, and a push only to the listed\n * branches. A deletion and a tag are always refused, and so is anything the route can't parse.\n */\nexport interface GitEgressRoute {\n readonly kind: \"git\";\n /** The first part of the path the sandbox's git remote uses, such as `git`. */\n readonly route: string;\n /** The git host, such as `github.com`. */\n readonly host: string;\n /** The repositories the route reaches, as `owner/name`. */\n readonly repositories: readonly string[];\n /** The branches a push may create or update, such as `refs/heads/agent/*`. Leave it out to refuse every push. */\n readonly pushRefs?: readonly string[];\n /** Whether a fetch or clone may read the repositories. Defaults to `false`. */\n readonly fetch?: boolean;\n /** The user name sent with the credential in HTTP Basic. Defaults to `x-access-token`, which GitHub App tokens use. */\n readonly username?: string;\n /** The name of the credential the host injects, in upper case, such as `GITHUB_TOKEN`. Never the credential. */\n readonly credential: string;\n}\n\n/** One credential route of an `EgressPolicy`. */\nexport type EgressRoute = HeaderEgressRoute | GitEgressRoute;\n\n/** What a sandbox may reach: the hosts it may tunnel to, and the routes that add a credential on its behalf. */\nexport interface EgressPolicy {\n /** Exact host names, with `:port` when it isn't 443. A wildcard and an address literal are refused. */\n readonly allow: readonly string[];\n readonly routes: readonly EgressRoute[];\n}\n\n/** The options of `compileEgressPolicy()`. */\nexport interface CompileEgressOptions {\n /** Reads the credential a route names, at each request, on the host. It never runs in the sandbox. */\n readonly secret: (name: string) => Promise<string>;\n}\n\n/** A compiled policy: the `allow` and `routes` options of `startEgressProxy()`. */\nexport interface CompiledEgressPolicy {\n readonly allow: readonly string[];\n readonly routes: readonly CredentialRoute[];\n}\n\nconst CREDENTIAL_NAME = /^[A-Z][A-Z0-9_]{0,63}$/;\n// Well-known credential formats, matched at the start of a value or of a token in it. Each prefix must be followed by a\n// body as long as a real token's, so a token pasted where its name belongs is refused while an ordinary name that\n// merely starts with such letters, such as sk-labs/app, sk-api.example.com or a route named sk-proxy, is not. An AWS\n// key id is matched only as a whole token, because its prefix starts ordinary upper-case names too.\nconst CREDENTIAL_SHAPED = new RegExp(\n [\n \"^gh[pousr]_[A-Za-z0-9]{30,}\",\n \"^github_pat_[A-Za-z0-9_]{20,}\",\n \"^xox[abposr]-[A-Za-z0-9-]{10,}\",\n \"^sk-[A-Za-z0-9_-]{20,}\",\n \"^sk_(live|test)_[A-Za-z0-9]{20,}\",\n \"^glpat-[A-Za-z0-9_-]{20,}\",\n \"^AIza[A-Za-z0-9_-]{30,}\",\n \"^(AKIA|ASIA)[0-9A-Z]{16}$\",\n ].join(\"|\"),\n);\nconst AUTH_SCHEME = /^(Bearer|Basic) /i;\n// What separates a pasted token from the text around it: white space, and the punctuation of `key=value`, `user:pass`,\n// `user@host`, lists and quotes. A repository's `/` and a host's `.` are not separators.\nconst TOKEN_SEPARATOR = /[\\s=:@,;\"'`]+/;\n\n/** Whether `text` looks like a credential, or carries one in a token or after an auth scheme. */\nconst credentialShaped = (text: string): boolean =>\n AUTH_SCHEME.test(text) || text.split(TOKEN_SEPARATOR).some((token) => CREDENTIAL_SHAPED.test(token));\nconst HEADER_FIELDS = new Set([\"kind\", \"route\", \"host\", \"methods\", \"header\", \"credential\"]);\nconst GIT_FIELDS = new Set([\"kind\", \"route\", \"host\", \"repositories\", \"pushRefs\", \"fetch\", \"username\", \"credential\"]);\nconst DEFAULT_GIT_USERNAME = \"x-access-token\";\n\nconst invalid = (message: string) => new HarnessError(\"invalid_egress_options\", message);\n\n/** Every string anywhere in `value`, for the scan that refuses a credential-shaped one. */\nfunction strings(value: unknown): string[] {\n if (typeof value === \"string\") return [value];\n if (Array.isArray(value)) return value.flatMap(strings);\n if (typeof value === \"object\" && value !== null) return Object.values(value).flatMap(strings);\n return [];\n}\n\n/** Throws unless `entry` is an exact host name, with an optional port. The message names only its place. */\nfunction checkHost(entry: unknown, where: string): void {\n const text = typeof entry === \"string\" ? entry : \"\";\n const name = text.replace(/:[0-9]+$/, \"\");\n if (text.includes(\"*\") || name.startsWith(\"[\") || isAddressLiteral(name)) {\n throw invalid(`${where} must be an exact host name, not a wildcard or an address`);\n }\n try {\n parseAllow([text]);\n } catch {\n // The proxy's own message quotes the entry, which this one must not.\n throw invalid(`${where} must be a host name, such as example.com`);\n }\n}\n\n/** Throws unless `route` has only its kind's fields and names its credential. */\nfunction checkRoute(route: unknown, index: number): asserts route is EgressRoute {\n if (typeof route !== \"object\" || route === null) throw invalid(`route ${index} is not an object`);\n const kind = (route as { kind?: unknown }).kind;\n const fields = kind === \"header\" ? HEADER_FIELDS : kind === \"git\" ? GIT_FIELDS : undefined;\n if (fields === undefined) throw invalid(`route ${index} must have the kind header or git`);\n if (Object.keys(route).some((key) => !fields.has(key))) {\n throw invalid(`route ${index} has a field an egress route doesn't have, such as a credential's value`);\n }\n const credential = (route as { credential?: unknown }).credential;\n if (typeof credential !== \"string\" || !CREDENTIAL_NAME.test(credential)) {\n throw invalid(`route ${index} must name its credential in upper case, such as GITHUB_TOKEN, not hold it`);\n }\n checkHost((route as { host?: unknown }).host, `the host of route ${index}`);\n const { route: name, methods, pushRefs } = route as { route?: unknown; methods?: unknown; pushRefs?: unknown };\n const listed = (value: unknown) => Array.isArray(value) && value.every((item) => typeof item === \"string\");\n if (typeof name !== \"string\" || (kind === \"header\" && !listed(methods))) {\n throw invalid(`route ${index} needs a name and, for a header route, a list of methods`);\n }\n if (kind === \"git\" && pushRefs !== undefined && !listed(pushRefs))\n throw invalid(`route ${index}'s pushRefs is not a list`);\n}\n\n/** The proxy's filter for a git route, with its defaults filled in. */\nfunction gitFilter(route: GitEgressRoute): GitRouteFilter {\n return {\n repositories: Array.isArray(route.repositories) ? [...route.repositories] : [],\n pushRefs: [...(route.pushRefs ?? [])],\n fetch: route.fetch ?? false,\n username: route.username ?? DEFAULT_GIT_USERNAME,\n };\n}\n\n/** The local proxy's route for one checked egress route. */\nfunction toCredentialRoute(route: EgressRoute, options: CompileEgressOptions): CredentialRoute {\n const secret = () => options.secret(route.credential);\n if (route.kind === \"header\") {\n return { route: route.route, host: route.host, methods: [...route.methods], header: route.header, secret };\n }\n return {\n route: route.route,\n host: route.host,\n methods: [\"GET\", \"POST\"],\n header: \"authorization\",\n secret,\n git: gitFilter(route),\n };\n}\n\n/** Throws unless each git route's filter is usable and no tunnel or other route reaches its host. */\nfunction checkGitRoutes(routes: readonly EgressRoute[], allow: readonly string[]): void {\n const overlap = gitHostOverlap(\n routes.map((route) => ({ host: route.host, ...(route.kind === \"git\" ? { git: gitFilter(route) } : {}) })),\n parseAllow(allow),\n );\n if (overlap?.with === \"allow\") {\n throw invalid(\n `the host of git route ${overlap.index} is also in allow, so a tunnel could go around its ref filter`,\n );\n }\n if (overlap?.with === \"route\") {\n throw invalid(\n `the host of git route ${overlap.index} is another route's host, so that route could go around its ref filter`,\n );\n }\n for (const [index, route] of routes.entries()) {\n if (route.kind !== \"git\") continue;\n try {\n checkGitFilter(gitFilter(route));\n } catch (error) {\n // The filter's messages name a field and its place, never its value.\n throw invalid(`git route ${index} is not usable: ${(error as Error).message}`);\n }\n }\n}\n\n/**\n * Checks `policy` and compiles it for `startEgressProxy()`: pass the result's `allow` and `routes` with a `log`.\n * Everything is refused that isn't plainly allowed, with `HarnessError` code `invalid_egress_options`, and the\n * message names the entry's place, never its value:\n *\n * - a field a route kind doesn't have, such as `secret` or `token`, and a credential that is not an upper-case name;\n * - any string in the policy that looks like a credential, such as one starting `ghp_` or `sk-`;\n * - a wildcard or an address literal in `allow` or a route's host;\n * - a git route whose host is also in `allow`, because a tunnel to it would go around the ref filter, and a git route\n * whose host is another route's host, because that route would carry a credential there without the ref filter;\n * - a git route with no repository, a push ref outside `refs/heads/`, or neither a push nor a fetch.\n *\n * The compiled routes read each credential through `options.secret` at every request, so a rotated one is used at once.\n */\nexport function compileEgressPolicy(policy: EgressPolicy, options: CompileEgressOptions): CompiledEgressPolicy {\n if (typeof options?.secret !== \"function\") throw invalid(\"compileEgressPolicy needs a secret function\");\n const { allow, routes } = (policy ?? {}) as Partial<EgressPolicy>;\n if (!Array.isArray(allow) || !Array.isArray(routes)) throw invalid(\"an egress policy has an allow and a routes list\");\n if (Object.keys(policy).some((key) => key !== \"allow\" && key !== \"routes\")) {\n throw invalid(\"an egress policy has only allow and routes\");\n }\n if (strings(policy).some(credentialShaped)) {\n throw invalid(\"the egress policy holds what looks like a credential; name it in a route's credential instead\");\n }\n for (const [index, entry] of allow.entries()) checkHost(entry, `allow entry ${index}`);\n for (const [index, route] of routes.entries()) checkRoute(route, index);\n checkGitRoutes(routes, allow);\n const compiled = routes.map((route) => toCredentialRoute(route, options));\n try {\n parseRoutes(compiled, parseAllow(allow));\n } catch {\n // The proxy's own message quotes the route's name or header, which this one must not.\n throw invalid(\"a route's name, methods or header is not usable, or two routes share a name\");\n }\n return { allow: [...allow], routes: compiled };\n}\n"]}
@@ -0,0 +1,82 @@
1
+ import { type CredentialRoute } from "./allowlist.js";
2
+ export type { CredentialRoute } from "./allowlist.js";
3
+ /** One line of the egress log. It names the host and the outcome, and never holds a header, a body or a secret. */
4
+ export interface EgressRecord {
5
+ /** When the request ended, as an ISO 8601 string. */
6
+ readonly time: string;
7
+ /** `connect` for a tunnel, `route` for a credential route and `fetch` for an in-process call. */
8
+ readonly kind: "connect" | "route" | "fetch";
9
+ /** The host the request was for. */
10
+ readonly host: string;
11
+ readonly port: number;
12
+ readonly method: string;
13
+ /** The status the sandbox saw: 200 for an established tunnel, 403 for a refusal, 502 for a failed connection. */
14
+ readonly status: number;
15
+ /** The bytes that went both ways, 0 for a refusal. */
16
+ readonly bytes: number;
17
+ /** The route's name, for a route request. */
18
+ readonly route?: string | undefined;
19
+ /** Why a request was refused or failed, as a short code such as `not_allowed` or `address_refused`. */
20
+ readonly reason?: string;
21
+ }
22
+ /** The options of `startEgressProxy()`. */
23
+ export interface EgressProxyOptions {
24
+ /** The names a tunnel or an in-process fetch may reach: `example.com`, `*.example.com`, or either with `:port`. */
25
+ readonly allow: readonly string[];
26
+ /** The credential routes. Without any, the proxy only tunnels. */
27
+ readonly routes?: readonly CredentialRoute[];
28
+ /** Receives one record for each request. A throw from it is ignored. */
29
+ readonly log: (record: EgressRecord) => void;
30
+ /** Listens on this Unix socket instead of a port on `127.0.0.1`, so a container can mount it (`dockerSandbox`'s `proxySocket`). */
31
+ readonly socketPath?: string;
32
+ /** Extra certificate authorities to trust for the routes' hosts and for the fetch, such as a test's own. */
33
+ readonly ca?: string | Uint8Array | readonly (string | Uint8Array)[];
34
+ /** Resolves a name to its addresses. Defaults to the system resolver. Every address it returns is checked. */
35
+ readonly resolve?: (host: string) => Promise<readonly string[]>;
36
+ /**
37
+ * Addresses that skip the public-address check. This exists so a test can reach a server on `127.0.0.1`. Never set it
38
+ * for a real run: the check is what keeps a name that points at the host's own network from being reached.
39
+ */
40
+ readonly unsafeAllowAddresses?: readonly string[];
41
+ /**
42
+ * Ends a tunnel, a forwarded request or a push check that is idle this long. A whole number of milliseconds from 0 to
43
+ * 2,147,483,647, where 0 turns the idle timeout off, as it does for a socket; anything else throws
44
+ * `invalid_egress_options` when the proxy starts. Defaults to 120000.
45
+ */
46
+ readonly idleTimeoutMs?: number;
47
+ /**
48
+ * The longest a push's command list may take to arrive, from the start of its body, however often bytes come. The
49
+ * clock starts once and is never reset, so a client that sends a byte just inside the idle timeout is still cut off;
50
+ * a push that takes longer is refused with `git_timeout`. Only the command list is timed, not the pack after it. A
51
+ * whole number of milliseconds from 1 to 2,147,483,647; anything else throws `invalid_egress_options` when the proxy
52
+ * starts. Defaults to 60000.
53
+ */
54
+ readonly pushCheckTimeoutMs?: number;
55
+ }
56
+ /** A running egress proxy. */
57
+ export interface EgressProxy {
58
+ /**
59
+ * Where the sandbox sends its requests: give it as `HTTPS_PROXY`, and join a route's name to it for a route. On a Unix
60
+ * socket it is `unix:<path>`, which is not a proxy URL: the program that uses the socket connects to it itself.
61
+ */
62
+ readonly url: string;
63
+ /** The Unix socket the proxy listens on, when it was started with `socketPath`. */
64
+ readonly socketPath?: string;
65
+ /** For each route, the placeholder the sandbox puts where the credential goes. The real secret never leaves the host. */
66
+ readonly sentinels: Readonly<Record<string, string>>;
67
+ /**
68
+ * Fetches `input` for an in-process tool, under the same allowlist. A host that isn't on it rejects with `egress_denied`.
69
+ * A route is reached at `${proxy.url}/<route>/…`, or at `http://egress.proxy/<route>/…`, which also works on a Unix socket.
70
+ */
71
+ fetch(input: string | URL, init?: RequestInit): Promise<Response>;
72
+ /** The routes' secrets now, for `scrubSecrets()`. */
73
+ knownSecrets(): Promise<readonly string[]>;
74
+ /** Stops listening and ends every open tunnel and request. */
75
+ close(): Promise<void>;
76
+ }
77
+ /**
78
+ * Starts the egress proxy on `127.0.0.1` with a port the system picks, or on `socketPath`. The allowlist and routes are
79
+ * checked first, and a bad entry throws `invalid_egress_options`. Give the sandbox `proxy.url` as `HTTPS_PROXY`, and
80
+ * give a tool that needs a credential the route's URL and its sentinel.
81
+ */
82
+ export declare function startEgressProxy(options: EgressProxyOptions): Promise<EgressProxy>;