node-oauth2-server

@node-oauth/oauth2-server is a complete OAuth 2.0 server implementation for Node.js, forked from the abandoned oauthjs/node-oauth2-server to keep the project actively maintained. It implements the authorization_code, client_credentials, refresh_token, and password grants (plus custom extension grants) fully compliant with RFC 6749 and the Bearer Token usage spec RFC 6750, and supports PKCE for public clients per OAuth 2.1 guidance.

The module is deliberately framework- and storage-agnostic: it defines a Model interface your application implements against whatever persistence layer you already use (PostgreSQL, MySQL, MongoDB, Redis, or anything else), and a Request/Response abstraction that decouples the library from any specific HTTP framework. Official wrapper packages (such as an Express adapter) exist for teams that want a drop-in middleware, while the core library stays usable standalone.

What You Get

• Full support for authorization_code, client_credentials, refresh_token, and password grants, plus a documented extension-grant mechanism for custom flows
• RFC 6749 and RFC 6750 compliance out of the box, including correct error codes and WWW-Authenticate header handling
• Built-in PKCE support (with an opt-in plain challenge method and an opt-in requirePKCE enforcement flag) for securing public clients
• A storage-agnostic Model interface so tokens, clients, and users can live in any database — Postgres, MySQL, MongoDB, Redis, or a custom store
• First-class async/await throughout, with no callback-based legacy API to work around
• TypeScript type definitions (index.d.ts) shipped in the package for editor autocomplete and compile-time checks

Common Use Cases

• Adding a self-hosted OAuth 2.0 authorization server to a Node.js API instead of depending on a third-party identity provider
• Issuing and validating bearer access tokens and refresh tokens for a first-party mobile or SPA client using the authorization_code grant with PKCE
• Securing service-to-service calls with the client_credentials grant
• Building a custom identity/auth layer on top of an existing user database via the Model interface, rather than migrating users to a hosted auth provider
• Implementing a custom extension grant type (e.g. a device-code or SAML-bearer flow) on top of the library’s AbstractGrantType base class

Under The Hood

Architecture The TokenHandler validates the incoming request, extracts client credentials via HTTP Basic auth or body parameters (with PKCE-aware fallbacks for public clients), and delegates to one of four grant-type classes (AuthorizationCodeGrantType, ClientCredentialsGrantType, PasswordGrantType, RefreshTokenGrantType), each extending a shared AbstractGrantType base that provides token generation, expiry calculation, and scope validation against the application’s Model. AuthorizeHandler and AuthenticateHandler follow the same layered shape for the authorization and resource-protection flows. Errors flow through a class hierarchy rooted in OAuthError, with each subclass mapping to a specific RFC error code, and non-OAuth errors are normalized to ServerError before reaching the client. The only integration points into an application are the Request/Response wrapper classes and the Model interface, so the core handlers and grant types never depend on a specific HTTP framework or storage engine.

Tech Stack Runtime dependencies are minimal: @node-oauth/formats for RFC ABNF format validation, basic-auth for HTTP Basic credential parsing, and type-is for content-type checks — no bundled web framework or ORM. Linting and formatting run through Biome rather than ESLint/Prettier, tests run on Mocha with Chai assertions and Sinon stubs, coverage is measured with nyc, and the documentation site is built with VitePress from JSDoc comments via a custom docs/build-api.js script. Type definitions in index.d.ts are hand-maintained rather than generated. The package targets Node >=16 and ships as plain CommonJS with no build step required by consumers.

Code Quality The test suite is organized into three tiers — test/unit, test/integration, and test/compliance — with the compliance tier specifically covering full RFC-conformance workflows (client authentication, PKCE, password grant, refresh-token grant). CI runs Biome lint/format checks, the full Mocha suite, and CodeQL semantic analysis on every push and pull request. Error handling is explicit and typed throughout: every failure raises a specific OAuthError subclass rather than a generic Error, and the library carefully distinguishes programmer/configuration errors (InvalidArgumentError) from protocol-level errors before they reach a client. File and class naming is consistently kebab-case and PascalCase respectively across lib/.

What Makes It Unique The library isn’t attempting novel protocol design — its value is being a faithful, actively maintained, framework-agnostic implementation of RFC 6749/6750/7636, continuing the project after the original oauthjs/node-oauth2-server was abandoned. Its distinguishing choices are practical rather than architectural: explicit requirePKCE/enablePlainPKCE toggles for OAuth 2.1-style enforcement, and a deliberate refusal to bundle a specific ORM or HTTP framework adapter, keeping the Model interface as the sole extension point for storage.