How this command is triggered — by the user, by Claude, or both
Slash command
/sigma-auth:setupFiles this command reads when invoked
The summary Claude sees in its command listing — used to decide when to auto-load this command
# Sigma Auth Setup Quick setup guide for integrating Sigma Identity authentication. ## Your Task Based on the argument provided (or default to nextjs): 1. **nextjs**: Setup @sigma-auth/better-auth-plugin in Next.js 2. **payload**: Setup with Payload CMS integration 3. **generic**: Show generic OAuth client setup ## Next.js Setup (Default) ### 1. Install Dependencies ### 2. Environment Variables Create `.env.local`: ### 3. Create Auth Client Create `lib/auth.ts`: ### 4. Token Exchange API Route Create `app/api/auth/sigma/callback/route.ts`: ### 5. Callback Page Create `...
Quick setup guide for integrating Sigma Identity authentication.
Based on the argument provided (or default to nextjs):
bun add @sigma-auth/better-auth-plugin better-auth
Create .env.local:
NEXT_PUBLIC_SIGMA_CLIENT_ID=your-app-name
SIGMA_MEMBER_PRIVATE_KEY=your-member-wif-key
NEXT_PUBLIC_SIGMA_AUTH_URL=https://auth.sigmaidentity.com
Create 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!,
plugins: [sigmaClient()],
});
export const signIn = authClient.signIn;
Create app/api/auth/sigma/callback/route.ts:
import { createCallbackHandler } from "@sigma-auth/better-auth-plugin/next";
export const runtime = "nodejs";
export const POST = createCallbackHandler();
Create app/auth/sigma/callback/page.tsx:
"use client";
import { Suspense, useEffect, useState } from "react";
import { useRouter, useSearchParams } from "next/navigation";
import { authClient } from "@/lib/auth";
function CallbackContent() {
const router = useRouter();
const searchParams = useSearchParams();
const [error, setError] = useState<string | null>(null);
useEffect(() => {
const handleCallback = async () => {
try {
const result = await authClient.sigma.handleCallback(searchParams);
localStorage.setItem("sigma_user", JSON.stringify(result.user));
localStorage.setItem("sigma_access_token", result.access_token);
router.push("/");
} catch (err: any) {
setError(err.message || "Authentication failed");
}
};
handleCallback();
}, [searchParams, router]);
if (error) return <div>Error: {error}</div>;
return <div>Completing sign in...</div>;
}
export default function CallbackPage() {
return (
<Suspense fallback={<div>Loading...</div>}>
<CallbackContent />
</Suspense>
);
}
import { signIn } from "@/lib/auth";
export function SignInButton() {
return (
<button onClick={() => signIn.sigma({
clientId: process.env.NEXT_PUBLIC_SIGMA_CLIENT_ID!,
callbackURL: "/auth/sigma/callback",
})}>
Sign in with Sigma
</button>
);
}
bun add @sigma-auth/better-auth-plugin payload-auth
Create app/api/auth/sigma/callback/route.ts:
import configPromise from "@payload-config";
import { createPayloadCallbackHandler } from "@sigma-auth/better-auth-plugin/payload";
export const runtime = "nodejs";
export const POST = createPayloadCallbackHandler({
configPromise,
createUser: async (payload, sigmaUser) => {
return payload.create({
collection: "users",
data: {
email: sigmaUser.email || `${sigmaUser.sub}@sigma.identity`,
name: sigmaUser.name || sigmaUser.sub,
bapId: sigmaUser.bap_id,
pubkey: sigmaUser.pubkey,
},
});
},
});
If you're building an OAuth provider (like auth.sigmaidentity.com or TokenPass), you need BOTH sigmaProvider AND oauthProvider plugins.
bun add @sigma-auth/better-auth-plugin @better-auth/oauth-provider better-auth postgres
lib/auth.ts)import { oauthProvider } from "@better-auth/oauth-provider";
import { sigmaProvider } from "@sigma-auth/better-auth-plugin/provider";
import { betterAuth } from "better-auth";
import { nextCookies } from "better-auth/next-js";
export const auth = betterAuth({
database: getDatabase(), // Your database connection
secret: process.env.BETTER_AUTH_SECRET,
baseURL: "http://localhost:21000", // Your server URL
plugins: [
// Sigma plugin - adds pubkey field and Bitcoin/BAP authentication
sigmaProvider({
debug: process.env.NODE_ENV === "development",
}),
// OAuth Provider - enables your app as an OAuth 2.1 server
oauthProvider({
loginPage: "/auth",
consentPage: "/consent",
allowDynamicClientRegistration: true,
defaultScope: "openid profile",
scopes: [
"openid", // OIDC ID token
"profile", // User profile + BSV pubkey/BAP claims
"email", // Email access
"offline_access", // Refresh tokens
],
}),
nextCookies(),
],
session: {
storeSessionInDatabase: true,
},
// Allow clients from different ports during development
trustedOrigins: [
"http://localhost:21000",
"http://localhost:4200",
"http://localhost:3000",
],
});
app/api/auth/[...all]/route.ts)import { auth } from "@/lib/auth";
import { toNextJsHandler } from "better-auth/next-js";
export const { GET, POST } = toNextJsHandler(auth.handler);
If you see this error:
The following scopes are invalid: openid, profile
It means you're missing the oauthProvider plugin. The oauthProvider is required to handle OAuth flows and scope validation.
useSession only works same-domain. Manage state with tokens.result.user.bap after authenticationsigmaProvider = run your own auth server; sigmaClient = authenticate against Sigma IdentityFull documentation: https://github.com/b-open-io/better-auth-plugin
npx claudepluginhub b-open-io/claude-plugins --plugin sigma-auth/better-auth-setupInteractively sets up better-auth: queries for DB/ORM/framework/OAuth/plugins, generates auth config, schema, routes, client code, and env template.
/hatch3r-auth-scaffoldScaffolds authentication boilerplate for a new API service: OAuth 2.1 authorization-code-with-PKCE flow, OIDC ID-token validation, and hashed PAT issuance/verification. Provides security gating against CQ3 auth floor.
/build-auth-systemBuilds complete API authentication and authorization system supporting JWT, OAuth2, API keys, sessions, MFA, and RBAC. Generates models, middleware, services, and security features.
/add-authAdds authentication to Next.js apps using Auth.js v5, including config, API routes, middleware, Prisma schema updates, UI components, and env vars.
/configure-studio-authInteractively configures OAuth for Nuxt Studio with GitHub, GitLab, or Google: detects setup, guides credential acquisition, updates .env.local.
/auth-setupGenerates backend authentication boilerplate with JWT (refresh tokens), OAuth2 (Google/GitHub/Facebook), bcrypt hashing, sessions, email verification, password reset, rate limiting, and middleware.