Refactor client storage to own domain type

Created storage.Client type that owns the complete client concept (OAuth
fields plus metadata). Fosite's DefaultClient couldn't hold metadata, so
we were losing CreatedAt timestamps from Firestore.

Now storage.Client has CreatedAt and can extend with LastUsed,
Description, Enabled in the future. Fosite becomes an implementation
detail we adapt to via ToFositeClient(), not something that constrains
our domain model.

The /clients/{client_id} and /register endpoints now return actual
creation timestamps instead of 0 or time.Now() at retrieval time.

Author: dgellow

CLAUDE.md

@@ -418,6 +418,29 @@ Remember: The mascot is an easter egg, not a distraction. Subtle movements creat
 
 3. **Don't bring patterns from other systems** - Understand THIS system's design choices.
 
+### Approaching Problems
+
+**Never rush.** There is no time pressure. Approach every question with curiosity and investigation, not urgency.
+
+When faced with a problem or decision:
+
+1. **Seek the complete picture first** - Don't jump to solutions
+2. **Investigate thoroughly** - Read the code, understand the architecture, trace the data flow
+3. **Ask clarifying questions** - What's the actual use case? What's the value? What are the tradeoffs?
+4. **Think architecturally** - What's the right abstraction? Where do concerns belong?
+5. **Expand the solution space** - Don't settle on the first approach. Be creative. What if we ignored time and complexity? Would a larger refactoring lead to a fundamentally better design?
+6. **Consider future needs** - What might we want later? Does this approach scale to those needs?
+7. **Only then decide** - After exploring fully, choose the approach
+
+The question is never "what's the quick fix?" The question is "what's the right design given what we now understand?"
+
+**Example progression:**
+- ❌ "Here are three options, which one do you want?"
+- ✅ "Let me investigate how this works... [reads code]... I see we already store timestamps in Firestore but lose them during conversion. The core issue is fosite.DefaultClient can't hold metadata. What's the actual value of exposing this timestamp?"
+- ✅✅ "One approach is adding GetClientMetadata() alongside GetClient(). But let me think bigger - what if we stopped being constrained by fosite's storage interface? We could build our own Client type with metadata and use fosite as an implementation detail. Larger refactoring, but natural place for future metadata needs. What's your instinct on likely future requirements?"
+
+Don't get anchored on the first solution. Explore the design space. Sometimes the right answer is a bigger change that solves the problem more fundamentally.
+
 ### When You're Stuck
 
 - **ASK QUESTIONS** - Even "dumb" questions are better than wrong assumptions

internal/server/auth_handlers.go

@@ -3,6 +3,7 @@ package server
 import (
 	"context"
 	"encoding/json"
+	"errors"
 	"fmt"
 	"net/http"
 	"net/url"
@@ -101,7 +102,6 @@ func (h *AuthHandlers) ProtectedResourceMetadataHandler(w http.ResponseWriter, r
 	}
 }
 
-// ClientMetadataHandler serves OAuth 2.0 Client Metadata for dynamic discovery
 func (h *AuthHandlers) ClientMetadataHandler(w http.ResponseWriter, r *http.Request) {
 	clientID := r.PathValue("client_id")
 	if clientID == "" {
@@ -111,26 +111,30 @@ func (h *AuthHandlers) ClientMetadataHandler(w http.ResponseWriter, r *http.Requ
 
 	log.Logf("Client metadata handler called for client: %s", clientID)
 
-	client, err := h.storage.GetClient(r.Context(), clientID)
+	client, err := h.storage.GetClientWithMetadata(r.Context(), clientID)
 	if err != nil {
 		log.LogError("Failed to get client %s: %v", clientID, err)
-		jsonwriter.WriteNotFound(w, "Client not found")
+		if errors.Is(err, fosite.ErrNotFound) {
+			jsonwriter.WriteNotFound(w, "Client not found")
+		} else {
+			jsonwriter.WriteInternalServerError(w, "Failed to retrieve client")
+		}
 		return
 	}
 
 	tokenEndpointAuthMethod := "none"
-	if len(client.GetHashedSecret()) > 0 {
+	if len(client.Secret) > 0 {
 		tokenEndpointAuthMethod = "client_secret_post"
 	}
 
 	metadata := oauth.BuildClientMetadata(
-		client.GetID(),
-		client.GetRedirectURIs(),
-		client.GetGrantTypes(),
-		client.GetResponseTypes(),
-		client.GetScopes(),
+		client.ID,
+		client.RedirectURIs,
+		client.GrantTypes,
+		client.ResponseTypes,
+		client.Scopes,
 		tokenEndpointAuthMethod,
-		0,
+		client.CreatedAt,
 	)
 
 	w.Header().Set("Content-Type", "application/json")
@@ -417,19 +421,17 @@ func (h *AuthHandlers) TokenHandler(w http.ResponseWriter, r *http.Request) {
 	h.oauthProvider.WriteAccessResponse(ctx, w, accessRequest, response)
 }
 
-// buildClientRegistrationResponse creates the registration response for a client
-func (h *AuthHandlers) buildClientRegistrationResponse(client *fosite.DefaultClient, tokenEndpointAuthMethod string, clientSecret string) map[string]any {
+func (h *AuthHandlers) buildClientRegistrationResponse(client *storage.Client, tokenEndpointAuthMethod string, clientSecret string) map[string]any {
 	response := map[string]any{
-		"client_id":                  client.GetID(),
-		"client_id_issued_at":        time.Now().Unix(),
-		"redirect_uris":              client.GetRedirectURIs(),
-		"grant_types":                client.GetGrantTypes(),
-		"response_types":             client.GetResponseTypes(),
-		"scope":                      strings.Join(client.GetScopes(), " "), // Space-separated string
+		"client_id":                  client.ID,
+		"client_id_issued_at":        client.CreatedAt,
+		"redirect_uris":              client.RedirectURIs,
+		"grant_types":                client.GrantTypes,
+		"response_types":             client.ResponseTypes,
+		"scope":                      strings.Join(client.Scopes, " "),
 		"token_endpoint_auth_method": tokenEndpointAuthMethod,
 	}
 
-	// Include client_secret only for confidential clients
 	if clientSecret != "" {
 		response["client_secret"] = clientSecret
 	}
@@ -461,27 +463,34 @@ func (h *AuthHandlers) RegisterHandler(w http.ResponseWriter, r *http.Request) {
 		return
 	}
 
-	// Check if client requests client_secret_post authentication
 	tokenEndpointAuthMethod := "none"
-	var client *fosite.DefaultClient
+	var client *storage.Client
 	var plaintextSecret string
 	clientID := crypto.GenerateSecureToken()
 
 	if authMethod, ok := metadata["token_endpoint_auth_method"].(string); ok && authMethod == "client_secret_post" {
-		// Create confidential client with a secret
 		plaintextSecret = crypto.GenerateSecureToken()
 		hashedSecret, err := crypto.HashClientSecret(plaintextSecret)
 		if err != nil {
 			log.LogError("Failed to hash client secret: %v", err)
 			jsonwriter.WriteInternalServerError(w, "Failed to create client")
 			return
 		}
-		client = h.storage.CreateConfidentialClient(clientID, hashedSecret, redirectURIs, scopes, h.authConfig.Issuer)
+		client, err = h.storage.CreateConfidentialClient(clientID, hashedSecret, redirectURIs, scopes, h.authConfig.Issuer)
+		if err != nil {
+			log.LogError("Failed to create confidential client: %v", err)
+			jsonwriter.WriteInternalServerError(w, "Failed to create client")
+			return
+		}
 		tokenEndpointAuthMethod = "client_secret_post"
 		log.Logf("Creating confidential client %s with client_secret_post authentication", clientID)
 	} else {
-		// Create public client (no secret)
-		client = h.storage.CreateClient(clientID, redirectURIs, scopes, h.authConfig.Issuer)
+		client, err = h.storage.CreateClient(clientID, redirectURIs, scopes, h.authConfig.Issuer)
+		if err != nil {
+			log.LogError("Failed to create client: %v", err)
+			jsonwriter.WriteInternalServerError(w, "Failed to create client")
+			return
+		}
 		log.Logf("Creating public client %s with no authentication", clientID)
 	}
 
@@ -640,7 +649,11 @@ func (h *AuthHandlers) CompleteOAuthHandler(w http.ResponseWriter, r *http.Reque
 	client, err := h.storage.GetClient(ctx, upstreamOAuthState.ClientID)
 	if err != nil {
 		log.LogError("Failed to get client: %v", err)
-		jsonwriter.WriteInternalServerError(w, "Client not found")
+		if errors.Is(err, fosite.ErrNotFound) {
+			jsonwriter.WriteNotFound(w, "Client not found")
+		} else {
+			jsonwriter.WriteInternalServerError(w, "Failed to retrieve client")
+		}
 		return
 	}
 

internal/storage/client.go

@@ -0,0 +1,43 @@
+package storage
+
+import "github.com/ory/fosite"
+
+type Client struct {
+	ID            string
+	Secret        []byte
+	RedirectURIs  []string
+	Scopes        []string
+	GrantTypes    []string
+	ResponseTypes []string
+	Audience      []string
+	Public        bool
+
+	CreatedAt int64
+}
+
+func (c *Client) ToFositeClient() *fosite.DefaultClient {
+	return &fosite.DefaultClient{
+		ID:            c.ID,
+		Secret:        c.Secret,
+		RedirectURIs:  c.RedirectURIs,
+		Scopes:        c.Scopes,
+		GrantTypes:    c.GrantTypes,
+		ResponseTypes: c.ResponseTypes,
+		Audience:      c.Audience,
+		Public:        c.Public,
+	}
+}
+
+func FromFositeClient(fc *fosite.DefaultClient, createdAt int64) *Client {
+	return &Client{
+		ID:            fc.ID,
+		Secret:        fc.Secret,
+		RedirectURIs:  fc.RedirectURIs,
+		Scopes:        fc.Scopes,
+		GrantTypes:    fc.GrantTypes,
+		ResponseTypes: fc.ResponseTypes,
+		Audience:      fc.Audience,
+		Public:        fc.Public,
+		CreatedAt:     createdAt,
+	}
+}