canopycms 0.0.0 → 0.0.2

package/src/authorization/groups/loader.ts

@@ -1,127 +0,0 @@
-/**
- * Groups file loader
- *
- * Handles loading and saving internal groups from the filesystem.
- */
-
-import { promises as fs } from 'node:fs'
-import { join } from 'node:path'
-import type { CanopyUserId } from '../../types'
-import { GroupsFileSchema, type InternalGroup, type GroupsFile } from './schema'
-import type { OperatingMode } from '../../operating-mode'
-import { operatingStrategy } from '../../operating-mode'
-import { RESERVED_GROUPS } from '../helpers'
-
-/**
- * Get the appropriate groups file path based on mode
- */
-function getGroupsFilePath(branchRoot: string, mode: OperatingMode): string {
-  return operatingStrategy(mode).getGroupsFilePath(branchRoot)
-}
-
-/**
- * Load full groups file (for version checking)
- * Returns null if file doesn't exist.
- */
-export async function loadGroupsFile(
-  branchRoot: string,
-  mode: OperatingMode,
-): Promise<GroupsFile | null> {
-  const groupsPath = getGroupsFilePath(branchRoot, mode)
-
-  try {
-    const content = await fs.readFile(groupsPath, 'utf-8')
-    const parsed = JSON.parse(content)
-    const validated = GroupsFileSchema.parse(parsed)
-    return validated
-  } catch (error) {
-    // File doesn't exist
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
-      return null
-    }
-    throw error
-  }
-}
-
-/**
- * Load internal groups from .canopycms/groups.json (or .local.json in dev mode)
- * Ensures Admins and Reviewers groups always exist, adding them dynamically if not present.
- * If Admins group exists in file, merges with bootstrap admin IDs.
- */
-export async function loadInternalGroups(
-  branchRoot: string,
-  mode: OperatingMode,
-  bootstrapAdminIds: Set<string> = new Set(),
-): Promise<InternalGroup[]> {
-  const file = await loadGroupsFile(branchRoot, mode)
-  const fileGroups = file?.groups ?? []
-
-  // Find existing Admins and Reviewers groups
-  let adminsGroup = fileGroups.find((g) => g.id === RESERVED_GROUPS.ADMINS)
-  let reviewersGroup = fileGroups.find((g) => g.id === RESERVED_GROUPS.REVIEWERS)
-
-  // Ensure Admins group exists and includes bootstrap admins
-  if (adminsGroup) {
-    // Merge bootstrap admin IDs with existing members
-    const allAdmins = new Set([...adminsGroup.members, ...bootstrapAdminIds])
-    adminsGroup = {
-      ...adminsGroup,
-      members: Array.from(allAdmins),
-    }
-  } else {
-    // Create Admins group with bootstrap admins
-    adminsGroup = {
-      id: RESERVED_GROUPS.ADMINS,
-      name: RESERVED_GROUPS.ADMINS,
-      description: 'Full access to all CMS operations',
-      members: Array.from(bootstrapAdminIds),
-    }
-  }
-
-  // Ensure Reviewers group exists
-  if (!reviewersGroup) {
-    reviewersGroup = {
-      id: RESERVED_GROUPS.REVIEWERS,
-      name: RESERVED_GROUPS.REVIEWERS,
-      description: 'Can review branches, request changes, approve PRs',
-      members: [],
-    }
-  }
-
-  // Return all groups: reserved groups first, then other groups
-  const otherGroups = fileGroups.filter(
-    (g) => g.id !== RESERVED_GROUPS.ADMINS && g.id !== RESERVED_GROUPS.REVIEWERS,
-  )
-
-  return [adminsGroup, reviewersGroup, ...otherGroups]
-}
-
-/**
- * Save internal groups to .canopycms/groups.json (or .local.json in dev mode)
- */
-export async function saveInternalGroups(
-  branchRoot: string,
-  groups: InternalGroup[],
-  updatedBy: CanopyUserId,
-  mode: OperatingMode,
-  contentVersion?: number,
-): Promise<void> {
-  const groupsPath = getGroupsFilePath(branchRoot, mode)
-  const groupsDir = join(groupsPath, '..')
-
-  // Ensure parent directory exists (e.g., .canopy-meta or .canopycms)
-  await fs.mkdir(groupsDir, { recursive: true })
-
-  const groupsFile: GroupsFile = {
-    version: 1,
-    contentVersion: contentVersion ?? 1,
-    updatedAt: new Date().toISOString(),
-    updatedBy,
-    groups,
-  }
-
-  // Validate before writing
-  GroupsFileSchema.parse(groupsFile)
-
-  await fs.writeFile(groupsPath, JSON.stringify(groupsFile, null, 2), 'utf-8')
-}

package/src/authorization/groups/schema.ts

@@ -1,48 +0,0 @@
-/**
- * Schema for groups.json file
- */
-
-import { z } from 'zod'
-import type { CanopyUserId, CanopyGroupId } from '../../types'
-
-/**
- * Schema for .canopycms/groups.json
- */
-export const GroupsFileSchema = z.object({
-  version: z.literal(1),
-  contentVersion: z.number().optional(), // For optimistic locking
-  updatedAt: z.string().datetime(),
-  updatedBy: z.string() as z.ZodType<CanopyUserId>,
-  groups: z.array(
-    z.object({
-      id: z.string() as z.ZodType<CanopyGroupId>,
-      name: z.string().min(1),
-      description: z.string().optional(),
-      members: z.array(z.string() as z.ZodType<CanopyUserId>),
-    }),
-  ),
-})
-
-export type GroupsFile = z.infer<typeof GroupsFileSchema>
-
-/**
- * Internal group representation
- */
-export interface InternalGroup {
-  id: CanopyGroupId
-  name: string
-  description?: string
-  members: CanopyUserId[]
-}
-
-/**
- * Default groups file
- */
-export function createDefaultGroupsFile(userId: CanopyUserId): GroupsFile {
-  return {
-    version: 1,
-    updatedAt: new Date().toISOString(),
-    updatedBy: userId,
-    groups: [],
-  }
-}

package/src/authorization/helpers.ts

@@ -1,48 +0,0 @@
-/**
- * Authorization helper functions
- *
- * Simple utilities for checking user roles and permissions.
- */
-
-/**
- * Reserved groups for CanopyCMS permission system.
- *
- * These groups have special meaning and cannot be deleted or renamed.
- * - Admins: Full access to all CMS operations
- * - Reviewers: Can review branches, request changes, approve PRs
- */
-export const RESERVED_GROUPS = {
-  ADMINS: 'Admins',
-  REVIEWERS: 'Reviewers',
-} as const
-
-export type ReservedGroupId = (typeof RESERVED_GROUPS)[keyof typeof RESERVED_GROUPS]
-
-/**
- * Check if a group ID is a reserved group
- */
-export function isReservedGroup(groupId: string): groupId is ReservedGroupId {
-  return Object.values(RESERVED_GROUPS).includes(groupId as ReservedGroupId)
-}
-
-/**
- * Check if user is in the Admins group
- */
-export function isAdmin(groups: readonly string[] | undefined): boolean {
-  return groups?.includes(RESERVED_GROUPS.ADMINS) ?? false
-}
-
-/**
- * Check if user is in the Reviewers group (or is an Admin, since Admins can do everything)
- */
-export function isReviewer(groups: readonly string[] | undefined): boolean {
-  return isAdmin(groups) || (groups?.includes(RESERVED_GROUPS.REVIEWERS) ?? false)
-}
-
-/**
- * Check if user has privileged access (Admin or Reviewer)
- * Used for operations that require elevated permissions but not full admin
- */
-export function isPrivileged(groups: readonly string[] | undefined): boolean {
-  return isReviewer(groups)
-}

package/src/authorization/index.ts

@@ -1,84 +0,0 @@
-/**
- * Authorization module for CanopyCMS
- *
- * This module provides a unified API for checking user access to branches and content.
- *
- * ## Quick Start
- *
- * For most use cases, use `checkContentAccess` which handles both branch and path permissions:
- *
- * ```ts
- * import { checkContentAccess } from './authorization'
- *
- * const result = await checkContentAccess(deps, context, branchRoot, 'content/posts/post.mdx', user, 'edit')
- * if (result.allowed) {
- *   // User can edit the file
- * }
- * ```
- *
- * ## Module Structure
- *
- * - `content.ts` - Combined branch + path access (main entry point)
- * - `branch.ts` - Branch-level access control
- * - `path.ts` - Path-level permissions
- * - `helpers.ts` - Utility functions (isAdmin, isReviewer, etc.)
- * - `permissions/` - Permissions file schema and loader
- * - `groups/` - Groups file schema and loader
- */
-
-// Types
-export type {
-  BranchAccessResult,
-  PathPermissionResult,
-  ContentAccessResult,
-  ContentAccessDeps,
-  PermissionPath,
-} from './types'
-
-// Validation
-export { parsePermissionPath } from './validation'
-
-// Main content access (recommended for most cases)
-export { checkContentAccess, createCheckContentAccess } from './content'
-
-// Branch-level access
-export {
-  checkBranchAccessWithDefault,
-  createCheckBranchAccess,
-  canPerformWorkflowAction,
-} from './branch'
-
-// Path-level access
-export { checkPathAccess, createCheckPathAccess } from './path'
-
-// Helper functions
-export {
-  RESERVED_GROUPS,
-  type ReservedGroupId,
-  isReservedGroup,
-  isAdmin,
-  isReviewer,
-  isPrivileged,
-} from './helpers'
-
-// Permissions file handling
-export {
-  PermissionsFileSchema,
-  createDefaultPermissionsFile,
-  type PermissionsFile,
-  loadPermissionsFile,
-  loadPathPermissions,
-  savePathPermissions,
-  ensurePermissionsFile,
-} from './permissions'
-
-// Groups file handling
-export {
-  GroupsFileSchema,
-  createDefaultGroupsFile,
-  type GroupsFile,
-  type InternalGroup,
-  loadGroupsFile,
-  loadInternalGroups,
-  saveInternalGroups,
-} from './groups'

package/src/authorization/path.ts

@@ -1,112 +0,0 @@
-/**
- * Path-level authorization
- *
- * Handles checking if a user can access a specific path based on permission rules.
- */
-
-import path from 'node:path'
-
-import { minimatch } from 'minimatch'
-
-import type {
-  PathPermission,
-  DefaultPathAccess,
-  PermissionLevel,
-  PermissionTarget,
-} from '../config'
-import { isAdmin } from './helpers'
-import type { CanopyUser } from '../user'
-import type { PathPermissionResult } from './types'
-import type { PhysicalPath } from '../paths/types'
-
-/**
- * Normalize a path for consistent matching
- */
-function normalize(p: PhysicalPath): PhysicalPath {
-  const normalized = (p as string).split(path.sep).join('/')
-  return normalized.replace(/^\.?\/*/, '') as PhysicalPath
-}
-
-/**
- * Check if a path matches a permission rule
- */
-function matchesRule(rule: PathPermission, relativePath: PhysicalPath): boolean {
-  return minimatch(relativePath as string, rule.path, { dot: true })
-}
-
-/**
- * Check if user matches a permission target
- */
-function isAllowedByTarget(target: PermissionTarget, user: CanopyUser): boolean {
-  const hasUserConstraint = !!target.allowedUsers?.length
-  const hasGroupConstraint = !!target.allowedGroups?.length
-
-  // No constraints means allowed (rule applies to everyone)
-  if (!hasUserConstraint && !hasGroupConstraint) {
-    return true
-  }
-
-  const matchesUser = hasUserConstraint && target.allowedUsers?.includes(user.userId)
-  const matchesGroup =
-    hasGroupConstraint && user.groups?.some((gid) => target.allowedGroups?.includes(gid))
-
-  return Boolean(matchesUser || matchesGroup)
-}
-
-/**
- * Evaluate access for a relative path against config-defined rules.
- * Uses defaultAccess when no rule matches. First matching rule wins.
- */
-export function checkPathAccess({
-  rules,
-  relativePath,
-  user,
-  defaultAccess,
-  level,
-}: {
-  rules: PathPermission[]
-  relativePath: PhysicalPath
-  user: CanopyUser
-  defaultAccess: DefaultPathAccess
-  level: PermissionLevel
-}): PathPermissionResult {
-  const normalizedPath = normalize(relativePath)
-
-  // Only Admins bypass all path permissions
-  if (isAdmin(user.groups)) {
-    return { allowed: true, reason: 'admin' }
-  }
-
-  for (const rule of rules) {
-    if (!matchesRule(rule, normalizedPath)) {
-      continue
-    }
-
-    // Get the permission target for this level
-    const target = rule[level]
-    if (!target) {
-      // No permissions defined for this level on this rule, continue to next rule
-      continue
-    }
-
-    const allowed = isAllowedByTarget(target, user)
-    return {
-      allowed,
-      matchedRule: rule,
-      reason: allowed ? 'allowed_by_rule' : 'denied_by_rule',
-    }
-  }
-
-  return { allowed: defaultAccess === 'allow', reason: 'no_rule_match' }
-}
-
-/**
- * Factory to bind rules and defaultAccess once.
- */
-export function createCheckPathAccess(rules: PathPermission[], defaultAccess: DefaultPathAccess) {
-  return (input: {
-    relativePath: PhysicalPath
-    user: CanopyUser
-    level: PermissionLevel
-  }): PathPermissionResult => checkPathAccess({ ...input, rules, defaultAccess })
-}

package/src/authorization/permissions/index.ts

@@ -1,11 +0,0 @@
-/**
- * Permissions module exports
- */
-
-export { PermissionsFileSchema, createDefaultPermissionsFile, type PermissionsFile } from './schema'
-export {
-  loadPermissionsFile,
-  loadPathPermissions,
-  savePathPermissions,
-  ensurePermissionsFile,
-} from './loader'

package/src/authorization/permissions/loader.ts

@@ -1,116 +0,0 @@
-/**
- * Permissions file loader
- *
- * Handles loading and saving path permissions from the filesystem.
- */
-
-import fs from 'node:fs/promises'
-import path from 'node:path'
-import type { PathPermission } from '../../config'
-import type { PermissionsFile } from './schema'
-import { PermissionsFileSchema } from './schema'
-import type { OperatingMode } from '../../operating-mode'
-import { operatingStrategy } from '../../operating-mode'
-
-/**
- * Get the appropriate permissions file path based on mode
- */
-function getPermissionsFilePath(repoRoot: string, mode: OperatingMode): string {
-  return operatingStrategy(mode).getPermissionsFilePath(repoRoot)
-}
-
-/**
- * Load full permissions file (for version checking)
- * Returns null if file doesn't exist.
- *
- * @param repoRoot - Repository root directory
- * @param mode - Operating mode (determines file path)
- */
-export async function loadPermissionsFile(
-  repoRoot: string,
-  mode: OperatingMode,
-): Promise<PermissionsFile | null> {
-  const permissionsPath = getPermissionsFilePath(repoRoot, mode)
-
-  try {
-    const fileContent = await fs.readFile(permissionsPath, 'utf-8')
-    const parsed = JSON.parse(fileContent)
-    const validated = PermissionsFileSchema.parse(parsed)
-    return validated
-  } catch (error) {
-    // File doesn't exist
-    if ((error as NodeJS.ErrnoException).code === 'ENOENT') {
-      return null
-    }
-
-    // Parse/validation error - this is more serious
-    console.error('CanopyCMS: Failed to parse permissions file', error)
-    throw new Error(
-      `Invalid permissions file: ${error instanceof Error ? error.message : 'unknown error'}`,
-    )
-  }
-}
-
-/**
- * Load path permissions from .canopycms/permissions.json (or .local.json in dev mode)
- * Returns empty array if file doesn't exist (no restrictions).
- *
- * @param repoRoot - Repository root directory
- * @param mode - Operating mode (determines file path)
- */
-export async function loadPathPermissions(
-  repoRoot: string,
-  mode: OperatingMode,
-): Promise<PathPermission[]> {
-  const file = await loadPermissionsFile(repoRoot, mode)
-  return file?.pathPermissions ?? []
-}
-
-/**
- * Save path permissions to .canopycms/permissions.json (or .local.json in dev mode)
- */
-export async function savePathPermissions(
-  repoRoot: string,
-  permissions: PathPermission[],
-  updatedBy: string,
-  mode: OperatingMode,
-  contentVersion?: number,
-): Promise<void> {
-  const permissionsPath = getPermissionsFilePath(repoRoot, mode)
-  const canopyDir = path.dirname(permissionsPath)
-
-  // Ensure .canopycms directory exists
-  await fs.mkdir(canopyDir, { recursive: true })
-
-  const permissionsFile: PermissionsFile = {
-    version: 1,
-    contentVersion: contentVersion ?? 1,
-    updatedAt: new Date().toISOString(),
-    updatedBy,
-    pathPermissions: permissions,
-  }
-
-  // Validate before writing
-  PermissionsFileSchema.parse(permissionsFile)
-
-  await fs.writeFile(permissionsPath, JSON.stringify(permissionsFile, null, 2), 'utf-8')
-}
-
-/**
- * Initialize permissions file if it doesn't exist
- */
-export async function ensurePermissionsFile(
-  repoRoot: string,
-  userId: string,
-  mode: OperatingMode,
-): Promise<void> {
-  const permissionsPath = getPermissionsFilePath(repoRoot, mode)
-
-  try {
-    await fs.access(permissionsPath)
-    // File exists, nothing to do
-  } catch {
-    // File doesn't exist, create default
-    await savePathPermissions(repoRoot, [], userId, mode)
-  }
-}

package/src/authorization/permissions/schema.ts

@@ -1,66 +0,0 @@
-/**
- * Schema for permissions.json file
- */
-
-import { z } from 'zod'
-import type { CanopyUserId, CanopyGroupId } from '../../types'
-import { parsePermissionPath } from '../validation'
-import type { PermissionPath } from '../types'
-
-const permissionTargetSchema = z.object({
-  allowedUsers: z.array(z.string() as z.ZodType<CanopyUserId>).optional(),
-  allowedGroups: z.array(z.string() as z.ZodType<CanopyGroupId>).optional(),
-})
-
-/**
- * Zod schema for PermissionPath - validates and prevents path traversal attacks.
- */
-const permissionPathSchema = z
-  .string()
-  .min(1)
-  .transform((val, ctx) => {
-    const result = parsePermissionPath(val)
-    if (!result.ok) {
-      ctx.addIssue({
-        code: z.ZodIssueCode.custom,
-        message: result.error,
-      })
-      return z.NEVER
-    }
-    return result.path
-  }) as unknown as z.ZodType<PermissionPath>
-
-/**
- * Schema for .canopycms/permissions.json
- *
- * SECURITY: Permission paths are validated to prevent path traversal attacks.
- * Any path containing '..' or other traversal sequences will be rejected.
- */
-export const PermissionsFileSchema = z.object({
-  version: z.literal(1),
-  contentVersion: z.number().optional(), // For optimistic locking
-  updatedAt: z.string().datetime(),
-  updatedBy: z.string() as z.ZodType<CanopyUserId>,
-  pathPermissions: z.array(
-    z.object({
-      path: permissionPathSchema,
-      read: permissionTargetSchema.optional(),
-      edit: permissionTargetSchema.optional(),
-      review: permissionTargetSchema.optional(),
-    }),
-  ),
-})
-
-export type PermissionsFile = z.infer<typeof PermissionsFileSchema>
-
-/**
- * Default permissions file
- */
-export function createDefaultPermissionsFile(userId: CanopyUserId): PermissionsFile {
-  return {
-    version: 1,
-    updatedAt: new Date().toISOString(),
-    updatedBy: userId,
-    pathPermissions: [],
-  }
-}

package/src/authorization/test-utils.ts

@@ -1,15 +0,0 @@
-/**
- * Test utilities for authorization types.
- *
- * These are unsafe casts with NO validation. Import only from test files.
- * For production code, use parsePermissionPath() instead.
- *
- * @example
- * // In test files only:
- * import { unsafeAsPermissionPath } from '../authorization/test-utils'
- */
-
-import type { PermissionPath } from './types'
-
-/** Test-only: cast a string to PermissionPath without validation. */
-export const unsafeAsPermissionPath = (path: string): PermissionPath => path as PermissionPath

package/src/authorization/types.ts

@@ -1,66 +0,0 @@
-/**
- * Authorization types for CanopyCMS
- *
- * This module exports all types related to authorization including
- * branch access, path permissions, and content access results.
- */
-
-import type { CanopyUserId, CanopyGroupId } from '../types'
-
-// Re-export types from other modules for convenience
-export type { CanopyUserId, CanopyGroupId }
-
-/**
- * A path used in permission rules.
- * SECURITY CRITICAL: Always validated to prevent path traversal.
- * Example: "content/posts" or "content/settings/config"
- */
-export type PermissionPath = string & { readonly __brand: 'PermissionPath' }
-
-/**
- * Result of checking branch-level access
- */
-export interface BranchAccessResult {
-  allowed: boolean
-  reason: 'privileged' | 'allowed_by_acl' | 'denied_by_acl' | 'no_acl'
-}
-
-/**
- * Result of checking path-level permissions
- */
-export interface PathPermissionResult {
-  allowed: boolean
-  matchedRule?: import('../config').PathPermission
-  reason?: string
-}
-
-/**
- * Combined result of checking both branch and path access
- */
-export interface ContentAccessResult {
-  allowed: boolean
-  branch: BranchAccessResult
-  path: PathPermissionResult
-}
-
-/**
- * Dependencies for content access checking
- */
-export interface ContentAccessDeps {
-  checkBranchAccess: (
-    context: import('../types').BranchContext,
-    user: import('../user').CanopyUser,
-  ) => BranchAccessResult
-  loadPathPermissions: (
-    branchRoot: string,
-    mode: import('../operating-mode').OperatingMode,
-  ) => Promise<import('../config').PathPermission[]>
-  defaultPathAccess: import('../config').DefaultPathAccess
-  mode: import('../operating-mode').OperatingMode
-  /**
-   * Get the settings branch root path for loading centralized permissions.
-   * Only used in prod/prod-sim modes.
-   * Must throw if settings branch cannot be loaded.
-   */
-  getSettingsBranchRoot?: () => Promise<string>
-}