@sigma-auth/client-plugin

Better Auth client plugin for Bitcoin-based OAuth authentication with Sigma Identity.

What is Sigma Identity?

Sigma Identity (auth.sigmaidentity.com) is a centralized OAuth provider for Bitcoin-based authentication - like "Sign in with Google" or "Sign in with GitHub", but for Bitcoin identities.

Your users' private keys NEVER leave Sigma's domain. Your application receives OAuth tokens, just like any other OAuth provider.

Installation

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

Setup

Add the Client Plugin

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

export const authClient = createAuthClient({
  baseURL: "http://localhost:3000", // Your API base URL
  plugins: [sigmaClient()],
});

Usage

Sign In with Sigma (Basic)

import { authClient } from "./auth-client";

export function SignInButton() {
  return (
    <button onClick={() => authClient.signIn.sigma()}>
      Sign in with Sigma
    </button>
  );
}

This redirects the user to auth.sigmaidentity.com where they authenticate with their Bitcoin wallet, then redirects back to your app with an OAuth authorization code.

Sign In with Provider

Sigma Identity supports OAuth providers like GitHub, Google, etc.:

<button onClick={() => authClient.signIn.sigma({ provider: 'github' })}>
  Sign in with GitHub via Sigma
</button>

Custom Callback URL

<button
  onClick={() => authClient.signIn.sigma({
    callbackURL: 'https://myapp.com/auth/callback'
  })}
>
  Sign in with Sigma
</button>

OAuth Flow

1. User clicks "Sign in with Sigma" button
2. Client plugin redirects to auth.sigmaidentity.com/api/oauth/authorize
3. User authenticates on Sigma's domain (private keys never leave Sigma)
4. Sigma redirects back to your app with authorization code
5. Your server exchanges code for access token
6. User is authenticated

Note: Your users' Bitcoin private keys are managed by Sigma Identity and NEVER exposed to your application.

API Reference

sigmaClient()

Creates the Sigma Auth client plugin for Better Auth.

const plugin = sigmaClient();

authClient.signIn.sigma(options?)

Initiates the OAuth flow by redirecting to Sigma Identity's authorization endpoint.

Parameters:

• options.callbackURL (string, optional) - Custom callback URL. Defaults to ${window.location.origin}/callback
• options.provider (string, optional) - OAuth provider to use via Sigma ('github', 'google', etc.)
• options.errorCallbackURL (string, optional) - URL to redirect to on error

Returns: Promise that never resolves (redirects away from page)

Server Setup

This plugin requires a corresponding Better Auth server plugin that handles the OAuth token exchange. See @sigma-auth/server-plugin for server-side setup.

Your server needs to:

1. Provide a callback endpoint to receive the authorization code
2. Exchange the code for an access token with Sigma Identity
3. Create a user session

Environment Variables

# Optional: Custom Sigma Auth server URL (defaults to https://auth.sigmaidentity.com)
NEXT_PUBLIC_SIGMA_AUTH_URL=https://auth.sigmaidentity.com

# Or for Vite projects:
VITE_SIGMA_AUTH_URL=https://auth.sigmaidentity.com

TypeScript

Full TypeScript support included:

import type { BetterAuthClientPlugin } from "better-auth/client";

const plugin: BetterAuthClientPlugin = sigmaClient();

Requirements

• better-auth ^1.3.34 (peer dependency)
• A Better Auth server with @sigma-auth/server-plugin

Security

• ✅ Private keys never leave Sigma Identity's domain
• ✅ CSRF protection via state parameter
• ✅ Standard OAuth 2.0 authorization code flow
• ✅ No secrets or sensitive data in client code

Related Packages

• @sigma-auth/server-plugin - Server-side Better Auth plugin
• Sigma Identity - Centralized Bitcoin OAuth provider

License

MIT