canopycms 0.0.0

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

@@ -0,0 +1,279 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+import type { AuthCacheProvider } from './caching-auth-plugin'
+import type { UserSearchResult, GroupMetadata } from './types'
+import type { CanopyUserId, CanopyGroupId } from '../types'
+import { createDebugLogger } from '../utils/debug'
+
+const log = createDebugLogger({ prefix: 'FileBasedAuthCache' })
+
+interface CachedUsers {
+  users: UserSearchResult[]
+}
+
+interface CachedGroups {
+  groups: GroupMetadata[]
+}
+
+interface CachedMemberships {
+  memberships: Record<string, string[]> // userId -> groupId[]
+}
+
+interface LoadedCache {
+  users: Map<CanopyUserId, UserSearchResult>
+  groups: Map<CanopyGroupId, GroupMetadata>
+  memberships: Map<CanopyUserId, CanopyGroupId[]>
+  allUsers: UserSearchResult[]
+  allGroups: GroupMetadata[]
+}
+
+/**
+ * Resolve the active cache directory.
+ *
+ * Supports two layouts:
+ * 1. Snapshot layout (preferred): {cachePath}/current → {cachePath}/snapshot-{ts}/
+ *    The `current` symlink points to the active snapshot directory.
+ * 2. Flat layout (legacy/simple): files directly in {cachePath}/
+ *
+ * Returns the directory path where users.json, orgs.json, memberships.json live.
+ */
+async function resolveActiveCacheDir(cachePath: string): Promise<string> {
+  const currentLink = path.join(cachePath, 'current')
+  try {
+    const target = await fs.readlink(currentLink)
+    // Symlink target may be relative or absolute
+    const resolved = path.isAbsolute(target) ? target : path.resolve(cachePath, target)
+    // SECURITY: Validate that resolved target stays within the expected cache directory
+    const normalizedCache = path.resolve(cachePath)
+    const normalizedTarget = path.resolve(resolved)
+    if (
+      !normalizedTarget.startsWith(normalizedCache + path.sep) &&
+      normalizedTarget !== normalizedCache
+    ) {
+      log.debug('cache', 'Symlink target escapes cache directory', {
+        cachePath: normalizedCache,
+        target: normalizedTarget,
+      })
+      return cachePath
+    }
+    return resolved
+  } catch {
+    // No symlink — fall back to flat layout
+    return cachePath
+  }
+}
+
+/**
+ * File-based auth cache provider.
+ * Reads JSON files from a directory that is populated externally
+ * (e.g., by an EC2 worker running refreshClerkCache).
+ *
+ * Supports two directory layouts:
+ * - Snapshot layout: {cachePath}/current/ symlink → snapshot-{ts}/ directory
+ * - Flat layout: files directly in {cachePath}/
+ *
+ * Expects:
+ * - users.json   — { users: UserSearchResult[] }
+ * - orgs.json    — { groups: GroupMetadata[] }
+ * - memberships.json — { memberships: { [userId]: groupId[] } }
+ *
+ * Caches in memory and re-reads when file mtime changes.
+ */
+export class FileBasedAuthCache implements AuthCacheProvider {
+  private cache: LoadedCache | null = null
+  private lastMtime = 0
+
+  constructor(private readonly cachePath: string) {}
+
+  async getUser(userId: CanopyUserId): Promise<UserSearchResult | null> {
+    const cache = await this.ensureLoaded()
+    return cache.users.get(userId) ?? null
+  }
+
+  async getGroup(groupId: CanopyGroupId): Promise<GroupMetadata | null> {
+    const cache = await this.ensureLoaded()
+    return cache.groups.get(groupId) ?? null
+  }
+
+  async getAllUsers(): Promise<UserSearchResult[]> {
+    const cache = await this.ensureLoaded()
+    return cache.allUsers
+  }
+
+  async getAllGroups(): Promise<GroupMetadata[]> {
+    const cache = await this.ensureLoaded()
+    return cache.allGroups
+  }
+
+  async getUserExternalGroups(userId: CanopyUserId): Promise<CanopyGroupId[]> {
+    const cache = await this.ensureLoaded()
+    return cache.memberships.get(userId) ?? []
+  }
+
+  private async ensureLoaded(): Promise<LoadedCache> {
+    const activeDir = await resolveActiveCacheDir(this.cachePath)
+
+    const usersPath = path.join(activeDir, 'users.json')
+    const orgsPath = path.join(activeDir, 'orgs.json')
+    const membershipsPath = path.join(activeDir, 'memberships.json')
+
+    // Check max mtime across all three files for cache freshness
+    let maxMtime = 0
+    for (const filePath of [usersPath, orgsPath, membershipsPath]) {
+      try {
+        const stat = await fs.stat(filePath)
+        maxMtime = Math.max(maxMtime, stat.mtimeMs)
+      } catch {
+        // File doesn't exist — continue checking others
+      }
+    }
+
+    if (maxMtime === 0) {
+      // No cache files exist — return empty cache
+      if (!this.cache) {
+        this.cache = this.emptyCache()
+      }
+      return this.cache
+    }
+
+    // If max mtime hasn't changed and we have a cache, return it
+    if (this.cache && maxMtime === this.lastMtime) {
+      return this.cache
+    }
+
+    // Load fresh data
+    this.cache = await this.loadFromDisk(activeDir)
+    this.lastMtime = maxMtime
+    return this.cache
+  }
+
+  private async loadFromDisk(dir: string): Promise<LoadedCache> {
+    const usersPath = path.join(dir, 'users.json')
+    const orgsPath = path.join(dir, 'orgs.json')
+    const membershipsPath = path.join(dir, 'memberships.json')
+
+    const [usersData, orgsData, membershipsData] = await Promise.all([
+      this.readJsonFile<CachedUsers>(usersPath, { users: [] }),
+      this.readJsonFile<CachedGroups>(orgsPath, { groups: [] }),
+      this.readJsonFile<CachedMemberships>(membershipsPath, {
+        memberships: {},
+      }),
+    ])
+
+    const users = new Map<CanopyUserId, UserSearchResult>()
+    for (const user of usersData.users) {
+      users.set(user.id, user)
+    }
+
+    const groups = new Map<CanopyGroupId, GroupMetadata>()
+    for (const group of orgsData.groups) {
+      groups.set(group.id, group)
+    }
+
+    const memberships = new Map<CanopyUserId, CanopyGroupId[]>()
+    for (const [userId, groupIds] of Object.entries(membershipsData.memberships)) {
+      memberships.set(userId as CanopyUserId, groupIds as CanopyGroupId[])
+    }
+
+    log.debug('cache', 'Loaded auth cache', {
+      dir,
+      users: users.size,
+      groups: groups.size,
+      memberships: memberships.size,
+    })
+
+    return {
+      users,
+      groups,
+      memberships,
+      allUsers: usersData.users,
+      allGroups: orgsData.groups,
+    }
+  }
+
+  private async readJsonFile<T>(filePath: string, fallback: T): Promise<T> {
+    try {
+      const content = await fs.readFile(filePath, 'utf-8')
+      return JSON.parse(content) as T
+    } catch {
+      log.debug('cache', 'Cache file not found or invalid', { path: filePath })
+      return fallback
+    }
+  }
+
+  private emptyCache(): LoadedCache {
+    return {
+      users: new Map(),
+      groups: new Map(),
+      memberships: new Map(),
+      allUsers: [],
+      allGroups: [],
+    }
+  }
+}
+
+/**
+ * Write auth cache files atomically using a snapshot directory and symlink swap.
+ *
+ * 1. Writes files to a timestamped snapshot directory: {cachePath}/snapshot-{ts}/
+ * 2. Creates a temporary symlink, then atomically renames it to {cachePath}/current
+ * 3. Cleans up old snapshot directories (keeps the 2 most recent)
+ *
+ * This ensures readers (FileBasedAuthCache) always see a consistent set of files:
+ * either the old snapshot or the new one, never a mix.
+ */
+export async function writeAuthCacheSnapshot(
+  cachePath: string,
+  files: Record<string, unknown>,
+): Promise<string> {
+  await fs.mkdir(cachePath, { recursive: true })
+
+  const timestamp = Date.now()
+  const snapshotDir = path.join(cachePath, `snapshot-${timestamp}`)
+  await fs.mkdir(snapshotDir, { recursive: true })
+
+  // Write all files to the snapshot directory
+  for (const [fileName, data] of Object.entries(files)) {
+    const tmpPath = path.join(snapshotDir, `${fileName}.tmp`)
+    const finalPath = path.join(snapshotDir, fileName)
+    await fs.writeFile(tmpPath, JSON.stringify(data, null, 2), 'utf-8')
+    await fs.rename(tmpPath, finalPath)
+  }
+
+  // Atomic symlink swap: create temp symlink, rename over current
+  const currentLink = path.join(cachePath, 'current')
+  const tmpLink = path.join(cachePath, `current-${timestamp}`)
+  await fs.symlink(snapshotDir, tmpLink)
+  await fs.rename(tmpLink, currentLink)
+
+  // Clean up old snapshots (keep the 2 most recent)
+  await cleanupOldSnapshots(cachePath, 2)
+
+  return snapshotDir
+}
+
+async function cleanupOldSnapshots(cachePath: string, keepCount: number): Promise<void> {
+  let entries: string[]
+  try {
+    entries = await fs.readdir(cachePath)
+  } catch {
+    return
+  }
+
+  const snapshots = entries
+    .filter((e) => e.startsWith('snapshot-'))
+    .sort()
+    .reverse()
+
+  // Skip the most recent `keepCount` snapshots
+  for (const snapshot of snapshots.slice(keepCount)) {
+    try {
+      await fs.rm(path.join(cachePath, snapshot), {
+        recursive: true,
+        force: true,
+      })
+    } catch {
+      // Best effort cleanup
+    }
+  }
+}

package/src/auth/index.ts

@@ -0,0 +1,12 @@
+export type { AuthPlugin, AuthPluginFactory } from './plugin'
+export type { UserSearchResult, GroupMetadata, AuthenticationResult } from './types'
+export {
+  isCanopyRequest,
+  isHeadersLike,
+  extractHeaders,
+  validateAuthContext,
+} from './context-helpers'
+export type { HeadersLike } from './context-helpers'
+// Server-only implementations (CachingAuthPlugin, FileBasedAuthCache, writeAuthCacheSnapshot)
+// are exported via 'canopycms/auth/cache' to avoid pulling Node.js APIs into client bundles.
+export type { AuthCacheProvider, TokenVerifier } from './caching-auth-plugin'

package/src/auth/plugin.ts

@@ -0,0 +1,51 @@
+import type { UserSearchResult, GroupMetadata, AuthenticationResult } from './types'
+import type { CanopyUserId, CanopyGroupId } from '../types'
+
+/**
+ * Abstract auth provider interface.
+ * Implement this to integrate different auth systems (Clerk, Auth0, NextAuth, etc.)
+ */
+export interface AuthPlugin {
+  /**
+   * Authenticate user from request context.
+   * Returns user identity (without final groups) - core will apply bootstrap admins.
+   *
+   * @param context - Framework-specific context (CanopyRequest, headers, etc.)
+   * @returns AuthenticationResult with user identity or error
+   */
+  authenticate(context: unknown): Promise<AuthenticationResult>
+
+  /**
+   * Search for users (for permission management UI)
+   * @param query - Search string (email, name, etc.)
+   * @param limit - Max results (default 10)
+   */
+  searchUsers(query: string, limit?: number): Promise<UserSearchResult[]>
+
+  /**
+   * Get detailed user metadata by ID
+   */
+  getUserMetadata(userId: CanopyUserId): Promise<UserSearchResult | null>
+
+  /**
+   * Get group/organization metadata by ID
+   */
+  getGroupMetadata(groupId: CanopyGroupId): Promise<GroupMetadata | null>
+
+  /**
+   * List all groups (for permission UI dropdowns)
+   */
+  listGroups(limit?: number): Promise<GroupMetadata[]>
+
+  /**
+   * Search for external groups/organizations (for group management UI)
+   * Optional - only needed if auth provider supports external groups
+   * @param query - Search string (name, ID, etc.)
+   */
+  searchExternalGroups?(query: string): Promise<Array<{ id: CanopyGroupId; name: string }>>
+}
+
+/**
+ * Factory function type for creating auth plugins
+ */
+export type AuthPluginFactory<TConfig = unknown> = (config: TConfig) => AuthPlugin

package/src/auth/types.ts

@@ -0,0 +1,38 @@
+import type { CanopyUserId, CanopyGroupId } from '../types'
+
+/**
+ * User search result for permission UI
+ */
+export interface UserSearchResult {
+  id: CanopyUserId
+  name: string
+  email: string
+  avatarUrl?: string
+}
+
+/**
+ * Group metadata for permission UI
+ */
+export interface GroupMetadata {
+  id: CanopyGroupId
+  name: string
+  description?: string
+  memberCount?: number
+}
+
+/**
+ * Authentication result from auth plugins.
+ * Returns user identity (without final groups) on success.
+ */
+export interface AuthenticationResult {
+  success: boolean
+  user?: {
+    userId: CanopyUserId
+    email?: string
+    name?: string
+    avatarUrl?: string
+    /** Groups from external auth provider (e.g., Clerk organizations) */
+    externalGroups?: CanopyGroupId[]
+  }
+  error?: string
+}

package/src/authorization/__tests__/branch.test.ts

@@ -0,0 +1,260 @@
+import { describe, expect, it } from 'vitest'
+
+import { checkBranchAccessWithDefault, canPerformWorkflowAction, RESERVED_GROUPS } from '../'
+import type { BranchContext } from '../../types'
+
+const baseContext: BranchContext = {
+  baseRoot: '/tmp/base',
+  branchRoot: '/tmp/base/feature-x',
+  branch: {
+    name: 'feature/x',
+    status: 'editing',
+    access: {},
+    createdBy: 'user-1',
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  },
+}
+
+describe('branch access', () => {
+  it('allows Admins', () => {
+    const res = checkBranchAccessWithDefault(baseContext, {
+      type: 'authenticated',
+      userId: 'u',
+      groups: [RESERVED_GROUPS.ADMINS],
+    })
+    expect(res.allowed).toBe(true)
+    expect(res.reason).toBe('privileged')
+  })
+
+  it('allows Reviewers', () => {
+    const res = checkBranchAccessWithDefault(baseContext, {
+      type: 'authenticated',
+      userId: 'u',
+      groups: [RESERVED_GROUPS.REVIEWERS],
+    })
+    expect(res.allowed).toBe(true)
+    expect(res.reason).toBe('privileged')
+  })
+
+  it('denies when no ACLs are set (default deny)', () => {
+    const res = checkBranchAccessWithDefault(baseContext, {
+      type: 'authenticated',
+      userId: 'u',
+      groups: [],
+    })
+    expect(res.allowed).toBe(false)
+    expect(res.reason).toBe('no_acl')
+  })
+
+  it('honors default allow override', () => {
+    const res = checkBranchAccessWithDefault(
+      baseContext,
+      { type: 'authenticated', userId: 'u', groups: [] },
+      'allow',
+    )
+    expect(res.allowed).toBe(true)
+    expect(res.reason).toBe('no_acl')
+  })
+
+  it('denies when managerOrAdminAllowed set but user is not privileged', () => {
+    const res = checkBranchAccessWithDefault(
+      {
+        ...baseContext,
+        branch: {
+          ...baseContext.branch,
+          access: { managerOrAdminAllowed: true },
+        },
+      },
+      { type: 'authenticated', userId: 'u', groups: [] },
+    )
+    expect(res.allowed).toBe(false)
+    expect(res.reason).toBe('denied_by_acl')
+  })
+
+  it('allows matching user', () => {
+    const res = checkBranchAccessWithDefault(
+      {
+        ...baseContext,
+        branch: { ...baseContext.branch, access: { allowedUsers: ['user-1'] } },
+      },
+      { type: 'authenticated', userId: 'user-1', groups: [] },
+    )
+    expect(res.allowed).toBe(true)
+  })
+
+  it('allows matching group', () => {
+    const res = checkBranchAccessWithDefault(
+      {
+        ...baseContext,
+        branch: {
+          ...baseContext.branch,
+          access: { allowedGroups: ['group-1'] },
+        },
+      },
+      { type: 'authenticated', userId: 'u', groups: ['group-1'] },
+    )
+    expect(res.allowed).toBe(true)
+  })
+
+  it('denies when allowlists miss', () => {
+    const res = checkBranchAccessWithDefault(
+      {
+        ...baseContext,
+        branch: { ...baseContext.branch, access: { allowedUsers: ['user-2'] } },
+      },
+      { type: 'authenticated', userId: 'user-1', groups: [] },
+    )
+    expect(res.allowed).toBe(false)
+    expect(res.reason).toBe('denied_by_acl')
+  })
+})
+
+describe('canPerformWorkflowAction', () => {
+  const regularUser = {
+    type: 'authenticated' as const,
+    userId: 'user-1',
+    groups: [],
+  }
+  const admin = {
+    type: 'authenticated' as const,
+    userId: 'admin-1',
+    groups: [RESERVED_GROUPS.ADMINS],
+  }
+  const reviewer = {
+    type: 'authenticated' as const,
+    userId: 'reviewer-1',
+    groups: [RESERVED_GROUPS.REVIEWERS],
+  }
+
+  describe('branch creator permissions', () => {
+    it('allows branch creator to perform workflow actions', () => {
+      const context: BranchContext = {
+        ...baseContext,
+        branch: { ...baseContext.branch, createdBy: 'user-1', access: {} },
+      }
+      expect(canPerformWorkflowAction(context, regularUser, 'allow')).toBe(true)
+    })
+
+    it('denies non-creator without ACL access', () => {
+      const context: BranchContext = {
+        ...baseContext,
+        branch: { ...baseContext.branch, createdBy: 'user-2', access: {} },
+      }
+      expect(canPerformWorkflowAction(context, regularUser, 'deny')).toBe(false)
+    })
+  })
+
+  describe('ACL-based permissions', () => {
+    it('allows user in allowedUsers ACL', () => {
+      const context: BranchContext = {
+        ...baseContext,
+        branch: {
+          ...baseContext.branch,
+          createdBy: 'user-2',
+          access: { allowedUsers: ['user-1'] },
+        },
+      }
+      expect(canPerformWorkflowAction(context, regularUser, 'deny')).toBe(true)
+    })
+
+    it('allows user in allowedGroups ACL', () => {
+      const userInGroup = {
+        type: 'authenticated' as const,
+        userId: 'user-1',
+        groups: ['team-a'],
+      }
+      const context: BranchContext = {
+        ...baseContext,
+        branch: {
+          ...baseContext.branch,
+          createdBy: 'user-2',
+          access: { allowedGroups: ['team-a'] },
+        },
+      }
+      expect(canPerformWorkflowAction(context, userInGroup, 'deny')).toBe(true)
+    })
+
+    it('denies user not in ACL', () => {
+      const context: BranchContext = {
+        ...baseContext,
+        branch: {
+          ...baseContext.branch,
+          createdBy: 'user-2',
+          access: { allowedUsers: ['user-3'] },
+        },
+      }
+      expect(canPerformWorkflowAction(context, regularUser, 'deny')).toBe(false)
+    })
+  })
+
+  describe('system branch permissions', () => {
+    it('allows any user with general access on system branches', () => {
+      const context: BranchContext = {
+        ...baseContext,
+        branch: {
+          ...baseContext.branch,
+          createdBy: 'canopycms-system',
+          access: {},
+        },
+      }
+      expect(canPerformWorkflowAction(context, regularUser, 'allow')).toBe(true)
+    })
+
+    it('denies user without general access on system branches', () => {
+      const context: BranchContext = {
+        ...baseContext,
+        branch: {
+          ...baseContext.branch,
+          createdBy: 'canopycms-system',
+          access: { allowedUsers: ['user-2'] },
+        },
+      }
+      expect(canPerformWorkflowAction(context, regularUser, 'deny')).toBe(false)
+    })
+  })
+
+  describe('privileged user permissions', () => {
+    it('allows admins to perform workflow actions', () => {
+      const context: BranchContext = {
+        ...baseContext,
+        branch: { ...baseContext.branch, createdBy: 'user-2', access: {} },
+      }
+      expect(canPerformWorkflowAction(context, admin, 'deny')).toBe(true)
+    })
+
+    it('allows reviewers to perform workflow actions', () => {
+      const context: BranchContext = {
+        ...baseContext,
+        branch: { ...baseContext.branch, createdBy: 'user-2', access: {} },
+      }
+      expect(canPerformWorkflowAction(context, reviewer, 'deny')).toBe(true)
+    })
+  })
+
+  describe('combined scenarios', () => {
+    it('allows creator who is also in ACL', () => {
+      const context: BranchContext = {
+        ...baseContext,
+        branch: {
+          ...baseContext.branch,
+          createdBy: 'user-1',
+          access: { allowedUsers: ['user-1', 'user-2'] },
+        },
+      }
+      expect(canPerformWorkflowAction(context, regularUser, 'deny')).toBe(true)
+    })
+
+    it('denies user who lacks both creator and ACL access', () => {
+      const context: BranchContext = {
+        ...baseContext,
+        branch: {
+          ...baseContext.branch,
+          createdBy: 'user-2',
+          access: { allowedUsers: ['user-3'] },
+        },
+      }
+      expect(canPerformWorkflowAction(context, regularUser, 'deny')).toBe(false)
+    })
+  })
+})