Registry / auth-security / better-auth-solana

better-auth-solana

JSON →
library1.0.0jsnpmunverified

better-auth-solana is a specialized plugin for the Better Auth authentication framework, designed to facilitate "Sign in With Solana" (SIWS) functionality. Currently at version 1.0.0, it provides a stable, initial release enabling Solana wallet integration into Better Auth applications. The package includes server-side endpoints for managing the SIWS flow (nonce generation, signature verification, wallet linking) and client-side utilities for constructing SIWS messages and interacting with the Better Auth client. It natively handles session establishment and account creation/linking within the Better Auth ecosystem, using its dedicated `siws` plugin namespace. The package is published as ESM-only, aligning with better-auth's modern module strategy.

npm install better-auth-solana
INSTALL
IMPORT
SIG · BETTER-AUTH-SOLANA
B
better-auth-solana
auth-securityjavascriptv1.0.0
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
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 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

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

siws
import { siws } from 'better-auth-solana'
const { siws } = require('better-auth-solana')
The server-side plugin for Better Auth; ESM-only since v1.0.0.
createSIWSInput
import { createSIWSInput } from 'better-auth-solana/client'
const { createSIWSInput } = require('better-auth-solana/client')
Client-side helper for creating structured SIWS input for wallets; ESM-only.
siwsClient
import { siwsClient } from 'better-auth-solana/client'
const { siwsClient } = require('better-auth-solana/client')
Client-side plugin to extend `better-auth/client` functionality; ESM-only.
formatSIWSMessage
import { formatSIWSMessage } from 'better-auth-solana/client'
const { formatSIWSMessage } = require('better-auth-solana/client')
Utility to format SIWS fields into a canonical message string; ESM-only.

Demonstrates a complete client-side 'Sign in With Solana' (SIWS) flow, including nonce retrieval, message creation, wallet signing (mocked), and session verification with Better Auth.

import { createAuthClient } from 'better-auth/client' import { createSIWSInput, siwsClient } from 'better-auth-solana/client' // Placeholder for your wallet's sign function async function signWithYourWallet(siwsInput: any): Promise<{ message: string; signature: string }> { console.log('Signing message with wallet:', siwsInput) // In a real app, this would involve connecting to a Solana wallet (e.g., Phantom, Solflare) // and using its sign message functionality. For demonstration, we'll return a mock. const mockSignature = 'mock_signature_' + Date.now() return { message: JSON.stringify(siwsInput), signature: mockSignature } } // Assume 'address' is the connected Solana wallet address const address = 'GMtGgT8d6R3FwYxK2c3L4p5Q6r7S8t9U0v1W2x3Y4z5' const authClient = createAuthClient({ plugins: [siwsClient()], }) async function performSolanaSignIn() { try { const nonceResult = await authClient.siws.nonce({ walletAddress: address, }) if (!nonceResult.data) { throw new Error('Failed to request SIWS nonce') } const siwsInput = createSIWSInput({ address, challenge: nonceResult.data, statement: 'Sign in to Example', domain: 'example.com', // Must match the domain configured on the server uri: 'https://example.com/siws', // The current application URI chainId: 'solana:mainnet', // Solana network chain ID version: '1' // SIWS version }) const signed = await signWithYourWallet(siwsInput) await authClient.siws.verify({ message: signed.message, signature: signed.signature, walletAddress: address, }) const session = await authClient.getSession() console.log('Successfully signed in:', session) } catch (error) { console.error('SIWS sign-in failed:', error) } } performSolanaSignIn()
Debug
Known issues
breakingThe `better-auth-solana` package is ESM-only (ECMAScript Modules) since its initial v1.0.0 release. Attempts to `require()` it in a CommonJS environment will result in module resolution errors.
fix
Ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json`) or use dynamic `import()` for CJS compatibility layers where appropriate.
affects: >=1.0.0
gotchaThis package has peer dependencies on `@solana/kit` (`^6.8.0`) and `better-auth` (`^1.5.0`). These must be installed separately in your project and meet the specified version constraints for `better-auth-solana` to function correctly.
fix
Run `npm install @solana/kit@^6.8.0 better-auth@^1.5.0 better-auth-solana` (or use `yarn`/`bun`) to ensure all required peer dependencies are present and compatible.
affects: >=1.0.0
gotchaWhen using client-side verification, differentiate between `authClient.siws.verify(...)` for establishing a new Better Auth session or logging in, and `authClient.siws.link(...)` for attaching a new Solana wallet to an *already authenticated* Better Auth session.
fix
Use `verify` for initial sign-in flows and `link` only when a user is already logged in and wants to add another wallet address to their existing account.
affects: >=1.0.0
gotchaThe plugin uses a fixed `siws` namespace, which means its API endpoints will always be nested under your Better Auth handler's path, e.g., `/api/auth/siws/verify`.
fix
When configuring frontend API calls or proxies, ensure the full path including the `/siws/` segment is correctly used for all interactions with the plugin's endpoints.
affects: >=1.0.0
Errors
Common errors & fixes
ERR_REQUIRE_ESM
Attempting to use `require()` to import `better-auth-solana` or its subpaths in a CommonJS module.
fix
Migrate your file or project to use ES Modules (`import ... from '...'`) or dynamically import the package using `await import(...)`.
Failed to request SIWS nonce
The server-side `/siws/nonce` endpoint did not return a challenge, possibly due to a network issue, server misconfiguration, or an invalid `walletAddress` provided.
fix
Verify the server is running and the `siws` plugin is correctly configured. Check network requests in your browser's developer tools for errors from the `/siws/nonce` endpoint and ensure `walletAddress` is valid.
Error: Invalid SIWS message format
The `message` or `signature` provided to `authClient.siws.verify` (or `link`) does not match the expected SIWS format or fails signature verification.
fix
Ensure `createSIWSInput` or `createSIWSMessage` is used correctly to generate the message. Confirm the wallet's `signMessage` function is returning the expected message and a valid signature. The `domain`, `uri`, and other SIWS fields must match those expected by the server.
Upgrade
Version history
1.0.0latest on npm
Audit
Dependencies
@solana/kitrequiredRequired for Solana wallet interactions and signing.
better-authrequiredCore authentication framework that this package extends as a plugin.
Agent activity
35 hits · last 30 days
node
28
OpenAI (training)
1
Resources
better-auth-solana — npm install better-auth-solana · libregistry