sigma-auth

@sigma-auth/better-auth-plugin

Bitcoin-native authentication for Better Auth. Users sign in with their Bitcoin wallet. Identity is a cryptographic keypair — persistent across apps, controlled only by the user.

Maintained by Sigma Identity. For support, open an issue on GitHub.

Features

• Passwordless from day one — Bitcoin wallet signatures replace passwords and magic links
• BAP identity support — Bitcoin Attestation Protocol provides persistent, portable user profiles
• PKCE OAuth flow — Fully spec-compliant authorization code flow with PKCE for public clients
• Iframe signer — Client-side signing without exposing private keys to your app domain
• Local signer fallback — Optional local TokenPass server for offline or privacy-first deployments
• NFT-based role gating — Assign roles based on NFT collection ownership across connected wallets
• Token balance gating — Grant roles when users hold minimum BSV-21 token balances
• BAP admin whitelist — Designate admins by Bitcoin identity key, checked at every session creation
• Multi-identity wallets — Users can select among multiple BAP identities at sign-in
• Subscription tiers — Verified subscription status flows through to your session
• Next.js App Router — Ready-to-use route handlers with a single import
• Payload CMS — Drop-in callback handler with customizable user creation
• Convex — Works inside @convex-dev/better-auth with no local auth instance required
• Full TypeScript — All types exported, including SigmaUserInfo, BAPProfile, and JWT claims

Installation

bun add @sigma-auth/better-auth-plugin
# or
npm install @sigma-auth/better-auth-plugin

Peer dependencies

Install only what you use:

# Required for all integrations
bun add better-auth

# Required for server-side token exchange
bun add bitcoin-auth

# Required for the provider plugin (running your own auth server)
bun add @bsv/sdk bsv-bap @neondatabase/serverless zod

# Required for Payload CMS integration
bun add payload-auth

Quick Start

This is the standard setup for an app that authenticates users via Sigma Identity. The whole flow takes under five minutes.

1. Set environment variables

# .env.local
NEXT_PUBLIC_SIGMA_CLIENT_ID=your-app-id
NEXT_PUBLIC_SIGMA_AUTH_URL=https://auth.sigmaidentity.com
SIGMA_MEMBER_PRIVATE_KEY=your-wif-private-key   # server-side only

Get your client ID and register your redirect URI at sigmaidentity.com/developers.

2. Configure the auth client

// lib/auth.ts
import { createAuthClient } from "better-auth/client";
import { sigmaClient } from "@sigma-auth/better-auth-plugin/client";

export const authClient = createAuthClient({
  baseURL: process.env.NEXT_PUBLIC_SIGMA_AUTH_URL || "https://auth.sigmaidentity.com",
  plugins: [sigmaClient()],
});

3. Add the token exchange route

// app/api/auth/sigma/callback/route.ts
import { createCallbackHandler } from "@sigma-auth/better-auth-plugin/next";

export const runtime = "nodejs";
export const POST = createCallbackHandler();

4. Add the OAuth callback page

// app/auth/sigma/callback/page.tsx
"use client";

import { Suspense, useEffect } from "react";
import { useRouter, useSearchParams } from "next/navigation";
import { authClient } from "@/lib/auth";

function CallbackContent() {
  const router = useRouter();
  const searchParams = useSearchParams();

  useEffect(() => {
    authClient.sigma.handleCallback(searchParams)
      .then((result) => {
        // Store tokens and user data in your state management solution
        localStorage.setItem("sigma_user", JSON.stringify(result.user));
        localStorage.setItem("sigma_access_token", result.access_token);
        router.push("/");
      })
      .catch((err) => {
        authClient.sigma.redirectToError(err);
      });
  }, [searchParams, router]);

  return <p>Completing sign in...</p>;
}

export default function CallbackPage() {
  return (
    <Suspense fallback={<p>Loading...</p>}>
      <CallbackContent />
    </Suspense>
  );
}

5. Add a sign-in button

import { authClient } from "@/lib/auth";

export function SignInButton() {
  return (
    <button
      onClick={() =>
        authClient.signIn.sigma({
          clientId: process.env.NEXT_PUBLIC_SIGMA_CLIENT_ID!,
        })
      }
    >
      Sign in with Bitcoin
    </button>
  );
}

The user clicks the button, authenticates with their Bitcoin wallet on the Sigma Identity server, and lands back in your app with a SigmaUserInfo object containing their pubkey, display name, and BAP identity.

---

Architecture

How Bitcoin authentication works