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