suaveplan/openspec/archive/2026-04-19-enterprise-oauth-client/proposal.md

OpenSpec Change: enterprise-oauth-client

• Change ID: enterprise-oauth-client
• Package: @suaveplan/oauth-client
• Category: universal
• Target path: universal/auth/oauth-client
• Status: PROPOSED
• Date: 2026-04-19
• Reference spec: /mnt/s/web/suaveplan/enterprise/oauth-client.md

Summary

OAuth 2.0 + OIDC client with PKCE support, built-in provider presets (Google, Microsoft, GitHub, Apple, Discord, Spotify, Slack, Auth0, Okta, Cognito), JWT decoding, OIDC discovery, token exchange/refresh/revocation, and ID-token claim validation. Runtime-agnostic — no Node or browser assumptions.

Current-state audit (genesis)

Package does not exist yet — fresh build.

Dependencies

• Workspace: @suaveplan/error, @suaveplan/types
• External (via catalog): zod, tslib, @opentelemetry/api
• Dev (via catalog): vitest, @vitest/coverage-istanbul, fast-check, mitata

Preserved public surface

Client

• OAuthClient, OAuthClientOptions
• oauthConfigMissing (error helper)

Discovery

• buildDiscoveryUrl, configFromDiscovery, fetchDiscoveryDocument, OIDCDiscoveryError, validateDiscoveryDocument

PKCE

• base64UrlDecode, base64UrlEncode, createCodeChallenge, generateCodeVerifier, generateNonce, generatePkcePair, generateState, verifyCodeChallenge

Provider

• createCustomProviderConfig, createProviderConfig, getAvailableProviders, getProviderPreset, isWellKnownProvider

Token

• decodeJwt, exchangeCode, isTokenExpired, normalizeTokenResponse, OAuthTokenError, refreshAccessToken, revokeToken, validateIdTokenClaims

Types / codes

AuthorizationParams, AuthorizationUrlResult, CodeChallengeMethod, FetchFunction, IdTokenClaims, IdTokenValidationOptions, JwtHeader, OAuthGrantType, OAuthProviderConfig, OIDCDiscoveryDocument, PkcePair, ProviderPreset, TokenExchangeParams, TokenRefreshParams, TokenResponse, TokenSet, WellKnownProvider, OAuthClientErrorCode, registerOAuthClientErrorCodes, OAUTH_CLIENT_ERROR_METADATA.

New genesis additions

• Codes via defineCodes: OAUTH_CLIENT.DISCOVERY_FAILED, OAUTH_CLIENT.TOKEN_EXCHANGE_FAILED, OAUTH_CLIENT.REFRESH_FAILED, OAUTH_CLIENT.REVOKE_FAILED, OAUTH_CLIENT.INVALID_ID_TOKEN, OAUTH_CLIENT.INVALID_STATE, OAUTH_CLIENT.PKCE_MISMATCH, OAUTH_CLIENT.UNKNOWN_PROVIDER.
• Zod schemas for every type.
• OTel counters per outcome; histogram oauth_client.token_exchange.duration_ms.
• Property tests: PKCE verify round-trip (verifyCodeChallenge(verifier, createCodeChallenge(verifier)) always true).

Impact

• Adds one new package: universal/auth/oauth-client
• Adds one new spec capability: oauth-client