Plugin: Re-verification

Relevant source files

The following files were used as context for generating this wiki page:

• packages/plugins/reverify/src/index.ts
• packages/plugins/reverify/src/client.ts
• packages/plugins/reverify/README.md
• packages/plugins/reverify/package.json
• packages/plugins/reverify/tests/reverify.test.ts

The Re-verification plugin for Better Auth provides a mechanism to prompt an already authenticated user to re-verify their identity. This is typically used before performing sensitive actions, such as changing a password or deleting an account, by requiring the user to provide a valid form of authentication again.

This plugin exposes a server-side endpoint to handle the verification logic and a corresponding client-side helper to call this endpoint easily. The primary method of re-verification implemented is via the user's password.

Sources: packages/plugins/reverify/README.md:3-4, packages/plugins/reverify/package.json:3-4, packages/plugins/reverify/src/index.ts:24-26

Architecture

The plugin is split into two main parts: a server-side component and a client-side component.

• Server-Side (BetterAuthPlugin): Defines the API endpoint /reverify/password, which contains the logic for checking the provided password against the authenticated user's credentials.
• Client-Side (BetterAuthClientPlugin): Provides a helper method on the better-auth client instance, allowing developers to easily call the re-verification endpoint from the frontend.

This separation allows for a clean integration into the Better Auth ecosystem, where the server handles the secure logic and the client provides a convenient interface.

Sources: packages/plugins/reverify/src/index.ts:9, packages/plugins/reverify/src/client.ts:7

Server-Side Implementation

The server-side logic is encapsulated within the reverify function, which returns a BetterAuthPlugin object. This plugin registers a single endpoint for handling password re-verification.

Sources: packages/plugins/reverify/src/index.ts:9-45

API Endpoint: reverifyPassword

This endpoint is responsible for validating a user's password for an active session.

Property	Value	Description
ID	reverifyPassword	The identifier for the endpoint within the plugin.
Path	/reverify/password	The URL path for the API endpoint.
Method	POST	The HTTP method used for the request.
Middleware	sessionMiddleware	Ensures that the request is made by an authenticated user with a valid session.
Body Schema	{ password: string }	The request body must contain the user's password as a string.

Sources: packages/plugins/reverify/src/index.ts:12-20

Verification Flow

The following diagram illustrates the logic executed by the reverifyPassword endpoint upon receiving a request.

This diagram shows the server-side flow for re-verifying a user's password.

Sources: packages/plugins/reverify/src/index.ts:21-44

Error Handling

The endpoint handles password validation errors specifically.

• If the password check fails with an APIError and a code of INVALID_PASSWORD, it gracefully returns { valid: false }.
• For any other type of error during the password check, it throws a generic INTERNAL_SERVER_ERROR to avoid leaking implementation details.

Sources: packages/plugins/reverify/src/index.ts:28-41

Client-Side Implementation

The client-side component simplifies interaction with the re-verification API.

Sources: packages/plugins/reverify/src/client.ts, packages/plugins/reverify/tests/reverify.test.ts

Client Plugin Configuration

To use the client-side helper, the reverifyClientPlugin must be added to the better-auth client options.

// Example from tests/reverify.test.ts
import { reverifyClientPlugin } from "../src/client";
import { getTestInstance } from "@better-auth-kit/tests";
import { auth } from "./auth";

const { client } = await getTestInstance(auth, {
    clientOptions: {
        plugins: [reverifyClientPlugin()],
    },
});

Sources: packages/plugins/reverify/tests/reverify.test.ts:8-12

The reverifyClientPlugin function defines the client-side interface for the plugin. It maps the /reverify/password path to the POST method.

Sources: packages/plugins/reverify/src/client.ts:7-14

Usage Example

Once configured, the client instance will have a reverify.password method available. This method sends the re-verification request to the server.

// Example from tests/reverify.test.ts
const { data: isValid, error } = await client.reverify.password({
    password: testUser.password,
    fetchOptions: {
        headers, // Must include session headers
    },
});

expect(isValid?.valid).toBe(true);

const { data: isInvalid } = await client.reverify.password({
    password: "wrong_password",
    fetchOptions: {
        headers,
    },
});

expect(isInvalid?.valid).toBe(false);

Sources: packages/plugins/reverify/tests/reverify.test.ts:21-36

End-to-End Re-verification Flow

This sequence diagram shows the complete interaction between the client and server for both a successful and a failed re-verification attempt.

This diagram illustrates the client-server communication during a password re-verification.

Sources: packages/plugins/reverify/src/index.ts:12-44, packages/plugins/reverify/tests/reverify.test.ts:21-36

Summary

The Re-verification plugin is a simple yet powerful addition to the better-auth-kit ecosystem. It provides a standardized way to re-authenticate users before they perform sensitive operations, enhancing application security. By leveraging the existing session management and providing clear client-side helpers, it offers a straightforward implementation for developers.

Sources: packages/plugins/reverify/README.md, packages/plugins/reverify/package.json