auth

type AccessToken struct {
	// Raw is the original JWT token string
	Raw string

	// ExpiresAt is when the token expires (from "exp" claim)
	ExpiresAt time.Time

	// UserID is the unique user identifier (from "sub" claim)
	UserID string

	// Email is the user's email address (from "email" claim)
	Email string

	// Roles are the user's roles (from "roles" claim)
	Roles []string

	// Issuer is the token issuer (from "iss" claim, should be "ainative-auth")
	Issuer string

	// Audience is the intended audience (from "aud" claim, should be "ainative-code")
	Audience string
}

type CallbackResult struct {
	// Code is the authorization code to exchange for tokens
	Code string

	// State is the CSRF token that must match the original request
	State string

	// Error is an error code if authorization failed
	Error string

	// ErrorDescription is a human-readable error description
	ErrorDescription string
}

type Client interface {
	// Authenticate initiates the OAuth 2.0 Authorization Code Flow with PKCE.
	//
	// This method:
	//   1. Generates PKCE parameters (code verifier, challenge, state)
	//   2. Builds authorization URL with required parameters
	//   3. Opens the user's browser to the authorization URL
	//   4. Starts local callback server to receive authorization code
	//   5. Waits for user to complete authorization
	//   6. Exchanges authorization code for tokens
	//   7. Stores tokens securely in OS keychain
	//   8. Returns the token pair
	//
	// The authorization flow respects context cancellation and timeouts.
	// Default timeout is 5 minutes, but can be configured via options.
	//
	// Returns:
	//   - ErrAuthorizationDenied if user denies authorization
	//   - ErrAuthorizationTimeout if user doesn't complete flow in time
	//   - ErrInvalidState if state parameter doesn't match (CSRF attack)
	//   - ErrCodeExchangeFailed if token endpoint rejects the code
	//   - ErrCallbackServerStart if local server fails to start
	//   - ErrBrowserOpen if browser cannot be opened
	//
	// Example:
	//
	//	ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
	//	defer cancel()
	//
	//	tokens, err := client.Authenticate(ctx)
	//	if err != nil {
	//	    return fmt.Errorf("authentication failed: %w", err)
	//	}
	//	fmt.Printf("Authenticated as: %s\n", tokens.AccessToken.Email)
	Authenticate(ctx context.Context) (*TokenPair, error)

	// RefreshToken exchanges a refresh token for a new access token.
	//
	// This method:
	//   1. Sends refresh token to token endpoint
	//   2. Receives new access token (and optionally new refresh token)
	//   3. Updates tokens in OS keychain
	//   4. Returns updated token pair
	//
	// If the refresh token is expired or revoked, this method returns an error
	// and the client should re-authenticate using Authenticate().
	//
	// Returns:
	//   - ErrTokenExpired if refresh token has expired
	//   - ErrCodeExchangeFailed if token endpoint rejects refresh token
	//   - ErrHTTPRequest if network request fails
	//   - ErrHTTPResponse if server returns error status
	//
	// Example:
	//
	//	tokens, err := client.GetStoredTokens(ctx)
	//	if err != nil {
	//	    return client.Authenticate(ctx)
	//	}
	//
	//	if tokens.AccessToken.IsExpired() {
	//	    tokens, err = client.RefreshToken(ctx, tokens.RefreshToken)
	//	    if err != nil {
	//	        // Refresh failed, re-authenticate
	//	        return client.Authenticate(ctx)
	//	    }
	//	}
	RefreshToken(ctx context.Context, refreshToken *RefreshToken) (*TokenPair, error)

	// GetStoredTokens retrieves tokens from OS keychain.
	//
	// This method:
	//   1. Reads token data from secure keychain storage
	//   2. Parses and validates JWT tokens
	//   3. Returns token pair if found and valid
	//
	// The returned tokens may be expired. Callers should check
	// token.AccessToken.IsExpired() and refresh if needed.
	//
	// Returns:
	//   - ErrKeychainNotFound if no tokens are stored
	//   - ErrKeychainAccess if keychain access is denied
	//   - ErrKeychainRetrieve if reading from keychain fails
	//   - ErrTokenParseFailed if stored token data is corrupted
	//
	// Example:
	//
	//	tokens, err := client.GetStoredTokens(ctx)
	//	if errors.Is(err, auth.ErrKeychainNotFound) {
	//	    // No stored tokens, authenticate
	//	    return client.Authenticate(ctx)
	//	}
	//	if err != nil {
	//	    return fmt.Errorf("failed to get tokens: %w", err)
	//	}
	GetStoredTokens(ctx context.Context) (*TokenPair, error)

	// StoreTokens saves tokens to OS keychain.
	//
	// This method:
	//   1. Validates token format and expiration
	//   2. Encrypts token data using OS keychain
	//   3. Stores in platform-specific secure storage
	//
	// Tokens are stored with service identifier "ainative-code"
	// and account identifier derived from user ID.
	//
	// Returns:
	//   - ErrKeychainAccess if keychain access is denied
	//   - ErrKeychainStore if writing to keychain fails
	//
	// Example:
	//
	//	tokens, err := client.Authenticate(ctx)
	//	if err != nil {
	//	    return err
	//	}
	//	// Tokens are automatically stored by Authenticate(),
	//	// but you can manually store them if needed:
	//	if err := client.StoreTokens(ctx, tokens); err != nil {
	//	    log.Printf("Failed to store tokens: %v", err)
	//	}
	StoreTokens(ctx context.Context, tokens *TokenPair) error

	// ClearTokens removes tokens from OS keychain.
	//
	// This method:
	//   1. Deletes token data from OS keychain
	//   2. Clears any in-memory token cache
	//
	// Use this method to implement logout functionality.
	//
	// Returns:
	//   - ErrKeychainAccess if keychain access is denied
	//   - ErrKeychainDelete if deletion fails
	//
	// Note: This does NOT revoke tokens on the server. To fully logout,
	// you should also call the server's token revocation endpoint.
	//
	// Example:
	//
	//	if err := client.ClearTokens(ctx); err != nil {
	//	    log.Printf("Failed to clear tokens: %v", err)
	//	}
	ClearTokens(ctx context.Context) error

	// ValidateToken checks if an access token is valid and not expired.
	//
	// This method:
	//   1. Checks token expiration time
	//   2. Verifies JWT signature using public key
	//   3. Validates standard claims (iss, aud, sub, exp)
	//   4. Optionally performs introspection at server (if configured)
	//
	// Returns true if token is valid and can be used for API requests.
	// Returns false if token is expired, has invalid signature, or fails
	// server-side validation.
	//
	// This is a convenience method. Callers can also check
	// token.IsExpired() directly for simple expiration checks.
	//
	// Example:
	//
	//	tokens, _ := client.GetStoredTokens(ctx)
	//	if !client.ValidateToken(ctx, tokens.AccessToken) {
	//	    // Token invalid, refresh or re-authenticate
	//	    tokens, err = client.RefreshToken(ctx, tokens.RefreshToken)
	//	}
	ValidateToken(ctx context.Context, token *AccessToken) bool
}

type ClientOptions struct {
	// ClientID is the OAuth 2.0 client identifier
	ClientID string

	// AuthEndpoint is the authorization endpoint URL
	// Default: https://auth.ainative.studio/oauth/authorize
	AuthEndpoint string

	// TokenEndpoint is the token endpoint URL
	// Default: https://auth.ainative.studio/oauth/token
	TokenEndpoint string

	// RedirectURI is the callback URL for OAuth redirect
	// Default: http://localhost:8080/callback
	RedirectURI string

	// Scopes are the OAuth 2.0 scopes to request
	// Default: ["read", "write", "offline_access"]
	Scopes []string

	// Timeout is the timeout for HTTP requests
	// Default: 30 seconds
	Timeout time.Duration

	// PublicKey is the RSA public key for JWT signature verification
	// This should be fetched from the auth server's JWKS endpoint
	PublicKey *rsa.PublicKey

	// CallbackPort is the port for the local callback server
	// Default: 8080
	CallbackPort int
}

type Config = ClientOptions

type PKCEParams struct {
	// CodeVerifier is a cryptographically random string (43-128 characters)
	// using the characters [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~"
	CodeVerifier string

	// CodeChallenge is the SHA-256 hash of CodeVerifier, base64url-encoded
	// without padding (RFC 4648 Section 5)
	CodeChallenge string

	// Method is the code challenge method, always "S256" for SHA-256
	Method string

	// State is a CSRF token that must be validated in the callback
	State string
}

type RefreshToken struct {
	// Raw is the original JWT token string
	Raw string

	// ExpiresAt is when the token expires (from "exp" claim)
	ExpiresAt time.Time

	// UserID is the unique user identifier (from "sub" claim)
	UserID string

	// SessionID is the session identifier (from "session_id" claim)
	SessionID string

	// Issuer is the token issuer (from "iss" claim, should be "ainative-auth")
	Issuer string

	// Audience is the intended audience (from "aud" claim, should be "ainative-code")
	Audience string
}

type TokenPair struct {
	// AccessToken is the JWT access token used for API authentication.
	AccessToken *AccessToken

	// RefreshToken is the JWT refresh token used to obtain new access tokens.
	RefreshToken *RefreshToken

	// ReceivedAt is when this token pair was received from the server.
	// Used for calculating token age and refresh timing.
	ReceivedAt time.Time
}

type TokenResponse struct {
	// AccessToken is the parsed access token
	AccessToken *AccessToken

	// RefreshToken is the parsed refresh token (may be nil)
	RefreshToken *RefreshToken

	// ExpiresIn is the number of seconds until access token expires
	ExpiresIn int64

	// TokenType is the type of token, always "Bearer" for JWT
	TokenType string

	// Scope is the granted scopes (space-separated string)
	Scope string
}