42 lines
2.4 KiB
Markdown
42 lines
2.4 KiB
Markdown
# 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.
|