moai-baas-clerk-ext

Original source / Raw SKILL.md

---
name: moai-baas-clerk-ext
version: 4.0.0
created: 2025-11-11
updated: '2025-11-18'
status: stable
description: Enterprise Clerk Authentication Platform with AI-powered modern identity
  architecture, Context7 integration, and intelligent user management orchestration
  for scalable applications
keywords:
- clerk
- modern-authentication
- user-management
- multi-platform
- webauthn
- organizations
- context7-integration
- ai-orchestration
- production-deployment
allowed-tools:
- Read
- Bash
- Write
- Edit
- Glob
- Grep
- WebFetch
- mcp__context7__resolve-library-id
- mcp__context7__get-library-docs
stability: stable
---


# Enterprise Clerk Authentication Platform Expert 

## Skill Metadata

| Field | Value |
| ----- | ----- |
| **Skill Name** | moai-baas-clerk-ext |
| **Version** | 4.0.0 (2025-11-13) |
| **Tier** | Enterprise Authentication Platform Expert |
| **AI-Powered** | ✅ Context7 Integration, Intelligent Architecture |
| **Auto-load** | On demand when Clerk keywords detected |

---

## What It Does

Enterprise Clerk Authentication Platform expert with AI-powered modern identity architecture, Context7 integration, and intelligent user management orchestration for scalable applications.

**Revolutionary  capabilities**:
- 🤖 **AI-Powered Clerk Architecture** using Context7 MCP for latest authentication patterns
- 📊 **Intelligent User Management** with automated organization and workflow optimization
- 🚀 **Advanced Multi-Platform Auth** with AI-driven cross-platform integration
- 🔗 **Enterprise Modern Identity** with zero-configuration WebAuthn and biometrics
- 📈 **Predictive User Analytics** with usage forecasting and optimization insights

---

## When to Use

**Automatic triggers**:
- Clerk authentication architecture and modern identity discussions
- Multi-platform user management and organization implementation
- WebAuthn and modern authentication method integration
- Real-time user experience and session management

**Manual invocation**:
- Designing enterprise Clerk architectures with optimal user experience
- Implementing organization management and multi-tenant authentication
- Planning migrations from traditional authentication systems
- Optimizing user onboarding and security configurations

---

# Quick Reference (Level 1)

## Clerk Authentication Platform (November 2025)

### Core Features Overview
- **Modern Authentication**: Passwordless, social login, biometric authentication
- **Multi-Platform Support**: Web, mobile, native applications with unified auth
- **Organizations**: Built-in multi-tenant workspace management
- **WebAuthn Integration**: Hardware security keys and biometric authentication
- **Real-time Sessions**: Advanced session management with cross-device sync

### Latest Versions (November 2025)
- **@clerk/nextjs**: v6.35.0 - Enhanced Next.js integration
- **@clerk/clerk-js**: v5.107.0 - Core JavaScript SDK improvements
- **@clerk/chrome-extension**: v2.7.14 - Chrome extension authentication
- **Android SDK**: Generally available with full feature parity

### Key Authentication Methods
- **Email/Password**: Traditional authentication with enhanced security
- **Social Login**: 30+ providers including Google, GitHub, Discord
- **Passwordless**: Magic links, email/SMS OTP
- **WebAuthn**: Hardware security keys, Windows Hello, Touch ID
- **M2M Tokens**: Machine-to-machine authentication

### Developer Experience
- **Zero Configuration**: Quick setup with sensible defaults
- **TypeScript Support**: Full type safety and autocomplete
- **Component Library**: Pre-built React components for auth UI
- **Customization**: Extensive theming and branding options

---

# Core Implementation (Level 2)

## Clerk Architecture Intelligence

```python
# AI-powered Clerk architecture optimization with Context7
class ClerkArchitectOptimizer:
    def __init__(self):
        self.context7_client = Context7Client()
        self.auth_analyzer = AuthenticationAnalyzer()
        self.ux_optimizer = UserExperienceOptimizer()
    
    async def design_optimal_clerk_architecture(self, 
                                              requirements: AuthenticationRequirements) -> ClerkArchitecture:
        """Design optimal Clerk architecture using AI analysis."""
        
        # Get latest Clerk and authentication documentation via Context7
        clerk_docs = await self.context7_client.get_library_docs(
            context7_library_id='/clerk/docs',
            topic="authentication user management organizations webauthn 2025",
            tokens=3000
        )
        
        auth_docs = await self.context7_client.get_library_docs(
            context7_library_id='/authentication/docs',
            topic="modern auth security patterns webauthn 2025",
            tokens=2000
        )
        
        # Optimize user experience flows
        ux_design = self.ux_optimizer.optimize_user_flows(
            requirements.user_preferences,
            requirements.platform_requirements,
            clerk_docs
        )
        
        # Configure security framework
        security_config = self.auth_analyzer.configure_security(
            requirements.security_level,
            requirements.threat_model,
            auth_docs
        )
        
        return ClerkArchitecture(
            authentication_flows=self._design_auth_flows(requirements),
            organization_setup=self._configure_organizations(requirements),
            security_framework=security_config,
            user_experience=ux_design,
            platform_integration=self._integrate_platforms(requirements),
            monitoring_setup=self._setup_monitoring(),
            migration_strategy=self._create_migration_strategy(requirements)
        )
```

## Multi-Platform Authentication Setup

```typescript
// Next.js application with Clerk integration
import { ClerkProvider, SignIn, SignUp, UserButton } from '@clerk/nextjs';
import { dark } from '@clerk/themes';
import type { AppProps } from 'next/app';

function MyApp({ Component, pageProps }: AppProps) {
  return (
    <ClerkProvider
      appearance={{
        baseTheme: dark,
        variables: {
          colorPrimary: '#ffffff',
          colorBackground: '#1a1a1a',
        },
        elements: {
          formButtonPrimary: 'bg-blue-600 hover:bg-blue-700 text-white',
          card: 'bg-gray-900 shadow-xl',
        },
      }}
      publishableKey={process.env.NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY}
    >
      <Component {...pageProps} />
    </ClerkProvider>
  );
}

export default MyApp;

// Protected route component
import { useAuth, RedirectToSignIn } from '@clerk/nextjs';
import { useEffect } from 'react';

export default function ProtectedPage() {
  const { isSignedIn, user, isLoaded } = useAuth();

  if (!isLoaded) {
    return <div>Loading...</div>;
  }

  if (!isSignedIn) {
    return <RedirectToSignIn />;
  }

  return (
    <div>
      <h1>Welcome, {user.firstName || user.emailAddresses[0].emailAddress}!</h1>
      <UserButton afterSignOutUrl="/" />
    </div>
  );
}
```

## Organization Management Implementation

```typescript
// Advanced organization management with Clerk
import { 
  ClerkProvider, 
  useOrganization, 
  useUser,
  OrganizationList,
  CreateOrganization,
} from '@clerk/nextjs';

export function OrganizationManagement() {
  const { organization, isLoaded, membership } = useOrganization();
  const { user } = useUser();

  if (!isLoaded) {
    return <div>Loading organization...</div>;
  }

  return (
    <div className="organization-management">
      {organization ? (
        <div className="current-organization">
          <h2>{organization.name}</h2>
          <p>Role: {membership?.role}</p>
          
          {/* Organization members management */}
          {membership?.role === 'admin' && (
            <div className="admin-panel">
              <h3>Admin Controls</h3>
              <OrganizationInvitation />
              <MemberList />
              <OrganizationSettings />
            </div>
          )}
          
          {/* Regular member view */}
          <div className="member-panel">
            <OrganizationProjects />
            <TeamCollaboration />
          </div>
        </div>
      ) : (
        <div className="no-organization">
          <h3>Join or Create an Organization</h3>
          <OrganizationList
            hidePersonal
            appearance={{
              elements: {
                organizationPreview: 'border border-gray-700 rounded-lg p-4',
              },
            }}
          />
          <CreateOrganization
            appearance={{
              elements: {
                formButtonPrimary: 'bg-blue-600 hover:bg-blue-700 text-white',
              },
            }}
          />
        </div>
      )}
    </div>
  );
}

// Organization invitation management
async function inviteUserToOrganization(
  organizationId: string,
  email: string,
  role: 'admin' | 'basic_member'
): Promise<void> {
  try {
    const response = await fetch(
      `https://api.clerk.dev/v1/organizations/${organizationId}/invitations`,
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.CLERK_SECRET_KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          email_address: email,
          role: role,
          disable_existing_memberships: false,
        }),
      }
    );

    if (!response.ok) {
      throw new Error('Failed to send invitation');
    }

    return await response.json();
  } catch (error) {
    console.error('Error inviting user:', error);
    throw error;
  }
}
```

---

# Advanced Implementation (Level 3)

## WebAuthn Security Implementation

```typescript
// Advanced WebAuthn configuration with Clerk
import { useAuth } from '@clerk/nextjs';
import { startAuthentication } from '@simplewebauthn/browser';

export function WebAuthnSecurity() {
  const { user } = useAuth();

  const enableWebAuthn = async () => {
    try {
      // Initiate WebAuthn registration
      const authResp = await startAuthentication({
        // Options provided by Clerk
        challenge: 'random_challenge_string',
        allowCredentials: [],
        userVerification: 'required',
        timeout: 60000,
      });

      // Complete registration with Clerk
      const response = await fetch('/api/auth/webauthn/register', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({
          credential: authResp,
          userId: user.id,
        }),
      });

      if (response.ok) {
        console.log('WebAuthn security key added successfully');
      }
    } catch (error) {
      console.error('WebAuthn registration failed:', error);
    }
  };

  return (
    <div className="webauthn-security">
      <h3>Security Keys</h3>
      <button onClick={enableWebAuthn}>
        Add Security Key (WebAuthn)
      </button>
      <SecurityKeyList />
    </div>
  );
}

// Backend API route for WebAuthn
import { clerkClient, getAuth } from '@clerk/nextjs/server';
import type { NextApiRequest, NextApiResponse } from 'next';

export default async function handler(
  req: NextApiRequest,
  res: NextApiResponse
) {
  const { userId } = getAuth(req);
  
  if (!userId) {
    return res.status(401).json({ error: 'Unauthorized' });
  }

  if (req.method === 'POST') {
    try {
      const { credential } = req.body;

      // Add WebAuthn credential to user
      const updatedUser = await clerkClient.users.updateUser(userId, {
        webauthnCredentials: [
          {
            publicKey: credential.response.publicKey,
            id: credential.id,
            type: credential.type,
            transports: credential.response.transports,
          }
        ]
      });

      res.status(200).json({ 
        success: true,
        message: 'Security key added successfully' 
      });
    } catch (error) {
      res.status(500).json({ error: 'Failed to add security key' });
    }
  } else {
    res.status(405).json({ error: 'Method not allowed' });
  }
}
```

### Real-time User Experience

```typescript
// Real-time user experience enhancements
import { useAuth, useUser } from '@clerk/nextjs';
import { useState, useEffect } from 'react';

export function RealtimeUserExperience() {
  const { user, isLoaded } = useUser();
  const [onlineStatus, setOnlineStatus] = useState<'online' | 'away' | 'offline'>('online');
  const [lastActivity, setLastActivity] = useState(Date.now());

  useEffect(() => {
    const handleActivity = () => {
      setLastActivity(Date.now());
      setOnlineStatus('online');
    };

    const checkInactivity = () => {
      const inactiveTime = Date.now() - lastActivity;
      if (inactiveTime > 300000) { // 5 minutes
        setOnlineStatus('away');
      }
      if (inactiveTime > 900000) { // 15 minutes
        setOnlineStatus('offline');
      }
    };

    // Track user activity
    window.addEventListener('mousemove', handleActivity);
    window.addEventListener('keydown', handleActivity);
    
    // Check inactivity periodically
    const inactivityTimer = setInterval(checkInactivity, 60000);

    return () => {
      window.removeEventListener('mousemove', handleActivity);
      window.removeEventListener('keydown', handleActivity);
      clearInterval(inactivityTimer);
    };
  }, [lastActivity]);

  if (!isLoaded) {
    return <div>Loading user experience...</div>;
  }

  return (
    <div className="user-experience">
      {/* Real-time presence indicator */}
      <div className={`status-indicator ${onlineStatus}`}>
        <span className="status-dot"></span>
        <span className="status-text">{onlineStatus}</span>
      </div>

      {/* Adaptive UI based on user preferences */}
      {user?.publicMetadata?.theme && (
        <div className="theme-applied">
          Theme: {user.publicMetadata.theme}
        </div>
      )}

      {/* Personalized features */}
      <PersonalizedFeatures user={user} />
    </div>
  );
}

// M2M (Machine-to-Machine) authentication
export function M2MAuthentication() {
  const [m2mToken, setM2mToken] = useState<string | null>(null);

  const generateM2MToken = async () => {
    try {
      const response = await fetch('/api/auth/m2m/token', {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${process.env.CLERK_SECRET_KEY}`,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify({
          template: 'service_account',
          expires_in_seconds: 3600,
        }),
      });

      const data = await response.json();
      setM2mToken(data.jwt);
    } catch (error) {
      console.error('M2M token generation failed:', error);
    }
  };

  return (
    <div className="m2m-authentication">
      <h3>Machine-to-Machine Authentication</h3>
      <button onClick={generateM2MToken}>
        Generate M2M Token
      </button>
      {m2mToken && (
        <div className="token-display">
          <p>Token generated successfully</p>
          <code>{m2mToken.substring(0, 20)}...</code>
        </div>
      )}
    </div>
  );
}
```

---

# Reference & Integration (Level 4)

## API Reference

### Core Clerk Operations
- `create_user(email, password)` - Create new user account
- `create_organization(name, slug)` - Create organization
- `invite_to_organization(org_id, email, role)` - Invite user to organization
- `add_webauthn_credential(user_id, credential)` - Add security key
- `generate_m2m_token(template)` - Generate machine-to-machine token

### Context7 Integration
- `get_latest_clerk_documentation()` - Official Clerk docs via Context7
- `analyze_modern_auth_patterns()` - Modern authentication via Context7
- `optimize_user_experience()` - UX best practices via Context7

## Best Practices (November 2025)

### DO
- Use Clerk components for consistent user experience
- Implement proper session management and security
- Configure organization features for multi-tenant applications
- Enable WebAuthn for enhanced security
- Customize appearance to match your brand
- Monitor authentication events and user activity
- Implement proper error handling for auth flows
- Use M2M tokens for service-to-service authentication

### DON'T
- Skip security configuration for production
- Ignore user experience optimization opportunities
- Forget to configure organization permissions properly
- Use hardcoded secrets or API keys
- Neglect monitoring and analytics
- Skip accessibility considerations in auth UI
- Forget to implement proper logout and session cleanup
- Ignore compliance requirements for user data

## Works Well With

- `moai-baas-foundation` (Enterprise BaaS architecture patterns)
- `moai-security-api` (API security and authorization)
- `moai-foundation-trust` (Security and compliance)
- `moai-baas-auth0-ext` (Enterprise authentication comparison)
- `moai-domain-frontend` (Frontend auth integration)
- `moai-essentials-perf` (Authentication performance optimization)
- `moai-domain-backend` (Backend auth integration)
- `moai-security-encryption` (Data protection and encryption)

## Changelog

- ** .0** (2025-11-13): Complete Enterprise   rewrite with 40% content reduction, 4-layer Progressive Disclosure structure, Context7 integration, November 2025 Clerk platform updates, and advanced WebAuthn implementation
- **v2.0.0** (2025-11-11): Complete metadata structure, auth patterns, organization management
- **v1.0.0** (2025-11-11): Initial Clerk authentication platform

---

**End of Skill** | Updated 2025-11-13

## Security & Compliance

### Modern Security Framework
- Multi-factor authentication with WebAuthn support
- Advanced session management with device fingerprinting
- Real-time threat detection and anomaly analysis
- Comprehensive audit logging and compliance reporting

### Data Protection
- GDPR compliance with data portability and deletion
- SOC2 Type II security controls
- Advanced encryption for sensitive authentication data
- Regional data residency with smart routing

---

**End of Enterprise Clerk Authentication Platform Expert **