Digest Fetch

3.1.1 · active · verified Wed Apr 22

digest-fetch is a JavaScript/TypeScript library that provides digest and basic HTTP authentication capabilities for both the standard `fetch` API and `node-fetch` in Node.js environments. The current stable version is 3.1.1. This library distinguishes itself by strictly adhering to RFC2069, RFC2617, and RFC7616 for digest access authentication, supporting various algorithms like MD5, SHA-256, and SHA-512-256, including their session variants. It primarily acts as a plugin, wrapping the `fetch` function to handle the authentication challenge-response cycle seamlessly. Major version 3.x transitioned the package to an ES module, requiring changes in project configuration for both JavaScript and TypeScript users. It allows for customizable options such as algorithm, status codes for failure, and cnonce size, and can also be configured to perform basic HTTP authentication.

Common errors

```
ReferenceError: require is not defined
```
cause Attempting to use CommonJS `require()` in an ES Module (ESM) context for `digest-fetch` v3+.

fix Ensure your project is configured as an ES module by adding `"type": "module"` to your `package.json`, and use `import DigestClient from 'digest-fetch';`. Alternatively, downgrade `digest-fetch` to a v2.x version if your project must remain CommonJS.
```
SyntaxError: Cannot use import statement outside a module
```
cause Attempting to use ES Module `import` syntax in a CommonJS context without proper configuration for `digest-fetch` v3+.

fix Ensure your project's `package.json` has `"type": "module"`. If you intend to use CommonJS, you must downgrade `digest-fetch` to v2.x.
```
TypeError: fetch is not a function
```
cause In Node.js environments, `digest-fetch` relies on a global `fetch` implementation, typically provided by `node-fetch`, which has not been correctly imported or polyfilled.

fix Install `node-fetch` (`npm install node-fetch`) and ensure it's made available globally, for instance, by adding `globalThis.fetch = fetch;` after importing `node-fetch` in your entry file.

Warnings

breaking Version 3.0.0 and above of `digest-fetch` are ES Module (ESM) only. This requires projects to be configured for ESM, including setting `"type": "module"` in `package.json` for Node.js projects.
Fix: For Node.js projects, add `"type": "module"` to your `package.json`. For TypeScript, ensure `tsconfig.json` includes `"module": "ESNext"` and `"moduleResolution": "node"`.
breaking When migrating to `digest-fetch` v3+, if you were previously using `node-fetch` v2, you will also need to upgrade `node-fetch` to v3+. `node-fetch` v3+ is also ESM-only, which aligns with `digest-fetch` v3+ but introduces its own breaking changes.
Fix: Update `node-fetch` to its latest version (`npm install node-fetch@latest`). Review `node-fetch` v3 upgrade guides for its specific breaking changes, such as the removal of the `timeout` option.
gotcha When using digest authentication in browsers, a 401 response might trigger a browser's native authentication prompt, which is often undesirable for programmatic use.
Fix: The library suggests using a custom alternate authentication failure code (`statusCode` option) to avoid the browser prompt. Alternatively, ensure the server returns a different status for initial challenges or handle the 401 in a way that doesn't trigger the browser UI.

Install

npm install digest-fetch npm
yarn add digest-fetch yarn
pnpm add digest-fetch pnpm

Imports

DigestClient
wrong:
```
const DigestClient = require('digest-fetch');
```
correct:
```
import DigestClient from 'digest-fetch';
```
Since v3.0.0, digest-fetch is an ES Module. Use `import` and ensure your project is configured for ESM ('type': 'module' in package.json).
DigestClient (CJS)
wrong:
```
import DigestClient from 'digest-fetch';
```
correct:
```
const DigestClient = require('digest-fetch');
```
For digest-fetch v2.0.3 or below, CommonJS `require` is the correct way. V3+ is ESM-only.
DigestClient (TypeScript)
wrong:
```
import type { DigestClient } from 'digest-fetch';
```
correct:
```
import DigestClient from 'digest-fetch';
```
DigestClient is a class, so it's imported as a value. Types are shipped with the package since v3, so no `@types/digest-fetch` is needed.

Quickstart

This quickstart demonstrates how to set up `digest-fetch` for digest authentication, create a `DigestClient`, and make an authenticated request in a TypeScript Node.js environment.

import DigestClient from 'digest-fetch';
import fetch from 'node-fetch'; // Required for Node.js environments

// Ensure node-fetch is globally available for DigestClient
// @ts-ignore - this is a common pattern for polyfilling fetch
globalThis.fetch = fetch;

async function authenticateAndFetch() {
  // Replace with actual credentials and URL
  const username = process.env.DIGEST_USER ?? 'testuser';
  const password = process.env.DIGEST_PASS ?? 'testpassword';
  const url = 'http://httpbin.org/digest-auth/auth/testuser/testpassword/MD5'; 

  // Create a DigestClient instance
  const client = new DigestClient(username, password, { algorithm: 'MD5' });

  try {
    // Make a request using the client's fetch method
    const response = await client.fetch(url, { method: 'GET' });

    if (!response.ok) {
      console.error(`HTTP error! status: ${response.status}`);
      const errorText = await response.text();
      console.error('Error details:', errorText);
      return;
    }

    const data = await response.json();
    console.log('Successfully authenticated and fetched data:');
    console.dir(data);
  } catch (error) {
    console.error('An error occurred:', error);
  }
}

authenticateAndFetch();

view raw JSON →