core

type APIKey struct {
	KeyID      string     `json:"key_id"`   // Public identifier (e.g., "oa_abc123...")
	KeyHash    string     `json:"key_hash"` // bcrypt hash of the secret portion
	UserID     string     `json:"user_id"`  // Owner of this key
	Name       string     `json:"name"`     // User-defined label
	Scopes     []string   `json:"scopes"`   // Allowed scopes
	CreatedAt  time.Time  `json:"created_at"`
	ExpiresAt  *time.Time `json:"expires_at,omitempty"` // Optional expiry
	LastUsedAt time.Time  `json:"last_used_at"`
	RevokedAt  *time.Time `json:"revoked_at,omitempty"`
	Revoked    bool       `json:"revoked"`
}

type APIKeyStore interface {
	// CreateAPIKey creates a new API key and returns the full key (only shown once)
	// The key format is: keyID + "_" + secret
	CreateAPIKey(userID, name string, scopes []string, expiresAt *time.Time) (fullKey string, apiKey *APIKey, err error)

	// GetAPIKeyByID retrieves an API key by its public ID
	GetAPIKeyByID(keyID string) (*APIKey, error)

	// ValidateAPIKey validates a full API key and returns the key metadata if valid
	// The fullKey format is: keyID + "_" + secret
	ValidateAPIKey(fullKey string) (*APIKey, error)

	// RevokeAPIKey marks an API key as revoked
	RevokeAPIKey(keyID string) error

	// ListUserAPIKeys returns all API keys for a user (without secrets)
	ListUserAPIKeys(userID string) ([]*APIKey, error)

	// UpdateAPIKeyLastUsed updates the last used timestamp
	UpdateAPIKeyLastUsed(keyID string) error
}

type AccountLockout struct {
	MaxAttempts  int           // consecutive failures before lockout (default: 5)
	LockDuration time.Duration // how long the lockout lasts (default: 15 min)
	// contains filtered or unexported fields
}

type AuthError struct {
	Code    string // "email_exists", "username_taken", "weak_password", "invalid_format", etc.
	Message string // Human-readable message
	Field   string // Which form field has the error (e.g., "email", "username", "password")
}

type AuthErrorHandler func(err *AuthError, w http.ResponseWriter, r *http.Request) bool

type AuthToken struct {
	Token     string    `json:"token"`
	Type      TokenType `json:"type"`
	UserID    string    `json:"user_id"`
	Email     string    `json:"email"`
	CreatedAt time.Time `json:"created_at"`
	ExpiresAt time.Time `json:"expires_at"`
}

type AuthorizationDetail struct {
	// Type is the authorization details type identifier (required).
	Type string `json:"type"`

	// Locations is an array of URIs indicating where the requested
	// resource can be found.
	Locations []string `json:"locations,omitempty"`

	// Actions is an array of strings describing the operations to be
	// performed on the resource.
	Actions []string `json:"actions,omitempty"`

	// DataTypes is an array of strings describing the types of data
	// being requested.
	DataTypes []string `json:"datatypes,omitempty"`

	// Identifier is a string identifying a specific resource at the API.
	Identifier string `json:"identifier,omitempty"`

	// Privileges is an array of strings representing privilege levels.
	Privileges []string `json:"privileges,omitempty"`

	// Extra holds API-specific extension fields. These are flattened into
	// the top-level JSON object (not nested under an "extra" key).
	Extra map[string]any `json:"-"`
}

type BasicUser struct {
	ID          string
	ProfileData map[string]any
}

type Channel struct {
	Provider    string         `json:"provider"`     // "local", "google", "github"
	IdentityKey string         `json:"identity_key"` // "email:john@example.com"
	Credentials map[string]any `json:"credentials"`  // password_hash, access_token, etc.
	Profile     map[string]any `json:"profile"`      // optional data from provider
	CreatedAt   time.Time      `json:"created_at"`
	UpdatedAt   time.Time      `json:"updated_at"`
	ExpiresAt   time.Time      `json:"expires_at"` // when channel auth expires and needs re-auth
	Version     int            `json:"version"`    // optimistic locking version
}

type ChannelStore interface {
	// GetChannel gets or optionally creates a channel
	GetChannel(provider string, identityKey string, createIfMissing bool) (channel *Channel, newCreated bool, err error)

	// SaveChannel creates or updates a channel (upsert)
	SaveChannel(channel *Channel) error

	// GetChannelsByIdentity returns all channels for an identity
	GetChannelsByIdentity(identityKey string) ([]*Channel, error)
}

type ConsoleEmailSender struct{}

type CreateUserFunc func(creds *Credentials) (User, error)

type Credentials struct {
	Username string  // Required for signup, can be username/email/phone for login
	Email    *string // Optional for signup
	Phone    *string // Optional for signup
	Password string  // Required
}

type CredentialsValidator func(username, password, usernameType string) (User, error)

type GetUserScopesFunc func(userID string) ([]string, error)

type HandleUserFunc func(authtype string, provider string, token *oauth2.Token, userInfo map[string]any, w http.ResponseWriter, r *http.Request)

type Identity struct {
	Type      string    `json:"type"`     // "email", "phone"
	Value     string    `json:"value"`    // "john@example.com", "+1-555-1234"
	UserID    string    `json:"user_id"`  // which user owns this identity
	Verified  bool      `json:"verified"` // has any channel verified this identity?
	CreatedAt time.Time `json:"created_at"`
	UpdatedAt time.Time `json:"updated_at"`
	Version   int       `json:"version"` // optimistic locking version
}

type IdentityStore interface {
	// GetIdentity gets or optionally creates an identity
	GetIdentity(identityType, identityValue string, createIfMissing bool) (identity *Identity, newCreated bool, err error)

	// SaveIdentity creates or updates an identity (upsert)
	SaveIdentity(identity *Identity) error

	// SetUserForIdentity associates an identity with a user
	SetUserForIdentity(identityType, identityValue string, newUserId string) error

	// MarkIdentityVerified marks an identity as verified
	MarkIdentityVerified(identityType, identityValue string) error

	// GetUserIdentities returns all identities for a user
	GetUserIdentities(userId string) ([]*Identity, error)
}

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

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

type RateLimiter interface {
	// Allow returns true if the operation is permitted for the given key.
	// Returns false if the rate limit has been exceeded.
	Allow(key string) bool
}

type RefreshToken struct {
	Token                string                `json:"token"`                           // 64-char hex token value
	TokenHash            string                `json:"token_hash"`                      // SHA256 hash for storage (optional)
	UserID               string                `json:"user_id"`                         // Associated user
	ClientID             string                `json:"client_id"`                       // Optional client/app identifier
	DeviceInfo           map[string]any        `json:"device_info"`                     // User agent, IP, etc.
	Family               string                `json:"family"`                          // Token family for rotation tracking
	Generation           int                   `json:"generation"`                      // Increments on rotation
	Scopes               []string              `json:"scopes"`                          // Granted scopes
	AuthorizationDetails []AuthorizationDetail `json:"authorization_details,omitempty"` // RFC 9396
	CreatedAt            time.Time             `json:"created_at"`
	ExpiresAt            time.Time             `json:"expires_at"`
	LastUsedAt           time.Time             `json:"last_used_at"`
	RevokedAt            *time.Time            `json:"revoked_at,omitempty"`
	Revoked              bool                  `json:"revoked"`
}

type RefreshTokenStore interface {
	// CreateRefreshToken creates a new refresh token for a user
	CreateRefreshToken(userID, clientID string, deviceInfo map[string]any, scopes []string) (*RefreshToken, error)

	// GetRefreshToken retrieves a refresh token by its value
	GetRefreshToken(token string) (*RefreshToken, error)

	// RotateRefreshToken invalidates old token and creates new one in same family
	// Returns ErrTokenReused if the old token was already revoked (theft detection)
	RotateRefreshToken(oldToken string) (*RefreshToken, error)

	// RevokeRefreshToken marks a token as revoked
	RevokeRefreshToken(token string) error

	// RevokeUserTokens revokes all refresh tokens for a user
	RevokeUserTokens(userID string) error

	// RevokeTokenFamily revokes all tokens in a family (theft detection)
	RevokeTokenFamily(family string) error

	// GetUserTokens lists all active (non-revoked, non-expired) refresh tokens for a user
	GetUserTokens(userID string) ([]*RefreshToken, error)

	// CleanupExpiredTokens removes expired tokens (for maintenance)
	CleanupExpiredTokens() error
}

type SendEmail interface {
	SendVerificationEmail(to string, verificationLink string) error
	SendPasswordResetEmail(to string, resetLink string) error
}

type SignupPolicy struct {
	RequireUsername       bool   // Is username required? (default: false)
	RequireEmail          bool   // Is email required? (default: true)
	RequirePhone          bool   // Is phone required? (default: false)
	RequirePassword       bool   // Is password required for local? (default: true)
	EnforceUsernameUnique bool   // Check UsernameStore? (default: true if username required)
	EnforceEmailUnique    bool   // Check IdentityStore? (default: true)
	MinPasswordLength     int    // Minimum password (default: 8)
	UsernamePattern       string // Regex for username (default: ^[a-zA-Z0-9_-]{3,20}$)
}

type SignupValidator func(creds *Credentials) error

type TokenBlacklist interface {
	// Revoke adds a token ID to the blacklist. The entry should be kept
	// until expiry (when the token would naturally expire anyway).
	Revoke(jti string, expiry time.Time) error

	// IsRevoked returns true if the token ID has been revoked and hasn't expired.
	IsRevoked(jti string) bool
}

type TokenError struct {
	Error            string `json:"error"`
	ErrorDescription string `json:"error_description,omitempty"`
}

type TokenPair struct {
	AccessToken          string                `json:"access_token"`
	TokenType            string                `json:"token_type"` // "Bearer"
	ExpiresIn            int64                 `json:"expires_in"` // Seconds until access token expires
	RefreshToken         string                `json:"refresh_token,omitempty"`
	Scope                string                `json:"scope,omitempty"`
	AuthorizationDetails []AuthorizationDetail `json:"authorization_details,omitempty"` // RFC 9396

	// IssuedTokenType identifies the type of token issued (RFC 8693 §2.2,
	// REQUIRED for token-exchange responses; absent for other grants).
	// Common values:
	//   urn:ietf:params:oauth:token-type:access_token
	//   urn:ietf:params:oauth:token-type:refresh_token
	//   urn:ietf:params:oauth:token-type:jwt
	IssuedTokenType string `json:"issued_token_type,omitempty"`
}

type TokenRequest struct {
	GrantType            string                `json:"grant_type"`                      // "password", "refresh_token", "client_credentials", "urn:ietf:params:oauth:grant-type:jwt-bearer", "urn:ietf:params:oauth:grant-type:token-exchange"
	Username             string                `json:"username,omitempty"`              // For password grant
	Password             string                `json:"password,omitempty"`              // For password grant
	RefreshToken         string                `json:"refresh_token,omitempty"`         // For refresh_token grant
	Scope                string                `json:"scope,omitempty"`                 // Requested scopes
	ClientID             string                `json:"client_id,omitempty"`             // Client identifier (for client_credentials, optional for others)
	ClientSecret         string                `json:"client_secret,omitempty"`         // Client secret (for client_credentials via client_secret_post)
	AuthorizationDetails []AuthorizationDetail `json:"authorization_details,omitempty"` // RFC 9396

	// Assertion is the signed JWT for grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
	// (RFC 7523 §2.1). The AS validates the assertion against a configured
	// trusted-issuer registry and issues an access token in exchange.
	Assertion string `json:"assertion,omitempty"`

	// ClientAssertionType + ClientAssertion authenticate the *client*
	// itself — distinct from Assertion (which authenticates the
	// resource owner via the jwt-bearer grant). Per RFC 7521 §4.2 +
	// RFC 7523 §2.2 + OIDC Core §9, ClientAssertionType MUST be
	// "urn:ietf:params:oauth:client-assertion-type:jwt-bearer" and
	// ClientAssertion is a signed JWT with iss == sub == client_id.
	// Used by the private_key_jwt and client_secret_jwt token-endpoint
	// authentication methods.
	ClientAssertionType string `json:"client_assertion_type,omitempty"`
	ClientAssertion     string `json:"client_assertion,omitempty"`

	// SubjectToken / SubjectTokenType / RequestedTokenType / Resource / Audience
	// support grant_type=urn:ietf:params:oauth:grant-type:token-exchange (RFC 8693).
	// SubjectToken is the credential representing the party on whose behalf
	// the request is made; SubjectTokenType identifies its kind (e.g.,
	// urn:ietf:params:oauth:token-type:jwt). RequestedTokenType (optional)
	// identifies the desired output token kind; defaults to access_token.
	SubjectToken       string `json:"subject_token,omitempty"`
	SubjectTokenType   string `json:"subject_token_type,omitempty"`
	RequestedTokenType string `json:"requested_token_type,omitempty"`
	Resource           string `json:"resource,omitempty"`
	Audience           string `json:"audience,omitempty"`
}

type TokenStore interface {
	CreateToken(userID, email string, tokenType TokenType, expiryDuration time.Duration) (*AuthToken, error)
	GetToken(token string) (*AuthToken, error)
	DeleteToken(token string) error
	DeleteUserTokens(userID string, tokenType TokenType) error
}

type TokenType string

type User interface {
	Id() string
	Profile() map[string]any
}

type UserStore interface {
	// CreateUser creates a new user with the given ID and profile
	CreateUser(userId string, isActive bool, profile map[string]any) (User, error)

	// GetUserById retrieves a user by their ID
	GetUserById(userId string) (User, error)

	// SaveUser creates or updates a user (upsert)
	SaveUser(user User) error
}

type UsernameStore interface {
	// ReserveUsername reserves a username for a user (creates username -> userID mapping)
	// Returns error if username is already taken
	ReserveUsername(username string, userID string) error

	// GetUserByUsername looks up a userID by username
	// Returns error if username not found
	GetUserByUsername(username string) (userID string, err error)

	// ReleaseUsername removes a username reservation
	ReleaseUsername(username string) error

	// ChangeUsername atomically changes a username (release old, reserve new)
	// Returns error if new username is already taken
	ChangeUsername(oldUsername, newUsername, userID string) error
}