@the-beus/sso-client

🔐 Official SSO Client SDK for The BEUS - OAuth 2.0 + PKCE authentication made simple

✨ Features

• 🔒 OAuth 2.0 + PKCE - Secure authentication without exposing secrets
• 🌐 Universal - Works in Browser & Node.js
• 📦 Lightweight - Zero dependencies, < 5KB gzipped
• 🎣 React Ready - Built-in hook factory
• 💪 TypeScript - Full type definitions included

📦 Installation

npm install @the-beus/sso-client
# or
yarn add @the-beus/sso-client
# or
pnpm add @the-beus/sso-client

🚀 Quick Start

Basic Usage

import { TheBeusSSOClient } from '@the-beus/sso-client'

const sso = new TheBeusSSOClient({
  clientId: 'your-client-id',
  redirectUri: 'https://your-site.com/auth/callback',
})

// Redirect to login
await sso.login()

Handle Callback

// In your callback page
const { tokens, user } = await sso.handleCallback()

console.log(user.name)    // "John Doe"
console.log(user.email)   // "[email protected]"
console.log(tokens.access_token)  // "eyJ..."

📖 Documentation

Configuration

interface SSOClientConfig {
  clientId: string        // Required - Your client ID
  clientSecret?: string   // Optional - For server-side only!
  redirectUri: string     // Required - Your callback URL
  providerUrl?: string    // Optional - Default: 'https://thebeus.com'
  scopes?: SSOScope[]     // Optional - Default: ['openid', 'profile', 'email']
}

Available Scopes

| Scope | Description | |-------|-------------| | openid | OpenID Connect (required) | | profile | User's profile (name, picture) | | email | User's email address | | offline_access | Get refresh token |

API Reference

login(options?)

Redirect user to The BEUS login page.

await sso.login()

// With custom callback
await sso.login({ callbackUrl: 'https://custom.com/callback' })

handleCallback(params?)

Handle OAuth callback and exchange code for tokens.

const { tokens, user } = await sso.handleCallback()

refreshToken(token)

Refresh access token using refresh token.

const newTokens = await sso.refreshToken(savedRefreshToken)

getUserInfo(accessToken)

Get user info using access token.

const user = await sso.getUserInfo(accessToken)

logout(tokens?)

Revoke tokens and logout.

await sso.logout({
  accessToken: savedAccessToken,
  refreshToken: savedRefreshToken,
})

⚛️ React Integration

Create a Custom Hook

// lib/sso.ts
import { createSSOAuthHook } from '@the-beus/sso-client'

export const useSSOAuth = createSSOAuthHook({
  clientId: process.env.NEXT_PUBLIC_SSO_CLIENT_ID!,
  redirectUri: `${process.env.NEXT_PUBLIC_SITE_URL}/auth/callback`,
})

Login Button Component

// components/LoginButton.tsx
import { useSSOAuth } from '@/lib/sso'

export function LoginButton() {
  const { login } = useSSOAuth()
  
  return (
    <button onClick={() => login()}>
      Login with The BEUS
    </button>
  )
}

Callback Page

// pages/auth/callback.tsx
import { useEffect, useState } from 'react'
import { useRouter } from 'next/router'
import { useSSOAuth } from '@/lib/sso'

export default function CallbackPage() {
  const router = useRouter()
  const { handleCallback } = useSSOAuth()
  const [error, setError] = useState<string | null>(null)
  
  useEffect(() => {
    handleCallback()
      .then(({ tokens, user }) => {
        // Save to your auth state
        localStorage.setItem('accessToken', tokens.access_token)
        localStorage.setItem('user', JSON.stringify(user))
        router.push('/dashboard')
      })
      .catch(err => {
        setError(err.message)
      })
  }, [])
  
  if (error) return <div>Error: {error}</div>
  return <div>Logging in...</div>
}

🔧 Next.js API Route (Server-Side)

// pages/api/auth/refresh.ts
import { TheBeusSSOClient } from '@the-beus/sso-client'
import type { NextApiRequest, NextApiResponse } from 'next'

const sso = new TheBeusSSOClient({
  clientId: process.env.SSO_CLIENT_ID!,
  clientSecret: process.env.SSO_CLIENT_SECRET!, // Safe on server
  redirectUri: process.env.SITE_URL + '/auth/callback',
})

export default async function handler(
  req: NextApiRequest, 
  res: NextApiResponse
) {
  const { refreshToken } = req.body
  
  try {
    const tokens = await sso.refreshToken(refreshToken)
    res.json(tokens)
  } catch (error) {
    res.status(401).json({ error: 'Token refresh failed' })
  }
}

🛡️ Security Best Practices

1. Never expose clientSecret in frontend code
2. Use HTTPS in production
3. Validate tokens on your backend
4. Store tokens securely (httpOnly cookies preferred)
5. Implement token refresh before expiration

📄 License

MIT © The BEUS