Registry / auth-security / fetch-mw-oauth2

fetch-mw-oauth2

library1.0.2jsnpmunverified

fetch-mw-oauth2 is a JavaScript library designed to simplify OAuth2 integration with the standard `fetch` API, handling automatic token acquisition and refreshing. Currently at v3.3.1, it supports `authorization_code`, `password`, and `client_credentials` grant types, offers robust error handling, OpenID Connect `id_token` exposure, and includes support for token revocation (RFC 7009) and the `resource` parameter (RFC 8707). Since its v3.0.0 release, the library is ESM-only and has ceased support for Node.js 14 and 16. It primarily functions as a `fetch` wrapper or middleware. This package is in maintenance mode, as development has shifted to its successor, `@badgateway/oauth2-client`, which offers enhanced features and similar functionality.

auth-security http-networking

npm install fetch-mw-oauth2

github ↗package ↗

INSTALL

IMPORT

SIG · FETCH-MW-OAUTH2

fetch-mw-oauth2

auth-securityjavascriptv1.0.2

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

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 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

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

OAuth2

✓ import { OAuth2 } from 'fetch-mw-oauth2'

✗ const { OAuth2 } = require('fetch-mw-oauth2')

Since v3.0.0, this library is ESM-only. CommonJS `require()` is not supported.

OAuth2 types

✓ import type { OAuth2Options, OAuth2Token } from 'fetch-mw-oauth2'

TypeScript types are shipped with the package for improved development experience.

OAuth2 instance creation and usage

✓ import { OAuth2 } from 'fetch-mw-oauth2'; const oauth2 = new OAuth2({ clientId: 'your-client-id', clientSecret: process.env.OAUTH_CLIENT_SECRET ?? '', // Optional in some cases tokenEndpoint: 'https://auth.example.org/token', }, { accessToken: 'initial-access-token', refreshToken: 'initial-refresh-token', }); const response = await oauth2.fetch('https://api.example.org/data');

The primary interaction is creating an OAuth2 instance and then using its `fetch` method, which transparently handles token management.

This example demonstrates how to set up `fetch-mw-oauth2` using the client_credentials grant to automatically handle OAuth2 authentication and fetch a protected resource. It utilizes environment variables for sensitive data.

import { OAuth2 } from 'fetch-mw-oauth2'; async function authenticateAndFetch() { // Configure OAuth2 for the client_credentials grant type const oauth2 = new OAuth2({ grantType: 'client_credentials', clientId: 'your-client-id', clientSecret: process.env.OAUTH_CLIENT_SECRET ?? '', // Ensure this is loaded from environment variables tokenEndpoint: 'https://auth.example.com/token', scope: 'api:read api:write' }); try { // Use the wrapped fetch function which automatically handles Authorization headers and token refreshes const response = await oauth2.fetch('https://api.example.com/protected-resource', { method: 'GET', headers: { 'Accept': 'application/json' } }); if (!response.ok) { throw new Error(`HTTP error! status: ${response.status}`); } const data = await response.json(); console.log('Fetched data:', data); } catch (error) { console.error('Failed to fetch data with OAuth2:', error); } } authenticateAndFetch();

Debug

Known issues

breakingVersion 3.0.0 introduced a full conversion to ES Modules (ESM) and dropped support for Node.js versions 14 and 16. Projects using CommonJS `require()` syntax or older Node.js runtimes will break.

fix

Migrate your project to use ES Modules `import` syntax and ensure you are running Node.js 18 or newer. Update your `package.json` to include `"type": "module"`.

affects: >=3.0.0

breakingIn v3.0.0, `client_id` and `client_secret` were changed to be strictly percent-encoded as per RFC 6749. This was a breaking change if your server was not strictly compliant with the OAuth2 spec and used special characters in secrets.

fix

If experiencing issues, update to v3.1.0 or newer and consider setting `authorizationMethod` or switching to `client_secret_post` if your server has compatibility problems with strict Basic auth encoding.

affects: 3.0.0

gotchaVersion 3.1.0 reverted the strict percent-encoding for the `Authorization: Basic` header due to interoperability problems with many real-world OAuth2 servers. The library now defaults to less strict encoding. If strict encoding is required, you must explicitly opt-in using the `authorizationMethod` option.

fix

Review `README.md` for `authorizationMethod` options if your server requires strict Basic encoding. Otherwise, consider `client_secret_post` for better compatibility.

affects: >=3.1.0

deprecatedThis `fetch-mw-oauth2` package is in maintenance mode. The project has been renamed and superseded by `@badgateway/oauth2-client`, which offers a more full-featured and actively developed OAuth2 client. Users are strongly recommended to upgrade.

fix

Migrate your application to use `@badgateway/oauth2-client` for continued feature development and support.

affects: all

gotchaEarly v3 releases (v3.0.0, v3.1.0) had issues with browser builds, particularly for Vite and Next.js users, due to the ESM conversion. This was addressed in v3.2.0.

fix

Ensure you are using `fetch-mw-oauth2` v3.2.0 or newer for better browser compatibility with modern bundlers.

affects: 3.0.0 - 3.1.0

gotchaVersion 3.3.1 fixed a race condition when multiple function calls were attempting OAuth2 endpoint discovery simultaneously.

fix

Upgrade to v3.3.1 or newer to avoid potential issues with concurrent endpoint discovery requests.

affects: <3.3.1

Errors

Common errors & fixes

ReferenceError: require is not defined

Attempting to use CommonJS `require()` syntax with `fetch-mw-oauth2` v3.0.0 or later in an ES Modules environment.

fix

Change `const { OAuth2 } = require('fetch-mw-oauth2');` to `import { OAuth2 } from 'fetch-mw-oauth2';` and ensure your `package.json` specifies `"type": "module"` if running in Node.js.

HTTP 400 Bad Request - Client Authentication Failed

Interoperability issues with OAuth2 servers related to client_id/client_secret encoding in the `Authorization: Basic` header, particularly after the strict encoding change in v3.0.0 or the subsequent revert in v3.1.0.

fix

If on v3.0.0, your server might not handle strict encoding; upgrade to v3.1.0+. If on v3.1.0+, your server might require strict encoding; explicitly set the `authorizationMethod` option, or prefer the `client_secret_post` method if your server supports it.

Build error (e.g., 'window is not defined', module resolution) when using Vite/Next.js

Compatibility issues with browser bundling introduced during the ESM migration in `fetch-mw-oauth2` v3.x releases prior to v3.2.0.

fix

Update your `fetch-mw-oauth2` dependency to version 3.2.0 or newer to resolve browser build issues with modern bundlers.

Upgrade

Version history

1.0.2latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

32 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/badgateway/fetch-mw-oauth2 ↗

packagehttps://www.npmjs.com/package/fetch-mw-oauth2 ↗