canopycms 0.0.0

package/src/authorization/validation.test.ts

@@ -0,0 +1,100 @@
+import { describe, it, expect } from 'vitest'
+import { parsePermissionPath } from './validation'
+
+describe('authorization validation', () => {
+  describe('parsePermissionPath', () => {
+    it('returns typed PermissionPath for valid paths', () => {
+      const result = parsePermissionPath('content/posts')
+      expect(result.ok).toBe(true)
+      if (result.ok) {
+        expect(result.path).toBe('content/posts')
+      }
+    })
+
+    it('accepts various valid permission paths', () => {
+      const validPaths = [
+        'content',
+        'content/posts',
+        'content/posts/published',
+        'content/settings/config',
+        'assets/images',
+      ]
+      validPaths.forEach((path) => {
+        const result = parsePermissionPath(path)
+        expect(result.ok).toBe(true)
+      })
+    })
+
+    it('rejects empty paths', () => {
+      const result = parsePermissionPath('')
+      expect(result.ok).toBe(false)
+      if (!result.ok) {
+        expect(result.error).toContain('required')
+      }
+    })
+
+    it('rejects paths with traversal sequences', () => {
+      const result = parsePermissionPath('content/../admin')
+      expect(result.ok).toBe(false)
+      if (!result.ok) {
+        expect(result.error).toContain('traversal')
+      }
+    })
+
+    it('rejects paths with double-dot at start', () => {
+      const result = parsePermissionPath('../content')
+      expect(result.ok).toBe(false)
+      if (!result.ok) {
+        expect(result.error).toContain('traversal')
+      }
+    })
+
+    it('rejects paths with double-dot at end', () => {
+      const result = parsePermissionPath('content/..')
+      expect(result.ok).toBe(false)
+      if (!result.ok) {
+        expect(result.error).toContain('traversal')
+      }
+    })
+
+    it('rejects paths starting with slash', () => {
+      const result = parsePermissionPath('/content/posts')
+      expect(result.ok).toBe(false)
+      if (!result.ok) {
+        expect(result.error).toContain('start')
+      }
+    })
+
+    it('rejects paths ending with slash', () => {
+      const result = parsePermissionPath('content/posts/')
+      expect(result.ok).toBe(false)
+      if (!result.ok) {
+        expect(result.error).toContain('end')
+      }
+    })
+
+    it('rejects paths with consecutive slashes', () => {
+      const result = parsePermissionPath('content//posts')
+      expect(result.ok).toBe(false)
+      if (!result.ok) {
+        expect(result.error).toContain('consecutive')
+      }
+    })
+
+    it('normalizes backslashes to forward slashes', () => {
+      const result = parsePermissionPath('content\\posts')
+      expect(result.ok).toBe(true)
+      if (result.ok) {
+        expect(result.path).toBe('content/posts')
+      }
+    })
+
+    it('prevents bypass via backslashes with traversal', () => {
+      const result = parsePermissionPath('content\\..\\admin')
+      expect(result.ok).toBe(false)
+      if (!result.ok) {
+        expect(result.error).toContain('traversal')
+      }
+    })
+  })
+})

package/src/authorization/validation.ts

@@ -0,0 +1,62 @@
+/**
+ * Authorization validation utilities.
+ *
+ * SECURITY CRITICAL: These functions validate permission paths
+ * to prevent path traversal attacks.
+ */
+
+import { hasTraversalSequence } from '../paths/normalize'
+import type { PermissionPath } from './types'
+
+/**
+ * Parse and validate a PermissionPath.
+ *
+ * SECURITY: Prevents path traversal attacks in permission rules.
+ *
+ * @param path - The permission path to validate
+ * @returns Object with success flag and either the typed path or an error
+ *
+ * @example
+ * ```ts
+ * const result = parsePermissionPath(rule.path)
+ * if (!result.ok) {
+ *   throw new Error(`Invalid permission path: ${result.error}`)
+ * }
+ * const permissionPath: PermissionPath = result.path
+ * ```
+ */
+export function parsePermissionPath(
+  path: string,
+): { ok: true; path: PermissionPath } | { ok: false; error: string } {
+  if (!path || typeof path !== 'string') {
+    return { ok: false, error: 'Permission path is required' }
+  }
+
+  // SECURITY: Prevent path traversal attacks
+  if (hasTraversalSequence(path)) {
+    return {
+      ok: false,
+      error: 'Permission path contains traversal sequence (..)',
+    }
+  }
+
+  // Normalize separators to prevent bypass via backslashes
+  const normalized = path.replace(/\\/g, '/')
+
+  // Additional security checks
+  if (normalized.startsWith('/') || normalized.endsWith('/')) {
+    return {
+      ok: false,
+      error: 'Permission path cannot start or end with a slash',
+    }
+  }
+
+  if (normalized.includes('//')) {
+    return {
+      ok: false,
+      error: 'Permission path cannot contain consecutive slashes',
+    }
+  }
+
+  return { ok: true, path: normalized as PermissionPath }
+}

package/src/branch-metadata.test.ts

@@ -0,0 +1,168 @@
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+import { describe, expect, it } from 'vitest'
+
+import { BranchMetadataFileManager, getBranchMetadataFileManager } from './branch-metadata'
+
+const tmpDir = async () => fs.mkdtemp(path.join(os.tmpdir(), 'canopycms-branchmeta-'))
+
+describe('BranchMetadataFileManager', () => {
+  describe('loadOnly', () => {
+    it('loads metadata from disk', async () => {
+      const root = await tmpDir()
+      const now = new Date().toISOString()
+
+      // Manually write file to test loadOnly
+      const metaDir = path.join(root, '.canopy-meta')
+      await fs.mkdir(metaDir, { recursive: true })
+      await fs.writeFile(
+        path.join(metaDir, 'branch.json'),
+        JSON.stringify({
+          schemaVersion: 1,
+          branch: {
+            name: 'feature/x',
+            status: 'editing',
+            access: { allowedUsers: ['u1'], allowedGroups: ['g1'] },
+            createdBy: 'u1',
+            createdAt: now,
+            updatedAt: now,
+          },
+        }),
+      )
+
+      const loaded = await BranchMetadataFileManager.loadOnly(root)
+      expect(loaded?.branch.name).toBe('feature/x')
+      expect(loaded?.branch.access.allowedGroups).toContain('g1')
+    })
+
+    it('returns null for missing metadata', async () => {
+      const root = await tmpDir()
+      const loaded = await BranchMetadataFileManager.loadOnly(root)
+      expect(loaded).toBeNull()
+    })
+  })
+
+  describe('update', () => {
+    it('creates metadata when none exists', async () => {
+      const root = await tmpDir()
+      const registryDir = await tmpDir()
+      const meta = getBranchMetadataFileManager(root, registryDir)
+
+      const created = await meta.save({
+        branch: {
+          name: 'feature/x',
+          status: 'editing',
+          access: { allowedUsers: ['u1'], allowedGroups: ['g1'] },
+          createdBy: 'u1',
+        },
+      })
+
+      expect(created.branch.name).toBe('feature/x')
+      expect(created.branch.access.allowedGroups).toContain('g1')
+
+      const loaded = await BranchMetadataFileManager.loadOnly(root)
+      expect(loaded?.branch.name).toBe('feature/x')
+    })
+
+    it('updates existing metadata and stamps updatedAt', async () => {
+      const root = await tmpDir()
+      const registryDir = await tmpDir()
+      const meta = getBranchMetadataFileManager(root, registryDir)
+
+      // First create
+      const created = await meta.save({
+        branch: {
+          name: 'feature/y',
+          status: 'editing',
+          createdBy: 'u1',
+        },
+      })
+
+      // Then update
+      const updated = await meta.save({
+        branch: {
+          name: 'feature/y',
+          status: 'submitted',
+          access: { managerOrAdminAllowed: true },
+          pullRequestNumber: 10,
+          pullRequestUrl: 'https://example.com/pr/10',
+        },
+      })
+
+      expect(updated.branch.status).toBe('submitted')
+      expect(updated.branch.pullRequestNumber).toBe(10)
+      expect(updated.branch.access.managerOrAdminAllowed).toBe(true)
+      expect(updated.branch.createdAt).toBe(created.branch.createdAt) // createdAt unchanged
+      expect(new Date(updated.branch.updatedAt).getTime()).toBeGreaterThanOrEqual(
+        new Date(created.branch.createdAt).getTime(),
+      )
+    })
+  })
+
+  describe('registry invalidation', () => {
+    it('update() invalidates registry cache', async () => {
+      const branchRoot = await tmpDir()
+      const registryDir = await tmpDir()
+
+      // Create initial cache file
+      const cacheFile = path.join(registryDir, 'branches.json')
+      await fs.mkdir(path.dirname(cacheFile), { recursive: true })
+      await fs.writeFile(cacheFile, JSON.stringify({ version: 1, branches: [] }))
+
+      // Create metadata with registryDir
+      const meta = getBranchMetadataFileManager(branchRoot, registryDir)
+
+      // First update creates the metadata and invalidates cache
+      await meta.save({
+        branch: {
+          name: 'feature/z',
+          status: 'editing',
+          createdBy: 'u1',
+        },
+      })
+
+      // Recreate cache file to test invalidation on second update
+      await fs.writeFile(cacheFile, JSON.stringify({ version: 1, branches: [] }))
+
+      // Second update should also invalidate registry
+      await meta.save({
+        branch: { status: 'submitted' },
+      })
+
+      // Cache should be gone, stale file should exist
+      const cacheExists = await fs
+        .stat(cacheFile)
+        .then(() => true)
+        .catch(() => false)
+      const staleFile = path.join(registryDir, 'branches.stale.json')
+      const staleExists = await fs
+        .stat(staleFile)
+        .then(() => true)
+        .catch(() => false)
+
+      expect(cacheExists).toBe(false)
+      expect(staleExists).toBe(true)
+    })
+
+    it('getBranchMetadataFileManager factory creates metadata with registryDir', async () => {
+      const branchRoot = await tmpDir()
+      const registryDir = await tmpDir()
+
+      const meta = getBranchMetadataFileManager(branchRoot, registryDir)
+
+      // Create metadata via update
+      await meta.save({
+        branch: {
+          name: 'feature/factory',
+          status: 'editing',
+          createdBy: 'u1',
+        },
+      })
+
+      const loaded = await BranchMetadataFileManager.loadOnly(branchRoot)
+      expect(loaded?.branch.name).toBe('feature/factory')
+    })
+  })
+})

package/src/branch-metadata.ts

@@ -0,0 +1,166 @@
+import fs from 'node:fs/promises'
+import path from 'node:path'
+
+import type { BranchContext, BranchMetadata, BranchStatus } from './types'
+import { BranchRegistry } from './branch-registry'
+import { resolveBranchPath } from './paths'
+import { type OperatingMode } from './operating-mode'
+import { isNotFoundError } from './utils/error'
+
+const BRANCH_META_DIR = '.canopy-meta'
+const BRANCH_META_FILE = 'branch.json'
+
+export interface BranchMetadataFile {
+  schemaVersion: number
+  branch: BranchMetadata
+}
+
+const CURRENT_SCHEMA_VERSION = 1
+
+export class BranchMetadataFileManager {
+  private readonly branchRoot: string
+  private readonly filePath: string
+  private readonly baseRoot: string
+
+  private constructor(branchRoot: string, baseRoot: string) {
+    this.branchRoot = path.resolve(branchRoot)
+    this.filePath = path.join(this.branchRoot, BRANCH_META_DIR, BRANCH_META_FILE)
+    this.baseRoot = baseRoot
+  }
+
+  /**
+   * Load branch metadata without requiring baseRoot.
+   * Use this for read-only access (e.g., in registry scanning or loadBranchContext).
+   */
+  static async loadOnly(branchRoot: string): Promise<BranchMetadataFile | null> {
+    const filePath = path.join(path.resolve(branchRoot), BRANCH_META_DIR, BRANCH_META_FILE)
+    try {
+      const raw = await fs.readFile(filePath, 'utf8')
+      return JSON.parse(raw) as BranchMetadataFile
+    } catch (err: unknown) {
+      if (isNotFoundError(err)) {
+        return null
+      }
+      throw err
+    }
+  }
+
+  /**
+   * Get a BranchMetadataFileManager instance configured for registry invalidation.
+   * Use this in API handlers to ensure registry cache is invalidated on updates.
+   */
+  static get(branchRoot: string, baseRoot: string): BranchMetadataFileManager {
+    return new BranchMetadataFileManager(branchRoot, baseRoot)
+  }
+
+  private async load(): Promise<BranchMetadataFile | null> {
+    try {
+      const raw = await fs.readFile(this.filePath, 'utf8')
+      const parsed = JSON.parse(raw) as BranchMetadataFile
+      return parsed
+    } catch (err: unknown) {
+      if (isNotFoundError(err)) {
+        return null
+      }
+      throw err
+    }
+  }
+
+  private async write(meta: BranchMetadataFile): Promise<void> {
+    const payload = {
+      ...meta,
+      schemaVersion: meta.schemaVersion ?? CURRENT_SCHEMA_VERSION,
+    }
+    await fs.mkdir(path.dirname(this.filePath), { recursive: true })
+    await fs.writeFile(this.filePath, JSON.stringify(payload, null, 2) + '\n', 'utf8')
+  }
+
+  async save(incoming: BranchMetadataUpdate): Promise<BranchMetadataFile> {
+    const existing = await this.load()
+    const now = new Date().toISOString()
+
+    const defaults: BranchMetadata = {
+      name: 'unknown',
+      status: 'editing' as BranchStatus,
+      access: {},
+      createdBy: 'unknown',
+      createdAt: now,
+      updatedAt: now,
+    }
+
+    const merged: BranchMetadataFile = {
+      schemaVersion: CURRENT_SCHEMA_VERSION,
+      branch: {
+        ...defaults,
+        ...existing?.branch,
+        ...incoming.branch,
+        access: {
+          ...existing?.branch?.access,
+          ...incoming.branch?.access,
+        },
+        // Immutable after creation
+        createdBy: existing?.branch.createdBy ?? incoming.branch?.createdBy ?? defaults.createdBy,
+        createdAt: existing?.branch.createdAt ?? defaults.createdAt,
+      },
+    }
+    await this.write(merged)
+    await this.invalidateRegistry()
+
+    return merged
+  }
+
+  /**
+   * Invalidates the registry cache so next list() call regenerates from branch.json files.
+   */
+  private async invalidateRegistry(): Promise<void> {
+    const registry = new BranchRegistry(this.baseRoot)
+    await registry.invalidate()
+  }
+}
+
+/**
+ * Fields that can be set via save().
+ * - createdBy: Only used on initial creation; ignored if metadata already exists
+ * - createdAt/updatedAt: Managed automatically
+ */
+export interface BranchMetadataUpdate {
+  branch?: Partial<Omit<BranchMetadata, 'createdAt' | 'updatedAt'>>
+}
+
+/**
+ * Get a BranchMetadataFileManager instance configured for registry invalidation.
+ * Use this in API handlers to ensure registry cache is invalidated on updates.
+ */
+export const getBranchMetadataFileManager = (
+  branchRoot: string,
+  baseRoot: string,
+): BranchMetadataFileManager => {
+  return BranchMetadataFileManager.get(branchRoot, baseRoot)
+}
+
+/**
+ * Load branch context from metadata file (source of truth).
+ * Returns null if the branch doesn't exist.
+ */
+export const loadBranchContext = async (options: {
+  branchName: string
+  mode: OperatingMode
+  basePathOverride?: string
+}): Promise<BranchContext | null> => {
+  const { branchRoot, baseRoot } = resolveBranchPath({
+    branchName: options.branchName,
+    mode: options.mode,
+    basePathOverride: options.basePathOverride,
+  })
+
+  const meta = await BranchMetadataFileManager.loadOnly(branchRoot)
+  if (!meta) {
+    return null
+  }
+
+  return {
+    branch: meta.branch,
+    branchRoot,
+    baseRoot,
+  }
+}