canopycms 0.0.0 → 0.0.1

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

@@ -1,279 +0,0 @@
-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

@@ -1,12 +0,0 @@
-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

@@ -1,51 +0,0 @@
-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

@@ -1,38 +0,0 @@
-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

@@ -1,260 +0,0 @@
-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)
-    })
-  })
-})