Skip to Content
better-auth-plugins

Security alerts

Tell users about security-relevant changes to their account, with a "This wasn't me" link.

The security alerts plugin tells users when something security-relevant happens to their account: a sign-in from a new device, a changed password or email address, a passkey added, two-factor turned off. You send the alerts (email, SMS, push); the plugin decides when, and what's in them.

  • Ten alert types, each on or off. Types whose plugin you don't use (passkey, two-factor, API key) never fire.
  • New-device detection without storing the device: a keyed hash of the browser and OS family, no alert on the first sign-in, devices forgotten after 90 days without a sign-in.
  • An email change is reported to the old address, so someone who took over the account can't hide it.
  • A "This wasn't me" link that signs out every session and blocks the password. Opening the link changes nothing, so mail scanners can't trigger it.
  • Never slows down or fails a request: alerts run in the background when configured, and errors are logged.
  • Works on its own; with the audit log, every alert is recorded too.

Installation

Install the package

npm install @checodo/better-auth-security-alerts

Add the plugin to your auth config

auth.ts
import { betterAuth } from "better-auth";
import { securityAlerts } from "@checodo/better-auth-security-alerts";

export const auth = betterAuth({
  plugins: [
    securityAlerts({
      sendAlert: async ({ type, email, details, secureAccountUrl }) => {
        await sendEmail({
          to: email,
          subject: `Security alert: ${type}`,
          text: `${details.device.label}, ${details.at.toISOString()}.\nNot you? ${secureAccountUrl}`,
        });
      },
      secureAccount: {
        callbackURL: "/secure-account",
        resetPasswordURL: "/reset-password",
      },
    }),
  ],
});

Migrate the database

The plugin adds a knownDevice table (see Schema).

npx auth@latest migrate

Add the client plugin

auth-client.ts
import { createAuthClient } from "better-auth/client";
import { securityAlertsClient } from "@checodo/better-auth-security-alerts/client";

export const authClient = createAuthClient({
  plugins: [securityAlertsClient()],
});

Usage

Alert types

TypeWhenSent toLink
new-deviceA sign-in, by any method, from a browser or device not seen beforethe useryes
password-changedchangePassword, or an admin's setUserPasswordthe useryes
password-reset-requestedA reset link or code was requested (email, email OTP, phone number)the userno
password-resetThe password was set with a reset link or codethe useryes
email-changedThe email address changed, by any flowthe old addressyes
passkey-addedA passkey was registered (passkey plugin)the useryes
passkey-removedA passkey was deletedthe useryes
two-factor-disabledTwo-factor was turned off (two-factor plugin)the useryes
account-linkedA social or other account was linked (not the first one, at sign-up)the useryes
api-key-createdAn API key was created (api-key plugin)the useryes

Every type is on by default. Turn single types off with alerts:

securityAlerts({
  sendAlert: async () => {},
  alerts: { "account-linked": false, "api-key-created": false },
});

password-reset-requested has no "This wasn't me" link: nothing has changed yet, so the alert only says "ignore this if it wasn't you". It is only sent for users that exist; the endpoint answers the same either way.

Sending alerts

sendAlert gets the alert type, the user (after the change), the address to send to (email), the details, and the secureAccountUrl, and the request as its second argument. Send the alert however you like; one template per type works well.

securityAlerts({
  sendAlert: async ({ type, user, email, details, secureAccountUrl }) => {
    const what = {
      "new-device": `New sign-in on ${details.device.label}`,
      "password-changed": "Your password was changed",
      "password-reset-requested": "Someone asked to reset your password",
      "password-reset": "Your password was reset",
      "email-changed": `Your email address was changed to ${details.newEmail}`,
      "passkey-added": `Passkey "${details.passkeyName ?? "unnamed"}" added`,
      "passkey-removed": `Passkey "${details.passkeyName ?? "unnamed"}" removed`,
      "two-factor-disabled": "Two-factor authentication was turned off",
      "account-linked": `Your ${details.providerId} account was linked`,
      "api-key-created": `API key "${details.apiKeyName ?? "unnamed"}" created`,
    }[type];
    await sendEmail({
      to: email,
      subject: what,
      text: [
        `Hi ${user.name},`,
        `${what} (${details.at.toUTCString()}, IP ${details.ipAddress ?? "unknown"}).`,
        details.actor === "admin" ? "An administrator made this change." : "",
        secureAccountUrl ? `Wasn't you? Secure your account: ${secureAccountUrl}` : "",
      ].join("\n"),
    });
  },
});

With better-auth's advanced.backgroundTasks configured, sendAlert runs after the response is sent, so a slow mail server doesn't slow down sign-ins. Without it, it is awaited. Either way, errors are logged as [security-alerts] sendAlert threw an error and never reach the client.

Alert details

FieldTypesWhat
atallWhen it happened
ipAddressallThe request's IP address, as better-auth sees it (advanced.ipAddress)
userAgentallThe request's user agent
deviceall{ browser, os, label }, e.g. "Chrome on macOS"
actorall"user" or "admin" (see Admin actions)
newEmailemail-changedThe new address, masked: j***@example.com
channelpassword-reset-requested, password-reset"email" or "phone-number"
providerIdaccount-linkedE.g. "github"
passkeyId, passkeyNamepasskey-added, passkey-removedThe passkey and the name the user gave it
apiKeyId, apiKeyNameapi-key-createdThe key's id and name; never the key

The new address in email-changed is masked because the alert goes to the old address, which may be in someone else's hands by then.

New devices

When a user signs in (with a password, OAuth, a magic link, a passkey, an OTP, ...), the plugin compares the browser and OS family with the devices the user signed in from before:

  • Known device: no alert. Versions don't count, so a browser update isn't a new device.
  • New device: an alert, and the device is remembered.
  • First sign-in: the user has no devices on record yet (a new user, or the first sign-in after you added the plugin). No alert, the device is remembered.
  • Not seen for 90 days (newDevice.expiresIn): new again.

Session rotations, impersonation by an admin, and failed sign-ins don't count. With two-factor, one sign-in alerts once.

The plugin stores no user agent or IP address of its own: knownDevice holds a hash of the browser family, OS family, and (with newDevice.includeIp) network, keyed with your auth secret, plus a label like "Chrome on macOS" for the device list.

Changing secret (or BETTER_AUTH_SECRET) changes every hash: each user's next sign-in from every device alerts once.

To tell networks apart too, set newDevice.includeIp: a sign-in from another /24 (IPv4) or /48 (IPv6) range counts as a new device. Phones and laptops change networks often, so this alerts much more.

newDevice.isNewDevice lets you decide yourself, e.g. to trust a company network or to ignore a test account. Return true to alert, false not to, or undefined for the default:

securityAlerts({
  sendAlert: async () => {},
  newDevice: {
    isNewDevice: ({ ipAddress, known, firstSignIn }) => {
      if (ipAddress?.startsWith("10.")) return false; // office network
      return undefined; // default: !known && !firstSignIn
    },
  },
});

The built-in parser knows the common browsers (Chrome, Edge, Firefox, Safari, Opera, Samsung Internet, Vivaldi, Yandex, Brave) and systems (Windows, macOS, iOS, Android, ChromeOS, Linux), and prefers User-Agent Client Hints (Sec-CH-UA, Sec-CH-UA-Platform) when the browser sends them. To use a parser library instead, pass newDevice.getDevice:

import { UAParser } from "ua-parser-js";

securityAlerts({
  sendAlert: async () => {},
  newDevice: {
    getDevice: (headers) => {
      const { browser, os } = UAParser(headers.get("user-agent") ?? "");
      return { browser: browser.name ?? null, os: os.name ?? null };
    },
  },
});

"This wasn't me"

With the secureAccount option, every alert except password-reset-requested gets a secureAccountUrl: a single-use link, valid for 7 days (secureAccount.expiresIn). It works in three steps:

  1. The link (GET /security-alerts/secure-account/:token) checks the token and redirects to your page, secureAccount.callbackURL, with ?token=... (or ?error=INVALID_TOKEN). It changes nothing: mail scanners and link previews open links in emails, and must not lock anyone out.
  2. Your page asks the user to confirm.
  3. On confirmation, it calls secureAccount with the token, which:
    • signs out every session of the user, everywhere;
    • makes every device new again, so the next sign-in from any of them alerts;
    • removes what the alert was about, if an attacker could sign in with it: the passkey of passkey-added, the account of account-linked, the API key of api-key-created;
    • with secureAccount.emailChange: "restore", puts the old email address back (see Email changes);
    • blocks the password and sends a reset link (secureAccount.password, see below);
    • records security.account-secured in the audit log, if you use it, and calls secureAccount.onSecured (see After securing).
app/secure-account/page.tsx
"use client";

import { useSearchParams } from "next/navigation";
import { useState } from "react";
import { authClient } from "@/lib/auth-client";

export default function SecureAccountPage() {
  const params = useSearchParams();
  const token = params.get("token");
  const [state, setState] = useState<"ask" | "busy" | "done" | "failed">("ask");

  if (!token || params.get("error")) {
    return <p>This link is invalid or has expired. Sign in and change your password.</p>;
  }
  if (state === "done") {
    return (
      <p>
        Your account is secured: every session is signed out. We sent you a link to set a
        new password.
      </p>
    );
  }

  const secure = async () => {
    setState("busy");
    const { error } = await authClient.securityAlerts.secureAccount({ token });
    setState(error ? "failed" : "done");
  };

  return (
    <div>
      <meta name="referrer" content="no-referrer" />
      <h1>Secure your account</h1>
      <p>
        This signs you out everywhere and blocks your current password. You'll get an email
        to set a new one.
      </p>
      <button type="button" onClick={secure} disabled={state === "busy"}>
        Secure my account
      </button>
      {state === "failed" && <p>This link is invalid or has expired.</p>}
    </div>
  );
}

The playground has a working page at /secure-account.

The token is in the page's URL. Keep it out of Referer headers to other sites (analytics, fonts, images) with Referrer-Policy: no-referrer on that page, e.g. <meta name="referrer" content="no-referrer" />.

Email changes

The link of an email-changed alert goes to the old address. What confirming it does about the email depends on secureAccount.emailChange:

ValueWhat happens
"keep" (default)The new address stays, and the reset link goes there.
"restore"The old address is put back (marked verified: the person just opened a link sent to it), and the reset link goes there. Not if another account has the address by now.

"restore" undoes the classic takeover: an attacker signs in, changes the email to their own, and resets the password. But it trusts the old mailbox: if a user moved away from an address someone else took over, "restore" hands the account to whoever holds it. Choose what fits your users; with "keep", changing the address back is up to your support.

Securing an account doesn't send alerts about its own changes, so the replaced address gets no email-changed alert.

After securing

secureAccount.onSecured runs after an account was secured, for what the plugin can't do itself: revoke API keys kept in secondary storage, open a support ticket, tell your team.

securityAlerts({
  sendAlert: async () => {},
  secureAccount: {
    callbackURL: "/secure-account",
    resetPasswordURL: "/reset-password",
    onSecured: async ({ user, alert, password, removed, restoredEmail }) => {
      await sendEmail({
        to: "security@example.com",
        subject: `Account secured: ${user.email}`,
        text: `After a ${alert} alert. Password: ${password}. Removed: ${removed ?? "nothing"}. Restored email: ${restoredEmail ?? "no"}.`,
      });
    },
  },
});

It runs like sendAlert (in the background with advanced.backgroundTasks); errors are logged.

What it can't undo

  • Signed-out devices with a cookie cache. With better-auth's session.cookieCache, a signed-out device keeps working until its cached cookie expires (cookieCache.maxAge, 5 minutes by default), like after any revoked session. The plugin can't reach that cookie; keep maxAge short (a minute or two) if you use the "This wasn't me" link, or turn the cookie cache off.
  • Two-factor that was turned off stays off; the user turns it on again after signing in.
  • API keys in secondary storage (the api-key plugin's storage: "secondary-storage") aren't removed, only keys in the database. Revoke them in onSecured.

What happens to the password

Whoever signed in probably knows the password, so signing out alone isn't enough. secureAccount.password decides:

ValueWhat happens
"block" (default)The current password stops working, and a reset link is sent. The attacker can't sign in with it again; the user sets a new one.
"send-reset"A reset link is sent; the current password keeps working until the user resets it.
"none"Only the sessions are signed out.

The reset link is the same as better-auth's requestPasswordReset sends: it goes through emailAndPassword.sendResetPassword and leads to secureAccount.resetPasswordURL (required unless password is "none"). Without sendResetPassword, "block" and "send-reset" act like "none", and the plugin logs a warning at startup: a blocked password could not be reset. Users without a password (only social sign-in) are only signed out.

Device list

Users can see the devices they signed in from, and forget one; the next sign-in from it alerts again.

const { data: devices } = await authClient.securityAlerts.listDevices();
// [{ id, label: "Chrome on macOS", lastSeenAt, createdAt, expiresAt, current: true }, ...]

await authClient.securityAlerts.forgetDevice({ id: "device-id" });

listDevices only shows devices seen within newDevice.expiresIn; current marks the device of the request. Both need a session and only see the signed-in user's devices.

Admin actions

When an admin changes someone's account (the admin plugin's setUserPassword, updateUser with a new email, ...), the user gets the alert, with details.actor: "admin". adminActions changes that:

securityAlerts({
  sendAlert: async () => {},
  adminActions: {
    alert: true, // false: no alerts for changes an admin makes
    showActor: false, // details.actor is always null
  },
});

Avoiding duplicate emails

Some better-auth flows send their own email for the same event. The plugin always sends every alert type that is on; decide per type which email you want:

Alertbetter-auth's own emailTo keep only one
email-changeduser.changeEmail.sendChangeEmailConfirmation asks the old address to approve the change, before it happensTurn the alert off, or keep both: one asks, one reports
password-reset-requestedemailAndPassword.sendResetPassword (or the OTP) goes to the same addressTurn the alert off unless you reset by phone number
password-resetemailAndPassword.onPasswordReset, if your callback sends an emailSend it from one of the two

To turn an alert off only in some cases, check type (and details) in sendAlert and return without sending:

securityAlerts({
  sendAlert: async ({ type, details }) => {
    // The reset email itself already reaches the address.
    if (type === "password-reset-requested" && details.channel === "email") return;
    // ... send the others
  },
});

Audit log

With the audit log plugin installed, the plugin records security.alert-sent for every alert (status: "failure" when sendAlert threw; metadata.alert is the type) and security.account-secured for every secured account. No addresses or tokens go into the events. The two plugins don't depend on each other.

Rate limits

POST /security-alerts/secure-account is limited to 5 requests per minute per IP (when better-auth's rate limiter is on). Change it with rateLimit.customRules:

betterAuth({
  rateLimit: {
    customRules: { "/security-alerts/secure-account": { window: 60, max: 10 } },
  },
});

Limits

  • An email change is only reported when the plugin can tell the old address: changes through better-auth's endpoints and the admin plugin. Server code that changes an email outside a request isn't reported.
  • Alerts need a request to tell the device and IP address; changes made by server code outside a request (linking an account, say) are reported with empty request details.
  • Users with placeholder emails (Sign-In with Ethereum, phone number, Steam, ...) get alerts with that address as email: skip addresses ending in .invalid in sendAlert, or send them another way.
  • Without advanced.backgroundTasks, sendAlert runs before the response: a reset request for an existing email then takes longer than for an unknown one, like better-auth's own reset email does. The plugin logs a warning at startup while password-reset-requested is on; configure background tasks so response times don't tell which emails have an account.
  • phoneNumber is assumed to be the phone-number plugin's field name.
  • Organization API keys alert the user who created them.

Schema

Table: knownDevice

Prop

Type

The "This wasn't me" links use better-auth's own verification table.

To rename the table or its columns, use the schema option:

auth.ts
securityAlerts({
  sendAlert: async () => {},
  schema: {
    knownDevice: {
      modelName: "known_devices",
      fields: { lastSeenAt: "last_seen_at" },
    },
  },
});

Error codes

Exported as SECURITY_ALERTS_ERROR_CODES from both entry points, to compare with error.code:

import { SECURITY_ALERTS_ERROR_CODES } from "@checodo/better-auth-security-alerts/client";

if (error?.code === SECURITY_ALERTS_ERROR_CODES.INVALID_TOKEN.code) {
  // show "This link is invalid or has expired"
}
CodeStatusWhen
INVALID_TOKEN400secureAccount with an unknown, used, or expired token, or without the secureAccount option
DEVICE_NOT_FOUND404forgetDevice with an id that isn't one of the user's devices

Options

Prop

Type

New device options

Prop

Type

Secure account options

Prop

Type

Admin actions options

Prop

Type

On this page