@startsimpli/auth 0.4.6 → 0.4.7

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@startsimpli/auth",
-  "version": "0.4.6",
+  "version": "0.4.7",
   "description": "Shared authentication package for StartSimpli Next.js apps",
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "exports": {
     ".": "./src/index.ts",
     "./client": "./src/client/index.ts",
+    "./components": "./src/components/index.ts",
     "./server": "./src/server/index.ts",
     "./types": "./src/types/index.ts",
     "./email": "./src/email/index.ts"

package/src/__tests__/auth-client.test.ts

@@ -4,7 +4,7 @@ import { AuthClient } from '../client/auth-client';
 // Helpers
 function makeToken(exp: number): string {
   const header = btoa(JSON.stringify({ alg: 'HS256', typ: 'JWT' }));
-  const body = btoa(JSON.stringify({ token_type: 'access', exp, iat: exp - 3600, jti: 'test', user_id: '123' }));
+  const body = btoa(JSON.stringify({ tokenType: 'access', exp, iat: exp - 3600, jti: 'test', userId: '123' }));
   return `${header}.${body}.signature`;
 }
 

package/src/__tests__/auth-fetch.test.ts

@@ -36,8 +36,8 @@ function makeJwt(payload: object): string {
   return `${encode({ alg: 'HS256' })}.${encode(payload)}.sig`;
 }
 
-const VALID_TOKEN = makeJwt({ exp: Math.floor(Date.now() / 1000) + 3600, user_id: '1' });
-const REFRESHED_TOKEN = makeJwt({ exp: Math.floor(Date.now() / 1000) + 7200, user_id: '1' });
+const VALID_TOKEN = makeJwt({ exp: Math.floor(Date.now() / 1000) + 3600, userId: '1' });
+const REFRESHED_TOKEN = makeJwt({ exp: Math.floor(Date.now() / 1000) + 7200, userId: '1' });
 
 // Stub the CSRF token helper so refreshAccessToken() doesn't fail
 vi.mock('../utils/cookies', () => ({

package/src/__tests__/auth-functions.test.ts

@@ -83,7 +83,7 @@ function makeJwt(payload: object): string {
   return `${encode({ alg: 'HS256' })}.${encode(payload)}.sig`;
 }
 
-const VALID_TOKEN = makeJwt({ exp: Math.floor(Date.now() / 1000) + 3600, user_id: '1' });
+const VALID_TOKEN = makeJwt({ exp: Math.floor(Date.now() / 1000) + 3600, userId: '1' });
 
 describe('CSRF not required for signin/register (endpoints are @csrf_exempt)', () => {
   beforeEach(() => {

package/src/__tests__/token.test.ts

@@ -10,16 +10,16 @@ describe('Token utilities', () => {
   describe('decodeToken', () => {
     it('should decode valid JWT token', () => {
       const token =
-        'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlbl90eXBlIjoiYWNjZXNzIiwiZXhwIjoxNzM5MjI3MjAwLCJpYXQiOjE3MzkxNDA4MDAsImp0aSI6InRlc3QtanRpIiwidXNlcl9pZCI6IjEyMzQ1In0.test-signature';
+        'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJ0b2tlblR5cGUiOiJhY2Nlc3MiLCJleHAiOjE3MzkyMjcyMDAsImlhdCI6MTczOTE0MDgwMCwianRpIjoidGVzdC1qdGkiLCJ1c2VySWQiOiIxMjM0NSJ9.test-signature';
 
       const payload = decodeToken(token);
 
       expect(payload).toEqual({
-        token_type: 'access',
+        tokenType: 'access',
         exp: 1739227200,
         iat: 1739140800,
         jti: 'test-jti',
-        user_id: '12345',
+        userId: '12345',
       });
     });
 

package/src/components/google-sign-in-button.tsx

@@ -0,0 +1,78 @@
+'use client'
+
+import { useState } from 'react'
+import { initiateGoogleOAuth } from '../client/functions'
+
+export interface GoogleSignInButtonProps {
+  /** Path for the OAuth callback page (default: "/auth/callback") */
+  callbackPath?: string
+  /** URL to redirect to after successful auth */
+  redirectTo?: string
+  /** Error handler */
+  onError?: (message: string) => void
+  /** Button text (default: "Continue with Google") */
+  children?: React.ReactNode
+  /** Additional class names */
+  className?: string
+  /** Disabled state */
+  disabled?: boolean
+}
+
+/**
+ * Google Sign-In button that handles the full OAuth initiate flow:
+ * 1. Calls backend to get authorization URL with PKCE
+ * 2. Stores state nonce in sessionStorage for CSRF protection
+ * 3. Redirects to Google consent screen
+ */
+export function GoogleSignInButton({
+  callbackPath = '/auth/callback',
+  redirectTo,
+  onError,
+  children,
+  className,
+  disabled,
+}: GoogleSignInButtonProps) {
+  const [isLoading, setIsLoading] = useState(false)
+
+  const handleClick = async () => {
+    setIsLoading(true)
+    try {
+      // Use a clean callback URL with no query params — Google requires exact redirect_uri match
+      const redirectUri = new URL(callbackPath, window.location.origin).toString()
+
+      const data = await initiateGoogleOAuth(redirectUri)
+      if (!data?.authorization_url) {
+        throw new Error('Missing authorization URL from server')
+      }
+
+      // Store state nonce for CSRF validation on the callback page
+      const authUrlParams = new URL(data.authorization_url).searchParams
+      const stateNonce = authUrlParams.get('state')
+      if (stateNonce) {
+        sessionStorage.setItem('oauth_state_nonce', stateNonce)
+      }
+
+      // Store post-auth redirect separately (not in the redirect_uri)
+      if (redirectTo) {
+        sessionStorage.setItem('oauth_redirect_to', redirectTo)
+      }
+
+      window.location.href = data.authorization_url
+    } catch (err) {
+      setIsLoading(false)
+      const message = err instanceof Error ? err.message : 'Failed to initiate Google sign-in'
+      onError?.(message)
+    }
+  }
+
+  return (
+    <button
+      type="button"
+      onClick={handleClick}
+      disabled={disabled || isLoading}
+      className={className}
+    >
+      {children ?? 'Continue with Google'}
+    </button>
+  )
+}

package/src/components/index.ts

@@ -0,0 +1,4 @@
+export { GoogleSignInButton, type GoogleSignInButtonProps } from './google-sign-in-button'
+export { OAuthCallback, type OAuthCallbackProps } from './oauth-callback'
+export { useOAuthCallback, type UseOAuthCallbackOptions, type UseOAuthCallbackReturn, type OAuthCallbackResult } from './use-oauth-callback'
+export { OAuthConnectionCard, type OAuthConnectionCardProps } from './oauth-connection-card'

package/src/components/oauth-callback.tsx

@@ -0,0 +1,95 @@
+'use client'
+
+import type { AuthUser } from '../types'
+import { useOAuthCallback, type OAuthCallbackResult } from './use-oauth-callback'
+
+export interface OAuthCallbackProps {
+  /** Code from OAuth redirect URL params */
+  code: string | null
+  /** State from OAuth redirect URL params */
+  state: string | null
+  /** Called on successful authentication. redirectTo is the path stored by GoogleSignInButton. */
+  onSuccess: (result: OAuthCallbackResult & { redirectTo: string }) => void
+  /** Called on error */
+  onError?: (message: string) => void
+  /** Path to redirect to on "Back to Sign In" (default: "/auth/signin") */
+  signInPath?: string
+  /** Custom loading content */
+  loadingContent?: React.ReactNode
+  /** Custom error content renderer */
+  renderError?: (error: string, signInPath: string) => React.ReactNode
+}
+
+/**
+ * OAuth callback handler component with built-in loading/error UI.
+ *
+ * Handles the full callback flow: state validation, token exchange, user fetch.
+ * Drop into your /auth/callback page:
+ *
+ * ```tsx
+ * const searchParams = useSearchParams()
+ * <OAuthCallback
+ *   code={searchParams.get('code')}
+ *   state={searchParams.get('state')}
+ *   onSuccess={({ access, user }) => {
+ *     setAccessToken(access); setUser(user); router.replace('/dashboard')
+ *   }}
+ * />
+ * ```
+ */
+export function OAuthCallback({
+  code,
+  state,
+  onSuccess,
+  onError,
+  signInPath = '/auth/signin',
+  loadingContent,
+  renderError,
+}: OAuthCallbackProps) {
+  const { error, isProcessing, redirectTo } = useOAuthCallback(
+    { code, state },
+    {
+      onSuccess: (result) => onSuccess({ ...result, redirectTo }),
+      onError,
+    },
+  )
+
+  if (error) {
+    if (renderError) {
+      return <>{renderError(error, signInPath)}</>
+    }
+
+    return (
+      <div className="min-h-screen flex items-center justify-center bg-gradient-to-br from-slate-50 to-slate-100 p-4">
+        <div className="w-full max-w-md rounded-2xl bg-white p-8 shadow-xl shadow-slate-200/50 ring-1 ring-slate-200 text-center">
+          <h1 className="text-2xl font-bold text-slate-900 mb-2">Authentication failed</h1>
+          <p className="text-slate-600 mb-6">{error}</p>
+          <a
+            href={signInPath}
+            className="inline-block w-full rounded-lg bg-indigo-600 px-4 py-2.5 text-sm font-semibold text-white shadow-sm hover:bg-indigo-500"
+          >
+            Back to Sign In
+          </a>
+        </div>
+      </div>
+    )
+  }
+
+  if (isProcessing) {
+    if (loadingContent) {
+      return <>{loadingContent}</>
+    }
+
+    return (
+      <div className="min-h-screen flex items-center justify-center bg-gradient-to-br from-slate-50 to-slate-100 p-4">
+        <div className="w-full max-w-md rounded-2xl bg-white p-8 shadow-xl shadow-slate-200/50 ring-1 ring-slate-200 text-center">
+          <div className="mx-auto mb-4 h-12 w-12 animate-spin rounded-full border-4 border-indigo-200 border-t-indigo-600" />
+          <h1 className="text-xl font-semibold text-slate-900">Finishing sign in...</h1>
+          <p className="text-slate-600 mt-2">This will only take a moment.</p>
+        </div>
+      </div>
+    )
+  }
+
+  return null
+}

package/src/components/oauth-connection-card.tsx

@@ -0,0 +1,117 @@
+'use client'
+
+import { useState, useCallback } from 'react'
+
+export interface OAuthConnectionCardProps {
+  providerName: string
+  providerIcon?: React.ReactNode
+  description?: string
+  connected: boolean
+  accountLabel?: string
+  lastSync?: string
+  connectUrl?: string
+  onConnect?: () => void | Promise<void>
+  onDisconnect?: () => void | Promise<void>
+}
+
+/**
+ * Card showing OAuth service connection status with connect/disconnect actions.
+ * Used for email (Gmail/Outlook), calendar, CRM integrations.
+ */
+export function OAuthConnectionCard({
+  providerName,
+  providerIcon,
+  description,
+  connected,
+  accountLabel,
+  lastSync,
+  connectUrl,
+  onConnect,
+  onDisconnect,
+}: OAuthConnectionCardProps) {
+  const [isLoading, setIsLoading] = useState(false)
+
+  const handleConnect = useCallback(async () => {
+    if (connectUrl) {
+      window.location.href = connectUrl
+      return
+    }
+    if (onConnect) {
+      setIsLoading(true)
+      try {
+        await onConnect()
+      } finally {
+        setIsLoading(false)
+      }
+    }
+  }, [connectUrl, onConnect])
+
+  const handleDisconnect = useCallback(async () => {
+    if (onDisconnect) {
+      setIsLoading(true)
+      try {
+        await onDisconnect()
+      } finally {
+        setIsLoading(false)
+      }
+    }
+  }, [onDisconnect])
+
+  return (
+    <div className="rounded-lg border border-gray-200 bg-white p-5">
+      <div className="flex items-start gap-4">
+        {providerIcon && (
+          <div className="flex-shrink-0 w-10 h-10 rounded-lg bg-gray-100 flex items-center justify-center">
+            {providerIcon}
+          </div>
+        )}
+        <div className="flex-1 min-w-0">
+          <div className="flex items-center justify-between mb-1">
+            <h3 className="font-medium text-gray-900">{providerName}</h3>
+            <span
+              className={`text-xs px-2 py-0.5 rounded-full font-medium ${
+                connected
+                  ? 'bg-green-100 text-green-700'
+                  : 'bg-gray-100 text-gray-500'
+              }`}
+            >
+              {connected ? 'Connected' : 'Not connected'}
+            </span>
+          </div>
+
+          {description && (
+            <p className="text-sm text-gray-600 mb-2">{description}</p>
+          )}
+
+          {connected && accountLabel && (
+            <p className="text-sm text-gray-700 mb-1">{accountLabel}</p>
+          )}
+
+          {connected && lastSync && (
+            <p className="text-xs text-gray-400 mb-2">Last sync: {lastSync}</p>
+          )}
+
+          <div className="mt-3">
+            {connected ? (
+              <button
+                onClick={handleDisconnect}
+                disabled={isLoading}
+                className="px-3 py-1.5 text-sm font-medium text-red-700 bg-red-50 hover:bg-red-100 rounded-md disabled:opacity-50 transition-colors"
+              >
+                {isLoading ? 'Disconnecting...' : 'Disconnect'}
+              </button>
+            ) : (
+              <button
+                onClick={handleConnect}
+                disabled={isLoading}
+                className="px-3 py-1.5 text-sm font-medium text-white bg-blue-600 hover:bg-blue-700 rounded-md disabled:opacity-50 transition-colors"
+              >
+                {isLoading ? 'Connecting...' : `Connect ${providerName}`}
+              </button>
+            )}
+          </div>
+        </div>
+      </div>
+    </div>
+  )
+}

package/src/components/use-oauth-callback.ts

@@ -0,0 +1,123 @@
+'use client'
+
+import { useEffect, useRef, useState } from 'react'
+import { completeGoogleOAuth, getMe } from '../client/functions'
+import type { AuthUser } from '../types'
+
+export interface OAuthCallbackResult {
+  /** Access token from successful auth */
+  access: string
+  /** Authenticated user */
+  user: AuthUser
+}
+
+export interface UseOAuthCallbackOptions {
+  /** Called on successful authentication */
+  onSuccess: (result: OAuthCallbackResult) => void
+  /** Called on error */
+  onError?: (message: string) => void
+}
+
+export interface UseOAuthCallbackReturn {
+  /** Error message if callback failed */
+  error: string
+  /** Whether the callback is still processing */
+  isProcessing: boolean
+  /** Post-auth redirect path stored by GoogleSignInButton (default: '/dashboard') */
+  redirectTo: string
+}
+
+/**
+ * Hook that handles the OAuth callback flow:
+ * 1. Reads code + state from URL search params
+ * 2. Validates state nonce against sessionStorage (CSRF protection)
+ * 3. Exchanges code for tokens via backend
+ * 4. Fetches user if not returned with tokens
+ * 5. Calls onSuccess with access token + user
+ *
+ * Usage in a Next.js callback page:
+ * ```tsx
+ * const searchParams = useSearchParams()
+ * const { error, isProcessing } = useOAuthCallback({
+ *   code: searchParams.get('code'),
+ *   state: searchParams.get('state'),
+ *   onSuccess: ({ access, user }) => {
+ *     setAccessToken(access)
+ *     setUser(user)
+ *     router.replace('/dashboard')
+ *   },
+ * })
+ * ```
+ */
+export function useOAuthCallback(
+  params: {
+    code: string | null
+    state: string | null
+  },
+  options: UseOAuthCallbackOptions,
+): UseOAuthCallbackReturn {
+  const [error, setError] = useState('')
+  const [isProcessing, setIsProcessing] = useState(true)
+  const [redirectTo] = useState(() => {
+    if (typeof window === 'undefined') return '/dashboard'
+    const stored = sessionStorage.getItem('oauth_redirect_to')
+    sessionStorage.removeItem('oauth_redirect_to')
+    return stored || '/dashboard'
+  })
+  const ranRef = useRef(false)
+
+  useEffect(() => {
+    // Prevent double-execution in React strict mode
+    if (ranRef.current) return
+    ranRef.current = true
+
+    const handleCallback = async () => {
+      const { code, state } = params
+      if (!code || !state) {
+        setError('Invalid OAuth callback — missing code or state')
+        setIsProcessing(false)
+        return
+      }
+
+      // CSRF check: validate state nonce against pre-auth sessionStorage value
+      const storedNonce = sessionStorage.getItem('oauth_state_nonce')
+      sessionStorage.removeItem('oauth_state_nonce')
+      if (!storedNonce || storedNonce !== state) {
+        setError('Invalid OAuth state — possible CSRF attempt')
+        setIsProcessing(false)
+        return
+      }
+
+      try {
+        const result = await completeGoogleOAuth(code, state)
+        const access = result?.access
+
+        if (!access) {
+          throw new Error('No access token returned')
+        }
+
+        let user = result?.user as AuthUser | undefined
+        if (!user) {
+          user = await getMe() as AuthUser | undefined
+        }
+
+        if (!user) {
+          throw new Error('Failed to retrieve user after authentication')
+        }
+
+        setIsProcessing(false)
+        options.onSuccess({ access, user })
+      } catch (err) {
+        const message = err instanceof Error ? err.message : 'Authentication failed'
+        setError(message)
+        setIsProcessing(false)
+        options.onError?.(message)
+      }
+    }
+
+    handleCallback()
+  // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [])
+
+  return { error, isProcessing, redirectTo }
+}

package/src/types/index.ts

@@ -58,11 +58,11 @@ export interface AuthUser {
  * JWT token payload structure
  */
 export interface TokenPayload {
-  token_type: 'access';
+  tokenType: 'access';
   exp: number;
   iat: number;
   jti: string;
-  user_id: string;
+  userId: string;
 }
 
 /**