@chesapeake/stack 0.1.0

package/components/ux/auth/github/context.ts

@@ -0,0 +1,34 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+import React, { createContext } from "react";
+import type { GitHubAuthConfig } from "./config.ts";
+
+/**
+ * Generic user type that applications can extend
+ */
+export type AuthUser = Record<string, unknown>;
+
+export interface GitHubAuthContextType {
+  user: AuthUser | null;
+  loading: boolean;
+  signInWithGitHub: () => void;
+  signOut: () => void;
+  updateUser: (user: AuthUser | null) => void;
+}
+
+export const GitHubAuthContext = createContext<GitHubAuthContextType | null>(
+  null
+);
+
+export interface GitHubAuthProviderProps {
+  children: React.ReactNode;
+  /** Backend API base URL (default: auto-detect from window.location) */
+  apiBaseUrl?: string;
+  /** Storage key for user data in localStorage (default: "user") */
+  storageKey?: string;
+  /** Callback when user is updated */
+  onUserUpdate?: (user: AuthUser | null) => void;
+  /** Custom GitHub Auth configuration (if not provided, uses default-client) */
+  config?: GitHubAuthConfig;
+}

package/components/ux/auth/github/default-client.ts

@@ -0,0 +1,74 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+import { createGitHubAuthConfig } from "./config.ts";
+import { GitHubAuthClient } from "./client.ts";
+import type { GitHubOAuthProfile } from "./types.ts";
+
+/**
+ * Default GitHub OAuth client (convention-over-configuration)
+ * Uses sensible defaults and environment variables for easy setup
+ */
+
+let defaultClient: GitHubAuthClient | null = null;
+
+/**
+ * Gets or creates the default GitHub Auth client
+ */
+function getDefaultClient(): GitHubAuthClient {
+  if (!defaultClient) {
+    const config = createGitHubAuthConfig();
+    defaultClient = new GitHubAuthClient(config);
+  }
+  return defaultClient;
+}
+
+/**
+ * Initiates GitHub OAuth login with default configuration
+ * Reads from VITE_GITHUB_CLIENT_ID and VITE_REDIRECT_URI environment variables
+ */
+export function initiateGitHubLogin(): void {
+  getDefaultClient().initiateLogin();
+}
+
+/**
+ * Handles OAuth callback with default configuration
+ * Calls POST /api/auth/github/callback by default
+ * @param code Authorization code from GitHub OAuth callback
+ * @param state State parameter from GitHub OAuth callback (optional)
+ * @returns User profile from backend
+ */
+export async function handleGitHubCallback(
+  code: string,
+  state?: string
+): Promise<GitHubOAuthProfile> {
+  return await getDefaultClient().handleCallback(code, state);
+}
+
+/**
+ * Default GitHub Auth class for common use cases
+ */
+export class DefaultGitHubAuth {
+  private client: GitHubAuthClient;
+
+  constructor() {
+    this.client = getDefaultClient();
+  }
+
+  /**
+   * Initiates GitHub OAuth login
+   */
+  login(): void {
+    this.client.initiateLogin();
+  }
+
+  /**
+   * Handles OAuth callback
+   */
+  async handleCallback(
+    code: string,
+    state?: string
+  ): Promise<GitHubOAuthProfile> {
+    return await this.client.handleCallback(code, state);
+  }
+}

package/components/ux/auth/github/index.ts

@@ -0,0 +1,43 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+// Types
+export type { GitHubOAuthProfile, GitHubUserProfile } from "./types.ts";
+export { toUserProfile } from "./types.ts";
+
+// Configuration
+export type { GitHubAuthCallbackResponse, GitHubAuthConfig } from "./config.ts";
+export { createGitHubAuthConfig, DEFAULT_SCOPE } from "./config.ts";
+
+// Configurable client (config-over-convention)
+export { GitHubAuthClient, initiateGitHubLogin } from "./client.ts";
+
+// Default client (convention-over-configuration)
+export {
+  DefaultGitHubAuth,
+  handleGitHubCallback,
+  initiateGitHubLogin as defaultInitiateGitHubLogin,
+} from "./default-client.ts";
+
+// Auth Provider
+export {
+  DefaultGitHubAuthProvider,
+  GitHubAuthProvider,
+} from "./AuthProvider.tsx";
+// Hook
+export { useGitHubAuth } from "./useGitHubAuth.ts";
+export type {
+  AuthUser,
+  GitHubAuthContextType,
+  GitHubAuthProviderProps,
+} from "./context.ts";
+
+// Auth Callback
+export {
+  DefaultGitHubAuthCallback,
+  GitHubAuthCallback,
+} from "./AuthCallback.tsx";
+export type {
+  DefaultGitHubAuthCallbackProps,
+  GitHubAuthCallbackProps,
+} from "./AuthCallback.tsx";

package/components/ux/auth/github/types.ts

@@ -0,0 +1,44 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+/**
+ * GitHub OAuth user profile returned from GitHub's user API endpoint
+ */
+export interface GitHubOAuthProfile {
+  id: number; // GitHub user ID
+  login: string; // GitHub username
+  name?: string; // User's display name
+  email?: string; // User's email
+  avatar_url: string; // User's avatar URL
+}
+
+/**
+ * User profile structure that can be used by applications
+ * This is the format returned from the backend after OAuth callback
+ */
+export interface GitHubUserProfile {
+  id: string;
+  displayName: string;
+  email?: string;
+  profilePicture?: string;
+  githubOAuthId: number;
+  githubUsername: string;
+  createdAt: Date;
+  updatedAt: Date;
+}
+
+/**
+ * Converts GitHub OAuth profile to application user profile format
+ */
+export function toUserProfile(profile: GitHubOAuthProfile): GitHubUserProfile {
+  return {
+    id: profile.id.toString(),
+    displayName: profile.name ?? profile.login,
+    email: profile.email,
+    profilePicture: profile.avatar_url,
+    githubOAuthId: profile.id,
+    githubUsername: profile.login,
+    createdAt: new Date(),
+    updatedAt: new Date(),
+  };
+}

package/components/ux/auth/github/useGitHubAuth.ts

@@ -0,0 +1,16 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+import { useContext } from "react";
+import { GitHubAuthContext, type GitHubAuthContextType } from "./context.ts";
+
+/**
+ * Hook to access GitHub Auth context
+ */
+export function useGitHubAuth(): GitHubAuthContextType {
+  const context = useContext(GitHubAuthContext);
+  if (!context) {
+    throw new Error("useGitHubAuth must be used within a GitHubAuthProvider");
+  }
+  return context;
+}

package/components/ux/auth/google/AuthCallback.tsx

@@ -0,0 +1,170 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+/** @jsxImportSource react */
+import { useEffect, useRef } from "react";
+import type { GoogleOAuthProfile } from "./types.ts";
+import { GoogleAuthClient } from "./client.ts";
+import { handleGoogleCallback as defaultHandleCallback } from "./default-client.ts";
+import type { GoogleAuthConfig } from "./config.ts";
+
+export interface GoogleAuthCallbackProps {
+  /** Authorization code from URL query params */
+  code: string;
+  /** Backend API base URL (default: auto-detect) */
+  apiBaseUrl?: string;
+  /** Callback when user profile is successfully retrieved */
+  onSuccess: (profile: GoogleOAuthProfile) => void | Promise<void>;
+  /** Callback when an error occurs */
+  onError: (error: Error) => void;
+  /** Custom Google Auth configuration (if not provided, uses default-client) */
+  config?: GoogleAuthConfig;
+}
+
+/**
+ * Configurable Google Auth Callback component
+ * Handles OAuth callback and calls appropriate callbacks
+ */
+export function GoogleAuthCallback({
+  code,
+  apiBaseUrl,
+  onSuccess,
+  onError,
+  config,
+}: GoogleAuthCallbackProps) {
+  const processedRef = useRef(false);
+
+  useEffect(() => {
+    if (processedRef.current) return;
+    processedRef.current = true;
+
+    const handleCallback = async () => {
+      try {
+        let profile: GoogleOAuthProfile;
+        if (config) {
+          const client = new GoogleAuthClient(config);
+          profile = await client.handleCallback(code);
+        } else {
+          profile = await defaultHandleCallback(code);
+        }
+        await onSuccess(profile);
+      } catch (error) {
+        onError(error instanceof Error ? error : new Error(String(error)));
+      }
+    };
+
+    void handleCallback();
+  }, [code, apiBaseUrl, onSuccess, onError, config]);
+
+  return (
+    <div className="flex items-center justify-center min-h-screen bg-background">
+      <div className="text-center">
+        <h1 className="text-2xl font-bold mb-4">Completing sign in...</h1>
+        <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-primary mx-auto"></div>
+      </div>
+    </div>
+  );
+}
+
+export interface DefaultGoogleAuthCallbackProps {
+  /** Authorization code from URL query params */
+  code: string;
+  /** Callback when existing user is found */
+  onUserFound: (profile: GoogleOAuthProfile) => void | Promise<void>;
+  /** Callback when new user (not found in system) */
+  onUserNotFound: (profile: GoogleOAuthProfile) => void | Promise<void>;
+  /** Callback when an error occurs */
+  onError: (error: Error) => void;
+  /** Backend API endpoint for user lookup (default: /api/users) */
+  userLookupEndpoint?: string;
+  /** Redirect path after successful login (default: /home) */
+  redirectPath?: string;
+  /** Redirect path for new users (default: /create-user) */
+  newUserRedirectPath?: string;
+}
+
+/**
+ * Default Google Auth Callback component with convention-over-configuration
+ * Handles common flow: callback -> lookup user -> redirect
+ */
+export function DefaultGoogleAuthCallback({
+  code,
+  onUserFound,
+  onUserNotFound,
+  onError,
+  userLookupEndpoint,
+  redirectPath,
+  newUserRedirectPath,
+}: DefaultGoogleAuthCallbackProps) {
+  const processedRef = useRef(false);
+
+  useEffect(() => {
+    if (processedRef.current) return;
+    processedRef.current = true;
+
+    const handleCallback = async () => {
+      try {
+        // Get user profile from backend
+        const profile = await defaultHandleCallback(code);
+
+        // Look up existing user
+        try {
+          const response = await fetch(userLookupEndpoint ?? "");
+          if (response.ok) {
+            const userResponse = (await response.json()) as {
+              value?: { googleOAuthId?: string }[];
+            };
+            const users = userResponse.value ?? [];
+            const existingUser = users.find(
+              (u: { googleOAuthId?: string }) => u.googleOAuthId === profile.sub
+            );
+
+            if (existingUser) {
+              await onUserFound(profile);
+              // Store redirect path if using localStorage
+              const storedRedirect =
+                localStorage.getItem("redirectAfterLogin") ?? redirectPath;
+              if (storedRedirect) {
+                // Redirect logic would go here
+              }
+              localStorage.removeItem("redirectAfterLogin");
+              // Note: Actual navigation should be handled by the app's router
+              return;
+            }
+          }
+        } catch (lookupError) {
+          console.warn(
+            "User lookup failed, treating as new user:",
+            lookupError
+          );
+        }
+
+        // New user flow
+        localStorage.setItem("oauth_profile", JSON.stringify(profile));
+        await onUserNotFound(profile);
+        // Note: Actual navigation should be handled by the app's router
+      } catch (error) {
+        onError(error instanceof Error ? error : new Error(String(error)));
+      }
+    };
+
+    void handleCallback();
+  }, [
+    code,
+    onUserFound,
+    onUserNotFound,
+    onError,
+    userLookupEndpoint,
+    redirectPath,
+    newUserRedirectPath,
+  ]);
+
+  return (
+    <div className="flex items-center justify-center min-h-screen bg-background">
+      <div className="text-center">
+        <h1 className="text-2xl font-bold mb-4">Completing sign in...</h1>
+        <div className="animate-spin rounded-full h-12 w-12 border-b-2 border-primary mx-auto"></div>
+      </div>
+    </div>
+  );
+}

package/components/ux/auth/google/AuthProvider.tsx

@@ -0,0 +1,108 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+/** @jsxImportSource react */
+import React, { useCallback, useEffect, useState } from "react";
+import { GoogleAuthClient } from "./client.ts";
+import { initiateGoogleLogin as defaultInitiateLogin } from "./default-client.ts";
+
+import {
+  type AuthUser,
+  GoogleAuthContext,
+  type GoogleAuthProviderProps,
+} from "./context.ts";
+
+/**
+ * Generic Google Auth Provider component
+ * Manages user state and provides auth context to children
+ */
+export function GoogleAuthProvider({
+  children,
+  storageKey,
+  onUserUpdate,
+  config,
+}: GoogleAuthProviderProps) {
+  const [user, setUser] = useState<AuthUser | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    // Initial load from localStorage
+    const storedUser = localStorage.getItem(storageKey ?? "user");
+    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);
+        } else {
+          // Invalid user data, clear it
+          localStorage.removeItem(storageKey ?? "user");
+        }
+      } catch (error) {
+        console.error("Error parsing stored user:", error);
+        localStorage.removeItem(storageKey ?? "user");
+      }
+    }
+    setLoading(false);
+  }, [storageKey]);
+
+  const updateUser = useCallback(
+    (newUser: AuthUser | null) => {
+      setUser(newUser);
+      if (newUser) {
+        localStorage.setItem(storageKey ?? "user", JSON.stringify(newUser));
+      } else {
+        localStorage.removeItem(storageKey ?? "user");
+      }
+      onUserUpdate?.(newUser);
+    },
+    [storageKey, onUserUpdate]
+  );
+
+  const signInWithGoogle = useCallback(() => {
+    if (config) {
+      const client = new GoogleAuthClient(config);
+      client.initiateLogin();
+    } else {
+      defaultInitiateLogin();
+    }
+  }, [config]);
+
+  const signOut = useCallback(() => {
+    setLoading(true);
+    localStorage.removeItem(storageKey ?? "user");
+    setUser(null);
+    onUserUpdate?.(null);
+    setLoading(false);
+  }, [storageKey, onUserUpdate]);
+
+  return (
+    <GoogleAuthContext.Provider
+      value={{ user, loading, signInWithGoogle, signOut, updateUser }}
+    >
+      {children}
+    </GoogleAuthContext.Provider>
+  );
+}
+
+/**
+ * Default Google Auth Provider with convention-over-configuration
+ * Uses sensible defaults: /api/auth/google/callback, storage key "user"
+ */
+export function DefaultGoogleAuthProvider({
+  children,
+  onUserUpdate,
+}: {
+  children: React.ReactNode;
+  onUserUpdate?: (user: AuthUser | null) => void;
+}) {
+  return (
+    <GoogleAuthProvider storageKey="user" onUserUpdate={onUserUpdate}>
+      {children}
+    </GoogleAuthProvider>
+  );
+}