clerk-data-handling

name	clerk-data-handling
description	Handle user data, privacy, and GDPR compliance with Clerk. Use when implementing data export, user deletion, or privacy compliance features. Trigger with phrases like "clerk user data", "clerk GDPR", "clerk privacy", "clerk data export", "clerk delete user".
allowed-tools	Read, Write, Edit, Bash(npm:*), Grep
version	1.0.0
license	MIT
author	Jeremy Longshore <[e-mail]>

Clerk Data Handling

Overview

Manage user data, implement privacy features, and ensure compliance with regulations.

Prerequisites

• Clerk integration working
• Understanding of GDPR/CCPA requirements
• Database with user-related data

Instructions

Step 1: User Data Export

// lib/data-export.ts
import { clerkClient } from '@clerk/nextjs/server'
import { db } from './db'

interface UserDataExport {
  clerk: ClerkUserData
  application: ApplicationUserData
  exportedAt: string
}

interface ClerkUserData {
  id: string
  email: string | undefined
  firstName: string | null
  lastName: string | null
  createdAt: Date
  lastSignIn: Date | null
  metadata: Record<string, any>
}

interface ApplicationUserData {
  profile: any
  orders: any[]
  preferences: any
  activityLog: any[]
}

export async function exportUserData(userId: string): Promise<UserDataExport> {
  const client = await clerkClient()

  // Get Clerk user data
  const clerkUser = await client.users.getUser(userId)

  // Get application data
  const [profile, orders, preferences, activityLog] = await Promise.all([
    db.userProfile.findUnique({ where: { clerkId: userId } }),
    db.order.findMany({ where: { userId }, orderBy: { createdAt: 'desc' } }),
    db.userPreference.findMany({ where: { userId } }),
    db.activityLog.findMany({
      where: { userId },
      orderBy: { timestamp: 'desc' },
      take: 1000
    })
  ])

  return {
    clerk: {
      id: clerkUser.id,
      email: clerkUser.primaryEmailAddress?.emailAddress,
      firstName: clerkUser.firstName,
      lastName: clerkUser.lastName,
      createdAt: new Date(clerkUser.createdAt),
      lastSignIn: clerkUser.lastSignInAt ? new Date(clerkUser.lastSignInAt) : null,
      metadata: {
        public: clerkUser.publicMetadata,
        // Note: privateMetadata should be handled carefully
      }
    },
    application: {
      profile: sanitizeForExport(profile),
      orders: orders.map(sanitizeForExport),
      preferences: preferences.map(sanitizeForExport),
      activityLog: activityLog.map(sanitizeForExport)
    },
    exportedAt: new Date().toISOString()
  }
}

function sanitizeForExport(data: any): any {
  if (!data) return null

  // Remove internal fields
  const { id, createdAt, updatedAt, ...rest } = data
  return rest
}

Step 2: User Deletion (Right to be Forgotten)

// lib/user-deletion.ts
import { clerkClient } from '@clerk/nextjs/server'
import { db } from './db'

interface DeletionResult {
  success: boolean
  deletedFrom: string[]
  errors: string[]
}

export async function deleteUserCompletely(userId: string): Promise<DeletionResult> {
  const result: DeletionResult = {
    success: true,
    deletedFrom: [],
    errors: []
  }

  // Step 1: Delete from application database
  try {
    await db.$transaction([
      // Delete related records first (foreign key constraints)
      db.activityLog.deleteMany({ where: { userId } }),
      db.order.deleteMany({ where: { userId } }),
      db.userPreference.deleteMany({ where: { userId } }),
      db.userProfile.delete({ where: { clerkId: userId } })
    ])
    result.deletedFrom.()
  }  (: ) {
    result..()
    result. = 
  }

  
   {
     client =  ()
     client..(userId)
    result..()
  }  (: ) {
    result..()
    result. = 
  }

  
   {
     (userId)
    result..()
  }  (: ) {
    result..()
  }

  
   (userId, result)

   result
}

  () {
  
  
  
  
}

  () {
  
   db..({
    : {
      : (userId),
      :  (),
      : result.,
      : result.
    }
  })
}

Step 3: Data Retention Policies

// lib/data-retention.ts
import { db } from './db'
import { clerkClient } from '@clerk/nextjs/server'

interface RetentionPolicy {
  activityLogs: number // days
  sessions: number // days
  inactiveUsers: number // days
}

const RETENTION_POLICY: RetentionPolicy = {
  activityLogs: 90,
  sessions: 30,
  inactiveUsers: 365
}

export async function enforceRetentionPolicy() {
  const now = new Date()

  // Clean up old activity logs
  const activityCutoff = new Date(
    now.getTime() - RETENTION_POLICY.activityLogs * 24 * 60 * 60 * 1000
  )

  const deletedLogs = await db.activityLog.deleteMany({
    where: {
      timestamp: { : activityCutoff }
    }
  })

  .()

  
   inactiveCutoff =  (
    now.() - . *  *  *  * 
  )

   inactiveUsers =  db..({
    : {
      : { : inactiveCutoff },
      : 
    }
  })

  
   ( user  inactiveUsers) {
     (user.)
     db..({
      : { : user. },
      : { :  }
    })
  }

  .()
}

Step 4: Consent Management

// lib/consent.ts
import { currentUser } from '@clerk/nextjs/server'

interface ConsentRecord {
  marketing: boolean
  analytics: boolean
  thirdParty: boolean
  updatedAt: Date
}

export async function getConsent(userId: string): Promise<ConsentRecord | null> {
  const user = await currentUser()

  if (!user) return null

  return {
    marketing: user.publicMetadata?.consent?.marketing ?? false,
    analytics: user.publicMetadata?.consent?.analytics ?? false,
    thirdParty: user.publicMetadata?.consent?.thirdParty ?? false,
    updatedAt: new Date(user.publicMetadata?.consent?.updatedAt || user.createdAt)
  }
}

   () {
   client =  ()

   user =  client..(userId)
   currentConsent = user.?. || {}

   client..(userId, {
    : {
      ...user.,
      : {
        ...currentConsent,
        ...consent,
        :  ().()
      }
    }
  })

  
   (userId, consent)
}

Step 5: GDPR API Endpoints

// app/api/user/data/route.ts
import { auth } from '@clerk/nextjs/server'
import { exportUserData } from '@/lib/data-export'

// Data Export (GDPR Article 20)
export async function GET() {
  const { userId } = await auth()

  if (!userId) {
    return Response.json({ error: 'Unauthorized' }, { status: 401 })
  }

  const userData = await exportUserData(userId)

  return new Response(JSON.stringify(userData, null, 2), {
    headers: {
      'Content-Type': 'application/json',
      'Content-Disposition': `attachment; filename="user-data-${userId}.json"`
    }
  })
}

// app/api/user/delete/route.ts
import { deleteUserCompletely } from '@/lib/user-deletion'

// Data Deletion (GDPR Article 17)
export async function DELETE() {
   { userId } =  ()

   (!userId) {
     .({ :  }, { :  })
  }

  
   confirmed = request..() === 
   (!confirmed) {
     .(
      { : , :  },
      { :  }
    )
  }

   result =  (userId)

   (result.) {
     .({ :  })
  }  {
     .(
      { : , : result },
      { :  }
    )
  }
}

Step 6: Audit Logging

// lib/audit-log.ts
interface AuditEvent {
  type: 'data_access' | 'data_export' | 'data_deletion' | 'consent_change'
  userId: string
  performedBy: string
  details: Record<string, any>
  timestamp: Date
}

export async function logAuditEvent(event: Omit<AuditEvent, 'timestamp'>) {
  await db.auditLog.create({
    data: {
      ...event,
      timestamp: new Date()
    }
  })

  // For compliance, also log to external service
  if (process.env.AUDIT_LOG_ENDPOINT) {
    await fetch(process.env.AUDIT_LOG_ENDPOINT, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ ...event, timestamp: new () })
    })
  }
}

Privacy Checklist

• Data export functionality (GDPR Article 20)
• Data deletion functionality (GDPR Article 17)
• Consent management
• Data retention policies
• Audit logging
• Privacy policy updated
• Cookie consent implemented
• Data processing agreements

Output

• Data export functionality
• User deletion capability
• Consent management
• Audit logging

Error Handling

Scenario	Action
Partial deletion	Retry failed services, log for manual review
Export timeout	Queue export, email when complete
Consent sync fail	Retry with exponential backoff

Resources

• GDPR Requirements
• CCPA Requirements
• Clerk Privacy

Next Steps

Proceed to clerk-enterprise-rbac for enterprise SSO and RBAC.