@chesapeake/stack 0.1.0

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

@@ -0,0 +1,450 @@
+# Google OAuth Authentication
+
+This package provides frontend components and utilities for Google 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
+
+## Installation
+
+This package is part of `@chesapeake/stack`. Import from:
+
+```typescript
+import { ... } from "@shared/components/ux/auth/google";
+```
+
+## 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_GOOGLE_CLIENT_ID=your_google_client_id_here
+VITE_REDIRECT_URI=http://localhost:5173/auth/callback
+```
+
+### 2. Setup Auth Provider
+
+```tsx
+import {
+  DefaultGoogleAuthProvider,
+  useGoogleAuth,
+} from "@shared/components/ux/auth/google";
+import { defaultInitiateGoogleLogin } from "@shared/components/ux/auth/google";
+
+function App() {
+  return (
+    <DefaultGoogleAuthProvider>
+      <YourApp />
+    </DefaultGoogleAuthProvider>
+  );
+}
+
+function LoginButton() {
+  const { signInWithGoogle } = useGoogleAuth();
+
+  return <button onClick={signInWithGoogle}>Sign in with Google</button>;
+}
+```
+
+### 3. Handle OAuth Callback
+
+```tsx
+import { DefaultGoogleAuthCallback } from "@shared/components/ux/auth/google";
+import { useNavigate, useSearchParams } from "react-router-dom";
+import { useGoogleAuth } from "@shared/components/ux/auth/google";
+
+function AuthCallbackPage() {
+  const navigate = useNavigate();
+  const [searchParams] = useSearchParams();
+  const { updateUser } = useGoogleAuth();
+  const code = searchParams.get("code");
+
+  if (!code) {
+    return <div>No authorization code received</div>;
+  }
+
+  return (
+    <DefaultGoogleAuthCallback
+      code={code}
+      onUserFound={async (profile) => {
+        // User exists in your system
+        // Update user state
+        updateUser(profile);
+        navigate("/home");
+      }}
+      onUserNotFound={async (profile) => {
+        // New user - redirect to create account page
+        navigate("/create-user");
+      }}
+      onError={(error) => {
+        console.error("Auth error:", error);
+        navigate("/login");
+      }}
+    />
+  );
+}
+```
+
+### 4. Backend Implementation
+
+You need to implement a backend endpoint `POST /api/auth/google/callback` that:
+
+1. Receives `{ code: string }` in the request body
+2. Exchanges the code for tokens using Google's OAuth API (server-side)
+3. Fetches user info from Google
+4. Returns `{ user: GoogleOAuthProfile }`
+
+See "Backend Implementation" section below for a complete Deno example.
+
+## Advanced Usage (Config-over-Convention)
+
+For full control over the OAuth flow:
+
+```tsx
+import {
+  GoogleAuthClient,
+  GoogleAuthProvider,
+} from "@shared/components/ux/auth/google";
+import type { GoogleAuthConfig } from "@shared/components/ux/auth/google";
+
+const config: GoogleAuthConfig = {
+  clientId: "your-client-id",
+  redirectUri: "https://yourapp.com/auth/callback",
+  apiBaseUrl: "https://api.yourapp.com",
+  scope: "openid email profile",
+  storageKey: "myAppUser",
+};
+
+function App() {
+  return (
+    <GoogleAuthProvider config={config}>
+      <YourApp />
+    </GoogleAuthProvider>
+  );
+}
+```
+
+## API Reference
+
+### Types
+
+#### `GoogleOAuthProfile`
+
+User profile returned from Google's userinfo endpoint:
+
+```typescript
+interface GoogleOAuthProfile {
+  sub: string; // Google user ID
+  name: string;
+  email: string;
+  picture?: string;
+  email_verified?: boolean;
+}
+```
+
+#### `GoogleAuthConfig`
+
+Configuration for OAuth client:
+
+```typescript
+interface GoogleAuthConfig {
+  clientId: string;
+  redirectUri: string;
+  apiBaseUrl?: string;
+  scope?: string;
+  storageKey?: string;
+}
+```
+
+### Default Client Functions
+
+#### `initiateGoogleLogin()`
+
+Initiates OAuth flow with default configuration. Reads from
+`VITE_GOOGLE_CLIENT_ID` and `VITE_REDIRECT_URI`.
+
+#### `handleGoogleCallback(code: string): Promise<GoogleOAuthProfile>`
+
+Handles OAuth callback by calling backend endpoint. Calls
+`POST /api/auth/google/callback` by default.
+
+### Components
+
+#### `DefaultGoogleAuthProvider`
+
+Auth provider with sensible defaults:
+
+- Storage key: `"user"`
+- API endpoint: `/api/auth/google/callback` (auto-detected)
+
+#### `GoogleAuthProvider`
+
+Configurable auth provider with full control over all parameters.
+
+#### `useGoogleAuth()`
+
+Hook to access auth context:
+
+```typescript
+const { user, loading, signInWithGoogle, signOut, updateUser } =
+  useGoogleAuth();
+```
+
+#### `DefaultGoogleAuthCallback`
+
+Callback component with sensible defaults for common flow.
+
+#### `GoogleAuthCallback`
+
+Configurable callback component for custom flows.
+
+## Backend Implementation
+
+### API Contract
+
+**Endpoint:** `POST /api/auth/google/callback`
+
+**Request:**
+
+```json
+{
+  "code": "authorization_code_from_google"
+}
+```
+
+**Response:**
+
+```json
+{
+  "user": {
+    "sub": "google_user_id",
+    "name": "User Name",
+    "email": "user@example.com",
+    "picture": "https://...",
+    "email_verified": true
+  }
+}
+```
+
+### Minimal Deno Implementation
+
+Here's a complete example for Deno:
+
+```typescript
+/// <reference lib="deno.unstable" />
+
+interface GoogleTokenResponse {
+  access_token: string;
+  token_type: string;
+  expires_in: number;
+  refresh_token?: string;
+  id_token?: string;
+}
+
+interface GoogleUserInfo {
+  sub: string;
+  name: string;
+  email: string;
+  picture?: string;
+  email_verified?: boolean;
+}
+
+/**
+ * Handles Google OAuth callback
+ * POST /api/auth/google/callback
+ */
+export async function googleAuthHandler(req: Request): Promise<Response> {
+  if (req.method !== "POST") {
+    return new Response("Method not allowed", { status: 405 });
+  }
+
+  try {
+    // Parse request body
+    const { code } = await req.json();
+    if (!code) {
+      return new Response(
+        JSON.stringify({ error: "Authorization code is required" }),
+        { status: 400, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    // Get environment variables
+    const clientId = Deno.env.get("GOOGLE_CLIENT_ID");
+    const clientSecret = Deno.env.get("GOOGLE_CLIENT_SECRET");
+    const redirectUri = Deno.env.get("GOOGLE_REDIRECT_URI") ||
+      "http://localhost:5173/auth/callback";
+
+    if (!clientId || !clientSecret) {
+      return new Response(
+        JSON.stringify({ error: "OAuth configuration missing" }),
+        { status: 500, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    // Exchange authorization code for tokens
+    const tokenResponse = await fetch("https://oauth2.googleapis.com/token", {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/x-www-form-urlencoded",
+      },
+      body: new URLSearchParams({
+        code,
+        client_id: clientId,
+        client_secret: clientSecret,
+        redirect_uri: redirectUri,
+        grant_type: "authorization_code",
+      }),
+    });
+
+    if (!tokenResponse.ok) {
+      const error = await tokenResponse.json();
+      return new Response(
+        JSON.stringify({
+          error: error.error_description ||
+            error.error ||
+            "Failed to exchange code for token",
+        }),
+        { status: 400, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    const tokens: GoogleTokenResponse = await tokenResponse.json();
+
+    if (!tokens.access_token) {
+      return new Response(
+        JSON.stringify({ error: "No access token received" }),
+        { status: 400, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    // Fetch user info from Google
+    const userResponse = await fetch(
+      "https://www.googleapis.com/oauth2/v3/userinfo",
+      {
+        headers: {
+          Authorization: `Bearer ${tokens.access_token}`,
+        },
+      },
+    );
+
+    if (!userResponse.ok) {
+      const error = await userResponse.json();
+      return new Response(
+        JSON.stringify({
+          error: error.error_description ||
+            error.error ||
+            "Failed to fetch user info",
+        }),
+        { status: 400, headers: { "Content-Type": "application/json" } },
+      );
+    }
+
+    const userInfo: GoogleUserInfo = await userResponse.json();
+
+    // Return user profile
+    return new Response(JSON.stringify({ user: userInfo }), {
+      status: 200,
+      headers: { "Content-Type": "application/json" },
+    });
+  } catch (error) {
+    console.error("OAuth error:", error);
+    return new Response(
+      JSON.stringify({
+        error: error instanceof Error ? error.message : "Internal server error",
+      }),
+      { status: 500, headers: { "Content-Type": "application/json" } },
+    );
+  }
+}
+```
+
+### Adding to Your Server
+
+In your Deno server routing:
+
+```typescript
+// In your main server file (e.g., serve_deno_deploy.ts)
+import { googleAuthHandler } from "./auth.ts";
+
+async function routeRequest(
+  req: Request,
+  kv: Deno.Kv,
+  config: ServerConfig,
+): Promise<Response> {
+  const url = new URL(req.url);
+
+  // Handle Google OAuth callback
+  if (url.pathname === "/api/auth/google/callback") {
+    return googleAuthHandler(req);
+  }
+
+  // ... other routes
+}
+```
+
+### Environment Variables
+
+Add to your server environment:
+
+```env
+GOOGLE_CLIENT_ID=your_google_client_id
+GOOGLE_CLIENT_SECRET=your_google_client_secret
+GOOGLE_REDIRECT_URI=http://localhost:5173/auth/callback
+```
+
+## Security Notes
+
+1. **Never expose client secret in frontend code** - Always exchange tokens
+   server-side
+2. **Use HTTPS in production** - OAuth requires secure connections
+3. **Validate redirect URIs** - Ensure redirect URIs match your Google OAuth app
+   configuration
+4. **Store tokens securely** - If storing refresh tokens, use secure server-side
+   storage
+
+## Google OAuth Setup
+
+1. Go to [Google Cloud Console](https://console.cloud.google.com/)
+2. Create a new project or select existing
+3. Enable Google+ API
+4. Go to "Credentials" → "Create Credentials" → "OAuth 2.0 Client ID"
+5. Configure:
+   - Application type: Web application
+   - Authorized redirect URIs: `http://localhost:5173/auth/callback` (dev) and
+     your production URL
+6. Copy Client ID and Client Secret
+
+## Troubleshooting
+
+### "Failed to exchange code for token"
+
+- Check that `GOOGLE_CLIENT_SECRET` is set correctly on the server
+- Verify redirect URI matches exactly (including trailing slashes)
+- Ensure the authorization code hasn't expired (codes expire quickly)
+
+### "No authorization code received"
+
+- Check that the callback URL is configured correctly in Google Cloud Console
+- Verify the redirect URI in your frontend matches the one in Google Cloud
+  Console
+
+### CORS errors
+
+- Ensure your backend allows requests from your frontend origin
+- Check that the API endpoint is correctly configured
+
+## Examples
+
+A demo that uses this package is available in this repo: run `npm run dev` from
+the stack package root and see the component showcase.

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

@@ -0,0 +1,109 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+import type { GoogleAuthCallbackResponse, GoogleAuthConfig } from "./config.ts";
+import type { GoogleOAuthProfile } from "./types.ts";
+
+/**
+ * Configurable Google OAuth client (config-over-convention)
+ * Provides full control over all OAuth parameters
+ */
+export class GoogleAuthClient {
+  private config: GoogleAuthConfig;
+
+  constructor(config: GoogleAuthConfig) {
+    // Validate config
+    if (!config.backendInitEndpoint && !config.clientId) {
+      throw new Error(
+        "Either clientId or backendInitEndpoint must be provided"
+      );
+    }
+    this.config = config;
+  }
+
+  /**
+   * Initiates Google OAuth login flow by redirecting to Google 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 Google
+    if (!this.config.clientId) {
+      throw new Error(
+        "clientId is required when backendInitEndpoint is not provided"
+      );
+    }
+
+    const params = new URLSearchParams({
+      client_id: this.config.clientId,
+      redirect_uri: this.config.redirectUri,
+      response_type: "code",
+      scope: this.config.scope ?? "openid email profile",
+      access_type: "offline",
+      prompt: "consent",
+    });
+
+    globalThis.location.href = `https://accounts.google.com/o/oauth2/v2/auth?${params.toString()}`;
+  }
+
+  /**
+   * Handles OAuth callback by exchanging code for user profile via backend
+   * @param code Authorization code from Google OAuth callback
+   * @returns User profile from backend
+   */
+  async handleCallback(code: string): Promise<GoogleOAuthProfile> {
+    const apiBaseUrl = this.config.apiBaseUrl ?? "";
+    const endpoint = `${apiBaseUrl}/api/auth/google/callback`;
+
+    const response = await fetch(endpoint, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json",
+      },
+      body: JSON.stringify({ code }),
+    });
+
+    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 GoogleAuthCallbackResponse;
+    return data.user;
+  }
+
+  /**
+   * Updates the configuration
+   */
+  updateConfig(config: Partial<GoogleAuthConfig>): void {
+    this.config = { ...this.config, ...config };
+  }
+
+  /**
+   * Gets the current configuration
+   */
+  getConfig(): GoogleAuthConfig {
+    return { ...this.config };
+  }
+}
+
+/**
+ * Standalone function to initiate Google OAuth login with configuration
+ */
+export function initiateGoogleLogin(config: GoogleAuthConfig): void {
+  const client = new GoogleAuthClient(config);
+  client.initiateLogin();
+}

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

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

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

@@ -0,0 +1,34 @@
+// Copyright 2026 Chesapeake Computing
+// SPDX-License-Identifier: Apache-2.0
+
+import React, { createContext } from "react";
+import type { GoogleAuthConfig } from "./config.ts";
+
+/**
+ * Generic user type that applications can extend
+ */
+export type AuthUser = Record<string, unknown>;
+
+export interface GoogleAuthContextType {
+  user: AuthUser | null;
+  loading: boolean;
+  signInWithGoogle: () => void;
+  signOut: () => void;
+  updateUser: (user: AuthUser | null) => void;
+}
+
+export const GoogleAuthContext = createContext<GoogleAuthContextType | null>(
+  null
+);
+
+export interface GoogleAuthProviderProps {
+  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 Google Auth configuration (if not provided, uses default-client) */
+  config?: GoogleAuthConfig;
+}