genericoauth

type AuthMethod string

type Config struct {
	Providers    map[string]*ProviderConfig
	HTTPClient   *http.Client
	CookieConfig CookieConfig
	StateTTL     time.Duration
}

type CookieConfig struct {
	Name     string
	Secret   string
	Domain   string
	Path     string
	Secure   bool
	HTTPOnly bool
	SameSite http.SameSite
	MaxAge   time.Duration
}

type ExchangeRequest struct {
	Code         string
	RedirectURI  string
	CodeVerifier string
	DeviceID     string
}

type LinkAccountRequestPayload struct {
	UserID       string `json:"userId"`
	ProviderID   string `json:"providerId"`
	Code         string `json:"code"`
	CodeVerifier string `json:"codeVerifier,omitempty"`
}

type OIDCDiscoveryDocument struct {
	Issuer                string   `json:"issuer"`
	AuthorizationEndpoint string   `json:"authorization_endpoint"`
	TokenEndpoint         string   `json:"token_endpoint"`
	UserInfoEndpoint      string   `json:"userinfo_endpoint"`
	JWKSURI               string   `json:"jwks_uri"`
	ScopesSupported       []string `json:"scopes_supported,omitempty"`
}

type Option func(*Config)

type ParamBuilderFunc func(ctx context.Context) map[string]string

type Plugin struct {
	// contains filtered or unexported fields
}

type ProfileMapperFunc func(ctx context.Context, profile map[string]any) (*UserPartial, error)

type ProviderConfig struct {
	ProviderID              string            `json:"provider_id"`
	DiscoveryURL            string            `json:"discovery_url,omitempty"`
	Issuer                  string            `json:"issuer,omitempty"`
	RequireIssuerValidation bool              `json:"require_issuer_validation,omitempty"`
	AuthorizationURL        string            `json:"authorization_url,omitempty"`
	TokenURL                string            `json:"token_url,omitempty"`
	UserInfoURL             string            `json:"user_info_url,omitempty"`
	ClientID                string            `json:"client_id"`
	ClientSecret            string            `json:"client_secret,omitempty"`
	Scopes                  []string          `json:"scopes,omitempty"`
	RedirectURI             string            `json:"redirect_uri,omitempty"`
	ResponseType            string            `json:"response_type,omitempty"`
	ResponseMode            ResponseMode      `json:"response_mode,omitempty"`
	Prompt                  string            `json:"prompt,omitempty"`
	PKCE                    bool              `json:"pkce,omitempty"`
	AccessType              string            `json:"access_type,omitempty"`
	AccessTokenExpiresIn    time.Duration     `json:"access_token_expires_in,omitempty"`
	Authentication          AuthMethod        `json:"authentication,omitempty"`
	DisableImplicitSignUp   bool              `json:"disable_implicit_sign_up,omitempty"`
	DisableSignUp           bool              `json:"disable_sign_up,omitempty"`
	OverrideUserInfo        bool              `json:"override_user_info,omitempty"`
	DiscoveryHeaders        http.Header       `json:"-"`
	AuthorizationHeaders    http.Header       `json:"-"`
	AuthURLParams           map[string]string `json:"auth_url_params,omitempty"`
	TokenURLParams          map[string]string `json:"token_url_params,omitempty"`

	// Custom Hooks
	GetToken         TokenFetcherFunc    `json:"-"`
	GetUserInfo      UserInfoFetcherFunc `json:"-"`
	MapProfileToUser ProfileMapperFunc   `json:"-"`
}

type Repository interface {
	// GetUserByEmail finds a user entity matching the provided email address.
	//
	// Function:
	//   Used during OAuth Callback to match an existing user account by email when implicit account linking is enabled.
	//
	// Storage:
	//   Database (GORM / SQL) - Relational user entity lookup.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - email: Normalized email address string.
	//
	// Returns:
	//   - *entity.User: Matching user profile if found.
	//   - error: ErrUserNotFound if missing, or database error.
	//
	// Example SQL:
	//   SELECT id, email, name, email_verified, created_at, updated_at FROM users WHERE email = $1 LIMIT 1;
	GetUserByEmail(ctx context.Context, email string) (*entity.User, error)

	// GetUserByID finds a user entity by unique primary key identifier.
	//
	// Function:
	//   Used during LinkAccount flow to verify existence of the target user account.
	//
	// Storage:
	//   Database (GORM / SQL) - User primary key lookup.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - id: Unique primary key user ID.
	//
	// Returns:
	//   - *entity.User: User profile entity.
	//   - error: ErrUserNotFound if missing.
	//
	// Example SQL:
	//   SELECT id, email, name, email_verified, created_at, updated_at FROM users WHERE id = $1 LIMIT 1;
	GetUserByID(ctx context.Context, id string) (*entity.User, error)

	// GetAccountByProvider finds a social account binding by provider ID and provider subject/account ID.
	//
	// Function:
	//   Called during OAuth Callback to check if this social account was previously linked to a user.
	//
	// Storage:
	//   Database (GORM / SQL) - Social provider binding query.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - providerID: Registered provider key (e.g. "github", "google", "auth0").
	//   - accountID: Provider sub/id returned in UserInfo response.
	//
	// Returns:
	//   - *entity.Account: Linked account entity if found, or nil if not linked yet.
	//   - error: Nil if not found, or database error.
	//
	// Example SQL:
	//   SELECT id, user_id, provider, account_id, created_at, updated_at FROM accounts WHERE provider = $1 AND account_id = $2 LIMIT 1;
	GetAccountByProvider(ctx context.Context, providerID, accountID string) (*entity.Account, error)

	// CreateUser persists a new user entity in storage.
	//
	// Function:
	//   Called during OAuth Callback when a new social user logs in and auto-signup is enabled.
	//
	// Storage:
	//   Database (GORM / SQL) - User creation.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - user: User entity to persist.
	//
	// Returns:
	//   - *entity.User: Newly persisted user entity.
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   INSERT INTO users (id, email, name, email_verified, created_at, updated_at) VALUES ($1, $2, $3, $4, $5, $6);
	CreateUser(ctx context.Context, user *entity.User) (*entity.User, error)

	// CreateAccount persists a new social account binding linking a provider subject ID to a user ID.
	//
	// Function:
	//   Called after user creation or account linking to store provider credentials/tokens.
	//
	// Storage:
	//   Database (GORM / SQL) - Account entity creation.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - account: Account entity containing UserID, Provider, and AccountID.
	//
	// Returns:
	//   - *entity.Account: Persisted account entity.
	//   - error: ErrAccountAlreadyLinked if bound to another user.
	//
	// Example SQL:
	//   INSERT INTO accounts (id, user_id, provider, account_id, access_token, refresh_token, created_at, updated_at)
	//   VALUES ($1, $2, $3, $4, $5, $6, $7, $8);
	CreateAccount(ctx context.Context, account *entity.Account) (*entity.Account, error)

	// CreateSession persists a new active user session after successful OAuth authentication.
	//
	// Function:
	//   Called at the end of Callback flow to issue a new session.
	//
	// Storage:
	//   Database (GORM / SQL) - Active session creation.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - session: Active session entity to persist.
	//
	// Returns:
	//   - *entity.Session: Active session entity.
	//   - error: Nil on success, or database error.
	//
	// Example SQL:
	//   INSERT INTO sessions (id, user_id, token, expires_at, created_at, updated_at) VALUES ($1, $2, $3, $4, $5, $6);
	CreateSession(ctx context.Context, session *entity.Session) (*entity.Session, error)

	// SaveState persists transient state metadata (e.g. for non-cookie state storage).
	//
	// Function:
	//   Called during SignIn to store PKCE code_verifier and redirect URLs when cookie state is not used.
	//
	// Storage:
	//   Cache (Redis / In-Memory TTL) - Transient OAuth state with expiration TTL.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - key: State key identifier.
	//   - data: StateData struct.
	//   - ttl: Expiration lifetime duration.
	//
	// Returns:
	//   - error: Nil on success.
	//
	// Example Cache (Redis):
	//   err := rdb.Set(ctx, "oauth:state:" + key, bytes, ttl).Err()
	SaveState(ctx context.Context, key string, data *StateData, ttl time.Duration) error

	// GetState retrieves transient state metadata by state key.
	//
	// Function:
	//   Called during Callback to restore PKCE code_verifier and callback URL.
	//
	// Storage:
	//   Cache (Redis / In-Memory TTL) - Transient state lookup.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - key: State key identifier.
	//
	// Returns:
	//   - *StateData: State metadata if found and not expired.
	//   - error: ErrInvalidState if missing or expired.
	//
	// Example Cache (Redis):
	//   val, err := rdb.Get(ctx, "oauth:state:" + key).Bytes()
	GetState(ctx context.Context, key string) (*StateData, error)

	// DeleteState removes transient state metadata.
	//
	// Function:
	//   Called after consuming state during Callback to prevent state replay.
	//
	// Storage:
	//   Cache (Redis / In-Memory TTL) - Key eviction from Redis/memory.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - key: State key identifier.
	//
	// Returns:
	//   - error: Nil on success.
	//
	// Example Cache (Redis):
	//   err := rdb.Del(ctx, "oauth:state:" + key).Err()
	DeleteState(ctx context.Context, key string) error
}

type ResponseMode string

type SignInData struct {
	URL          string `json:"url"`
	State        string `json:"state"`
	CodeVerifier string `json:"code_verifier,omitempty"`
	Redirect     bool   `json:"redirect"`
}

type SignInRequestPayload struct {
	ProviderID  string `json:"providerId"`
	CallbackURL string `json:"callbackUrl,omitempty"`
}

type StateData struct {
	ProviderID   string    `json:"provider_id"`
	CodeVerifier string    `json:"code_verifier,omitempty"`
	CallbackURL  string    `json:"callback_url,omitempty"`
	CreatedAt    time.Time `json:"created_at"`
}

type TokenFetcherFunc func(ctx context.Context, req ExchangeRequest) (*Tokens, error)

type Tokens struct {
	AccessToken           string         `json:"access_token"`
	RefreshToken          string         `json:"refresh_token,omitempty"`
	IDToken               string         `json:"id_token,omitempty"`
	TokenType             string         `json:"token_type,omitempty"`
	AccessTokenExpiresAt  time.Time      `json:"access_token_expires_at,omitempty"`
	RefreshTokenExpiresAt time.Time      `json:"refresh_token_expires_at,omitempty"`
	Scopes                []string       `json:"scopes,omitempty"`
	Raw                   map[string]any `json:"raw,omitempty"`
}

type UserInfo struct {
	ID            string         `json:"id,omitempty"`
	Sub           string         `json:"sub,omitempty"`
	Email         string         `json:"email,omitempty"`
	EmailVerified bool           `json:"email_verified,omitempty"`
	Name          string         `json:"name,omitempty"`
	Picture       string         `json:"picture,omitempty"`
	Raw           map[string]any `json:"raw,omitempty"`
}

type UserInfoFetcherFunc func(ctx context.Context, tokens *Tokens) (*UserInfo, error)

type UserPartial struct {
	ID            string         `json:"id,omitempty"`
	Email         string         `json:"email,omitempty"`
	EmailVerified bool           `json:"email_verified,omitempty"`
	Name          string         `json:"name,omitempty"`
	Image         string         `json:"image,omitempty"`
	CustomFields  map[string]any `json:"custom_fields,omitempty"`
}