identity

Documentation

Overview

Package identity provides identity management for CoreForge applications.

Index

• Variables
• func HashPassword(password string, params *Argon2idParams) (string, error)
• func NeedsRehash(encodedHash string, params *Argon2idParams) (bool, error)
• func VerifyPassword(password, encodedHash string) (bool, error)
• type Argon2idParams
  • func DefaultArgon2idParams() *Argon2idParams
• type CreateMembershipInput
• type CreateOAuthAccountInput
• type CreateOrganizationInput
• type CreateUserInput
• type MembershipInfo
• type MembershipService
• type OAuthAccountInfo
• type OAuthService
• type OrganizationInfo
• type OrganizationService
• type UpdateMembershipInput
• type UpdateOrganizationInput
• type UpdateUserInput
• type UserInfo
• type UserService

Variables

var (
	// ErrInvalidHash indicates the hash format is invalid.
	ErrInvalidHash = errors.New("invalid hash format")
	// ErrIncompatibleVersion indicates the Argon2 version is incompatible.
	ErrIncompatibleVersion = errors.New("incompatible argon2 version")
)

Functions

func HashPassword

func HashPassword(password string, params *Argon2idParams) (string, error)

HashPassword hashes a password using Argon2id with the given parameters. Returns the encoded hash in the format: $argon2id$v=19$m=65536,t=3,p=2$salt$hash

func NeedsRehash

func NeedsRehash(encodedHash string, params *Argon2idParams) (bool, error)

NeedsRehash checks if a hash needs to be regenerated with new parameters. This is useful when upgrading hash parameters over time.

func VerifyPassword

func VerifyPassword(password, encodedHash string) (bool, error)

VerifyPassword verifies a password against an encoded Argon2id hash. Returns true if the password matches, false otherwise.

Types

type Argon2idParams

type Argon2idParams struct {
	Memory      uint32 // Memory in KiB
	Iterations  uint32 // Number of iterations
	Parallelism uint8  // Degree of parallelism
	SaltLength  uint32 // Salt length in bytes
	KeyLength   uint32 // Hash length in bytes
}

Argon2idParams holds the parameters for Argon2id password hashing.

func DefaultArgon2idParams

func DefaultArgon2idParams() *Argon2idParams

DefaultArgon2idParams returns recommended Argon2id parameters. These follow OWASP recommendations for password hashing.

type CreateMembershipInput

type CreateMembershipInput struct {
	UserID         uuid.UUID
	OrganizationID uuid.UUID
	Role           string
	Permissions    []string
}

CreateMembershipInput contains fields for creating a membership.

type CreateOAuthAccountInput

type CreateOAuthAccountInput struct {
	UserID         uuid.UUID
	Provider       string
	ProviderUserID string
	AccessToken    *string `json:"-"` // Never serialized
	RefreshToken   *string `json:"-"` // Never serialized
}

CreateOAuthAccountInput contains fields for creating an OAuth account.

type CreateOrganizationInput

type CreateOrganizationInput struct {
	Name     string
	Slug     string
	LogoURL  *string
	Plan     string
	Settings map[string]any
}

CreateOrganizationInput contains fields for creating an organization.

type CreateUserInput

type CreateUserInput struct {
	Email           string
	Name            string
	AvatarURL       *string
	Password        *string `json:"-"` // Optional, hashed before storage (never serialized) //nolint:gosec // G117: field holds user-provided value, not a hardcoded secret
	IsPlatformAdmin bool
}

CreateUserInput contains fields for creating a new user.

type MembershipInfo

type MembershipInfo struct {
	ID             uuid.UUID
	UserID         uuid.UUID
	OrganizationID uuid.UUID
	Role           string
	Permissions    []string
}

MembershipInfo represents a user's membership in an organization.

type MembershipService

type MembershipService interface {
	// GetByID retrieves a membership by ID.
	GetByID(ctx context.Context, id uuid.UUID) (*MembershipInfo, error)

	// GetByUserAndOrg retrieves a user's membership in a specific organization.
	GetByUserAndOrg(ctx context.Context, userID, orgID uuid.UUID) (*MembershipInfo, error)

	// Create adds a user to an organization with a role.
	Create(ctx context.Context, input CreateMembershipInput) (*MembershipInfo, error)

	// Update updates a membership's role or permissions.
	Update(ctx context.Context, id uuid.UUID, input UpdateMembershipInput) (*MembershipInfo, error)

	// Delete removes a user from an organization.
	Delete(ctx context.Context, id uuid.UUID) error

	// ListForOrg lists all members of an organization.
	ListForOrg(ctx context.Context, orgID uuid.UUID) ([]*MembershipInfo, error)

	// ListForUser lists all memberships for a user.
	ListForUser(ctx context.Context, userID uuid.UUID) ([]*MembershipInfo, error)

	// HasRole checks if a user has a specific role in an organization.
	HasRole(ctx context.Context, userID, orgID uuid.UUID, role string) (bool, error)

	// HasAnyRole checks if a user has any of the specified roles.
	HasAnyRole(ctx context.Context, userID, orgID uuid.UUID, roles []string) (bool, error)
}

MembershipService defines operations for membership management.

type OAuthAccountInfo

type OAuthAccountInfo struct {
	ID             uuid.UUID
	UserID         uuid.UUID
	Provider       string
	ProviderUserID string
}

OAuthAccountInfo represents an OAuth provider connection.

type OAuthService

type OAuthService interface {
	// GetByProviderUser retrieves an OAuth account by provider and external user ID.
	GetByProviderUser(ctx context.Context, provider, providerUserID string) (*OAuthAccountInfo, error)

	// Create links an OAuth account to a user.
	Create(ctx context.Context, input CreateOAuthAccountInput) (*OAuthAccountInfo, error)

	// Delete removes an OAuth account link.
	Delete(ctx context.Context, id uuid.UUID) error

	// ListForUser lists all OAuth accounts for a user.
	ListForUser(ctx context.Context, userID uuid.UUID) ([]*OAuthAccountInfo, error)
}

OAuthService defines operations for OAuth account management.

type OrganizationInfo

type OrganizationInfo struct {
	ID       uuid.UUID
	Name     string
	Slug     string
	LogoURL  *string
	Plan     string
	Settings map[string]any
	Active   bool
}

OrganizationInfo represents basic organization information.

type OrganizationService

type OrganizationService interface {
	// GetByID retrieves an organization by ID.
	GetByID(ctx context.Context, id uuid.UUID) (*OrganizationInfo, error)

	// GetBySlug retrieves an organization by slug.
	GetBySlug(ctx context.Context, slug string) (*OrganizationInfo, error)

	// Create creates a new organization.
	Create(ctx context.Context, input CreateOrganizationInput) (*OrganizationInfo, error)

	// Update updates an existing organization.
	Update(ctx context.Context, id uuid.UUID, input UpdateOrganizationInput) (*OrganizationInfo, error)

	// Delete soft-deletes an organization.
	Delete(ctx context.Context, id uuid.UUID) error

	// ListForUser lists all organizations a user is a member of.
	ListForUser(ctx context.Context, userID uuid.UUID) ([]*OrganizationInfo, error)
}

OrganizationService defines operations for organization management.

type UpdateMembershipInput

type UpdateMembershipInput struct {
	Role        *string
	Permissions []string
}

UpdateMembershipInput contains fields for updating a membership.

type UpdateOrganizationInput

type UpdateOrganizationInput struct {
	Name     *string
	Slug     *string
	LogoURL  *string
	Plan     *string
	Settings map[string]any
	Active   *bool
}

UpdateOrganizationInput contains fields for updating an organization.

type UpdateUserInput

type UpdateUserInput struct {
	Email           *string
	Name            *string
	AvatarURL       *string
	IsPlatformAdmin *bool
	Active          *bool
}

UpdateUserInput contains fields for updating a user.

type UserInfo

type UserInfo struct {
	ID              uuid.UUID
	Email           string
	Name            string
	AvatarURL       *string
	IsPlatformAdmin bool
	Active          bool
}

UserInfo represents basic user information returned by services.

type UserService

type UserService interface {
	// GetByID retrieves a user by ID.
	GetByID(ctx context.Context, id uuid.UUID) (*UserInfo, error)

	// GetByEmail retrieves a user by email address.
	GetByEmail(ctx context.Context, email string) (*UserInfo, error)

	// Create creates a new user.
	Create(ctx context.Context, input CreateUserInput) (*UserInfo, error)

	// Update updates an existing user.
	Update(ctx context.Context, id uuid.UUID, input UpdateUserInput) (*UserInfo, error)

	// Delete soft-deletes a user by setting active=false.
	Delete(ctx context.Context, id uuid.UUID) error

	// SetPassword sets a user's password hash.
	SetPassword(ctx context.Context, id uuid.UUID, password string) error

	// VerifyPassword verifies a user's password.
	VerifyPassword(ctx context.Context, id uuid.UUID, password string) (bool, error)

	// UpdateLastLogin updates the user's last login timestamp.
	UpdateLastLogin(ctx context.Context, id uuid.UUID) error
}

UserService defines operations for user management.