@suaveplan/oauth-client - Universal OAuth 2.0 / OIDC client: Authorization Code + PKCE, Client Credentials, token refresh, OIDC discovery, JWT decoding, and provider presets

Summary

Universal OAuth 2.0 / OIDC client for Node.js, browsers, Bun, Deno, and edge runtimes.

Documentation tree

authorization-code — (no submodules)
- authorization-code — (no submodules)
client — (no submodules)
- oauth-client — (no submodules)
client-credentials — (no submodules)
- client-credentials — (no submodules)
discovery — (no submodules)
- discovery — (no submodules)
provider — (no submodules)
- provider — (no submodules)
token-refresh — (no submodules)
- token-refresh — (no submodules)
errors — (no submodules)
- oauth-client-error — (no submodules)
jwt — Provides minimal JWT decoding utilities for extracting and validating ID-token claims on the client side. Signature ver…
pkce — Implements RFC 7636 Proof Key for Code Exchange (PKCE) utilities for the OAuth 2.0 authorization code flow. PKCE preven…
url-builder — Provides pure URL-building and body-encoding utilities used internally by all OAuth 2.0 grant flows. Keeping these help…

- [authorization-code](./src/core/authorization-code/authorization-code.md) — _(no submodules)_- [client](./src/core/client/oauth-client.md) — _(no submodules)_- [oauth-client](./src/core/client/oauth-client.md) — _(no submodules)_- [client-credentials](./src/core/client-credentials/client-credentials.md) — _(no submodules)_- [client-credentials](./src/core/client-credentials/client-credentials.md) — _(no submodules)_- [discovery](./src/core/discovery/discovery.md) — _(no submodules)_- [discovery](./src/core/discovery/discovery.md) — _(no submodules)_- [provider](./src/core/provider/provider.md) — _(no submodules)_- [provider](./src/core/provider/provider.md) — _(no submodules)_- [token-refresh](./src/core/token-refresh/token-refresh.md) — _(no submodules)_- [token-refresh](./src/core/token-refresh/token-refresh.md) — _(no submodules)_- [errors](./src/errors/oauth-client-error.md) — _(no submodules)_- [oauth-client-error](./src/errors/oauth-client-error.md) — _(no submodules)_- [jwt](./src/utils/jwt.md) — Provides minimal JWT decoding utilities for extracting and validating ID-token claims on the client side. Signature ver…

pkce — Implements RFC 7636 Proof Key for Code Exchange (PKCE) utilities for the OAuth 2.0 authorization code flow. PKCE preven…
url-builder — Provides pure URL-building and body-encoding utilities used internally by all OAuth 2.0 grant flows. Keeping these help…
authorization-code — (no submodules)- client — (no submodules)- oauth-client — (no submodules)- client-credentials — (no submodules)- client-credentials — (no submodules)- discovery — (no submodules)- discovery — (no submodules)- provider — (no submodules)- provider — (no submodules)- token-refresh — (no submodules)- token-refresh — (no submodules)- errors — (no submodules)- oauth-client-error — (no submodules)- jwt — Provides minimal JWT decoding utilities for extracting and validating ID-token claims on the client side. Signature ver…
pkce — Implements RFC 7636 Proof Key for Code Exchange (PKCE) utilities for the OAuth 2.0 authorization code flow. PKCE preven…
url-builder — Provides pure URL-building and body-encoding utilities used internally by all OAuth 2.0 grant flows. Keeping these help…
authorization-code — (no submodules)- client — (no submodules)- oauth-client — (no submodules)- client-credentials — (no submodules)- client-credentials — (no submodules)- discovery — (no submodules)- discovery — (no submodules)- provider — (no submodules)- provider — (no submodules)- token-refresh — (no submodules)- token-refresh — (no submodules)- errors — (no submodules)- oauth-client-error — (no submodules)- jwt — Provides minimal JWT decoding utilities for extracting and validating ID-token claims on the client side. Signature ver…
pkce — Implements RFC 7636 Proof Key for Code Exchange (PKCE) utilities for the OAuth 2.0 authorization code flow. PKCE preven…
url-builder — Provides pure URL-building and body-encoding utilities used internally by all OAuth 2.0 grant flows. Keeping these help…
authorization-code — (no submodules)- client — (no submodules) - oauth-client — (no submodules)- client-credentials — (no submodules) - client-credentials — (no submodules)- discovery — (no submodules) - discovery — (no submodules)- provider — (no submodules) - provider — (no submodules)- token-refresh — (no submodules) - token-refresh — (no submodules)- errors — (no submodules) - oauth-client-error — (no submodules)- jwt — Provides minimal JWT decoding utilities for extracting and validating ID-token claims on the client side. Signature ver…
pkce — Implements RFC 7636 Proof Key for Code Exchange (PKCE) utilities for the OAuth 2.0 authorization code flow. PKCE preven…
url-builder — Provides pure URL-building and body-encoding utilities used internally by all OAuth 2.0 grant flows. Keeping these help…

Features

Authorization Code + PKCE flow (RFC 7636)
Client Credentials grant for M2M authentication
Token refresh (RFC 6749 §6) and revocation (RFC 7009)
OIDC discovery (RFC 8414)
JWT decoding and ID-token claim validation
Built-in provider presets: Google, Microsoft, GitHub, Apple, Discord, Spotify, Slack, Auth0, Okta, Amazon Cognito
Injectable fetch and generateRandom — fully runtime-agnostic
OTel metrics: oauth_client.token_request.total and oauth_client.token_request.duration_ms
Structured errors via @suaveplan/error with stable code registry

Quick Start

import { createOAuthClient } from "@suaveplan/oauth-client";
import { createProviderConfig } from "@suaveplan/oauth-client/core/provider/provider";

const client = createOAuthClient({
  config: createProviderConfig("google", {
    clientId: "your-client-id",
    redirectUri: "https://app.example.com/callback",
  }),
});

// Generate authorization URL
const { url, state, codeVerifier } = await client.createAuthorizationRequest();
// Redirect user to `url`; store state and codeVerifier in session.

// After redirect callback
const tokens = await client.handleCallback(code, callbackState, state, codeVerifier);

Modules

Module	Description
`src/errors/oauth-client-error`	Error codes and `OAuthClientError` class
`src/utils/pkce`	RFC 7636 PKCE utilities
`src/utils/url-builder`	URL-building and form-encoding helpers
`src/utils/jwt`	JWT decoding and ID-token claim validation
`src/core/authorization-code/authorization-code`	Authorization Code + PKCE flow
`src/core/client-credentials/client-credentials`	Client Credentials grant
`src/core/token-refresh/token-refresh`	Token refresh, revocation, expiry check
`src/core/discovery/discovery`	OIDC discovery document fetch and parse
`src/core/provider/provider`	Built-in provider presets
`src/core/client/oauth-client`	`OAuthClient` façade class

Client Credentials Example

import { createOAuthClient } from "@suaveplan/oauth-client";

const client = createOAuthClient({
  config: {
    clientId: "my-service",
    clientSecret: "my-secret",
    authorizationUrl: "",
    tokenUrl: "https://auth.example.com/token",
    scopes: ["api:read"],
  },
});

const tokens = await client.fetchClientCredentialsToken();

Auto-Refresh Example

// Get a valid token, refreshing automatically if expired
const freshTokens = await client.getValidToken(storedTokens);

Dependencies

@suaveplan/error — structured error types
@suaveplan/types — shared type definitions
@opentelemetry/api — OTel metrics
zod — schema validation
tslib — TypeScript runtime helpers

13 KiB Raw Blame History