canopycms 0.0.0

package/src/paths/validation.ts

@@ -0,0 +1,391 @@
+/**
+ * Path validation utilities.
+ *
+ * Security-focused validation for content paths and slugs.
+ */
+
+import { normalizeFilesystemPath, hasTraversalSequence } from './normalize'
+import type {
+  LogicalPath,
+  PhysicalPath,
+  ContentId,
+  BranchName,
+  EntrySlug,
+  CollectionSlug,
+} from './types'
+
+/**
+ * Base58 alphabet used for content IDs (excludes ambiguous: 0, O, I, l)
+ */
+const BASE58_PATTERN = '[123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz]'
+
+/**
+ * Pattern matching exactly a 12-character content ID
+ */
+const CONTENT_ID_PATTERN = new RegExp(`^${BASE58_PATTERN}{12}$`)
+
+/**
+ * Pattern matching a physical path segment with embedded ID.
+ * Matches patterns like:
+ * - `post.my-slug.abc123def456.json` (entry)
+ * - `posts.abc123def456` (collection directory)
+ */
+const PHYSICAL_SEGMENT_PATTERN = new RegExp(`\\.${BASE58_PATTERN}{12}(?:\\.[a-z]+)?$`)
+
+/**
+ * Validate a content path for security.
+ *
+ * @param path - The path to validate
+ * @param rootPath - The root directory (for traversal check)
+ * @returns Validation result
+ */
+export function validateContentPath(
+  path: string,
+  rootPath: string,
+): { valid: boolean; error?: string } {
+  const normalized = normalizeFilesystemPath(path)
+
+  // Check for traversal sequences
+  if (hasTraversalSequence(normalized)) {
+    return { valid: false, error: 'Path contains traversal sequence' }
+  }
+
+  // Check path doesn't escape root
+  const normalizedRoot = normalizeFilesystemPath(rootPath)
+  if (!normalized.startsWith(normalizedRoot) && normalized !== normalizedRoot) {
+    // Allow paths that are relative within the root
+    const normalizedPath = `${normalizedRoot}/${normalized}`
+    if (hasTraversalSequence(normalizedPath)) {
+      return { valid: false, error: 'Path escapes root directory' }
+    }
+  }
+
+  return { valid: true }
+}
+
+/**
+ * Validate a collection path.
+ *
+ * @param collectionPath - The collection path to validate
+ * @returns true if valid, false otherwise
+ */
+export function isValidCollectionPath(collectionPath: string): boolean {
+  if (!collectionPath || collectionPath.length === 0) {
+    return false
+  }
+
+  // Normalize and check for traversal
+  const normalized = normalizeFilesystemPath(collectionPath)
+  if (hasTraversalSequence(normalized)) {
+    return false
+  }
+
+  // Collection paths should only contain alphanumeric, hyphens, underscores, and forward slashes
+  const validPattern = /^[a-zA-Z0-9_/-]+$/
+  return validPattern.test(normalized)
+}
+
+/**
+ * Sanitize a string for use in paths by removing dangerous characters.
+ *
+ * @param input - The string to sanitize
+ * @returns Sanitized string safe for path use
+ */
+export function sanitizeForPath(input: string): string {
+  return input
+    .replace(/[<>:"|?*\\]/g, '') // Remove invalid filesystem chars
+    .replace(/\.{2,}/g, '.') // Collapse multiple dots
+    .replace(/^\./, '') // Remove leading dot
+    .trim()
+}
+
+/**
+ * Check if a path segment contains an embedded content ID.
+ *
+ * Physical paths have segments with embedded 12-char IDs:
+ * - `post.my-slug.abc123def456.json` (entry file)
+ * - `posts.abc123def456` (collection directory)
+ *
+ * @param segment - A single path segment (no slashes)
+ * @returns true if segment contains embedded ID pattern
+ */
+export function hasEmbeddedContentId(segment: string): boolean {
+  return PHYSICAL_SEGMENT_PATTERN.test(segment)
+}
+
+/**
+ * Check if a path appears to be a physical path (contains embedded content IDs).
+ *
+ * Physical paths have the format:
+ * - `content/posts.abc123/post.hello.def456.json`
+ *
+ * Logical paths do not have embedded IDs:
+ * - `content/posts/hello` or `posts/hello`
+ *
+ * @param path - The path to check
+ * @returns true if any segment contains an embedded content ID
+ */
+export function looksLikePhysicalPath(path: string): boolean {
+  const segments = path.split('/')
+  return segments.some(hasEmbeddedContentId)
+}
+
+/**
+ * Check if a path appears to be a logical path (no embedded content IDs).
+ *
+ * @param path - The path to check
+ * @returns true if no segments contain embedded content IDs
+ */
+export function looksLikeLogicalPath(path: string): boolean {
+  return !looksLikePhysicalPath(path)
+}
+
+/**
+ * Validate and cast a string to LogicalPath.
+ *
+ * Use this at API boundaries to validate incoming path strings
+ * and cast them to the branded LogicalPath type.
+ *
+ * @param path - The path string to validate
+ * @returns Object with success flag and either the typed path or an error
+ *
+ * @example
+ * ```ts
+ * const result = parseLogicalPath(params.collectionPath)
+ * if (!result.ok) {
+ *   return { ok: false, status: 400, error: result.error }
+ * }
+ * const collectionPath: LogicalPath = result.path
+ * ```
+ */
+export function parseLogicalPath(
+  path: string,
+): { ok: true; path: LogicalPath } | { ok: false; error: string } {
+  // Basic validation
+  if (!path || typeof path !== 'string') {
+    return { ok: false, error: 'Path is required' }
+  }
+
+  // Normalize backslashes to forward slashes (consistent with parsePermissionPath)
+  const normalized = path.replace(/\\/g, '/')
+
+  // Security check
+  if (hasTraversalSequence(normalized)) {
+    return { ok: false, error: 'Path contains traversal sequence' }
+  }
+
+  // Check it's not a physical path
+  if (looksLikePhysicalPath(normalized)) {
+    return {
+      ok: false,
+      error:
+        'Path appears to be a physical path (contains embedded content ID). Expected a logical path.',
+    }
+  }
+
+  return { ok: true, path: normalized as LogicalPath }
+}
+
+/**
+ * Validate and cast a string to PhysicalPath.
+ *
+ * Use this at API boundaries to validate incoming path strings
+ * and cast them to the branded PhysicalPath type.
+ *
+ * @param path - The path string to validate
+ * @returns Object with success flag and either the typed path or an error
+ */
+export function parsePhysicalPath(
+  path: string,
+): { ok: true; path: PhysicalPath } | { ok: false; error: string } {
+  // Basic validation
+  if (!path || typeof path !== 'string') {
+    return { ok: false, error: 'Path is required' }
+  }
+
+  // Normalize backslashes to forward slashes (consistent with parseLogicalPath)
+  const normalized = path.replace(/\\/g, '/')
+
+  // Security check
+  if (hasTraversalSequence(normalized)) {
+    return { ok: false, error: 'Path contains traversal sequence' }
+  }
+
+  // Check it looks like a physical path
+  if (!looksLikePhysicalPath(normalized)) {
+    return {
+      ok: false,
+      error:
+        'Path appears to be a logical path (no embedded content ID). Expected a physical path.',
+    }
+  }
+
+  return { ok: true, path: normalized as PhysicalPath }
+}
+
+/**
+ * Check if a string is a valid 12-character content ID.
+ *
+ * @param id - The string to check
+ * @returns true if valid Base58 12-char ID
+ */
+export function isValidContentId(id: string): boolean {
+  return CONTENT_ID_PATTERN.test(id)
+}
+
+/**
+ * Parse and validate a ContentId from a string.
+ * Validates Base58 format and 12-character length.
+ *
+ * @param id - The string to validate
+ * @returns Object with success flag and either the typed ID or an error
+ *
+ * @example
+ * ```ts
+ * const result = parseContentId(fileId)
+ * if (!result.ok) {
+ *   throw new Error(result.error)
+ * }
+ * const contentId: ContentId = result.id
+ * ```
+ */
+export function parseContentId(
+  id: string,
+): { ok: true; id: ContentId } | { ok: false; error: string } {
+  if (!id || typeof id !== 'string') {
+    return { ok: false, error: 'Content ID is required' }
+  }
+
+  if (!isValidContentId(id)) {
+    return {
+      ok: false,
+      error: `Invalid content ID format (expected 12 Base58 characters, got: ${id})`,
+    }
+  }
+
+  return { ok: true, id: id as ContentId }
+}
+
+/**
+ * Parse and validate a BranchName.
+ * Checks git branch naming rules.
+ *
+ * @param name - The branch name to validate
+ * @returns Object with success flag and either the typed name or an error
+ *
+ * @example
+ * ```ts
+ * const result = parseBranchName(params.branch)
+ * if (!result.ok) {
+ *   return { ok: false, status: 400, error: result.error }
+ * }
+ * const branchName: BranchName = result.name
+ * ```
+ */
+export function parseBranchName(
+  name: string,
+): { ok: true; name: BranchName } | { ok: false; error: string } {
+  if (!name || typeof name !== 'string') {
+    return { ok: false, error: 'Branch name is required' }
+  }
+
+  // Length limit (branch names become directory names)
+  if (name.length > 250) {
+    return { ok: false, error: 'Branch name too long (max 250 characters)' }
+  }
+
+  // Git branch name rules
+  if (name.includes('..')) {
+    return { ok: false, error: 'Branch name cannot contain ".."' }
+  }
+
+  if (name.startsWith('/') || name.endsWith('/') || name.includes('//')) {
+    return { ok: false, error: 'Invalid branch name format (invalid slashes)' }
+  }
+
+  if (name.includes(' ')) {
+    return { ok: false, error: 'Branch name cannot contain spaces' }
+  }
+
+  // Additional git restrictions
+  if (name.startsWith('.') || name.endsWith('.')) {
+    return { ok: false, error: 'Branch name cannot start or end with a dot' }
+  }
+
+  if (name.includes('@{')) {
+    return { ok: false, error: 'Branch name cannot contain "@{"' }
+  }
+
+  // Git-forbidden characters: ~ ^ : ? * [ \ and control chars
+  // eslint-disable-next-line no-control-regex -- intentional: git forbids control characters in branch names
+  if (/[~^:?*[\\\x00-\x1f\x7f]/.test(name)) {
+    return { ok: false, error: 'Branch name contains invalid characters' }
+  }
+
+  if (name.endsWith('.lock')) {
+    return { ok: false, error: 'Branch name cannot end with ".lock"' }
+  }
+
+  return { ok: true, name: name as BranchName }
+}
+
+/**
+ * Parse and validate a slug (collection or entry).
+ * Validates format and length constraints.
+ *
+ * @param slug - The slug to validate
+ * @param type - Whether this is a collection or entry slug
+ * @returns Object with success flag and either the typed slug or an error
+ *
+ * @example
+ * ```ts
+ * const result = parseSlug(params.slug, 'entry')
+ * if (!result.ok) {
+ *   return { ok: false, status: 400, error: result.error }
+ * }
+ * const entrySlug: EntrySlug = result.slug
+ * ```
+ */
+export function parseSlug(
+  slug: string,
+  type: 'collection' | 'entry',
+): { ok: true; slug: CollectionSlug | EntrySlug } | { ok: false; error: string } {
+  if (!slug || typeof slug !== 'string') {
+    return {
+      ok: false,
+      error: `${type === 'collection' ? 'Collection' : 'Entry'} slug is required`,
+    }
+  }
+
+  // Check length (filesystem path safety)
+  if (slug.length > 64) {
+    return { ok: false, error: 'Slug too long (max 64 characters)' }
+  }
+
+  // Check for path separators and traversal
+  if (slug.includes('/') || slug.includes('\\')) {
+    return {
+      ok: false,
+      error: 'Slug cannot contain path separators',
+    }
+  }
+
+  if (slug === '.' || slug === '..') {
+    return {
+      ok: false,
+      error: 'Slug cannot be a traversal sequence',
+    }
+  }
+
+  // Validation from ContentStore.renameEntry
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(slug)) {
+    return {
+      ok: false,
+      error:
+        'Slug must start with a letter or number and contain only lowercase letters, numbers, and hyphens',
+    }
+  }
+
+  // Cast to appropriate branded type
+  return { ok: true, slug: slug as CollectionSlug | EntrySlug }
+}

package/src/reference-resolver.test.ts

@@ -0,0 +1,107 @@
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+import { afterEach, beforeEach, describe, expect, it } from 'vitest'
+
+import type { CanopyConfig } from './config'
+import { flattenSchema } from './config'
+import { ContentIdIndex } from './content-id-index'
+import { ContentStore } from './content-store'
+import { ReferenceResolver } from './reference-resolver'
+import { unsafeAsLogicalPath } from './paths/test-utils'
+
+describe('ReferenceResolver', () => {
+  let tempDir: string
+  let store: ContentStore
+  let idIndex: ContentIdIndex
+  let resolver: ReferenceResolver
+
+  beforeEach(async () => {
+    // Create temp directory with content structure
+    tempDir = await fs.mkdtemp(path.join(os.tmpdir(), 'canopy-test-'))
+    await fs.mkdir(path.join(tempDir, 'content', 'authors'), {
+      recursive: true,
+    })
+
+    // Create test author files with embedded IDs: {type}.{slug}.{id}.{ext}
+    const aliceId = 'aXice123ABC4' // 12 chars, valid Base58
+    const bobId = 'bob456XYZ789' // 12 chars, valid Base58
+
+    await fs.writeFile(
+      path.join(tempDir, 'content', 'authors', `author.alice.${aliceId}.json`),
+      JSON.stringify({ slug: 'alice', name: 'Alice' }),
+    )
+    await fs.writeFile(
+      path.join(tempDir, 'content', 'authors', `author.bob.${bobId}.json`),
+      JSON.stringify({ slug: 'bob', name: 'Bob' }),
+    )
+
+    // Initialize store and index
+    const schema = {
+      collections: [
+        {
+          name: 'authors',
+          path: 'authors',
+          entries: [
+            {
+              name: 'author',
+              format: 'json' as const,
+              schema: [{ name: 'name', type: 'string' as const, label: 'Name' }],
+            },
+          ],
+        },
+      ],
+    } as const
+
+    const config: CanopyConfig = {
+      contentRoot: 'content',
+      gitBotAuthorName: 'Test Bot',
+      gitBotAuthorEmail: 'test@example.com',
+      mode: 'prod',
+    }
+
+    store = new ContentStore(tempDir, flattenSchema(schema, config.contentRoot))
+    idIndex = await store.idIndex()
+    resolver = new ReferenceResolver(store, idIndex)
+  })
+
+  afterEach(async () => {
+    // Clean up temp directory
+    await fs.rm(tempDir, { recursive: true, force: true })
+  })
+
+  describe('loadReferenceOptions', () => {
+    it('loads options when collection path does not include content/ prefix', async () => {
+      // REGRESSION TEST: ID index stores "content/authors" but schema specifies "authors"
+      // This ensures the collection path normalization works correctly
+      const options = await resolver.loadReferenceOptions([unsafeAsLogicalPath('authors')], 'name')
+
+      expect(options).toHaveLength(2)
+      const labels = options.map((o) => o.label).sort()
+      expect(labels).toEqual(['Alice', 'Bob'])
+      expect(options.every((o) => o.id && o.collection)).toBe(true)
+    })
+
+    it('loads options when collection path includes content/ prefix', async () => {
+      // REGRESSION TEST: Should also work if "content/authors" is explicitly specified
+      const options = await resolver.loadReferenceOptions(
+        [unsafeAsLogicalPath('content/authors')],
+        'name',
+      )
+
+      expect(options).toHaveLength(2)
+      const labels = options.map((o) => o.label).sort()
+      expect(labels).toEqual(['Alice', 'Bob'])
+    })
+
+    it('returns empty array for non-existent collection', async () => {
+      const options = await resolver.loadReferenceOptions(
+        [unsafeAsLogicalPath('nonexistent')],
+        'name',
+      )
+
+      expect(options).toHaveLength(0)
+    })
+  })
+})

package/src/reference-resolver.ts

@@ -0,0 +1,157 @@
+import path from 'node:path'
+
+import type { ContentStore } from './content-store'
+import type { ContentIdIndex } from './content-id-index'
+import { extractSlugFromFilename } from './content-id-index'
+import type { LogicalPath, PhysicalPath, EntrySlug } from './paths'
+
+export interface ResolvedReference {
+  id: string
+  exists: boolean
+  displayValue: string
+  collection?: LogicalPath
+  slug?: EntrySlug
+}
+
+export interface ReferenceOption {
+  id: string
+  label: string
+  collection: string
+}
+
+/**
+ * ReferenceResolver resolves content IDs to display values for reference fields.
+ *
+ * This class provides utilities for:
+ * - Resolving a single ID to its display value (e.g., title)
+ * - Loading all available options for a reference field
+ * - Filtering options by collection constraints
+ * - Searching options by display value
+ */
+export class ReferenceResolver {
+  constructor(
+    private store: ContentStore,
+    private idIndex: ContentIdIndex,
+  ) {}
+
+  /**
+   * Resolve a content ID to a display value.
+   * Returns null if the ID doesn't exist or points to a collection.
+   *
+   * @param id - The content ID to resolve
+   * @param displayField - The field to use for display value (default: 'title')
+   */
+  async resolve(id: string, displayField = 'title'): Promise<ResolvedReference | null> {
+    const location = this.idIndex.findById(id)
+
+    if (!location || location.type !== 'entry') {
+      return {
+        id,
+        exists: false,
+        displayValue: id, // Fallback to showing the ID itself
+      }
+    }
+
+    try {
+      const doc = await this.store.read(location.collection!, location.slug!)
+      const displayValue = String(doc.data[displayField] || doc.data.title || location.slug)
+
+      return {
+        id,
+        exists: true,
+        displayValue,
+        collection: location.collection,
+        slug: location.slug,
+      }
+    } catch (error) {
+      console.error('Failed to resolve reference:', { id, error })
+      return {
+        id,
+        exists: false,
+        displayValue: id,
+      }
+    }
+  }
+
+  /**
+   * Load all available reference options for a reference field.
+   *
+   * This method scans the specified collections and returns options
+   * suitable for a dropdown/select field.
+   *
+   * @param collections - Collection paths to search (e.g., ['posts', 'docs'])
+   * @param displayField - Field to use for option labels (default: 'title')
+   * @param search - Optional search string to filter options
+   */
+  async loadReferenceOptions(
+    collections: LogicalPath[],
+    displayField = 'title',
+    search?: string,
+  ): Promise<ReferenceOption[]> {
+    const options: ReferenceOption[] = []
+
+    for (const collectionPath of collections) {
+      // Get all entries in this collection
+      const entries = await this.listEntriesInCollection(collectionPath)
+
+      for (const entry of entries) {
+        const id = this.idIndex.findByPath(entry.relativePath)
+        if (!id) continue
+
+        try {
+          // The slug from the index may include the entry type prefix for new-format files
+          // (e.g., "author.alice" instead of just "alice"). We need to strip the type prefix
+          // before passing to store.read() to avoid double-prefixing.
+          // Use extractSlugFromFilename to properly extract just the slug part.
+          const filename = path.basename(entry.relativePath)
+          const normalizedSlug = extractSlugFromFilename(filename)
+
+          const doc = await this.store.read(entry.collection, normalizedSlug as EntrySlug)
+          const label = String(doc.data[displayField] || doc.data.title || normalizedSlug)
+
+          // Apply search filter if provided
+          if (search && !label.toLowerCase().includes(search.toLowerCase())) {
+            continue
+          }
+
+          options.push({
+            id,
+            label,
+            collection: entry.collection,
+          })
+        } catch (error) {
+          // Skip entries that can't be read
+          console.error('Failed to read entry for reference options:', {
+            collection: entry.collection,
+            slug: entry.slug,
+            error,
+          })
+          continue
+        }
+      }
+    }
+
+    return options.sort((a, b) => a.label.localeCompare(b.label))
+  }
+
+  /**
+   * Helper to list all entries in a collection.
+   */
+  private async listEntriesInCollection(collectionPath: LogicalPath): Promise<
+    Array<{
+      relativePath: PhysicalPath
+      collection: LogicalPath
+      slug: EntrySlug
+    }>
+  > {
+    return this.store.listCollectionEntries(collectionPath)
+  }
+
+  /**
+   * Resolve multiple IDs at once.
+   * Useful for displaying lists of referenced items.
+   */
+  async resolveMany(ids: string[], displayField = 'title'): Promise<(ResolvedReference | null)[]> {
+    return Promise.all(ids.map((id) => this.resolve(id, displayField)))
+  }
+}

package/src/schema/index.ts

@@ -0,0 +1,29 @@
+/**
+ * Schema Module
+ *
+ * This module provides schema loading and resolution for CanopyCMS.
+ * Schema structure is defined in .collection.json files (single source of truth)
+ * while field schemas are defined in an entry schema registry for reusability.
+ *
+ * @example
+ * ```ts
+ * import { resolveSchema } from 'canopycms/schema'
+ *
+ * const { schema, sources } = await resolveSchema(contentRoot, entrySchemaRegistry)
+ * ```
+ */
+
+// Types
+export type { EntrySchemaRegistry, SchemaSourceInfo, SchemaResolutionResult } from './types'
+
+// Meta loader (low-level API)
+export {
+  loadCollectionMetaFiles,
+  resolveCollectionReferences,
+  watchCollectionMetaFiles,
+  type CollectionMeta,
+  type RootCollectionMeta,
+} from './meta-loader'
+
+// Resolver (high-level API)
+export { resolveSchema, hasSchemaFiles, isValidSchema } from './resolver'