scim

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

type Address struct {
	Formatted     string `json:"formatted,omitempty"`
	StreetAddress string `json:"streetAddress,omitempty"`
	Locality      string `json:"locality,omitempty"`
	Region        string `json:"region,omitempty"`
	PostalCode    string `json:"postalCode,omitempty"`
	Country       string `json:"country,omitempty"`
	Type          string `json:"type,omitempty"`
	Primary       bool   `json:"primary,omitempty"`
}

type AllowAllAuthorizationHook = DefaultAuthorizationHook

type AttributeFilter struct {
	// Attributes to include (if empty, include all)
	Attributes []string

	// Attributes to exclude
	ExcludedAttributes []string
}

type AuthenticationScheme struct {
	Type             string `json:"type"`
	Name             string `json:"name"`
	Description      string `json:"description"`
	SpecURI          string `json:"specUri,omitempty"`
	DocumentationURI string `json:"documentationUri,omitempty"`
	Primary          bool   `json:"primary,omitempty"`
}

type AuthorizationHook interface {
	// CanRead checks if the authenticated user can read the resource.
	CanRead(ctx context.Context, resourceType, resourceID string) error

	// CanCreate checks if the authenticated user can create resources of this type.
	CanCreate(ctx context.Context, resourceType string) error

	// CanUpdate checks if the authenticated user can update the resource.
	CanUpdate(ctx context.Context, resourceType, resourceID string) error

	// CanDelete checks if the authenticated user can delete the resource.
	CanDelete(ctx context.Context, resourceType, resourceID string) error
}

type BcryptHasher struct {
	// Cost is the bcrypt cost parameter. Default is bcrypt.DefaultCost (10).
	Cost int
}

type BulkInput struct {
	Body *BulkRequest `doc:"Bulk request containing multiple operations"`
}

type BulkOperation struct {
	Method  string `json:"method"`
	BulkID  string `json:"bulkId,omitempty"`
	Version string `json:"version,omitempty"`
	Path    string `json:"path"`
	Data    any    `json:"data,omitempty"`
}

type BulkOutput struct {
	Body *BulkResponse
}

type BulkRequest struct {
	Schemas      []string        `json:"schemas"`
	FailOnErrors int             `json:"failOnErrors,omitempty"`
	Operations   []BulkOperation `json:"Operations"`
}

type BulkResponse struct {
	Schemas    []string                `json:"schemas"`
	Operations []BulkResponseOperation `json:"Operations"`
}

type BulkResponseOperation struct {
	Method   string `json:"method"`
	BulkID   string `json:"bulkId,omitempty"`
	Version  string `json:"version,omitempty"`
	Location string `json:"location,omitempty"`
	Status   string `json:"status"`
	Response any    `json:"response,omitempty"`
}

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

type Config struct {
	// BaseURL is the base URL for SCIM resources (e.g., "https://example.com/scim/v2").
	BaseURL string

	// MaxResults is the maximum number of resources returned in a list response.
	MaxResults int

	// DefaultPageSize is the default number of resources per page.
	DefaultPageSize int

	// SupportFiltering indicates whether filtering is supported.
	SupportFiltering bool

	// SupportSorting indicates whether sorting is supported.
	SupportSorting bool

	// SupportPatch indicates whether PATCH operations are supported.
	SupportPatch bool

	// SupportBulk indicates whether bulk operations are supported.
	SupportBulk bool

	// BulkMaxOperations is the maximum number of operations in a bulk request.
	BulkMaxOperations int

	// BulkMaxPayloadSize is the maximum size of a bulk request in bytes.
	BulkMaxPayloadSize int

	// SupportChangePassword indicates whether password changes via SCIM are supported.
	SupportChangePassword bool

	// SupportETag indicates whether ETag-based optimistic locking is supported.
	SupportETag bool

	// AuthenticationSchemes defines the supported authentication methods.
	AuthenticationSchemes []AuthenticationScheme

	// DocumentationURI is an optional URI to SCIM documentation.
	DocumentationURI string
}

type CreateGroupInput struct {
	Body *Group `doc:"Group resource to create"`
}

type CreateGroupOutput struct {
	Body     *Group
	Location string `header:"Location" doc:"URI of the created resource"`
	ETag     string `header:"ETag" doc:"Entity tag for caching and conditional requests"`
}

type CreateUserInput struct {
	Body *User `doc:"User resource to create"`
}

type CreateUserOutput struct {
	Body     *User
	Location string `header:"Location" doc:"URI of the created resource"`
	ETag     string `header:"ETag" doc:"Entity tag for caching and conditional requests"`
}

type Credential struct {
	// Subject identifies the client (for example a token ID).
	Subject string
	// Scopes are the client's SCIM scopes (ScopeUsersRead, ...).
	Scopes []string
	// Scope is what the client may provision: its organization, or the
	// platform for an operator credential. Requests with an invalid scope
	// are refused.
	Scope Scope
}

type DeleteResourceInput struct {
	ID string `path:"id" doc:"Resource ID"`
}

type DenyAllAuthorizationHook struct{}

type EnterpriseUser struct {
	EmployeeNumber string      `json:"employeeNumber,omitempty"`
	CostCenter     string      `json:"costCenter,omitempty"`
	Organization   string      `json:"organization,omitempty"`
	Division       string      `json:"division,omitempty"`
	Department     string      `json:"department,omitempty"`
	Manager        *ManagerRef `json:"manager,omitempty"`
}

type Error struct {
	Schemas  []string `json:"schemas"`
	ScimType string   `json:"scimType,omitempty"`
	Detail   string   `json:"detail,omitempty"`
	Status   int      `json:"status"`
}

type GetGroupOutput struct {
	Body *Group
	ETag string `header:"ETag" doc:"Entity tag for caching and conditional requests"`
}

type GetResourceInput struct {
	ID                 string `path:"id" doc:"Resource ID"`
	Attributes         string `query:"attributes" doc:"Comma-separated list of attributes to return"`
	ExcludedAttributes string `query:"excludedAttributes" doc:"Comma-separated list of attributes to exclude"`
	IfNoneMatch        string `header:"If-None-Match" doc:"ETag for conditional request"`
}

type GetResourceTypeOutput struct {
	Body *schema.ResourceType
}

type GetSchemaOutput struct {
	Body *schema.Schema
}

type GetUserOutput struct {
	Body *User
	ETag string `header:"ETag" doc:"Entity tag for caching and conditional requests"`
}

type Group struct {
	Resource
	DisplayName string      `json:"displayName"`
	Members     []MemberRef `json:"members,omitempty"`
}

type GroupRef struct {
	Value   string `json:"value,omitempty"`
	Ref     string `json:"$ref,omitempty"`
	Display string `json:"display,omitempty"`
	Type    string `json:"type,omitempty"`
}

type ListGroupsOutput struct {
	Body *ListResponse
}

type ListOptions struct {
	Filter     string
	StartIndex int
	Count      int
	SortBy     string
	SortOrder  string
	Attributes []string
}

type ListResourceTypesOutput struct {
	Body *ListResponse
}

type ListResourcesInput struct {
	Filter             string `query:"filter" doc:"SCIM filter expression (RFC 7644)"`
	Attributes         string `query:"attributes" doc:"Comma-separated list of attributes to return"`
	ExcludedAttributes string `query:"excludedAttributes" doc:"Comma-separated list of attributes to exclude"`
	SortBy             string `query:"sortBy" doc:"Attribute path to sort by"`
	SortOrder          string `query:"sortOrder" enum:"ascending,descending" default:"ascending" doc:"Sort order"`
	StartIndex         int    `query:"startIndex" minimum:"1" default:"1" doc:"1-based index of first result"`
	Count              int    `query:"count" minimum:"0" doc:"Number of resources to return per page"`
}

type ListResponse struct {
	Schemas      []string `json:"schemas"`
	TotalResults int      `json:"totalResults"`
	StartIndex   int      `json:"startIndex,omitempty"`
	ItemsPerPage int      `json:"itemsPerPage,omitempty"`
	Resources    []any    `json:"Resources,omitempty"`
}

type ListSchemasOutput struct {
	Body *ListResponse
}

type ListUsersOutput struct {
	Body *ListResponse
}

type ManagerRef struct {
	Value       string `json:"value,omitempty"`
	Ref         string `json:"$ref,omitempty"`
	DisplayName string `json:"displayName,omitempty"`
}

type MeOutput struct {
	Body *User
	ETag string `header:"ETag" doc:"Entity tag for caching and conditional requests"`
}

type MePatchInput struct {
	IfMatch string        `header:"If-Match" doc:"ETag for conditional update"`
	Body    *PatchRequest `doc:"PATCH operations to apply"`
}

type MemberRef struct {
	Value   string `json:"value,omitempty"`
	Ref     string `json:"$ref,omitempty"`
	Display string `json:"display,omitempty"`
	Type    string `json:"type,omitempty"`
}

type Meta struct {
	ResourceType string     `json:"resourceType,omitempty"`
	Created      *time.Time `json:"created,omitempty"`
	LastModified *time.Time `json:"lastModified,omitempty"`
	Location     string     `json:"location,omitempty"`
	Version      string     `json:"version,omitempty"`
}

type MultiValue struct {
	Value   string `json:"value,omitempty"`
	Display string `json:"display,omitempty"`
	Type    string `json:"type,omitempty"`
	Primary bool   `json:"primary,omitempty"`
}

type Name struct {
	Formatted       string `json:"formatted,omitempty"`
	FamilyName      string `json:"familyName,omitempty"`
	GivenName       string `json:"givenName,omitempty"`
	MiddleName      string `json:"middleName,omitempty"`
	HonorificPrefix string `json:"honorificPrefix,omitempty"`
	HonorificSuffix string `json:"honorificSuffix,omitempty"`
}

type NoOpHasher struct{}

type Option func(*API)

type PasswordHasher interface {
	// Hash hashes a plain text password.
	Hash(password string) (string, error)

	// Verify compares a plain text password with a hashed password.
	Verify(password, hash string) error
}

type PatchOperation struct {
	Op    string `json:"op"`
	Path  string `json:"path,omitempty"`
	Value any    `json:"value,omitempty"`
}

type PatchRequest struct {
	Schemas    []string         `json:"schemas"`
	Operations []PatchOperation `json:"Operations"`
}

type PatchResourceInput struct {
	ID      string        `path:"id" doc:"Resource ID"`
	IfMatch string        `header:"If-Match" doc:"ETag for conditional update"`
	Body    *PatchRequest `doc:"PATCH operations to apply"`
}

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

type ProviderOption func(*Provider)

type RequestMetadata struct {
	// Filter is the SCIM filter expression.
	Filter string

	// StartIndex is the 1-based index of the first result (default 1).
	StartIndex int

	// Count is the number of resources to return per page.
	Count int

	// SortBy is the attribute to sort by.
	SortBy string

	// SortOrder is "ascending" or "descending".
	SortOrder string

	// Attributes specifies which attributes to return.
	Attributes []string

	// ExcludedAttributes specifies which attributes to exclude.
	ExcludedAttributes []string

	// IfMatch is the ETag value from If-Match header.
	IfMatch string

	// IfNoneMatch is the ETag value from If-None-Match header.
	IfNoneMatch string
}

type Resource struct {
	Schemas    []string `json:"schemas"`
	ID         string   `json:"id,omitempty"`
	ExternalID string   `json:"externalId,omitempty"`
	Meta       *Meta    `json:"meta,omitempty"`
}

type ResourceTypeNameInput struct {
	Name string `path:"name" doc:"Resource type name"`
}

type RoleBasedAuthorizationHook struct {
	// AdminRoles are roles that have full SCIM access.
	AdminRoles []string

	// ReadOnlyRoles are roles that have read-only SCIM access.
	ReadOnlyRoles []string

	// RoleExtractor extracts roles from context.
	// If nil, defaults to looking for "roles" in context values.
	RoleExtractor func(ctx context.Context) []string
}

type SchemaIDInput struct {
	ID string `path:"id" doc:"Schema URN"`
}

type Scope struct {
	// OrganizationID is the organization a tenant credential provisions.
	OrganizationID uuid.UUID
	// Platform marks a platform operator credential that provisions every
	// organization.
	Platform bool
}

type ScopedAuthorizationHook struct {
	// RequireScopes determines whether to enforce scope checking.
	// If false, all operations are allowed (useful for development/testing).
	RequireScopes bool
}

type SearchInput struct {
	Body *SearchRequest `doc:"Search request body"`
}

type SearchOutput struct {
	Body *ListResponse
}

type SearchRequest struct {
	Schemas            []string `json:"schemas,omitempty"`
	Attributes         []string `json:"attributes,omitempty"`
	ExcludedAttributes []string `json:"excludedAttributes,omitempty"`
	Filter             string   `json:"filter,omitempty"`
	SortBy             string   `json:"sortBy,omitempty"`
	SortOrder          string   `json:"sortOrder,omitempty"`
	StartIndex         int      `json:"startIndex,omitempty"`
	Count              int      `json:"count,omitempty"`
}

type Service interface {

	// GetUser retrieves a user by ID.
	GetUser(ctx context.Context, id string) (*User, error)

	// ListUsers lists users with optional filtering and pagination.
	ListUsers(ctx context.Context, opts ListOptions) (*ListResponse, error)

	// CreateUser creates a new user.
	CreateUser(ctx context.Context, user *User) (*User, error)

	// UpdateUser replaces a user (PUT semantics).
	UpdateUser(ctx context.Context, id string, user *User, etag string) (*User, error)

	// PatchUser applies partial modifications to a user.
	PatchUser(ctx context.Context, id string, patch *PatchRequest, etag string) (*User, error)

	// DeleteUser removes a user.
	DeleteUser(ctx context.Context, id string) error

	// GetGroup retrieves a group by ID.
	GetGroup(ctx context.Context, id string) (*Group, error)

	// ListGroups lists groups with optional filtering and pagination.
	ListGroups(ctx context.Context, opts ListOptions) (*ListResponse, error)

	// CreateGroup creates a new group.
	CreateGroup(ctx context.Context, group *Group) (*Group, error)

	// UpdateGroup replaces a group (PUT semantics).
	UpdateGroup(ctx context.Context, id string, group *Group, etag string) (*Group, error)

	// PatchGroup applies partial modifications to a group.
	PatchGroup(ctx context.Context, id string, patch *PatchRequest, etag string) (*Group, error)

	// DeleteGroup removes a group.
	DeleteGroup(ctx context.Context, id string) error

	// ProcessBulk processes a bulk request.
	ProcessBulk(ctx context.Context, req *BulkRequest) (*BulkResponse, error)

	// GetMe retrieves the current user based on context.
	GetMe(ctx context.Context) (*User, error)

	// PatchMe applies partial modifications to the current user.
	PatchMe(ctx context.Context, patch *PatchRequest, etag string) (*User, error)
}

type ServiceProviderConfigOutput struct {
	Body schema.ServiceProviderConfig
}

type Store interface {

	// GetUserByID retrieves a user by SCIM ID.
	GetUserByID(ctx context.Context, id string) (*User, error)

	// GetUserByUserName retrieves a user by userName (typically email).
	GetUserByUserName(ctx context.Context, userName string) (*User, error)

	// GetUserByExternalID retrieves a user by externalId.
	GetUserByExternalID(ctx context.Context, externalID string) (*User, error)

	// ListUsers lists users with filtering and pagination.
	// Returns resources, total count, and error.
	ListUsers(ctx context.Context, opts ListOptions) ([]*User, int, error)

	// CreateUser creates a new user.
	CreateUser(ctx context.Context, user *User) (*User, error)

	// UpdateUser updates an existing user.
	UpdateUser(ctx context.Context, id string, user *User) (*User, error)

	// DeleteUser deletes a user.
	DeleteUser(ctx context.Context, id string) error

	// GetGroupByID retrieves a group by SCIM ID.
	GetGroupByID(ctx context.Context, id string) (*Group, error)

	// GetGroupByDisplayName retrieves a group by displayName.
	GetGroupByDisplayName(ctx context.Context, displayName string) (*Group, error)

	// GetGroupByExternalID retrieves a group by externalId.
	GetGroupByExternalID(ctx context.Context, externalID string) (*Group, error)

	// ListGroups lists groups with filtering and pagination.
	// Returns resources, total count, and error.
	ListGroups(ctx context.Context, opts ListOptions) ([]*Group, int, error)

	// CreateGroup creates a new group.
	CreateGroup(ctx context.Context, group *Group) (*Group, error)

	// UpdateGroup updates an existing group.
	UpdateGroup(ctx context.Context, id string, group *Group) (*Group, error)

	// DeleteGroup deletes a group.
	DeleteGroup(ctx context.Context, id string) error

	// GetGroupsForUser returns all groups a user belongs to.
	GetGroupsForUser(ctx context.Context, userID string) ([]GroupRef, error)

	// GetMembersForGroup returns all members of a group.
	GetMembersForGroup(ctx context.Context, groupID string) ([]MemberRef, error)

	// AddMemberToGroup adds a user to a group.
	AddMemberToGroup(ctx context.Context, groupID, userID string) error

	// RemoveMemberFromGroup removes a user from a group.
	RemoveMemberFromGroup(ctx context.Context, groupID, userID string) error
}

type UpdateGroupInput struct {
	ID      string `path:"id" doc:"Group ID"`
	IfMatch string `header:"If-Match" doc:"ETag for conditional update"`
	Body    *Group `doc:"Group resource to replace"`
}

type UpdateGroupOutput struct {
	Body *Group
	ETag string `header:"ETag" doc:"Entity tag for caching and conditional requests"`
}

type UpdateUserInput struct {
	ID      string `path:"id" doc:"User ID"`
	IfMatch string `header:"If-Match" doc:"ETag for conditional update"`
	Body    *User  `doc:"User resource to replace"`
}

type UpdateUserOutput struct {
	Body *User
	ETag string `header:"ETag" doc:"Entity tag for caching and conditional requests"`
}

type User struct {
	Resource
	UserName          string       `json:"userName"`
	Name              *Name        `json:"name,omitempty"`
	DisplayName       string       `json:"displayName,omitempty"`
	NickName          string       `json:"nickName,omitempty"`
	ProfileURL        string       `json:"profileUrl,omitempty"`
	Title             string       `json:"title,omitempty"`
	UserType          string       `json:"userType,omitempty"`
	PreferredLanguage string       `json:"preferredLanguage,omitempty"`
	Locale            string       `json:"locale,omitempty"`
	Timezone          string       `json:"timezone,omitempty"`
	Active            *bool        `json:"active,omitempty"`
	Password          string       `json:"password,omitempty"` //nolint:gosec // G117: field holds SCIM password attribute, not hardcoded secret
	Emails            []MultiValue `json:"emails,omitempty"`
	PhoneNumbers      []MultiValue `json:"phoneNumbers,omitempty"`
	IMs               []MultiValue `json:"ims,omitempty"`
	Photos            []MultiValue `json:"photos,omitempty"`
	Addresses         []Address    `json:"addresses,omitempty"`
	Groups            []GroupRef   `json:"groups,omitempty"`
	Entitlements      []MultiValue `json:"entitlements,omitempty"`
	Roles             []MultiValue `json:"roles,omitempty"`
	X509Certificates  []MultiValue `json:"x509Certificates,omitempty"`

	// Enterprise User Extension
	EnterpriseUser *EnterpriseUser `json:"urn:ietf:params:scim:schemas:extension:enterprise:2.0:User,omitempty"`
}