plugins

func Access ¶ added in v0.12.0

func Access(masterStatements access.Statements, opts ...access.Option) *access.Plugin

Access instantiates a new Access Control (Granular Permissions & RBAC/ABAC) plugin configured with master statements and options.

The Access plugin provides sub-microsecond in-memory permission evaluation, boolean logic combinators (AND/OR), wildcard matching ('*'), multi-role subject aggregation, dynamic role inheritance (Extend/Merge), thread-safe runtime role registration, JSON persistence serialization, and execution guards for HTTP/gRPC middlewares.

Available Methods ¶

• Plugin Methods:

• AccessControl() *AccessControl: Returns the underlying central AccessControl manager instance.

• PublishAuthorized(roles []string, req AuthorizeRequest, extra map[string]any): Dispatch access:authorized security event.

• PublishDenied(roles []string, req AuthorizeRequest, reason string, extra map[string]any): Dispatch access:denied security event.

• PublishRoleCreated(role *Role): Dispatch access:role:created lifecycle event.

• PublishRoleDeleted(roleName string): Dispatch access:role:deleted lifecycle event.

• AccessControl Manager Methods (via plugin.AccessControl()):

• NewRole(name string, roleStatements Statements) (*Role, error): Create and register a named role in the registry.

• MustNewRole(name string, roleStatements Statements) *Role: Create a role, panicking on validation error.

• NewAnonymousRole(roleStatements Statements) (*Role, error): Instantiate an unregistered ephemeral role.

• GetRole(name string) (*Role, bool): Retrieve a registered role by identifier.

• GetAllRoles() map[string]*Role: Return snapshot of all registered roles.

• DeleteRole(name string) bool: Remove a role from the registry.

• AuthorizeRoles(roleNames []string, request AuthorizeRequest, connector ...Connector) AuthorizeResult: Atomic multi-role evaluation combining statements with union semantics.

• AuthorizeRoleString(roleString string, request AuthorizeRequest, connector ...Connector) AuthorizeResult: Evaluate comma-separated role string ("admin,editor").

• MergeRoles(roleNames ...string) (*Role, error): Consolidate multiple registered roles into a combined Role instance.

• MasterStatements() Statements: Retrieve schema master statements.

• Role Instance Methods (via role):

• Authorize(request AuthorizeRequest, connector ...Connector) AuthorizeResult: Evaluate granular permission request with short-circuit evaluation.

• HasPermission(resource string, action string) bool: Check single resource and action permission in sub-microsecond time.

• Extend(newName string, additionalStatements Statements) *Role: Derive a new role inheriting base statements without mutating parent.

• Clone(newName ...string) *Role: Create a deep copy of the role.

• Statements() Statements: Return copy of role permission statements.

• Name() string: Return role name.

Configuration Options ¶

You can pass functional options to customize the plugin:

• access.WithMasterStatements(stmts access.Statements): Define the global master schema of valid resources and permitted actions.
• access.WithInitialRoles(roles map[string]access.Statements): Pre-register initial static or dynamic roles on startup.
• access.WithAllowWildcards(allow bool): Enable or disable wildcard ('*') matching for resources and actions (default: true).
• access.WithStrictResources(strict bool): Enforce that registered roles must strictly match MasterStatements (default: false).

Example:

ctx := context.Background()
statements := access.Statements{
	"project": {"create", "read", "update", "delete"},
	"user":    {"create", "read", "update", "delete"},
}

app, err := auth.New(
	config.WithPlugins(
		plugins.Access(
			statements,
			access.WithInitialRoles(map[string]access.Statements{
				"admin": {"*": {"*"}},
				"user":  {"project": {"read"}, "user": {"read"}},
			}),
		),
	),
)
if err != nil {
	panic(err)
}

ac := auth.Plugin[access.Plugin](app).AccessControl()
res := ac.AuthorizeRoles([]string{"user"}, access.Req("project", "read"))
if !res.Success {
	panic(res.Error)
}

func Admin ¶ added in v0.8.0

func Admin(repo admin.Repository, opts ...admin.Option) *admin.Plugin

Admin instantiates a new Admin governance plugin configured with a repository and options.

The Admin plugin provides role-based access control (RBAC), user moderation (ban/unban with automatic expiry), CRUD operations on users, password administration, active session management and revocation, and user impersonation.

Available Methods ¶

• User Administration:

• CreateUser(ctx context.Context, params CreateUserParams) (*entity.User, error): Provision a new user account with assigned role and credentials.

• GetUser(ctx context.Context, params GetUserParams) (*entity.User, error): Retrieve comprehensive user profile details.

• ListUsers(ctx context.Context, params ListUsersParams) (*ListUsersResult, error): Paginated search and filtering of users by role, ban status, email, or creation date.

• UpdateUser(ctx context.Context, params UpdateUserParams) (*entity.User, error): Update user profile, email, name, image, or metadata.

• RemoveUser(ctx context.Context, params RemoveUserParams) error: Permanently delete a user account and associated credentials.

• SetRole(ctx context.Context, params SetRoleParams) (*entity.User, error): Update administrative RBAC role assigned to a user.

• SetUserPassword(ctx context.Context, params SetUserPasswordParams) error: Directly set/override a user's password.

• Moderation & Ban:

• BanUser(ctx context.Context, params BanUserParams) (*entity.User, error): Suspend a user account with optional reason and expiry duration.

• UnbanUser(ctx context.Context, params UnbanUserParams) (*entity.User, error): Reinstate a suspended user account.

• CheckUserBanStatus(ctx context.Context, user *entity.User) error: Validate if user account is currently banned or expired.

• Impersonation:

• ImpersonateUser(ctx context.Context, params ImpersonateUserParams) (*ImpersonateResult, error): Issue a masquerade session to act on behalf of another user.

• StopImpersonating(ctx context.Context, params StopImpersonatingParams) (*StopImpersonatingResult, error): Terminate masquerade session and restore original admin session.

• Session Governance:

• ListUserSessions(ctx context.Context, params ListUserSessionsParams) ([]*entity.Session, error): Retrieve all active sessions for a user.

• RevokeUserSession(ctx context.Context, params RevokeUserSessionParams) error: Terminate a specific user session.

• RevokeUserSessions(ctx context.Context, params RevokeUserSessionsParams) error: Invalidate all active sessions for a user.

• RBAC Evaluation:

• CheckPermission(ctx context.Context, params CheckPermissionParams) (bool, error): Evaluate whether caller role possesses required administrative permissions.

Configuration Options ¶

You can pass functional options to customize the plugin:

• admin.WithDefaultRole(role string): Default role for new users (default: "user").
• admin.WithAdminRoles(roles ...string): Roles recognized with administrator privileges (default: ["admin"]).
• admin.WithAdminUserIDs(userIDs ...string): Explicit user IDs granted unrestricted administrator access.
• admin.WithDefaultBanReason(reason string): Fallback reason for account suspensions.
• admin.WithDefaultBanExpiresIn(duration time.Duration): Default duration for temporary account suspensions (0 = permanent).
• admin.WithImpersonationSessionDuration(duration time.Duration): Duration for masquerade sessions (default: 1h).
• admin.WithBannedUserMessage(msg string): User-facing error message for suspended users.
• admin.WithAllowImpersonatingAdmins(allow bool): Allow administrators to masquerade as other administrators.
• admin.WithPasswordLength(min, max int): Minimum and maximum allowed password lengths for administrative updates.
• admin.WithCustomRoles(roles map[string]admin.Role): Configure custom static RBAC roles and statements.
• admin.WithRole(role admin.Role): Register or override an individual role definition.

Example:

ctx := context.Background()
storage := memory.New()
app, err := auth.New(
	config.WithPlugins(
		plugins.Admin(
			storage,
			admin.WithAdminRoles("admin", "superadmin"),
		),
	),
)
if err != nil {
	panic(err)
}

userRes, err := auth.Plugin[admin.Plugin](app).CreateUser(ctx, admin.CreateUserParams{
	Caller:   admin.CallerContext{Role: "admin"},
	Name:     "Jane Doe",
	Email:    "jane@example.com",
	Password: "SecurePassword123!",
	Role:     "user",
})
if err != nil {
	panic(err)
}

func ApiKey ¶ added in v0.17.0

func ApiKey(repo apikey.Repository, opts ...apikey.Option) *apikey.Plugin

ApiKey instantiates a new ApiKey authentication and rate-limiting plugin configured with the given repository and options.

The ApiKey plugin allows applications to create, verify, list, update, and revoke API keys with SHA-256 base64url hashing, sliding window rate limiting, quota auto-refill, scope permission verification, custom JSON metadata, expiration, asynchronous background updates (DeferUpdates), and HTTP header middleware authentication.

Available Methods ¶

• CreateKey(ctx context.Context, params CreateApiKeyParams) (*CreateApiKeyResult, error): Issue a new API key.
• VerifyKey(ctx context.Context, params VerifyApiKeyParams) (*VerifyApiKeyResult, error): Authenticate an incoming API key.
• GetKey(ctx context.Context, params GetApiKeyParams) (*ApiKey, error): Retrieve key details by ID.
• UpdateKey(ctx context.Context, params UpdateApiKeyParams) (*ApiKey, error): Update metadata, status, or quota parameters.
• DeleteKey(ctx context.Context, params DeleteApiKeyParams) error: Revoke and delete an API key.
• ListKeys(ctx context.Context, params ListApiKeysParams) (*ListApiKeysResult, error): List keys for a owner reference ID.
• DeleteAllExpiredKeys(ctx context.Context) (int64, error): Purge all expired keys from storage.
• HTTPMiddleware() func(next http.Handler) http.Handler: Net/HTTP middleware for authenticating API Key request headers.

Configuration Options ¶

• apikey.WithHeaderNames(headers ...string): Request headers checked for API keys (default: "X-API-Key").
• apikey.WithDefaultKeyLength(length int): Key character length (default: 32).
• apikey.WithDefaultPrefix(prefix string): Key prefix attached to issued keys (e.g. "sk_live_").
• apikey.WithRateLimit(enabled bool, window time.Duration, maxReq int64): Configure sliding window rate limiting.
• apikey.WithExpiration(defaultExpiresIn *time.Duration): Configure default expiration duration.
• apikey.WithDisableKeyHashing(disable bool): Toggle storing raw plaintext keys instead of SHA-256 hashes.
• apikey.WithEnableSessionForAPIKeys(enable bool): Populate mock user identity during HTTP middleware verification.
• apikey.WithDeferUpdates(deferUpdates bool): Execute request counter and timestamp updates asynchronously.

Example:

ctx := context.Background()
storage := repo // custom apikey.Repository implementation
app, err := auth.New(
	config.WithPlugins(
		plugins.ApiKey(
			storage,
			apikey.WithDefaultPrefix("sk_live_"),
			apikey.WithDeferUpdates(true),
		),
	),
)
if err != nil {
	panic(err)
}

ak := auth.Plugin[apikey.Plugin](app)
res, err := ak.CreateKey(ctx, apikey.CreateApiKeyParams{
	ReferenceID: "user_123",
	Name:        stringPtr("Production Access"),
})
if err != nil {
	panic(err)
}
fmt.Println("Raw API Key (shown once):", res.RawKey)

func Bearer ¶ added in v0.4.0

func Bearer(repo bearer.Repository, opts ...bearer.Option) *bearer.Plugin

Bearer instantiates a new Bearer authentication plugin configured with an optional session repository and functional options.

The Bearer plugin handles RFC 7235 compliant Bearer token extraction, HMAC-SHA256 cryptographic signing and verification with constant-time comparison, CORS header exposition, and seamless session resolution for API and mobile clients.

Available Methods ¶

• Verify(ctx context.Context, params VerifyParams) (*VerifyResult, error): Cryptographically verify and parse an incoming Bearer token.
• CreateToken(ctx context.Context, params CreateTokenParams) (*CreateTokenResult, error): Generate and sign an HMAC-SHA256 authenticated Bearer token.
• ResolveSession(ctx context.Context, params ResolveSessionParams) (*ResolveSessionResult, error): Extract token, verify HMAC signature, and retrieve database session.
• ExtractToken(headerValue string) (string, error): Parse raw token from an HTTP Authorization header ("Bearer <token>").
• FormatHeader(token string) string: Format a token into standard "Bearer <token>" header value.
• FormatAuthTokenHeader(token string) (headerName, headerValue string): Generate "set-auth-token" response header.
• ExposedHeaders() string: Return CORS headers to expose to browsers ("set-auth-token").

Configuration Options ¶

You can pass functional options to customize the plugin:

• bearer.WithSecret(secret string): Cryptographic HMAC secret key used for signing and verifying tokens.
• bearer.WithRequireSignature(require bool): Enforce that incoming tokens must already have a valid HMAC signature.
• bearer.WithTokenHeader(header string): Customize incoming authorization header name (default: "Authorization").
• bearer.WithAuthTokenHeader(header string): Customize outgoing token header name (default: "set-auth-token").
• bearer.WithExposeHeaders(expose bool): Enable CORS Access-Control-Expose-Headers propagation.

Example:

ctx := context.Background()
storage := memory.New()
app, err := auth.New(
	config.WithPlugins(
		plugins.Bearer(
			storage,
			bearer.WithSecret("my-cryptographic-secret-key"),
		),
	),
)
if err != nil {
	panic(err)
}

tokenRes, err := auth.Plugin[bearer.Plugin](app).CreateToken(ctx, bearer.CreateTokenParams{
	Token:  "session_token_xyz",
	UserID: "usr_123",
})
if err != nil {
	panic(err)
}

func DeviceAuth ¶ added in v0.15.0

func DeviceAuth(repo deviceauth.Repository, opts ...deviceauth.Option) *deviceauth.Plugin

DeviceAuth instantiates a new Device Authorization Flow (RFC 8628) plugin configured with the given repository and options.

The DeviceAuth plugin enables OAuth 2.0 Device Authorization Grant workflow for input-constrained or browserless devices (Smart TVs, CLI tools, IoT hardware), issuing short verification codes for end-user approval on a secondary browser and exchanging approved grants for active user sessions.

Available Methods ¶

• RequestDeviceCode(ctx context.Context, params RequestDeviceCodeParams) (*DeviceCodeResponse, error): Initiate a new device authorization grant request.
• ExchangeDeviceToken(ctx context.Context, params ExchangeDeviceTokenParams) (*TokenResponse, error): Poll for authorization and exchange an approved device code for a session token.
• GetVerificationState(ctx context.Context, rawUserCode string) (*DeviceCode, error): Retrieve device authorization status by user verification code.
• ApproveDeviceCode(ctx context.Context, params ApproveDeviceCodeParams) error: Authorize a pending device code request for an authenticated user.
• DenyDeviceCode(ctx context.Context, params DenyDeviceCodeParams) error: Reject a pending device code authorization request.

Configuration Options ¶

• deviceauth.WithExpiresIn(d time.Duration): Expiration lifetime duration of issued device code grants (default: 30 minutes).
• deviceauth.WithInterval(d time.Duration): Minimum polling interval requirement between token requests (default: 5 seconds).
• deviceauth.WithDeviceCodeLength(length int): Character length of generated device codes (default: 40).
• deviceauth.WithUserCodeLength(length int): Character length of generated user codes (default: 8).
• deviceauth.WithVerificationURI(uri string): Base verification path returned in responses (default: "/device").
• deviceauth.WithCustomURI(uri string): Custom domain base URI for complete verification URLs.
• deviceauth.WithSessionExpiry(d time.Duration): Duration of sessions generated upon token exchange (default: 24 hours).
• deviceauth.WithGenerateDeviceCode(fn func(int) (string, error)): Custom device code generator callback.
• deviceauth.WithGenerateUserCode(fn func(int) (string, error)): Custom user code generator callback.
• deviceauth.WithValidateClient(fn func(context.Context, string) (bool, error)): Callback to validate client_id during requests.
• deviceauth.WithOnDeviceAuthRequest(fn func(context.Context, string, *string) error): Callback hook executed on device code requests.

Example:

ctx := context.Background()
storage := repo // custom deviceauth.Repository implementation
app, err := auth.New(
	config.WithPlugins(
		plugins.DeviceAuth(
			storage,
			deviceauth.WithExpiresIn(15*time.Minute),
			deviceauth.WithInterval(5*time.Second),
		),
	),
)
if err != nil {
	panic(err)
}

devPlugin := auth.Plugin[deviceauth.Plugin](app)
resp, err := devPlugin.RequestDeviceCode(ctx, deviceauth.RequestDeviceCodeParams{
	ClientID: "cli_app",
})
if err != nil {
	panic(err)
}

func EmailOTP ¶ added in v0.9.0

func EmailOTP(repo emailotp.Repository, opts ...emailotp.Option) *emailotp.Plugin

EmailOTP instantiates a new Email OTP authentication plugin configured with a repository and functional options.

The EmailOTP plugin handles passwordless authentication (sign-in and automatic sign-up), email address verification, secure password reset flows, and verified email change requests via cryptographically secure one-time numeric passwords.

Available Methods ¶

• SendVerificationOTP(ctx context.Context, params *SendVerificationOTPParams) (*SendVerificationOTPResult, error): Generate and dispatch an OTP code via transactional email.
• CreateVerificationOTP(ctx context.Context, params *CreateVerificationOTPParams) (string, error): Server-side generation of an OTP code without sending email.
• GetVerificationOTP(ctx context.Context, params *GetVerificationOTPParams) (*GetVerificationOTPResult, error): Retrieve active OTP details for testing or inspection.
• CheckVerificationOTP(ctx context.Context, params *CheckVerificationOTPParams) (*CheckVerificationOTPResult, error): Non-destructive validation check of an OTP code without consuming it.
• VerifyEmailOTP(ctx context.Context, params *VerifyEmailOTPParams) (*VerifyEmailOTPResult, error): Verify OTP for email address confirmation.
• SignInEmailOTP(ctx context.Context, params *SignInEmailOTPParams) (*SignInEmailOTPResult, error): Passwordless authentication (sign-in/sign-up) using verified OTP code.
• RequestPasswordResetEmailOTP(ctx context.Context, params *RequestPasswordResetParams) (*RequestPasswordResetResult, error): Initiate password reset workflow via email OTP.
• ResetPasswordEmailOTP(ctx context.Context, params *ResetPasswordParams) (*ResetPasswordResult, error): Reset user password upon submitting valid OTP code.
• RequestEmailChangeEmailOTP(ctx context.Context, params *RequestEmailChangeParams) (*RequestEmailChangeResult, error): Initiate email address change workflow with OTP validation.
• ChangeEmailEmailOTP(ctx context.Context, params *ChangeEmailParams) (*ChangeEmailResult, error): Finalize email address update using verified OTP code.

Configuration Options ¶

You can pass functional options to customize the plugin:

• emailotp.WithSendVerificationOTP(fn SendVerificationOTPFunc): Required delivery callback to send emails.
• emailotp.WithOTPLength(length int): Number of numeric digits for generated OTPs (default: 6).
• emailotp.WithExpiresIn(d time.Duration): Expiration lifetime of generated OTPs (default: 5m).
• emailotp.WithAllowedAttempts(attempts int): Max incorrect verification attempts before invalidation (default: 3).
• emailotp.WithStoreOTP(mode StoreOTPMode, secretKey ...string): Storage mode ("plain", "hashed", "encrypted").
• emailotp.WithResendStrategy(strategy ResendStrategy): Resend policy ("rotate" or "reuse", default: "rotate").
• emailotp.WithDisableSignUp(disable bool): Prevent auto-creating new users on sign-in (default: false).
• emailotp.WithAutoSignInAfterVerification(auto bool): Automatically create session upon email verification (default: true).
• emailotp.WithRevokeSessionsOnPasswordReset(revoke bool): Invalidate all active sessions on password reset (default: true).
• emailotp.WithChangeEmail(enabled, verifyCurrent bool): Configure email change flow parameters.

Example:

ctx := context.Background()
storage := memory.New()
app, err := auth.New(
	config.WithPlugins(
		plugins.EmailOTP(
			storage,
			emailotp.WithSendVerificationOTP(func(ctx context.Context, data emailotp.SendEmailData) error {
				return mailer.Send(data.Email, "Your OTP Code", data.OTP)
			}),
		),
	),
)
if err != nil {
	panic(err)
}

otpRes, err := auth.Plugin[emailotp.Plugin](app).SendVerificationOTP(ctx, emailotp.SendVerificationOTPParams{
	Email: "gopher@golang.org",
	Type:  emailotp.OTPTypeSignIn,
})
if err != nil {
	panic(err)
}

func EmailPassword ¶

func EmailPassword(repo emailpassword.Repository, opts ...emailpassword.Option) *emailpassword.Plugin

EmailPassword instantiates a new EmailPassword authentication plugin configured with the given repository and options.

The EmailPassword plugin handles traditional user registration (sign-up), login authentication (sign-in), password changes, forgot/reset password flows, email verification, active password verification, and lifecycle event hooks.

Available Methods ¶

• SignUp(ctx context.Context, input dto.SignUpParams) (*entity.User, error): Register a new user with email and password.
• SignIn(ctx context.Context, input dto.SignInParams) (*entity.User, error): Authenticate an existing user with email and password credentials.
• ChangePassword(ctx context.Context, input dto.ChangePasswordParams) error: Update the password for an authenticated user.
• ForgotPassword(ctx context.Context, input dto.ForgotPasswordParams) (*entity.VerificationToken, error): Generate a secure password reset token and dispatch email.
• ResetPassword(ctx context.Context, input dto.ResetPasswordParams) error: Reset a user password using a valid reset token.
• SendVerificationEmail(ctx context.Context, input dto.SendVerificationEmailParams) (*entity.VerificationToken, error): Issue and send an email verification token.
• VerifyEmail(ctx context.Context, input dto.VerifyEmailParams) (*entity.User, error): Confirm user email address using a verification token.
• VerifyPassword(ctx context.Context, input dto.VerifyPasswordParams) (bool, error): Verify if a given plaintext password matches user hash.

Configuration Options ¶

You can pass functional options to customize the plugin:

• emailpassword.WithMinPasswordLength(minLen int): Minimum password length required during registration (default: 8).
• emailpassword.WithMaxPasswordLength(maxLen int): Maximum allowed password length (default: 128).
• emailpassword.WithRequireEmailVerification(require bool): Require email verification before sign-in (default: false).
• emailpassword.WithSendVerificationOnSignUp(send bool): Automatically dispatch verification email on sign-up (default: false).
• emailpassword.WithResetTokenExpiry(duration time.Duration): Expiry duration for reset tokens (default: 15 minutes).
• emailpassword.WithVerificationTokenExpiry(duration time.Duration): Expiry duration for verification tokens (default: 24 hours).
• emailpassword.WithSendResetPasswordEmail(fn SendEmailFunc): Transactional email callback for reset links.
• emailpassword.WithSendVerificationEmail(fn SendEmailFunc): Transactional email callback for verification links.

Example:

ctx := context.Background()
storage := memory.New()
app, err := auth.New(
	config.WithPlugins(
		plugins.EmailPassword(storage, emailpassword.WithMinPasswordLength(8)),
	),
)
if err != nil {
	panic(err)
}

user, err := auth.Plugin[emailpassword.Plugin](app).SignUp(ctx, dto.SignUpParams{
	Name:     "Gopher Go",
	Email:    "gopher@golang.org",
	Password: "SecurePassword123!",
})
if err != nil {
	panic(err)
}

func JWT ¶ added in v0.5.0

func JWT(repo jwt.Repository, opts ...jwt.Option) *jwt.Plugin

JWT instantiates a new JSON Web Token authentication plugin configured with a key repository and functional options.

The JWT plugin provides RFC 7519 JSON Web Token issuance and RFC 7517 JSON Web Key Set (JWKS) key management, supporting modern asymmetric cryptographic algorithms (Ed25519/EdDSA, ECDSA ES256/ES512, RSA RS256/PS256), AES-256-GCM authenticated encryption for private keys in persistent storage, and automatic key rotation with grace periods.

Available Methods ¶

• Sign(ctx context.Context, params SignParams) (*SignResult, error): Construct and sign an RFC 7519 compact JWT token with active signing key.
• Verify(ctx context.Context, params VerifyParams) (*VerifyResult, error): Verify cryptographic signature and claims (iss, aud, exp, nbf) of a JWT.
• GetJWKS(ctx context.Context, params GetJWKSParams) (*GetJWKSResult, error): Serve RFC 7517 JSON Web Key Set containing active and valid grace-period public keys.
• GetToken(ctx context.Context, params GetTokenParams) (*GetTokenResult, error): Issue a signed JWT for an authenticated user session.
• RotateKeys(ctx context.Context, params RotateKeysParams) (*RotateKeysResult, error): Perform on-demand cryptographic key rotation, generating new active key pair.

Configuration Options ¶

You can pass functional options to customize the plugin:

• jwt.WithIssuer(issuer string): Issuer identifier ("iss" claim) in generated tokens (default: "GoModularAuth").
• jwt.WithAudience(aud ...string): Audience identifiers ("aud" claim) in generated tokens.
• jwt.WithExpiration(duration time.Duration): Expiration duration ("exp" claim) for tokens (default: 15 minutes).
• jwt.WithAlgorithm(alg jwt.Algorithm): Asymmetric signing algorithm (default: jwt.AlgEdDSA / Ed25519).
• jwt.WithSecret(secret string): Symmetric encryption secret used to protect private keys via AES-256-GCM.
• jwt.WithGracePeriod(grace time.Duration): Grace period for keeping expired keys in public JWKS (default: 30 days).
• jwt.WithDefinePayload(fn jwt.PayloadFunc): Callback to inject custom claims based on session and user.
• jwt.WithGetSubject(fn jwt.SubjectFunc): Callback to resolve the subject ("sub") claim.

Example:

ctx := context.Background()
storage := memory.New()
app, err := auth.New(
	config.WithPlugins(
		plugins.JWT(
			storage,
			jwt.WithIssuer("https://auth.example.com"),
			jwt.WithSecret("my-aes-encryption-secret-32b"),
		),
	),
)
if err != nil {
	panic(err)
}

jwtRes, err := auth.Plugin[jwt.Plugin](app).Sign(ctx, jwt.SignParams{
	Subject: "usr_123",
	Payload: map[string]any{"role": "admin"},
})
if err != nil {
	panic(err)
}

func MagicLink ¶ added in v0.13.0

func MagicLink(repo magiclink.Repository, opts ...magiclink.Option) *magiclink.Plugin

MagicLink instantiates a new MagicLink authentication plugin configured with the given repository and options.

The MagicLink plugin provides passwordless user authentication and auto-registration via transactional email verification links. It features atomic single-use token consumption (protecting against race conditions and replay attacks), flexible token storage modes (plain text, SHA-256 constant-time hashing, and AES-256-GCM symmetric encryption), customizable redirect URLs for new vs existing users, HTTP handlers for direct router integration, and lifecycle event bus hooks.

Available Methods ¶

• SignInMagicLink(ctx context.Context, params magiclink.SignInMagicLinkParams) (*magiclink.SignInMagicLinkResult, error): Issue a secure verification token and dispatch the magic link email.
• VerifyMagicLink(ctx context.Context, params magiclink.VerifyMagicLinkParams) (*magiclink.VerifyMagicLinkResult, error): Atomically consume token, authenticate/register user, and issue active session.
• HandleSignInMagicLink(w http.ResponseWriter, r *http.Request): HTTP POST endpoint handler for /sign-in/magic-link.
• HandleVerifyMagicLink(w http.ResponseWriter, r *http.Request): HTTP GET/POST endpoint handler for /magic-link/verify with JSON or browser redirect output.

Configuration Options ¶

You can pass functional options to customize the plugin:

• magiclink.WithSendMagicLink(fn magiclink.SendMagicLinkFunc): Transactional email delivery callback for dispatching magic links (Required).
• magiclink.WithExpiresIn(duration time.Duration): Expiry duration for verification tokens (default: 5 minutes).
• magiclink.WithDisableSignUp(disable bool): Prevent auto-registration of unknown email addresses (default: false).
• magiclink.WithDefaultCallbackURL(url string): Default fallback redirect URL after successful login (default: "/").
• magiclink.WithStoreTokenMode(mode magiclink.StoreTokenMode): Security storage mode ("plain", "hashed", "encrypted", default: "plain").
• magiclink.WithSecretKey(key string): Secret key used for AES-256-GCM encrypted token storage.
• magiclink.WithCustomHasher(h magiclink.Hasher): Custom token hasher implementation for hashed mode.
• magiclink.WithCustomCipher(c magiclink.Cipher): Custom token cipher implementation for encrypted mode.
• magiclink.WithGenerateToken(fn magiclink.TokenGeneratorFunc): Custom token generator function.
• magiclink.WithRateLimit(window time.Duration, max int): Request throttling configuration (default: 5 requests per 60 seconds).

Example:

ctx := context.Background()
storage := memory.New()
app, err := auth.New(
	config.WithPlugins(
		plugins.MagicLink(
			storage,
			magiclink.WithSendMagicLink(func(ctx context.Context, data magiclink.SendMagicLinkData) error {
				fmt.Printf("Send magic link to %s: %s\n", data.Email, data.URL)
				return nil
			}),
			magiclink.WithExpiresIn(10 * time.Minute),
			magiclink.WithDefaultCallbackURL("/dashboard"),
		),
	),
)
if err != nil {
	panic(err)
}

res, err := auth.Plugin[magiclink.Plugin](app).SignInMagicLink(ctx, magiclink.SignInMagicLinkParams{
	Email: "gopher@golang.org",
	Name:  "Gopher Go",
})
if err != nil {
	panic(err)
}

func OAuth2 ¶ added in v0.11.0

func OAuth2(repo oauth2.Repository, opts ...oauth2.Option) *oauth2.Plugin

OAuth2 instantiates a new OAuth 2.1 & OpenID Connect Provider authentication plugin.

The OAuth2 plugin provides full compliance with OAuth 2.1 (mandatory PKCE S256, single-use atomic code exchange, RFC 9207 issuer identification, refresh token rotation with family revocation) and OpenID Connect Core 1.0 (ID Token issuance with at_hash/c_hash, UserInfo endpoint, RP-Initiated Logout, Dynamic Client Registration, and Discovery Metadata).

Available Methods ¶

• Authorization Flow:

• Authorize(ctx context.Context, params AuthorizeParams) (*AuthorizeResult, error): Initiate OAuth 2.1 authorization request with PKCE and scope negotiation.

• ContinueAuthorize(ctx context.Context, params ContinueAuthorizeParams) (*AuthorizeResult, error): Resume authorization after user login and scope consent approval.

• Token Exchange & Management:

• Token(ctx context.Context, params TokenParams) (*TokenResult, error): Exchange authorization code or refresh token for Access Token and OIDC ID Token.

• Introspect(ctx context.Context, params IntrospectParams) (*IntrospectResult, error): RFC 7662 token introspection to query token status and claims.

• Revoke(ctx context.Context, params RevokeParams) (*RevokeResult, error): RFC 7009 token revocation for access and refresh tokens.

• OIDC UserInfo & Session Termination:

• UserInfo(ctx context.Context, params UserInfoParams) (*UserInfoResult, error): Serve OIDC UserInfo endpoint returning verified subject claims.

• EndSession(ctx context.Context, params EndSessionParams) (*EndSessionResult, error): RP-Initiated Logout to terminate user sessions.

• Client Registration (RFC 7591):

• RegisterClient(ctx context.Context, params RegisterClientParams) (*RegisterClientResult, error): Dynamically register an OAuth 2.1 client application.

• GetClient(ctx context.Context, params GetClientParams) (*GetClientResult, error): Retrieve registered client details.

• UpdateClient(ctx context.Context, params UpdateClientParams) (*UpdateClientResult, error): Modify client configuration (redirect URIs, scopes, grant types).

• DeleteClient(ctx context.Context, params DeleteClientParams) (*DeleteClientResult, error): Delete a registered client application.

• RotateClientSecret(ctx context.Context, params RotateClientSecretParams) (*RotateClientSecretResult, error): Rotate client secret credentials.

• User Consent Management:

• Consent(ctx context.Context, params ConsentParams) (*ConsentResult, error): Record user consent for authorized client scopes.

• RevokeConsent(ctx context.Context, params RevokeConsentParams) (*RevokeConsentResult, error): Revoke client access to user data.

• ListConsents(ctx context.Context, params ListConsentsParams) (*ListConsentsResult, error): List all active third-party application authorizations for a user.

• Discovery & Metadata:

• GetOpenIDConfiguration(ctx context.Context, params OpenIDConfigurationParams) (*OpenIDConfigurationResult, error): Serve .well-known/openid-configuration metadata.

• GetOAuthAuthorizationServerMetadata(ctx context.Context, params OAuthMetadataParams) (*OAuthMetadataResult, error): Serve RFC 8414 OAuth 2.0 authorization server metadata.

Configuration Options ¶

You can pass functional options to customize the plugin:

• oauth2.WithIssuer(issuer string): Authorization server base URL ("iss" claim).
• oauth2.WithAccessTokenType(t oauth2.AccessTokenType): Issue RFC 9068 JWT or opaque access tokens.
• oauth2.WithJWTSigner(signer oauth2.JWTSigner): Custom JWT signer (compatible with plugins/jwt or RSA/EdDSA).
• oauth2.WithPages(loginPage, consentPage string): Interactive UI redirect paths.
• oauth2.WithScopes(scopes ...string): Supported OAuth/OIDC scopes.
• oauth2.WithGrantTypes(types ...oauth2.GrantType): Enabled grant types.
• oauth2.WithTokenExpirations(code, access, refresh, idToken time.Duration): Token validity lifetimes.
• oauth2.WithStoreModes(secretMode, tokenMode oauth2.StoreMode, secretKey string): Persistence security modes.
• oauth2.WithPairwiseSecret(secret string): Secret salt for pairwise pseudonymous sub derivation.
• oauth2.WithDynamicClientRegistration(allow, allowUnauthenticated bool): RFC 7591 client registration.
• oauth2.WithCustomAccessTokenClaims(fn oauth2.CustomClaimsFunc): Application-specific JWT access token claims.
• oauth2.WithCustomIDTokenClaims(fn oauth2.CustomClaimsFunc): Application-specific OIDC ID token claims.
• oauth2.WithCustomUserInfoClaims(fn oauth2.CustomClaimsFunc): Application-specific UserInfo claims.

Example:

ctx := context.Background()
storage := memory.New()
app, err := auth.New(
	config.WithPlugins(
		plugins.OAuth2(
			storage,
			oauth2.WithIssuer("https://auth.example.com"),
			oauth2.WithAccessTokenType(oauth2.AccessTokenTypeJWT),
		),
	),
)
if err != nil {
	panic(err)
}

authRes, err := auth.Plugin[oauth2.Plugin](app).Authorize(ctx, oauth2.AuthorizeParams{
	ClientID:            "client_123",
	RedirectURI:         "https://app.example.com/callback",
	ResponseType:        "code",
	CodeChallenge:       "E9Melhoa2OwvFrGMTJguCH5rtx64EH_vu9-D64PJstU",
	CodeChallengeMethod: "S256",
	Scope:               "openid profile email",
	State:               "state_xyz",
})
if err != nil {
	panic(err)
}

func OIDCProvider ¶ added in v0.16.0

func OIDCProvider(repo oidcprovider.Repository, opts ...oidcprovider.Option) *oidcprovider.Plugin

OIDCProvider instantiates a new OIDC Provider (OpenID Connect 1.0 / OAuth 2.0) plugin configured with the given repository and options.

The OIDCProvider plugin converts your application into an OAuth 2.0 Authorization Server and OpenID Connect Provider (OP), handling client registration, Authorization Code Flow with PKCE (RFC 7636), user consent management, Access/Refresh/ID Token issuance, UserInfo claims endpoint, RP-Initiated Logout, OpenID Connect Discovery metadata (/.well-known/openid-configuration), and public JWKS export.

Available Methods ¶

• RegisterClient(ctx context.Context, params RegisterClientParams) (*OAuthClient, error): Register a new OAuth 2.0 / OIDC client application.
• GetClient(ctx context.Context, clientID string) (*OAuthClient, error): Retrieve a registered client application by client_id.
• Authorize(ctx context.Context, params AuthorizeParams) (*AuthorizeResponse, error): Process an authorization request and issue an authorization code.
• GrantConsent(ctx context.Context, params GrantConsentParams) (*AuthorizeResponse, error): Record explicit user scope consent for a client.
• ExchangeToken(ctx context.Context, params ExchangeTokenParams) (*TokenResponse, error): Exchange an authorization code or refresh token for token pairs.
• GetUserInfo(ctx context.Context, accessToken string) (UserInfoClaims, error): Retrieve standard OpenID Connect claims for a valid access_token.
• EndSession(ctx context.Context, idTokenHint string, postLogoutRedirectURI *string) (string, error): Perform RP-Initiated Logout.
• GetDiscoveryMetadata(ctx context.Context) (*DiscoveryMetadata, error): Generate OpenID Connect Discovery 1.0 JSON configuration.
• GetJWKS(ctx context.Context) (map[string]any, error): Export public keys in JWKS format.

Configuration Options ¶

• oidcprovider.WithIssuer(issuer string): OIDC issuer identifier URL (default: "http://localhost:8080").
• oidcprovider.WithBaseURL(url string): Base URL for endpoint path construction.
• oidcprovider.WithTokenExpirations(access, refresh, code time.Duration): Expiration durations for tokens and codes.
• oidcprovider.WithSupportedScopes(scopes []string): List of supported OIDC scopes (default: openid, profile, email, offline_access).
• oidcprovider.WithRequirePKCE(require bool): Enforce PKCE for authorization code grant requests (default: true).
• oidcprovider.WithRSAKeys(privateKey *rsa.PrivateKey): RSA private key for RS256 ID Token signing and JWKS export.
• oidcprovider.WithSecretKey(secret []byte): Shared secret key for HS256 ID Token signing.
• oidcprovider.WithStoreClientSecretMode(mode SecretStoreMode): How client_secret values are stored and verified.
• oidcprovider.WithConsentPageURL(url string): Interactive consent UI page URL.
• oidcprovider.WithLoginPageURL(url string): Login redirect URL.
• oidcprovider.WithAdditionalClaims(fn AdditionalClaimsFunc): Custom callback to inject custom claims into UserInfo and ID Tokens.

Example:

ctx := context.Background()
storage := repo // custom oidcprovider.Repository implementation
app, err := auth.New(
	config.WithPlugins(
		plugins.OIDCProvider(
			storage,
			oidcprovider.WithIssuer("https://auth.example.com"),
			oidcprovider.WithSecretKey([]byte("my-super-secret-key-32-bytes")),
		),
	),
)
if err != nil {
	panic(err)
}

op := auth.Plugin[oidcprovider.Plugin](app)
client, err := op.RegisterClient(ctx, oidcprovider.RegisterClientParams{
	Name:         "My Web App",
	Type:         oidcprovider.ClientTypeWeb,
	RedirectURIs: []string{"https://app.example.com/callback"},
})
if err != nil {
	panic(err)
}

func Organization ¶ added in v0.6.0

func Organization(repo organization.Repository, opts ...organization.Option) *organization.Plugin

Organization instantiates a new Organization multi-tenancy plugin configured with a repository and options.

The Organization plugin provides multi-tenancy, organization lifecycle management, member and role management, static and dynamic Role-Based Access Control (RBAC), team hierarchies (Teams), and full invitation workflows.

Available Methods ¶

• Organization Lifecycle:

• CreateOrganization(ctx context.Context, params CreateOrganizationParams) (*CreateOrganizationResult, error): Create a new organization entity and assign creator role.

• GetOrganization(ctx context.Context, params GetOrganizationParams) (*GetOrganizationResult, error): Retrieve organization details by ID.

• GetOrganizationBySlug(ctx context.Context, params GetOrganizationBySlugParams) (*GetOrganizationBySlugResult, error): Retrieve organization details by URL slug.

• GetFullOrganization(ctx context.Context, params GetFullOrganizationParams) (*GetFullOrganizationResult, error): Fetch organization alongside its members, teams, and invitations.

• UpdateOrganization(ctx context.Context, params UpdateOrganizationParams) (*UpdateOrganizationResult, error): Update organization metadata (name, slug, logo, metadata).

• DeleteOrganization(ctx context.Context, params DeleteOrganizationParams) (*DeleteOrganizationResult, error): Permanently delete an organization and cascade delete child records.

• ListOrganizations(ctx context.Context, params ListOrganizationsParams) (*ListOrganizationsResult, error): List all organizations where a user is an active member.

• CheckSlug(ctx context.Context, params CheckSlugParams) (*CheckSlugResult, error): Validate slug availability and format.

• SetActiveOrganization(ctx context.Context, params SetActiveOrganizationParams) (*SetActiveOrganizationResult, error): Switch the active organization context on a session.

• GetActiveOrganization(ctx context.Context, params GetActiveOrganizationParams) (*GetActiveOrganizationResult, error): Retrieve the currently active organization for a session.

• Member Management:

• AddMember(ctx context.Context, params AddMemberParams) (*AddMemberResult, error): Directly add a user to an organization with a specific role.

• GetMember(ctx context.Context, params GetMemberParams) (*GetMemberResult, error): Retrieve membership record for a user in an organization.

• GetActiveMember(ctx context.Context, params GetActiveMemberParams) (*GetActiveMemberResult, error): Retrieve active membership details from the current session.

• GetActiveMemberRole(ctx context.Context, params GetActiveMemberRoleParams) (*GetActiveMemberRoleResult, error): Retrieve active member's assigned role.

• UpdateMemberRole(ctx context.Context, params UpdateMemberRoleParams) (*UpdateMemberRoleResult, error): Modify a member's role within an organization.

• RemoveMember(ctx context.Context, params RemoveMemberParams) (*RemoveMemberResult, error): Remove a user from an organization.

• LeaveOrganization(ctx context.Context, params LeaveOrganizationParams) (*LeaveOrganizationResult, error): Allow a member to voluntarily depart an organization.

• ListMembers(ctx context.Context, params ListMembersParams) (*ListMembersResult, error): List all members with pagination.

• Invitation Workflows:

• CreateInvitation(ctx context.Context, params CreateInvitationParams) (*CreateInvitationResult, error): Issue an email invitation with secure token.

• GetInvitation(ctx context.Context, params GetInvitationParams) (*GetInvitationResult, error): Retrieve invitation details by ID or token.

• AcceptInvitation(ctx context.Context, params AcceptInvitationParams) (*AcceptInvitationResult, error): Accept an invitation and join organization.

• RejectInvitation(ctx context.Context, params RejectInvitationParams) (*RejectInvitationResult, error): Decline an incoming organization invitation.

• CancelInvitation(ctx context.Context, params CancelInvitationParams) (*CancelInvitationResult, error): Revoke a pending invitation.

• ListInvitations(ctx context.Context, params ListInvitationsParams) (*ListInvitationsResult, error): List pending invitations for an organization.

• ListUserInvitations(ctx context.Context, params ListUserInvitationsParams) (*ListUserInvitationsResult, error): List all pending invitations addressed to a user.

• Teams:

• CreateTeam(ctx context.Context, params CreateTeamParams) (*CreateTeamResult, error): Create a team sub-unit within an organization.

• GetTeam(ctx context.Context, params GetTeamParams) (*GetTeamResult, error): Retrieve team details.

• UpdateTeam(ctx context.Context, params UpdateTeamParams) (*UpdateTeamResult, error): Modify team name or metadata.

• DeleteTeam(ctx context.Context, params DeleteTeamParams) (*DeleteTeamResult, error): Delete a team.

• ListTeams(ctx context.Context, params ListTeamsParams) (*ListTeamsResult, error): List all teams in an organization.

• AddTeamMember(ctx context.Context, params AddTeamMemberParams) (*AddTeamMemberResult, error): Assign an organization member to a team.

• RemoveTeamMember(ctx context.Context, params RemoveTeamMemberParams) (*RemoveTeamMemberResult, error): Remove a member from a team.

• ListTeamMembers(ctx context.Context, params ListTeamMembersParams) (*ListTeamMembersResult, error): List all members assigned to a team.

• SetActiveTeam(ctx context.Context, params SetActiveTeamParams) (*SetActiveTeamResult, error): Set active team on session.

• GetActiveTeam(ctx context.Context, params GetActiveTeamParams) (*GetActiveTeamResult, error): Get active team from session.

• Dynamic Roles & RBAC:

• CreateRole(ctx context.Context, params CreateRoleParams) (*CreateRoleResult, error): Provision a dynamic database-persisted custom role.

• GetRole(ctx context.Context, params GetRoleParams) (*GetRoleResult, error): Retrieve dynamic role permissions.

• UpdateRole(ctx context.Context, params UpdateRoleParams) (*UpdateRoleResult, error): Modify dynamic role permissions.

• DeleteRole(ctx context.Context, params DeleteRoleParams) (*DeleteRoleResult, error): Delete a dynamic role.

• ListRoles(ctx context.Context, params ListRolesParams) (*ListRolesResult, error): List all dynamic and static roles for an organization.

• HasPermission(ctx context.Context, params HasPermissionParams) (*HasPermissionResult, error): Check if a role satisfies specific permissions.

• CheckPermission(ctx context.Context, orgID, userRole string, required Permissions) (bool, error): Evaluate RBAC permissions.

Configuration Options ¶

You can pass functional options to customize the plugin:

• organization.WithCreatorRole(role string): Role assigned to the organization creator (default: "owner").
• organization.WithInvitationExpiresIn(duration time.Duration): Duration for invitation expiry (default: 48h).
• organization.WithMembershipLimit(limit int): Max members per organization.
• organization.WithOrganizationLimit(limit int): Max organizations created per user.
• organization.WithTeams(enabled, defaultTeam, allowRemovingAll bool): Configure teams sub-module.
• organization.WithDynamicAccessControl(enabled bool): Enable database-persisted dynamic roles.
• organization.WithCustomRoles(roles map[string]Permissions): Define custom static roles.
• organization.WithSendInvitationEmail(fn SendInvitationEmailFunc): Email delivery callback.

Example:

ctx := context.Background()
storage := memory.New()
app, err := auth.New(
	config.WithPlugins(
		plugins.Organization(
			storage,
			organization.WithCreatorRole("owner"),
		),
	),
)
if err != nil {
	panic(err)
}

orgRes, err := auth.Plugin[organization.Plugin](app).CreateOrganization(ctx, organization.CreateOrganizationParams{
	Name:   "Acme Corp",
	Slug:   "acme",
	UserID: "usr_123",
})
if err != nil {
	panic(err)
}

func Passkey ¶ added in v0.9.0

func Passkey(repo passkey.Repository, opts ...passkey.Option) *passkey.Plugin

Passkey instantiates a new Passkey (WebAuthn / FIDO2 / Passwordless) authentication plugin configured with a repository and options.

The Passkey plugin provides biometric and security key passwordless authentication, resident keys (discoverable credentials / conditional UI), AAGUID authenticator metadata lookup, replay and cloning protection via monotonic signature counters, and full lifecycle event dispatching.

Available Methods ¶

• GenerateRegistrationOptions(ctx context.Context, params *GenerateRegistrationOptionsParams) (*RegistrationOptionsResult, error): Generate WebAuthn creation ceremony options and challenge.
• VerifyRegistration(ctx context.Context, params *VerifyRegistrationParams) (*entity.Passkey, error): Verify navigator.credentials.create() response and persist public key credential.
• GenerateAuthenticationOptions(ctx context.Context, params *GenerateAuthenticationOptionsParams) (*AuthenticationOptionsResult, error): Generate WebAuthn assertion ceremony options (supports discoverable keys/autofill).
• VerifyAuthentication(ctx context.Context, params *VerifyAuthenticationParams) (*VerifyAuthenticationResult, error): Verify navigator.credentials.get() assertion response and establish authenticated session.
• ListPasskeys(ctx context.Context, params *ListPasskeysParams) ([]*entity.Passkey, error): List all registered passkeys for an authenticated user.
• GetPasskey(ctx context.Context, id string) (*entity.Passkey, error): Retrieve specific passkey credential details by ID.
• UpdatePasskey(ctx context.Context, params *UpdatePasskeyParams) (*entity.Passkey, error): Rename or update friendly label of a registered passkey.
• DeletePasskey(ctx context.Context, params *DeletePasskeyParams) error: Remove a passkey credential from user account.

Configuration Options ¶

You can pass functional options to customize the plugin:

• passkey.WithRPDisplayName(name string): Relying Party human-readable name (default: "GoModularAuth").
• passkey.WithRPID(rpID string): Relying Party domain identifier (default: "localhost").
• passkey.WithRPOrigins(origins ...string): Allowed origin URLs (e.g. "http://localhost:3000").
• passkey.WithChallengeTimeout(d time.Duration): Expiry duration for ephemeral challenges (default: 5m).
• passkey.WithRequireSessionOnRegistration(require bool): Enforce active user session during registration (default: true).
• passkey.WithUserVerification(uv protocol.UserVerificationRequirement): Verification requirement (discouraged, preferred, required).
• passkey.WithResidentKey(rk protocol.ResidentKeyRequirement): Resident key requirement (discouraged, preferred, required).
• passkey.WithAttestation(att protocol.ConveyancePreference): Attestation conveyance (none, indirect, direct, enterprise).
• passkey.WithAuthenticatorAttachment(att protocol.AuthenticatorAttachment): Restrict attachment (platform, cross-platform).
• passkey.WithSessionDuration(d time.Duration): Duration for created user sessions (default: 7 days).
• passkey.WithResolveUser(fn passkey.ResolveUserFunc): User resolution callback when registration occurs without an active session.
• passkey.WithAfterRegistration(hook passkey.AfterRegistrationHook): Lifecycle callback executed after successful registration.
• passkey.WithAfterAuthentication(hook passkey.AfterAuthenticationHook): Lifecycle callback executed after successful authentication.

Example:

ctx := context.Background()
storage := memory.New()
app, err := auth.New(
	config.WithPlugins(
		plugins.Passkey(
			storage,
			passkey.WithRPDisplayName("Acme Corp"),
			passkey.WithRPID("auth.acme.com"),
			passkey.WithRPOrigins("https://auth.acme.com"),
		),
	),
)
if err != nil {
	panic(err)
}

regOpts, err := auth.Plugin[passkey.Plugin](app).GenerateRegistrationOptions(ctx, passkey.GenerateRegistrationOptionsParams{
	UserID:          "usr_123",
	UserName:        "gopher@golang.org",
	UserDisplayName: "Gopher Go",
})
if err != nil {
	panic(err)
}

func PhoneNumber ¶ added in v0.10.0

func PhoneNumber(repo phonenumber.Repository, opts ...phonenumber.Option) *phonenumber.Plugin

PhoneNumber instantiates a new Phone Number (SMS OTP) authentication plugin configured with a repository and options.

The PhoneNumber plugin handles passwordless SMS OTP authentication, phone number verification and updates, credentialed phone + password sign-in, secure password resets via SMS, attempt budgeting, and anti-replay protection.

Available Methods ¶

• SendOTP(ctx context.Context, params SendOTPParams) (*SendOTPResult, error): Generate and dispatch a numeric OTP code via SMS callback.
• Verify(ctx context.Context, params VerifyParams) (*VerifyResult, error): Verify an SMS OTP code for passwordless sign-in, registration, or phone update.
• SignIn(ctx context.Context, params SignInParams) (*SignInResult, error): Authenticate an existing user using verified phone number and password credentials.
• RequestPasswordReset(ctx context.Context, params RequestPasswordResetParams) (*RequestPasswordResetResult, error): Initiate password reset flow via SMS OTP code.
• ResetPassword(ctx context.Context, params ResetPasswordParams) (*ResetPasswordResult, error): Finalize password reset using verified SMS OTP code.
• UnlinkPhoneNumber(ctx context.Context, userID string) (*entity.User, error): Remove associated phone number from user account.
• CreateVerificationOTP(ctx context.Context, params CreateVerificationOTPParams) (*CreateVerificationOTPResult, error): Server-side generation of phone OTP code.
• GetVerificationOTP(ctx context.Context, params GetVerificationOTPParams) (*GetVerificationOTPResult, error): Inspect active phone OTP code record.
• CheckVerificationOTP(ctx context.Context, params CheckVerificationOTPParams) (*CheckVerificationOTPResult, error): Non-destructive validation check of phone OTP code.

Configuration Options ¶

You can pass functional options to customize the plugin:

• phonenumber.WithSendOTP(fn SendOTPFunc): Required delivery callback to dispatch SMS messages.
• phonenumber.WithVerifyOTP(fn VerifyOTPFunc): Optional delegated verification callback (e.g. Twilio Verify).
• phonenumber.WithSendPasswordResetOTP(fn SendOTPFunc): Optional dedicated callback for password reset SMS OTPs.
• phonenumber.WithOTPLength(length int): Number of numeric digits for generated OTPs (default: 6).
• phonenumber.WithExpiresIn(d time.Duration): Expiration lifetime of generated OTPs (default: 5m).
• phonenumber.WithAllowedAttempts(attempts int): Max incorrect verification attempts before invalidation (default: 3).
• phonenumber.WithStoreOTP(mode StoreOTPMode, secretKey ...string): Storage mode ("plain", "hashed", "encrypted").
• phonenumber.WithResendStrategy(strategy ResendStrategy): Resend policy ("rotate" or "reuse", default: "rotate").
• phonenumber.WithRequireVerification(require bool): Enforce verified phone before password login (default: false).
• phonenumber.WithDisableSignUp(disable bool): Prevent auto-creating new users on verification (default: false).
• phonenumber.WithRevokeSessionsOnPasswordReset(revoke bool): Invalidate all active sessions on password reset (default: true).
• phonenumber.WithPhoneNumberValidator(fn PhoneNumberValidatorFunc): Custom validator for phone number formats (e.g. E.164).
• phonenumber.WithSignUpOnVerification(cfg SignUpOnVerificationConfig): Custom temporary email/name generators for auto-signup.
• phonenumber.WithCallbackOnVerification(fn CallbackOnVerificationFunc): Hook executed after phone verification.
• phonenumber.WithOnPasswordReset(fn OnPasswordResetFunc): Hook executed after password reset confirmation.

Example:

ctx := context.Background()
storage := memory.New()
app, err := auth.New(
	config.WithPlugins(
		plugins.PhoneNumber(
			storage,
			phonenumber.WithSendOTP(func(ctx context.Context, data phonenumber.SendOTPData) error {
				return smsClient.SendSMS(data.PhoneNumber, "Your code is: " + data.Code)
			}),
		),
	),
)
if err != nil {
	panic(err)
}

otpRes, err := auth.Plugin[phonenumber.Plugin](app).SendOTP(ctx, phonenumber.SendOTPParams{
	PhoneNumber: "+15551234567",
})
if err != nil {
	panic(err)
}

func TwoFactor ¶

func TwoFactor(repo twofactor.Repository, opts ...twofactor.Option) *twofactor.Plugin

TwoFactor instantiates a new TwoFactor authentication plugin configured with the given repository and options.

The TwoFactor plugin provides Time-based One-Time Password (TOTP / RFC 6238) multi-factor authentication, generating secure Base32 secrets, creating otpauth:// URIs for authenticator apps (Google Authenticator, Authy, 1Password), verifying 6- or 8-digit TOTP codes, managing single-use backup recovery codes, issuing sign-in challenge tokens, authorizing trusted client devices, and dispatching SMS/Email OTP challenges.

Available Methods ¶

• Enable(ctx context.Context, params EnableParams) (*EnableResult, error): Initialize 2FA enrollment, generating secret, TOTP URI, and backup codes.
• Disable(ctx context.Context, params DisableParams) error: Deactivate two-factor authentication for a user.
• GetTOTPURI(ctx context.Context, params GetTOTPURIParams) (string, error): Retrieve otpauth:// URI for an enrolled user.
• VerifyTOTP(ctx context.Context, params VerifyTOTPParams) (*VerifyResult, error): Validate a time-based 6-digit TOTP code.
• VerifyBackupCode(ctx context.Context, params VerifyBackupCodeParams) (*VerifyResult, error): Consume and validate a single-use backup recovery code.
• GenerateBackupCodes(ctx context.Context, params GenerateBackupCodesParams) (*BackupCodesResult, error): Regenerate a fresh set of recovery backup codes.
• ViewBackupCodes(ctx context.Context, params ViewBackupCodesParams) (*BackupCodesResult, error): View active unconsumed backup codes.
• SendOTP(ctx context.Context, params SendOTPParams) (*SendOTPResult, error): Dispatch SMS/Email OTP code for 2FA verification.
• VerifyOTP(ctx context.Context, params VerifyOTPParams) (*VerifyResult, error): Verify an SMS/Email OTP challenge code.
• CreateChallenge(ctx context.Context, params CreateChallengeParams) (*ChallengeResult, error): Create a temporary sign-in challenge token.
• VerifyChallenge(ctx context.Context, params VerifyChallengeParams) (*VerifyResult, error): Complete authentication by verifying challenge token and 2FA code.
• TrustDevice(ctx context.Context, params TrustDeviceParams) (*TrustDeviceResult, error): Authorize and issue a trusted client device cookie/token.
• VerifyTrustDevice(ctx context.Context, params VerifyTrustDeviceParams) (bool, error): Check if a client device token is valid and trusted.
• RevokeTrustedDevice(ctx context.Context, params RevokeTrustedDeviceParams) error: Revoke authorization for a specific trusted device.
• RevokeAllTrustedDevices(ctx context.Context, userID string) error: Invalidate all trusted devices for a user.
• GenerateTOTPSecret(ctx context.Context, userID string) (string, error): Generate a raw Base32 TOTP secret.
• VerifyCode(ctx context.Context, userID, code string) (bool, error): Simple validation helper for TOTP or backup codes.

Configuration Options ¶

You can pass functional options to customize the plugin:

• twofactor.WithIssuer(issuer string): Issuer name shown in authenticator apps (default: "GoModularAuth").
• twofactor.WithAlgorithm(alg twofactor.TOTPAlgorithm): Hashing algorithm (SHA1, SHA256, SHA512).
• twofactor.WithTOTPOptions(digits int, period int): Number of digits and duration period (default: 6 digits, 30s).
• twofactor.WithBackupCodeOptions(amount, length int): Number and length of backup codes (default: 10 codes, 10 chars).
• twofactor.WithLockoutProtection(maxAttempts int, duration time.Duration): Rate-limiting brute-force protection.
• twofactor.WithTrustDevice(secret string, maxAge time.Duration): Configure authorized trusted devices.
• twofactor.WithChallengeExpiry(d time.Duration): Duration for sign-in 2FA challenge tokens (default: 10m).
• twofactor.WithSendOTP(fn twofactor.SendOTPFunc): Delivery callback for SMS/Email OTP challenges.

Example:

ctx := context.Background()
storage := memory.New()
app, err := auth.New(
	config.WithPlugins(
		plugins.TwoFactor(
			storage,
			twofactor.WithIssuer("GoModularAuth"),
			twofactor.WithTOTPOptions(6, 30),
		),
	),
)
if err != nil {
	panic(err)
}

res, err := auth.Plugin[twofactor.Plugin](app).Enable(ctx, twofactor.EnableParams{
	UserID: "usr_123",
})
if err != nil {
	panic(err)
}

func Username ¶ added in v0.14.0

func Username(repo username.Repository, opts ...username.Option) *username.Plugin

Username instantiates a new Username authentication plugin configured with the given repository and options.

The Username plugin enables username-based sign-in, username availability validation, character normalization (lowercasing by default), display username support, and timing attack mitigation.

Available Methods ¶

• SignIn(ctx context.Context, params SignInUsernameParams) (*SignInUsernameResult, error): Authenticate a user with username and password credentials.
• IsAvailable(ctx context.Context, username string) (*IsUsernameAvailableResult, error): Check if a username is available for registration.
• UpdateUsername(ctx context.Context, params UpdateUsernameParams) (*UpdateUsernameResult, error): Update a user's username and display name.
• ProcessSignUpUsername(ctx context.Context, username, displayUsername string) (normalized, finalDisplay string, err error): Validate and normalize credentials for user registration.
• ValidateUsername(ctx context.Context, username string) error: Validate username length, format, and custom constraints.

Configuration Options ¶

• username.WithMinLength(minLen int): Minimum allowed username length (default: 3).
• username.WithMaxLength(maxLen int): Maximum allowed username length (default: 30).
• username.WithUsernameValidator(pattern string): Custom regular expression format pattern.
• username.WithCustomValidator(fn username.CustomValidatorFunc): Asynchronous custom validator callback.
• username.WithNormalization(enable bool): Enable or disable username normalization (default: true).
• username.WithNormalizationFunc(fn username.NormalizationFunc): Custom normalization routine (default: strings.ToLower).
• username.WithRequireEmailVerification(require bool): Require verified email before sign-in (default: false).

Example:

ctx := context.Background()
storage := memory.New()
app, err := auth.New(
	config.WithPlugins(
		plugins.Username(
			storage,
			username.WithMinLength(4),
			username.WithRequireEmailVerification(true),
		),
	),
)
if err != nil {
	panic(err)
}

res, err := auth.Plugin[username.Plugin](app).SignIn(ctx, username.SignInUsernameParams{
	Username: "gopher_coder",
	Password: "SecurePassword123!",
})
if err != nil {
	panic(err)
}