Registry / http-networking / xmlhttprequest-ssl

xmlhttprequest-ssl

JSON →
library4.0.0jsnpmunverified

This package provides a robust `XMLHttpRequest` implementation for Node.js environments, specifically designed to extend the original `node-XMLHttpRequest` with critical SSL/TLS configuration options. Currently at version 4.0.0, it addresses the need for finer-grained control over secure connections within a Node.js context, a feature often required by client-side libraries like `engine.io-client` when used on the server. The project acts as a maintained fork, incorporating changes that were not merged into its upstream predecessor. Its key differentiator is the direct exposure of Node.js `https` module options (such as `ca`, `cert`, `key`, `rejectUnauthorized`) via the `XMLHttpRequest` constructor, enabling developers to configure client-side certificates, custom CAs, and other security parameters. This allows for traditional AJAX-style request patterns in Node.js while adhering to specific network security requirements. The release cadence appears to be driven by feature needs and updates related to Node.js's network capabilities.

npm install xmlhttprequest-ssl
INSTALL
IMPORT
SIG · XMLHTTPREQUEST-SSL
X
xmlhttprequest-ssl
http-networkingjavascriptv4.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

XMLHttpRequest
const { XMLHttpRequest } = require('xmlhttprequest-ssl');
const XMLHttpRequest = require('xmlhttprequest-ssl').XMLHttpRequest;
The README example `var XMLHttpRequest = require("xmlhttprequest-ssl").XMLHttpRequest;` is correct but destructuring is often preferred for clarity and consistency with modern JS. Direct import of the named export `XMLHttpRequest` is recommended.
XMLHttpRequest
import { XMLHttpRequest } from 'xmlhttprequest-ssl';
While the README only shows CommonJS, modern Node.js environments (>=13.0.0 specified in engines) support ES Modules. This import style is compatible with ESM projects.
XMLHttpRequest (constructor options)
const xhr = new XMLHttpRequest({ rejectUnauthorized: false, maxRedirects: 10 });
Custom SSL/TLS and other non-standard options are passed directly to the XMLHttpRequest constructor as an object. This is a key feature of this fork compared to standard browser XHR.

Demonstrates how to perform a basic GET request and how to utilize the non-standard constructor options for SSL/TLS configuration (e.g., `rejectUnauthorized`) and redirect control, highlighting best practices for security.

const { XMLHttpRequest } = require('xmlhttprequest-ssl'); // Example 1: Basic GET request const xhrBasic = new XMLHttpRequest(); xhrBasic.open('GET', 'https://jsonplaceholder.typicode.com/posts/1', true); xhrBasic.onload = () => { if (xhrBasic.status >= 200 && xhrBasic.status < 300) { console.log('Basic request success:', xhrBasic.responseText.substring(0, 100) + '...'); } else { console.error('Basic request error:', xhrBasic.status, xhrBasic.statusText); } }; xhrBasic.onerror = (e) => console.error('Basic request network error:', e); xhrBasic.send(); // Example 2: Request with custom SSL/TLS and redirect options // NOTE: rejectUnauthorized: false is generally INSECURE and should only be used for testing against self-signed certs. // For production, use 'ca', 'cert', 'key', 'pfx' for proper certificate handling. const xhrSecure = new XMLHttpRequest({ rejectUnauthorized: process.env.NODE_ENV === 'production' ? true : false, // Control certificate validation maxRedirects: 5, // Allow up to 5 redirects agent: undefined, // Example of another option, undefined means default agent origin: 'http://example.com' // Set a base URL for relative paths }); xhrSecure.open('GET', 'https://self-signed.badssl.com/', true); xhrSecure.onload = () => { if (xhrSecure.status >= 200 && xhrSecure.status < 300) { console.log('Secure request success (potentially insecure):', xhrSecure.responseText.substring(0, 100) + '...'); } else { console.error('Secure request error:', xhrSecure.status, xhrSecure.statusText); } }; xhrSecure.onerror = (e) => console.error('Secure request network error:', e); xhrSecure.send();
Debug
Known issues
breakingThis package is a fork of `node-XMLHttpRequest`. While it aims for compatibility, users migrating from the original `driverdan/node-XMLHttpRequest` might encounter subtle behavior differences, especially related to SSL/TLS handling or `engine.io-client` integrations, which this fork specifically addresses.
fix
Thoroughly test existing code when migrating. Review the `xmlhttprequest-ssl` specific options if SSL/TLS issues arise.
affects: >=1.0.0
gotchaUsing `rejectUnauthorized: false` in production environments is highly insecure as it disables certificate validation, making your application vulnerable to Man-in-the-Middle (MITM) attacks. Only use this for development or against known self-signed certificates with full understanding of the risks.
fix
Always aim to use proper `ca`, `cert`, `key`, or `pfx` options to trust specific certificates or CAs. Ensure your Node.js environment has trusted root certificates correctly installed. Set `rejectUnauthorized: true` (default) in production.
affects: >=1.0.0
gotchaThe `syncPolicy` option controls synchronous `XMLHttpRequest` behavior. Setting it to `"disabled"` will cause an error when `send()` is called in synchronous mode. The default `"warn"` will log a warning, but synchronous XHR is generally discouraged in Node.js due to its blocking nature.
fix
Prefer asynchronous requests by setting the third parameter of `xhr.open()` to `true` (default). If synchronous behavior is strictly required, ensure `syncPolicy` is not `"disabled"` and be aware of the performance implications.
affects: >=1.0.0
gotchaThe `allowFileSystemResources: true` (default) option permits access to the local filesystem via the `file:` protocol. While useful for specific Node.js applications, it can pose a security risk if user-controlled URLs are used, potentially leading to local file disclosure.
fix
Set `allowFileSystemResources: false` if your application does not require `file:` protocol access or if you are handling untrusted URLs. Implement strict URL validation for all requests.
affects: >=1.0.0
gotchaThe `disableHeaderCheck: true` option disables checks against forbidden HTTP headers (e.g., `Host`, `User-Agent`). This can lead to non-standard HTTP requests and potentially allow for header injection if not carefully managed.
fix
Avoid `disableHeaderCheck: true` unless you have a specific, validated reason. Adhere to standard HTTP practices. If enabled, rigorously sanitize all user-provided header values.
affects: >=1.0.0
Errors
Common errors & fixes
Error: Cannot find module 'xmlhttprequest-ssl'
The package was not installed or there is a typo in the `require()` or `import` path.
fix
Run `npm install xmlhttprequest-ssl` to ensure the package is installed. Double-check the spelling of the module name in your `require()` or `import` statement.
Error: XMLHttpRequest is not a constructor
Attempting to use `require('xmlhttprequest-ssl')` directly as a constructor without accessing the `XMLHttpRequest` property.
fix
Correct the import statement to `const { XMLHttpRequest } = require('xmlhttprequest-ssl');` or `var XMLHttpRequest = require('xmlhttprequest-ssl').XMLHttpRequest;` for CommonJS, or `import { XMLHttpRequest } from 'xmlhttprequest-ssl';` for ES Modules.
ReferenceError: XMLHttpRequest is not defined
In ESM contexts, using `require()` is not allowed, or in CJS, the variable was not correctly assigned after `require()`.
fix
Ensure you are using the correct import syntax for your module type (CJS `require` or ESM `import`) and that the `XMLHttpRequest` symbol is properly destructured or assigned.
Error: unable to verify the first certificate
Node.js encountered a server certificate that it could not validate against its trusted root CAs. This often happens with self-signed certificates or custom enterprise CAs.
fix
If this is a known self-signed certificate for testing, pass `rejectUnauthorized: false` to the `XMLHttpRequest` constructor (with caution). For custom CAs, provide the CA certificate using the `ca` option: `new XMLHttpRequest({ ca: fs.readFileSync('path/to/custom-ca.pem') })`.
Path must be a string. Received type object
This error can occur if a path-related option (like `cert`, `key`, `ca`, `pfx`) is passed an incorrect type, such as an object, instead of a string or Buffer containing the certificate data.
fix
Ensure that `cert`, `key`, `ca`, and `pfx` options are provided as strings (paths to files) or Buffer objects containing the certificate/key data, as expected by Node.js's `https` module.
Upgrade
Version history
4.0.0latest on npm
Audit
Dependencies

No dependency data recorded yet.

Agent activity
36 hits · last 30 days
node
26
OpenAI (training)
1
Resources
xmlhttprequest-ssl — npm install xmlhttprequest-ssl · libregistry