2.4 KiB
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.