@girardmedia/bootspring 1.2.0 → 2.0.3

package/skills/patterns/security/audit-logging.md

@@ -1,444 +0,0 @@
-# Audit Logging Patterns
-
-Patterns for tracking user actions and system events.
-
-## Audit Log Schema
-
-```prisma
-// prisma/schema.prisma
-model AuditLog {
-  id          String   @id @default(cuid())
-  timestamp   DateTime @default(now())
-  userId      String?
-  user        User?    @relation(fields: [userId], references: [id])
-  action      String   // e.g., "user.create", "post.delete"
-  entityType  String   // e.g., "User", "Post"
-  entityId    String?
-  oldValues   Json?
-  newValues   Json?
-  metadata    Json?    // IP, user agent, etc.
-  status      String   @default("success") // success, failure
-  errorMessage String?
-
-  @@index([userId])
-  @@index([entityType, entityId])
-  @@index([action])
-  @@index([timestamp])
-}
-```
-
-## Audit Logger Service
-
-```typescript
-// lib/audit/logger.ts
-import { prisma } from '@/lib/db'
-import { headers } from 'next/headers'
-
-interface AuditContext {
-  userId?: string
-  ip?: string
-  userAgent?: string
-}
-
-interface AuditEntry {
-  action: string
-  entityType: string
-  entityId?: string
-  oldValues?: Record<string, any>
-  newValues?: Record<string, any>
-  metadata?: Record<string, any>
-  status?: 'success' | 'failure'
-  errorMessage?: string
-}
-
-export class AuditLogger {
-  private context: AuditContext
-
-  constructor(context?: AuditContext) {
-    this.context = context ?? {}
-  }
-
-  static fromRequest(): AuditLogger {
-    const headersList = headers()
-    return new AuditLogger({
-      ip: headersList.get('x-forwarded-for') ?? headersList.get('x-real-ip') ?? undefined,
-      userAgent: headersList.get('user-agent') ?? undefined
-    })
-  }
-
-  setUser(userId: string): this {
-    this.context.userId = userId
-    return this
-  }
-
-  async log(entry: AuditEntry): Promise<void> {
-    await prisma.auditLog.create({
-      data: {
-        userId: this.context.userId,
-        action: entry.action,
-        entityType: entry.entityType,
-        entityId: entry.entityId,
-        oldValues: entry.oldValues,
-        newValues: entry.newValues,
-        status: entry.status ?? 'success',
-        errorMessage: entry.errorMessage,
-        metadata: {
-          ...entry.metadata,
-          ip: this.context.ip,
-          userAgent: this.context.userAgent
-        }
-      }
-    })
-  }
-
-  async logSuccess(entry: Omit<AuditEntry, 'status'>): Promise<void> {
-    await this.log({ ...entry, status: 'success' })
-  }
-
-  async logFailure(
-    entry: Omit<AuditEntry, 'status'>,
-    error?: Error
-  ): Promise<void> {
-    await this.log({
-      ...entry,
-      status: 'failure',
-      errorMessage: error?.message
-    })
-  }
-}
-
-// Singleton for simple usage
-export const auditLog = new AuditLogger()
-```
-
-## Audit Decorator/Wrapper
-
-```typescript
-// lib/audit/decorator.ts
-import { AuditLogger } from './logger'
-
-interface AuditOptions {
-  action: string
-  entityType: string
-  getEntityId?: (result: any) => string
-  getOldValues?: () => Promise<Record<string, any>>
-}
-
-export function withAudit<T extends (...args: any[]) => Promise<any>>(
-  fn: T,
-  options: AuditOptions,
-  getUserId: () => string | undefined
-): T {
-  return (async (...args: Parameters<T>) => {
-    const logger = AuditLogger.fromRequest()
-    const userId = getUserId()
-
-    if (userId) {
-      logger.setUser(userId)
-    }
-
-    const oldValues = options.getOldValues
-      ? await options.getOldValues()
-      : undefined
-
-    try {
-      const result = await fn(...args)
-
-      await logger.logSuccess({
-        action: options.action,
-        entityType: options.entityType,
-        entityId: options.getEntityId?.(result),
-        oldValues,
-        newValues: result
-      })
-
-      return result
-    } catch (error) {
-      await logger.logFailure(
-        {
-          action: options.action,
-          entityType: options.entityType,
-          oldValues
-        },
-        error as Error
-      )
-      throw error
-    }
-  }) as T
-}
-
-// Usage example
-const createUserWithAudit = withAudit(
-  async (data: { email: string; name: string }) => {
-    return prisma.user.create({ data })
-  },
-  {
-    action: 'user.create',
-    entityType: 'User',
-    getEntityId: (user) => user.id
-  },
-  () => getCurrentUserId()
-)
-```
-
-## Prisma Middleware for Automatic Auditing
-
-```typescript
-// lib/audit/prisma-middleware.ts
-import { Prisma } from '@prisma/client'
-import { prisma } from '@/lib/db'
-
-const AUDITED_MODELS = ['User', 'Post', 'Team', 'Subscription']
-const AUDITED_ACTIONS = ['create', 'update', 'delete']
-
-export const auditMiddleware: Prisma.Middleware = async (params, next) => {
-  const { model, action, args } = params
-
-  if (!model || !AUDITED_MODELS.includes(model)) {
-    return next(params)
-  }
-
-  if (!AUDITED_ACTIONS.includes(action)) {
-    return next(params)
-  }
-
-  // Get old values for update/delete
-  let oldValues: any = null
-  if ((action === 'update' || action === 'delete') && args.where) {
-    oldValues = await (prisma as any)[model.toLowerCase()].findUnique({
-      where: args.where
-    })
-  }
-
-  try {
-    const result = await next(params)
-
-    // Log successful operation
-    await prisma.auditLog.create({
-      data: {
-        action: `${model.toLowerCase()}.${action}`,
-        entityType: model,
-        entityId: result?.id ?? args.where?.id,
-        oldValues: oldValues ? JSON.parse(JSON.stringify(oldValues)) : null,
-        newValues: action !== 'delete' ? JSON.parse(JSON.stringify(result)) : null,
-        status: 'success'
-      }
-    })
-
-    return result
-  } catch (error) {
-    // Log failed operation
-    await prisma.auditLog.create({
-      data: {
-        action: `${model.toLowerCase()}.${action}`,
-        entityType: model,
-        entityId: args.where?.id,
-        oldValues: oldValues ? JSON.parse(JSON.stringify(oldValues)) : null,
-        status: 'failure',
-        errorMessage: error instanceof Error ? error.message : 'Unknown error'
-      }
-    })
-
-    throw error
-  }
-}
-
-// Register middleware
-// prisma.$use(auditMiddleware)
-```
-
-## API Route Auditing
-
-```typescript
-// lib/audit/route-wrapper.ts
-import { NextRequest, NextResponse } from 'next/server'
-import { AuditLogger } from './logger'
-import { auth } from '@/auth'
-
-type Handler = (req: NextRequest, context?: any) => Promise<NextResponse>
-
-interface AuditRouteOptions {
-  action: string
-  entityType: string
-  getEntityId?: (req: NextRequest, response: any) => string | undefined
-}
-
-export function auditedRoute(handler: Handler, options: AuditRouteOptions): Handler {
-  return async (req: NextRequest, context?: any) => {
-    const logger = AuditLogger.fromRequest()
-    const session = await auth()
-
-    if (session?.user?.id) {
-      logger.setUser(session.user.id)
-    }
-
-    const startTime = Date.now()
-
-    try {
-      const response = await handler(req, context)
-      const responseData = await response.clone().json().catch(() => null)
-
-      await logger.logSuccess({
-        action: options.action,
-        entityType: options.entityType,
-        entityId: options.getEntityId?.(req, responseData),
-        metadata: {
-          method: req.method,
-          path: req.nextUrl.pathname,
-          statusCode: response.status,
-          duration: Date.now() - startTime
-        }
-      })
-
-      return response
-    } catch (error) {
-      await logger.logFailure(
-        {
-          action: options.action,
-          entityType: options.entityType,
-          metadata: {
-            method: req.method,
-            path: req.nextUrl.pathname,
-            duration: Date.now() - startTime
-          }
-        },
-        error as Error
-      )
-
-      throw error
-    }
-  }
-}
-
-// Usage
-// app/api/users/[id]/route.ts
-export const DELETE = auditedRoute(
-  async (req, { params }) => {
-    const user = await prisma.user.delete({
-      where: { id: params.id }
-    })
-    return NextResponse.json({ success: true })
-  },
-  {
-    action: 'user.delete',
-    entityType: 'User',
-    getEntityId: (req, _) => req.nextUrl.pathname.split('/').pop()
-  }
-)
-```
-
-## Audit Log Viewer
-
-```typescript
-// app/admin/audit/page.tsx
-import { prisma } from '@/lib/db'
-import { formatDistanceToNow } from 'date-fns'
-
-interface AuditLogFilters {
-  userId?: string
-  action?: string
-  entityType?: string
-  startDate?: Date
-  endDate?: Date
-}
-
-async function getAuditLogs(filters: AuditLogFilters, page = 1, limit = 50) {
-  const where: any = {}
-
-  if (filters.userId) where.userId = filters.userId
-  if (filters.action) where.action = { contains: filters.action }
-  if (filters.entityType) where.entityType = filters.entityType
-  if (filters.startDate || filters.endDate) {
-    where.timestamp = {}
-    if (filters.startDate) where.timestamp.gte = filters.startDate
-    if (filters.endDate) where.timestamp.lte = filters.endDate
-  }
-
-  const [logs, total] = await Promise.all([
-    prisma.auditLog.findMany({
-      where,
-      include: { user: { select: { name: true, email: true } } },
-      orderBy: { timestamp: 'desc' },
-      skip: (page - 1) * limit,
-      take: limit
-    }),
-    prisma.auditLog.count({ where })
-  ])
-
-  return { logs, total, pages: Math.ceil(total / limit) }
-}
-
-export default async function AuditLogPage({
-  searchParams
-}: {
-  searchParams: { page?: string }
-}) {
-  const page = parseInt(searchParams.page ?? '1')
-  const { logs, total, pages } = await getAuditLogs({}, page)
-
-  return (
-    <div className="container py-8">
-      <h1 className="text-2xl font-bold mb-6">Audit Logs</h1>
-
-      <table className="w-full">
-        <thead>
-          <tr className="border-b">
-            <th className="text-left py-2">Time</th>
-            <th className="text-left py-2">User</th>
-            <th className="text-left py-2">Action</th>
-            <th className="text-left py-2">Entity</th>
-            <th className="text-left py-2">Status</th>
-          </tr>
-        </thead>
-        <tbody>
-          {logs.map(log => (
-            <tr key={log.id} className="border-b">
-              <td className="py-2 text-sm text-gray-600">
-                {formatDistanceToNow(log.timestamp, { addSuffix: true })}
-              </td>
-              <td className="py-2">
-                {log.user?.name ?? log.user?.email ?? 'System'}
-              </td>
-              <td className="py-2">
-                <code className="text-sm bg-gray-100 px-1 rounded">
-                  {log.action}
-                </code>
-              </td>
-              <td className="py-2">
-                {log.entityType}
-                {log.entityId && (
-                  <span className="text-gray-500 text-sm ml-1">
-                    #{log.entityId.slice(0, 8)}
-                  </span>
-                )}
-              </td>
-              <td className="py-2">
-                <span
-                  className={`px-2 py-0.5 rounded text-xs ${
-                    log.status === 'success'
-                      ? 'bg-green-100 text-green-800'
-                      : 'bg-red-100 text-red-800'
-                  }`}
-                >
-                  {log.status}
-                </span>
-              </td>
-            </tr>
-          ))}
-        </tbody>
-      </table>
-
-      <div className="mt-4 text-sm text-gray-600">
-        Showing {logs.length} of {total} logs
-      </div>
-    </div>
-  )
-}
-```
-
-## When to Use
-
-- Compliance requirements
-- Security monitoring
-- User activity tracking
-- Debugging and forensics

package/skills/patterns/security/csrf.md

@@ -1,234 +0,0 @@
-# CSRF Protection Patterns
-
-Patterns for Cross-Site Request Forgery protection.
-
-## Token-Based CSRF Protection
-
-```typescript
-// lib/csrf.ts
-import { randomBytes, createHmac } from 'crypto'
-import { cookies } from 'next/headers'
-
-const CSRF_SECRET = process.env.CSRF_SECRET!
-const CSRF_COOKIE = 'csrf_token'
-const CSRF_HEADER = 'x-csrf-token'
-
-export function generateCsrfToken(): string {
-  const token = randomBytes(32).toString('hex')
-  const signature = createHmac('sha256', CSRF_SECRET)
-    .update(token)
-    .digest('hex')
-
-  return `${token}.${signature}`
-}
-
-export function validateCsrfToken(token: string): boolean {
-  const [value, signature] = token.split('.')
-
-  if (!value || !signature) return false
-
-  const expectedSignature = createHmac('sha256', CSRF_SECRET)
-    .update(value)
-    .digest('hex')
-
-  return signature === expectedSignature
-}
-
-export async function setCsrfCookie() {
-  const token = generateCsrfToken()
-  const cookieStore = cookies()
-
-  cookieStore.set(CSRF_COOKIE, token, {
-    httpOnly: true,
-    secure: process.env.NODE_ENV === 'production',
-    sameSite: 'strict',
-    path: '/'
-  })
-
-  return token
-}
-
-export async function verifyCsrfToken(headerToken: string | null): boolean {
-  if (!headerToken) return false
-
-  const cookieStore = cookies()
-  const cookieToken = cookieStore.get(CSRF_COOKIE)?.value
-
-  if (!cookieToken) return false
-
-  return headerToken === cookieToken && validateCsrfToken(headerToken)
-}
-```
-
-## CSRF Middleware
-
-```typescript
-// middleware.ts
-import { NextResponse } from 'next/server'
-import type { NextRequest } from 'next/server'
-
-const SAFE_METHODS = ['GET', 'HEAD', 'OPTIONS']
-
-export function middleware(request: NextRequest) {
-  // Skip CSRF check for safe methods
-  if (SAFE_METHODS.includes(request.method)) {
-    return NextResponse.next()
-  }
-
-  // Skip for API routes that use other auth (API keys, etc.)
-  if (request.nextUrl.pathname.startsWith('/api/webhooks')) {
-    return NextResponse.next()
-  }
-
-  const csrfHeader = request.headers.get('x-csrf-token')
-  const csrfCookie = request.cookies.get('csrf_token')?.value
-
-  if (!csrfHeader || !csrfCookie || csrfHeader !== csrfCookie) {
-    return NextResponse.json(
-      { error: 'Invalid CSRF token' },
-      { status: 403 }
-    )
-  }
-
-  return NextResponse.next()
-}
-
-export const config = {
-  matcher: '/api/:path*'
-}
-```
-
-## CSRF Token Provider
-
-```tsx
-// components/providers/CsrfProvider.tsx
-'use client'
-
-import { createContext, useContext, useEffect, useState } from 'react'
-
-const CsrfContext = createContext<string | null>(null)
-
-export function CsrfProvider({ children }: { children: React.ReactNode }) {
-  const [token, setToken] = useState<string | null>(null)
-
-  useEffect(() => {
-    fetch('/api/csrf')
-      .then(res => res.json())
-      .then(data => setToken(data.token))
-  }, [])
-
-  return (
-    <CsrfContext.Provider value={token}>
-      {children}
-    </CsrfContext.Provider>
-  )
-}
-
-export function useCsrfToken() {
-  return useContext(CsrfContext)
-}
-
-// API route to get CSRF token
-// app/api/csrf/route.ts
-export async function GET() {
-  const token = await setCsrfCookie()
-  return Response.json({ token })
-}
-```
-
-## Protected Form
-
-```tsx
-// components/forms/ProtectedForm.tsx
-'use client'
-
-import { useCsrfToken } from '@/components/providers/CsrfProvider'
-
-export function ProtectedForm() {
-  const csrfToken = useCsrfToken()
-
-  async function handleSubmit(e: React.FormEvent<HTMLFormElement>) {
-    e.preventDefault()
-    const formData = new FormData(e.currentTarget)
-
-    const response = await fetch('/api/submit', {
-      method: 'POST',
-      headers: {
-        'Content-Type': 'application/json',
-        'X-CSRF-Token': csrfToken ?? ''
-      },
-      body: JSON.stringify(Object.fromEntries(formData))
-    })
-
-    // Handle response...
-  }
-
-  return (
-    <form onSubmit={handleSubmit}>
-      <input type="hidden" name="csrf_token" value={csrfToken ?? ''} />
-      {/* Form fields */}
-      <button type="submit">Submit</button>
-    </form>
-  )
-}
-```
-
-## Double Submit Cookie
-
-```typescript
-// lib/csrf-double-submit.ts
-import { cookies } from 'next/headers'
-import { randomBytes } from 'crypto'
-
-export function getOrCreateCsrfToken(): string {
-  const cookieStore = cookies()
-  let token = cookieStore.get('csrf')?.value
-
-  if (!token) {
-    token = randomBytes(32).toString('hex')
-    cookieStore.set('csrf', token, {
-      httpOnly: false, // Must be readable by JS
-      secure: process.env.NODE_ENV === 'production',
-      sameSite: 'strict'
-    })
-  }
-
-  return token
-}
-
-// Client-side: read cookie and send in header
-export function getCsrfTokenFromCookie(): string | null {
-  const match = document.cookie.match(/csrf=([^;]+)/)
-  return match ? match[1] : null
-}
-```
-
-## SameSite Cookie Protection
-
-```typescript
-// lib/session.ts
-// Modern approach: rely on SameSite cookies
-
-export function setSessionCookie(sessionId: string) {
-  const cookieStore = cookies()
-
-  cookieStore.set('session', sessionId, {
-    httpOnly: true,
-    secure: true,
-    sameSite: 'lax', // or 'strict' for more protection
-    path: '/',
-    maxAge: 60 * 60 * 24 * 7 // 1 week
-  })
-}
-
-// SameSite=Lax: Cookie sent with top-level navigations and GET from third-party
-// SameSite=Strict: Cookie only sent in first-party context
-// Combined with secure: true, this prevents most CSRF attacks
-```
-
-## When to Use
-
-- Form submissions
-- State-changing operations
-- API mutations
-- Authenticated requests