Go Packages

All Authsome packages are importable from github.com/xraph/authsome.

Core packages

`github.com/xraph/authsome`

Root package. Exports the engine constructor, configuration types, and functional options.

Export	Description
`New(...Option) (*Engine, error)`	Create an Authsome engine
`Config`	Engine configuration struct
`PasswordConfig`	Password policy configuration
`SessionConfig`	Session behavior configuration
`MFAConfig`	Multi-factor authentication configuration
`PhoneConfig`	Phone authentication configuration
`OAuth2Config`	OAuth2 provider configuration
`JWTConfig`	JWT signing configuration
`RateLimitConfig`	Rate limiting configuration
`WithStore(store.Store)`	Set the primary data store
`WithPlugin(Plugin)`	Register an authentication plugin
`WithConfig(Config)`	Set engine configuration
`WithMFAStore(mfa.Store)`	Set the MFA enrollment store
`WithSMSSender(bridge.SMSSender)`	Set the SMS bridge
`WithMailer(bridge.Mailer)`	Set the email bridge
`WithPasswordHistory(store)`	Set the password history store
`WithRateLimiter(ratelimit.Limiter)`	Set the rate limiter
`WithLockout(lockout.Lockout)`	Set the account lockout handler
`WithLogger(logger)`	Set the logger

`github.com/xraph/authsome/engine`

The central engine with all authentication and management operations.

Export	Description
`Engine.Start(ctx)`	Initialize the engine
`Engine.Stop(ctx)`	Graceful shutdown
`Engine.SignUp(ctx, req)`	Create user account and session
`Engine.SignIn(ctx, req)`	Authenticate user
`Engine.SignOut(ctx, sessionID)`	Revoke a session
`Engine.Refresh(ctx, refreshToken)`	Refresh session tokens
`Engine.GetMe(ctx, userID)`	Get user profile
`Engine.UpdateMe(ctx, user)`	Update user profile
`Engine.DeleteAccount(ctx, userID)`	Delete user account (GDPR)
`Engine.ExportUserData(ctx, userID)`	Export all user data (GDPR)
`Engine.ForgotPassword(ctx, appID, email)`	Initiate password reset
`Engine.ResetPassword(ctx, token, newPassword)`	Complete password reset
`Engine.ChangePassword(ctx, userID, current, new)`	Change password
`Engine.VerifyEmail(ctx, token)`	Verify email address
`Engine.Impersonate(ctx, adminID, targetID, appID)`	Create impersonation session
`Engine.ListSessions(ctx, userID)`	List user sessions
`Engine.RevokeSession(ctx, sessionID)`	Revoke a specific session
`Engine.RevokeAllSessions(ctx, userID)`	Revoke all user sessions
`Engine.ValidateToken(ctx, token)`	Validate a session token
`Engine.ListUserDevices(ctx, userID)`	List tracked devices
`Engine.GetDevice(ctx, deviceID)`	Get device by ID
`Engine.DeleteDevice(ctx, deviceID)`	Remove a device
`Engine.TrustDevice(ctx, deviceID)`	Mark device as trusted
`Engine.CreateWebhook(ctx, webhook)`	Register a webhook
`Engine.GetWebhook(ctx, webhookID)`	Get webhook by ID
`Engine.UpdateWebhook(ctx, webhook)`	Update a webhook
`Engine.DeleteWebhook(ctx, webhookID)`	Delete a webhook
`Engine.ListWebhooks(ctx, appID)`	List webhooks for an app
`Engine.CreateRole(ctx, role)`	Create an RBAC role
`Engine.GetRole(ctx, roleID)`	Get role by ID
`Engine.UpdateRole(ctx, role)`	Update a role
`Engine.DeleteRole(ctx, roleID)`	Delete a role
`Engine.ListRoles(ctx, appID)`	List roles for an app
`Engine.AddPermission(ctx, perm)`	Add permission to a role
`Engine.ListRolePermissions(ctx, roleID)`	List role permissions
`Engine.RemovePermission(ctx, permID)`	Remove a permission
`Engine.AssignUserRole(ctx, userRole)`	Assign role to user
`Engine.UnassignUserRole(ctx, userID, roleID)`	Unassign role
`Engine.ListUserRoles(ctx, userID)`	List user roles

Entity packages

`github.com/xraph/authsome/user`

User entity and store interface.

Export	Description
`User`	User struct with all profile fields
`Metadata`	`map[string]string` for custom fields
`UserQuery`	Query parameters for listing/filtering users
`UserList`	Paginated user list response
`Store`	User persistence interface

`github.com/xraph/authsome/session`

Session entity and store interface.

Export	Description
`Session`	Session struct with tokens and metadata
`Store`	Session persistence interface

`github.com/xraph/authsome/device`

Device tracking entity and store interface.

Export	Description
`Device`	Device struct with fingerprint and trust status
`Store`	Device persistence interface

`github.com/xraph/authsome/organization`

Organization, member, invitation, and team entities.

Export	Description
`Organization`	Organization struct
`Member`	Membership struct with role
`MemberRole`	Role type (`owner`, `admin`, `member`)
`Invitation`	Invitation struct with status
`InvitationStatus`	Status type (`pending`, `accepted`, `expired`, `declined`)
`Team`	Team struct
`Metadata`	`map[string]string` for org metadata
`Store`	Organization persistence interface

`github.com/xraph/authsome/webhook`

Webhook entity and store interface.

Export	Description
`Webhook`	Webhook struct with URL, events, and secret
`Store`	Webhook persistence interface

`github.com/xraph/authsome/app`

Application entity and store interface.

Export	Description
`App`	Application struct
`Store`	App persistence interface

`github.com/xraph/authsome/rbac`

Role-based access control entities and store interface.

Export	Description
`Role`	Role struct
`Permission`	Permission struct (action + resource)
`UserRole`	User-role assignment
`Store`	RBAC persistence interface

Authentication packages

`github.com/xraph/authsome/account`

Account lifecycle operations: password hashing, validation, session creation.

Export	Description
`SignUpRequest`	Signup request struct
`SignInRequest`	Signin request struct
`SessionConfig`	Session token configuration
`NewSession(appID, userID, cfg)`	Create a new session
`HashPasswordWithPolicy(password, policy)`	Hash a password
`NeedsRehash(hash, policy)`	Check if hash needs migration
`Store`	Account lifecycle store (verification, password reset)
`Verification`	Email verification record
`PasswordReset`	Password reset record
`ErrInvalidCredentials`	Invalid email/password
`ErrEmailTaken`	Email already registered
`ErrUsernameTaken`	Username already registered
`ErrUserBanned`	User is banned
`ErrSessionExpired`	Session has expired
`ErrWeakPassword`	Password fails policy
`ErrPasswordReused`	Password matches history

`github.com/xraph/authsome/strategy`

Authentication strategy interface.

Export	Description
`Strategy`	Strategy interface (`Name()`, `Authenticate()`)
`Result`	Authentication result (user, session, is-new)
`ErrStrategyNotApplicable`	Strategy does not apply to request

`github.com/xraph/authsome/plugins/password`

Password authentication plugin.

Export	Description
`New(config ...Config) Strategy`	Create password strategy
`Config`	Plugin config (allowed domains)

`github.com/xraph/authsome/plugins/mfa`

Multi-factor authentication plugin.

Export	Description
`Enrollment`	MFA enrollment record
`RecoveryCode`	Recovery code record
`SMSChallenge`	Pending SMS challenge
`TOTPConfig`	TOTP generation config
`Store`	MFA persistence interface
`GenerateTOTPKey(cfg)`	Generate TOTP secret
`ValidateTOTP(code, secret)`	Validate TOTP code
`GenerateTOTPCode(secret)`	Generate TOTP code (testing)
`GenerateSMSCode(length)`	Generate random numeric code
`SendSMSChallenge(ctx, sender, phone)`	Send SMS and return challenge
`ValidateSMSCode(code, challenge)`	Validate SMS code
`GenerateRecoveryCodes(userID, count)`	Generate recovery codes
`VerifyRecoveryCode(plaintext, code)`	Verify a recovery code
`DefaultRecoveryCodeCount`	Default: 8

`github.com/xraph/authsome/plugins/social`

Social OAuth login plugin (Google, GitHub, Apple, Microsoft, etc.).

`github.com/xraph/authsome/plugins/sso`

Enterprise SSO plugin (SAML, OIDC).

`github.com/xraph/authsome/plugins/passkey`

WebAuthn/passkey authentication plugin.

`github.com/xraph/authsome/plugins/email`

Magic link (email-based passwordless) plugin.

Configuration packages

`github.com/xraph/authsome/formconfig`

Dynamic form configuration and branding.

Export	Description
`FormConfig`	Form schema definition
`FormField`	Individual field definition
`FieldType`	Field type constants
`Validation`	Field validation rules
`SelectOption`	Option for select/radio/checkbox
`BrandingConfig`	Per-org branding configuration
`FormTypeSignup`	Constant: `"signup"`

`github.com/xraph/authsome/appsessionconfig`

Per-app session configuration overrides.

Export	Description
`Config`	Per-app session config (TTL, format, binding)
`Store`	Persistence interface
`ErrNotFound`	No config exists for app

Store packages

`github.com/xraph/authsome/store`

Composite store interface embedding all subsystem stores.

Export	Description
`Store`	Composite interface (user, session, device, org, webhook, etc.)
`ErrNotFound`	Record not found

`github.com/xraph/authsome/store/postgres`

PostgreSQL backend via Grove ORM with embedded migrations.

`github.com/xraph/authsome/store/sqlite`

SQLite backend via Grove ORM.

`github.com/xraph/authsome/store/mongo`

MongoDB backend.

`github.com/xraph/authsome/store/memory`

In-memory backend for testing.

Bridge packages

`github.com/xraph/authsome/bridge`

Bridge interfaces for external integrations.

Export	Description
`SMSSender`	SMS sending interface
`SMSMessage`	SMS message struct
`Mailer`	Email sending interface
`ErrSMSNotAvailable`	No SMS bridge configured

`github.com/xraph/authsome/bridge/smsadapter`

SMS bridge implementations.

Export	Description
`NewTwilioSender(sid, token, from)`	Twilio SMS sender

`github.com/xraph/authsome/bridge/maileradapter`

Email bridge implementations.

Export	Description
`NewResendMailer(apiKey)`	Resend email sender
`NewSMTPMailer(config)`	SMTP email sender

Infrastructure packages

`github.com/xraph/authsome/middleware`

HTTP middleware for authentication, rate limiting, and RBAC.

Export	Description
`Auth(engine)`	Session validation middleware
`RateLimit(limiter, cfg)`	Rate limiting middleware
`RBAC(engine)`	Role-based access control middleware
`UserIDFrom(ctx)`	Extract user ID from context
`SessionIDFrom(ctx)`	Extract session ID from context

`github.com/xraph/authsome/ratelimit`

Rate limiting interfaces and implementations.

Export	Description
`Limiter`	Rate limiter interface
`NewMemoryLimiter()`	In-memory sliding window limiter
`NewNoopLimiter()`	No-op limiter (disabled)

`github.com/xraph/authsome/lockout`

Account lockout interfaces and implementations.

Export	Description
`Lockout`	Lockout interface
`NewMemoryLockout()`	In-memory lockout tracker
`NewNoopLockout()`	No-op lockout (disabled)

`github.com/xraph/authsome/api`

Forge-native HTTP handlers.

Export	Description
`New(engine, router)`	Create the API handler
`RegisterRoutes(router)`	Mount all HTTP endpoints

`github.com/xraph/authsome/extension`

Forge framework extension adapter.

Export	Description
`New(...Option) *Extension`	Create the Forge extension
`Extension.Name()`	Returns `"authsome"`
`Extension.Version()`	Returns current version
`Extension.Engine()`	Access the underlying engine
`Extension.Middlewares()`	Returns auth middleware stack

`github.com/xraph/authsome/ceremony`

Temporary data store for multi-step flows (PKCE, WebAuthn).

Export	Description
`Store`	Key-value store with TTL

ID package

`github.com/xraph/authsome/id`

TypeID-based identifiers (UUIDv7, K-sortable) for all entities.

func NewUserID() UserID
func NewSessionID() SessionID
func NewAppID() AppID
func NewDeviceID() DeviceID
func NewOrgID() OrgID
func NewMemberID() MemberID
func NewInvitationID() InvitationID
func NewTeamID() TeamID
func NewWebhookID() WebhookID
func NewRoleID() RoleID
func NewPermissionID() PermissionID
func NewMFAID() MFAID
func NewRecoveryCodeID() RecoveryCodeID
func NewFormConfigID() FormConfigID
func NewBrandingConfigID() BrandingConfigID
func NewAppSessionConfigID() AppSessionConfigID
func NewEnvironmentID() EnvironmentID

func ParseUserID(s string) (UserID, error)
func ParseSessionID(s string) (SessionID, error)
func ParseAppID(s string) (AppID, error)
func ParseDeviceID(s string) (DeviceID, error)
func ParseOrgID(s string) (OrgID, error)
// ... Parse functions for all ID types

All IDs implement String() string and are based on TypeID (UUIDv7, K-sortable). Prefixes:

Prefix	Entity
`ausr_`	User
`ases_`	Session
`aapp_`	App
`adev_`	Device
`aorg_`	Organization
`ambr_`	Member
`ainv_`	Invitation
`atm_`	Team
`awhk_`	Webhook
`arol_`	Role
`aprm_`	Permission
`amfa_`	MFA Enrollment
`arc_`	Recovery Code
`afcf_`	FormConfig
`abrd_`	BrandingConfig
`aenv_`	Environment

Go Packages

On this page