clerk-data-handling

What this skill does

# Clerk Data Handling

## Overview

Manage user data, implement privacy features, and ensure GDPR/CCPA compliance using the Clerk Backend API. Covers data export, right to be forgotten, consent management, and audit logging.

## Prerequisites

- Clerk integration working
- Understanding of GDPR/CCPA requirements
- Database with user-related data linked by Clerk user IDs

## Instructions

### Step 1: User Data Export

```typescript
// app/api/privacy/export/route.ts
import { auth, clerkClient } from '@clerk/nextjs/server'

export async function GET() {
  const { userId } = await auth()
  if (!userId) return Response.json({ error: 'Unauthorized' }, { status: 401 })

  const client = await clerkClient()
  const clerkUser = await client.users.getUser(userId)

  // Gather data from Clerk
  const clerkData = {
    id: clerkUser.id,
    emails: clerkUser.emailAddresses.map((e) => e.emailAddress),
    firstName: clerkUser.firstName,
    lastName: clerkUser.lastName,
    createdAt: clerkUser.createdAt,
    lastSignInAt: clerkUser.lastSignInAt,
    publicMetadata: clerkUser.publicMetadata,
  }

  // Gather data from your database
  const appData = await db.user.findUnique({
    where: { clerkId: userId },
    include: { posts: true, comments: true, preferences: true },
  })

  return Response.json({
    exportDate: new Date().toISOString(),
    clerkProfile: clerkData,
    applicationData: appData,
  })
}
```

### Step 2: User Deletion (Right to be Forgotten)

```typescript
// app/api/privacy/delete/route.ts
import { auth, clerkClient } from '@clerk/nextjs/server'

export async function DELETE() {
  const { userId } = await auth()
  if (!userId) return Response.json({ error: 'Unauthorized' }, { status: 401 })

  const deletionLog: { step: string; status: string }[] = []

  try {
    // 1. Delete application data first
    await db.comment.deleteMany({ where: { authorId: userId } })
    deletionLog.push({ step: 'comments', status: 'deleted' })

    await db.post.deleteMany({ where: { authorId: userId } })
    deletionLog.push({ step: 'posts', status: 'deleted' })

    await db.user.delete({ where: { clerkId: userId } })
    deletionLog.push({ step: 'app_user', status: 'deleted' })

    // 2. Delete from Clerk (this ends the session)
    const client = await clerkClient()
    await client.users.deleteUser(userId)
    deletionLog.push({ step: 'clerk_user', status: 'deleted' })

    // 3. Log deletion for compliance audit trail
    await db.auditLog.create({
      data: {
        action: 'USER_DELETED',
        subjectId: userId,
        details: JSON.stringify(deletionLog),
        timestamp: new Date(),
      },
    })

    return Response.json({ deleted: true, log: deletionLog })
  } catch (error) {
    return Response.json({ error: 'Partial deletion', log: deletionLog }, { status: 500 })
  }
}
```

### Step 3: Consent Management with Metadata

```typescript
// lib/consent.ts
import { clerkClient } from '@clerk/nextjs/server'

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

export async function updateConsent(userId: string, consent: Partial<ConsentRecord>) {
  const client = await clerkClient()
  const user = await client.users.getUser(userId)
  const existing = (user.publicMetadata.consent as ConsentRecord) || {}

  const updated: ConsentRecord = {
    ...existing,
    ...consent,
    updatedAt: new Date().toISOString(),
  }

  await client.users.updateUser(userId, {
    publicMetadata: { ...user.publicMetadata, consent: updated },
  })

  return updated
}

export async function getConsent(userId: string): Promise<ConsentRecord | null> {
  const client = await clerkClient()
  const user = await client.users.getUser(userId)
  return (user.publicMetadata.consent as ConsentRecord) || null
}
```

### Step 4: Consent UI Component

```typescript
'use client'
import { useUser } from '@clerk/nextjs'
import { useState } from 'react'

export function ConsentManager() {
  const { user } = useUser()
  const consent = (user?.publicMetadata as any)?.consent || {}
  const [marketing, setMarketing] = useState(consent.marketing ?? false)
  const [analytics, setAnalytics] = useState(consent.analytics ?? true)

  const saveConsent = async () => {
    await fetch('/api/privacy/consent', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ marketing, analytics }),
    })
  }

  return (
    <div>
      <h3>Privacy Preferences</h3>
      <label>
        <input type="checkbox" checked={marketing} onChange={(e) => setMarketing(e.target.checked)} />
        Marketing communications
      </label>
      <label>
        <input type="checkbox" checked={analytics} onChange={(e) => setAnalytics(e.target.checked)} />
        Analytics tracking
      </label>
      <button onClick={saveConsent}>Save Preferences</button>
    </div>
  )
}
```

### Step 5: Audit Logging via Webhooks

```typescript
// app/api/webhooks/clerk/route.ts (audit section)
async function logAuditEvent(evt: WebhookEvent) {
  const auditEntry = {
    eventType: evt.type,
    userId: 'user_id' in evt.data ? evt.data.user_id : evt.data.id,
    timestamp: new Date().toISOString(),
    metadata: JSON.stringify(evt.data),
  }

  await db.auditLog.create({ data: auditEntry })

  // Track compliance-relevant events
  if (['user.deleted', 'user.updated'].includes(evt.type)) {
    console.log(`[COMPLIANCE] ${evt.type} for user ${auditEntry.userId}`)
  }
}
```

## Output

- Data export API returning Clerk profile + application data
- User deletion cascade (app data, then Clerk, then audit log)
- Consent management stored in Clerk publicMetadata
- Privacy preferences UI component
- Audit logging for compliance events

## Error Handling

| Scenario | Action |
|----------|--------|
| Partial deletion failure | Log completed steps, retry failed services, alert ops team |
| Export timeout on large data | Queue export job, email user download link when ready |
| Consent sync failure | Retry with exponential backoff, fall back to local storage |
| Clerk API rate limit on bulk delete | Batch deletions with delays between requests |

## Examples

### Bulk User Data Cleanup Script

```typescript
// scripts/cleanup-orphaned-users.ts
import { createClerkClient } from '@clerk/backend'

const clerk = createClerkClient({ secretKey: process.env.CLERK_SECRET_KEY! })

async function cleanupOrphanedDbUsers() {
  const dbUsers = await db.user.findMany({ select: { clerkId: true } })

  for (const dbUser of dbUsers) {
    try {
      await clerk.users.getUser(dbUser.clerkId)
    } catch (err: any) {
      if (err.status === 404) {
        console.log(`Orphaned user: ${dbUser.clerkId} — removing from DB`)
        await db.user.delete({ where: { clerkId: dbUser.clerkId } })
      }
    }
  }
}
```

## Resources

- [Clerk User API](https://clerk.com/docs/references/backend/user/get-user)
- [Clerk Metadata](https://clerk.com/docs/users/metadata)
- [GDPR Compliance Guide](https://gdpr.eu/checklist/)

## Next Steps

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