feat: add outbound proxy support to @arcjet/transport and @arcjet/guard

[davidmytton]

Adds outbound proxy support to @arcjet/transport and @arcjet/guard. The standard proxy environment variables (HTTP_PROXY and HTTPS_PROXY, respecting NO_PROXY) are auto-detected so requests to the Arcjet API can be routed through a proxy such as Squid.

How proxying works per runtime

Each runtime uses its own built-in proxy support:

• Node.js — routes through the proxy over HTTP/1.1 using the Node.js HTTP agent's built-in proxy support, otherwise connects directly over HTTP/2.
• Bun and Deno — the runtime's native fetch performs the proxying. On @arcjet/guard, Bun resolves to the HTTP/2 transport, but its Node HTTP agent ignores the proxy option, so it falls back to the fetch transport when a proxy is detected (verified on Bun 1.3.14).
• Edge runtimes (edge-light, workerd) — don't support outbound proxy environment variables, so no proxy is used.

Notes

• The NO_PROXY parsing is intentionally duplicated between the two packages (@arcjet/guard keeps an edge-safe, dependency-free copy). The shared logic is kept logically identical and annotated with a "keep in sync" comment in both files.
• The agent's built-in proxy support requires Node.js >=22.21.0 <23 || >=24.5.0, so the engines fields and @types/node are bumped accordingly.
• Startup line is logged at info level. In @arcjet/transport (via @arcjet/logger, default level warn) it requires ARCJET_LOG_LEVEL=info to be visible; in @arcjet/guard (via console.info) it always shows.

Closes #6082

[arcjet-review]

Arcjet Review — 🔴 High Risk

Decision: Reviewers Assigned

Rationale: This PR changes the core outbound transport behavior for both @arcjet/transport and @arcjet/guard, adds proxy environment-variable detection, changes supported Node.js engine ranges, adds runtime entry points, and introduces new package dependencies. The implementation includes good test coverage for many NO_PROXY and HTTP proxy cases and avoids logging proxy credentials, but proxy auto-detection is security-sensitive and there is a potential HTTP_PROXY/httpoxy-style risk that should be reviewed by humans. No specific escalation reviewers are configured, so the decision is Reviewers Assigned.

Summary of Changes

Adds outbound proxy support using HTTP_PROXY/HTTPS_PROXY with NO_PROXY handling across Node.js, Bun, Deno, and guard transports; adds proxy detection utilities and tests; adds a Deno transport entry point; updates docs, Node engine requirements, type configuration, and transport dependencies.

Escalation Triggers

• Dependency Changes: package.json files were changed: @arcjet/transport adds @arcjet/env and @arcjet/logger dependencies and tightens Node engine support; @arcjet/guard updates @types/node and engine constraints.

Security Flags

• [MEDIUM] Proxy environment handling (transport/detect-proxy.ts:116): Uppercase HTTP_PROXY is honored by default for HTTP base URLs. In CGI-like or legacy server environments, inbound Proxy headers can be translated into HTTP_PROXY, allowing attacker-controlled outbound proxying unless an httpoxy mitigation is applied, such as ignoring uppercase HTTP_PROXY when REQUEST_METHOD is present.

Review Focus Areas

• Should uppercase HTTP_PROXY be ignored when REQUEST_METHOD is present, or should the package explicitly document that CGI-style environments are unsupported?
  This is the standard mitigation for the httpoxy class of vulnerabilities when libraries automatically honor HTTP_PROXY.
• If an httpoxy mitigation is added to @arcjet/transport, can the duplicated proxy-resolution logic in @arcjet/guard be updated in lockstep?
  The PR intentionally duplicates proxy logic, so security fixes must remain synchronized between packages.
• Please verify Deno users can call createTransport() without --allow-env, or handle permission errors when reading process.env.
  The Deno entry point calls detectProxy by default, and environment access in Deno can be permission-gated; this could turn proxy auto-detection into a runtime failure for otherwise valid clients.
• Can CI or tests exercise actual HTTPS-over-proxy behavior, not just construction of an HTTPS proxy transport?
  The HTTP proxy integration test validates HTTP/1.1 proxying, but HTTPS proxying depends on Node Agent CONNECT behavior and is the likely production path for the Arcjet API.
• Is dropping Node >=20 and Node 23 support acceptable for this package version, and is this covered in release notes as a breaking runtime-support change?
  The package previously advertised node >=20 and now requires >=22.21.0 <23 || >=24.5.0, which can break existing consumers even when they do not use proxy support.
• Please confirm the new @arcjet/env and @arcjet/logger dependencies are reflected in the lockfile/workspace metadata and have compatible licenses and acceptable transitive dependency impact.
  New runtime dependencies affect supply-chain risk and install reproducibility.

Notes

The diff appears to exceed the 1000-line automated-review threshold, so human review is recommended even aside from the security-sensitive proxy behavior. No hardcoded secrets were identified, and the proxy URL is deliberately not logged.

Path filtering: 2 files excluded by ignore paths. 20 of 22 files included in review.

_{Review: 7d63a58a | Model: openai/gpt-5.5 | Powered by Arcjet Review}

[arcjet-review]

Arcjet Review — 🔴 High Risk

Decision: Reviewers Assigned

Rationale: This PR changes core outbound transport behavior for @arcjet/transport and @arcjet/guard, adds proxy auto-detection across runtimes, changes Node.js engine requirements broadly across packages, adds runtime entry points, and modifies CI coverage. The previously raised httpoxy concern appears addressed by ignoring uppercase HTTP_PROXY when REQUEST_METHOD is present, and the previous Deno permission concern appears addressed by catching environment-read failures and adding tests. No hardcoded secrets were identified, and proxy URLs/credentials are deliberately not logged. However, proxy routing is security-sensitive and the PR also triggers CI/CD and dependency-change escalation paths, so human review is required. No specific escalation reviewers are configured.

Summary of Changes

Adds outbound proxy support using HTTP_PROXY/HTTPS_PROXY/NO_PROXY for @arcjet/transport and @arcjet/guard, with Node using HTTP/1.1 agent proxying when needed and Bun/Deno relying on native fetch proxy support. Also adds Deno exports/runtime tests, expands proxy test coverage, updates README documentation, modifies CI matrices, and raises Node engine requirements across the workspace.

Escalation Triggers

• CI/CD Pipeline: Changes GitHub Actions workflows to use Node 22, remove Node 20 from the test matrix, and add Bun/Deno runtime proxy test jobs.
• Dependency Changes: Many package.json files change engine requirements; @arcjet/transport adds internal workspace dependencies on @arcjet/env and @arcjet/logger and adds new runtime exports/scripts.

Review Focus Areas

• Confirm the httpoxy mitigation intentionally ignores only uppercase HTTP_PROXY for HTTP targets when REQUEST_METHOD is present, and that this behavior matches the duplicated guard implementation.
  Proxy environment handling can affect outbound request routing; the previous security finding is addressed here but should be verified by a human because this is a trust-boundary-sensitive path.
• Verify the Node.js built-in Agent proxyEnv behavior works as expected on the declared supported engine ranges, including HTTPS CONNECT behavior and the HTTP/2-to-HTTP/1.1 fallback when a proxy is detected.
  The transport protocol changes under proxy configuration, and incorrect runtime assumptions could silently bypass proxies or break production connectivity.
• Check that the Bun/Deno runtime detection and fallback to createFetchTransport cannot double-log, bypass NO_PROXY expectations, or choose the wrong transport under conditional exports.
  @arcjet/guard has duplicated proxy detection and different runtime entry behavior, so drift or runtime-condition mistakes could create inconsistent behavior between packages.
• Verify the lockfile is updated consistently for package.json dependency/engine changes, or confirm no lockfile changes are required for these workspace-only dependencies.
  npm ci can fail or install a different graph if package.json and the lockfile are out of sync.
• Confirm public docs/release notes clearly call out the breaking Node.js support change from Node 20 to Node 22+ and the narrower proxy-supported ranges for @arcjet/transport and @arcjet/guard.
  This PR changes runtime support across many packages; users need clear migration guidance before release.

Notes

The diff appears to exceed the 1000-line automated-review threshold, so this is potentially too large for reliable automated review. Previous review concerns about uppercase HTTP_PROXY/httpoxy and Deno environment permission failures appear to have been addressed in the current diff.

Path filtering: 2 files excluded by ignore paths. 58 of 60 files included in review.

_{Review: 20395000 | Model: openai/gpt-5.5 | Powered by Arcjet Review}

[arcjet-rei]

I did a couple passes at a review with Claude, and then added a bunch of tests to ensure that we had end-to-end coverage for all of Node, Bun, and Deno. As such, I don't think it makes sense for me to approve this, so I'm passing the buck to @qw-in for final signoff. The diff is bulky, but most of the line count is tests, so all we really need is for Quinn to scan through the tests and verify that the tests do what they say they do.

One important note: to keep support simple, and because it's time, one of the commits I added to this PR is removal of support for the now EOL Node 20. @arcjet/transport has more specific requirements for which versions of Node 22 it requires due to its proxy support, but anybody tracking LTS should be fine. The commit message should trigger this getting flagged by release-please in any case, but we should be clear about the new Node version requirements in the release notes for the SDK.

The bot should not be setting "changes requested" when all it's doing is escalating to human reviewers (without any providing any actionable feedback).

[qw-in]

I pulled the node update out into #6090 as there are a few other items I was aware of that could be tweaked. If that looks good I can rebase this on top later.

In the meantime I'll run through this diff

[arcjet-rei]

@qw-in this has now been rebased and had its version of the Node 20 drop dropped.

[qw-in]

Thanks @arcjet-rei! Still going through right now

[qw-in]

I think my main concern with this approach is we are being automagic ✨. I'd prefer to make this an explicitly configurable option. Partially thats how I prefer to design apis but I also worry about breaking existing customers who may have HTTP_PROXY environment variables.

The current approach also doesn't (to my eye) allow opting arcjet out of the environment's proxy config without manually updating the environment variables.

So, Id propose we put it on the SDK initialization:

// requests
const aj = arcjet({
  // Place in transport to differentiate from "proxy"
  // top level configuration object
  transport: {
    // ...
    proxy: /* ... */
  }
  // ...
});

// guard
const arcjet = launchArcjet({
  transport: {
    // ...
    proxy: /* ... */
  }
});

This has the side benefit of giving us somewhere to explain the http proxy in tsdoc.

Note

We will want to be careful not to confuse users with "proxy" as we already have a a few difference references to "proxy"

My other concern is right now configuring a proxy will degrade the underlying connection from http2 to http1.1 which (to my understanding) has real latency implications. I think we should model the configuration to make this clear. Maybe something like this? (Just spitballing)

type ArcjetTransportConfiguration =
  | {
      protocol: "http2";
      /** Not supported over HTTP/2 — see {@link …} */
      proxy?: never;
    }
  | {
      protocol: "http1.1";
      proxy?: HttpProxyConfig;
    };

---

We can still have automatic proxy support but I'd suggest making it opt-in:

// requests

import { arcjet } from "@arcjet/node";
// export on the base package or could be transport directly
// unrelated conversation but I'd like us to move to this
// pattern instead of multiple packages one day
import { transportFromEnvironment } from "arcjet/transport"

const aj = arcjet({
  transport: transportFromEnvironment(),
  // or maybe 
  transport: {
    protocol: "http1.1",
    proxy: proxyFromEnvironment(process.env),
  }
});

// guards

import { arcjet } from "@arcjet/guard";
import { transportFromEnvironment } from "@arcjet/guard/transport"

const arcjet = launchArcjet({
  transport: transportFromEnvironment(),
});

I think this means we can scope down where we are touching the environment variables (which lots of bundlers/runtimes seem to trip over in my experience)

[arcjet-rei]

I think my main concern with this approach is we are being automagic ✨. I'd prefer to make this an explicitly configurable option. Partially thats how I prefer to design apis but I also worry about breaking existing customers who may have HTTP_PROXY environment variables.

The current approach also doesn't (to my eye) allow opting arcjet out of the environment's proxy config without manually updating the environment variables.

The reason I didn't raise an eyebrow at the transparent / environment variable approach to proxying is that that's basically the way I've always done it, all the way back to Perl's CGI.pm thousands of years ago. It's a very common approach in pretty much every ecosystem except Node, which chooses to be more explicit about it (FWIW, we built transparent / automatic proxy support into node-newrelic because that was the convention we followed at the time).

But I think Node as a whole sides with your philosophy. I'm fine with making this explicit and opt-in, or at least making this a judgment call for @davidmytton. Removing the environment variable code would certainly simplify the PR.

My other concern is right now configuring a proxy will degrade the underlying connection from http2 to http1.1 which (to my understanding) has real latency implications. I think we should model the configuration to make this clear. Maybe something like this? (Just spitballing)

We don't necessarily have to pay that tax for Node (the story is muddier for Bun and Deno) -- because Squid doesn't mess with the traffic, if we do an HTTP/2 CONNECT, that should work. There are some nuances (if the underlying socket isn't created correctly by the HTTP/2 client and/or Squid, there's packet overhead on sequential requests over the HTTP/2 socket that amounts to a ~40ms/req tax. We should make HTTP2 configurable, use sensible defaults to avoid incurring the Nagle tax unnecessarily, and make sure that we have clear documentation about how egress proxying will need to be configured to keep request overhead low. I'll add a commit with HTTP/2 support for Node.

I've gone ahead and added a commit to the PR that adds HTTP/2 support for Node proxying.

Both Bun and Deno treat HTTP/2 via their fetch implementations as either immature or experimental, and the Bun implementation has at least one significant outstanding bug. Deno and Bun users are outta luck for now, unless they want to use a sidecar for egress that transparently proxies Arcjet-bound traffic instead of configuring proxy support in-app (which is probably what most Fargate or EKS / GKE users are doing without even knowing it).

[davidmytton]

It's standard to use HTTP_PROXY, HTTPS_PROXY, and NO_PROXY vars and Node supports this as documented with node:http and node:https (v22.21.0 or v24.5.0+) methods as well as fetch() (v22.21.0 or v24.0.0+). We should follow the same approach.

[qw-in]

Sounds good - let's ship it!