obelisk-universal-auth

Universal authentication system for all Obelisk platforms using Supabase. This package provides a unified login system that allows users to sign up and sign in with username and password across all Obelisk products.

Features

• Username + Password Authentication: Users sign up and sign in with username and password (no email required initially)
• Mock Email Generation: Automatically generates {username}@example.com for Supabase auth
• Universal User Database: Centralized user table linked to Supabase auth
• Email Linking: Users can link their real email later in settings
• Platform Integration: Each platform maintains its own profile table linked to universal auth UUID
• Simple UI Components: Ready-to-use SignUp and SignIn React components

Installation

From NPM (Production)

npm install obelisk-universal-auth

Local Development

If you're developing the package locally:

# In this package directory
npm link

# In your project directory
npm link obelisk-universal-auth

See PUBLISHING.md for detailed publishing instructions.

Setup

1. Database Setup

First, run the database migration in your Supabase SQL editor:

-- Copy and paste the contents of src/database/schema.sql
-- Or run it programmatically (requires service role key)

The schema creates:

• users table with id (UUID from auth), username, mock_email, and timestamps
• Indexes for fast username lookups
• Row Level Security policies

2. Supabase Auth Configuration

Important: Disable email confirmations in Supabase to allow mock emails:

1. Go to Supabase Dashboard → Authentication → Settings
2. Find "Enable email confirmations"
3. Turn it OFF
4. Save

This allows mock email addresses ({username}@example.com) to work without verification.

3. Initialize Auth Client

In your platform's code, initialize the auth client with your Supabase credentials:

import { createAuthClient } from 'obelisk-universal-auth';

const auth = createAuthClient({
  supabaseUrl: process.env.SUPABASE_URL!,
  supabaseKey: process.env.SUPABASE_ANON_KEY!,
});

Usage

Sign Up

import { signup } from 'obelisk-universal-auth';

try {
  const { user, session } = await signup({
    username: 'johndoe',
    password: 'securepassword123',
  });
  
  // User is now signed up and authenticated
  // Create platform-specific profile
} catch (error) {
  console.error('Signup failed:', error.message);
}

Sign In

import { signin } from 'obelisk-universal-auth';

try {
  const { user, session } = await signin({
    username: 'johndoe',
    password: 'securepassword123',
  });
  
  // User is now authenticated
} catch (error) {
  console.error('Sign in failed:', error.message);
}

Update Email

When a user links their real email in settings:

import { updateEmail } from 'obelisk-universal-auth';

try {
  const updatedUser = await updateEmail({
    userId: user.id,
    newEmail: '[email protected]',
  });
  
  // Email updated in Supabase auth
} catch (error) {
  console.error('Email update failed:', error.message);
}

Platform Profile Integration

After signup, create a platform-specific profile linked to the universal auth UUID:

import { createPlatformProfile } from 'obelisk-universal-auth';

// After successful signup
await createPlatformProfile(
  user.id, // UUID from universal auth
  'profiles', // Your platform's profile table name
  {
    // Additional platform-specific data
    display_name: 'John Doe',
    bio: 'Web3 developer',
  }
);

Get Universal User Data

import { getUniversalUser, getCurrentUser } from 'obelisk-universal-auth';

// Get by UUID
const universalUser = await getUniversalUser(userId);

// Get current authenticated user
const currentUser = await getCurrentUser();

React Components

Use the provided UI components:

import { SignUp, SignIn } from 'obelisk-universal-auth';
// Import styles (adjust path based on your build setup)
import 'obelisk-universal-auth/src/ui/styles.css';
// Or if using from dist: import 'obelisk-universal-auth/dist/ui/styles.css';

function AuthPage() {
  return (
    <div>
      <SignUp
        onSuccess={(result) => {
          console.log('Signed up:', result.user);
          // Create platform profile, redirect, etc.
        }}
        onError={(error) => {
          console.error('Signup error:', error);
        }}
      />
      
      <SignIn
        onSuccess={(result) => {
          console.log('Signed in:', result.user);
          // Redirect to dashboard, etc.
        }}
        onError={(error) => {
          console.error('Sign in error:', error);
        }}
      />
    </div>
  );
}

Platform Integration Pattern

Each platform should:

1. Install the package: npm install @obelisk/universal-auth

2. Initialize with platform's Supabase instance:

   createAuthClient({
     supabaseUrl: process.env.SUPABASE_URL,
     supabaseKey: process.env.SUPABASE_ANON_KEY,
   });

3. Create platform profile table with obelisk_auth_id:

   CREATE TABLE profiles (
     id UUID PRIMARY KEY DEFAULT gen_random_uuid(),
     obelisk_auth_id UUID REFERENCES users(id),
     username TEXT,
     -- other platform-specific fields
     created_at TIMESTAMPTZ DEFAULT NOW(),
     updated_at TIMESTAMPTZ DEFAULT NOW()
   );

4. After signup, create platform profile:

   await createPlatformProfile(user.id, 'profiles', { /* platform data */ });

Architecture

┌─────────────────────────────────────┐
│   Universal Auth (Supabase)         │
│   - auth.users (email, password)    │
│   - users table (id, username)      │
└─────────────────────────────────────┘
              │
              │ UUID reference
              │
    ┌─────────┴─────────┬──────────────┐
    │                   │              │
┌───▼───┐         ┌─────▼─────┐  ┌────▼────┐
│Web3Recap│       │   Hub     │  │ Creatix │
│profiles │       │ profiles  │  │profiles │
└─────────┘       └───────────┘  └─────────┘

TypeScript Support

Full TypeScript support with exported types:

import type {
  UniversalAuthConfig,
  SignUpResult,
  SignInResult,
  UniversalUser,
} from 'obelisk-universal-auth';

Requirements

• Node.js 18+
• React 18+ (for UI components)
• Supabase account and project
• Each platform must have its own Supabase instance

License

MIT