localauth

func LinkLocalCredentials ¶

func LinkLocalCredentials(config EnsureAuthUserConfig, userID string, username, password, email string) error

LinkLocalCredentials adds local (password) authentication to an existing OAuth-only user. This enables "incremental auth" where users sign up via OAuth and later add a password.

Who Calls This ¶

Your app calls this from a "Set Password" or "Complete Profile" page. Typically:

1. User signed up via Google OAuth (has google channel, no local channel)
2. User visits profile page, sees "Add password for email login"
3. User submits password (and optionally username) form
4. Your handler calls LinkLocalCredentials with the logged-in user's ID
5. User can now login with email/password OR Google

Example Handler in Your App ¶

func handleSetPassword(w http.ResponseWriter, r *http.Request) {
    userID := getLoggedInUserID(r) // from session/JWT
    user, _ := userStore.GetUserById(userID)
    email := user.Profile()["email"].(string)

    username := r.FormValue("username") // optional
    password := r.FormValue("password")

    err := oneauth.LinkLocalCredentials(config, userID, username, password, email)
    if err != nil {
        // handle error (e.g., username taken, password too weak)
    }
    // redirect to profile with success message
}

What It Does ¶

1. Verifies the email belongs to the given userID
2. Checks that local channel doesn't already exist
3. Creates local channel with hashed password
4. Reserves username in UsernameStore (if configured and username provided)
5. Updates user profile["channels"] to include "local"

func NewCreateUserFunc ¶

func NewCreateUserFunc(userStore core.UserStore, identityStore core.IdentityStore, channelStore core.ChannelStore) core.CreateUserFunc

NewCreateUserFunc creates a CreateUserFunc from stores

func NewCredentialsValidator ¶

func NewCredentialsValidator(identityStore core.IdentityStore, channelStore core.ChannelStore, userStore core.UserStore) core.CredentialsValidator

NewCredentialsValidator creates a CredentialsValidator from stores

func NewCredentialsValidatorWithUsername ¶

func NewCredentialsValidatorWithUsername(identityStore core.IdentityStore, channelStore core.ChannelStore, userStore core.UserStore, usernameStore core.UsernameStore) core.CredentialsValidator

NewCredentialsValidatorWithUsername creates a CredentialsValidator that supports logging in with username (in addition to email/phone).

Who Calls This ¶

Use this instead of NewCredentialsValidator when setting up LocalAuth if you want users to be able to login with their username:

localAuth := &oneauth.LocalAuth{
    ValidateCredentials: oneauth.NewCredentialsValidatorWithUsername(
        identityStore, channelStore, userStore, usernameStore,
    ),
    // ... other config
}

How Username Login Works ¶

1. User enters "johndoe" and password on login form
2. DetectUsernameType returns "username" (not email, not phone)
3. This validator looks up "johndoe" in UsernameStore → gets userID
4. Gets user's email identity from IdentityStore
5. Gets local channel for that email identity
6. Verifies password against channel's password_hash
7. Returns the user

Fallback Behavior ¶

If user enters an email or phone number instead of username, it falls back to the standard email/phone lookup (same as NewCredentialsValidator).

func NewEnsureAuthUserFunc ¶

func NewEnsureAuthUserFunc(config EnsureAuthUserConfig) func(authtype string, provider string, token any, userInfo map[string]any) (core.User, error)

NewEnsureAuthUserFunc creates a function that handles user creation/lookup for both OAuth and local authentication with channel linking support.

Who Calls This ¶

This function is called by OneAuth.SaveUserAndRedirect after a successful OAuth callback or local login. The returned function implements the core logic for AuthUserStore.EnsureAuthUser.

Flow for OAuth (e.g., Google Login) ¶

1. User clicks "Login with Google" → redirects to Google
2. Google redirects back to /auth/google/callback with auth code
3. OAuth handler exchanges code for token, fetches userInfo (email, name, picture)
4. OAuth handler calls OneAuth.SaveUserAndRedirect(authtype="oauth", provider="google", token, userInfo)
5. SaveUserAndRedirect calls UserStore.EnsureAuthUser → this function
6. This function checks if email identity exists: - EXISTS: Link Google channel to existing user, update profile["channels"] - NEW: Create User, Identity (verified=true), Google Channel
7. SaveUserAndRedirect creates JWT, sets cookies, redirects to app

Flow for Local Signup ¶

1. User submits signup form with email/password
2. LocalAuth.HandleSignup validates and calls CreateUser (from NewCreateUserFunc)
3. CreateUser creates User, Identity (verified=false), Local Channel
4. HandleSignup calls HandleUser → SaveUserAndRedirect → this function
5. User is logged in (or email verification required)

Channel Linking Logic ¶

Multiple channels (local, google, github) can point to the same user via shared email:

User (id: abc123)
├── Identity: email → user@example.com
├── Channel: local → email:user@example.com (password_hash)
├── Channel: google → email:user@example.com (oauth profile)
└── Channel: github → email:user@example.com (oauth profile)

User profile tracks linked providers: profile["channels"] = ["local", "google", "github"]