@chesapeake/stack 0.1.0

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

@@ -0,0 +1,177 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+/** @jsxImportSource react */
+import { useEffect, useRef } from "react";
+import type { GitHubOAuthProfile } from "./types.ts";
+import { GitHubAuthClient } from "./client.ts";
+import { handleGitHubCallback as defaultHandleCallback } from "./default-client.ts";
+import type { GitHubAuthConfig } from "./config.ts";
+
+export interface GitHubAuthCallbackProps {
+  /** Authorization code from URL query params */
+  code: string;
+  /** State parameter from URL query params (optional) */
+  state?: string;
+  /** Backend API base URL (default: auto-detect) */
+  apiBaseUrl?: string;
+  /** Callback when user profile is successfully retrieved */
+  onSuccess: (profile: GitHubOAuthProfile) => void | Promise<void>;
+  /** Callback when an error occurs */
+  onError: (error: Error) => void;
+  /** Custom GitHub Auth configuration (if not provided, uses default-client) */
+  config?: GitHubAuthConfig;
+}
+
+/**
+ * Configurable GitHub Auth Callback component
+ * Handles OAuth callback and calls appropriate callbacks
+ */
+export function GitHubAuthCallback({
+  code,
+  state,
+  apiBaseUrl,
+  onSuccess,
+  onError,
+  config,
+}: GitHubAuthCallbackProps) {
+  const processedRef = useRef(false);
+
+  useEffect(() => {
+    if (processedRef.current) return;
+    processedRef.current = true;
+
+    const handleCallback = async () => {
+      try {
+        let profile: GitHubOAuthProfile;
+        if (config) {
+          const client = new GitHubAuthClient(config);
+          profile = await client.handleCallback(code, state);
+        } else {
+          profile = await defaultHandleCallback(code, state);
+        }
+        await onSuccess(profile);
+      } catch (error) {
+        onError(error instanceof Error ? error : new Error(String(error)));
+      }
+    };
+
+    void handleCallback();
+  }, [code, state, 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 DefaultGitHubAuthCallbackProps {
+  /** Authorization code from URL query params */
+  code: string;
+  /** State parameter from URL query params (optional) */
+  state?: string;
+  /** Callback when existing user is found */
+  onUserFound: (profile: GitHubOAuthProfile) => void | Promise<void>;
+  /** Callback when new user (not found in system) */
+  onUserNotFound: (profile: GitHubOAuthProfile) => 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 GitHub Auth Callback component with convention-over-configuration
+ * Handles common flow: callback -> lookup user -> redirect
+ */
+export function DefaultGitHubAuthCallback({
+  code,
+  state,
+  onUserFound,
+  onUserNotFound,
+  onError,
+  userLookupEndpoint,
+  redirectPath,
+  newUserRedirectPath,
+}: DefaultGitHubAuthCallbackProps) {
+  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, state);
+
+        // Look up existing user
+        try {
+          const response = await fetch(userLookupEndpoint ?? "");
+          if (response.ok) {
+            const userResponse = (await response.json()) as {
+              value?: { githubOAuthId?: number }[];
+            };
+            const users = userResponse.value ?? [];
+            const existingUser = users.find(
+              (u: { githubOAuthId?: number }) => u.githubOAuthId === profile.id
+            );
+
+            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,
+    state,
+    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/github/AuthProvider.tsx

@@ -0,0 +1,111 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+/** @jsxImportSource react */
+import React, { useCallback, useEffect, useState } from "react";
+import { GitHubAuthClient } from "./client.ts";
+import { initiateGitHubLogin as defaultInitiateLogin } from "./default-client.ts";
+
+import {
+  type AuthUser,
+  GitHubAuthContext,
+  type GitHubAuthProviderProps,
+} from "./context.ts";
+
+/**
+ * Generic GitHub Auth Provider component
+ * Manages user state and provides auth context to children
+ */
+export function GitHubAuthProvider({
+  children,
+  storageKey,
+  onUserUpdate,
+  config,
+}: GitHubAuthProviderProps) {
+  const [user, setUser] = useState<AuthUser | null>(null);
+  const [loading, setLoading] = useState(true);
+
+  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);
+        } 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) => {
+      setUser(newUser);
+      const key = storageKey ?? "user";
+      if (newUser) {
+        localStorage.setItem(key, JSON.stringify(newUser));
+      } else {
+        localStorage.removeItem(key);
+      }
+      onUserUpdate?.(newUser);
+    },
+    [storageKey, onUserUpdate]
+  );
+
+  const signInWithGitHub = useCallback(() => {
+    if (config) {
+      const client = new GitHubAuthClient(config);
+      client.initiateLogin();
+    } else {
+      defaultInitiateLogin();
+    }
+  }, [config]);
+
+  const signOut = useCallback(() => {
+    setLoading(true);
+    const key = storageKey ?? "user";
+    localStorage.removeItem(key);
+    setUser(null);
+    onUserUpdate?.(null);
+    setLoading(false);
+  }, [storageKey, onUserUpdate]);
+
+  return (
+    <GitHubAuthContext.Provider
+      value={{ user, loading, signInWithGitHub, signOut, updateUser }}
+    >
+      {children}
+    </GitHubAuthContext.Provider>
+  );
+}
+
+/**
+ * Default GitHub Auth Provider with convention-over-configuration
+ * Uses sensible defaults: /api/auth/github/callback, storage key "user"
+ */
+export function DefaultGitHubAuthProvider({
+  children,
+  onUserUpdate,
+}: {
+  children: React.ReactNode;
+  onUserUpdate?: (user: AuthUser | null) => void;
+}) {
+  return (
+    <GitHubAuthProvider storageKey="user" onUserUpdate={onUserUpdate}>
+      {children}
+    </GitHubAuthProvider>
+  );
+}

package/components/ux/auth/github/README.md

@@ -0,0 +1,208 @@
+# GitHub OAuth Authentication
+
+This package provides frontend components and utilities for GitHub OAuth
+authentication. It supports both **config-over-convention** (full control) and
+**convention-over-configuration** (sensible defaults) approaches.
+
+## Features
+
+- 🔐 Secure OAuth flow (client secret never exposed to frontend)
+- ⚙️ Two API styles: configurable and default
+- 🎨 React components for auth provider and callback handling
+- 📦 TypeScript types for type safety
+- 🔄 Automatic user state management with localStorage
+- 🔧 Support for both frontend-initiated and backend-handled OAuth flows
+
+## Installation
+
+This package is part of the `@chesapeake/shared-components` package. Import
+from:
+
+```typescript
+import { ... } from "@shared/components/ux/auth/github";
+```
+
+## Quick Start (Convention-over-Configuration)
+
+For most use cases, the default client provides sensible defaults:
+
+### 1. Environment Variables
+
+Add to your `.env` file:
+
+```env
+VITE_GITHUB_CLIENT_ID=your_github_client_id_here
+VITE_REDIRECT_URI=http://localhost:5173/auth/callback
+```
+
+Or, if your backend handles OAuth initiation:
+
+```env
+VITE_GITHUB_BACKEND_INIT_ENDPOINT=/api/auth/github
+```
+
+### 2. Setup Auth Provider
+
+```tsx
+import {
+  DefaultGitHubAuthProvider,
+  useGitHubAuth,
+} from "@shared/components/ux/auth/github";
+import { defaultInitiateGitHubLogin } from "@shared/components/ux/auth/github";
+
+function App() {
+  return (
+    <DefaultGitHubAuthProvider>
+      <YourApp />
+    </DefaultGitHubAuthProvider>
+  );
+}
+
+function LoginButton() {
+  const { signInWithGitHub } = useGitHubAuth();
+
+  return <button onClick={signInWithGitHub}>Sign in with GitHub</button>;
+}
+```
+
+## Backend Implementation
+
+### API Contract
+
+**Endpoint:** `POST /api/auth/github/callback`
+
+**Request:**
+
+```json
+{
+  "code": "authorization_code_from_github",
+  "state": "optional_state_parameter"
+}
+```
+
+**Response:**
+
+```json
+{
+  "user": {
+    "id": 12345678,
+    "login": "username",
+    "name": "User Name",
+    "email": "user@example.com",
+    "avatar_url": "https://avatars.githubusercontent.com/u/12345678"
+  }
+}
+```
+
+### Backend-Handled OAuth Flow
+
+If your backend handles the entire OAuth flow (initiation and callback),
+configure the client with `backendInitEndpoint`:
+
+```tsx
+import { GitHubAuthProvider } from "@shared/components/ux/auth/github";
+
+function App() {
+  return (
+    <GitHubAuthProvider
+      config={{
+        clientId: "", // Not needed when using backend endpoint
+        redirectUri: window.location.origin + "/api/auth/github/callback",
+        backendInitEndpoint: "/api/auth/github", // Backend handles OAuth initiation
+      }}
+    >
+      <YourApp />
+    </GitHubAuthProvider>
+  );
+}
+```
+
+### Minimal Deno Implementation
+
+Here's a complete example for Deno:
+
+```typescript
+// Backend OAuth initiation endpoint
+async function handleGitHubAuth(req: Request): Promise<Response> {
+  const GITHUB_CLIENT_ID = Deno.env.get("GITHUB_CLIENT_ID");
+  const GITHUB_REDIRECT_URI = Deno.env.get("GITHUB_REDIRECT_URI");
+
+  const state = crypto.randomUUID();
+  const authUrl = new URL("https://github.com/login/oauth/authorize");
+  authUrl.searchParams.set("client_id", GITHUB_CLIENT_ID!);
+  authUrl.searchParams.set("redirect_uri", GITHUB_REDIRECT_URI);
+  authUrl.searchParams.set("scope", "user:email");
+  authUrl.searchParams.set("state", state);
+
+  // Store state for validation
+  await kv.set(["oauth_state", state], { expiresAt: Date.now() + 600000 });
+
+  return Response.redirect(authUrl.toString());
+}
+
+// Backend OAuth callback endpoint
+async function handleGitHubCallback(req: Request): Promise<Response> {
+  const url = new URL(req.url);
+  const code = url.searchParams.get("code");
+  const state = url.searchParams.get("state");
+
+  // Validate state
+  const stateResult = await kv.get(["oauth_state", state!]);
+  if (!stateResult.value) {
+    return new Response("Invalid state", { status: 400 });
+  }
+  await kv.delete(["oauth_state", state!]);
+
+  // Exchange code for token
+  const tokenResponse = await fetch(
+    "https://github.com/login/oauth/access_token",
+    {
+      method: "POST",
+      headers: {
+        Accept: "application/json",
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: new URLSearchParams({
+        client_id: Deno.env.get("GITHUB_CLIENT_ID")!,
+        client_secret: Deno.env.get("GITHUB_CLIENT_SECRET")!,
+        code: code!,
+        redirect_uri: Deno.env.get("GITHUB_REDIRECT_URI")!,
+      }),
+    },
+  );
+
+  const tokenData = await tokenResponse.json();
+  const accessToken = tokenData.access_token;
+
+  // Get user data
+  const userResponse = await fetch("https://api.github.com/user", {
+    headers: {
+      Authorization: `Bearer ${accessToken}`,
+      Accept: "application/vnd.github.v3+json",
+    },
+  });
+
+  const user = await userResponse.json();
+
+  // Return user profile
+  return new Response(
+    JSON.stringify({
+      user: {
+        id: user.id,
+        login: user.login,
+        name: user.name,
+        email: user.email,
+        avatar_url: user.avatar_url,
+      },
+    }),
+    {
+      headers: { "Content-Type": "application/json" },
+    },
+  );
+}
+```
+
+## Advanced Usage
+
+See the main [auth README](../README.md) for multi-provider setup and advanced
+configuration options.

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

@@ -0,0 +1,127 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+import type { GitHubAuthCallbackResponse, GitHubAuthConfig } from "./config.ts";
+import type { GitHubOAuthProfile } from "./types.ts";
+
+/**
+ * Configurable GitHub OAuth client (config-over-convention)
+ * Provides full control over all OAuth parameters
+ */
+export class GitHubAuthClient {
+  private config: GitHubAuthConfig;
+
+  constructor(config: GitHubAuthConfig) {
+    // Validate config
+    if (!config.backendInitEndpoint && !config.clientId) {
+      throw new Error(
+        "Either clientId or backendInitEndpoint must be provided"
+      );
+    }
+    this.config = config;
+  }
+
+  /**
+   * Initiates GitHub OAuth login flow by redirecting to GitHub or backend endpoint
+   */
+  initiateLogin(): void {
+    // If backend handles OAuth initiation, redirect to backend endpoint
+    if (this.config.backendInitEndpoint) {
+      globalThis.location.href = this.config.backendInitEndpoint;
+      return;
+    }
+
+    // Otherwise, redirect directly to GitHub
+    const params = new URLSearchParams({
+      client_id: this.config.clientId,
+      redirect_uri: this.config.redirectUri,
+      scope: this.config.scope ?? "user:email",
+      state: this.generateState(),
+    });
+
+    // Store state in sessionStorage for validation
+    const state = params.get("state");
+    if (state) {
+      sessionStorage.setItem(`github_oauth_state_${state}`, "pending");
+    }
+
+    globalThis.location.href = `https://github.com/login/oauth/authorize?${params.toString()}`;
+  }
+
+  /**
+   * Generates a secure random state parameter for OAuth
+   */
+  private generateState(): string {
+    return crypto.randomUUID();
+  }
+
+  /**
+   * Handles OAuth callback by exchanging code for user profile via backend
+   * @param code Authorization code from GitHub OAuth callback
+   * @param state State parameter from GitHub OAuth callback (optional, for validation)
+   * @returns User profile from backend
+   */
+  async handleCallback(
+    code: string,
+    state?: string
+  ): Promise<GitHubOAuthProfile> {
+    // Validate state if provided
+    if (state) {
+      const storedState = sessionStorage.getItem(`github_oauth_state_${state}`);
+      if (!storedState) {
+        throw new Error("Invalid state parameter");
+      }
+      sessionStorage.removeItem(`github_oauth_state_${state}`);
+    }
+
+    const apiBaseUrl = this.config.apiBaseUrl ?? "";
+    const endpoint = `${apiBaseUrl}/api/auth/github/callback`;
+
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ code, state }),
+    });
+
+    if (!response.ok) {
+      const error = (await response.json().catch(() => ({
+        error: "Failed to exchange code for token",
+      }))) as {
+        error_description?: string;
+        error?: string;
+      };
+      throw new Error(
+        error.error_description ??
+          error.error ??
+          "Failed to exchange code for token"
+      );
+    }
+
+    const data = (await response.json()) as GitHubAuthCallbackResponse;
+    return data.user;
+  }
+
+  /**
+   * Updates the configuration
+   */
+  updateConfig(config: Partial<GitHubAuthConfig>): void {
+    this.config = { ...this.config, ...config };
+  }
+
+  /**
+   * Gets the current configuration
+   */
+  getConfig(): GitHubAuthConfig {
+    return { ...this.config };
+  }
+}
+
+/**
+ * Standalone function to initiate GitHub OAuth login with configuration
+ */
+export function initiateGitHubLogin(config: GitHubAuthConfig): void {
+  const client = new GitHubAuthClient(config);
+  client.initiateLogin();
+}

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

@@ -0,0 +1,68 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+import type { GitHubOAuthProfile } from "./types.ts";
+
+/**
+ * Configuration for GitHub OAuth client
+ */
+export interface GitHubAuthConfig {
+  /** GitHub OAuth client ID */
+  clientId: string;
+  /** Redirect URI after OAuth authorization */
+  redirectUri: string;
+  /** Backend API base URL (e.g., "https://api.example.com" or "/api") */
+  apiBaseUrl?: string;
+  /** OAuth scopes (default: "user:email") */
+  scope?: string;
+  /** Storage key for user data in localStorage (default: "user") */
+  storageKey?: string;
+  /** Backend endpoint for OAuth initiation (if backend handles OAuth flow) */
+  backendInitEndpoint?: string;
+}
+
+/**
+ * Default OAuth scopes
+ */
+export const DEFAULT_SCOPE = "user:email";
+
+/**
+ * Creates a GitHubAuthConfig from environment variables
+ * Note: This function expects Vite environment variables (import.meta.env)
+ */
+export function createGitHubAuthConfig(): GitHubAuthConfig {
+  // Type assertion for Vite's import.meta.env
+  const env = (import.meta as { env?: Record<string, string | undefined> })
+    .env as {
+    VITE_GITHUB_CLIENT_ID?: string;
+    VITE_REDIRECT_URI?: string;
+    VITE_API_BASE_URL?: string;
+    VITE_GITHUB_BACKEND_INIT_ENDPOINT?: string;
+  };
+
+  const clientId = env.VITE_GITHUB_CLIENT_ID;
+  if (!clientId && !env.VITE_GITHUB_BACKEND_INIT_ENDPOINT) {
+    throw new Error(
+      "VITE_GITHUB_CLIENT_ID or VITE_GITHUB_BACKEND_INIT_ENDPOINT environment variable is required"
+    );
+  }
+
+  const redirectUri =
+    env.VITE_REDIRECT_URI ?? `${globalThis.location.origin}/auth/callback`;
+
+  return {
+    clientId: clientId ?? "",
+    redirectUri,
+    apiBaseUrl: env.VITE_API_BASE_URL,
+    scope: DEFAULT_SCOPE,
+    storageKey: "user",
+    backendInitEndpoint: env.VITE_GITHUB_BACKEND_INIT_ENDPOINT,
+  };
+}
+
+/**
+ * Backend API response from OAuth callback endpoint
+ */
+export interface GitHubAuthCallbackResponse {
+  user: GitHubOAuthProfile;
+}