Registry / auth-security / better-auth-sync

better-auth-sync

library0.2.0jsnpmunverified

better-auth-sync is a plugin for the Better Auth system, designed to synchronize authentication data to external databases via webhooks. It offers first-class integration and helper functions specifically for Convex, enabling real-time mirroring of user and session data. The current stable version is 0.2.0, indicating it is an early-stage but actively developed package. While a specific release cadence isn't defined, its low version number suggests ongoing evolution and potential for rapid iteration. Key differentiators include its tight integration with Better Auth's plugin architecture and specialized utilities for Convex, such as schema definitions, JWT handling, and webhook verification, streamlining complex authentication setups involving external data stores.

auth-security database web-framework

npm install better-auth-sync

package ↗

INSTALL

IMPORT

SIG · BETTER-AUTH-SYNC

better-auth-sync

auth-securityjavascriptv0.2.0

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.

syncPlugin

✓ import { syncPlugin } from 'better-auth-sync';

✗ const syncPlugin = require('better-auth-sync').syncPlugin;

Primary plugin for Better Auth to enable webhook syncing.

convexJwt

✓ import { convexJwt } from 'better-auth-sync/jwt';

✗ import { convexJwt } from 'better-auth-sync';

Imported from a subpath, specifically for Convex JWT integration. Ensure correct subpath import.

authTables

✓ import { authTables } from 'better-auth-sync/convex';

✗ import { authTables } from 'better-auth-sync/schema';

Helper object for defining mirrored auth tables in Convex schema, imported from the `/convex` subpath.

createConvexBetterAuth

✓ import { createConvexBetterAuth } from 'better-auth-sync/react';

✗ import { createConvexBetterAuth } from 'better-auth-sync';

React hook creator for integrating Convex auth context, specific to the `/react` subpath.

This code snippet demonstrates how to configure Better Auth with the `better-auth-sync` plugin and `convexJwt` for JWT integration, highlighting essential environment variables for a secure setup.

import { betterAuth } from "better-auth"; import { syncPlugin } from "better-auth-sync"; import { convexJwt } from "better-auth-sync/jwt"; // Ensure these environment variables are set in your Better Auth server environment // BETTER_AUTH_URL=https://auth.your-app.com // WEBHOOK_URL=https://your-project.convex.site/auth-webhook // WEBHOOK_SECRET=replace-with-a-long-random-secret // APP_ORIGIN=https://your-app.com export const auth = betterAuth({ // Replace with your actual adapter, trusted origins, and providers // adapter: ..., // trustedOrigins: [process.env.APP_ORIGIN!], // providers: { email: { ... } }, plugins: [ convexJwt({ issuer: process.env.APP_ORIGIN ?? 'https://your-app.com', audience: process.env.APP_ORIGIN ?? 'https://your-app.com' }), syncPlugin({ secret: process.env.WEBHOOK_SECRET ?? 'your-webhook-secret-placeholder', url: process.env.WEBHOOK_URL ?? 'https://your-project.convex.site/auth-webhook', retryAttempts: 3 }) ] }); console.log('Better Auth instance configured with sync and Convex JWT plugins.'); console.log('Ensure environment variables are correctly loaded and JWT issuer/audience match APP_ORIGIN.');

Debug

Known issues

gotchaMismatch between `applicationID` in `convex/auth.config.ts` and `issuer`/`audience` in `convexJwt` will cause JWT validation failures, preventing users from being authenticated correctly via Convex. This is a common misconfiguration point.

fix

Ensure `applicationID` in `convex/auth.config.ts` exactly matches the `issuer` and `audience` values provided to `convexJwt` plugin. Both typically derive from `process.env.APP_ORIGIN`.

affects: >=0.1.0

gotchaThe `WEBHOOK_SECRET` environment variable must be a long, random, and securely stored string. If exposed or easily guessable, it could allow unauthorized parties to send forged authentication events to your Convex backend, leading to data corruption or security vulnerabilities.

fix

Generate a strong, unpredictable secret using a secure random string generator. Store it in environment variables and never commit it to source control. Rotate secrets regularly.

affects: >=0.1.0

gotchaIncorrect configuration of HTTP routes in Convex for `/auth-webhook` or `/.well-known/jwks.json` will prevent the sync plugin from functioning or JWTs from being validated. Missing routes or incorrect methods/handlers will lead to 404/405 errors.

fix

Carefully follow the documentation for setting up the HTTP routes in `convex/http.ts`, ensuring correct paths, methods (`POST` for webhook, `GET` for JWKS), and handler functions (`verifyWebhook`, `fetchJwks`).

affects: >=0.1.0

gotchaThe package is in version `0.2.0`, indicating it's still under active development and not yet at a stable 1.0.0 release. Minor versions might introduce breaking changes without a major version bump, though semver would dictate otherwise. Expect API adjustments in future updates.

fix

Pin exact versions (`~0.2.0` or `0.2.0`) rather than caret ranges (`^0.2.0`) in your `package.json` to prevent unexpected breaking changes on patch/minor updates. Review release notes carefully when upgrading.

affects: <1.0.0

Errors

Common errors & fixes

TypeError: Cannot read properties of undefined (reading 'APP_ORIGIN')

Environment variable `APP_ORIGIN` is not defined or accessible where `convexJwt` is configured.

fix

Ensure `APP_ORIGIN` is correctly set in your environment variables for the Better Auth server. For Node.js, this typically means `process.env.APP_ORIGIN`.

Response with status 401 from webhook endpoint

The `verifyWebhook` function in your Convex HTTP route failed, likely due to a mismatch in `WEBHOOK_SECRET` or an invalid signature/timestamp in the incoming webhook request.

fix

Verify that `process.env.WEBHOOK_SECRET` in your `convex/http.ts` matches the `secret` configured in the `syncPlugin` on your Better Auth server. Also, check for clock skew between the Better Auth server and Convex.

Convex `ConvexProviderWithAuth` or `useAuth` hook not working as expected, authentication state is missing.

The `createConvexBetterAuth` setup in your `src/providers/convex-provider.tsx` is incorrect, or `authClient` is not properly initialized, preventing the auth context from being provided.

fix

Double-check that `authClient` from `@/lib/auth-client` is correctly configured and that `ConvexClientProvider` is wrapping your application's components at a high level in the React tree.

Upgrade

Version history

0.2.0latest on npm

Audit

Dependencies

better-authrequiredCore authentication library this package extends.

convexrequiredDatabase backend with specific integration helpers provided by this package.

reactrequiredRequired for the `createConvexBetterAuth` hook and `ConvexProviderWithAuth` in frontend applications.

Agent activity

26 hits · last 30 days

node

OpenAI (training)

Resources

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