63 lines
2.7 KiB
Markdown
63 lines
2.7 KiB
Markdown
# 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`
|