120 lines
13 KiB
Markdown
120 lines
13 KiB
Markdown
# @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.
|
|
|
|
<!-- begin:auto-docs -->
|
|
## Documentation tree
|
|
|
|
- [authorization-code](./src/core/authorization-code/authorization-code.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [authorization-code](./src/core/authorization-code/authorization-code.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [client](./src/core/client/oauth-client.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [oauth-client](./src/core/client/oauth-client.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [client-credentials](./src/core/client-credentials/client-credentials.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [client-credentials](./src/core/client-credentials/client-credentials.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [discovery](./src/core/discovery/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [discovery](./src/core/discovery/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [provider](./src/core/provider/provider.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [provider](./src/core/provider/provider.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [token-refresh](./src/core/token-refresh/token-refresh.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [token-refresh](./src/core/token-refresh/token-refresh.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [errors](./src/errors/oauth-client-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [oauth-client-error](./src/errors/oauth-client-error.md) — <!-- begin:auto-docs --> _(no submodules)_ <!-- end:auto-docs -->
|
|
- [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…
|
|
<!-- end:auto-docs --> - [authorization-code](./src/core/authorization-code/authorization-code.md) — <!-- begin:auto-docs --> _(no submodules)_- [client](./src/core/client/oauth-client.md) — <!-- begin:auto-docs --> _(no submodules)_- [oauth-client](./src/core/client/oauth-client.md) — <!-- begin:auto-docs --> _(no submodules)_- [client-credentials](./src/core/client-credentials/client-credentials.md) — <!-- begin:auto-docs --> _(no submodules)_- [client-credentials](./src/core/client-credentials/client-credentials.md) — <!-- begin:auto-docs --> _(no submodules)_- [discovery](./src/core/discovery/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [discovery](./src/core/discovery/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [provider](./src/core/provider/provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [provider](./src/core/provider/provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-refresh](./src/core/token-refresh/token-refresh.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-refresh](./src/core/token-refresh/token-refresh.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/oauth-client-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [oauth-client-error](./src/errors/oauth-client-error.md) — <!-- begin:auto-docs --> _(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) — <!-- begin:auto-docs --> _(no submodules)_- [client](./src/core/client/oauth-client.md) — <!-- begin:auto-docs --> _(no submodules)_- [oauth-client](./src/core/client/oauth-client.md) — <!-- begin:auto-docs --> _(no submodules)_- [client-credentials](./src/core/client-credentials/client-credentials.md) — <!-- begin:auto-docs --> _(no submodules)_- [client-credentials](./src/core/client-credentials/client-credentials.md) — <!-- begin:auto-docs --> _(no submodules)_- [discovery](./src/core/discovery/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [discovery](./src/core/discovery/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [provider](./src/core/provider/provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [provider](./src/core/provider/provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-refresh](./src/core/token-refresh/token-refresh.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-refresh](./src/core/token-refresh/token-refresh.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/oauth-client-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [oauth-client-error](./src/errors/oauth-client-error.md) — <!-- begin:auto-docs --> _(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) — <!-- begin:auto-docs --> _(no submodules)_- [client](./src/core/client/oauth-client.md) — <!-- begin:auto-docs --> _(no submodules)_- [oauth-client](./src/core/client/oauth-client.md) — <!-- begin:auto-docs --> _(no submodules)_- [client-credentials](./src/core/client-credentials/client-credentials.md) — <!-- begin:auto-docs --> _(no submodules)_- [client-credentials](./src/core/client-credentials/client-credentials.md) — <!-- begin:auto-docs --> _(no submodules)_- [discovery](./src/core/discovery/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [discovery](./src/core/discovery/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [provider](./src/core/provider/provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [provider](./src/core/provider/provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-refresh](./src/core/token-refresh/token-refresh.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-refresh](./src/core/token-refresh/token-refresh.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/oauth-client-error.md) — <!-- begin:auto-docs --> _(no submodules)_- [oauth-client-error](./src/errors/oauth-client-error.md) — <!-- begin:auto-docs --> _(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) — <!-- begin:auto-docs --> _(no submodules)_- [client](./src/core/client/oauth-client.md) — <!-- begin:auto-docs --> _(no submodules)_ - [oauth-client](./src/core/client/oauth-client.md) — <!-- begin:auto-docs --> _(no submodules)_- [client-credentials](./src/core/client-credentials/client-credentials.md) — <!-- begin:auto-docs --> _(no submodules)_ - [client-credentials](./src/core/client-credentials/client-credentials.md) — <!-- begin:auto-docs --> _(no submodules)_- [discovery](./src/core/discovery/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_ - [discovery](./src/core/discovery/discovery.md) — <!-- begin:auto-docs --> _(no submodules)_- [provider](./src/core/provider/provider.md) — <!-- begin:auto-docs --> _(no submodules)_ - [provider](./src/core/provider/provider.md) — <!-- begin:auto-docs --> _(no submodules)_- [token-refresh](./src/core/token-refresh/token-refresh.md) — <!-- begin:auto-docs --> _(no submodules)_ - [token-refresh](./src/core/token-refresh/token-refresh.md) — <!-- begin:auto-docs --> _(no submodules)_- [errors](./src/errors/oauth-client-error.md) — <!-- begin:auto-docs --> _(no submodules)_ - [oauth-client-error](./src/errors/oauth-client-error.md) — <!-- begin:auto-docs --> _(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
|