foldrun 19.2.6 → 19.3.0

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.
package/docs/network.md CHANGED
@@ -296,7 +296,8 @@ What a held step does differently:
296
296
  and every other — they browse from their own network, which no list here
297
297
  holds), `proxy=` (a proxy of your own is not reachable), `live:` sessions,
298
298
  and the Lightpanda and Obscura engines (no way through the proxy verified
299
- yet). A vendor step is refused before it connects; to accept browsing that
299
+ yet). A vendor step is refused before it connects — unless the install
300
+ holds that vendor through its vendor door (below); to accept browsing that
300
301
  no list holds for one agent, give that agent `network: open`.
301
302
  - **Secrets bound to sites** stay out of the sandbox: a `headers=` value can
302
303
  carry the `${NAME}`, which the proxy fills; `auth=`, `cookies=` and
@@ -306,8 +307,13 @@ What a held step does differently:
306
307
  secret. Chromium is told to trust the egress CA for them by its key;
307
308
  Firefox browses in a profile whose certificate database holds it (the
308
309
  session's profile, or one made for the call), and the trace says
309
- `browser: firefox trusts the egress proxy's certificate`. WebKit is not
310
- told yet, and a page there fails its certificate check.
310
+ `browser: firefox trusts the egress proxy's certificate`. WebKit trusts
311
+ only the system store, so the platform puts the CA there for any step that
312
+ gets it: an init container builds the store from a platform-owned
313
+ ConfigMap and the sandbox mounts it at `/etc/ssl/certs`, root's and not
314
+ the agent's to change (the
315
+ trace says `egress CA: in this sandbox's system trust store too`), and
316
+ every other program that reads only the system store trusts it as well.
311
317
  - **Web search** goes through the egress proxy's search door, as for any
312
318
  walled step ([Search](#search)).
313
319
 
@@ -339,6 +345,39 @@ applies to an agent. An agent that must stay inside its list where browsing
339
345
  is not held should not browse: give it `web: {actions: [search, fetch]}`,
340
346
  which goes through the proxy like any other program.
341
347
 
348
+ ### A vendor's browser, through foldrun's vendor door
349
+
350
+ A rented browser — Browserbase, Steel, Hyperbrowser or Browserless, the four
351
+ that take a customer's proxy — runs on the vendor's machines, so the egress
352
+ proxy never sees its pages. On an install that holds a vendor through its
353
+ **vendor door** (`FOLDRUN_VENDOR_EGRESS`, below; FOL-145), a held step may
354
+ use that vendor instead of being refused:
355
+
356
+ - the vendor's key is bound to the vendor's API, so it is only a name in the
357
+ sandbox and the egress proxy fills it;
358
+ - every call to the vendor goes through the proxy, under that vendor's
359
+ session rules: the call that **starts** a browser is rewritten so its only
360
+ proxy is foldrun's vendor door, with a credential made for that session
361
+ (fifteen minutes at most, ended with the step); reading or ending a
362
+ session passes; anything else is refused, and the trace says why;
363
+ - the vendor's remote-control connection goes through the proxy's `/e/`
364
+ door as well — the walled sandbox reaches nothing else;
365
+ - the door holds every page to the step's list, refuses private addresses,
366
+ caps connections and bytes per step, and closes the step's connections
367
+ within a second of the step ending;
368
+ - **no site a secret is bound to**: a vendor's browser cannot trust foldrun's
369
+ certificate, so the proxy cannot fill a secret there — such a page is
370
+ refused (`unsupported capability: vendor secret filling`); use foldrun's
371
+ own browser for those steps;
372
+ - for such a step there is no way round: plain `http://` to a vendor, a
373
+ tunnel to a vendor whose key is not bound, and a tunnel to a bare address
374
+ are refused.
375
+
376
+ Bright Data, ZenRows and a raw DevTools address always browse through their
377
+ own network and are never held this way. A vendor is listed on an install
378
+ only once it has passed foldrun's qualification for it (FOL-151); until then
379
+ it is refused under a held list, as before.
380
+
342
381
  ### The browse service
343
382
 
344
383
  On a cluster whose operator has switched it on (`FOLDRUN_BROWSE_SERVICE=1`,
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "foldrun",
3
- "version": "19.2.6",
3
+ "version": "19.3.0",
4
4
  "description": "Agents are just folders. Write them, check them, run them — on your machine.",
5
5
  "license": "FSL-1.1-ALv2",
6
6
  "type": "module",
package/src/commands.mjs CHANGED
@@ -9957,11 +9957,16 @@ async function agentLinkCmd(positional, flags, layout) {
9957
9957
  * from core's listAgents when it says (core ≥ the FOL-110 phase 3 release).
9958
9958
  * @param {{ level?: string, enforceWanted?: unknown, browseVendor?: unknown }} p
9959
9959
  */
9960
- function browsingLine(p) {
9960
+ function browsingLine(p, doorable = false) {
9961
9961
  const vendor = typeof p.browseVendor === "string" && p.browseVendor ? p.browseVendor : null;
9962
9962
  const enforce = p.enforceWanted === true ? " (network_enforce: true here)" : "";
9963
+ // FOL-145: a vendor that takes a customer proxy can be held through the
9964
+ // platform's vendor door, where the install lists it; the rest never can.
9965
+ const door = doorable
9966
+ ? ` — unless the platform holds ${vendor} through its vendor door (an install that lists it): then the session it starts has foldrun's door as its only proxy and its pages are held to this list, sites a secret is bound to excepted`
9967
+ : "";
9963
9968
  return vendor
9964
- ? `browsing: this agent browses with ${vendor}, which browses from its own network — on a platform that confines browsing, with this list enforced${enforce}, its steps are refused before they connect; elsewhere they are not held to the list (\`foldrun docs network\`, Browsing). Drop browse: ${vendor} to use foldrun's own browser, which is held to it.`
9969
+ ? `browsing: this agent browses with ${vendor}, which browses from its own network — on a platform that confines browsing, with this list enforced${enforce}, its steps are refused before they connect${door}; elsewhere they are not held to the list (\`foldrun docs network\`, Browsing). Drop browse: ${vendor} to use foldrun's own browser, which is held to it.`
9965
9970
  : `browsing: this agent may browse. On a platform that confines browsing, with this list enforced${enforce}, its browser runs walled in the step's sandbox and the list holds for it; on this machine, or with the list only reported, its browser and its other programs reach sites directly (\`foldrun docs network\`, Browsing).`;
9966
9971
  }
9967
9972
 
@@ -10024,12 +10029,18 @@ async function agentNetworkCmd(positional, flags, layout) {
10024
10029
  : (info?.tools ?? []).includes("web") && (!actions || actions.includes("browse"));
10025
10030
  return { info, own: net.readNetwork(front.network).setting, browses };
10026
10031
  });
10032
+ // FOL-145: which vendors can be held through a vendor door (core providers).
10033
+ const doorProviders = await import("@foldrun/core/providers").catch(() => null);
10027
10034
  const show = (info, browses) => {
10028
10035
  const p = info?.network;
10029
10036
  if (!p) return;
10030
10037
  console.log(` ${net.networkLine(p, true)}`);
10031
10038
  if (p.level !== "open") console.log(` ${c.dim("a run also allows its MCP servers, its web providers and the sites its secrets are bound to")}`);
10032
- if (browses && p.level !== "open") console.log(` ${c.yellow(browsingLine(p))}`);
10039
+ if (browses && p.level !== "open") {
10040
+ const vendor = typeof p.browseVendor === "string" ? p.browseVendor : "";
10041
+ const doorable = !!vendor && /** @type {any} */ (doorProviders)?.findBrowserApi?.(vendor)?.egress === "proxy";
10042
+ console.log(` ${c.yellow(browsingLine(p, doorable))}`);
10043
+ }
10033
10044
  const search = searchLine(p);
10034
10045
  if (search) console.log(` ${c.dim(search)}`);
10035
10046
  };