Email and password

The emailpassword plugin adds sign-up, sign-in, and sign-out with an email address and a password. It can also reset a forgotten password by a link sent to the user's address. See Password reset.

Setup #

Pass the plugin to Prepare. It needs no tables of its own: users, accounts, and sessions are core tables.

go
import "github.com/go-behemoth/behemoth/plugins/emailpassword"

plugin := emailpassword.New(emailpassword.Options{})

app, err := engine.Prepare([]core.Plugin{plugin}, engine.PrepareConfig{})
// ...
ac, err := engine.Boot(ctx, app, db, engine.BootConfig{ /* ... */ })

The plugin's name is emailpassword (emailpassword.PluginName). Use it in PluginMeta.Dependencies to build on the plugin, and in HookOptions.Before/After to order a handler around it.

To let users sign in with a username as well, add the username plugin. For a phone number, with a one-time code or the password, add the phone number plugin.

A user who signs up starts with EmailVerified false. To confirm addresses, add the email verification plugin: it sends the link without any change here, and can refuse sign-ins until the address is confirmed.

Options #

The zero value works. Every field is optional.

FieldDefaultMeaning
MinPasswordLength8Shortest password accepted at sign-up and at a password reset, in characters.
MaxPasswordLength128Longest password accepted at sign-up and at a password reset, in characters.
ValidatePasswordnoneAn extra check on a new password, run after the length check. Return an error to reject it.
ValidateEmailutils.IsValidEmailThe check on the email at sign-up. It receives the address trimmed and lowercased.
ResetoffPassword reset. Setting Reset.LinkURL turns it on; see Password reset.
go
plugin := emailpassword.New(emailpassword.Options{
    MinPasswordLength: 12,
    ValidatePassword: func(password string) error {
        if isBreached(password) {
            return errors.New("this password has appeared in a data breach")
        }
        return nil
    },
})
  • The rules apply where a password is set: at sign-up and at a password reset. Sign-in does not apply them, so raising MinPasswordLength later does not lock out users whose password is shorter.
  • A minimum above the maximum, or a negative limit, is a configuration error from Boot.
  • Passwords are hashed with the hasher configured in BootConfig.Crypto. The plugin has no hashing option of its own. See Bound the password hashes that run at once.
  • crypto.Config.Password sets the Argon2id parameters. A field left at zero takes the value of crypto.DefaultParams. A salt or key length under 16 bytes, or a Memory under 8 KiB per lane (Parallelism), is a configuration error from Boot.
  • The sign-up response says invalid email or invalid password, with the code email_invalid_input or password_invalid_input. The text of the error your function returns is not sent to the client.

Bound the password hashes that run at once #

Sign-up, sign-in, and the password reset each hash a password. A sign-in for an unknown email hashes one too, so that its answer takes as long as a wrong password's. A hash with crypto.DefaultParams holds 64 MiB of memory while it runs. crypto.Config.PasswordLimit bounds how many hashes run at once in the process, so a burst of requests waits for the hasher instead of exhausting the process's memory:

go
ac, err := engine.Boot(ctx, app, db, engine.BootConfig{
    Crypto: crypto.Config{
        Secrets: SECRET_SOURCE,
        PasswordLimit: crypto.PasswordLimit{
            // zero means GOMAXPROCS
            MaxConcurrent: 4,
            // zero means two seconds
            MaxWait:       2 * time.Second,
        },
    },
    // ...
})

SECRET_SOURCE is your crypto.SecretSource, such as a crypto.StaticSecretSource.

The bound works as follows:

  • A request over the bound waits for a running hash to finish. A request that waits longer than MaxWait gets 503 with {"error": "the server is busy, please try again later", "code": "server_busy"} and a Retry-After header of MaxWait, rounded up to whole seconds. Called from code, a flow returns an *errs.DomainError of category errs.CategoryUnavailable with the code errs.CodeServerBusy.
  • A request whose context ends while it waits gets the context's error. A hash that has started runs to the end.
  • A refusal is not a failed sign-in. No failed point fires, so a lockout built on auth.signIn.failed does not count it. Sign-in answers 503 for an unknown email as for a known one, so the answer does not show which addresses have an account.
  • The memory the running hashes hold stays within MaxConcurrent times Params.Memory. With Go's default garbage collector settings, the process holds up to about twice that for hashing. Checking a password that was stored with more memory than Params.Memory counts for more than one hash.
  • More hashes at once add memory and waiting time, and few hashes a second once every CPU is busy.
  • The bound holds per process. Each replica of a deployment has its own, so more replicas take more sign-ins at once.
  • In a container, GOMAXPROCS follows the container's CPU limit. A container without a CPU limit sees every CPU of its host, and the default bound can then need more memory than the container has. Set MaxConcurrent from the container's memory limit in that case. For example, with DefaultParams and 1 GiB, a bound of 4 holds about 512 MiB (4 × 64 MiB × 2).
  • A negative field is a configuration error from Boot.

behemoth.password.wait and behemoth.password.busy show how long requests wait and how many are refused. See Telemetry.

Routes #

The routes sit directly under the router's base path.

RouteBodyResult
POST /sign-up/emailemail, password, and optionally firstname, lastname, image_url201 with {"user": {...}}. Other fields in the body are not stored by this plugin. A plugin can take one: the username plugin stores username.
POST /sign-in/emailemail, password. Other fields are not used by sign-in, but handlers on auth.signIn.before see them.200 with {"user": {...}}, or {"status": "requires_second_factor"} when a second factor is pending. The session token arrives by the configured delivery: a cookie, the Set-Auth-Token header, or token in this body.
POST /sign-outnone; needs a valid session200 with {"status": "signed_out"}, and the session is revoked. With a cookie delivery the response also removes the cookie.

The user is keyed by column name (for example id, email, email_verified, and image_url). Sessions describes the token deliveries, the response body, and the user's JSON in full.

With SessionConfig.CaptureIPAndAgent on, the session created at sign-in records the client's IP address and user agent. The address is resolved with RouterConfig.TrustedProxies and ClientIPHeader, so behind a load balancer it is the client's and not the proxy's.

Error responses #

An error response is JSON with an error message and, for most errors, a code.

RouteWhenStatusBody
POST /sign-up/email, POST /sign-in/emailthe body is not valid JSON400{"error": "request validation error", "code": "request_validation_error"}
POST /sign-up/emailemail is missing, not a string, or refused by ValidateEmail400{"error": "invalid email", "code": "email_invalid_input"}
POST /sign-up/emailpassword is missing or fails the password rules400{"error": "invalid password", "code": "password_invalid_input"}
POST /sign-up/emailthe email already has an account409{"error": "an account with this email already exists", "code": "email_taken"}
POST /sign-in/emailunknown email, wrong password, or a user who has no password401{"error": "invalid email or password", "code": "invalid_credentials"}
POST /sign-outthe request has no session token401{"error": "missing session token", "code": "session_missing"}
POST /sign-outthe token belongs to no session, or its session is revoked or expired401the message and code of the reason: session_invalid, session_revoked, session_expired. With a cookie delivery the response also removes the cookie. See Sessions.
anya hook handler rejected the request with a typed errorthe error's statusthe error's public message and code
anytoo many requests. Sign-in and sign-up each allow 10 attempts a minute per client address (engine.RuleSignInAddress, engine.RuleSignUpAddress)429 with a Retry-After header: the seconds left until the limit resets{"error": "too many requests, please try again later", "code": "rate_limited"}
POST /sign-up/email, POST /sign-in/emailtoo many passwords are being hashed at once; see Bound the password hashes that run at once503 with a Retry-After header{"error": "the server is busy, please try again later", "code": "server_busy"}
anyBehemoth failed (the database is down, for example)500a generic message; the error's own text is logged, not sent

Sign-in gives the same answer for an unknown email and a wrong password, so the response does not show which addresses have an account. Sign-up does show it: a 409 says the address is registered. Two sign-ups for the same new address at the same moment get one account, and the other gets the same 409 with email_taken.

A unique column another plugin adds to users, such as the username plugin's, gets its own 409 code at sign-up: username_taken.

The codes are exported: emailpassword.ErrorCodeInvalidEmail, ErrorCodeInvalidPassword, ErrorCodeEmailTaken, and ErrorCodeInvalidCredentials. Branch on the code and not on the message.

A handler on one of the plugin's hook points that rejects a request should return one of the errs package's types. An untyped error (errors.New) is treated as a failure of the system: the client gets a 500 and the error is logged.

Hook points #

The plugin fires the auth.signUp.*, auth.signIn.*, and auth.signOut.* points. See Flow points for their payloads and failure codes.

Call the flows from code #

The routes are thin wrappers around two methods on the plugin. Use them from a CLI, a job, a test, or another plugin, after Boot:

go
user, err := plugin.SignUp(ctx, behemoth.M{
    "email":    "ada@example.com",
    "password": "correct horse battery",
})

result, err := plugin.SignIn(ctx, emailpassword.EmailAndPasswordCredentials{
    Email: "ada@example.com", Password: "correct horse battery",
})
// result.User, result.Session, result.RawToken

The two flows take their input in different forms. Sign-up's fields are open-ended (the profile fields, plus whatever a plugin adds), so it takes a behemoth.M. Sign-in needs exactly an email and a password, so it takes a struct, with an Extra map for input that only hook handlers read:

go
result, err := plugin.SignIn(ctx, emailpassword.EmailAndPasswordCredentials{
    Email:    "ada@example.com",
    Password: "correct horse battery",
    Extra:    behemoth.M{"captchaToken": token},
})

A handler on auth.signIn.before reads it as payload["captchaToken"], next to payload["email"]. The route fills Extra from the request body, so the same handler works for a request and for a call from code:

go
reg.OnBefore(
    hooks.HookSignInBefore,
    func(hctx *core.HookContext, payload behemoth.M) (behemoth.M, error) {
        token, _ := payload["captchaToken"].(string)
        if !captchaPasses(hctx.Ctx, token) {
            return nil, errs.NewInvalidInputError(
                "signin",
                "captcha",
                "captcha check failed",
                nil,
            )
        }
        return nil, nil
    },
    nil,
)

Both flows follow these rules:

  • They fire the same hook points as the routes, with the same payloads.
  • SignUp stores email, password, and the profile fields listed above. Other keys in the input are not stored, but handlers on auth.signUp.before see them, which is how a plugin accepts a field of its own (an invite code, for example).
  • Extra is not stored, and a key in it named email or password is ignored: the struct's fields are used.
  • Pass the context of the request you are handling when there is one. Hook handlers get the request from it, and the session records its IP address and user agent. With any other context, httpapi.RequestFrom(hctx.Ctx) is nil and the session has neither.
  • SignIn returns a *emailpassword.SignInResult, which is core.SignInResult: the user, the session, the raw token, and Method ("emailpassword"). Handlers on auth.signIn.after receive the same value.
  • SignIn returns the raw session token and delivers nothing. From a route of your own, hand the result to httpapi.WriteSignIn, which is what the plugin's route does. See Write a sign-in route.
  • Called before Boot, both return a configuration error.
  • SignUp returns typed errors for its own rejections too: check errs.IsCode(err, emailpassword.ErrorCodeEmailTaken), ErrorCodeInvalidEmail, or ErrorCodeInvalidPassword.
  • SignIn returns a typed error for a refused credential, so you can tell it from a failure:
go
result, err := plugin.SignIn(ctx, creds)
switch {
case err == nil:
    // signed in
case errs.IsCode(err, emailpassword.ErrorCodeInvalidCredentials):
    // unknown email, wrong password, or no password: ask again
default:
    // a hook's rejection, a rate limit, or a failure such as a database outage
}

Sign in by another identifier #

SignInWith is SignIn for a user who is named by something other than an email. A plugin that adds an identifier calls it and supplies the lookup. The password check, the second-factor checkpoint, the session, and the auth.signIn.* points are the same as for SignIn. The username plugin signs in this way:

go
result, err := plugin.SignInWith(ctx, emailpassword.IdentifierCredentials{
    // the payload key, and the Values key for rate-limit rules
    Key:      "username",
    Value:    name,
    Password: password,
    // SignInResult.Method
    Method:   "username",
    Find: func(
        ctx context.Context,
        s *store.Store,
        value string,
    ) (*models.User, error) {
        return s.FindUserBy(ctx, "username", value)
    },
})

SignInWith behaves as follows:

  • Find returns a NotFound error for an unknown identifier. Sign-in then answers invalid_credentials, as for a wrong password.
  • Handlers on auth.signIn.before see Value under Key, where an email sign-in has email. Find gets the value they left.
  • Value is published in Values under Key as it is, so pass it in the form a rate-limit rule should count by. No email is published.
  • The error message names the key: invalid username or password.

Set a password from your code #

go
admin := identity.WithCaller(ctx, identity.System("support-tool"))
err := plugin.ValidatePassword(newPassword)
if err != nil {
    // password_invalid_input
}
user, err := plugin.SetPassword(admin, userID, newPassword)

SetPassword sets the password of the account you name. It is an admin operation: it requires emailpassword.PermissionSetPassword (user:set_password), which only a system caller holds. A signed-in user gets 403 with the code insufficient_scope, and an anonymous caller the session error. Your code names itself with identity.System(name), and the audit log records that name.

plugin.SetPasswordUnchecked(ctx, userID, newPassword) is the same without the check of the caller. It is for a plugin that has established the right by its own means: the phone number plugin calls it after a code sent to the user's number was confirmed, for a caller who is anonymous. Don't call it from a route that takes the user id from its input.

Both behave as follows:

  • They apply the password rules, give a user without a password one, end every session of the user, and create none.
  • They send the core.MailPasswordChanged notice when a mail sender is configured.
  • They fire no points, and work with password reset by email off.
  • Call ValidatePassword first when a later refusal would cost you something, such as a code already used up.

passwords.SignOut(ctx) ends the session of the caller on ctx and fires the sign-out points. It is the flow behind POST /sign-out, and requires the permission emailpassword.PermissionSignOut (session:sign_out), which a signed-in user holds:

  • The caller is the one the router put on the request's context, or the one another transport put there. A caller that is not signed in gets the reason as a 401 session error, as from httpapi.RequireSession.
  • It ends the caller's own session only. A job that acts for a user (identity.System("job").For(userID)) has no session, and gets session_missing. To end another session from code, call ac.SessionManager.Revoke.
  • It writes nothing to a response, so the session's cookie stays with its browser. A route of yours that calls it removes the cookie afterwards with rctx.TokenCarrier.Clear(rctx); see Sessions.

Reject a sign-up from a hook #

A hook handler can reject a sign-up with its own status and message. Return a typed error from a handler on auth.signUp.before, data.user.beforeCreate, or data.user.afterCreate:

go
reg.OnBefore(
    hooks.HookUserBeforeCreate,
    func(hctx *core.HookContext, row behemoth.M) (behemoth.M, error) {
        if blocked(row[models.UserEmail]) {
            return nil, errs.NewInvalidInputError(
                "signup",
                "user",
                "this email domain is not allowed",
                nil,
            )
        }
        return row, nil
    },
    nil,
)

The client gets the status of the error's category (400 here) and its public message, and auth.signUp.failed fires with code rejected_by_hook. An untyped error (errors.New) from a data hook also stops the sign-up, but it counts as a failure of the system. The client gets a 500, the error is logged, and no failed point fires. errs.IsRejection(err) reports which of the two an error is. It is true for a typed error of category validation, conflict, unauthorized, forbidden, or rate limited.

Password reset #

A user who forgot their password asks for a link by email and sets a new password with it. Reset is off until you set Options.Reset.LinkURL.

The plugin does not send email. It hands the link to the mail sender you give Behemoth at Boot. See Mail.

StepWhoWhat happens
1clientposts an email to POST /password-reset/request
2pluginfinds the user, issues a single-use token, and hands the link to your mail sender
3yousend the message
4useropens the link, which is a page of your application: https://app.example.com/auth/reset?token=...
5your pageasks for the new password and posts it with the token to POST /password-reset/confirm
6pluginconsumes the token, sets the password and ends the user's sessions

Setup #

go
plugin := emailpassword.New(emailpassword.Options{
    Reset: emailpassword.ResetOptions{
        LinkURL: "https://app.example.com/auth/reset",
    },
})

ac, err := engine.Boot(ctx, app, db, engine.BootConfig{
    Mail: core.MailConfig{
        Sender: core.MailSenderFunc(
            func(ctx context.Context, msg core.MailMessage) error {
                return mailQueue.Enqueue(
                    ctx,
                    msg.To,
                    subjectFor(msg.Kind),
                    msg.URL,
                )
            },
        ),
    },
    // ...
})

Reset uses the core tokens table and, for its limit per email, the rate_limits table or Redis.

Your sender gets two kinds of message, both as a core.MailMessage:

KindWhenContent
core.MailPasswordReseta link was requestedURL, Token and ExpiresAt of the link
core.MailPasswordChangeda reset went throughno link. It tells the owner their password was changed, in case it was not them.
ResetOptions fieldDefaultMeaning
LinkURLempty: reset is offThe page of your application the link points to. Absolute, http or https. The plugin adds the token as the token query parameter and keeps any query the URL already has.
TTL1 hourHow long a link works. TokenConfig.TTLOverrides[core.TokenKindPasswordReset] takes precedence.
RequestLimit5 per 15 minutesReset requests allowed per email.
WaitForSendfalsefalse: the request returns once the message is queued, and a failed send is logged. true: the request waits for your sender, and a failed send revokes the link.
LeaveEmailUnverifiedfalseSet it to stop a completed reset from marking the email as verified.

With reset on, a missing mail sender, a LinkURL that is not an absolute URL, and a negative TTL are configuration errors from Boot.

examples/init runs reset end to end: a sender that prints the link (mail.go) and the page the link opens (pages.go).

Routes #

RouteBodyResult
POST /password-reset/requestemail, and optionally metadata (an object passed to your sender in MailMessage.Metadata)200 with {"status": "ok"}, whether or not the email has an account
POST /password-reset/confirmtoken, password200 with {"status": "password_reset"}. No session token: the user signs in with the new password.
RouteWhenStatusCode
requestthe body is not valid JSON, or email is not an address400request_validation_error, email_invalid_input
requesttoo many requests for this email or from this client address429rate_limited
confirmtoken or password is missing400token_invalid_input, password_invalid_input
confirmthe password fails the plugin's rules400password_invalid_input. The link stays usable.
confirmthe link is unknown, expired, already used, or replaced by a newer one401invalid_reset_token
confirmtoo many passwords are being hashed at once. The link stays usable.503 with Retry-Afterserver_busy

The request route gives one answer for an unknown email, a known one, and a send that failed, so the response does not show which addresses have an account. Confirm gives one answer for every link it refuses.

What a reset does #

A reset has these effects:

  • It sets the password under the same rules as sign-up. MinPasswordLength, MaxPasswordLength, and ValidatePassword apply. The password is checked before the token, so a refused password does not cost the user the link.
  • The link works once. It is used up at the moment the password is written. If that write fails (a database error, a data hook's veto), the link is spent and the user asks for a new one.
  • A new link replaces the old one. A user has one live reset link.
  • It ends every session of the user. They are revoked with the reason password_reset (emailpassword.SessionRevokedPasswordReset).
  • It does not sign the user in. The user signs in with the new password, so a second factor still applies.
  • It gives a password to a user who had none. A user created by a magic link or a provider can ask for a reset link, and using it creates their credential account.
  • It marks the email as verified. The link was sent to the address, so using it shows the user controls it. Set LeaveEmailUnverified if verified should only mean that your own verification passed.
  • It is tied to the address it was sent to. If the user's email changes before the link is used, the link is refused.
  • It tells the user. A core.MailPasswordChanged message goes to the account's address in the background. If it can't be queued or sent, that is logged and the reset still stands.
  • Asking for a link changes nothing. The old password and the sessions keep working until the link is used.

Call the flows from code #

go
sent, err := plugin.RequestPasswordReset(
    ctx,
    emailpassword.ResetRequest{
        Email: "ada@example.com",
    },
)
// sent.UserID, sent.TokenID, sent.ExpiresAt

user, err := plugin.ResetPassword(ctx, rawToken, newPassword)

The flows behave as follows:

  • Unlike the route, RequestPasswordReset reports an unknown email (emailpassword.ErrNoAccount) and a failed send.
  • ResetPassword returns a typed error with the code emailpassword.ErrorCodeInvalidResetToken for a link it refuses, and a validation error for a refused password.
  • With reset off, both return a configuration error.

Hooks #

The plugin declares six points when reset is on.

PointPhasePayload or result
auth.passwordReset.beforeRequest (emailpassword.HookResetRequestBefore)beforeemail and metadata. A handler may rewrite them or stop the request.
auth.passwordReset.afterRequest (emailpassword.HookResetRequestAfter)aftera *emailpassword.ResetRequestResult: user id, email, token id, expiry. Not the token.
auth.passwordReset.requestFailed (emailpassword.HookResetRequestFailed)failedcodes user_not_found, issue_failed, send_failed, rejected_by_hook
auth.passwordReset.before (emailpassword.HookResetBefore)beforepassword, and email when the token is valid. A handler can stop the reset; what it writes to the payload is not used.
auth.passwordReset.after (emailpassword.HookResetAfter)afterthe *models.User
auth.passwordReset.failed (emailpassword.HookResetFailed)failedcodes invalid_token, user_not_found, email_changed, rejected_by_hook

The after and failed points are audited under their point names. Issuing and consuming the token also fire the token manager's points with the kind password_reset, and each ended session fires the session revoke points.

Rate limits #

RuleLimitsDefault
emailpassword.RuleResetRequestAddressreset requests per client address10 a minute
emailpassword.RuleResetConfirmAddressreset attempts per client address10 a minute
emailpassword.RuleResetRequestEmailreset requests per emailReset.RequestLimit, 5 per 15 minutes

The rules are attached to the flows' before points, auth.passwordReset.beforeRequest and auth.passwordReset.before, so they also hold for RequestPasswordReset and ResetPassword called from your own code or another transport. A call from code with no client address is counted per email only. Change a limit, or turn a rule off, by its name with RateLimitConfig; see Hooks.

The rule per email counts requests for unknown emails too, so a 429 does not show whether the address has an account.

Limits #

The plugin has no password change for a signed-in user. To add one, write a plugin that depends on emailpassword, checks the caller and the current password itself, and calls SetPasswordUnchecked, so that the password rules stay in one place.