canopycms 0.0.0

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

@@ -0,0 +1,142 @@
+import { describe, expect, it, vi } from 'vitest'
+
+import { createCheckBranchAccess, createCheckContentAccess, RESERVED_GROUPS } from '../'
+import { unsafeAsPermissionPath } from '../test-utils'
+import type { PathPermission } from '../../config'
+import { unsafeAsPhysicalPath } from '../../paths/test-utils'
+
+const branchContext = {
+  baseRoot: '/tmp/base',
+  branchRoot: '/tmp/base/feature-x',
+  branch: {
+    name: 'feature/x',
+    status: 'editing' as const,
+    access: {},
+    createdBy: 'u1',
+    createdAt: new Date().toISOString(),
+    updatedAt: new Date().toISOString(),
+  },
+}
+
+// Path permission rules (from .canopycms/permissions.json)
+// Rule with explicit constraints - only Admins group can edit admin paths
+const pathRules: PathPermission[] = [
+  {
+    path: unsafeAsPermissionPath('content/admin/**'),
+    edit: { allowedGroups: ['Admins'] },
+  },
+]
+
+describe('checkContentAccess', () => {
+  it('denies when branch ACL defaults to deny and no allowlist', async () => {
+    const mockLoadPermissions = vi.fn().mockResolvedValue(pathRules)
+    const checkContent = createCheckContentAccess({
+      checkBranchAccess: createCheckBranchAccess('deny'),
+      loadPathPermissions: mockLoadPermissions,
+      defaultPathAccess: 'allow',
+      mode: 'dev',
+    })
+
+    const res = await checkContent(
+      branchContext,
+      '/repo',
+      unsafeAsPhysicalPath('content/pages/foo.md'),
+      { type: 'authenticated', userId: 'u1', groups: [] },
+      'edit',
+    )
+
+    expect(mockLoadPermissions).toHaveBeenCalledWith('/repo', 'dev')
+    expect(res.allowed).toBe(false)
+    expect(res.branch.reason).toBe('no_acl')
+  })
+
+  it('allows Reviewer override even if branch default deny', async () => {
+    const mockLoadPermissions = vi.fn().mockResolvedValue(pathRules)
+    const checkContent = createCheckContentAccess({
+      checkBranchAccess: createCheckBranchAccess('deny'),
+      loadPathPermissions: mockLoadPermissions,
+      defaultPathAccess: 'allow',
+      mode: 'dev',
+    })
+
+    const res = await checkContent(
+      branchContext,
+      '/repo',
+      unsafeAsPhysicalPath('content/pages/foo.md'),
+      {
+        type: 'authenticated',
+        userId: 'u1',
+        groups: [RESERVED_GROUPS.REVIEWERS],
+      },
+      'edit',
+    )
+
+    expect(res.allowed).toBe(true)
+    expect(res.branch.reason).toBe('privileged')
+  })
+
+  it('denies path access for regular users hitting admin paths', async () => {
+    const mockLoadPermissions = vi.fn().mockResolvedValue(pathRules)
+    const checkContent = createCheckContentAccess({
+      checkBranchAccess: createCheckBranchAccess('allow'),
+      loadPathPermissions: mockLoadPermissions,
+      defaultPathAccess: 'allow',
+      mode: 'dev',
+    })
+
+    const res = await checkContent(
+      branchContext,
+      '/repo',
+      unsafeAsPhysicalPath('content/admin/secret.md'),
+      { type: 'authenticated', userId: 'u1', groups: [] },
+      'edit',
+    )
+
+    expect(res.allowed).toBe(false)
+    expect(res.path.allowed).toBe(false)
+  })
+
+  it('respects defaultPathAccess when no rule matches', async () => {
+    const mockLoadPermissions = vi.fn().mockResolvedValue([])
+    const checkContent = createCheckContentAccess({
+      checkBranchAccess: createCheckBranchAccess('allow'),
+      loadPathPermissions: mockLoadPermissions,
+      defaultPathAccess: 'deny',
+      mode: 'dev',
+    })
+
+    const res = await checkContent(
+      branchContext,
+      '/repo',
+      unsafeAsPhysicalPath('content/open/page.md'),
+      { type: 'authenticated', userId: 'u1', groups: [] },
+      'edit',
+    )
+
+    expect(res.allowed).toBe(false)
+    expect(res.path.allowed).toBe(false)
+    expect(res.path.reason).toBe('no_rule_match')
+  })
+
+  it('allows access when defaultPathAccess is allow and no rules match', async () => {
+    const mockLoadPermissions = vi.fn().mockResolvedValue([])
+    const checkContent = createCheckContentAccess({
+      checkBranchAccess: createCheckBranchAccess('allow'),
+      loadPathPermissions: mockLoadPermissions,
+      defaultPathAccess: 'allow',
+      mode: 'dev',
+    })
+
+    const res = await checkContent(
+      branchContext,
+      '/repo',
+      unsafeAsPhysicalPath('content/open/page.md'),
+      { type: 'authenticated', userId: 'u1', groups: [] },
+      'edit',
+    )
+
+    expect(res.allowed).toBe(true)
+    expect(res.path.allowed).toBe(true)
+    expect(res.path.reason).toBe('no_rule_match')
+  })
+})

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

@@ -0,0 +1,133 @@
+import { describe, expect, it } from 'vitest'
+
+import { checkPathAccess, RESERVED_GROUPS } from '../'
+import { unsafeAsPermissionPath } from '../test-utils'
+import type { PathPermission } from '../../config'
+import type { CanopyUser } from '../../user'
+import { unsafeAsPhysicalPath } from '../../paths/test-utils'
+
+// Path permission rules (previously from config.pathPermissions, now from .canopycms/permissions.json)
+const rules: PathPermission[] = [
+  { path: unsafeAsPermissionPath('content/admin/**'), edit: {} },
+  {
+    path: unsafeAsPermissionPath('content/partners/**'),
+    edit: { allowedGroups: ['partner-org'] },
+  },
+  {
+    path: unsafeAsPermissionPath('content/restricted/**'),
+    edit: { allowedUsers: ['user-a'] },
+  },
+]
+
+// Helper to create authenticated users
+const createUser = (userId: string, groups: string[] = []): CanopyUser => ({
+  type: 'authenticated',
+  userId,
+  groups,
+})
+
+describe('path permissions', () => {
+  it('allows admin', () => {
+    const result = checkPathAccess({
+      rules,
+      relativePath: unsafeAsPhysicalPath('content/admin/secret.md'),
+      user: createUser('any', [RESERVED_GROUPS.ADMINS]),
+      defaultAccess: 'deny',
+      level: 'edit',
+    })
+    expect(result.allowed).toBe(true)
+    expect(result.reason).toBe('admin')
+  })
+
+  it('allows user when edit rule has no constraints', () => {
+    const result = checkPathAccess({
+      rules,
+      relativePath: unsafeAsPhysicalPath('content/admin/secret.md'),
+      user: createUser('any', []),
+      defaultAccess: 'deny',
+      level: 'edit',
+    })
+    expect(result.allowed).toBe(true)
+  })
+
+  it('denies when user does not match allowedUsers or allowedGroups', () => {
+    const result = checkPathAccess({
+      rules,
+      relativePath: unsafeAsPhysicalPath('content/restricted/secret.md'),
+      user: createUser('user-b', ['partner-org']),
+      defaultAccess: 'deny',
+      level: 'edit',
+    })
+    expect(result.allowed).toBe(false)
+  })
+
+  it('allows group membership', () => {
+    const result = checkPathAccess({
+      rules,
+      relativePath: unsafeAsPhysicalPath('content/partners/page.md'),
+      user: createUser('user-x', ['partner-org']),
+      defaultAccess: 'deny',
+      level: 'edit',
+    })
+    expect(result.allowed).toBe(true)
+  })
+
+  it('denies missing group membership', () => {
+    const result = checkPathAccess({
+      rules,
+      relativePath: unsafeAsPhysicalPath('content/partners/page.md'),
+      user: createUser('user-x', ['other-org']),
+      defaultAccess: 'deny',
+      level: 'edit',
+    })
+    expect(result.allowed).toBe(false)
+  })
+
+  it('defaults to allow when no rule matches', () => {
+    const result = checkPathAccess({
+      rules,
+      relativePath: unsafeAsPhysicalPath('content/open/page.md'),
+      user: createUser('user-x'),
+      defaultAccess: 'allow',
+      level: 'edit',
+    })
+    expect(result.allowed).toBe(true)
+  })
+
+  it('uses defaultAccess=allow when no rule matches and explicitly set', () => {
+    const result = checkPathAccess({
+      rules,
+      relativePath: unsafeAsPhysicalPath('content/open/page.md'),
+      user: createUser('user-x'),
+      defaultAccess: 'allow',
+      level: 'edit',
+    })
+    expect(result.allowed).toBe(true)
+    expect(result.reason).toBe('no_rule_match')
+  })
+
+  it('uses defaultAccess=deny when no rule matches', () => {
+    const result = checkPathAccess({
+      rules,
+      relativePath: unsafeAsPhysicalPath('content/open/page.md'),
+      user: createUser('user-x'),
+      defaultAccess: 'deny',
+      level: 'edit',
+    })
+    expect(result.allowed).toBe(false)
+    expect(result.reason).toBe('no_rule_match')
+  })
+
+  it('applies matching rule regardless of defaultAccess', () => {
+    // Even with defaultAccess=allow, a matching rule that denies should deny
+    const result = checkPathAccess({
+      rules,
+      relativePath: unsafeAsPhysicalPath('content/restricted/secret.md'),
+      user: createUser('regular-user', []),
+      defaultAccess: 'allow',
+      level: 'edit',
+    })
+    expect(result.allowed).toBe(false)
+    expect(result.reason).toBe('denied_by_rule')
+  })
+})

package/src/authorization/__tests__/permissions-loader.test.ts

@@ -0,0 +1,200 @@
+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 { loadPathPermissions, savePathPermissions, ensurePermissionsFile } from '../permissions'
+import { unsafeAsPermissionPath } from '../test-utils'
+import { mockConsole } from '../../test-utils/console-spy.js'
+
+describe('permissions loader', () => {
+  let testRoot: string
+
+  beforeEach(async () => {
+    testRoot = await fs.mkdtemp(path.join(os.tmpdir(), 'canopy-perms-test-'))
+  })
+
+  afterEach(async () => {
+    await fs.rm(testRoot, { recursive: true, force: true })
+  })
+
+  describe('loadPathPermissions', () => {
+    it('loads from file when it exists', async () => {
+      // Create permissions file
+      const canopyDir = testRoot
+      await fs.mkdir(canopyDir, { recursive: true })
+      await fs.writeFile(
+        path.join(canopyDir, 'permissions.json'),
+        JSON.stringify({
+          version: 1,
+          updatedAt: new Date().toISOString(),
+          updatedBy: 'admin-user',
+          pathPermissions: [
+            {
+              path: 'content/admin/**',
+              edit: {},
+            },
+            {
+              path: 'content/partners/**',
+              edit: { allowedGroups: ['partner-org'] },
+            },
+          ],
+        }),
+        'utf-8',
+      )
+
+      const permissions = await loadPathPermissions(testRoot, 'prod')
+
+      expect(permissions).toHaveLength(2)
+      expect(permissions[0]).toEqual({
+        path: 'content/admin/**',
+        edit: {},
+      })
+      expect(permissions[1]).toEqual({
+        path: 'content/partners/**',
+        edit: { allowedGroups: ['partner-org'] },
+      })
+    })
+
+    it('returns empty array when file does not exist', async () => {
+      const permissions = await loadPathPermissions(testRoot, 'prod')
+      expect(permissions).toEqual([])
+    })
+
+    it('throws error on invalid JSON', async () => {
+      const consoleSpy = mockConsole()
+
+      // Create invalid permissions file in new location
+      const canopyDir = testRoot
+      await fs.mkdir(canopyDir, { recursive: true })
+      await fs.writeFile(path.join(canopyDir, 'permissions.json'), 'invalid json', 'utf-8')
+
+      await expect(loadPathPermissions(testRoot, 'prod')).rejects.toThrow(
+        'Invalid permissions file',
+      )
+      expect(consoleSpy).toHaveErrored('Failed to parse permissions file')
+      consoleSpy.restore()
+    })
+
+    it('throws error on invalid schema', async () => {
+      const consoleSpy = mockConsole()
+
+      // Create file with wrong version in new location
+      const canopyDir = testRoot
+      await fs.mkdir(canopyDir, { recursive: true })
+      await fs.writeFile(
+        path.join(canopyDir, 'permissions.json'),
+        JSON.stringify({
+          version: 2, // Wrong version
+          updatedAt: new Date().toISOString(),
+          updatedBy: 'admin',
+          pathPermissions: [],
+        }),
+        'utf-8',
+      )
+
+      await expect(loadPathPermissions(testRoot, 'prod')).rejects.toThrow(
+        'Invalid permissions file',
+      )
+      expect(consoleSpy).toHaveErrored('Failed to parse permissions file')
+      consoleSpy.restore()
+    })
+  })
+
+  describe('savePathPermissions', () => {
+    it('saves permissions to file', async () => {
+      const permissions = [
+        {
+          path: unsafeAsPermissionPath('content/admin/**'),
+          edit: {},
+        },
+        {
+          path: unsafeAsPermissionPath('content/users/**'),
+          edit: { allowedUsers: ['user-1', 'user-2'] },
+        },
+      ]
+
+      await savePathPermissions(testRoot, permissions, 'admin-user', 'prod')
+
+      const filePath = path.join(testRoot, 'permissions.json')
+      const fileContent = await fs.readFile(filePath, 'utf-8')
+      const parsed = JSON.parse(fileContent)
+
+      expect(parsed.version).toBe(1)
+      expect(parsed.updatedBy).toBe('admin-user')
+      expect(parsed.updatedAt).toBeTruthy()
+      expect(parsed.pathPermissions).toHaveLength(2)
+      expect(parsed.pathPermissions[0]).toEqual({
+        path: 'content/admin/**',
+        edit: {},
+      })
+    })
+
+    it('validates permissions before saving', async () => {
+      const invalidPermissions: any = [
+        {
+          path: '', // Invalid empty path
+          edit: {},
+        },
+      ]
+
+      await expect(
+        savePathPermissions(testRoot, invalidPermissions, 'admin', 'prod'),
+      ).rejects.toThrow()
+    })
+
+    it('overwrites existing file', async () => {
+      const firstPermissions = [
+        {
+          path: unsafeAsPermissionPath('content/first/**'),
+          edit: { allowedUsers: ['user-1'] },
+        },
+      ]
+      await savePathPermissions(testRoot, firstPermissions, 'admin-1', 'prod')
+
+      const secondPermissions = [
+        {
+          path: unsafeAsPermissionPath('content/second/**'),
+          edit: { allowedUsers: ['user-2'] },
+        },
+      ]
+      await savePathPermissions(testRoot, secondPermissions, 'admin-2', 'prod')
+
+      const loaded = await loadPathPermissions(testRoot, 'prod')
+
+      expect(loaded).toHaveLength(1)
+      expect(loaded[0].path).toBe('content/second/**')
+    })
+  })
+
+  describe('ensurePermissionsFile', () => {
+    it('creates default file if it does not exist', async () => {
+      await ensurePermissionsFile(testRoot, 'admin-user', 'prod')
+
+      const filePath = path.join(testRoot, 'permissions.json')
+      const fileContent = await fs.readFile(filePath, 'utf-8')
+      const parsed = JSON.parse(fileContent)
+
+      expect(parsed.version).toBe(1)
+      expect(parsed.updatedBy).toBe('admin-user')
+      expect(parsed.pathPermissions).toEqual([])
+    })
+
+    it('does nothing if file already exists', async () => {
+      const existingPermissions = [
+        {
+          path: unsafeAsPermissionPath('content/**'),
+          edit: { allowedUsers: ['existing'] },
+        },
+      ]
+      await savePathPermissions(testRoot, existingPermissions, 'original-admin', 'prod')
+
+      await ensurePermissionsFile(testRoot, 'new-admin', 'prod')
+
+      const loaded = await loadPathPermissions(testRoot, 'prod')
+
+      // Original permissions should still be there
+      expect(loaded).toHaveLength(1)
+      expect(loaded[0].path).toBe('content/**')
+    })
+  })
+})

package/src/authorization/branch.ts

@@ -0,0 +1,94 @@
+/**
+ * Branch-level authorization
+ *
+ * Handles checking if a user can access a branch based on ACLs.
+ */
+
+import type { BranchContext } from '../types'
+import type { DefaultBranchAccess } from '../config'
+import { isAdmin, isReviewer } from './helpers'
+import type { CanopyUser } from '../user'
+import type { BranchAccessResult } from './types'
+
+/**
+ * Check if user has access to a branch with explicit default behavior.
+ */
+export function checkBranchAccessWithDefault(
+  context: BranchContext,
+  user: CanopyUser,
+  defaultAccess: DefaultBranchAccess = 'deny',
+): BranchAccessResult {
+  // Admins and Reviewers have full branch access
+  if (isAdmin(user.groups) || isReviewer(user.groups)) {
+    return { allowed: true, reason: 'privileged' }
+  }
+
+  const access = context.branch.access
+  const hasUserConstraint = !!access.allowedUsers?.length
+  const hasGroupConstraint = !!access.allowedGroups?.length
+  const managerOrAdminAllowed = access.managerOrAdminAllowed ?? false
+
+  if (!hasUserConstraint && !hasGroupConstraint) {
+    if (managerOrAdminAllowed) {
+      return { allowed: false, reason: 'denied_by_acl' }
+    }
+    const allowed = defaultAccess === 'allow'
+    return { allowed, reason: 'no_acl' }
+  }
+
+  const userAllowed = hasUserConstraint && access.allowedUsers?.includes(user.userId)
+  const groupAllowed =
+    hasGroupConstraint && user.groups?.some((g) => access.allowedGroups?.includes(g))
+
+  const allowed = Boolean(userAllowed || groupAllowed)
+  return { allowed, reason: allowed ? 'allowed_by_acl' : 'denied_by_acl' }
+}
+
+/**
+ * Create a branch access checker with bound default access.
+ */
+export function createCheckBranchAccess(defaultAccess: DefaultBranchAccess = 'deny') {
+  return (context: BranchContext, user: CanopyUser): BranchAccessResult =>
+    checkBranchAccessWithDefault(context, user, defaultAccess)
+}
+
+/**
+ * Check if user can perform workflow actions (submit/withdraw) on a branch.
+ * Allowed if: user is creator OR user has ACL access OR (system branch AND user has general access).
+ *
+ * This implements a hybrid permission model:
+ * - Branch creators can always submit/withdraw their branches
+ * - Users explicitly listed in branch ACLs can also submit/withdraw
+ * - For system branches (createdBy: 'canopycms-system'), anyone with general access can submit/withdraw
+ * - Admins and Reviewers always have access (via checkBranchAccess)
+ */
+export function canPerformWorkflowAction(
+  context: BranchContext,
+  user: CanopyUser,
+  defaultAccess: DefaultBranchAccess = 'deny',
+): boolean {
+  // Check if user has general branch access (handles admins, reviewers, ACLs)
+  const accessResult = checkBranchAccessWithDefault(context, user, defaultAccess)
+
+  // If user doesn't have basic branch access, deny immediately
+  if (!accessResult.allowed) {
+    return false
+  }
+
+  // Check if user is the branch creator
+  const userIsCreator = context.branch.createdBy === user.userId
+
+  // Check if this is a system-created branch
+  const isSystemBranch = context.branch.createdBy === 'canopycms-system'
+
+  // Allow if:
+  // 1. User is the creator, OR
+  // 2. User has ACL access (reason: 'privileged' or 'allowed_by_acl'), OR
+  // 3. System branch with general access
+  return (
+    userIsCreator ||
+    accessResult.reason === 'privileged' ||
+    accessResult.reason === 'allowed_by_acl' ||
+    (isSystemBranch && accessResult.allowed)
+  )
+}

package/src/authorization/content.ts

@@ -0,0 +1,93 @@
+/**
+ * Content access authorization
+ *
+ * This is the main entry point for authorization checks. It combines
+ * branch-level and path-level access checks into a single API.
+ *
+ * Usage:
+ * ```ts
+ * import { checkContentAccess } from './authorization'
+ *
+ * const result = await checkContentAccess(deps, context, branchRoot, 'content/posts/my-post.mdx', user, 'edit')
+ * if (result.allowed) {
+ *   // User can edit the file
+ * }
+ * ```
+ */
+
+import type { BranchContext } from '../types'
+import type { PermissionLevel } from '../config'
+import type { CanopyUser } from '../user'
+import { operatingStrategy } from '../operating-mode'
+import { createCheckPathAccess } from './path'
+import type { ContentAccessResult, ContentAccessDeps } from './types'
+import type { PhysicalPath } from '../paths/types'
+
+/**
+ * Check content access by evaluating both branch and path permissions.
+ * Path permissions are loaded dynamically from the branch root.
+ *
+ * @param deps - Dependencies including branch access checker and path permissions loader
+ * @param context - Branch context containing branch metadata
+ * @param branchRoot - Root directory of the branch
+ * @param relativePath - Physical path relative to branch root (with embedded IDs)
+ * @param user - User to check access for
+ * @param level - Permission level to check ('read', 'edit', or 'review')
+ */
+export async function checkContentAccess(
+  deps: ContentAccessDeps,
+  context: BranchContext,
+  branchRoot: string,
+  relativePath: PhysicalPath,
+  user: CanopyUser,
+  level: PermissionLevel,
+): Promise<ContentAccessResult> {
+  const branch = deps.checkBranchAccess(context, user)
+
+  // Load permissions from appropriate location based on operating mode
+  // Modes with separate settings branch: load from settings branch
+  // Other modes: load from the current branch
+  let permissionsRoot = branchRoot
+  const mode = deps.mode
+  const strategy = operatingStrategy(mode)
+
+  if (strategy.usesSeparateSettingsBranch()) {
+    if (!deps.getSettingsBranchRoot) {
+      throw new Error(
+        'getSettingsBranchRoot is required for modes that use separate settings branch',
+      )
+    }
+    // getSettingsBranchRoot must throw if it cannot load the settings branch
+    // This ensures we never fall back to reading permissions from the current branch
+    permissionsRoot = await deps.getSettingsBranchRoot()
+  }
+
+  const rules = await deps.loadPathPermissions(permissionsRoot, deps.mode)
+  const pathChecker = createCheckPathAccess(rules, deps.defaultPathAccess)
+
+  const path = pathChecker({
+    relativePath,
+    user,
+    level,
+  })
+
+  return {
+    allowed: branch.allowed && path.allowed,
+    branch,
+    path,
+  }
+}
+
+/**
+ * Create a content access checker with bound dependencies.
+ */
+export function createCheckContentAccess(deps: ContentAccessDeps) {
+  return (
+    context: BranchContext,
+    branchRoot: string,
+    relativePath: PhysicalPath,
+    user: CanopyUser,
+    level: PermissionLevel,
+  ): Promise<ContentAccessResult> =>
+    checkContentAccess(deps, context, branchRoot, relativePath, user, level)
+}

package/src/authorization/groups/index.ts

@@ -0,0 +1,11 @@
+/**
+ * Groups module exports
+ */
+
+export {
+  GroupsFileSchema,
+  createDefaultGroupsFile,
+  type GroupsFile,
+  type InternalGroup,
+} from './schema'
+export { loadGroupsFile, loadInternalGroups, saveInternalGroups } from './loader'