Handling Authentication in StickerNest

This skill covers implementing authentication flows, protecting routes, managing sessions, and providing auth context to widgets.

Architecture Overview

┌─────────────────────────────────────────────────────────────┐
│                     Supabase Auth                            │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │   Email     │  │   OAuth     │  │   Magic     │          │
│  │  Password   │  │   (Google)  │  │   Link      │          │
│  └──────┬──────┘  └──────┬──────┘  └──────┬──────┘          │
└─────────┼────────────────┼────────────────┼─────────────────┘
          │                │                │
          └────────────────┼────────────────┘
                           ▼
┌─────────────────────────────────────────────────────────────┐
│                     AuthContext                              │
│  ┌─────────────┐  ┌─────────────┐  ┌─────────────┐          │
│  │    user     │  │   session   │  │  isLoading  │          │
│  │   profile   │  │   tokens    │  │   isLocal   │          │
│  └─────────────┘  └─────────────┘  └─────────────┘          │
└─────────────────────────┬───────────────────────────────────┘
                          │
        ┌─────────────────┼─────────────────┐
        ▼                 ▼                 ▼
  Components         Widgets          Services
  (useAuth)       (WidgetAuth)      (API calls)

AuthContext Implementation

Location: `src/contexts/AuthContext.tsx`

typescript

import React, { createContext, useContext, useEffect, useState } from 'react';
import { createClient, SupabaseClient, User, Session } from '@supabase/supabase-js';

interface Profile {
  id: string;
  username: string | null;
  display_name: string | null;
  avatar_url: string | null;
  bio: string | null;
}

interface AuthContextType {
  user: User | null;
  profile: Profile | null;
  session: Session | null;
  isLoading: boolean;
  isAuthenticated: boolean;
  isLocalDevMode: boolean;
  signUp: (email: string, password: string) => Promise<{ error: Error | null }>;
  signIn: (email: string, password: string) => Promise<{ error: Error | null }>;
  signInWithOAuth: (provider: 'google' | 'github') => Promise<void>;
  signOut: () => Promise<void>;
  updateProfile: (updates: Partial<Profile>) => Promise<{ error: Error | null }>;
}

const AuthContext = createContext<AuthContextType | undefined>(undefined);

// Supabase client singleton
let supabaseClient: SupabaseClient | null = null;

export function getSupabaseClient(): SupabaseClient | null {
  if (!supabaseClient && import.meta.env.VITE_SUPABASE_URL) {
    supabaseClient = createClient(
      import.meta.env.VITE_SUPABASE_URL,
      import.meta.env.VITE_SUPABASE_ANON_KEY
    );
  }
  return supabaseClient;
}

export function AuthProvider({ children }: { children: React.ReactNode }) {
  const [user, setUser] = useState<User | null>(null);
  const [profile, setProfile] = useState<Profile | null>(null);
  const [session, setSession] = useState<Session | null>(null);
  const [isLoading, setIsLoading] = useState(true);

  const isLocalDevMode = !import.meta.env.VITE_SUPABASE_URL;

  useEffect(() => {
    if (isLocalDevMode) {
      // Local dev mode - use demo user
      setUser({ id: 'demo-user', email: 'demo@local.dev' } as User);
      setProfile({
        id: 'demo-user',
        username: 'demo',
        display_name: 'Demo User',
        avatar_url: null,
        bio: 'Local development user',
      });
      setIsLoading(false);
      return;
    }

    const supabase = getSupabaseClient();
    if (!supabase) return;

    // Get initial session
    supabase.auth.getSession().then(({ data: { session } }) => {
      setSession(session);
      setUser(session?.user ?? null);
      if (session?.user) {
        fetchProfile(session.user.id);
      }
      setIsLoading(false);
    });

    // Listen for auth changes
    const { data: { subscription } } = supabase.auth.onAuthStateChange(
      async (event, session) => {
        setSession(session);
        setUser(session?.user ?? null);

        if (event === 'SIGNED_IN' && session?.user) {
          await fetchProfile(session.user.id);
        } else if (event === 'SIGNED_OUT') {
          setProfile(null);
        }
      }
    );

    return () => subscription.unsubscribe();
  }, [isLocalDevMode]);

  async function fetchProfile(userId: string) {
    const supabase = getSupabaseClient();
    if (!supabase) return;

    const { data, error } = await supabase
      .from('profiles')
      .select('*')
      .eq('id', userId)
      .single();

    if (!error && data) {
      setProfile(data);
    }
  }

  async function signUp(email: string, password: string) {
    const supabase = getSupabaseClient();
    if (!supabase) return { error: new Error('Supabase not configured') };

    const { error } = await supabase.auth.signUp({ email, password });
    return { error };
  }

  async function signIn(email: string, password: string) {
    const supabase = getSupabaseClient();
    if (!supabase) return { error: new Error('Supabase not configured') };

    const { error } = await supabase.auth.signInWithPassword({ email, password });
    return { error };
  }

  async function signInWithOAuth(provider: 'google' | 'github') {
    const supabase = getSupabaseClient();
    if (!supabase) return;

    await supabase.auth.signInWithOAuth({
      provider,
      options: {
        redirectTo: `${window.location.origin}/auth/callback`,
      },
    });
  }

  async function signOut() {
    const supabase = getSupabaseClient();
    if (!supabase) return;

    await supabase.auth.signOut();
  }

  async function updateProfile(updates: Partial<Profile>) {
    const supabase = getSupabaseClient();
    if (!supabase || !user) return { error: new Error('Not authenticated') };

    const { error } = await supabase
      .from('profiles')
      .update(updates)
      .eq('id', user.id);

    if (!error) {
      setProfile((prev) => prev ? { ...prev, ...updates } : null);
    }

    return { error };
  }

  const value: AuthContextType = {
    user,
    profile,
    session,
    isLoading,
    isAuthenticated: !!user,
    isLocalDevMode,
    signUp,
    signIn,
    signInWithOAuth,
    signOut,
    updateProfile,
  };

  return (
    <AuthContext.Provider value={value}>
      {children}
    </AuthContext.Provider>
  );
}

export function useAuth() {
  const context = useContext(AuthContext);
  if (context === undefined) {
    throw new Error('useAuth must be used within an AuthProvider');
  }
  return context;
}

Protected Routes

ProtectedRoute Component

typescript

// src/components/ProtectedRoute.tsx

import { Navigate, useLocation } from 'react-router-dom';
import { useAuth } from '@/contexts/AuthContext';

interface ProtectedRouteProps {
  children: React.ReactNode;
  requireProfile?: boolean;
}

export function ProtectedRoute({ children, requireProfile = false }: ProtectedRouteProps) {
  const { isAuthenticated, isLoading, profile, isLocalDevMode } = useAuth();
  const location = useLocation();

  // Show loading while checking auth
  if (isLoading) {
    return <LoadingSpinner />;
  }

  // Local dev mode - always authenticated
  if (isLocalDevMode) {
    return <>{children}</>;
  }

  // Not authenticated - redirect to login
  if (!isAuthenticated) {
    return <Navigate to="/login" state={{ from: location }} replace />;
  }

  // Need profile but don't have one - redirect to onboarding
  if (requireProfile && !profile?.username) {
    return <Navigate to="/onboarding" state={{ from: location }} replace />;
  }

  return <>{children}</>;
}

Route Setup

typescript

// src/App.tsx or routes.tsx

import { Routes, Route } from 'react-router-dom';
import { ProtectedRoute } from '@/components/ProtectedRoute';

function AppRoutes() {
  return (
    <Routes>
      {/* Public routes */}
      <Route path="/login" element={<LoginPage />} />
      <Route path="/signup" element={<SignupPage />} />
      <Route path="/auth/callback" element={<AuthCallback />} />

      {/* Protected routes */}
      <Route
        path="/dashboard"
        element={
          <ProtectedRoute>
            <DashboardPage />
          </ProtectedRoute>
        }
      />

      {/* Protected + requires profile */}
      <Route
        path="/canvas/:id"
        element={
          <ProtectedRoute requireProfile>
            <EditorPage />
          </ProtectedRoute>
        }
      />

      {/* Public canvas viewing */}
      <Route path="/c/:slug" element={<PublicCanvasPage />} />
    </Routes>
  );
}

Auth Components

Login Form

typescript

// src/components/auth/LoginForm.tsx

import { useState } from 'react';
import { useAuth } from '@/contexts/AuthContext';
import { useNavigate, useLocation } from 'react-router-dom';

export function LoginForm() {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [error, setError] = useState('');
  const [isSubmitting, setIsSubmitting] = useState(false);

  const { signIn, signInWithOAuth } = useAuth();
  const navigate = useNavigate();
  const location = useLocation();

  const from = location.state?.from?.pathname || '/dashboard';

  async function handleSubmit(e: React.FormEvent) {
    e.preventDefault();
    setError('');
    setIsSubmitting(true);

    const { error } = await signIn(email, password);

    if (error) {
      setError(error.message);
      setIsSubmitting(false);
    } else {
      navigate(from, { replace: true });
    }
  }

  return (
    <form onSubmit={handleSubmit}>
      {error && <div className="error">{error}</div>}

      <input
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        placeholder="Email"
        required
      />

      <input
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
        placeholder="Password"
        required
      />

      <button type="submit" disabled={isSubmitting}>
        {isSubmitting ? 'Signing in...' : 'Sign In'}
      </button>

      <div className="oauth-buttons">
        <button type="button" onClick={() => signInWithOAuth('google')}>
          Continue with Google
        </button>
        <button type="button" onClick={() => signInWithOAuth('github')}>
          Continue with GitHub
        </button>
      </div>
    </form>
  );
}

OAuth Callback Handler

typescript

// src/pages/AuthCallback.tsx

import { useEffect } from 'react';
import { useNavigate } from 'react-router-dom';
import { getSupabaseClient } from '@/contexts/AuthContext';

export function AuthCallback() {
  const navigate = useNavigate();

  useEffect(() => {
    const supabase = getSupabaseClient();
    if (!supabase) {
      navigate('/login');
      return;
    }

    // Handle OAuth callback
    supabase.auth.getSession().then(({ data: { session } }) => {
      if (session) {
        // Check if profile exists
        supabase
          .from('profiles')
          .select('username')
          .eq('id', session.user.id)
          .single()
          .then(({ data }) => {
            if (data?.username) {
              navigate('/dashboard');
            } else {
              navigate('/onboarding');
            }
          });
      } else {
        navigate('/login');
      }
    });
  }, [navigate]);

  return <LoadingSpinner />;
}

Widget Authentication

Providing Auth to Widgets

typescript

// src/runtime/WidgetHost.ts

class WidgetHost {
  private sendAuthInfo() {
    const { user, profile, isAuthenticated } = this.authContext;

    // Only send safe, read-only info to widget
    this.sendMessage('widget:auth', {
      isAuthenticated,
      userId: user?.id || null,
      username: profile?.username || null,
      displayName: profile?.display_name || null,
      avatarUrl: profile?.avatar_url || null,
      // Never send: email, tokens, session
    });
  }

  // Handle auth-requiring requests from widgets
  private handleWidgetRequest(action: string, data: any) {
    if (!this.authContext.isAuthenticated) {
      return { error: 'Not authenticated' };
    }

    switch (action) {
      case 'social:follow':
        return SocialGraphService.followUser(data.userId);
      case 'social:sendMessage':
        return ChatService.sendMessage(data.channelId, data.content);
      // ... other authenticated actions
    }
  }
}

Widget-Side Auth Handling

javascript

// In widget code
const WidgetAPI = {
  auth: null,

  handleMessage(event) {
    if (event.data.type === 'widget:auth') {
      this.auth = event.data.payload;
      this.onAuthChange?.(this.auth);
    }
  },

  isAuthenticated() {
    return this.auth?.isAuthenticated ?? false;
  },

  getCurrentUser() {
    return this.auth;
  },

  // Request that requires auth
  async sendMessage(content) {
    if (!this.isAuthenticated()) {
      throw new Error('Authentication required');
    }
    return this.request('social:sendMessage', { content });
  }
};

Session Management

Token Refresh

typescript

// Supabase handles token refresh automatically
// But you can listen for refresh events:

supabase.auth.onAuthStateChange((event, session) => {
  if (event === 'TOKEN_REFRESHED') {
    console.log('Token refreshed');
    // Update any cached tokens
  }
});

Session Persistence

typescript

// Configure session persistence (default is localStorage)
const supabase = createClient(url, key, {
  auth: {
    persistSession: true,
    storageKey: 'stickernest-auth',
    storage: window.localStorage,
  },
});

Permission Checks

Service-Level Authorization

typescript

// In services, always verify user can perform action

export async function deleteCanvas(canvasId: string): Promise<void> {
  const supabase = getSupabaseClient();
  const user = (await supabase.auth.getUser()).data.user;

  if (!user) {
    throw new Error('Not authenticated');
  }

  // RLS will also enforce this, but explicit check is good practice
  const { data: canvas } = await supabase
    .from('canvases')
    .select('user_id')
    .eq('id', canvasId)
    .single();

  if (canvas?.user_id !== user.id) {
    throw new Error('Not authorized');
  }

  await supabase.from('canvases').delete().eq('id', canvasId);
}

Hook for Permission Checks

typescript

// src/hooks/usePermission.ts

export function usePermission() {
  const { user, profile } = useAuth();

  return {
    canEditCanvas: (canvas: Canvas) => canvas.user_id === user?.id,
    canDeleteWidget: (widget: Widget, canvas: Canvas) => canvas.user_id === user?.id,
    canFollow: (targetUserId: string) => user?.id !== targetUserId,
    canSendDM: (targetUserId: string) => user?.id !== targetUserId,
    isOwner: (resource: { user_id: string }) => resource.user_id === user?.id,
  };
}

Local Development Mode

Demo User Setup

typescript

// When VITE_SUPABASE_URL is not set, use local mode

const isLocalDevMode = !import.meta.env.VITE_SUPABASE_URL;

if (isLocalDevMode) {
  // Use demo user
  const demoUser = {
    id: 'demo-user-id',
    email: 'demo@local.dev',
  };

  const demoProfile = {
    id: 'demo-user-id',
    username: 'demo',
    display_name: 'Demo User',
    avatar_url: null,
  };

  // Store in localStorage
  localStorage.setItem('demo-user', JSON.stringify(demoUser));
  localStorage.setItem('demo-profile', JSON.stringify(demoProfile));
}

Error Handling

Auth Error Types

typescript

type AuthError =
  | 'invalid_credentials'
  | 'email_not_confirmed'
  | 'user_not_found'
  | 'email_taken'
  | 'weak_password'
  | 'rate_limited'
  | 'network_error';

function getAuthErrorMessage(error: any): string {
  const message = error?.message?.toLowerCase() || '';

  if (message.includes('invalid login')) return 'Invalid email or password';
  if (message.includes('email not confirmed')) return 'Please confirm your email';
  if (message.includes('already registered')) return 'Email already registered';
  if (message.includes('password')) return 'Password must be at least 6 characters';
  if (message.includes('rate limit')) return 'Too many attempts. Please wait.';

  return 'An error occurred. Please try again.';
}

Reference Files

File	Purpose
`src/contexts/AuthContext.tsx`	Auth provider and hooks
`src/components/ProtectedRoute.tsx`	Route protection
`src/pages/Login.tsx`	Login page
`src/pages/Signup.tsx`	Signup page
`src/pages/AuthCallback.tsx`	OAuth callback handler
`src/runtime/WidgetHost.ts`	Widget auth integration

Best Practices

Never expose tokens to widgets - Only send user ID and profile info
Use RLS as primary security - Service checks are secondary
Handle loading states - Show spinners during auth checks
Redirect after login - Return to original destination
Support local dev mode - Demo user for offline development
Validate on server - Never trust client-side checks alone
Use secure cookies - For session persistence in production
Implement rate limiting - Prevent brute force attacks

Search AI Tools

handling-authentication

Install this agent skill to your Project

SKILL.md

Handling Authentication in StickerNest

Architecture Overview

AuthContext Implementation

Location: `src/contexts/AuthContext.tsx`

Protected Routes

ProtectedRoute Component

Route Setup

Auth Components

Login Form

OAuth Callback Handler

Widget Authentication

Providing Auth to Widgets

Widget-Side Auth Handling

Session Management

Token Refresh

Session Persistence

Permission Checks

Service-Level Authorization

Hook for Permission Checks

Local Development Mode

Demo User Setup

Error Handling

Auth Error Types

Reference Files

Best Practices

Search AI Tools

Install this agent skill to your Project

SKILL.md

Handling Authentication in StickerNest

Architecture Overview

AuthContext Implementation

Location: src/contexts/AuthContext.tsx

Protected Routes

ProtectedRoute Component

Route Setup

Auth Components

Login Form

OAuth Callback Handler

Widget Authentication

Providing Auth to Widgets

Widget-Side Auth Handling

Session Management

Token Refresh

Session Persistence

Permission Checks

Service-Level Authorization

Hook for Permission Checks

Local Development Mode

Demo User Setup

Error Handling

Auth Error Types

Reference Files

Best Practices

Location: `src/contexts/AuthContext.tsx`