canopycms-auth-clerk 0.0.0

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "canopycms-auth-clerk",
+  "version": "0.0.0",
+  "description": "Clerk authentication provider for CanopyCMS",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/safeinsights/canopycms.git",
+    "directory": "packages/canopycms-auth-clerk"
+  },
+  "private": false,
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": "./src/index.ts",
+    "./client": "./src/client.ts",
+    "./cache-writer": "./src/cache-writer.ts"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "publishConfig": {
+    "exports": {
+      ".": {
+        "import": "./dist/index.js",
+        "types": "./dist/index.d.ts"
+      },
+      "./client": {
+        "import": "./dist/client.js",
+        "types": "./dist/client.d.ts"
+      },
+      "./cache-writer": {
+        "import": "./dist/cache-writer.js",
+        "types": "./dist/cache-writer.d.ts"
+      }
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run --reporter=dot",
+    "typecheck": "tsc --noEmit"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "peerDependencies": {
+    "canopycms": "*",
+    "@clerk/backend": "^2.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.9.0",
+    "typescript": "^5.6.3",
+    "vitest": "^1.6.0"
+  }
+}

package/src/cache-writer.ts

@@ -0,0 +1,152 @@
+import { createClerkClient } from '@clerk/backend'
+import { writeAuthCacheSnapshot } from 'canopycms/auth/cache'
+
+/**
+ * Response types that handle both camelCase and snake_case Clerk SDK variants.
+ */
+interface ClerkUserData {
+  id: string
+  username?: string
+  fullName?: string | null
+  full_name?: string | null
+  imageUrl?: string | null
+  image_url?: string | null
+  primaryEmailAddress?: { emailAddress: string } | null
+  email_addresses?: Array<{ email_address: string }> | null
+}
+
+interface ClerkOrganization {
+  id: string
+  name: string
+  membersCount?: number
+  members_count?: number
+}
+
+interface ClerkOrganizationMembership {
+  organization: ClerkOrganization
+}
+
+interface ClerkPaginatedResponse<T> {
+  data: T[]
+}
+
+type ClerkResponse<T> = T[] | ClerkPaginatedResponse<T>
+
+function unwrapClerkResponse<T>(response: ClerkResponse<T>): T[] {
+  return Array.isArray(response) ? response : response.data
+}
+
+export interface RefreshClerkCacheOptions {
+  /** Clerk Secret Key (CLERK_SECRET_KEY) */
+  secretKey: string
+  /** Directory to write cache files to (e.g., /mnt/efs/workspace/.cache) */
+  cachePath: string
+  /** Whether to treat Clerk organizations as groups (default: true) */
+  useOrganizationsAsGroups?: boolean
+}
+
+export interface RefreshClerkCacheResult {
+  userCount: number
+  groupCount: number
+  membershipCount: number
+}
+
+/**
+ * Fetches all user/org metadata from Clerk API and writes to JSON cache files.
+ *
+ * Used by the EC2 worker to populate the cache that FileBasedAuthCache reads.
+ * Writes atomically (write to temp file, then rename) to avoid partial reads.
+ *
+ * Output files:
+ * - {cachePath}/users.json    — { users: UserSearchResult[] }
+ * - {cachePath}/orgs.json     — { groups: GroupMetadata[] }
+ * - {cachePath}/memberships.json — { memberships: { [userId]: groupId[] } }
+ */
+export async function refreshClerkCache(
+  options: RefreshClerkCacheOptions,
+): Promise<RefreshClerkCacheResult> {
+  const { secretKey, cachePath, useOrganizationsAsGroups = true } = options
+
+  const clerkClient = createClerkClient({ secretKey })
+
+  // Fetch all users (paginate to handle large organizations)
+  const clerkUsers: ClerkUserData[] = []
+  const pageSize = 500
+  let offset = 0
+  // eslint-disable-next-line no-constant-condition
+  while (true) {
+    const usersResponse = (await clerkClient.users.getUserList({
+      limit: pageSize,
+      offset,
+    })) as ClerkResponse<ClerkUserData>
+    const page = unwrapClerkResponse(usersResponse)
+    clerkUsers.push(...page)
+    if (page.length < pageSize) break
+    offset += pageSize
+  }
+
+  const users = clerkUsers.map((u) => ({
+    id: u.id,
+    name: u.fullName ?? u.full_name ?? u.username ?? u.id,
+    email: u.primaryEmailAddress?.emailAddress ?? u.email_addresses?.[0]?.email_address ?? '',
+    avatarUrl: u.imageUrl ?? u.image_url ?? undefined,
+  }))
+
+  let groups: Array<{ id: string; name: string; memberCount?: number }> = []
+  const memberships: Record<string, string[]> = {}
+
+  if (useOrganizationsAsGroups) {
+    // Fetch all organizations (paginate)
+    const clerkOrgs: ClerkOrganization[] = []
+    let orgOffset = 0
+    const orgPageSize = 100
+    // eslint-disable-next-line no-constant-condition
+    while (true) {
+      const orgsResponse = (await clerkClient.organizations.getOrganizationList({
+        limit: orgPageSize,
+        offset: orgOffset,
+      })) as ClerkResponse<ClerkOrganization>
+      const page = unwrapClerkResponse(orgsResponse)
+      clerkOrgs.push(...page)
+      if (page.length < orgPageSize) break
+      orgOffset += orgPageSize
+    }
+
+    groups = clerkOrgs.map((o) => ({
+      id: o.id,
+      name: o.name,
+      memberCount: o.membersCount ?? o.members_count,
+    }))
+
+    // Fetch memberships per user
+    for (const user of clerkUsers) {
+      try {
+        const membershipResponse = (await clerkClient.users.getOrganizationMembershipList({
+          userId: user.id,
+        })) as ClerkResponse<ClerkOrganizationMembership>
+        const userMemberships = unwrapClerkResponse(membershipResponse)
+        if (userMemberships.length > 0) {
+          memberships[user.id] = userMemberships.map((m) => m.organization.id)
+        }
+      } catch (err) {
+        console.warn(
+          `Failed to fetch memberships for user ${user.id}:`,
+          err instanceof Error ? err.message : err,
+        )
+      }
+    }
+  }
+
+  // Write cache files atomically via snapshot directory + symlink swap
+  await writeAuthCacheSnapshot(cachePath, {
+    'users.json': { users },
+    'orgs.json': { groups },
+    'memberships.json': { memberships },
+  })
+
+  return {
+    userCount: users.length,
+    groupCount: groups.length,
+    membershipCount: Object.keys(memberships).length,
+  }
+}

package/src/clerk-plugin.test.ts

@@ -0,0 +1,385 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { mockConsole } from '../../canopycms/src/test-utils/console-spy.js'
+
+// Create mock objects
+const mockGetUser = vi.fn()
+const mockGetUserList = vi.fn()
+const mockGetOrganizationMembershipList = vi.fn()
+const mockGetOrganization = vi.fn()
+const mockGetOrganizationList = vi.fn()
+
+const mockClerkClient = {
+  users: {
+    getUser: mockGetUser,
+    getUserList: mockGetUserList,
+    getOrganizationMembershipList: mockGetOrganizationMembershipList,
+  },
+  organizations: {
+    getOrganization: mockGetOrganization,
+    getOrganizationList: mockGetOrganizationList,
+  },
+}
+
+// Mock @clerk/backend - must be hoisted before imports
+vi.mock('@clerk/backend', () => ({
+  createClerkClient: vi.fn(() => mockClerkClient),
+  verifyToken: vi.fn(),
+}))
+
+import { ClerkAuthPlugin } from './clerk-plugin'
+import { verifyToken } from '@clerk/backend'
+import type { CanopyRequest } from 'canopycms/http'
+
+const mockVerifyToken = verifyToken as any
+
+describe('ClerkAuthPlugin', () => {
+  beforeEach(() => {
+    vi.clearAllMocks()
+    // Set default env var
+    process.env.CLERK_SECRET_KEY = 'sk_test_1234'
+  })
+
+  describe('constructor', () => {
+    it('throws error if CLERK_SECRET_KEY not provided', () => {
+      delete process.env.CLERK_SECRET_KEY
+      expect(() => new ClerkAuthPlugin()).toThrow('CLERK_SECRET_KEY')
+    })
+
+    it('uses env var for secret key by default', () => {
+      const plugin = new ClerkAuthPlugin()
+      expect(plugin).toBeDefined()
+    })
+
+    it('uses default config values', () => {
+      const plugin = new ClerkAuthPlugin()
+      // Config is private, but we can test behavior
+      expect(plugin).toBeDefined()
+    })
+  })
+
+  describe('authenticate', () => {
+    it('returns failure if no token in request', async () => {
+      const plugin = new ClerkAuthPlugin()
+      const req = {
+        method: 'GET',
+        header: vi.fn().mockReturnValue(null),
+      } as unknown as CanopyRequest
+
+      const result = await plugin.authenticate(req)
+
+      expect(result.success).toBe(false)
+      expect(result.error).toBe('No authentication token found')
+    })
+
+    it('returns failure if token verification fails', async () => {
+      const plugin = new ClerkAuthPlugin()
+      const req = {
+        method: 'GET',
+        header: vi.fn().mockImplementation((name: string) => {
+          if (name === 'Authorization') return 'Bearer test_token'
+          return null
+        }),
+      } as unknown as CanopyRequest
+
+      mockVerifyToken.mockRejectedValue(new Error('Invalid token'))
+
+      const result = await plugin.authenticate(req)
+
+      expect(result.success).toBe(false)
+      expect(result.error).toBe('Invalid token')
+    })
+
+    it('verifies valid session and returns user identity', async () => {
+      const plugin = new ClerkAuthPlugin()
+      const req = {
+        method: 'GET',
+        header: vi.fn().mockImplementation((name: string) => {
+          if (name === 'Authorization') return 'Bearer valid_token'
+          return null
+        }),
+      } as unknown as CanopyRequest
+
+      mockVerifyToken.mockResolvedValue({
+        sub: 'user_123',
+        sid: 'sess_123',
+      })
+
+      mockGetUser.mockResolvedValue({
+        id: 'user_123',
+        fullName: 'John Doe',
+        primaryEmailAddress: { emailAddress: 'john@example.com' },
+      })
+
+      mockGetOrganizationMembershipList.mockResolvedValue({
+        data: [{ organization: { id: 'org_1' } }, { organization: { id: 'org_2' } }],
+      })
+
+      const result = await plugin.authenticate(req)
+
+      expect(result.success).toBe(true)
+      expect(result.user).toEqual({
+        userId: 'user_123',
+        name: 'John Doe',
+        email: 'john@example.com',
+        externalGroups: ['org_1', 'org_2'],
+      })
+    })
+
+    it('returns user without external groups if organizations disabled', async () => {
+      const plugin = new ClerkAuthPlugin({ useOrganizationsAsGroups: false })
+      const req = {
+        method: 'GET',
+        header: vi.fn().mockImplementation((name: string) => {
+          if (name === 'Authorization') return 'Bearer valid_token'
+          return null
+        }),
+      } as unknown as CanopyRequest
+
+      mockVerifyToken.mockResolvedValue({
+        sub: 'user_123',
+        sid: 'sess_123',
+      })
+
+      mockGetUser.mockResolvedValue({
+        id: 'user_123',
+        fullName: 'Jane Doe',
+        primaryEmailAddress: { emailAddress: 'jane@example.com' },
+      })
+
+      const result = await plugin.authenticate(req)
+
+      expect(result.success).toBe(true)
+      expect(result.user?.externalGroups).toBeUndefined()
+      expect(mockGetOrganizationMembershipList).not.toHaveBeenCalled()
+    })
+
+    it('handles errors gracefully', async () => {
+      const plugin = new ClerkAuthPlugin()
+      const req = {
+        method: 'GET',
+        header: vi.fn().mockImplementation((name: string) => {
+          if (name === 'Authorization') return 'Bearer valid_token'
+          return null
+        }),
+      } as unknown as CanopyRequest
+
+      mockVerifyToken.mockRejectedValue(new Error('Network error'))
+
+      const result = await plugin.authenticate(req)
+
+      expect(result.success).toBe(false)
+      expect(result.error).toBe('Network error')
+    })
+
+    it('extracts token from __session cookie', async () => {
+      const plugin = new ClerkAuthPlugin()
+      const req = {
+        method: 'GET',
+        header: vi.fn().mockImplementation((name: string) => {
+          if (name === 'Cookie') return '__session=cookie_token; other=value'
+          return null
+        }),
+      } as unknown as CanopyRequest
+
+      mockVerifyToken.mockResolvedValue({
+        sub: 'user_123',
+      })
+
+      mockGetUser.mockResolvedValue({
+        id: 'user_123',
+        fullName: 'Cookie User',
+        primaryEmailAddress: { emailAddress: 'cookie@example.com' },
+      })
+
+      mockGetOrganizationMembershipList.mockResolvedValue({ data: [] })
+
+      const result = await plugin.authenticate(req)
+
+      expect(result.success).toBe(true)
+      expect(mockVerifyToken).toHaveBeenCalledWith('cookie_token', expect.any(Object))
+    })
+  })
+
+  describe('searchUsers', () => {
+    it('searches users and returns results', async () => {
+      const plugin = new ClerkAuthPlugin()
+
+      mockGetUserList.mockResolvedValue({
+        data: [
+          {
+            id: 'user_1',
+            fullName: 'Alice Smith',
+            primaryEmailAddress: { emailAddress: 'alice@example.com' },
+            imageUrl: 'https://example.com/alice.jpg',
+          },
+          {
+            id: 'user_2',
+            username: 'bob',
+            primaryEmailAddress: { emailAddress: 'bob@example.com' },
+            imageUrl: 'https://example.com/bob.jpg',
+          },
+        ],
+      })
+
+      const results = await plugin.searchUsers('alice')
+
+      expect(results).toHaveLength(2)
+      expect(results[0]).toEqual({
+        id: 'user_1',
+        name: 'Alice Smith',
+        email: 'alice@example.com',
+        avatarUrl: 'https://example.com/alice.jpg',
+      })
+      expect(results[1]).toEqual({
+        id: 'user_2',
+        name: 'bob',
+        email: 'bob@example.com',
+        avatarUrl: 'https://example.com/bob.jpg',
+      })
+      expect(mockGetUserList).toHaveBeenCalledWith({
+        query: 'alice',
+        limit: 10,
+      })
+    })
+
+    it('returns empty array on error', async () => {
+      const consoleSpy = mockConsole()
+      const plugin = new ClerkAuthPlugin()
+
+      mockGetUserList.mockRejectedValue(new Error('API error'))
+
+      const results = await plugin.searchUsers('test')
+
+      expect(results).toEqual([])
+      consoleSpy.restore()
+    })
+  })
+
+  describe('getUserMetadata', () => {
+    it('gets user metadata by ID', async () => {
+      const plugin = new ClerkAuthPlugin()
+
+      mockGetUser.mockResolvedValue({
+        id: 'user_123',
+        fullName: 'Test User',
+        primaryEmailAddress: { emailAddress: 'test@example.com' },
+        imageUrl: 'https://example.com/test.jpg',
+      })
+
+      const result = await plugin.getUserMetadata('user_123')
+
+      expect(result).toEqual({
+        id: 'user_123',
+        name: 'Test User',
+        email: 'test@example.com',
+        avatarUrl: 'https://example.com/test.jpg',
+      })
+    })
+
+    it('returns null on error', async () => {
+      const consoleSpy = mockConsole()
+      const plugin = new ClerkAuthPlugin()
+
+      mockGetUser.mockRejectedValue(new Error('User not found'))
+
+      const result = await plugin.getUserMetadata('user_123')
+
+      expect(result).toBeNull()
+      consoleSpy.restore()
+    })
+  })
+
+  describe('getGroupMetadata', () => {
+    it('gets organization metadata when enabled', async () => {
+      const plugin = new ClerkAuthPlugin({ useOrganizationsAsGroups: true })
+
+      mockGetOrganization.mockResolvedValue({
+        id: 'org_123',
+        name: 'Test Org',
+        membersCount: 42,
+      })
+
+      const result = await plugin.getGroupMetadata('org_123')
+
+      expect(result).toEqual({
+        id: 'org_123',
+        name: 'Test Org',
+        memberCount: 42,
+      })
+    })
+
+    it('returns null when organizations disabled', async () => {
+      const plugin = new ClerkAuthPlugin({ useOrganizationsAsGroups: false })
+
+      const result = await plugin.getGroupMetadata('org_123')
+
+      expect(result).toBeNull()
+      expect(mockGetOrganization).not.toHaveBeenCalled()
+    })
+
+    it('returns null on error', async () => {
+      const consoleSpy = mockConsole()
+      const plugin = new ClerkAuthPlugin({ useOrganizationsAsGroups: true })
+
+      mockGetOrganization.mockRejectedValue(new Error('Org not found'))
+
+      const result = await plugin.getGroupMetadata('org_123')
+
+      expect(result).toBeNull()
+      consoleSpy.restore()
+    })
+  })
+
+  describe('listGroups', () => {
+    it('lists organizations when enabled', async () => {
+      const plugin = new ClerkAuthPlugin({ useOrganizationsAsGroups: true })
+
+      mockGetOrganizationList.mockResolvedValue({
+        data: [
+          { id: 'org_1', name: 'Org One', membersCount: 10 },
+          { id: 'org_2', name: 'Org Two', membersCount: 20 },
+        ],
+      })
+
+      const results = await plugin.listGroups(50)
+
+      expect(results).toHaveLength(2)
+      expect(results[0]).toEqual({
+        id: 'org_1',
+        name: 'Org One',
+        memberCount: 10,
+      })
+      expect(mockGetOrganizationList).toHaveBeenCalledWith({ limit: 50 })
+    })
+
+    it('returns empty array when organizations disabled', async () => {
+      const plugin = new ClerkAuthPlugin({ useOrganizationsAsGroups: false })
+
+      const results = await plugin.listGroups()
+
+      expect(results).toEqual([])
+      expect(mockGetOrganizationList).not.toHaveBeenCalled()
+    })
+
+    it('returns empty array on error', async () => {
+      const consoleSpy = mockConsole()
+      const plugin = new ClerkAuthPlugin({ useOrganizationsAsGroups: true })
+
+      mockGetOrganizationList.mockRejectedValue(new Error('API error'))
+
+      const results = await plugin.listGroups()
+
+      expect(results).toEqual([])
+      consoleSpy.restore()
+    })
+  })
+
+  describe('createClerkAuthPlugin factory', () => {
+    it('creates plugin instance', async () => {
+      const { createClerkAuthPlugin } = await import('./clerk-plugin')
+      const plugin = createClerkAuthPlugin({})
+
+      expect(plugin).toBeInstanceOf(ClerkAuthPlugin)
+    })
+  })
+})