Registry / auth-security / better-near-auth

better-near-auth

library0.5.2jsnpmunverified

better-near-auth is a plugin for the Better Auth library, enabling 'Sign in with NEAR' (SIWN) functionality for web3 applications. It abstracts the complexities of interacting with the NEAR Protocol's authentication mechanisms, allowing developers to integrate NEAR login flows into their existing Better Auth setups. The library currently stands at version 0.5.2 and shows an active development cadence with regular patch and minor releases, indicated by recent updates addressing bug fixes and introducing new features like single-step authentication and improved wallet selection logic. Key differentiators include its tight integration with Better Auth, support for modern NEAR authentication patterns (including `signMessage`), and handling of wallet connection and account resolution within the authentication flow.

auth-security web-framework

npm install better-near-auth

github ↗package ↗

INSTALL

IMPORT

SIG · BETTER-NEAR-AUTH

better-near-auth

auth-securityjavascriptv0.5.2

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.

BetterNearAuthPlugin

✓ import { BetterNearAuthPlugin } from 'better-near-auth';

This is the main export for the plugin class, typically instantiated and passed to your Better Auth instance.

init

✓ import { init } from 'better-auth';

While better-near-auth is a plugin, its usage often starts with initializing the core `better-auth` library, which then registers the plugin.

signIn

✓ const { signIn } = useAuth(); // or similar access from better-auth instance

The `signIn` method, extended by the plugin, is accessed from your `better-auth` instance. The specific method to call for NEAR authentication is `signIn.near()`.

This quickstart demonstrates how to initialize Better Auth with the BetterNearAuthPlugin and then initiate a 'Sign in with NEAR' flow. It configures the NEAR network parameters and calls `signIn.near()`.

import { init } from 'better-auth'; import { BetterNearAuthPlugin } from 'better-near-auth'; const betterAuth = init({ plugins: [ new BetterNearAuthPlugin({ networkId: 'testnet', // or 'mainnet' nodeUrl: 'https://rpc.testnet.near.org', // or 'https://rpc.mainnet.near.org' walletUrl: 'https://wallet.testnet.near.org', // or 'https://wallet.near.org' helperUrl: 'https://helper.testnet.near.org', // or 'https://helper.near.org' explorerUrl: 'https://explorer.testnet.near.org' // or 'https://explorer.near.org' }) ], // other better-auth configurations }); async function authenticateWithNear() { try { console.log('Attempting to sign in with NEAR...'); const user = await betterAuth.signIn.near(); console.log('Successfully signed in:', user); // You can now access user.id, user.walletId, etc. } catch (error) { console.error('NEAR authentication failed:', error); // Handle specific errors, e.g., user canceled login } } // Call the authentication function (e.g., on a button click) authenticateWithNear();

Debug

Known issues

breakingThe underlying NEAR wallet connection and signing libraries were replaced in v0.3.0. If you were directly interacting with `fastintear`, you will need to update your code to use the new `near-kit` and `hot-connect` abstractions through `better-near-auth`'s API.

fix

Ensure your integration exclusively uses the `better-near-auth` plugin methods (e.g., `signIn.near()`) and does not rely on internals of `fastintear`.

affects: >=0.3.0

gotchaWhen calling `signIn.near()` without a prior wallet connection, the system might fail to properly show the wallet selector or determine the authentication flow, potentially leading to 'No accounts found' errors. This was partially addressed in v0.5.1.

fix

Upgrade to version 0.5.1 or newer. If the issue persists, ensure that the wallet selection process is correctly initiated before or during the `signIn.near()` call, possibly by explicitly connecting a wallet first if your UI flow requires it.

affects: <0.5.1

gotchaVersion 0.5.0 introduced a 'single-step authentication flow' for wallets supporting `signMessage`. This changes the internal authentication process, which might behave differently than previous versions for certain wallets or setups.

fix

Test your authentication flow thoroughly with various NEAR wallets after upgrading to v0.5.0 to ensure compatibility with the new single-step flow. Report issues if specific wallets do not function as expected.

affects: >=0.5.0

breakingThe package manager was migrated from Bun to pnpm in v0.5.0, which might affect development environments that rely on Bun's specific package resolution or lockfile format.

fix

Ensure your development environment uses pnpm for installing `better-near-auth`'s dependencies to avoid potential issues related to package resolution or conflicting lockfiles.

affects: >=0.5.0

Errors

Common errors & fixes

Error: No accounts found. Please connect a NEAR wallet.

The `signIn.near()` method was called without a user having previously connected or selected a NEAR wallet, or the wallet selector failed to appear/resolve.

fix

Ensure the wallet selection UI is correctly presented to the user before or during the `signIn.near()` call. Upgrade to `better-near-auth@0.5.1` or newer, which includes fixes for this specific scenario.

TypeError: betterAuth.signIn.near is not a function

The `BetterNearAuthPlugin` was not correctly initialized and registered with your `better-auth` instance, or the `better-auth` instance itself was not properly created.

fix

Verify that `new BetterNearAuthPlugin(...)` is included in the `plugins` array during the `better-auth.init()` call. Also, ensure `betterAuth` is the correct instance returned from `init()` or `useAuth()`.

Wallet transaction failed: User rejected signature request.

The user explicitly declined the authentication or signature request presented by their NEAR wallet.

fix

Handle this error gracefully in your application's UI, informing the user that the sign-in process was canceled. Provide options for them to retry authentication.

Upgrade

Version history

0.5.2latest on npm

Audit

Dependencies

better-authrequiredCore authentication framework this package extends as a plugin.

typescriptrequiredRequired for type checking, as the library ships with TypeScript types and is intended for use in TypeScript projects.

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/elliotBraem/better-near-auth ↗

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