feat: add HTTP/2 multiplexing support for Node.js

[maxleonard]

Summary

Add HTTP/2 multiplexing support to the Node.js authentication package, enabling all requests to the same origin to share a single TCP connection. This significantly reduces latency for concurrent workloads common in Solid pod interactions (fetching resources, ACLs, containers, profiles, etc.).

Browsers already negotiate HTTP/2 transparently — this addresses the Node.js-only limitation where fetch defaults to HTTP/1.1 with ~6 concurrent TCP connections per origin.

Detailed Changes

New files

• packages/node/src/http2Fetch.ts — HTTP/2-aware fetch implementation with connection pooling

  • createHttp2Fetch() factory returns a fetch-compatible function with close() method
  • Connection pool: Map<origin, http2.ClientHttp2Session> with configurable idle timeout (default 30s)
  • Automatic error recovery: destroyed/closed sessions are removed and reconnected on next request
  • Full fetch API compatibility: RequestInfo | URL input, RequestInit options, Headers objects, request body streaming
  • Maps fetch API to HTTP/2 pseudo-headers (:method, :path) and streams
  • Exported Http2Fetch type with JSDoc and @since 2.6.0

• packages/node/src/http2Fetch.spec.ts — 11 tests against a real HTTP/2 server

  • Uses node:http2.createSecureServer with self-signed certificates
  • Covers: GET/POST, custom headers, request body, multiplexing verification, error handling, close(), URL objects, Headers objects, response URL property

Modified files — Session integration

• packages/node/src/Session.ts

  • Added http2?: boolean to ISessionOptions — creates HTTP/2 fetch when true
  • Unauthenticated requests route through http2Fetch
  • logout() calls http2Fetch.close() to release connections

• packages/node/src/index.ts — Added createHttp2Fetch and Http2Fetch exports

Modified files — Threading customFetch through the login flow

The buildAuthenticatedFetch function already accepts an options.fetch for the underlying transport. These changes thread the HTTP/2 fetch to that point:

• packages/core/src/Session.ts — Added customFetch?: typeof fetch to SessionConfig
• packages/core/src/login/ILoginOptions.ts — Added customFetch field
• packages/core/src/login/oidc/IOidcOptions.ts — Added customFetch field
• packages/node/src/ClientAuthentication.ts — Passes config.customFetch to login handler
• packages/node/src/login/oidc/OidcLoginHandler.ts — Copies customFetch into IOidcOptions
• packages/node/src/login/oidc/oidcHandlers/ClientCredentialsOidcHandler.ts — Passes to buildAuthenticatedFetch
• packages/node/src/login/oidc/oidcHandlers/RefreshTokenOidcHandler.ts — Passes through refreshAccess() to buildAuthenticatedFetch
• packages/node/src/login/oidc/incomingRedirectHandler/AuthCodeRedirectHandler.ts — Passes from SessionConfig to buildAuthenticatedFetch

Documentation

• packages/node/README.md — HTTP/2 Support section with Session usage, standalone usage, and DPoP/Bearer compatibility notes

Data flow

Session({ http2: true })
  → SessionConfig.customFetch = http2Fetch
    → ClientAuthentication.login() passes customFetch in ILoginOptions
      → OidcLoginHandler copies to IOidcOptions
        → OIDC handlers pass to buildAuthenticatedFetch(token, { fetch: customFetch })

DPoP compatibility

Works with both DPoP and Bearer authentication. DPoP proofs are generated per-request by buildAuthenticatedFetch; the HTTP/2 transport is transparent to the auth layer.

Usage

// With Session
const session = new Session({ http2: true });
await session.login({ ... });
const dataset = await getSolidDataset(url, { fetch: session.fetch });
await session.logout(); // Closes HTTP/2 connections

// Standalone
const h2fetch = createHttp2Fetch();
const dataset = await getSolidDataset(url, { fetch: h2fetch });
h2fetch.close();

Test plan

• 11 new HTTP/2 fetch tests pass
• 340 existing tests pass (37 suites)
• Manual integration test with a real Solid pod
• Verify DPoP authentication over HTTP/2

🤖 Generated with Claude Code

In general, the problem is that user-controlled resource is used as the URL argument to fetch with no constraints. To fix this without breaking existing semantics, we should validate and normalize the URL before passing it to fetch, and reject or constrain values that don’t meet safe criteria (e.g., enforce HTTPS and disallow internal IPs / localhost in the test server). Since the library Session.fetch is a general-purpose method, we keep it flexible, but we can add a minimal safeguard to ensure the unauthenticated, “raw” fetch path only accepts absolute URLs with allowed protocols. The core SSRF surface exposed over HTTP is the Express test app; there we can be stricter and apply explicit checks.

Concretely:

1. In e2e/node/server/express.ts:

   • In both /legacy/fetch and /tokens/fetch, after confirming resource is a string, parse it with new URL(resource) inside a try/catch.
   • Enforce that url.protocol is http: or https:.
   • Optionally (and safely) add a basic blocklist for obviously sensitive hosts (loopback / link-local / private networks). Since we must not assume extra infrastructure, we can at minimum prevent localhost and 127.0.0.0/8 and document that this is a safety check for the test server.
   • If the URL fails validation, respond with HTTP 400 and do not call fetch.
   • Use the parsed and validated url.toString() for the fetch call (or keep the original string once validated, but parsing already proves it is a valid URL).

2. In packages/node/src/Session.ts:

   • Add a shallow check in the unauthenticated branch of fetch: ensure url is either a URL object or a string that parses to a URL with http: or https: protocol. This is mostly defense-in-depth and satisfies CodeQL that we’re not blindly using attacker-controlled protocols; it should not affect normal usage where callers use standard URLs.
   • If the check fails, throw an error, as that’s better than making a dangerous request.

Implementation elements:

• Use the built-in URL class (global in Node 18+, or import { URL } from "url"; if needed – but Node’s global is likely already available; we can call new URL(...) directly).
• We do not add any third-party dependencies; native URL handling is sufficient.

The lines to change:

• e2e/node/server/express.ts:
  • Around lines 146–162 and 164–188 (within /legacy/fetch and /tokens/fetch), wrap resource in validation logic before fetch(resource).
• packages/node/src/Session.ts:
  • Around line 458–462, extend the unauthenticated branch to validate url before calling (this.http2Fetch ?? fetch)(url, init).

---