admin

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

type AllSessionsRevokedEventPayload struct {
	CallerID   string `json:"caller_id"`
	CallerRole string `json:"caller_role"`
	UserID     string `json:"user_id"`
	plugin.ExtraContainer
}

type AuthorizeResult struct {
	Success bool   `json:"success"`
	Error   string `json:"error,omitempty"`
}

type BanUserParams struct {
	Caller       CallerContext  `json:"caller"`
	UserID       string         `json:"user_id"`
	BanReason    string         `json:"ban_reason,omitempty"`
	BanExpiresIn *time.Duration `json:"ban_expires_in,omitempty"`
}

type CallerContext struct {
	UserID string `json:"user_id"`
	Role   string `json:"role"`
	plugin.ExtraContainer
}

type CheckPermissionParams struct {
	Caller      CallerContext `json:"caller"`
	Permissions Permissions   `json:"permissions"`
	Connector   Connector     `json:"connector,omitempty"`
}

type Config struct {
	// DefaultRole is the default role assigned to users if none is specified (default: "user").
	DefaultRole string

	// AdminRoles is a list of roles considered to hold administrator privileges (default: ["admin"]).
	AdminRoles []string

	// AdminUserIDs is an explicit list of user IDs granted full administrative bypass access.
	AdminUserIDs []string

	// DefaultBanReason is the standard reason applied when suspending an account without a reason (default: "No reason provided").
	DefaultBanReason string

	// DefaultBanExpiresIn defines the default expiration duration for suspensions (default: 0, meaning permanent).
	DefaultBanExpiresIn time.Duration

	// ImpersonationSessionDuration defines the validity period for temporary impersonated sessions (default: 1 hour).
	ImpersonationSessionDuration time.Duration

	// BannedUserMessage is the user-facing message returned when a banned user attempts authentication.
	BannedUserMessage string

	// AllowImpersonatingAdmins specifies whether administrators can impersonate other administrators without explicit statement permission (default: false).
	AllowImpersonatingAdmins bool

	// MinPasswordLength is the minimum password length enforced by SetUserPassword (default: 8).
	MinPasswordLength int

	// MaxPasswordLength is the maximum allowed password length for SetUserPassword (default: 128).
	MaxPasswordLength int

	// Roles defines the complete dictionary of custom and built-in roles and statement permissions.
	Roles map[string]Role
}

type Connector string

type CreateUserParams struct {
	Caller   CallerContext `json:"caller"`
	Name     string        `json:"name"`
	Email    string        `json:"email"`
	Password string        `json:"password,omitempty"`
	Role     string        `json:"role,omitempty"`
	plugin.ExtraContainer
}

type GetUserParams struct {
	Caller CallerContext `json:"caller"`
	UserID string        `json:"user_id"`
}

type HasPermissionInput struct {
	UserID       string
	Role         string
	AdminUserIDs []string
	RolesConfig  map[string]Role
	DefaultRole  string
	Permissions  Permissions
	Connector    Connector
}

type ImpersonateResult struct {
	Session           *entity.Session `json:"session"`
	User              *entity.User    `json:"user"`
	AdminSessionToken string          `json:"admin_session_token,omitempty"`
}

type ImpersonateUserParams struct {
	Caller    CallerContext  `json:"caller"`
	UserID    string         `json:"user_id"`
	IPAddress string         `json:"ip_address,omitempty"`
	UserAgent string         `json:"user_agent,omitempty"`
	Duration  *time.Duration `json:"duration,omitempty"`
}

type ImpersonationStoppedEventPayload struct {
	AdminUserID  string `json:"admin_user_id"`
	TargetUserID string `json:"target_user_id"`
	SessionToken string `json:"session_token"`
	plugin.ExtraContainer
}

type ListUserSessionsParams struct {
	Caller CallerContext `json:"caller"`
	UserID string        `json:"user_id"`
}

type ListUsersFilter struct {
	SearchValue    string `json:"search_value,omitempty"`    // Search query term
	SearchField    string `json:"search_field,omitempty"`    // Target field to search ("email", "name", etc.)
	SearchOperator string `json:"search_operator,omitempty"` // "contains", "starts_with", "ends_with", "exact"
	FilterField    string `json:"filter_field,omitempty"`    // Attribute field to filter by (e.g. "role", "banned")
	FilterOperator string `json:"filter_operator,omitempty"` // "eq", "ne", "in", etc.
	FilterValue    any    `json:"filter_value,omitempty"`    // Target value for the filter condition
	SortBy         string `json:"sort_by,omitempty"`         // Field to sort by ("created_at", "email", "name")
	SortDirection  string `json:"sort_direction,omitempty"`  // "asc" or "desc"
	Limit          int    `json:"limit,omitempty"`           // Number of records per page
	Offset         int    `json:"offset,omitempty"`          // Pagination offset
}

type ListUsersParams struct {
	Caller CallerContext   `json:"caller"`
	Filter ListUsersFilter `json:"filter"`
}

type ListUsersResult struct {
	Users  []*entity.User `json:"users"`
	Total  int64          `json:"total"`
	Limit  int            `json:"limit"`
	Offset int            `json:"offset"`
}

type Option func(*Config)

type Permissions map[string][]string

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

type RemoveUserParams struct {
	Caller CallerContext `json:"caller"`
	UserID string        `json:"user_id"`
}

type Repository interface {
	// GetUserByID retrieves a user entity matching the provided unique identifier.
	//
	// Function:
	//   Used during admin user detail lookup, role updates, and account ban/unban checks.
	//
	// Storage:
	//   Database (GORM / SQL) - Relational user entity query by primary key.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - id: Unique primary key identifier of the user.
	//
	// Returns:
	//   - *entity.User: Matching user profile.
	//   - error: ErrUserNotFound if missing.
	//
	// Example SQL:
	//   SELECT id, name, email, email_verified, two_factor_enabled, role, banned, ban_reason, ban_expires, created_at, updated_at FROM users WHERE id = $1 LIMIT 1;
	GetUserByID(ctx context.Context, id string) (*entity.User, error)

	// GetUserByEmail retrieves a user entity matching the provided normalized email address.
	//
	// Function:
	//   Used in user search or when checking duplicate email existence during admin user creation.
	//
	// Storage:
	//   Database (GORM / SQL) - Query user by normalized email.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - email: Normalized email address string.
	//
	// Returns:
	//   - *entity.User: Matching user profile.
	//   - error: ErrUserNotFound if missing.
	//
	// Example SQL:
	//   SELECT id, name, email, email_verified, two_factor_enabled, role, banned, ban_reason, ban_expires, created_at, updated_at FROM users WHERE LOWER(email) = LOWER($1) LIMIT 1;
	GetUserByEmail(ctx context.Context, email string) (*entity.User, error)

	// CreateUser persists a newly created user entity in storage.
	//
	// Function:
	//   Called by administrators creating accounts directly via the administrative portal.
	//
	// Storage:
	//   Database (GORM / SQL) - User domain entity creation.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - params: Parameters for creating a user.
	//
	// Returns:
	//   - *entity.User: Newly created user record.
	//   - error: ErrUserAlreadyExists on email conflict.
	//
	// Example SQL:
	//   INSERT INTO users (id, name, email, role, banned, ban_reason, ban_expires, email_verified, two_factor_enabled, created_at, updated_at) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11);
	CreateUser(ctx context.Context, params *dto.CreateUserParams) (*entity.User, error)

	// UpdateUser updates modified fields of an existing user profile in storage.
	//
	// Function:
	//   Used when setting roles, banning/unbanning users, or updating profile attributes.
	//
	// Storage:
	//   Database (GORM / SQL) - Relational user table update.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - user: Modified User domain entity.
	//
	// Returns:
	//   - error: Nil on success.
	//
	// Example SQL:
	//   UPDATE users SET name = $1, email = $2, role = $3, banned = $4, ban_reason = $5, ban_expires = $6, email_verified = $7, updated_at = $8 WHERE id = $9;
	UpdateUser(ctx context.Context, user *entity.User) error

	// DeleteUser removes a user record and their related accounts and credentials from storage.
	//
	// Function:
	//   Called when an administrator permanently deletes a user account.
	//
	// Storage:
	//   Database (GORM / SQL) - Relational user record deletion.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - id: Target user primary key ID.
	//
	// Returns:
	//   - error: Nil on success.
	//
	// Example SQL:
	//   DELETE FROM users WHERE id = $1;
	DeleteUser(ctx context.Context, id string) error

	// ListUsers returns a paginated and filtered list of user records matching search filter criteria.
	//
	// Function:
	//   Used by admin dashboard user management tables.
	//
	// Storage:
	//   Database (GORM / SQL) - Paginated relational query with search and filters.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - filter: ListUsersFilter defining search terms, filters, sorting, and pagination parameters.
	//
	// Returns:
	//   - []*entity.User: Slice of matching user entities.
	//   - int64: Total total matching record count.
	//   - error: Nil on success.
	//
	// Example SQL:
	//   SELECT id, name, email, role, banned, ban_reason, ban_expires, email_verified, created_at, updated_at FROM users WHERE email ILIKE '%' || $1 || '%' ORDER BY created_at DESC LIMIT $2 OFFSET $3;
	ListUsers(ctx context.Context, filter ListUsersFilter) ([]*entity.User, int64, error)

	// LinkCredentialAccount links or updates provider credential password hashes for a user.
	//
	// Function:
	//   Called when an admin resets or assigns a new password to a user account.
	//
	// Storage:
	//   Database (GORM / SQL) - Credential account update or insert.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - userID: Target user ID.
	//   - passwordHash: New hashed password.
	//
	// Returns:
	//   - error: Nil on success.
	//
	// Example SQL:
	//   INSERT INTO accounts (id, user_id, provider_id, password_hash, created_at, updated_at) VALUES ($1, $2, 'credential', $3, $4, $5) ON CONFLICT (user_id, provider_id) DO UPDATE SET password_hash = $3, updated_at = $5;
	LinkCredentialAccount(ctx context.Context, userID, passwordHash string) error

	// CreateSession persists a new session entity (supporting impersonation tracking).
	//
	// Function:
	//   Called during impersonation flows when an administrator impersonates a target user.
	//
	// Storage:
	//   Database (GORM / SQL) - Active session creation.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - session: DTO for session creation.
	//
	// Returns:
	//   - *entity.Session: Active session entity.
	//   - error: Nil on success.
	//
	// Example SQL:
	//   INSERT INTO sessions (id, user_id, token, expires_at, ip_address, user_agent, impersonated_by, created_at, updated_at) VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9);
	CreateSession(ctx context.Context, session *dto.CreateSessionParams) (*entity.Session, error)

	// GetSessionByToken retrieves an active session by its raw token string.
	//
	// Function:
	//   Used during impersonation verification and stop-impersonation flows.
	//
	// Storage:
	//   Both (Cache-Aside Strategy) - Cached in Redis (`session:<token>`) for fast session validation.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - token: Session token string.
	//
	// Returns:
	//   - *entity.Session: Session entity.
	//   - error: ErrAdminSessionNotFound if missing.
	//
	// Example SQL:
	//   SELECT id, user_id, token, expires_at, ip_address, user_agent, impersonated_by, created_at, updated_at FROM sessions WHERE token = $1 LIMIT 1;
	//
	// Example Cache (Redis):
	//   val, err := rdb.Get(ctx, "session:" + token).Bytes()
	GetSessionByToken(ctx context.Context, token string) (*entity.Session, error)

	// ListSessionsByUserID lists all active sessions belonging to the specified user.
	//
	// Function:
	//   Used in admin user session management panels.
	//
	// Storage:
	//   Database (GORM / SQL) - Relational user session list query.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - userID: Target user ID.
	//
	// Returns:
	//   - []*entity.Session: List of active sessions.
	//   - error: Nil on success.
	//
	// Example SQL:
	//   SELECT id, user_id, token, expires_at, ip_address, user_agent, impersonated_by, created_at, updated_at FROM sessions WHERE user_id = $1;
	ListSessionsByUserID(ctx context.Context, userID string) ([]*entity.Session, error)

	// DeleteSession deletes a specific session by token.
	//
	// Function:
	//   Called when an admin revokes a single session.
	//
	// Storage:
	//   Database (GORM / SQL) - Session record deletion.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - token: Target session token string.
	//
	// Returns:
	//   - error: Nil on success.
	//
	// Example SQL:
	//   DELETE FROM sessions WHERE token = $1;
	DeleteSession(ctx context.Context, token string) error

	// DeleteSessionsByUserID deletes all active sessions belonging to a user.
	//
	// Function:
	//   Used during account bans, security locks, and global session revocation.
	//
	// Storage:
	//   Database (GORM / SQL) - Bulk user session deletion.
	//
	// Arguments:
	//   - ctx: Request cancellation context.
	//   - userID: Target user ID.
	//
	// Returns:
	//   - error: Nil on success.
	//
	// Example SQL:
	//   DELETE FROM sessions WHERE user_id = $1;
	DeleteSessionsByUserID(ctx context.Context, userID string) error
}

type RevokeUserSessionParams struct {
	Caller       CallerContext `json:"caller"`
	SessionToken string        `json:"session_token"`
}

type RevokeUserSessionsParams struct {
	Caller CallerContext `json:"caller"`
	UserID string        `json:"user_id"`
}

type Role struct {
	Name       string     `json:"name"`
	Statements Statements `json:"statements"`
}

type SessionRevokedEventPayload struct {
	CallerID     string `json:"caller_id"`
	CallerRole   string `json:"caller_role"`
	SessionToken string `json:"session_token"`
	plugin.ExtraContainer
}

type SetRoleParams struct {
	Caller CallerContext `json:"caller"`
	UserID string        `json:"user_id"`
	Role   string        `json:"role"`
}

type SetUserPasswordParams struct {
	Caller      CallerContext `json:"caller"`
	UserID      string        `json:"user_id"`
	NewPassword string        `json:"new_password"`
}

type Statements map[string][]string

type StopImpersonatingParams struct {
	ImpersonatedSessionToken string `json:"impersonated_session_token"`
	AdminSessionToken        string `json:"admin_session_token,omitempty"`
}

type StopImpersonatingResult struct {
	AdminSession *entity.Session `json:"admin_session,omitempty"`
	AdminUser    *entity.User    `json:"admin_user"`
}

type UnbanUserParams struct {
	Caller CallerContext `json:"caller"`
	UserID string        `json:"user_id"`
}

type UpdateUserParams struct {
	Caller        CallerContext `json:"caller"`
	UserID        string        `json:"user_id"`
	Name          *string       `json:"name,omitempty"`
	Email         *string       `json:"email,omitempty"`
	EmailVerified *bool         `json:"email_verified,omitempty"`
	Role          *string       `json:"role,omitempty"`
	Banned        *bool         `json:"banned,omitempty"`
	BanReason     *string       `json:"ban_reason,omitempty"`
	BanExpires    *time.Time    `json:"ban_expires,omitempty"`
	plugin.ExtraContainer
}

type UserBannedEventPayload struct {
	CallerID   string       `json:"caller_id"`
	CallerRole string       `json:"caller_role"`
	UserID     string       `json:"user_id"`
	BanReason  string       `json:"ban_reason"`
	BanExpires *time.Time   `json:"ban_expires,omitempty"`
	User       *entity.User `json:"user"`
	plugin.ExtraContainer
}

type UserCreatedEventPayload struct {
	CallerID   string       `json:"caller_id"`
	CallerRole string       `json:"caller_role"`
	User       *entity.User `json:"user"`
	plugin.ExtraContainer
}

type UserDeletedEventPayload struct {
	CallerID   string `json:"caller_id"`
	CallerRole string `json:"caller_role"`
	UserID     string `json:"user_id"`
	plugin.ExtraContainer
}

type UserImpersonatedEventPayload struct {
	CallerID     string          `json:"caller_id"`
	CallerRole   string          `json:"caller_role"`
	TargetUserID string          `json:"target_user_id"`
	Session      *entity.Session `json:"session"`
	plugin.ExtraContainer
}

type UserPasswordChangedEventPayload struct {
	CallerID   string `json:"caller_id"`
	CallerRole string `json:"caller_role"`
	UserID     string `json:"user_id"`
	plugin.ExtraContainer
}

type UserRoleChangedEventPayload struct {
	CallerID   string       `json:"caller_id"`
	CallerRole string       `json:"caller_role"`
	UserID     string       `json:"user_id"`
	OldRole    string       `json:"old_role"`
	NewRole    string       `json:"new_role"`
	User       *entity.User `json:"user"`
	plugin.ExtraContainer
}

type UserUnbannedEventPayload struct {
	CallerID   string       `json:"caller_id"`
	CallerRole string       `json:"caller_role"`
	UserID     string       `json:"user_id"`
	User       *entity.User `json:"user"`
	plugin.ExtraContainer
}

type UserUpdatedEventPayload struct {
	CallerID   string       `json:"caller_id"`
	CallerRole string       `json:"caller_role"`
	User       *entity.User `json:"user"`
	plugin.ExtraContainer
}