canopycms 0.0.0

package/src/auth/caching-auth-plugin.test.ts

@@ -0,0 +1,154 @@
+import { describe, it, expect, vi, beforeEach } from 'vitest'
+import { CachingAuthPlugin } from './caching-auth-plugin'
+import type { AuthCacheProvider, TokenVerifier } from './caching-auth-plugin'
+import type { UserSearchResult, GroupMetadata } from './types'
+
+function createMockCache(overrides: Partial<AuthCacheProvider> = {}): AuthCacheProvider {
+  const users: UserSearchResult[] = [
+    {
+      id: 'user_1',
+      name: 'Alice Smith',
+      email: 'alice@example.com',
+      avatarUrl: 'https://avatar/alice',
+    },
+    { id: 'user_2', name: 'Bob Jones', email: 'bob@example.com' },
+  ]
+  const groups: GroupMetadata[] = [
+    { id: 'org_1', name: 'Engineering', memberCount: 5 },
+    { id: 'org_2', name: 'Design', memberCount: 3 },
+  ]
+  const memberships: Record<string, string[]> = {
+    user_1: ['org_1', 'org_2'],
+    user_2: ['org_1'],
+  }
+
+  return {
+    getUser: vi.fn(async (userId) => users.find((u) => u.id === userId) ?? null),
+    getGroup: vi.fn(async (groupId) => groups.find((g) => g.id === groupId) ?? null),
+    getAllUsers: vi.fn(async () => users),
+    getAllGroups: vi.fn(async () => groups),
+    getUserExternalGroups: vi.fn(async (userId) => memberships[userId] ?? []),
+    ...overrides,
+  }
+}
+
+describe('CachingAuthPlugin', () => {
+  let mockVerifier: TokenVerifier
+  let mockCache: AuthCacheProvider
+  let plugin: CachingAuthPlugin
+
+  beforeEach(() => {
+    mockVerifier = vi.fn(async () => ({ userId: 'user_1' }))
+    mockCache = createMockCache()
+    plugin = new CachingAuthPlugin(mockVerifier, mockCache)
+  })
+
+  describe('authenticate', () => {
+    it('returns user with cached metadata on successful token verification', async () => {
+      const result = await plugin.authenticate({})
+
+      expect(result.success).toBe(true)
+      expect(result.user).toEqual({
+        userId: 'user_1',
+        name: 'Alice Smith',
+        email: 'alice@example.com',
+        avatarUrl: 'https://avatar/alice',
+        externalGroups: ['org_1', 'org_2'],
+      })
+    })
+
+    it('returns failure when token verification fails', async () => {
+      mockVerifier = vi.fn(async () => null)
+      plugin = new CachingAuthPlugin(mockVerifier, mockCache)
+
+      const result = await plugin.authenticate({})
+
+      expect(result.success).toBe(false)
+      expect(result.error).toBe('No valid authentication token')
+    })
+
+    it('returns userId as name when user not in cache', async () => {
+      mockVerifier = vi.fn(async () => ({ userId: 'unknown_user' }))
+      plugin = new CachingAuthPlugin(mockVerifier, mockCache)
+
+      const result = await plugin.authenticate({})
+
+      expect(result.success).toBe(true)
+      expect(result.user?.userId).toBe('unknown_user')
+      expect(result.user?.name).toBe('unknown_user')
+      expect(result.user?.externalGroups).toEqual([])
+    })
+
+    it('passes context to verifier', async () => {
+      const context = { headers: new Headers({ Authorization: 'Bearer test' }) }
+      await plugin.authenticate(context)
+
+      expect(mockVerifier).toHaveBeenCalledWith(context)
+    })
+  })
+
+  describe('searchUsers', () => {
+    it('filters users by name', async () => {
+      const results = await plugin.searchUsers('alice')
+      expect(results).toHaveLength(1)
+      expect(results[0].name).toBe('Alice Smith')
+    })
+
+    it('filters users by email', async () => {
+      const results = await plugin.searchUsers('bob@')
+      expect(results).toHaveLength(1)
+      expect(results[0].email).toBe('bob@example.com')
+    })
+
+    it('is case insensitive', async () => {
+      const results = await plugin.searchUsers('ALICE')
+      expect(results).toHaveLength(1)
+    })
+
+    it('respects limit', async () => {
+      const results = await plugin.searchUsers('', 1)
+      expect(results).toHaveLength(1)
+    })
+
+    it('returns empty for no matches', async () => {
+      const results = await plugin.searchUsers('nonexistent')
+      expect(results).toHaveLength(0)
+    })
+  })
+
+  describe('getUserMetadata', () => {
+    it('returns user from cache', async () => {
+      const user = await plugin.getUserMetadata('user_1')
+      expect(user?.name).toBe('Alice Smith')
+    })
+
+    it('returns null for unknown user', async () => {
+      const user = await plugin.getUserMetadata('unknown')
+      expect(user).toBeNull()
+    })
+  })
+
+  describe('getGroupMetadata', () => {
+    it('returns group from cache', async () => {
+      const group = await plugin.getGroupMetadata('org_1')
+      expect(group?.name).toBe('Engineering')
+    })
+
+    it('returns null for unknown group', async () => {
+      const group = await plugin.getGroupMetadata('unknown')
+      expect(group).toBeNull()
+    })
+  })
+
+  describe('listGroups', () => {
+    it('returns all groups', async () => {
+      const groups = await plugin.listGroups()
+      expect(groups).toHaveLength(2)
+    })
+
+    it('respects limit', async () => {
+      const groups = await plugin.listGroups(1)
+      expect(groups).toHaveLength(1)
+    })
+  })
+})

package/src/auth/caching-auth-plugin.ts

@@ -0,0 +1,109 @@
+import type { AuthPlugin } from './plugin'
+import type { UserSearchResult, GroupMetadata, AuthenticationResult } from './types'
+import type { CanopyUserId, CanopyGroupId } from '../types'
+import { createDebugLogger } from '../utils/debug'
+
+const log = createDebugLogger({ prefix: 'CachingAuthPlugin' })
+
+/**
+ * Generic cache provider interface for auth metadata.
+ * Any auth system can implement its own cache backend
+ * (file-based, Redis, in-memory, etc.)
+ */
+export interface AuthCacheProvider {
+  getUser(userId: CanopyUserId): Promise<UserSearchResult | null>
+  getGroup(groupId: CanopyGroupId): Promise<GroupMetadata | null>
+  getAllUsers(): Promise<UserSearchResult[]>
+  getAllGroups(): Promise<GroupMetadata[]>
+  getUserExternalGroups(userId: CanopyUserId): Promise<CanopyGroupId[]>
+}
+
+/**
+ * Token verifier function type.
+ * Given a request context, extracts and verifies the auth token,
+ * returning the user ID on success.
+ */
+export type TokenVerifier = (context: unknown) => Promise<{ userId: CanopyUserId } | null>
+
+/**
+ * Auth plugin that wraps a token verifier with cached metadata lookups.
+ *
+ * Used in environments where the auth provider API is not reachable
+ * (e.g., Lambda with no internet). JWT verification is done locally,
+ * and user/group metadata comes from a cache populated externally
+ * (e.g., by an EC2 worker).
+ */
+export class CachingAuthPlugin implements AuthPlugin {
+  constructor(
+    private readonly verifyToken: TokenVerifier,
+    private readonly cache: AuthCacheProvider,
+  ) {}
+
+  async authenticate(context: unknown): Promise<AuthenticationResult> {
+    const identity = await this.verifyToken(context)
+    if (!identity) {
+      return { success: false, error: 'No valid authentication token' }
+    }
+
+    try {
+      const user = await this.cache.getUser(identity.userId)
+      const externalGroups = await this.cache.getUserExternalGroups(identity.userId)
+
+      return {
+        success: true,
+        user: {
+          userId: identity.userId,
+          name: user?.name ?? identity.userId,
+          email: user?.email,
+          avatarUrl: user?.avatarUrl,
+          externalGroups,
+        },
+      }
+    } catch {
+      // Cache error — still return authenticated with minimal info
+      log.debug('auth', 'Cache lookup failed, returning minimal user', {
+        userId: identity.userId,
+      })
+      return {
+        success: true,
+        user: {
+          userId: identity.userId,
+          name: identity.userId,
+          externalGroups: [],
+        },
+      }
+    }
+  }
+
+  async searchUsers(query: string, limit = 10): Promise<UserSearchResult[]> {
+    try {
+      const allUsers = await this.cache.getAllUsers()
+      const lowerQuery = query.toLowerCase()
+      return allUsers
+        .filter(
+          (u) =>
+            u.name.toLowerCase().includes(lowerQuery) || u.email.toLowerCase().includes(lowerQuery),
+        )
+        .slice(0, limit)
+    } catch {
+      return []
+    }
+  }
+
+  async getUserMetadata(userId: CanopyUserId): Promise<UserSearchResult | null> {
+    return this.cache.getUser(userId)
+  }
+
+  async getGroupMetadata(groupId: CanopyGroupId): Promise<GroupMetadata | null> {
+    return this.cache.getGroup(groupId)
+  }
+
+  async listGroups(limit = 50): Promise<GroupMetadata[]> {
+    try {
+      const allGroups = await this.cache.getAllGroups()
+      return allGroups.slice(0, limit)
+    } catch {
+      return []
+    }
+  }
+}

package/src/auth/context-helpers.ts

@@ -0,0 +1,75 @@
+import type { CanopyRequest } from '../http/types'
+
+/**
+ * Headers-like interface for auth context.
+ * Framework-agnostic - matches Web Headers, Next.js Headers, and any similar interface.
+ */
+export interface HeadersLike {
+  get(name: string): string | null
+}
+
+/**
+ * Type guard to check if context is a CanopyRequest.
+ * CanopyRequest has both 'header' method and 'method' property.
+ */
+export function isCanopyRequest(context: unknown): context is CanopyRequest {
+  return (
+    typeof context === 'object' &&
+    context !== null &&
+    'header' in context &&
+    'method' in context &&
+    typeof (context as Record<string, unknown>).header === 'function'
+  )
+}
+
+/**
+ * Type guard to check if context is a headers-like object.
+ * Headers have a 'get' method for retrieving header values.
+ */
+export function isHeadersLike(context: unknown): context is HeadersLike {
+  return (
+    typeof context === 'object' &&
+    context !== null &&
+    'get' in context &&
+    typeof (context as Record<string, unknown>).get === 'function'
+  )
+}
+
+/**
+ * Extract headers from various auth context types.
+ * Supports CanopyRequest (API routes) and any headers-like object (server components).
+ *
+ * @returns HeadersLike object or null if context type is unsupported
+ */
+export function extractHeaders(context: unknown): HeadersLike | null {
+  if (isCanopyRequest(context)) {
+    // Wrap CanopyRequest.header() as HeadersLike.get()
+    return {
+      get: (name: string) => context.header(name),
+    }
+  }
+
+  if (isHeadersLike(context)) {
+    return context
+  }
+
+  return null
+}
+
+/**
+ * Validate auth context and throw helpful error if unsupported.
+ * Use this in auth plugins to provide clear error messages.
+ */
+export function validateAuthContext(context: unknown): HeadersLike {
+  const headers = extractHeaders(context)
+
+  if (!headers) {
+    throw new Error(
+      'Invalid auth context: expected CanopyRequest or Headers object. ' +
+        'Received: ' +
+        (context === null ? 'null' : typeof context),
+    )
+  }
+
+  return headers
+}

package/src/auth/file-based-auth-cache.test.ts

@@ -0,0 +1,257 @@
+import { describe, it, expect, beforeEach, afterEach } from 'vitest'
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import os from 'node:os'
+import { FileBasedAuthCache, writeAuthCacheSnapshot } from './file-based-auth-cache'
+
+describe('FileBasedAuthCache', () => {
+  let tmpDir: string
+  let cache: FileBasedAuthCache
+
+  const testUsers = {
+    users: [
+      {
+        id: 'user_1',
+        name: 'Alice',
+        email: 'alice@test.com',
+        avatarUrl: 'https://avatar/alice',
+      },
+      { id: 'user_2', name: 'Bob', email: 'bob@test.com' },
+    ],
+  }
+
+  const testGroups = {
+    groups: [
+      { id: 'org_1', name: 'Engineering', memberCount: 5 },
+      { id: 'org_2', name: 'Design', memberCount: 3 },
+    ],
+  }
+
+  const testMemberships = {
+    memberships: {
+      user_1: ['org_1', 'org_2'],
+      user_2: ['org_1'],
+    },
+  }
+
+  beforeEach(async () => {
+    tmpDir = await fs.mkdtemp(path.join(os.tmpdir(), 'canopy-cache-test-'))
+    cache = new FileBasedAuthCache(tmpDir)
+  })
+
+  afterEach(async () => {
+    await fs.rm(tmpDir, { recursive: true, force: true })
+  })
+
+  async function writeCache() {
+    await fs.writeFile(path.join(tmpDir, 'users.json'), JSON.stringify(testUsers))
+    await fs.writeFile(path.join(tmpDir, 'orgs.json'), JSON.stringify(testGroups))
+    await fs.writeFile(path.join(tmpDir, 'memberships.json'), JSON.stringify(testMemberships))
+  }
+
+  describe('with populated cache', () => {
+    beforeEach(writeCache)
+
+    it('getUser returns user by ID', async () => {
+      const user = await cache.getUser('user_1')
+      expect(user).toEqual(testUsers.users[0])
+    })
+
+    it('getUser returns null for unknown ID', async () => {
+      const user = await cache.getUser('unknown')
+      expect(user).toBeNull()
+    })
+
+    it('getGroup returns group by ID', async () => {
+      const group = await cache.getGroup('org_1')
+      expect(group).toEqual(testGroups.groups[0])
+    })
+
+    it('getGroup returns null for unknown ID', async () => {
+      const group = await cache.getGroup('unknown')
+      expect(group).toBeNull()
+    })
+
+    it('getAllUsers returns all users', async () => {
+      const users = await cache.getAllUsers()
+      expect(users).toHaveLength(2)
+      expect(users[0].name).toBe('Alice')
+    })
+
+    it('getAllGroups returns all groups', async () => {
+      const groups = await cache.getAllGroups()
+      expect(groups).toHaveLength(2)
+    })
+
+    it('getUserExternalGroups returns group IDs for user', async () => {
+      const groups = await cache.getUserExternalGroups('user_1')
+      expect(groups).toEqual(['org_1', 'org_2'])
+    })
+
+    it('getUserExternalGroups returns empty array for unknown user', async () => {
+      const groups = await cache.getUserExternalGroups('unknown')
+      expect(groups).toEqual([])
+    })
+  })
+
+  describe('with empty cache directory', () => {
+    it('returns empty results when no cache files exist', async () => {
+      const users = await cache.getAllUsers()
+      expect(users).toEqual([])
+
+      const groups = await cache.getAllGroups()
+      expect(groups).toEqual([])
+
+      const user = await cache.getUser('user_1')
+      expect(user).toBeNull()
+    })
+  })
+
+  describe('cache invalidation', () => {
+    it('re-reads cache when file mtime changes', async () => {
+      await writeCache()
+
+      // First read
+      const users1 = await cache.getAllUsers()
+      expect(users1).toHaveLength(2)
+
+      // Wait a moment so mtime changes
+      await new Promise((r) => setTimeout(r, 50))
+
+      // Update cache with different data
+      const updatedUsers = {
+        users: [{ id: 'user_3', name: 'Charlie', email: 'charlie@test.com' }],
+      }
+      await fs.writeFile(path.join(tmpDir, 'users.json'), JSON.stringify(updatedUsers))
+
+      // Should pick up new data
+      const users2 = await cache.getAllUsers()
+      expect(users2).toHaveLength(1)
+      expect(users2[0].name).toBe('Charlie')
+    })
+
+    it('uses cached data when mtime unchanged', async () => {
+      await writeCache()
+
+      // Read twice — should use in-memory cache on second read
+      const users1 = await cache.getAllUsers()
+      const users2 = await cache.getAllUsers()
+      expect(users1).toEqual(users2)
+    })
+  })
+
+  describe('partial cache files', () => {
+    it('handles missing orgs.json gracefully', async () => {
+      await fs.writeFile(path.join(tmpDir, 'users.json'), JSON.stringify(testUsers))
+      // No orgs.json or memberships.json
+
+      const users = await cache.getAllUsers()
+      expect(users).toHaveLength(2)
+
+      const groups = await cache.getAllGroups()
+      expect(groups).toEqual([])
+    })
+
+    it('handles malformed JSON gracefully', async () => {
+      await fs.writeFile(path.join(tmpDir, 'users.json'), 'not json')
+
+      const users = await cache.getAllUsers()
+      expect(users).toEqual([])
+    })
+  })
+
+  describe('snapshot layout (symlink)', () => {
+    it('reads from snapshot directory via current symlink', async () => {
+      await writeAuthCacheSnapshot(tmpDir, {
+        'users.json': testUsers,
+        'orgs.json': testGroups,
+        'memberships.json': testMemberships,
+      })
+
+      const snapshotCache = new FileBasedAuthCache(tmpDir)
+      const users = await snapshotCache.getAllUsers()
+      expect(users).toHaveLength(2)
+      expect(users[0].name).toBe('Alice')
+
+      const groups = await snapshotCache.getAllGroups()
+      expect(groups).toHaveLength(2)
+
+      const memberships = await snapshotCache.getUserExternalGroups('user_1')
+      expect(memberships).toEqual(['org_1', 'org_2'])
+    })
+
+    it('picks up new snapshot after symlink swap', async () => {
+      await writeAuthCacheSnapshot(tmpDir, {
+        'users.json': testUsers,
+        'orgs.json': testGroups,
+        'memberships.json': testMemberships,
+      })
+
+      const snapshotCache = new FileBasedAuthCache(tmpDir)
+      const users1 = await snapshotCache.getAllUsers()
+      expect(users1).toHaveLength(2)
+
+      // Wait so mtime changes
+      await new Promise((r) => setTimeout(r, 50))
+
+      // Write new snapshot with different data
+      const updatedUsers = {
+        users: [{ id: 'user_3', name: 'Charlie', email: 'charlie@test.com' }],
+      }
+      await writeAuthCacheSnapshot(tmpDir, {
+        'users.json': updatedUsers,
+        'orgs.json': { groups: [] },
+        'memberships.json': { memberships: {} },
+      })
+
+      const users2 = await snapshotCache.getAllUsers()
+      expect(users2).toHaveLength(1)
+      expect(users2[0].name).toBe('Charlie')
+    })
+
+    it('falls back to flat layout when symlink target escapes cache directory', async () => {
+      // Create a symlink pointing outside the cache directory
+      const currentLink = path.join(tmpDir, 'current')
+      try {
+        await fs.unlink(currentLink)
+      } catch {
+        // May not exist
+      }
+      await fs.symlink('/tmp', currentLink)
+
+      // Write users.json to the flat layout (in tmpDir directly)
+      await fs.writeFile(path.join(tmpDir, 'users.json'), JSON.stringify(testUsers))
+
+      const escapedCache = new FileBasedAuthCache(tmpDir)
+      // Should fall back to flat layout instead of following the escape symlink
+      const users = await escapedCache.getAllUsers()
+      expect(users).toHaveLength(2)
+      expect(users[0].name).toBe('Alice')
+    })
+
+    it('cleans up old snapshots keeping only 2', async () => {
+      // Write 3 snapshots
+      await writeAuthCacheSnapshot(tmpDir, {
+        'users.json': { users: [] },
+        'orgs.json': { groups: [] },
+        'memberships.json': { memberships: {} },
+      })
+      await new Promise((r) => setTimeout(r, 10))
+      await writeAuthCacheSnapshot(tmpDir, {
+        'users.json': { users: [] },
+        'orgs.json': { groups: [] },
+        'memberships.json': { memberships: {} },
+      })
+      await new Promise((r) => setTimeout(r, 10))
+      await writeAuthCacheSnapshot(tmpDir, {
+        'users.json': { users: [] },
+        'orgs.json': { groups: [] },
+        'memberships.json': { memberships: {} },
+      })
+
+      const entries = await fs.readdir(tmpDir)
+      const snapshots = entries.filter((e) => e.startsWith('snapshot-'))
+      expect(snapshots).toHaveLength(2)
+    })
+  })
+})