SMS and one-time codes

Plugins that send text messages hand them to an SMS sender you give Behemoth at Boot. Behemoth writes no message text and talks to no provider. The phone number plugin uses it.

It works like the mail sender, with a code where a mail has a link.

The sender #

go
ac, err := engine.Boot(ctx, app, db, engine.BootConfig{
    SMS: core.SMSConfig{
        Sender: core.SMSSenderFunc(
            func(ctx context.Context, msg core.SMSMessage) error {
                return provider.Send(ctx, msg.To, textFor(msg.Kind, msg.Code))
            },
        ),
    },
})
defer ac.SMS.Close(context.Background())
SMSMessage fieldContent
Kindwhat the message is for: core.SMSPhoneVerification, core.SMSSignIn, core.SMSPasswordReset, and the two-factor plugin's core.SMSTwoFactorSetup and core.SMSTwoFactorCode
Tothe number, in E.164 form
Codethe one-time code. It is a credential: do not log it.
ExpiresAtwhen the code stops working
Userthe account the message is about
Metadatawhat the request carried for you, such as a locale. It is client input.
SMSConfig fieldDefaultMeaning
SendernoneYour sender. Without one, a plugin that sends fails Boot.
Workers4Background sends running at once.
QueueSize256Background sends that may wait.
SendTimeout30 secondsHow long one background send may take.

The sender and the queue behave as follows:

  • Your provider's API key belongs to your sender. It is not part of SMSConfig.
  • A plugin either waits for your sender or queues the message. The phone number plugin queues by default (WaitForSend).
  • The queue is in memory and does not retry, like the mailer's. If you need retries, use a sender that puts the message on your own queue.
  • Call ac.SMS.Close(ctx) at shutdown. Mail and SMS have separate queues.
  • Messages are counted in behemoth.sms.sent, by kind and result (sent, error, dropped).

One-time codes #

ac.Codes issues and checks the short numeric codes a text message carries. A plugin of yours can use it:

go
code, issued, err := ac.Codes.Issue(
    ctx,
    "myplugin.confirm",
    userID,
    core.CodeOptions{},
)
// send code ...
consumed, err := ac.Codes.Consume(ctx, "myplugin.confirm", userID, typed)
if errs.IsCodeRejection(err) {
    // wrong, expired, used, or out of attempts
}
CodeOptions fieldDefaultMeaning
Length6Digits, 4 to 12.
TTL5 minutesHow long the code works.
MaxAttempts5Tries, the right one included.
MetadatanoneStored with the code and returned by Consume.

Codes behave as follows:

  • There is one live code per kind and subject. Issuing another replaces it.
  • Only a keyed hash is stored, in the core verification_codes table. The table is new in core. Generate and apply a migration before you deploy a version that has it, whether or not you use codes, because deleting a user clears the user's codes from it.
  • Consume gives one error for every refusal, with the code code_invalid.
  • Use a user id as the subject when the code belongs to a user: Store.DeleteUser removes the codes whose subject is the user's id.
  • Expired codes that were never used stay until a purge removes them. ac.Store.Purge does on every run. See Remove old rows.

A code is not a token. Use ac.TokenManager for a long secret that travels in a link, and a code for a short one a person types.