oauth

type AccountLinkedPayload struct {
	UserID     string `json:"user_id"`
	AccountID  string `json:"account_id"`
	Provider   string `json:"provider"`
	ProviderID string `json:"provider_id"`
}

type AccountUnlinkedPayload struct {
	UserID    string `json:"user_id"`
	AccountID string `json:"account_id"`
	Provider  string `json:"provider"`
}

type Action string

type AuthResult struct {
	// User is the resolved or newly created Core User.
	User *user.User

	// Account is the Core Account linking the User to this OAuth provider.
	Account *account.Account

	// Session is the newly issued Core Session.
	Session *session.Session

	// Token is the plaintext session token returned strictly once at session creation.
	Token string

	// IsNewUser indicates whether this authentication caused a new user to be registered.
	IsNewUser bool

	// TokenResponse holds the tokens returned by the OAuth provider.
	TokenResponse *provider.TokenResponse

	// Profile holds the normalized profile attributes fetched from the provider.
	Profile *provider.ProviderProfile
}

type AuthenticatedPayload struct {
	UserID     string `json:"user_id"`
	AccountID  string `json:"account_id"`
	Provider   string `json:"provider"`
	ProviderID string `json:"provider_id"`
	IsNewUser  bool   `json:"is_new_user"`
}

type BeginAuthInput struct {
	// Provider is the identifier of the registered OAuth provider (e.g. "google").
	Provider string

	// RedirectURI is the target callback URI to which the provider should redirect.
	RedirectURI string

	// Scopes specifies scopes for this request, overriding provider defaults if provided.
	Scopes []string

	// Prompt controls the IdP prompt behavior (e.g. "consent", "select_account").
	Prompt string

	// AccessType controls whether offline access / refresh tokens are requested ("offline").
	AccessType string

	// Metadata stores custom client state associated with this in-flight flow.
	Metadata map[string]string

	// UsePKCE overrides the default PKCE setting for this request (nil uses plugin default, which is true).
	UsePKCE *bool
}

type BeginAuthResult struct {
	// AuthURL is the complete provider URL the client browser should navigate to.
	AuthURL string

	// State is the unique, cryptographically random state identifier.
	State string

	// CodeVerifier is the generated PKCE verifier (stored securely in state session).
	CodeVerifier string

	// ExpiresAt specifies when the state session expires.
	ExpiresAt time.Time
}

type BeginLinkInput struct {
	// UserID is the ID of the currently authenticated Core user who is linking an account.
	UserID string

	// Provider is the identifier of the registered OAuth provider.
	Provider string

	// RedirectURI is the callback URI.
	RedirectURI string

	// Scopes specifies requested scopes.
	Scopes []string

	// Prompt controls the IdP prompt behavior.
	Prompt string

	// AccessType controls access type.
	AccessType string

	// Metadata stores custom client state.
	Metadata map[string]string

	// UsePKCE overrides default PKCE behavior.
	UsePKCE *bool
}

type CompleteAuthInput struct {
	// Provider is the identifier of the OAuth provider.
	Provider string

	// Code is the authorization code returned by the provider.
	Code string

	// State is the state parameter returned by the provider.
	State string

	// RedirectURI is the redirect URI supplied to the provider callback.
	RedirectURI string

	// Session holds optional metadata (IP address, user agent) recorded when creating the core session.
	Session auth.SessionOptions
}

type CompleteLinkInput struct {
	// Code is the authorization code returned by the provider.
	Code string

	// State is the state parameter returned by the provider.
	State string

	// RedirectURI is the callback redirect URI.
	RedirectURI string
}

type Config struct {
	// Providers maps provider name to its Provider implementation.
	Providers map[string]provider.Provider

	// StateTTL is the validity duration of newly issued OAuth state sessions.
	StateTTL time.Duration

	// LinkingPolicy determines whether and how accounts are linked when email addresses collide.
	// Defaults to LinkingPolicyExplicitOnly (preventing unsafe automatic account linking).
	LinkingPolicy LinkingPolicy

	// AllowSignUp controls whether unknown OAuth users are automatically registered.
	// Defaults to true.
	AllowSignUp bool

	// AllowOrphanUser allows unlinking a provider even if it leaves the user with no remaining auth credentials.
	// Defaults to false.
	AllowOrphanUser bool

	// UsePKCE determines whether PKCE (RFC 7636) is generated and required by default.
	// Defaults to true.
	UsePKCE bool

	// Hooks provides lifecycle interceptors for OAuth operations.
	Hooks *Hooks
}

type FailedPayload struct {
	Provider string `json:"provider"`
	Reason   string `json:"reason"`
}

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

type LinkResult struct {
	// User is the authenticated Core User who owns the linked account.
	User *user.User

	// Account is the newly created Core Account link.
	Account *account.Account

	// Profile is the normalized profile claims fetched from the provider.
	Profile *provider.ProviderProfile
}

type LinkingPolicy string

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

type OAuth interface {
	// BeginAuth initiates an OAuth authorization code flow for sign-in or account registration.
	// It validates the redirect URI, generates state and PKCE verifier, persists state, and returns the authorization URL.
	BeginAuth(ctx context.Context, in BeginAuthInput) (*BeginAuthResult, error)

	// BeginLink initiates an OAuth authorization code flow specifically for linking a provider to an existing authenticated user.
	// The user ID is bound to the state session to prevent CSRF and session confusion.
	BeginLink(ctx context.Context, in BeginLinkInput) (*BeginAuthResult, error)

	// CompleteAuth completes the OAuth flow: atomically consumes state, exchanges authorization code for tokens,
	// fetches provider profile, creates or locates the user and Core Account, and creates an active Core Session.
	CompleteAuth(ctx context.Context, in CompleteAuthInput) (*AuthResult, error)

	// CompleteLink completes an explicit account linking flow for the user bound during BeginLink.
	CompleteLink(ctx context.Context, in CompleteLinkInput) (*LinkResult, error)

	// UnlinkAccount removes the link between a user and an OAuth provider.
	// Fails with ErrCannotUnlinkSoleAuthMethod if this is the user's sole authentication method and orphaning is disabled.
	UnlinkAccount(ctx context.Context, userID, provider string) error

	// ListAccounts returns all external OAuth accounts linked to the user.
	ListAccounts(ctx context.Context, userID string) ([]*account.Account, error)

	// GetProvider returns a registered provider by name.
	GetProvider(name string) (provider.Provider, error)

	// PurgeExpired cleans up expired states from the store.
	PurgeExpired(ctx context.Context) (int, error)
}

type Option func(*Config)

type PKCEPair struct {
	Verifier  string `json:"verifier"`
	Challenge string `json:"challenge"`
	Method    string `json:"method"`
}

type StateCreatedPayload struct {
	Provider  string    `json:"provider"`
	State     string    `json:"state"`
	Action    string    `json:"action"`
	UserID    string    `json:"user_id,omitempty"`
	ExpiresAt time.Time `json:"expires_at"`
}

type StateSession struct {
	State        string            `json:"state"`
	Provider     string            `json:"provider"`
	RedirectURI  string            `json:"redirect_uri"`
	CodeVerifier string            `json:"code_verifier,omitempty"`
	Action       Action            `json:"action"`
	UserID       string            `json:"user_id,omitempty"`
	Metadata     map[string]string `json:"metadata,omitempty"`
	ExpiresAt    time.Time         `json:"expires_at"`
	ConsumedAt   *time.Time        `json:"consumed_at,omitempty"`
	CreatedAt    time.Time         `json:"created_at"`
}

type UserCreatedPayload struct {
	UserID     string `json:"user_id"`
	Email      string `json:"email"`
	Provider   string `json:"provider"`
	ProviderID string `json:"provider_id"`
}