@prmichaelsen/acp-visualizer 0.1.0

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

@@ -0,0 +1,387 @@
+# 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

@@ -0,0 +1,271 @@
+# 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