HTTP NTLM Authentication for Node.js

Common errors

• www-authenticate not found on response of second request

  cause During the NTLM handshake, the server must respond with a `WWW-Authenticate` header containing the Type 2 challenge message. This error indicates the server did not provide the expected challenge, likely due to an invalid initial Type 1 message or incorrect server configuration.
  fix Verify the URL, username, password, workstation, and domain are correct. Ensure the server endpoint is indeed NTLM-protected and configured correctly. Debug the initial Type 1 message sent to confirm it's well-formed.

• NTLM authentication failed: Invalid credentials

  cause This is a generic authentication failure, usually stemming from incorrect `username`, `password`, `workstation`, or `domain` parameters. It can also occur if the NTLM hashes generated are incorrect.
  fix Double-check all authentication parameters for typos or incorrect values. Ensure the user account has access to the resource. If pre-encrypting passwords, verify the `lm_password` and `nt_password` buffers are generated correctly from the plaintext password. Consider setting `domain` to an empty string if unsure.

• TypeError: require is not a function

  cause This error occurs when attempting to use `require()` syntax in an ECMAScript Module (ESM) context. The `httpntlm` library is designed for CommonJS.
  fix If your project is ESM, either switch to dynamic `await import('httpntlm')` (if supported and appropriate for your use case) or configure your build system to handle CommonJS modules. If possible, consider setting `"type": "commonjs"` in your `package.json` or changing file extensions to `.cjs` for files that use `require()`.

Warnings

• gotcha The library explicitly states that it assumes the server supports NTLMv2 and creates responses accordingly. If the server only supports NTLMv1 and does not negotiate NTLMv2 extended security, this assumption might lead to authentication failures or unexpected behavior.
  Fix: Ensure the target server supports NTLMv2. If NTLMv1 is strictly required, manual NTLM message handling via `httpntlm.ntlm` might be necessary, or consider alternative libraries that allow explicit NTLM version specification.
• deprecated The package's specified Node.js engine requirement is `>=10.4.0`, a very old version of Node.js. While the library might function on newer Node.js versions, official support and compatibility testing beyond Node.js 10 may be limited, potentially leading to unforeseen issues.
  Fix: Exercise caution when using in modern Node.js environments. Monitor for compatibility issues and consider alternative, actively maintained NTLM solutions if stability becomes a concern.
• breaking The package is primarily CommonJS (CJS). Attempting to `import` it directly in a pure ECMAScript Module (ESM) Node.js project (e.g., with `"type": "module"` in `package.json`) will result in a `TypeError: require is not a function` or similar module resolution errors.
  Fix: For ESM projects, use dynamic `await import('httpntlm')` or ensure your build process correctly transpiles or bundles CJS dependencies. Alternatively, switch your project to CommonJS if `httpntlm` is a critical dependency and ESM is not strictly required.
• gotcha The Snyk security scan badge in the README indicates 'Known Vulnerabilities'. While the Snyk Vulnerability Database currently shows no *direct* vulnerabilities for `httpntlm` itself, it's crucial to check its *dependencies* for vulnerabilities which may be indirectly introduced.
  Fix: Regularly scan your project's dependencies using tools like Snyk, npm audit, or yarn audit to identify and mitigate any transitive vulnerabilities introduced by `httpntlm` or its components. Update dependencies as recommended.

Install

• npm install httpntlm npm
• yarn add httpntlm yarn
• pnpm add httpntlm pnpm

Imports

• httpntlm
  wrong:

  import httpntlm from 'httpntlm';

  correct:

  const httpntlm = require('httpntlm');

  This package is primarily CommonJS. Direct `import` syntax will likely result in an error in pure ESM environments without specific Node.js configuration or bundler setup.
• httpntlm.get

  const httpntlm = require('httpntlm');
  httpntlm.get({ /* options */ }, callback);

  The primary method for performing NTLM-authenticated GET requests. Similar methods (post, put, del) are also available.
• httpntlm.ntlm
  wrong:

  import { ntlm } from 'httpntlm';

  correct:

  const { ntlm } = require('httpntlm');
  // or
  const ntlm = require('httpntlm').ntlm;

  Provides access to the raw NTLM message creation and parsing functions (e.g., `createType1Message`, `parseType2Message`, `create_LM_hashed_password`), intended for advanced scenarios where manual control over the NTLM handshake is required.

Quickstart

Demonstrates how to perform a basic NTLM-authenticated GET request using the library's high-level API, including error handling and using environment variables for sensitive credentials.

const httpntlm = require('httpntlm');

httpntlm.get({
  url: "https://someurl.com", // Replace with your NTLM-protected URL
  username: process.env.NTLM_USERNAME ?? '',
  password: process.env.NTLM_PASSWORD ?? '',
  workstation: process.env.NTLM_WORKSTATION ?? 'local_workstation',
  domain: process.env.NTLM_DOMAIN ?? ''
}, function (err, res){
  if(err) {
    console.error("NTLM GET request failed:", err.message); // Log the error message
    return;
  }

  console.log("Status Code:", res.statusCode);
  console.log("Response Headers:", res.headers);
  console.log("Response Body (truncated):");
  console.log(res.body ? res.body.substring(0, 500) + '...' : '[No Body]'); // Truncate body for readability
});