@prmichaelsen/acp-visualizer 0.1.0 → 0.1.2

package/agent/patterns/tanstack-cloudflare.auth-session-management.md

@@ -1,387 +0,0 @@
-# Auth Session Management Pattern
-
-**Category**: Architecture
-**Applicable To**: TanStack Start + Cloudflare Workers applications with authentication
-**Status**: Stable
-
----
-
-## Overview
-
-This pattern provides cookie-based session management for TanStack Start applications running on Cloudflare Workers. It uses Firebase Admin SDK for token verification, HTTP-only session cookies for security, and a server function (`getAuthSession`) that can be called from any component, route, or API handler to get the current authenticated user.
-
-The pattern enforces server-side-only authentication — all auth checks happen on the server, never on the client. This prevents token exposure and ensures that authentication state is always authoritative.
-
----
-
-## When to Use This Pattern
-
-✅ **Use this pattern when:**
-- Building authenticated TanStack Start applications
-- Need cookie-based session management
-- Using Firebase Authentication as the identity provider
-- Need a universal `getAuthSession()` function callable from any context
-- Want server-side auth enforcement (never client-side token verification)
-
-❌ **Don't use this pattern when:**
-- Building public-only applications with no authentication
-- Using a different auth provider that handles sessions differently (Auth0, Clerk)
-- Building static sites
-
----
-
-## Core Principles
-
-1. **Server-Side Only**: All authentication verification happens on the server — never verify tokens client-side
-2. **Cookie-Based Sessions**: Use HTTP-only cookies to store session tokens (not localStorage)
-3. **Universal Server Function**: `getAuthSession()` is a `createServerFn` callable from any context
-4. **Graceful Fallback**: Auth failures return `null`, never throw — callers decide how to handle
-5. **Session Cookie Exchange**: Exchange short-lived ID tokens for long-lived session cookies (14 days)
-6. **Request-Based Verification**: `getServerSession(request)` extracts and verifies the cookie from the request
-
----
-
-## Implementation
-
-### Structure
-
-```
-src/
-├── lib/
-│   └── auth/
-│       ├── session.ts             # Server-side session verification
-│       └── server-fn.ts           # createServerFn wrapper for components
-├── types/
-│   └── auth.ts                    # User and ServerSession types
-├── components/
-│   └── auth/
-│       ├── AuthContext.tsx         # React context for auth state
-│       └── AuthForm.tsx           # Login/register UI
-└── routes/
-    ├── __root.tsx                 # Root layout with auth initialization
-    ├── auth.tsx                   # Auth page
-    └── api/
-        └── auth/
-            ├── session.tsx        # POST: Create session cookie
-            └── logout.tsx         # POST: Destroy session
-```
-
-### Code Example
-
-#### Step 1: Define Auth Types
-
-```typescript
-// src/types/auth.ts
-export interface User {
-  uid: string
-  email: string | null
-  displayName: string | null
-  photoURL: string | null
-  emailVerified: boolean
-}
-
-export interface ServerSession {
-  user: User
-}
-```
-
-#### Step 2: Server-Side Session Verification
-
-```typescript
-// src/lib/auth/session.ts
-import { verifyIdToken, verifySessionCookie, createSessionCookie as createFirebaseSessionCookie }
-  from '@prmichaelsen/firebase-admin-sdk-v8'
-import type { User, ServerSession } from '@/types/auth'
-
-/**
- * Extract session cookie from request headers
- */
-function getSessionCookie(request: Request): string | undefined {
-  const cookieHeader = request.headers.get('cookie')
-  if (!cookieHeader) return undefined
-
-  const cookies = cookieHeader.split(';').reduce((acc, cookie) => {
-    const [name, value] = cookie.trim().split('=')
-    acc[name] = value
-    return acc
-  }, {} as Record<string, string>)
-
-  return cookies.session
-}
-
-/**
- * Get authenticated user from request
- * Returns null if not authenticated — never throws
- */
-export async function getServerSession(request: Request): Promise<ServerSession | null> {
-  try {
-    const sessionCookie = getSessionCookie(request)
-    if (!sessionCookie) return null
-
-    // Verify session cookie (try session cookie first, fallback to ID token)
-    let decodedToken
-    try {
-      decodedToken = await verifySessionCookie(sessionCookie)
-    } catch {
-      decodedToken = await verifyIdToken(sessionCookie)
-    }
-
-    const user: User = {
-      uid: decodedToken.sub,
-      email: decodedToken.email || null,
-      displayName: decodedToken.name || null,
-      photoURL: decodedToken.picture || null,
-      emailVerified: decodedToken.email_verified || false,
-    }
-
-    return { user }
-  } catch (error) {
-    console.error('Failed to get server session', error)
-    return null
-  }
-}
-
-/**
- * Create a long-lived session cookie from a Firebase ID token
- */
-export async function createSessionCookie(idToken: string): Promise<string> {
-  return createFirebaseSessionCookie(idToken, {
-    expiresIn: 60 * 60 * 24 * 14 * 1000  // 14 days
-  })
-}
-```
-
-#### Step 3: Universal Server Function
-
-```typescript
-// src/lib/auth/server-fn.ts
-import { createServerFn } from '@tanstack/react-start'
-import { getRequest } from '@tanstack/react-start/server'
-import { getServerSession } from '@/lib/auth/session'
-import { initFirebaseAdmin } from '@/lib/firebase-admin'
-
-/**
- * Server function to get current auth session.
- * Callable from any component, route, or server context.
- */
-export const getAuthSession = createServerFn({ method: 'GET' }).handler(async () => {
-  try {
-    initFirebaseAdmin()
-    const session = await getServerSession(getRequest())
-    return session?.user || null
-  } catch (error) {
-    console.error('[getAuthSession] Error:', error)
-    return null
-  }
-})
-```
-
-#### Step 4: Root Layout with Auth Initialization
-
-```typescript
-// src/routes/__root.tsx
-import { createRootRouteWithContext } from '@tanstack/react-router'
-import { getAuthSession } from '@/lib/auth/server-fn'
-import { AuthProvider } from '@/components/auth/AuthContext'
-
-export const Route = createRootRouteWithContext()({
-  beforeLoad: async () => {
-    // Fetch auth session server-side (SSR)
-    const user = await getAuthSession()
-    return { user }
-  },
-  component: RootLayout,
-})
-
-function RootLayout() {
-  const { user } = Route.useRouteContext()
-
-  return (
-    <AuthProvider initialUser={user}>
-      <Outlet />
-    </AuthProvider>
-  )
-}
-```
-
-#### Step 5: Auth Context Provider
-
-```typescript
-// src/components/auth/AuthContext.tsx
-import { createContext, useContext, useState } from 'react'
-import type { User } from '@/types/auth'
-
-interface AuthContextType {
-  user: User | null
-  setUser: (user: User | null) => void
-}
-
-const AuthContext = createContext<AuthContextType | null>(null)
-
-export function AuthProvider({ initialUser, children }: {
-  initialUser: User | null
-  children: React.ReactNode
-}) {
-  const [user, setUser] = useState<User | null>(initialUser)
-
-  return (
-    <AuthContext.Provider value={{ user, setUser }}>
-      {children}
-    </AuthContext.Provider>
-  )
-}
-
-export function useAuth(): AuthContextType {
-  const ctx = useContext(AuthContext)
-  if (!ctx) throw new Error('useAuth must be used within AuthProvider')
-  return ctx
-}
-```
-
-#### Step 6: Protected Route with Redirect
-
-```typescript
-// src/routes/profile.tsx
-import { createFileRoute, redirect } from '@tanstack/react-router'
-import { getAuthSession } from '@/lib/auth/server-fn'
-
-export const Route = createFileRoute('/profile')({
-  beforeLoad: async () => {
-    const user = await getAuthSession()
-
-    if (!user) {
-      throw redirect({
-        to: '/auth',
-        search: { redirect_url: '/profile' },
-      })
-    }
-
-    return { user }
-  },
-  component: ProfilePage,
-})
-```
-
-#### Step 7: Session Creation API Route
-
-```typescript
-// src/routes/api/auth/session.tsx
-import { createFileRoute } from '@tanstack/react-router'
-import { createSessionCookie } from '@/lib/auth/session'
-
-export const Route = createFileRoute('/api/auth/session')({
-  server: {
-    handlers: {
-      POST: async ({ request }) => {
-        try {
-          const { idToken } = await request.json()
-          const sessionCookie = await createSessionCookie(idToken)
-
-          return new Response(JSON.stringify({ success: true }), {
-            status: 200,
-            headers: {
-              'Content-Type': 'application/json',
-              'Set-Cookie': `session=${sessionCookie}; Path=/; HttpOnly; Secure; SameSite=Lax; Max-Age=${60 * 60 * 24 * 14}`,
-            },
-          })
-        } catch (error) {
-          return new Response(JSON.stringify({ error: 'Failed to create session' }), {
-            status: 401,
-            headers: { 'Content-Type': 'application/json' },
-          })
-        }
-      },
-    },
-  },
-})
-```
-
----
-
-## Benefits
-
-### 1. Universal Auth Check
-`getAuthSession()` works in components, `beforeLoad`, API routes, and server functions — one function everywhere.
-
-### 2. Secure by Default
-HTTP-only cookies prevent XSS attacks. Server-side verification prevents token tampering.
-
-### 3. SSR Compatible
-Auth state is available during server-side rendering via `beforeLoad`, enabling instant authenticated content.
-
-### 4. Graceful Degradation
-Auth failures return `null` instead of throwing, preventing cascading errors.
-
----
-
-## Trade-offs
-
-### 1. Firebase Dependency
-**Downside**: Tightly coupled to Firebase Admin SDK for token verification.
-**Mitigation**: Wrap in an interface if you anticipate switching auth providers.
-
-### 2. Cookie Size Limits
-**Downside**: Session cookies have size limits (~4KB).
-**Mitigation**: Store minimal data in the cookie (just the session token), not user profile data.
-
----
-
-## Anti-Patterns
-
-### ❌ Anti-Pattern 1: Client-Side Token Verification
-
-```typescript
-// ❌ BAD: Verifying tokens on the client
-function MyComponent() {
-  const token = localStorage.getItem('token')
-  const user = jwt.decode(token)  // Client-side decode — not verified!
-}
-
-// ✅ GOOD: Always verify on server
-const user = await getAuthSession()
-```
-
-### ❌ Anti-Pattern 2: Throwing on Auth Failure
-
-```typescript
-// ❌ BAD: Throwing prevents page from loading
-export async function getServerSession(request) {
-  const cookie = getSessionCookie(request)
-  if (!cookie) throw new Error('Not authenticated')  // Crashes!
-}
-
-// ✅ GOOD: Return null, let callers decide
-export async function getServerSession(request) {
-  const cookie = getSessionCookie(request)
-  if (!cookie) return null  // Graceful
-}
-```
-
----
-
-## Related Patterns
-
-- **[API Route Handlers](./tanstack-cloudflare.api-route-handlers.md)**: API routes use `getAuthSession()` for auth
-- **[SSR Preload Pattern](./tanstack-cloudflare.ssr-preload.md)**: `beforeLoad` uses auth for user-specific data
-- **[Rate Limiting](./tanstack-cloudflare.rate-limiting.md)**: Rate limit auth endpoints
-
----
-
-## Checklist for Implementation
-
-- [ ] `getServerSession(request)` returns `ServerSession | null`
-- [ ] `getAuthSession` is a `createServerFn` wrapper
-- [ ] Session cookie is HTTP-only, Secure, SameSite=Lax
-- [ ] Root layout fetches auth in `beforeLoad`
-- [ ] AuthProvider wraps app with `initialUser` from SSR
-- [ ] Protected routes use `redirect` to `/auth` when not authenticated
-- [ ] API routes check `getAuthSession()` before processing
-- [ ] Auth failures never throw — always return null
-- [ ] Firebase Admin SDK initialized before verification
-
----
-
-**Status**: Stable - Proven pattern for TanStack Start authentication
-**Recommendation**: Use for all authenticated TanStack Start applications
-**Last Updated**: 2026-02-28
-**Contributors**: Patrick Michaelsen

package/agent/patterns/tanstack-cloudflare.card-and-list.md

@@ -1,271 +0,0 @@
-# Card, NotificationCard & CardList
-
-**Category**: Design
-**Applicable To**: All card-based data display, notification items with swipe-to-dismiss, and generic feed/list rendering
-**Status**: Stable
-
----
-
-## Overview
-
-Cards are the primary data display unit across the app. This pattern covers the standard card styling, NotificationCard with swipe-to-dismiss gesture, and CardList (FeedList) — a generic list component that handles loading skeletons, empty states, and error banners for any card type.
-
----
-
-## Implementation
-
-### Card (Standard Styling)
-
-All cards in the app follow consistent styling:
-
-```typescript
-// Standard card container
-<div className="bg-gray-900/50 backdrop-blur-sm border border-gray-800 rounded-xl p-4">
-  {/* Card content */}
-</div>
-
-// With hover effect
-<div className="bg-gray-900/50 backdrop-blur-sm border border-gray-800 rounded-xl p-4
-                hover:border-blue-500/50 transition-colors cursor-pointer">
-  {/* Clickable card */}
-</div>
-
-// Highlighted/active
-<div className="bg-purple-900/20 border border-purple-400/60 rounded-xl p-4 shadow-purple-500/10">
-  {/* Active card */}
-</div>
-```
-
-**Text Hierarchy**:
-- Title: `text-white font-semibold`
-- Subtitle/secondary: `text-gray-400 text-sm`
-- Meta/timestamp: `text-gray-500 text-xs`
-
-**Action Buttons** (icon buttons within cards):
-- Base: `p-2 text-gray-400 hover:text-white hover:bg-gray-700/50 rounded transition-colors`
-- Danger: `text-red-400 hover:text-red-300`
-- Disabled: `opacity-50 cursor-not-allowed`
-
-**State Variants**:
-- Deleted/faded: `opacity-20 transition-opacity duration-200`
-- Loading: `animate-pulse bg-gray-800`
-
----
-
-### NotificationCard
-
-**File**: `src/components/notifications/NotificationCard.tsx`
-
-```typescript
-interface NotificationCardProps {
-  notification: Notification
-  onMarkAsRead: (id: string) => void
-  onOpenFriendRequest?: (notification: Notification) => void
-}
-```
-
-**Features**:
-- Unread indicator: blue dot (w-2 h-2) on left side
-- Avatar circle (w-10 h-10) or type-specific icon with colored background
-- Content: title (truncated), message (line-clamp-2), relative timestamp
-- Message count badge (top-right, blue pill)
-- **Swipe-to-dismiss**: horizontal swipe >80px threshold
-  - Reveal background: `bg-blue-600/30`
-  - Smooth dismiss animation (300ms translateX)
-  - Calls `onMarkAsRead` on dismiss
-- Type-specific icons: `friend_request`, `friend_accepted`, `group_invite`, `new_message`, `system`, `memory_published`, `memory_comment`, `organize_nudge`
-
----
-
-### CardList (Generic Feed Primitive)
-
-**File**: `src/components/feed/FeedList.tsx`
-
-```typescript
-interface CardListProps<T> {
-  items: T[]
-  loading: boolean
-  error: string | null
-  renderItem: (item: T, index: number) => ReactNode
-  emptyIcon: ReactNode
-  emptyMessage: string
-  skeletonCount?: number  // default: 4
-}
-
-export function FeedList<T>({ items, loading, error, renderItem, emptyIcon, emptyMessage, skeletonCount = 4 }: CardListProps<T>) {
-  // Error state: red banner
-  if (error) return <div className="text-red-400 p-4 ...">{error}</div>
-
-  // Loading state: skeleton cards
-  if (loading) return (
-    <div className="space-y-2">
-      {Array.from({ length: skeletonCount }).map((_, i) => (
-        <div key={i} className="bg-gray-800 rounded-xl h-32 animate-pulse" />
-      ))}
-    </div>
-  )
-
-  // Empty state: centered icon + message
-  if (items.length === 0) return (
-    <div className="flex flex-col items-center justify-center py-12 text-gray-500">
-      {emptyIcon}
-      <p className="mt-2">{emptyMessage}</p>
-    </div>
-  )
-
-  // Items
-  return <div className="space-y-2">{items.map(renderItem)}</div>
-}
-```
-
-**Usage**:
-
-```typescript
-<FeedList
-  items={conversations}
-  loading={loading}
-  error={error}
-  renderItem={(conv, i) => <ConversationCard key={conv.id} conversation={conv} />}
-  emptyIcon={<MessageSquare className="w-12 h-12 text-gray-600" />}
-  emptyMessage="No conversations yet"
-  skeletonCount={6}
-/>
-```
-
----
-
-### Virtualized Lists (react-virtuoso)
-
-For feeds with many items, use `react-virtuoso` instead of mapping all items to DOM. Two usage patterns exist:
-
-#### Pattern A: Window-Scroll Feed (Memories, Spaces, Groups, Profiles)
-
-Used for page-level feeds where the entire page scrolls. `useWindowScroll` delegates scrolling to the browser window.
-
-```typescript
-import { Virtuoso } from 'react-virtuoso'
-
-<Virtuoso
-  useWindowScroll
-  data={memories}
-  endReached={() => {
-    if (hasMore && !loading && !loadingMore) {
-      loadFeed(false)  // Append next page
-    }
-  }}
-  itemContent={(index, memory) => (
-    <div className="pb-2">
-      <MemoryCard memory={memory} source={source} />
-    </div>
-  )}
-  components={{
-    Footer: () =>
-      loadingMore ? (
-        <div className="flex justify-center py-4">
-          <Loader2 className="w-5 h-5 animate-spin text-gray-500" />
-        </div>
-      ) : null,
-  }}
-/>
-```
-
-**Key props**:
-- `useWindowScroll`: Scroll container is the browser window, not Virtuoso's own div
-- `data`: The array of items to render
-- `endReached`: Callback when user scrolls to the bottom — trigger load-more
-- `itemContent`: Render function per item (wraps card in `pb-2` for gap)
-- `components.Footer`: Loading spinner while fetching next page
-
-**Used in**: `/memories`, `SpacesFeed`, `ProfileMemoriesFeed`, `GroupMemories`
-
-#### Pattern B: Container-Scroll Chat (MessageList)
-
-Used for chat where messages prepend from the top and the container has a fixed height.
-
-```typescript
-import { Virtuoso, VirtuosoHandle } from 'react-virtuoso'
-
-const virtuosoRef = useRef<VirtuosoHandle>(null)
-
-<Virtuoso
-  ref={virtuosoRef}
-  className="flex-grow h-0"
-  firstItemIndex={firstItemIndex}
-  initialTopMostItemIndex={items.length - 1}
-  data={items}
-  startReached={() => {
-    if (!isLoadingMore && hasMore && onLoadMore) {
-      setIsLoadingMore(true)
-      onLoadMore()
-    }
-  }}
-  itemContent={(index, item) => <Message ... />}
-/>
-
-// Programmatic scroll to bottom
-virtuosoRef.current?.scrollToIndex({ index: 'LAST', behavior: 'smooth' })
-```
-
-**Key props**:
-- `firstItemIndex`: Enables stable prepend — set to a large number minus item count, decrement as older messages load
-- `initialTopMostItemIndex`: Start at bottom (`items.length - 1`)
-- `startReached`: Callback when user scrolls to the top — load older messages
-- `ref` (`VirtuosoHandle`): Exposes `scrollToIndex` for programmatic scroll (new message arrival, search result navigation)
-
-**Used in**: `MessageList`
-
-#### When to Use Each
-
-| Pattern | When | Scroll Container |
-|---|---|---|
-| FeedList (non-virtualized) | < ~50 items, simple lists | Parent div |
-| Virtuoso `useWindowScroll` | Feed pages with infinite scroll | Browser window |
-| Virtuoso container-scroll | Chat with prepend, fixed height | Virtuoso div |
-
----
-
-## Anti-Patterns
-
-### Inconsistent Card Styling
-
-```typescript
-// Bad: Custom card styling that doesn't match the system
-<div className="bg-white rounded-md p-2 shadow">{content}</div>
-
-// Good: Use standard card classes
-<div className="bg-gray-900/50 backdrop-blur-sm border border-gray-800 rounded-xl p-4">
-  {content}
-</div>
-```
-
-### Reimplementing Loading/Empty/Error States
-
-```typescript
-// Bad: Custom loading/empty per page
-{loading ? <Spinner /> : items.length === 0 ? <p>Empty</p> : items.map(...)}
-
-// Good: Use CardList/FeedList
-<FeedList items={items} loading={loading} error={error}
-  renderItem={(item) => <MyCard item={item} />}
-  emptyIcon={<Icon />} emptyMessage="Nothing here" />
-```
-
----
-
-## Checklist
-
-- [ ] Cards use `bg-gray-900/50 backdrop-blur-sm border border-gray-800 rounded-xl p-4`
-- [ ] Text hierarchy follows: white (title), gray-400 (subtitle), gray-500 (meta)
-- [ ] Use `FeedList` for small static lists with loading/empty/error states
-- [ ] Use `Virtuoso` with `useWindowScroll` for feed pages with infinite scroll
-- [ ] Use `Virtuoso` container-scroll with `firstItemIndex` for chat-style prepend lists
-- [ ] Wrap each Virtuoso item in `<div className="pb-2">` for consistent card gap
-- [ ] Provide `components.Footer` with loading spinner for load-more feedback
-- [ ] Swipe-to-dismiss uses 80px threshold with reveal background
-- [ ] Deleted/faded items use `opacity-20` transition
-
----
-
-**Status**: Stable
-**Last Updated**: 2026-03-14
-**Contributors**: Community