@badgateway/oauth2-client

@badgateway/oauth2-client is a fully-featured OAuth2 client for TypeScript, built for both Node.js and browser environments. At roughly 5KB gzipped with zero dependencies, it relies entirely on modern built-in APIs like fetch() and Web Crypto rather than pulling in a large dependency tree.

It supports the authorization_code grant with optional PKCE, password and client_credentials grants, OAuth2 server metadata discovery (RFC 8414), token introspection (RFC 7662), token revocation (RFC 7009), and resource indicators (RFC 8707). A built-in fetch() wrapper automatically attaches and refreshes bearer tokens for authenticated API calls.

What You Get

• authorization_code grant flow with optional PKCE support for public clients
• password and client_credentials grant flows for machine-to-machine and legacy use cases
• A fetch() wrapper that automatically attaches and refreshes Bearer tokens
• OAuth2 server metadata discovery per RFC 8414, reducing manual endpoint configuration
• Token introspection (RFC 7662) and token revocation (RFC 7009) support
• Resource Indicators (RFC 8707) and multiple response type encoding support

Common Use Cases

• Implementing browser-based authorization_code plus PKCE login flows in single-page apps
• Building Node.js backend services that authenticate against an OAuth2 server via client_credentials
• Adding automatic Bearer token attachment and refresh to API calls without hand-rolled interceptor logic
• Integrating with any spec-compliant OAuth2 server using discovery instead of hardcoding endpoint URLs

Under The Hood

Architecture: The library is organized around a small set of focused modules under src/ - client.ts and the client/ directory implement the OAuth2Client class and its grant-specific methods, token.ts models the OAuth2Token shape and refresh logic, fetch-wrapper.ts implements the auto-refreshing fetch() wrapper, messages.ts builds and parses the OAuth2 wire-protocol requests/responses, and error.ts centralizes typed error handling, a compact roughly 1300-line codebase reflecting its stated goal of a minimal footprint. Tech Stack: Written entirely in TypeScript, published as an ESM package (type module) targeting Node.js 18+, with zero runtime dependencies - it relies solely on platform-native fetch() and Web Crypto APIs to avoid the dependency bloat common in OAuth2 libraries, using a Makefile-driven build/test/lint pipeline. Code Quality: A dedicated test/ directory (9 files) covers the grant flows and token wrapper behavior; the changelog and issue tracker show active maintenance discipline, and the codebase’s small size makes it easy to audit end-to-end, a meaningful property for a security-sensitive library. API Design: The single OAuth2Client constructor accepts server, clientId, clientSecret plus optional endpoint overrides that fall back to RFC 8414 discovery, minimizing required configuration; the README documents every option inline with runnable TypeScript examples, and the automatic-refresh fetch() wrapper removes the most common source of OAuth2 integration bugs, namely manually re-attaching refreshed tokens.