canopycms 0.0.0

package/src/api/validators.test.ts

@@ -0,0 +1,275 @@
+import { describe, it, expect } from 'vitest'
+import { z } from 'zod'
+import {
+  branchNameSchema,
+  logicalPathSchema,
+  contentIdSchema,
+  entrySlugSchema,
+  collectionSlugSchema,
+  permissionPathSchema,
+} from './validators'
+
+describe('API validators', () => {
+  describe('branchNameSchema', () => {
+    it('validates and brands valid branch names', () => {
+      const result = branchNameSchema.parse('main')
+      expect(result).toBe('main')
+    })
+
+    it('accepts branch names with slashes', () => {
+      const result = branchNameSchema.parse('feature/add-dark-mode')
+      expect(result).toBe('feature/add-dark-mode')
+    })
+
+    it('rejects empty branch names', () => {
+      expect(() => branchNameSchema.parse('')).toThrow()
+    })
+
+    it('rejects branch names with spaces', () => {
+      expect(() => branchNameSchema.parse('my branch')).toThrow('space')
+    })
+
+    it('rejects branch names with double dots', () => {
+      expect(() => branchNameSchema.parse('feature..bug')).toThrow()
+    })
+
+    it('rejects branch names starting with slash', () => {
+      expect(() => branchNameSchema.parse('/feature')).toThrow('slash')
+    })
+
+    it('rejects branch names ending with slash', () => {
+      expect(() => branchNameSchema.parse('feature/')).toThrow('slash')
+    })
+
+    it('provides clear error messages', () => {
+      try {
+        branchNameSchema.parse('my branch')
+      } catch (error) {
+        expect(error).toBeInstanceOf(z.ZodError)
+        if (error instanceof z.ZodError) {
+          expect(error.errors[0].message).toContain('space')
+        }
+      }
+    })
+  })
+
+  describe('logicalPathSchema', () => {
+    it('validates and brands valid logical paths', () => {
+      const result = logicalPathSchema.parse('content/posts')
+      expect(result).toBe('content/posts')
+    })
+
+    it('accepts nested paths', () => {
+      const result = logicalPathSchema.parse('content/posts/published')
+      expect(result).toBe('content/posts/published')
+    })
+
+    it('rejects empty paths', () => {
+      expect(() => logicalPathSchema.parse('')).toThrow()
+    })
+
+    it('rejects paths with traversal sequences', () => {
+      expect(() => logicalPathSchema.parse('content/../admin')).toThrow('traversal')
+    })
+
+    it('rejects physical paths', () => {
+      expect(() => logicalPathSchema.parse('posts.abc123def456')).toThrow('physical path')
+    })
+
+    it('provides clear error messages', () => {
+      try {
+        logicalPathSchema.parse('content/../admin')
+      } catch (error) {
+        expect(error).toBeInstanceOf(z.ZodError)
+        if (error instanceof z.ZodError) {
+          expect(error.errors[0].message).toContain('traversal')
+        }
+      }
+    })
+  })
+
+  describe('contentIdSchema', () => {
+    it('validates and brands valid content IDs', () => {
+      const result = contentIdSchema.parse('vh2WdhwAFiSL')
+      expect(result).toBe('vh2WdhwAFiSL')
+    })
+
+    it('accepts various Base58 IDs', () => {
+      const validIds = ['abc123def456', 'XYZabc123def', 'vh2WdhwAFiSL']
+      validIds.forEach((id) => {
+        const result = contentIdSchema.parse(id)
+        expect(result).toBe(id)
+      })
+    })
+
+    it('rejects empty IDs', () => {
+      expect(() => contentIdSchema.parse('')).toThrow('required')
+    })
+
+    it('rejects IDs with wrong length', () => {
+      expect(() => contentIdSchema.parse('abc123')).toThrow('12 Base58 characters')
+    })
+
+    it('rejects IDs with invalid characters', () => {
+      // 0, O, I, l are excluded from Base58
+      expect(() => contentIdSchema.parse('0abc23def456')).toThrow('12 Base58 characters')
+    })
+
+    it('provides clear error messages with the invalid ID', () => {
+      try {
+        contentIdSchema.parse('invalid')
+      } catch (error) {
+        expect(error).toBeInstanceOf(z.ZodError)
+        if (error instanceof z.ZodError) {
+          expect(error.errors[0].message).toContain('invalid')
+        }
+      }
+    })
+  })
+
+  describe('entrySlugSchema', () => {
+    it('validates and brands valid entry slugs', () => {
+      const result = entrySlugSchema.parse('my-first-post')
+      expect(result).toBe('my-first-post')
+    })
+
+    it('accepts slugs starting with numbers', () => {
+      const result = entrySlugSchema.parse('2023-update')
+      expect(result).toBe('2023-update')
+    })
+
+    it('rejects empty slugs', () => {
+      expect(() => entrySlugSchema.parse('')).toThrow()
+    })
+
+    it('rejects slugs with path separators', () => {
+      expect(() => entrySlugSchema.parse('posts/hello')).toThrow('separator')
+    })
+
+    it('rejects slugs with uppercase', () => {
+      expect(() => entrySlugSchema.parse('HelloWorld')).toThrow('lowercase')
+    })
+
+    it('rejects slugs not starting with alphanumeric', () => {
+      expect(() => entrySlugSchema.parse('-hello')).toThrow('start with a letter or number')
+    })
+
+    it('rejects slugs longer than 64 characters', () => {
+      const longSlug = 'a'.repeat(65)
+      expect(() => entrySlugSchema.parse(longSlug)).toThrow('too long')
+    })
+
+    it('provides clear error messages', () => {
+      try {
+        entrySlugSchema.parse('posts/hello')
+      } catch (error) {
+        expect(error).toBeInstanceOf(z.ZodError)
+        if (error instanceof z.ZodError) {
+          expect(error.errors[0].message).toContain('separator')
+        }
+      }
+    })
+  })
+
+  describe('collectionSlugSchema', () => {
+    it('validates and brands valid collection slugs', () => {
+      const result = collectionSlugSchema.parse('blog-posts')
+      expect(result).toBe('blog-posts')
+    })
+
+    it('applies same validation as entry slugs', () => {
+      // Valid
+      expect(collectionSlugSchema.parse('posts')).toBe('posts')
+
+      // Invalid
+      expect(() => collectionSlugSchema.parse('')).toThrow()
+      expect(() => collectionSlugSchema.parse('posts/items')).toThrow('separator')
+      expect(() => collectionSlugSchema.parse('Posts')).toThrow('lowercase')
+    })
+  })
+
+  describe('permissionPathSchema', () => {
+    it('validates and brands valid permission paths', () => {
+      const result = permissionPathSchema.parse('content/posts')
+      expect(result).toBe('content/posts')
+    })
+
+    it('accepts nested paths', () => {
+      const result = permissionPathSchema.parse('content/docs/guides')
+      expect(result).toBe('content/docs/guides')
+    })
+
+    it('accepts simple single-segment paths', () => {
+      const result = permissionPathSchema.parse('content')
+      expect(result).toBe('content')
+    })
+
+    it('rejects empty paths', () => {
+      expect(() => permissionPathSchema.parse('')).toThrow()
+    })
+
+    it('rejects paths with traversal sequences', () => {
+      expect(() => permissionPathSchema.parse('../etc/passwd')).toThrow('traversal')
+    })
+
+    it('rejects paths with embedded traversal', () => {
+      expect(() => permissionPathSchema.parse('content/../admin')).toThrow('traversal')
+    })
+
+    it('rejects backslash traversal bypass', () => {
+      expect(() => permissionPathSchema.parse('content\\..\\etc')).toThrow('traversal')
+    })
+
+    it('rejects paths starting with slash', () => {
+      expect(() => permissionPathSchema.parse('/content/posts')).toThrow('slash')
+    })
+
+    it('rejects paths ending with slash', () => {
+      expect(() => permissionPathSchema.parse('content/posts/')).toThrow('slash')
+    })
+
+    it('rejects paths with consecutive slashes', () => {
+      expect(() => permissionPathSchema.parse('content//posts')).toThrow('consecutive slashes')
+    })
+  })
+
+  describe('integration with z.object', () => {
+    it('works in combined schemas', () => {
+      const schema = z.object({
+        branch: branchNameSchema,
+        path: logicalPathSchema,
+        slug: entrySlugSchema,
+      })
+
+      const result = schema.parse({
+        branch: 'main',
+        path: 'content/posts',
+        slug: 'hello-world',
+      })
+
+      expect(result.branch).toBe('main')
+      expect(result.path).toBe('content/posts')
+      expect(result.slug).toBe('hello-world')
+    })
+
+    it('reports multiple validation errors', () => {
+      const schema = z.object({
+        branch: branchNameSchema,
+        path: logicalPathSchema,
+      })
+
+      try {
+        schema.parse({
+          branch: 'my branch',
+          path: 'content/../admin',
+        })
+      } catch (error) {
+        expect(error).toBeInstanceOf(z.ZodError)
+        if (error instanceof z.ZodError) {
+          // Should have errors for both fields
+          expect(error.errors.length).toBeGreaterThanOrEqual(1)
+        }
+      }
+    })
+  })
+})

package/src/api/validators.ts

@@ -0,0 +1,176 @@
+/**
+ * Zod schemas for branded type validation at API boundaries.
+ *
+ * These schemas validate incoming strings from HTTP requests
+ * and cast them to branded types for type-safe handling in API handlers.
+ *
+ * Usage:
+ * ```ts
+ * import { branchNameSchema, logicalPathSchema } from './validators'
+ *
+ * const paramsSchema = z.object({
+ *   branch: branchNameSchema,
+ *   path: logicalPathSchema,
+ * })
+ *
+ * // TypeScript infers branded types automatically
+ * const params = paramsSchema.parse(req.params)
+ * // params.branch is BranchName (not string)
+ * // params.path is LogicalPath (not string)
+ * ```
+ */
+
+import { z } from 'zod'
+import {
+  parseBranchName,
+  parseLogicalPath,
+  parseContentId,
+  parseSlug,
+  type BranchName,
+  type LogicalPath,
+  type ContentId,
+  type EntrySlug,
+  type CollectionSlug,
+} from '../paths'
+import { parsePermissionPath, type PermissionPath } from '../authorization'
+
+/**
+ * Zod schema for BranchName - validates git branch naming rules and brands.
+ *
+ * Validates:
+ * - No empty strings
+ * - No double dots (..)
+ * - No leading/trailing slashes
+ * - No spaces
+ * - No leading/trailing dots
+ * - No @{ sequences
+ */
+export const branchNameSchema = z
+  .string()
+  .min(1)
+  .transform((val, ctx) => {
+    const result = parseBranchName(val)
+    if (!result.ok) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: result.error,
+      })
+      return z.NEVER
+    }
+    return result.name
+  }) as unknown as z.ZodType<BranchName>
+
+/**
+ * Zod schema for LogicalPath - validates and brands logical content paths.
+ *
+ * Validates:
+ * - No empty strings
+ * - No path traversal sequences (..)
+ * - Not a physical path (no embedded content IDs)
+ */
+export const logicalPathSchema = z
+  .string()
+  .min(1)
+  .transform((val, ctx) => {
+    const result = parseLogicalPath(val)
+    if (!result.ok) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: result.error,
+      })
+      return z.NEVER
+    }
+    return result.path
+  }) as unknown as z.ZodType<LogicalPath>
+
+/**
+ * Zod schema for ContentId - validates 12-char Base58 IDs.
+ *
+ * Validates:
+ * - Exactly 12 characters
+ * - Base58 alphabet only (no 0, O, I, l)
+ */
+export const contentIdSchema = z.string().transform((val, ctx) => {
+  const result = parseContentId(val)
+  if (!result.ok) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      message: result.error,
+    })
+    return z.NEVER
+  }
+  return result.id
+}) as unknown as z.ZodType<ContentId>
+
+/**
+ * Zod schema for EntrySlug - validates entry slugs.
+ *
+ * Validates:
+ * - No path separators (/ or \)
+ * - Starts with lowercase letter or number
+ * - Only lowercase letters, numbers, and hyphens
+ * - Max 64 characters
+ */
+export const entrySlugSchema = z
+  .string()
+  .min(1)
+  .transform((val, ctx) => {
+    const result = parseSlug(val, 'entry')
+    if (!result.ok) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: result.error,
+      })
+      return z.NEVER
+    }
+    return result.slug as EntrySlug
+  }) as unknown as z.ZodType<EntrySlug>
+
+/**
+ * Zod schema for CollectionSlug - validates collection slugs.
+ *
+ * Validates:
+ * - No path separators (/ or \)
+ * - Starts with lowercase letter or number
+ * - Only lowercase letters, numbers, and hyphens
+ * - Max 64 characters
+ */
+export const collectionSlugSchema = z
+  .string()
+  .min(1)
+  .transform((val, ctx) => {
+    const result = parseSlug(val, 'collection')
+    if (!result.ok) {
+      ctx.addIssue({
+        code: z.ZodIssueCode.custom,
+        message: result.error,
+      })
+      return z.NEVER
+    }
+    return result.slug as CollectionSlug
+  }) as unknown as z.ZodType<CollectionSlug>
+
+/**
+ * Zod schema for PermissionPath - validates permission rule paths.
+ *
+ * SECURITY: Prevents path traversal attacks in permission rules.
+ *
+ * Validates:
+ * - No path traversal sequences (..)
+ * - No leading/trailing slashes
+ * - No consecutive slashes
+ */
+export 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>

package/src/asset-store.test.ts

@@ -0,0 +1,37 @@
+import fs from 'node:fs/promises'
+import os from 'node:os'
+import path from 'node:path'
+
+import { describe, expect, it } from 'vitest'
+
+import { LocalAssetStore } from './asset-store'
+
+const tmpDir = async () => fs.mkdtemp(path.join(os.tmpdir(), 'canopycms-assets-'))
+
+describe('LocalAssetStore', () => {
+  it('uploads, lists, and deletes assets', async () => {
+    const root = await tmpDir()
+    const store = new LocalAssetStore({
+      root,
+      publicBaseUrl: 'https://cdn.test',
+    })
+
+    const uploaded = await store.upload('images/foo.png', Buffer.from('hello'), 'image/png')
+    expect(uploaded.key).toBe('images/foo.png')
+    expect(uploaded.url).toBe('https://cdn.test/images/foo.png')
+
+    const items = await store.list('images')
+    expect(items).toHaveLength(1)
+    expect(items[0].key).toBe('images/foo.png')
+
+    await store.delete('images/foo.png')
+    const afterDelete = await store.list('images')
+    expect(afterDelete).toHaveLength(0)
+  })
+
+  it('prevents path traversal', async () => {
+    const root = await tmpDir()
+    const store = new LocalAssetStore({ root })
+    await expect(store.upload('../evil.txt', Buffer.from('x'))).rejects.toBeInstanceOf(Error)
+  })
+})

package/src/asset-store.ts

@@ -0,0 +1,110 @@
+import fs from 'node:fs/promises'
+import type { Dirent } from 'node:fs'
+import path from 'node:path'
+
+import { isNotFoundError } from './utils/error'
+
+export interface AssetItem {
+  key: string
+  url?: string
+  size?: number
+  contentType?: string
+  updatedAt?: string
+}
+
+export interface AssetStore {
+  list(prefix?: string): Promise<AssetItem[]>
+  upload(key: string, data: Buffer | Uint8Array, contentType?: string): Promise<AssetItem>
+  delete(key: string): Promise<void>
+  getSignedUrl?(key: string, expiresInSeconds?: number): Promise<string>
+}
+
+export interface LocalAssetStoreOptions {
+  root: string
+  publicBaseUrl?: string
+}
+
+const normalizeKey = (key: string) => key.replace(/^\/+/, '')
+
+/**
+ * Local filesystem asset store for dev and tests. In production, swap with S3 adapter.
+ */
+export class LocalAssetStore implements AssetStore {
+  private readonly root: string
+  private readonly publicBaseUrl?: string
+
+  constructor(options: LocalAssetStoreOptions) {
+    this.root = path.resolve(options.root)
+    this.publicBaseUrl = options.publicBaseUrl?.replace(/\/+$/, '')
+  }
+
+  private resolvePath(key: string): string {
+    const clean = normalizeKey(key)
+    const resolved = path.resolve(this.root, clean)
+    if (!resolved.startsWith(this.root)) {
+      throw new Error('Path traversal detected')
+    }
+    return resolved
+  }
+
+  private toUrl(key: string): string | undefined {
+    if (!this.publicBaseUrl) return undefined
+    return `${this.publicBaseUrl}/${normalizeKey(key)}`
+  }
+
+  async list(prefix = ''): Promise<AssetItem[]> {
+    const dir = this.resolvePath(prefix)
+    let entries: Dirent[]
+    try {
+      entries = await fs.readdir(dir, { withFileTypes: true })
+    } catch (err: unknown) {
+      if (isNotFoundError(err)) return []
+      throw err
+    }
+    const items: AssetItem[] = []
+    for (const entry of entries) {
+      if (entry.isDirectory()) continue
+      const key = path.join(prefix, entry.name).split(path.sep).join('/')
+      const stat = await fs.stat(path.join(dir, entry.name))
+      items.push({
+        key,
+        size: stat.size,
+        updatedAt: stat.mtime.toISOString(),
+        url: this.toUrl(key),
+      })
+    }
+    return items
+  }
+
+  async upload(key: string, data: Buffer | Uint8Array, contentType?: string): Promise<AssetItem> {
+    const filePath = this.resolvePath(key)
+    await fs.mkdir(path.dirname(filePath), { recursive: true })
+    await fs.writeFile(filePath, data)
+    const stat = await fs.stat(filePath)
+    return {
+      key: normalizeKey(key),
+      size: stat.size,
+      updatedAt: stat.mtime.toISOString(),
+      url: this.toUrl(key),
+      contentType,
+    }
+  }
+
+  async delete(key: string): Promise<void> {
+    const filePath = this.resolvePath(key)
+    try {
+      await fs.unlink(filePath)
+    } catch (err: unknown) {
+      if (isNotFoundError(err)) return
+      throw err
+    }
+  }
+
+  async getSignedUrl(key: string): Promise<string> {
+    const url = this.toUrl(key)
+    if (!url) {
+      throw new Error('Public base URL not configured')
+    }
+    return url
+  }
+}

package/src/auth/cache.ts

@@ -0,0 +1,7 @@
+/**
+ * Server-only auth cache exports.
+ * These use node:fs/promises and must NOT be imported in client bundles.
+ * Use 'canopycms/auth/cache' as the import path.
+ */
+export { FileBasedAuthCache, writeAuthCacheSnapshot } from './file-based-auth-cache'
+export { CachingAuthPlugin } from './caching-auth-plugin'