Registry / auth-security / better-auth-siws

better-auth-siws

JSON →
library0.1.3jsnpmunverified

better-auth-siws is a specialized plugin designed to integrate Sign-In With Solana (SIWS) functionality into applications utilizing the Better Auth framework. Currently at version 0.1.3, this package provides both server-side and client-side plugins (`siwsPlugin` and `siwsClientPlugin` respectively) along with a utility (`buildSiwsMessage`) to construct the canonical SIWS message. It streamlines the implementation of SIWS by offering `start` and `verify` endpoints, abstracting away much of the cryptographic and session management complexity when paired with Better Auth. The package is actively maintained and extends Better Auth's capabilities to support Solana-based authentication flows, differentiating itself by providing a tightly integrated solution specifically for the Better Auth ecosystem.

npm install better-auth-siws
INSTALL
IMPORT
SIG · BETTER-AUTH-SIWS
B
better-auth-siws
auth-securityjavascriptv0.1.3
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.

siwsPlugin
import { siwsPlugin } from 'better-auth-siws';
const siwsPlugin = require('better-auth-siws').siwsPlugin;
Used for configuring the SIWS server plugin within your Better Auth instance. This package is ESM-first.
siwsClientPlugin
import { siwsClientPlugin } from 'better-auth-siws/client';
import { siwsClientPlugin } from 'better-auth-siws';
Used for configuring the SIWS client plugin within your Better Auth client instance. Note the explicit '/client' subpath.
buildSiwsMessage
import { buildSiwsMessage } from 'better-auth-siws';
const buildSiwsMessage = require('better-auth-siws').buildSiwsMessage;
A utility function to programmatically construct the canonical Sign-In With Solana message string.

This quickstart demonstrates a complete client-side Sign-In With Solana (SIWS) flow using `better-auth-siws`. It covers initializing the Better Auth client, requesting a nonce from the server, building the canonical SIWS message, having a mock Solana wallet sign the message, and finally verifying the signature with the server to establish a user session. This illustrates the typical steps a user would take in a web application.

import bs58 from "bs58"; import { buildSiwsMessage } from "better-auth-siws"; import { createAuthClient } from "better-auth/client"; import { siwsClientPlugin } from "better-auth-siws/client"; // 1. Initialize Better Auth client with SIWS plugin export const clientAuth = createAuthClient({ baseURL: "https://app.example.com/api/auth", // Ensure this matches your server's baseURL plugins: [siwsClientPlugin()], }); /** * Simulates a Solana wallet with publicKey and signMessage capabilities. * In a real app, this would come from a wallet adapter (e.g., @solana/wallet-adapter). */ const mockWallet = { publicKey: { toBase58: () => 'HbC8N9p6jR8g7A6y5X4Z3W2V1U0T9S8Q' }, signMessage: async (data: Uint8Array) => { // In a real app, this would prompt the user to sign // For this example, returning a dummy signature console.log("Wallet signing message:", new TextDecoder().decode(data)); return new Uint8Array(Array(64).fill(0)); // Dummy 64-byte signature } }; async function signInWithSolana(wallet: typeof mockWallet) { // 2. Request a nonce from the server const address = wallet.publicKey.toBase58(); const { nonce, domain, uri } = await clientAuth.api.start({ body: { address }, }); // 3. Build the canonical SIWS message for signing const message = buildSiwsMessage({ domain, address, uri, nonce, issuedAt: new Date().toISOString(), }); // 4. Have the user's wallet sign the message const signatureBytes = await wallet.signMessage(new TextEncoder().encode(message)); const signature = bs58.encode(signatureBytes); // 5. Send signed message and signature to the server for verification const result = await clientAuth.api.verify({ body: { address, message, signature }, }); console.log("Sign-In successful!"); console.log("User session:", result); return result; } // Example usage: signInWithSolana(mockWallet).catch(console.error);
Debug
Known issues
gotchaThe 'domain' configured in the `siwsPlugin` on your server MUST precisely match the domain your application is hosted on (without protocol) and align with the 'domain' returned by the `/siws/start` endpoint. A mismatch will cause signature verification to fail due to the SIWS specification.
fix
Ensure `siwsPlugin({ domain: 'app.example.com' })` on the server exactly matches your application's domain. Also, `betterAuth({ security: { trustedOrigins: [...] } })` should include the exact client origin.
affects: >=0.1.0
gotchaThe `nonceTtlSeconds` configured on the server-side `siwsPlugin` (default: 300 seconds) defines how long a generated nonce remains valid. If the user takes too long to sign the message and send it for verification, the nonce may expire, leading to verification failure.
fix
Inform users about the time limit or consider increasing `nonceTtlSeconds` on the server if longer delays are expected. For example: `siwsPlugin({ nonceTtlSeconds: 600 })`.
affects: >=0.1.0
gotchaThe client-side SIWS flow requires a connected Solana wallet that implements a `signMessage` method which accepts a `Uint8Array` message and returns a `Promise<Uint8Array>` signature. Wallets or adapter libraries that provide different APIs for message signing will not work directly.
fix
Ensure you are using a compatible Solana wallet adapter (e.g., `@solana/wallet-adapter`) and that the wallet is connected and exposes the `signMessage` function as expected.
affects: >=0.1.0
gotchaThis package is a plugin for `better-auth`. Proper functioning relies on `better-auth` itself being correctly configured, especially its `baseURL` and `security.trustedOrigins`. Requests from unlisted origins will be rejected by Better Auth's security middleware, preventing SIWS flow completion.
fix
Verify your `better-auth` server configuration, ensuring `baseURL` is correct and all client origins are listed in `security.trustedOrigins`.
affects: >=0.1.0
Errors
Common errors & fixes
Error: SIWS verification failed: Domain mismatch.
The 'domain' in the signed SIWS message does not match the 'domain' configured in the server's `siwsPlugin` instance.
fix
Check the `domain` option passed to `siwsPlugin({ domain: '...' })` on your server to ensure it precisely matches the `domain` of your application where the SIWS flow is initiated.
Error: SIWS verification failed: Nonce expired.
The time elapsed between the server issuing a nonce and the client submitting the signed message for verification exceeded the configured `nonceTtlSeconds`.
fix
Expedite the client-side signing process, or increase the `nonceTtlSeconds` option in your server's `siwsPlugin` configuration (e.g., `siwsPlugin({ nonceTtlSeconds: 600 })`).
TypeError: wallet.signMessage is not a function
The connected Solana wallet object does not expose a `signMessage` method, or it's not available when the SIWS signing attempt is made.
fix
Ensure a compatible Solana wallet (e.g., via `@solana/wallet-adapter`) is connected and the wallet instance provides the `signMessage` function with the expected signature (`(data: Uint8Array) => Promise<Uint8Array>`).
Error: Unauthorized origin for SIWS start/verify endpoint.
The `Origin` header of the client request is not included in the `trustedOrigins` array configured in your `better-auth` server instance.
fix
Add the full origin URL of your frontend application (e.g., `https://app.example.com`) to the `trustedOrigins` array in your `betterAuth({ security: { trustedOrigins: [...] } })` server configuration.
Upgrade
Version history
0.1.3latest on npm
Audit
Dependencies
better-authrequiredThis package is a plugin for Better Auth and requires it as a peer dependency.
bs58requiredUsed for base58 encoding of Solana signatures during the SIWS verification process.
Agent activity
30 hits · last 30 days
node
26
OpenAI (training)
1
Resources
better-auth-siws — npm install better-auth-siws · libregistry