Initial Commit

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

@@ -0,0 +1,62 @@
+# 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`