Improve documentation.

jwk.go

@@ -16,37 +16,74 @@ import (
 	"time"
 )
 
-// JWK represents a JSON Web Key
+// JWK represents a JSON Web Key as defined in RFC 7517.
+// It contains the cryptographic key information used for token verification.
 type JWK struct {
+	// Kty is the key type (e.g., "RSA", "EC")
 	Kty string `json:"kty"`
+
+	// Kid is the unique key identifier
 	Kid string `json:"kid"`
+
+	// Use specifies the intended use of the key (e.g., "sig" for signature)
 	Use string `json:"use"`
-	N   string `json:"n"`
-	E   string `json:"e"`
+
+	// N is the modulus for RSA keys
+	N string `json:"n"`
+
+	// E is the exponent for RSA keys
+	E string `json:"e"`
+
+	// Alg is the algorithm intended for use with the key
 	Alg string `json:"alg"`
+
+	// Crv is the curve for EC keys (e.g., "P-256", "P-384", "P-521")
 	Crv string `json:"crv"`
-	X   string `json:"x"`
-	Y   string `json:"y"`
+
+	// X is the x-coordinate for EC keys
+	X string `json:"x"`
+
+	// Y is the y-coordinate for EC keys
+	Y string `json:"y"`
 }
 
-// JWKSet represents a set of JWKs
+// JWKSet represents a set of JSON Web Keys as returned by the JWKS endpoint.
+// OIDC providers typically expose multiple keys to support key rotation.
 type JWKSet struct {
+	// Keys is the array of JSON Web Keys
 	Keys []JWK `json:"keys"`
 }
 
-// JWKCache caches the JWKs
+// JWKCache provides a thread-safe caching mechanism for JWK sets.
+// It caches the keys for a configurable duration to reduce load on the OIDC provider
+// while ensuring keys are refreshed periodically to handle key rotation.
 type JWKCache struct {
-	jwks      *JWKSet
+	// jwks holds the cached set of JSON Web Keys
+	jwks *JWKSet
+
+	// expiresAt is the timestamp when the cached keys should be refreshed
 	expiresAt time.Time
-	mutex     sync.RWMutex
+
+	// mutex protects concurrent access to the cache
+	mutex sync.RWMutex
 }
 
-// JWKCacheInterface defines the interface for the JWK cache
+// JWKCacheInterface defines the interface for JWK caching operations.
+// This interface allows for different caching implementations while
+// maintaining consistent behavior in the token verification process.
 type JWKCacheInterface interface {
 	GetJWKS(jwksURL string, httpClient *http.Client) (*JWKSet, error)
 }
 
-// GetJWKS gets the JWKS, either from cache or by fetching it
+// GetJWKS retrieves the JSON Web Key Set, either from cache or by fetching it
+// from the OIDC provider. It implements a thread-safe double-checked locking
+// pattern to prevent multiple simultaneous fetches of the same keys.
+// Parameters:
+//   - jwksURL: The URL of the JWKS endpoint
+//   - httpClient: The HTTP client to use for fetching keys
+// Returns:
+//   - The JSON Web Key Set
+//   - An error if the keys cannot be retrieved or parsed
 func (c *JWKCache) GetJWKS(jwksURL string, httpClient *http.Client) (*JWKSet, error) {
 	c.mutex.RLock()
 	if c.jwks != nil && time.Now().Before(c.expiresAt) {
@@ -73,7 +110,14 @@ func (c *JWKCache) GetJWKS(jwksURL string, httpClient *http.Client) (*JWKSet, er
 	return jwks, nil
 }
 
-// fetchJWKS fetches the JWKS from the provider
+// fetchJWKS retrieves the JSON Web Key Set from the OIDC provider's JWKS endpoint.
+// It handles HTTP communication and JSON parsing of the response.
+// Parameters:
+//   - jwksURL: The URL of the JWKS endpoint
+//   - httpClient: The HTTP client to use for the request
+// Returns:
+//   - The parsed JSON Web Key Set
+//   - An error if the request fails or the response is invalid
 func fetchJWKS(jwksURL string, httpClient *http.Client) (*JWKSet, error) {
 	resp, err := httpClient.Get(jwksURL)
 	if err != nil {
@@ -93,7 +137,9 @@ func fetchJWKS(jwksURL string, httpClient *http.Client) (*JWKSet, error) {
 	return &jwks, nil
 }
 
-// jwkToPEM converts a JWK to PEM format
+// jwkToPEM converts a JSON Web Key to PEM format for use with standard
+// cryptographic functions. It supports both RSA and EC keys, delegating
+// to the appropriate converter based on the key type.
 func jwkToPEM(jwk *JWK) ([]byte, error) {
 	converter, ok := jwkConverters[jwk.Kty]
 	if !ok {
@@ -109,7 +155,9 @@ var jwkConverters = map[string]jwkToPEMConverter{
 	"EC":  ecJWKToPEM,
 }
 
-// rsaJWKToPEM converts an RSA JWK to PEM
+// rsaJWKToPEM converts an RSA JSON Web Key to PEM format.
+// It handles base64url decoding of the modulus and exponent,
+// constructs an RSA public key, and encodes it in PEM format.
 func rsaJWKToPEM(jwk *JWK) ([]byte, error) {
 	nBytes, err := base64.RawURLEncoding.DecodeString(jwk.N)
 	if err != nil {
@@ -141,7 +189,10 @@ func rsaJWKToPEM(jwk *JWK) ([]byte, error) {
 	return pubKeyPEM, nil
 }
 
-// ecJWKToPEM converts an EC JWK to PEM
+// ecJWKToPEM converts an EC (Elliptic Curve) JSON Web Key to PEM format.
+// It supports the P-256, P-384, and P-521 curves as defined in the
+// OIDC specification, decoding the x and y coordinates and encoding
+// the resulting public key in PEM format.
 func ecJWKToPEM(jwk *JWK) ([]byte, error) {
 	xBytes, err := base64.RawURLEncoding.DecodeString(jwk.X)
 	if err != nil {