@chesapeake/stack 0.1.0

package/components/ux/auth/MultiAuthProvider.tsx

@@ -0,0 +1,196 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+/** @jsxImportSource react */
+import { useCallback, useEffect, useState } from "react";
+import type { GoogleAuthConfig } from "./google/config.ts";
+import type { GitHubAuthConfig } from "./github/config.ts";
+import { GoogleAuthProvider } from "./google/AuthProvider.tsx";
+import { GitHubAuthProvider } from "./github/AuthProvider.tsx";
+import { GoogleAuthClient } from "./google/client.ts";
+import { GitHubAuthClient } from "./github/client.ts";
+import { initiateGoogleLogin as defaultInitiateGoogleLogin } from "./google/default-client.ts";
+import { initiateGitHubLogin as defaultInitiateGitHubLogin } from "./github/default-client.ts";
+
+import {
+  type AuthUser,
+  MultiAuthContext,
+  type MultiAuthProviderProps,
+} from "./context.ts";
+
+/**
+ * Multi-Provider Auth Provider component
+ * Wraps individual providers and provides unified auth interface
+ */
+export function MultiAuthProvider({
+  children,
+  providers,
+  storageKey,
+  apiBaseUrl,
+  onUserUpdate,
+}: MultiAuthProviderProps) {
+  const [user, setUser] = useState<AuthUser | null>(null);
+  const [loading, setLoading] = useState(true);
+  const [activeProvider, setActiveProvider] = useState<
+    "google" | "github" | null
+  >(null);
+
+  const googleConfig = providers.find(
+    (p) => p.provider === "google" && p.enabled
+  );
+  const githubConfig = providers.find(
+    (p) => p.provider === "github" && p.enabled
+  );
+
+  useEffect(() => {
+    // Initial load from localStorage
+    const key = storageKey ?? "user";
+    const storedUser = localStorage.getItem(key);
+    if (storedUser) {
+      try {
+        const parsedUser = JSON.parse(storedUser) as AuthUser;
+        // Validate that parsed user is actually a valid user object
+        // Reject null, empty objects, or invalid values
+        if (
+          typeof parsedUser === "object" &&
+          Object.keys(parsedUser).length > 0
+        ) {
+          setUser(parsedUser);
+          setActiveProvider(
+            (parsedUser as { provider?: "google" | "github" }).provider ?? null
+          );
+        } else {
+          // Invalid user data, clear it
+          localStorage.removeItem(key);
+        }
+      } catch (error) {
+        console.error("Error parsing stored user:", error);
+        localStorage.removeItem(key);
+      }
+    }
+    setLoading(false);
+  }, [storageKey]);
+
+  const updateUser = useCallback(
+    (newUser: AuthUser | null, provider?: "google" | "github") => {
+      setUser(newUser);
+      const key = storageKey ?? "user";
+      if (newUser) {
+        const userWithProvider = {
+          ...newUser,
+          provider:
+            provider ??
+            (newUser as { provider?: "google" | "github" }).provider,
+        };
+        localStorage.setItem(key, JSON.stringify(userWithProvider));
+        setActiveProvider(
+          provider ??
+            (newUser as { provider?: "google" | "github" }).provider ??
+            null
+        );
+      } else {
+        localStorage.removeItem(key);
+        setActiveProvider(null);
+      }
+      onUserUpdate?.(newUser);
+    },
+    [storageKey, onUserUpdate]
+  );
+
+  const signOut = useCallback(() => {
+    setLoading(true);
+    const key = storageKey ?? "user";
+    localStorage.removeItem(key);
+    setUser(null);
+    setActiveProvider(null);
+    onUserUpdate?.(null);
+    setLoading(false);
+  }, [storageKey, onUserUpdate]);
+
+  const signInWithGoogle = useCallback(() => {
+    if (googleConfig) {
+      if (googleConfig.config) {
+        const client = new GoogleAuthClient(
+          googleConfig.config as GoogleAuthConfig
+        );
+        client.initiateLogin();
+      } else {
+        defaultInitiateGoogleLogin();
+      }
+    }
+  }, [googleConfig]);
+
+  const signInWithGitHub = useCallback(() => {
+    if (githubConfig) {
+      if (githubConfig.config) {
+        const client = new GitHubAuthClient(
+          githubConfig.config as GitHubAuthConfig
+        );
+        client.initiateLogin();
+      } else {
+        defaultInitiateGitHubLogin();
+      }
+    }
+  }, [githubConfig]);
+
+  // Render providers based on configuration
+  let content = children;
+
+  // Wrap with GitHub provider if enabled
+  if (githubConfig) {
+    content = (
+      <GitHubAuthProvider
+        apiBaseUrl={apiBaseUrl}
+        storageKey={storageKey}
+        config={githubConfig.config as GitHubAuthConfig}
+        onUserUpdate={(user) => {
+          if (user) {
+            updateUser(user as AuthUser, "github");
+          } else if (activeProvider === "github") {
+            updateUser(null);
+          }
+        }}
+      >
+        {content}
+      </GitHubAuthProvider>
+    );
+  }
+
+  // Wrap with Google provider if enabled
+  if (googleConfig) {
+    content = (
+      <GoogleAuthProvider
+        apiBaseUrl={apiBaseUrl}
+        storageKey={storageKey}
+        config={googleConfig.config as GoogleAuthConfig}
+        onUserUpdate={(user) => {
+          if (user) {
+            updateUser(user as AuthUser, "google");
+          } else if (activeProvider === "google") {
+            updateUser(null);
+          }
+        }}
+      >
+        {content}
+      </GoogleAuthProvider>
+    );
+  }
+
+  return (
+    <MultiAuthContext.Provider
+      value={{
+        user,
+        loading,
+        provider: activeProvider,
+        signInWithGoogle,
+        signInWithGitHub,
+        signOut,
+        updateUser: (user) => {
+          updateUser(user, activeProvider ?? undefined);
+        },
+      }}
+    >
+      {content}
+    </MultiAuthContext.Provider>
+  );
+}

package/components/ux/auth/README.md

@@ -0,0 +1,317 @@
+# Multi-Provider Authentication
+
+This package provides a unified authentication system that supports multiple
+OAuth providers (Google, GitHub) with a single interface. Apps can configure
+which providers are available, and users can choose which provider to use.
+
+## Features
+
+- 🔐 Support for multiple OAuth providers (Google, GitHub)
+- 🎛️ Configure which providers are enabled per app
+- 🎨 Unified `AuthSelector` component for provider selection
+- 🔄 Single user identity at a time (one provider active)
+- ⚙️ Both configurable and default client options
+- 📦 TypeScript types for type safety
+
+## Installation
+
+This package is part of the `@chesapeake/shared-components` package. Import
+from:
+
+```typescript
+import { ... } from "@shared/components/ux/auth";
+```
+
+## Quick Start
+
+### 1. Setup MultiAuthProvider
+
+Wrap your app with `MultiAuthProvider` and configure which providers are
+enabled:
+
+```tsx
+import {
+  type AuthProviderConfig,
+  MultiAuthProvider,
+} from "@shared/components/ux/auth";
+
+function App() {
+  // Configure which providers are available
+  const authProviders: AuthProviderConfig[] = [
+    { provider: "github", enabled: true },
+    { provider: "google", enabled: true }, // Enable both
+  ];
+
+  return (
+    <MultiAuthProvider providers={authProviders}>
+      <YourApp />
+    </MultiAuthProvider>
+  );
+}
+```
+
+### 2. Use AuthSelector Component
+
+The `AuthSelector` component provides buttons for enabled providers:
+
+```tsx
+import { AuthSelector } from "@shared/components/ux/auth";
+
+function LoginPage() {
+  return (
+    <AuthSelector
+      enableGithub={true}
+      enableGoogle={true}
+      onAuthSuccess={(user, provider) => {
+        console.log(`User authenticated with ${provider}:`, user);
+      }}
+    />
+  );
+}
+```
+
+### 3. Use Auth Hook
+
+Access auth state and methods with the unified `useAuth` hook:
+
+```tsx
+import { useAuth } from "@shared/components/ux/auth";
+
+function UserProfile() {
+  const { user, loading, provider, signOut } = useAuth();
+
+  if (loading) return <div>Loading...</div>;
+  if (!user) return <div>Not authenticated</div>;
+
+  return (
+    <div>
+      <p>Signed in with {provider}</p>
+      <button onClick={signOut}>Sign Out</button>
+    </div>
+  );
+}
+```
+
+## Configuration Examples
+
+### Single Provider (GitHub only)
+
+```tsx
+const authProviders: AuthProviderConfig[] = [
+  { provider: "github", enabled: true },
+  { provider: "google", enabled: false },
+];
+
+<MultiAuthProvider providers={authProviders}>
+  <AuthSelector enableGithub={true} enableGoogle={false} />
+</MultiAuthProvider>;
+```
+
+### Single Provider (Google only)
+
+```tsx
+const authProviders: AuthProviderConfig[] = [
+  { provider: "google", enabled: true },
+  { provider: "github", enabled: false },
+];
+
+<MultiAuthProvider providers={authProviders}>
+  <AuthSelector enableGoogle={true} enableGithub={false} />
+</MultiAuthProvider>;
+```
+
+### Custom Configuration
+
+You can provide custom configuration for each provider:
+
+```tsx
+const authProviders: AuthProviderConfig[] = [
+  {
+    provider: "github",
+    enabled: true,
+    config: {
+      clientId: "your-github-client-id",
+      redirectUri: "http://localhost:5173/auth/callback",
+      backendInitEndpoint: "/api/auth/github", // Optional: if backend handles OAuth
+    },
+  },
+  {
+    provider: "google",
+    enabled: true,
+    config: {
+      clientId: "your-google-client-id",
+      redirectUri: "http://localhost:5173/auth/callback",
+      scope: "openid email profile",
+    },
+  },
+];
+```
+
+### Using Default Clients
+
+If you don't provide config, the providers will use default clients that read
+from environment variables:
+
+```tsx
+// Uses VITE_GITHUB_CLIENT_ID or VITE_GITHUB_BACKEND_INIT_ENDPOINT
+const authProviders: AuthProviderConfig[] = [
+  { provider: "github", enabled: true }, // Uses default client
+  { provider: "google", enabled: true }, // Uses VITE_GOOGLE_CLIENT_ID
+];
+```
+
+## AuthSelector Component
+
+The `AuthSelector` component provides a ready-to-use UI for authentication:
+
+### Props
+
+```typescript
+interface AuthSelectorProps {
+  /** Enable Google OAuth provider */
+  enableGoogle?: boolean;
+  /** Enable GitHub OAuth provider */
+  enableGithub?: boolean;
+  /** Custom styling/className */
+  className?: string;
+  /** Callback when user successfully authenticates */
+  onAuthSuccess?: (user: AuthUser, provider: "google" | "github") => void;
+  /** Custom button components (optional) */
+  googleButton?: React.ReactNode;
+  githubButton?: React.ReactNode;
+}
+```
+
+### Behavior
+
+- Renders buttons for enabled providers
+- Buttons are disabled when user is already authenticated
+- Shows current authenticated provider state
+- Provides sign out button when authenticated
+- Only one provider can be active at a time
+
+## useAuth Hook
+
+The unified `useAuth` hook provides access to auth state and methods:
+
+```typescript
+interface MultiAuthContextType {
+  user: AuthUser | null;
+  loading: boolean;
+  provider: "google" | "github" | null;
+  signInWithGoogle: () => void;
+  signInWithGitHub: () => void;
+  signOut: () => void;
+  updateUser: (user: AuthUser | null) => void;
+}
+```
+
+## Backend Integration
+
+### Backend-Handled OAuth Flow
+
+If your backend handles the entire OAuth flow (common for server-side session
+management), configure providers with `backendInitEndpoint`:
+
+```tsx
+const authProviders: AuthProviderConfig[] = [
+  {
+    provider: "github",
+    enabled: true,
+    config: {
+      backendInitEndpoint: "/api/auth/github", // Backend handles OAuth initiation
+      redirectUri: window.location.origin + "/api/auth/github/callback",
+    },
+  },
+];
+```
+
+The frontend will redirect to the backend endpoint, which then redirects to the
+OAuth provider. After successful authentication, the backend should redirect
+back to your app, and the frontend will sync with the backend session.
+
+### Frontend-Handled OAuth Flow
+
+If your frontend initiates OAuth and backend only handles the callback:
+
+```tsx
+const authProviders: AuthProviderConfig[] = [
+  {
+    provider: "github",
+    enabled: true,
+    config: {
+      clientId: "your-github-client-id",
+      redirectUri: "http://localhost:5173/auth/callback",
+      apiBaseUrl: "", // Backend API base URL
+    },
+  },
+];
+```
+
+## Individual Provider Documentation
+
+- [Google Auth](./google/README.md) - Google OAuth setup and usage
+- [GitHub Auth](./github/README.md) - GitHub OAuth setup and usage
+
+## Type Safety
+
+All components and hooks are fully typed with TypeScript:
+
+```typescript
+import type {
+  AuthProviderConfig,
+  AuthSelectorProps,
+  AuthUser,
+  MultiAuthContextType,
+  MultiAuthProviderProps,
+} from "@shared/components/ux/auth";
+```
+
+## Examples
+
+### Complete Example: Todo App with GitHub Auth
+
+```tsx
+import {
+  AuthSelector,
+  MultiAuthProvider,
+  useAuth,
+} from "@shared/components/ux/auth";
+
+function App() {
+  const authProviders: AuthProviderConfig[] = [
+    {
+      provider: "github",
+      enabled: true,
+      config: {
+        backendInitEndpoint: "/api/auth/github",
+        redirectUri: window.location.origin + "/api/auth/github/callback",
+      },
+    },
+    { provider: "google", enabled: false },
+  ];
+
+  return (
+    <MultiAuthProvider providers={authProviders}>
+      <TodoApp />
+    </MultiAuthProvider>
+  );
+}
+
+function ProfilePage() {
+  const { user, signOut } = useAuth();
+
+  return (
+    <div>
+      {user
+        ? (
+          <div>
+            <p>Signed in as {user.login || user.email}</p>
+            <button onClick={signOut}>Sign Out</button>
+          </div>
+        )
+        : <AuthSelector enableGithub={true} enableGoogle={false} />}
+    </div>
+  );
+}
+```

package/components/ux/auth/context.ts

@@ -0,0 +1,46 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+import React, { createContext } from "react";
+import type { GoogleAuthConfig } from "./google/config.ts";
+import type { GitHubAuthConfig } from "./github/config.ts";
+
+/**
+ * Generic user type that applications can extend
+ */
+export interface AuthUser {
+  [key: string]: unknown;
+  provider?: "google" | "github";
+}
+
+export interface MultiAuthContextType {
+  user: AuthUser | null;
+  loading: boolean;
+  provider: "google" | "github" | null;
+  signInWithGoogle: () => void;
+  signInWithGitHub: () => void;
+  signOut: () => void;
+  updateUser: (user: AuthUser | null) => void;
+}
+
+export const MultiAuthContext = createContext<MultiAuthContextType | null>(
+  null
+);
+
+export interface AuthProviderConfig {
+  provider: "google" | "github";
+  enabled: boolean;
+  config?: GoogleAuthConfig | GitHubAuthConfig;
+}
+
+export interface MultiAuthProviderProps {
+  children: React.ReactNode;
+  /** Configuration for which providers are enabled */
+  providers: AuthProviderConfig[];
+  /** Storage key for user data in localStorage (default: "user") */
+  storageKey?: string;
+  /** Backend API base URL (default: auto-detect from window.location) */
+  apiBaseUrl?: string;
+  /** Callback when user is updated */
+  onUserUpdate?: (user: AuthUser | null) => void;
+}