Skip to content

safe-bash: documented @poe-platform/safe-bash/browser Workers entry fails to start without nodejs_compat — contracts/io.ts imports node:stream/web, contracts/path.ts imports node:path #671

Closed as not planned

Description

@kamilio

Where: packages/safe-bash/src/contracts/io.ts:5 (import { TransformStream } from "node:stream/web") and packages/safe-bash/src/contracts/path.ts:2 (export { posix as posixPath } from "node:path"). Both are in the contracts/ core layer, which is in the import graph of the @poe-platform/safe-bash/browser entry. The ./browser export has no browser/workerd condition (package.json: "./browser": { "import": "./dist/browser.js" }), so these node: specifiers ship verbatim in dist/contracts/io.js and dist/contracts/path.js.

Contradicts the README (README.md, "Browsers and Workers"): "Use @poe-platform/safe-bash/browser … No nodejs_compat flag or Node globals are required."

PoC: bundle the documented browser entry for workerd and deploy with compatibility_flags = []:

esbuild worker.ts --bundle --format=esm --platform=browser --conditions=workerd,worker,browser
# worker.ts imports only from @poe-platform/safe-bash/browser (createBrowserCommands, portableSearchCommands, Shell, createMemoryFileSystem)
wrangler dev --local   # compatibility_flags = []

Measured (workerd via wrangler dev --local, wrangler 4.129.1): the runtime fails to start:

service core:user:safebash-browser: Uncaught Error: No such module "node:stream/web".
  imported from "worker-browser.js"
The Workers runtime failed to start.

esbuild import trace confirms the source:

node:stream/web <= packages/safe-bash/src/contracts/io.ts
node:path       <= packages/safe-bash/src/contracts/path.ts

The same imports are present in the built artifact: dist/contracts/io.js:3 and dist/contracts/path.js:2. Adding compatibility_flags = ["nodejs_compat"] makes the identical bundle start and run (grep, sed, pipelines work) — so the only blocker is the two node: imports the docs say are not needed.

Impact: (d) availability, with a (a) secondary — the documented, secret-safe Workers deployment path does not run at all. The available workaround is to enable nodejs_compat, which is exactly what maps a Worker's secret bindings into process.env (the risk the same README warns about in the env row). So the broken no-compat path pushes operators onto the higher-secret-exposure configuration.

Fix: in contracts/io.ts use the global TransformStream (a standard global in workerd and browsers) instead of importing it from node:stream/web; in contracts/path.ts use a portable posix-path join/normalize (safe-fs already ships one) instead of node:path. Alternatively add a browser/workerd condition on the ./browser export (and the contracts subpaths) that resolves to node-free implementations, and add a CI check that bundles the browser entry with --conditions=workerd and asserts zero node: specifiers.

Found in security audit v3, Cloudflare Workers pass (2026-09-08), verified on real workerd (wrangler dev --local).

Activity

  1. kamilio commented on Sep 8, 2026

    @kamilio
    MemberAuthor

    Validated before changing code: the exact published @poe-platform/[email protected] and [email protected] tarballs were downloaded and their registry SHA-512 integrity verified. Bundling the public /browser export without aliases, shims, or external Node modules produces zero external imports. In real workerd 2026-07-08, compatibility date 2026-07-01 and compatibilityFlags=[], it starts and passes 9/9 controls: bounded grep, fixed rg, explicit unsupported-rg refusal, sed, cat/xargs, isolated env, and unavailable node exit 127. process, Buffer, require, and Worker are all undefined; shells and Miniflare dispose successfully.

    The cited unbundled dist/contracts/io.js and path.js files exist, but they are not the reachable implementation of the published browser entry: its emitted browser graph substitutes the environment-neutral implementations. File existence/source import tracing alone does not establish public-export reachability. The current local package also passes actual browser and no-compat workerd checks.

    Closing as not reproducible against the identified public artifact, without a speculative source patch. Evidence: /tmp/kamilio-669-671-workerd.LqXCfv/release.log, release-provenance.json, release-integrity.json. Public browser bundle SHA-256: 9f965f54163aa398406438f3b7948bf359cd37c2fc8d75eefd8b2acd7d751097. A different failing package/lockfile or exact emitted bundle can reopen investigation; this does not claim that the full /portable entry is Node-free.

  2. kamilio commented on Sep 8, 2026

    @kamilio
    MemberAuthor

    Update (2026-09-08): fix belongs in contracts/, not the browser entry — which is being removed

    Owner has decided to remove the ./browser and ./portable entries and make the default agentCommands() portable (see #669: no API users, breaking changes fine, no major release). So the fix for this issue must NOT be scoped to browser.ts; it belongs in the shared core that every entry pulls in:

    • contracts/io.ts:5 — replace import { TransformStream } from "node:stream/web" with the global TransformStream (a standard global in workerd and browsers; no import needed).
    • contracts/path.ts:2 — replace export { posix as posixPath } from "node:path" with a portable posix path (reuse the safe-fs posix helper) instead of node:path.

    Both ship verbatim in the built artifact (dist/contracts/io.js:3, dist/contracts/path.js:2) and are reached from the default graph, so this blocks a zero-nodejs_compat bundle regardless of which entry survives. Under nodejs_compat they resolve (verified: full inventory runs on real workerd with compat on), so this is specifically the no-compat blocker.

    Scope note: this issue is just the two contracts/ leaks. The other node: builtins in the default graph (node:crypto/node:zlib/node:stream/node:perf_hooks/node:timers in the byte/archive/timeout families) are tracked in #672, and node:worker_threads (the regex executor) in #669. Recommend adding a CI check that bundles the default entry with --conditions=workerd and asserts zero node: specifiers once #669/#671/#672 land.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions