# 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`