axios-ntlm

axios-ntlm is a lightweight Node.js helper that adds NTLM authentication support to the Axios HTTP client. Rather than requiring callers to hand-roll the NTLM handshake, it wraps a standard Axios instance with a response interceptor that automatically detects a 401 challenge carrying a WWW-Authenticate: NTLM header, negotiates the Type 1/Type 2/Type 3 message exchange, and retries the original request with the resulting Authorization header attached.

The library reimplements NTLMv1 and NTLMv2 message encoding directly (carried over from an older node-ntlm-client implementation) using a pure-JavaScript DES implementation for encryption and a small MD4 library for hashing, so it has no native binary dependencies. It’s commonly used to reach legacy Windows-authenticated services — internal SharePoint sites, IIS-hosted APIs, and other corporate intranet endpoints — from Node.js scripts and services that already use Axios.

What You Get

• A drop-in NtlmClient(credentials, axiosConfig) factory that returns a fully configured Axios instance
• Automatic 401 challenge detection and NTLM Type1/Type2/Type3 handshake negotiation via a response interceptor
• Built-in NTLMv1 and NTLMv2 response hashing (DES plus MD4/HMAC-MD5) with no native binary dependencies
• Automatic keep-alive HTTP/HTTPS agent configuration so the negotiated connection is reused for the retried request
• TypeScript type definitions for NtlmCredentials and re-exported Axios types (AxiosError, AxiosInstance, etc.)

Common Use Cases

• Calling an internal SharePoint or IIS-hosted API from a Node.js backend service
• Scripting data pulls from legacy Windows-authenticated intranet endpoints in CI/automation jobs
• Proxying requests from a modern Node.js app to a corporate service that only supports NTLM auth
• Migrating a Windows-integrated-auth client to Node.js without reimplementing the NTLM protocol

Under The Hood

Architecture The library is a thin, single-responsibility wrapper split across three files: a small TypeScript entry point exposing the public NtlmClient API, and two plain-JavaScript modules — one for message construction/parsing, and one for the underlying cryptographic hash primitives — carried over from an older NTLM helper project. NtlmClient wraps a real Axios instance with a single response interceptor: on a 401 response carrying an NTLM challenge header, the interceptor decides whether to send a fresh negotiation message or decode the server’s challenge based on header length, delegates the encoding work to the message module (which in turn defers to the hash module for the cryptographic primitives), and re-issues the original request with the computed Authorization header attached — reusing a shared keep-alive agent so the handshake completes over the same connection. Credentials are captured in a closure rather than passed explicitly through each call, so a single client instance is tied to one credential set for its lifetime. It’s a compact, understandable design without dependency injection or a layering scheme, but blending message-encoding and hashing responsibilities in the same module blurs separation of concerns somewhat.

Tech Stack The public entry point is TypeScript compiled via the standard TypeScript compiler, while the underlying NTLM message and hashing logic remains plain CommonJS JavaScript, carried over largely unmodified from an earlier project. The only runtime dependency beyond Axios itself is a pure-JavaScript DES implementation for legacy NTLMv1 hashing and a small MD4 hashing library for the NTLM hash step; Node’s built-in crypto module supplies HMAC-MD5 for NTLMv2. There’s no web framework, ORM, or database involved — this is a pure HTTP client extension. Build tooling is limited to the TypeScript compiler with Node type definitions; there’s no bundler. The checked-in docs folder is a static TypeDoc-generated site rather than a hosted documentation pipeline, and the only CI workflow publishes to npm on release — it doesn’t run tests or linting.

Code Quality There is no automated test suite — the package.json test script is an intentional failing stub, and no test files exist anywhere in the repository. The sole CI workflow only publishes to npm when a release is created; it does not run tests or linting as a gate. Error handling in the public client is minimal: it rethrows anything that isn’t a matching NTLM challenge, without validating malformed headers before attempting to parse them, and the underlying message/hash modules throw plain errors on protocol violations. Naming is clear and descriptive throughout, and the public-facing client module is fully typed with a well-defined credentials interface and passthrough Axios types, but the carried-over message and hashing modules remain untyped plain JavaScript with no inline documentation. No linter or formatter configuration is present in the repository.

API Design The public surface is deliberately minimal — a single client factory that accepts credentials and an optional Axios config and returns a genuine Axios instance, so callers keep using the Axios API they already know rather than learning new vocabulary. It automatically handles the parts developers would otherwise have to get right by hand — attaching keep-alive agents, retrying the request over the same connection, and choosing the correct handshake step based on the challenge received — so integrating NTLM authentication requires no protocol-level knowledge from the consumer. Documentation is thin: the README walks through a handful of copy-pasteable examples but doesn’t cover edge cases like streamed responses or workstation overrides in depth, and the generated API reference documents the shapes mechanically without much usage guidance.