first commit

2026-05-29 08:20:56 +01:00
commit 949299f58d
6368 changed files with 527176 additions and 0 deletions
--- a/docs/identity/auth/oauth-client/README.md
+++ b/docs/identity/auth/oauth-client/README.md
@@ -0,0 +1,119 @@
+# @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