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`

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

@@ -0,0 +1,41 @@
+# Capability Spec: oauth-client
+
+**Package**: `@suaveplan/oauth-client`
+**Version**: 0.0.0 (genesis)
+**Status**: ADDED
+
+---
+
+## ADDED Requirements
+
+### OC-01 — PKCE
+
+`generateCodeVerifier()` MUST produce a cryptographically-random string of 43–128 URL-safe characters per RFC 7636. `createCodeChallenge(verifier, method?)` MUST default `method` to `'S256'`. `verifyCodeChallenge(verifier, challenge, method?)` MUST return `true` iff `createCodeChallenge(verifier, method) === challenge`.
+
+### OC-02 — State / nonce
+
+`generateState()` and `generateNonce()` MUST each produce at least 128 bits of entropy encoded as Base64URL. Client-side code MUST compare state values with constant-time comparison to avoid timing oracles.
+
+### OC-03 — Discovery
+
+`fetchDiscoveryDocument(issuer, fetch?)` MUST fetch `${issuer}/.well-known/openid-configuration`, validate against `OIDCDiscoveryDocumentSchema`, and throw `OAUTH_CLIENT.DISCOVERY_FAILED` on network or validation failure. `configFromDiscovery` MUST produce an `OAuthProviderConfig` with all available endpoints.
+
+### OC-04 — Provider presets
+
+`getProviderPreset(name)` MUST return the `OAuthProviderConfig` for any `WellKnownProvider`. `getAvailableProviders()` MUST enumerate every preset. `isWellKnownProvider(name)` MUST return a type predicate.
+
+### OC-05 — Token exchange
+
+`exchangeCode(params)` MUST POST `application/x-www-form-urlencoded` to the token endpoint with `grant_type=authorization_code`, `code`, `redirect_uri`, `client_id`, `code_verifier`, and optional `client_secret`. A non-2xx response MUST surface as `OAUTH_CLIENT.TOKEN_EXCHANGE_FAILED` with `{ status, errorCode, errorDescription }`.
+
+### OC-06 — Refresh / revoke
+
+`refreshAccessToken(params)` MUST POST with `grant_type=refresh_token`. `revokeToken(params)` MUST POST to the provider's revocation endpoint per RFC 7009 and treat 200 and 204 as success.
+
+### OC-07 — JWT decode + ID-token validation
+
+`decodeJwt(token)` MUST return `{ header, payload, signature, raw }` without verifying the signature. `validateIdTokenClaims(claims, options)` MUST check `iss`, `aud`, `exp`, `nbf`, `iat`, `nonce`, `azp`. Failures MUST surface as `OAUTH_CLIENT.INVALID_ID_TOKEN`. Signature verification is out of scope for this capability (delegated to a future verifier).
+
+### OC-08 — Observability
+
+Every token operation MUST record `oauth_client.token_exchange.duration_ms` or `oauth_client.refresh.duration_ms` histograms and corresponding counters.

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

@@ -0,0 +1,43 @@
+# Tasks: enterprise-oauth-client
+
+## 1. Scaffold
+
+- [x] 1.1 `universal/auth/oauth-client/`; 100/100/100/100; guard tests; CLAUDE/README/FOLDERS.
+
+## 2. Errors + schemas
+
+- [x] 2.1 `src/error-codes.ts` — codes + side-effect register.
+- [x] 2.2 `src/config-errors.ts` — `oauthConfigMissing` helper.
+- [x] 2.3 Zod schemas for every type export.
+
+## 3. PKCE
+
+- [x] 3.1 `src/pkce/pkce.ts` — verifier/challenge/nonce/state + Base64URL codec.
+- [x] 3.2 Property tests.
+
+## 4. Provider presets
+
+- [x] 4.1 `src/provider/provider.ts` — built-in presets + factory functions.
+- [x] 4.2 Fixture tests against each preset's discovery document.
+
+## 5. Discovery
+
+- [x] 5.1 `src/discovery/discovery.ts` — URL builder + fetch + validation.
+
+## 6. Token operations
+
+- [x] 6.1 `src/token/token.ts` — `exchangeCode`, `refreshAccessToken`, `revokeToken`, `decodeJwt`, `validateIdTokenClaims`, `normalizeTokenResponse`, `isTokenExpired`, `OAuthTokenError`.
+
+## 7. Client
+
+- [x] 7.1 `src/client/client.ts` — `OAuthClient` façade; uses injected `FetchFunction` for testability.
+
+## 8. Docs / barrel / subpath exports / README
+
+## 9. Benchmarks
+
+- [x] 9.1 `exchangeCode.bench.ts`, `decodeJwt.bench.ts`.
+
+## 10. Ship gate
+
+- [x] 10.1 Verification sequence; fold + archive.