Why Go
- Case Studies
  
  Common problems companies solve with Go
- Use Cases
  
  Stories about how and why companies use Go
- Security
  
  How Go can help keep you secure by default
Learn
Docs
- Effective Go
  
  Tips for writing clear, performant, and idiomatic Go code
- Go User Manual
  
  A complete introduction to building software with Go
- Standard library
  
  Reference documentation for Go's standard library
- Release Notes
  
  Learn what's new in each Go release
- API
  
  Reference documentation for the pkg.go.dev API
Packages
Community
- Recorded Talks
  
  Videos from prior events
- Meetups
  
  Meet other local Go developers
- Conferences
  
  Learn and network with Go developers from around the world
- Go blog
  
  The Go project's official blog.
- Go project
  
  Get help and stay informed from Go
- Get connected

ulinzi

package module

Go to main page

Versions in this module

v0

v0.4.0

Jul 7, 2026

Changes in this version

+ var ErrExternalLoginNotFound = errors.New("ulinzi: external login not found")

+ var ErrExternalLoginUnavailable = errors.New("ulinzi: external-login store not configured (use WithExternalLogins)")

+ var ErrIdpProviderRequired = errors.New("ulinzi: idp provider is required")

+ var ErrPasskeyNotFound = errors.New("ulinzi: passkey not found")

+ var ErrWebAuthnChallengeMissing = errors.New("ulinzi: webauthn challenge missing or expired")

+ var ErrWebAuthnCredentialExists = errors.New("ulinzi: passkey credential already registered")

+ type AESGCMIdpSecretProtector struct

+ func NewAESGCMIdpSecretProtector(key []byte) (*AESGCMIdpSecretProtector, error)

+ func (p *AESGCMIdpSecretProtector) ProtectClientSecret(provider, plaintext string) (string, error)

+ func (p *AESGCMIdpSecretProtector) ProtectServiceUserToken(provider, plaintext string) (string, error)

+ func (p *AESGCMIdpSecretProtector) ProtectZitadelClientID(plaintext string) (string, error)

+ func (p *AESGCMIdpSecretProtector) TryUnprotectClientSecret(provider, ciphertext string) (string, bool)

+ func (p *AESGCMIdpSecretProtector) TryUnprotectServiceUserToken(provider, ciphertext string) (string, bool)

+ func (p *AESGCMIdpSecretProtector) TryUnprotectZitadelClientID(ciphertext string) (string, bool)

+ type AppUserMfa = domain.AppUserMfa

+ type AppUserPasskey = domain.AppUserPasskey

+ type ChallengeStore interface

+ Save func(ctx context.Context, userID uuid.UUID, purpose string, data []byte, ...) error

+ Take func(ctx context.Context, userID uuid.UUID, purpose string) (data []byte, ok bool, err error)

+ type ExternalLoginStore interface

+ GetUserIDByExternalLogin func(ctx context.Context, provider IdentityProvider, providerKey string) (userID uuid.UUID, ok bool, err error)

+ LinkExternalLogin func(ctx context.Context, login UserLogin) error

+ ListExternalLogins func(ctx context.Context, userID uuid.UUID) ([]UserLogin, error)

+ UnlinkExternalLogin func(ctx context.Context, provider IdentityProvider, providerKey string) (removed bool, err error)

+ type IdpConfigInfo = domain.IdpConfigInfo

+ type IdpConfigService struct

+ func NewIdpConfigService(store IdpConfigStore, protector IdpSecretProtector) *IdpConfigService

+ func (s *IdpConfigService) DecryptedClientSecret(ctx context.Context, provider string) (secret string, ok bool, err error)

+ func (s *IdpConfigService) DecryptedServiceUserToken(ctx context.Context, provider string) (token string, ok bool, err error)

+ func (s *IdpConfigService) DecryptedZitadelClientID(ctx context.Context) (clientID string, ok bool, err error)

+ func (s *IdpConfigService) Get(ctx context.Context, provider string) (*IdpConfigInfo, error)

+ func (s *IdpConfigService) List(ctx context.Context) ([]IdpConfigInfo, error)

+ func (s *IdpConfigService) RawClientID(ctx context.Context, provider string) (*string, error)

+ func (s *IdpConfigService) Upsert(ctx context.Context, provider string, in UpsertIdpConfigInput, ...) (*IdpConfigInfo, error)

+ type IdpConfigStore interface

+ GetIdpConfigByProvider func(ctx context.Context, provider string) (*IdpConfiguration, error)

+ ListIdpConfigs func(ctx context.Context) ([]IdpConfiguration, error)

+ UpsertIdpConfig func(ctx context.Context, c *IdpConfiguration) error

+ type IdpConfiguration = domain.IdpConfiguration

+ type IdpSecretProtector interface

+ ProtectClientSecret func(provider, plaintext string) (string, error)

+ ProtectServiceUserToken func(provider, plaintext string) (string, error)

+ ProtectZitadelClientID func(plaintext string) (string, error)

+ TryUnprotectClientSecret func(provider, ciphertext string) (plaintext string, ok bool)

+ TryUnprotectServiceUserToken func(provider, ciphertext string) (plaintext string, ok bool)

+ TryUnprotectZitadelClientID func(ciphertext string) (plaintext string, ok bool)

+ type InMemoryChallengeStore struct

+ func NewInMemoryChallengeStore() *InMemoryChallengeStore

+ func (c *InMemoryChallengeStore) Save(_ context.Context, userID uuid.UUID, purpose string, data []byte, ...) error

+ func (c *InMemoryChallengeStore) Take(_ context.Context, userID uuid.UUID, purpose string) ([]byte, bool, error)

+ type NoopIdpSecretProtector struct

+ func (NoopIdpSecretProtector) ProtectClientSecret(_, plaintext string) (string, error)

+ func (NoopIdpSecretProtector) ProtectServiceUserToken(_, plaintext string) (string, error)

+ func (NoopIdpSecretProtector) ProtectZitadelClientID(plaintext string) (string, error)

+ func (NoopIdpSecretProtector) TryUnprotectClientSecret(_, ciphertext string) (string, bool)

+ func (NoopIdpSecretProtector) TryUnprotectServiceUserToken(_, ciphertext string) (string, bool)

+ func (NoopIdpSecretProtector) TryUnprotectZitadelClientID(ciphertext string) (string, bool)

type Option

+ func WithExternalLogins(store ExternalLoginStore) Option

+ type PasskeyStore interface

+ AddPasskey func(ctx context.Context, p *AppUserPasskey) error

+ GetPasskeyByCredentialID func(ctx context.Context, credentialID string) (*AppUserPasskey, error)

+ ListPasskeysByUserID func(ctx context.Context, userID uuid.UUID) ([]AppUserPasskey, error)

+ RemovePasskeyByUserAndCredentialID func(ctx context.Context, userID uuid.UUID, credentialID string) (removed bool, err error)

+ UpdatePasskeySignCount func(ctx context.Context, id uuid.UUID, signCount uint32) error

type Service

+ func (s *Service) LinkExternalLogin(ctx context.Context, provider IdentityProvider, providerKey string, ...) error

+ func (s *Service) ListExternalLogins(ctx context.Context, userID uuid.UUID) ([]UserLogin, error)

+ func (s *Service) ResolveExternalLogin(ctx context.Context, provider IdentityProvider, providerKey string) (*User, error)

+ func (s *Service) UnlinkExternalLogin(ctx context.Context, provider IdentityProvider, providerKey string) (bool, error)

+ type UpsertIdpConfigInput struct

+ ClientID *string

+ ClientSecret *string

+ DiscoveryURL *string

+ DisplayName *string

+ MetadataJSON *string

+ ServiceUserToken *string

+ TenantID *string

+ type UserLogin = domain.UserLogin

+ type WebAuthnConfig struct

+ ChallengeTTL time.Duration

+ RPDisplayName string

+ RPID string

+ RPOrigins []string

type WebAuthnService

+ func NewWebAuthnService(store PasskeyStore, sessions ChallengeStore, cfg WebAuthnConfig) (*WebAuthnService, error)

+ func (s *WebAuthnService) ListPasskeys(ctx context.Context, userID uuid.UUID) ([]AppUserPasskey, error)

+ func (s *WebAuthnService) RemovePasskey(ctx context.Context, userID uuid.UUID, credentialID string) (bool, error)

v0.3.0

Jul 7, 2026

Changes in this version

+ const AuditAccountLocked

+ const AuditEmailChanged

+ const AuditEmailConfirmed

+ const AuditLoginFailed

+ const AuditLoginSucceeded

+ const AuditLogout

+ const AuditMfaDisabled

+ const AuditMfaEnrolled

+ const AuditMfaVerified

+ const AuditPasswordChanged

+ const AuditPasswordReset

+ const AuditPasswordResetRequested

+ const AuditSessionsInvalidated

+ const AuditStatusFailure

+ const AuditStatusSuccess

+ const AuditUserCreated

+ const Version

+ var ErrAccountLocked = errors.New("ulinzi: account locked out")

+ var ErrAuthUnavailable = errors.New("ulinzi: auth store not configured (use New(store, cfg, WithAuthStore(...)))")

+ var ErrEmailTaken = errors.New("ulinzi: email already registered")

+ var ErrInvalidCredentials = errors.New("ulinzi: invalid credentials")

+ var ErrLockoutUnavailable = errors.New("ulinzi: lockout not configured (use WithLockout)")

+ var ErrMFARequired = errors.New("ulinzi: mfa code required")

+ var ErrMfaNotEnrolled = errors.New("ulinzi: mfa not enrolled")

+ var ErrNoPrincipal = errors.New("ulinzi: no principal in context")

+ var ErrNotImplemented = errors.New("ulinzi: not implemented (wave-2)")

+ var ErrSecretProtection = errors.New("ulinzi: mfa secret could not be decrypted")

+ var ErrSessionExpired = errors.New("ulinzi: session expired")

+ var ErrSessionNotFound = errors.New("ulinzi: session not found")

+ var ErrSessionRevoked = errors.New("ulinzi: session revoked")

+ var ErrSessionStampChanged = errors.New("ulinzi: session invalidated (security stamp changed)")

+ var ErrUserInactive = errors.New("ulinzi: user inactive")

+ func ContextWithPrincipal(ctx context.Context, p *Principal) context.Context

+ func ValidatePassword(ctx context.Context, password string, policy PasswordPolicy, hibp HibpService) []string

+ type AESGCMSecretProtector struct

+ func NewAESGCMSecretProtector(key []byte) (*AESGCMSecretProtector, error)

+ func (p *AESGCMSecretProtector) Protect(secret string) (string, error)

+ func (p *AESGCMSecretProtector) Unprotect(ciphertext string) (string, error)

+ func (p *AESGCMSecretProtector) UnprotectOrLegacy(value string) (string, bool, error)

+ type ActiveLockout struct

+ ExpiresAt *time.Time

+ LockoutCount int

+ func (a *ActiveLockout) IsPermanent() bool

+ type AuditEvent struct

+ Details string

+ EventType string

+ IPAddress string

+ OccurredAt time.Time

+ SessionID string

+ Status string

+ UserAgent string

+ UserID string

+ type AuditService struct

+ func NewAuditService(store AuditStore) *AuditService

+ func (s *AuditService) Record(ctx context.Context, e AuditEvent) error

+ func (s *AuditService) VerifyChain(ctx context.Context) (ok bool, brokenSeq int64, err error)

+ type AuditStore interface

+ AppendChained func(ctx context.Context, e AuditEvent, hashFn func(prevHash string) string) error

+ VerifyAuditChain func(ctx context.Context, hashFn func(prevHash string, e AuditEvent) string) (ok bool, brokenSeq int64, err error)

+ type AuthStore interface

+ CreateSession func(ctx context.Context, rec *SessionRecord, loginCompletedAt time.Time) error

+ CreateUser func(ctx context.Context, id uuid.UUID, ...) error

+ GetUserAuthByEmail func(ctx context.Context, normalizedEmail string) (*UserAuth, error)

+ RevokeSession func(ctx context.Context, sessionID, reason string, at time.Time) error

+ type Config struct

+ CookieName string

+ DefaultSessionPolicy SessionPolicy

+ LastActivityThrottle time.Duration

+ PasswordHashCost int

+ func DefaultConfig() Config

+ type DefaultHibpService struct

+ func NewHibpService() *DefaultHibpService

+ func (h *DefaultHibpService) IsCompromised(ctx context.Context, password string) (bool, error)

+ type EnrollResult struct

+ ProvisioningURI string

+ RecoveryCodes []string

+ Secret string

+ type HibpService interface

+ IsCompromised func(ctx context.Context, password string) (bool, error)

+ type IPWhitelistService interface

+ IsAllowed func(ctx context.Context, ip string) (bool, error)

+ type IdentityProvider string

+ const ProviderEntra

+ const ProviderGoogle

+ const ProviderLocal

+ const ProviderZitadel

+ type LockoutPolicy struct

+ IsActive bool

+ LockoutDuration time.Duration

+ MaxFailedAttempts int

+ MaxLockoutDuration time.Duration

+ ObservationWindow time.Duration

+ PermanentThreshold *int

+ ProgressiveEnabled bool

+ ProgressiveMultiplier float64

+ func DefaultLockoutPolicy() LockoutPolicy

+ type LockoutService struct

+ func NewLockoutService(store LockoutStore) *LockoutService

+ func (s *LockoutService) CheckLockout(ctx context.Context, email string) (locked bool, info *ActiveLockout, err error)

+ func (s *LockoutService) RecordFailure(ctx context.Context, email string, userID *string, reason, ip, ua string) (bool, error)

+ func (s *LockoutService) RecordSuccess(ctx context.Context, email string, userID *string, ip, ua string) error

+ func (s *LockoutService) Unlock(ctx context.Context, email, reason string, byUserID *string) error

+ type LockoutStore interface

+ CountRecentFailures func(ctx context.Context, email string, since time.Time) (int, error)

+ GetActiveLockout func(ctx context.Context, email string) (*ActiveLockout, error)

+ GetLockoutPolicy func(ctx context.Context) (*LockoutPolicy, error)

+ InsertLockout func(ctx context.Context, email string, userID *string, ...) error

+ RecordLoginAttempt func(ctx context.Context, a LoginAttempt) error

+ UnlockAccount func(ctx context.Context, email, reason string, byUserID *string, at time.Time) error

+ type LoginAttempt struct

+ AttemptType string

+ Email string

+ FailureReason string

+ IPAddress string

+ IdentityProvider string

+ Success bool

+ UserAgent string

+ UserID *string

+ type LoginInput struct

+ Email string

+ IPAddress string

+ Password string

+ TOTPCode string

+ UserAgent string

+ type LoginResult struct

+ Principal *Principal

+ SessionID string

+ type Mfa struct

+ AuthenticatorKey string

+ ExternalUserID uuid.UUID

+ RecoveryCodeHashes []string

+ TwoFactorEnabled bool

+ UpdatedAt time.Time

+ type MfaMethod interface

+ IsEnrolled func(ctx context.Context, userID uuid.UUID) (bool, error)

+ Name func() string

+ Verify func(ctx context.Context, userID uuid.UUID, code string) (bool, error)

+ type MfaSecretProtector interface

+ Protect func(base32Secret string) (string, error)

+ Unprotect func(ciphertext string) (string, error)

+ UnprotectOrLegacy func(value string) (secret string, wasEncrypted bool, err error)

+ type MfaStore interface

+ GetMfa func(ctx context.Context, userID uuid.UUID) (*Mfa, error)

+ UpsertMfa func(ctx context.Context, m *Mfa) error

+ type MfaUsageStore interface

+ TryClaimMfaCode func(ctx context.Context, userID uuid.UUID, codeHash string, ttl time.Duration) (bool, error)

+ type NewUser struct

+ Email string

+ Password string

+ type NoopHibpService struct

+ func (NoopHibpService) IsCompromised(context.Context, string) (bool, error)

+ type NoopSecretProtector struct

+ func (NoopSecretProtector) Protect(secret string) (string, error)

+ func (NoopSecretProtector) Unprotect(ciphertext string) (string, error)

+ func (NoopSecretProtector) UnprotectOrLegacy(value string) (string, bool, error)

+ type OIDCService interface

+ Exchange func(ctx context.Context, provider IdentityProvider, code, redirectURI string) (userID string, err error)

+ type Option func(*Service)

+ func WithAudit(store AuditStore) Option

+ func WithAuthStore(a AuthStore) Option

+ func WithHibp(h HibpService) Option

+ func WithLockout(store LockoutStore) Option

+ func WithMfaMethods(methods ...MfaMethod) Option

+ func WithPasswordPolicy(store PasswordPolicyStore) Option

+ func WithSecurityStamps(store SecurityStampStore) Option

+ type PasswordPolicy struct

+ CheckBreachDatabase bool

+ IsActive bool

+ MaxLength int

+ MinLength int

+ MinUniqueChars int

+ RequireDigit bool

+ RequireLowercase bool

+ RequireSpecial bool

+ RequireUppercase bool

+ func DefaultPasswordPolicy() PasswordPolicy

+ type PasswordPolicyError struct

+ Violations []string

+ func (e *PasswordPolicyError) Error() string

+ type PasswordPolicyStore interface

+ GetPasswordPolicy func(ctx context.Context) (*PasswordPolicy, error)

+ type PasswordStore interface

+ GetUserAuthByID func(ctx context.Context, id uuid.UUID) (*UserAuth, error)

+ UpdatePasswordHash func(ctx context.Context, id uuid.UUID, passwordHash string) error

+ type PermissionError struct

+ Key string

+ func (e *PermissionError) Error() string

+ type Principal struct

+ Email string

+ Roles []string

+ SessionID string

+ UserID uuid.UUID

+ func PrincipalFromContext(ctx context.Context) (*Principal, bool)

+ func (p *Principal) Has(permissionKey string) bool

+ func (p *Principal) Permissions() []string

+ type RecoveryCodeMethod struct

+ func NewRecoveryCodeMethod(store MfaStore) *RecoveryCodeMethod

+ func (m *RecoveryCodeMethod) IsEnrolled(ctx context.Context, userID uuid.UUID) (bool, error)

+ func (m *RecoveryCodeMethod) Name() string

+ func (m *RecoveryCodeMethod) Verify(ctx context.Context, userID uuid.UUID, code string) (bool, error)

+ type SecurityStampStore interface

+ BumpSecurityStamp func(ctx context.Context, userID uuid.UUID, newStamp string) error

+ type Service struct

+ func New(store Store, cfg Config, opts ...Option) *Service

+ func (s *Service) Audit() *AuditService

+ func (s *Service) ChangePassword(ctx context.Context, userID uuid.UUID, currentPassword, newPassword string) error

+ func (s *Service) CookieName() string

+ func (s *Service) CreateUser(ctx context.Context, in NewUser) (uuid.UUID, error)

+ func (s *Service) HasPermission(ctx context.Context, permissionKey string) bool

+ func (s *Service) InvalidateUserSessions(ctx context.Context, userID uuid.UUID) error

+ func (s *Service) Login(ctx context.Context, in LoginInput) (*LoginResult, error)

+ func (s *Service) Logout(ctx context.Context, sessionID string) error

+ func (s *Service) RequireContextPermission(ctx context.Context, permissionKey string) error

+ func (s *Service) RequirePermission(key string, next http.Handler) http.Handler

+ func (s *Service) SessionEnforcement(next http.Handler) http.Handler

+ func (s *Service) UnlockAccount(ctx context.Context, email, reason string, byUserID *string) error

+ func (s *Service) ValidateSession(ctx context.Context, sessionID string) (*Principal, error)

+ type SessionCapStore interface

+ EnforceSessionCap func(ctx context.Context, userID uuid.UUID, max int) error

+ type SessionPolicy struct

+ IdleTimeout time.Duration

+ MaxSessions int

+ SessionTimeout time.Duration

+ type SessionRecord struct

+ CreatedAt time.Time

+ ID uuid.UUID

+ IPAddress string

+ LastActivityAt time.Time

+ LoggedOutAt *time.Time

+ SecurityStamp string

+ SessionID string

+ TokenExpiresAt *time.Time

+ UserAgent string

+ UserID uuid.UUID

+ type Store interface

+ GetActiveSessionPolicy func(ctx context.Context) (*SessionPolicy, error)

+ GetSessionByID func(ctx context.Context, sessionID string) (*SessionRecord, error)

+ GetUserByID func(ctx context.Context, id uuid.UUID) (*User, error)

+ GetUserPermissions func(ctx context.Context, userID uuid.UUID) ([]string, error)

+ GetUserRoles func(ctx context.Context, userID uuid.UUID) ([]string, error)

+ TouchSession func(ctx context.Context, id uuid.UUID, at time.Time) error

+ type TOTPOption func(*TOTPService)

+ func TOTPWithReplayGuard(u MfaUsageStore) TOTPOption

+ func TOTPWithSecretProtector(p MfaSecretProtector) TOTPOption

+ type TOTPService struct

+ func NewTOTPService(store MfaStore, issuer string, opts ...TOTPOption) *TOTPService

+ func (s *TOTPService) Disable(ctx context.Context, userID uuid.UUID) error

+ func (s *TOTPService) EnrollTOTP(ctx context.Context, userID uuid.UUID) (EnrollResult, error)

+ func (s *TOTPService) IsEnabled(ctx context.Context, userID uuid.UUID) (bool, error)

+ func (s *TOTPService) IsEnrolled(ctx context.Context, userID uuid.UUID) (bool, error)

+ func (s *TOTPService) Name() string

+ func (s *TOTPService) Verify(ctx context.Context, userID uuid.UUID, code string) (bool, error)

+ func (s *TOTPService) VerifyRecoveryCode(ctx context.Context, userID uuid.UUID, code string) (bool, error)

+ func (s *TOTPService) VerifyTOTP(ctx context.Context, userID uuid.UUID, code string) (bool, error)

+ type TrustedDeviceService interface

+ IsTrusted func(ctx context.Context, userID, deviceToken string) (bool, error)

+ Trust func(ctx context.Context, userID, deviceToken string) error

+ type UnimplementedIPWhitelistService struct

+ func (UnimplementedIPWhitelistService) IsAllowed(context.Context, string) (bool, error)

+ type UnimplementedOIDCService struct

+ func (UnimplementedOIDCService) Exchange(context.Context, IdentityProvider, string, string) (string, error)

+ type UnimplementedTrustedDeviceService struct

+ func (UnimplementedTrustedDeviceService) IsTrusted(context.Context, string, string) (bool, error)

+ func (UnimplementedTrustedDeviceService) Trust(context.Context, string, string) error

+ type UnimplementedWebAuthnService struct

+ func (UnimplementedWebAuthnService) BeginLogin(context.Context, string) ([]byte, error)

+ func (UnimplementedWebAuthnService) BeginRegistration(context.Context, string) ([]byte, error)

+ func (UnimplementedWebAuthnService) FinishLogin(context.Context, string, []byte) error

+ func (UnimplementedWebAuthnService) FinishRegistration(context.Context, string, []byte) error

+ type User struct

+ Email string

+ ID uuid.UUID

+ IsActive bool

+ SecurityStamp string

+ UserName string

+ type UserAuth struct

+ Email string

+ ID uuid.UUID

+ IsActive bool

+ PasswordHash string

+ SecurityStamp string

+ type WebAuthnService interface

+ BeginLogin func(ctx context.Context, userID string) (options []byte, err error)

+ BeginRegistration func(ctx context.Context, userID string) (options []byte, err error)

+ FinishLogin func(ctx context.Context, userID string, assertion []byte) error

+ FinishRegistration func(ctx context.Context, userID string, attestation []byte) error