Registry / auth-security / better-auth-custom-credentials

better-auth-custom-credentials

library0.1.8jsnpmunverified

This package provides a plugin for the `better-auth` library, enabling highly customizable credentials-based authentication. It allows developers to integrate `better-auth` with virtually any backend authentication system, such as Rails, Django, custom APIs, or LDAP, while leveraging `better-auth`'s existing session management infrastructure. Currently at version 0.1.8, the library is in active development, meaning minor versions may introduce breaking changes to its API. Key differentiators include the ability to define flexible input schemas using Zod for robust validation, store arbitrary custom data (like JWTs or permissions) directly within `better-auth` sessions, configure auto sign-up features, and set custom session expiry per authentication method. It offers a comprehensive solution for adapting diverse authentication logic to the `better-auth` ecosystem.

auth-security

npm install better-auth-custom-credentials

github ↗package ↗

INSTALL

IMPORT

SIG · BETTER-AUTH-CUSTOM

better-auth-custom-credentials

auth-securityjavascriptv0.1.8

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

credentialsPlugin

✓ import { credentialsPlugin } from 'better-auth-custom-credentials';

✗ const credentialsPlugin = require('better-auth-custom-credentials');

This is the main server-side plugin for Better Auth, primarily used in ESM contexts.

extendAuthClientWithCredentials

✓ import { extendAuthClientWithCredentials } from 'better-auth-custom-credentials';

✗ const extendAuthClientWithCredentials = require('better-auth-custom-credentials').extendAuthClientWithCredentials;

Used client-side, typically with React/Next.js, to extend the `better-auth` client with credentials methods. Requires `createAuthClient` from `better-auth/react`.

✓ import { z } from 'zod';

Zod is a peer dependency and is essential for defining the input schema for the credentials plugin.

Demonstrates client-side setup for `better-auth-custom-credentials`, including extending the auth client, signing in with custom credentials, and retrieving session data.

import { createAuthClient } from 'better-auth/react'; import { extendAuthClientWithCredentials } from 'better-auth-custom-credentials'; // Create a basic Better Auth client, ensuring credentials are included for session management. // This client will interact with your server-side Better Auth setup. export const authClient = extendAuthClientWithCredentials( createAuthClient({ fetch: (url, init) => { return fetch(url, { ...init, credentials: 'include', // Important: Ensures cookies are sent with requests cache: 'no-store', }); }, }) ); async function authenticateAndGetSession() { console.log('Attempting to sign in with credentials...'); // Sign in using the credentials method. The input object must match the server-side Zod schema. const result = await authClient.signIn.credentials({ email: 'user@example.com', otp: '123456', rememberMe: true, }); if (result.ok) { console.log('Sign in successful!'); // Retrieve the session data after successful authentication. const { data: session } = await authClient.getSession(); const jwt = session?.data?.jwt; const permissions = session?.data?.permissions; console.log('Session Data:', session); console.log('JWT:', jwt); console.log('Permissions:', permissions); } else { console.error('Sign in failed:', result.reason); } } // Example call (in a real app, this would be triggered by a form submission or similar event) // authenticateAndGetSession();

Debug

Known issues

breakingAs a pre-1.0 package (version 0.1.8), the API is subject to frequent and significant breaking changes between minor versions. Always consult the latest README and changelog before upgrading.

fix

Review the official GitHub repository for the latest API documentation and migration guides when updating versions. Pin exact versions in `package.json` to prevent unexpected breaks.

affects: >=0.1.0

gotchaThe `verify` function within `credentialsPlugin` must strictly return an object conforming to `{ ok: boolean; reason?: string; user?: User; meta?: Record<string, any> }` on success or failure. An incorrect return type can lead to authentication failures or incomplete session data.

fix

Ensure your `verify` implementation consistently returns an object with an `ok` boolean, an optional `reason` (for failures), and `user` and `meta` (for success) to be picked up by Better Auth's session management.

affects: >=0.1.0

gotchaWhen using `createAuthClient` on the client-side, it is crucial to include `credentials: 'include'` in your `fetch` configuration. Omitting this will prevent cookies (like session tokens) from being sent with requests, leading to unauthenticated requests or session management issues.

fix

Modify your `createAuthClient` configuration to always pass `{ credentials: 'include' }` in the `fetch` options: `createAuthClient({ fetch: (url, init) => fetch(url, { ...init, credentials: 'include' }) })`.

affects: >=0.1.0

gotchaForgetting to define a robust `inputSchema` using Zod within the `credentialsPlugin` configuration can lead to insecure or unexpected authentication behavior, as input validation will be absent or incomplete.

fix

Always provide a comprehensive `z.object()` schema to the `inputSchema` property of `credentialsPlugin` to define and validate all expected input fields from the client-side form.

affects: >=0.1.0

Errors

Common errors & fixes

TypeError: credentialsPlugin is not a function

Attempting to import `credentialsPlugin` using CommonJS `require()` syntax or incorrect named import from an ESM-only package.

fix

Ensure you are using ECMAScript Modules (ESM) import syntax: `import { credentialsPlugin } from 'better-auth-custom-credentials';`.

ZodError: Invalid input

The data sent from the client-side `authClient.signIn.credentials()` call does not conform to the `inputSchema` defined with Zod on the server-side `credentialsPlugin`.

fix

Review your server-side `inputSchema` and ensure the client-side `signIn.credentials` method is sending an object with the exact keys and types expected by the schema.

Error: Cannot find module 'better-auth' or 'zod'

The `better-auth` or `zod` peer dependencies are not installed in your project.

fix

Install the required peer dependencies: `npm install better-auth zod` or `pnpm add better-auth zod`.

Type 'Partial<User>' is not assignable to type 'User'. Property 'id' is missing in type 'Partial<User>' but required in type 'User'.

The `user` object returned by the `verify` function does not contain all required properties as defined by your application's `User` type for Better Auth.

fix

Ensure the `user` object returned from `verify` includes all mandatory fields (e.g., `id`, `email`, `name`) that your `better-auth` configuration expects for a `User`.

Upgrade

Version history

0.1.8latest on npm

Audit

Dependencies

better-authrequiredCore authentication library that this plugin extends.

zodrequiredUsed for defining and validating input schemas for the custom credentials.

Agent activity

23 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/Pradumn27/better-auth-custom-credentials ↗

packagehttps://www.npmjs.com/package/better-auth-custom-credentials ↗