# @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](./src/core/authorization-code/authorization-code.md) — _(no submodules)_ - [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](./src/utils/pkce.md) — Implements RFC 7636 Proof Key for Code Exchange (PKCE) utilities for the OAuth 2.0 authorization code flow. PKCE preven… - [url-builder](./src/utils/url-builder.md) — 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](./src/utils/pkce.md) — Implements RFC 7636 Proof Key for Code Exchange (PKCE) utilities for the OAuth 2.0 authorization code flow. PKCE preven… - [url-builder](./src/utils/url-builder.md) — 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](./src/utils/pkce.md) — Implements RFC 7636 Proof Key for Code Exchange (PKCE) utilities for the OAuth 2.0 authorization code flow. PKCE preven… - [url-builder](./src/utils/url-builder.md) — 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](./src/utils/pkce.md) — Implements RFC 7636 Proof Key for Code Exchange (PKCE) utilities for the OAuth 2.0 authorization code flow. PKCE preven… - [url-builder](./src/utils/url-builder.md) — 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](./src/utils/pkce.md) — Implements RFC 7636 Proof Key for Code Exchange (PKCE) utilities for the OAuth 2.0 authorization code flow. PKCE preven… - [url-builder](./src/utils/url-builder.md) — 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 ```ts 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`](src/errors/oauth-client-error.md) | Error codes and `OAuthClientError` class | | [`src/utils/pkce`](src/utils/pkce.md) | RFC 7636 PKCE utilities | | [`src/utils/url-builder`](src/utils/url-builder.md) | URL-building and form-encoding helpers | | [`src/utils/jwt`](src/utils/jwt.md) | JWT decoding and ID-token claim validation | | [`src/core/authorization-code/authorization-code`](src/core/authorization-code/authorization-code.md) | Authorization Code + PKCE flow | | [`src/core/client-credentials/client-credentials`](src/core/client-credentials/client-credentials.md) | Client Credentials grant | | [`src/core/token-refresh/token-refresh`](src/core/token-refresh/token-refresh.md) | Token refresh, revocation, expiry check | | [`src/core/discovery/discovery`](src/core/discovery/discovery.md) | OIDC discovery document fetch and parse | | [`src/core/provider/provider`](src/core/provider/provider.md) | Built-in provider presets | | [`src/core/client/oauth-client`](src/core/client/oauth-client.md) | `OAuthClient` façade class | ## Client Credentials Example ```ts 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 ```ts // 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