boltdocs 2.4.1 → 2.5.0

package/src/node/plugins/plugin-types.ts

@@ -0,0 +1,107 @@
+import type { Plugin as VitePlugin } from 'vite'
+import type { BoltdocsConfig } from '../config'
+
+/**
+ * Permissions that a plugin can request to access specific Boltdocs capabilities.
+ */
+export type PluginPermission =
+  | 'fs:read'      // Read filesystem
+  | 'fs:write'     // Write filesystem
+  | 'vite:config'  // Modify Vite config
+  | 'mdx:remark'   // Add remark plugins
+  | 'mdx:rehype'   // Add rehype plugins
+  | 'components'   // Register MDX components
+  | 'hooks:build'  // Access build lifecycle hooks
+  | 'hooks:dev'    // Access dev lifecycle hooks
+
+/**
+ * Shared context injected into every plugin lifecycle hook.
+ */
+export interface PluginContext {
+  /** The full, resolved Boltdocs configuration (Readonly) */
+  readonly config: BoltdocsConfig
+  /** A plugin-specific logger */
+  readonly logger: PluginLogger
+  /** A shared store for dependency injection and state sharing between plugins */
+  readonly store: PluginStore
+  /** Metadata about the current plugin */
+  readonly meta: PluginMeta
+}
+
+/**
+ * Simple logger interface for plugins.
+ */
+export interface PluginLogger {
+  info(message: string): void
+  warn(message: string): void
+  error(message: string | Error): void
+  debug(message: string): void
+}
+
+/**
+ * A shared key-value store that allows plugins to share state and configuration.
+ */
+export interface PluginStore {
+  /** Get a value from the store. Keys are namespaced by plugin internally. */
+  get<T = unknown>(pluginName: string, key: string): T | undefined
+  /** Set a value in the store. */
+  set(pluginName: string, key: string, value: unknown): void
+  /** Check if a key exists in the store. */
+  has(pluginName: string, key: string): boolean
+}
+
+/**
+ * Metadata for a plugin, used for identification and compatibility checks.
+ */
+export interface PluginMeta {
+  /** Unique identifier for the plugin */
+  name: string
+  /** Version of the plugin itself (semver) */
+  version?: string
+  /** Minimum required version of Boltdocs (semver range) */
+  boltdocsVersion?: string
+}
+
+/**
+ * Lifecycle hooks that a plugin can implement to hook into the build and dev processes.
+ */
+export interface PluginLifecycleHooks {
+  /** Called before the build process starts */
+  beforeBuild?: (ctx: PluginContext) => Promise<void> | void
+  /** Called after the build process finishes successfully */
+  afterBuild?: (ctx: PluginContext) => Promise<void> | void
+  /** Called before the dev server starts */
+  beforeDev?: (ctx: PluginContext) => Promise<void> | void
+  /** Called after the dev server is ready (configureServer) */
+  afterDev?: (ctx: PluginContext) => Promise<void> | void
+  /** Called when the final Boltdocs config is resolved */
+  configResolved?: (ctx: PluginContext, config: BoltdocsConfig) => void
+  /** Called when the build is closing */
+  buildEnd?: (ctx: PluginContext) => Promise<void> | void
+}
+
+/**
+ * The extended, secure Boltdocs plugin interface.
+ */
+export interface SecureBoltdocsPlugin {
+  /** A unique name for the plugin (e.g., 'boltdocs-plugin-mermaid') */
+  name: string
+  /** Whether to run this plugin before or after default ones */
+  enforce?: 'pre' | 'post'
+  /** Version of the plugin (optional, but recommended for security) */
+  version?: string
+  /** Minimum compatible Boltdocs version (optional, semver range) */
+  boltdocsVersion?: string
+  /** List of permissions this plugin requires to operate */
+  permissions?: PluginPermission[]
+  /** Optional remark plugins to add to the MDX pipeline (requires 'mdx:remark' permission) */
+  remarkPlugins?: unknown[]
+  /** Optional rehype plugins to add to the MDX pipeline (requires 'mdx:rehype' permission) */
+  rehypePlugins?: unknown[]
+  /** Optional Vite plugins to inject into the build process (requires 'vite:config' permission) */
+  vitePlugins?: VitePlugin[]
+  /** Optional custom React components to register in MDX. Map of Name -> Module Path. (requires 'components' permission) */
+  components?: Record<string, string>
+  /** Implementation of lifecycle hooks (requires 'hooks:build' or 'hooks:dev' permissions) */
+  hooks?: PluginLifecycleHooks
+}

package/src/node/plugins/plugin-validator.ts

@@ -0,0 +1,105 @@
+import { z } from 'zod'
+import semver from 'semver'
+import path from 'path'
+import { BoltdocsPluginSchema } from '../schema/config'
+import {
+  PluginValidationError,
+  PluginCompatibilityError,
+} from './plugin-errors'
+import type { SecureBoltdocsPlugin, PluginPermission } from './plugin-types'
+
+/**
+ * Enhanced Zod schema for secure plugins.
+ */
+export const SecurePluginSchema = BoltdocsPluginSchema.extend({
+  version: z.string().optional(),
+  boltdocsVersion: z.string().optional(),
+  permissions: z.array(z.string()).optional(),
+  hooks: z
+    .object({
+      beforeBuild: z.function().optional(),
+      afterBuild: z.function().optional(),
+      beforeDev: z.function().optional(),
+      afterDev: z.function().optional(),
+      configResolved: z.function().optional(),
+      buildEnd: z.function().optional(),
+    })
+    .optional(),
+})
+
+/**
+ * Validates a list of plugins for correctness, security, and compatibility.
+ */
+export function validatePlugins(
+  plugins: any[],
+  boltdocsVersion: string,
+): SecureBoltdocsPlugin[] {
+  const validatedPlugins: SecureBoltdocsPlugin[] = []
+  const pluginNames = new Set<string>()
+
+  for (const rawPlugin of plugins) {
+    // 1. Basic Structure Validation
+    const result = SecurePluginSchema.safeParse(rawPlugin)
+    if (!result.success) {
+      throw new PluginValidationError(
+        rawPlugin.name || 'unknown',
+        result.error.issues
+          .map((i) => `${i.path.join('.')}: ${i.message}`)
+          .join(', '),
+      )
+    }
+
+    const plugin = result.data as SecureBoltdocsPlugin
+
+    // 2. Name Uniqueness
+    if (pluginNames.has(plugin.name)) {
+      throw new PluginValidationError(
+        plugin.name,
+        'Duplicate plugin name detected',
+      )
+    }
+    pluginNames.add(plugin.name)
+
+    // 3. Semver Compatibility
+    if (
+      plugin.boltdocsVersion &&
+      !semver.satisfies(boltdocsVersion, plugin.boltdocsVersion)
+    ) {
+      throw new PluginCompatibilityError(
+        plugin.name,
+        `Plugin expects Boltdocs version ${plugin.boltdocsVersion}, but current is ${boltdocsVersion}`,
+      )
+    }
+
+    // 4. Component Path Security (Path Traversal Prevention)
+    if (plugin.components) {
+      for (const [compName, compPath] of Object.entries(plugin.components)) {
+        if (compPath.includes('..') || path.isAbsolute(compPath)) {
+          // Absolute paths are technically okay but we restrict them for consistency/security
+          // if they point outside the workspace. For now, we block '..' explicitly.
+          if (compPath.includes('..')) {
+            throw new PluginValidationError(
+              plugin.name,
+              `Component '${compName}' has an invalid path: traversal sequences are not allowed.`,
+            )
+          }
+        }
+      }
+    }
+
+    validatedPlugins.push(plugin)
+  }
+
+  return validatedPlugins
+}
+
+/**
+ * Helper to check if a specific permission is granted to a plugin.
+ */
+export function hasPermission(
+  plugin: SecureBoltdocsPlugin,
+  permission: PluginPermission,
+): boolean {
+  if (!plugin.permissions) return false
+  return plugin.permissions.includes(permission)
+}

package/src/node/routes/parser.ts

@@ -11,7 +11,10 @@ import {
   extractNumberPrefix,
   sanitizeHtml,
   stripHtmlTags,
+  logSecurityEvent,
 } from '../utils'
+import { MAX_PATH_LENGTH, ALLOWED_PATH_CHARS } from '../security/constants'
+import { EncodingSecurityError, PathTraversalError } from '../errors'
 
 /**
  * Parses a single Markdown/MDX file and extracts its metadata for routing.
@@ -32,8 +35,30 @@ export function parseDocFile(
   basePath: string,
   config?: BoltdocsConfig,
 ): ParsedDocFile {
-  // Security: Prevent path traversal
-  const decodedFile = decodeURIComponent(file)
+  // Security: Prevent path traversal and malicious encoding
+  let decodedFile: string
+  try {
+    decodedFile = decodeURIComponent(file)
+  } catch {
+    const fileName = path.basename(file)
+    logSecurityEvent('ENCODING_ERROR', 'Invalid character encoding', { file: fileName })
+    throw new EncodingSecurityError(
+      `Security breach: Invalid characters or encoding in path: ${fileName}`,
+    )
+  }
+
+  // Validation: Path length
+  if (decodedFile.length > MAX_PATH_LENGTH) {
+    const fileName = path.basename(decodedFile)
+    logSecurityEvent('PATH_TOO_LONG', 'Path length exceeds limit', {
+      length: decodedFile.length,
+      file: fileName,
+    })
+    throw new PathTraversalError(
+      `Security breach: Path length exceeds limit of ${MAX_PATH_LENGTH} characters: ${fileName}`,
+    )
+  }
+
   const absoluteFile = path.resolve(decodedFile)
   const absoluteDocsDir = path.resolve(docsDir)
   const relativePath = normalizePath(
@@ -43,10 +68,15 @@ export function parseDocFile(
   if (
     relativePath.startsWith('../') ||
     relativePath === '..' ||
-    absoluteFile.includes('\0')
+    absoluteFile.includes('\0') ||
+    !ALLOWED_PATH_CHARS.test(relativePath)
   ) {
-    throw new Error(
-      `Security breach: File is outside of docs directory or contains null bytes: ${file}`,
+    const fileName = path.basename(file)
+    logSecurityEvent('PATH_TRAVERSAL_ATTEMPT', 'Path traversal or invalid characters detected', {
+      path: relativePath,
+    })
+    throw new PathTraversalError(
+      `Security breach: File is outside of docs directory, contains null bytes, or invalid characters: ${fileName}`,
     )
   }
 

package/src/node/schema/config.ts

@@ -0,0 +1,208 @@
+import { z } from 'zod'
+
+/**
+ * Zod schema for a single social link.
+ */
+export const SocialLinkSchema = z.object({
+  icon: z.string().max(50),
+  link: z.string().url(),
+})
+
+/**
+ * Zod schema for footer configuration.
+ */
+export const FooterConfigSchema = z.object({
+  text: z.string().max(2000).optional(),
+})
+
+/**
+ * Zod schema for plugin permissions.
+ */
+export const PluginPermissionSchema = z.enum([
+  'fs:read',
+  'fs:write',
+  'vite:config',
+  'mdx:remark',
+  'mdx:rehype',
+  'components',
+  'hooks:build',
+  'hooks:dev',
+])
+
+/**
+ * Zod schema for a Boltdocs plugin.
+ */
+export const BoltdocsPluginSchema = z.object({
+  name: z.string(),
+  enforce: z.enum(['pre', 'post']).optional(),
+  version: z.string().optional(),
+  boltdocsVersion: z.string().optional(),
+  permissions: z.array(PluginPermissionSchema).optional(),
+  remarkPlugins: z.array(z.any()).optional(),
+  rehypePlugins: z.array(z.any()).optional(),
+  vitePlugins: z.array(z.any()).optional(),
+  components: z.record(z.string(), z.string()).optional(),
+  hooks: z.record(z.string(), z.any()).optional(),
+})
+
+/**
+ * Zod schema for theme configuration.
+ */
+export const ThemeConfigSchema = z.object({
+  title: z.union([z.string(), z.record(z.string(), z.string())]).optional(),
+  description: z.union([z.string(), z.record(z.string(), z.string())]).optional(),
+  logo: z
+    .union([
+      z.string(),
+      z.object({
+        dark: z.string(),
+        light: z.string(),
+        alt: z.string().optional(),
+        width: z.number().optional(),
+        height: z.number().optional(),
+      }),
+    ])
+    .optional(),
+  navbar: z
+    .array(
+      z.object({
+        label: z.union([z.string(), z.record(z.string(), z.string())]),
+        href: z.string(),
+      }),
+    )
+    .optional(),
+  sidebar: z
+    .record(
+      z.string(),
+      z.array(
+        z.object({
+          text: z.string(),
+          link: z.string(),
+        }),
+      ),
+    )
+    .optional(),
+  socialLinks: z.array(SocialLinkSchema).optional(),
+  footer: FooterConfigSchema.optional(),
+  breadcrumbs: z.boolean().optional(),
+  editLink: z.string().refine(val => !val || val.includes(':path'), {
+    message: "editLink must contain ':path' placeholder if specified"
+  }).optional(),
+  communityHelp: z.string().url().optional(),
+  version: z.string().max(50).optional(),
+  githubRepo: z.string().max(100).optional(),
+  favicon: z.string().optional(),
+  ogImage: z.string().optional(),
+  poweredBy: z.boolean().optional(),
+  tabs: z
+    .array(
+      z.object({
+        id: z.string(),
+        text: z.union([z.string(), z.record(z.string(), z.string())]),
+        icon: z.string().optional(),
+      }),
+    )
+    .optional(),
+  codeTheme: z
+    .union([z.string(), z.object({ light: z.string(), dark: z.string() })])
+    .optional(),
+  copyMarkdown: z
+    .union([
+      z.boolean(),
+      z.object({
+        text: z.string().optional(),
+        icon: z.string().optional(),
+      }),
+    ])
+    .optional(),
+})
+
+/**
+ * Zod schema for robots.txt configuration.
+ */
+export const RobotsConfigSchema = z.union([
+  z.string(),
+  z.object({
+    rules: z
+      .array(
+        z.object({
+          userAgent: z.string(),
+          allow: z.union([z.string(), z.array(z.string())]).optional(),
+          disallow: z.union([z.string(), z.array(z.string())]).optional(),
+        }),
+      )
+      .optional(),
+    sitemaps: z.array(z.string().url()).optional(),
+  }),
+])
+
+/**
+ * Zod schema for internationalization configuration.
+ */
+export const I18nConfigSchema = z.object({
+  defaultLocale: z.string(),
+  locales: z.record(z.string(), z.string()),
+  localeConfigs: z
+    .record(
+      z.string(),
+      z.object({
+        label: z.string().optional(),
+        direction: z.enum(['ltr', 'rtl']).optional(),
+        htmlLang: z.string().optional(),
+        calendar: z.string().optional(),
+      }),
+    )
+    .optional(),
+})
+
+/**
+ * Zod schema for versioning configuration.
+ */
+export const VersionsConfigSchema = z.object({
+  defaultVersion: z.string(),
+  prefix: z.string().optional(),
+  versions: z.array(
+    z.object({
+      label: z.string(),
+      path: z.string(),
+    }),
+  ),
+})
+
+/**
+ * Zod schema for security configuration.
+ */
+export const SecurityConfigSchema = z.object({
+  headers: z.record(z.string(), z.string()).optional(),
+  enableCSP: z.boolean().optional(),
+  customHeaders: z.record(z.string(), z.string()).optional(),
+})
+
+/**
+ * Zod schema for integrations configuration.
+ */
+export const IntegrationsConfigSchema = z.object({
+  sandbox: z
+    .object({
+      enable: z.boolean().optional(),
+      config: z.record(z.string(), z.unknown()).optional(),
+    })
+    .optional(),
+})
+
+/**
+ * Root Zod schema for Boltdocs project configuration.
+ */
+export const BoltdocsConfigSchema = z.object({
+  siteUrl: z.string().url().optional(),
+  docsDir: z.string().optional(),
+  homePage: z.string().optional(),
+  theme: ThemeConfigSchema.optional(),
+  i18n: I18nConfigSchema.optional(),
+  versions: VersionsConfigSchema.optional(),
+  plugins: z.array(BoltdocsPluginSchema).optional(),
+  integrations: IntegrationsConfigSchema.optional(),
+  robots: RobotsConfigSchema.optional(),
+  security: SecurityConfigSchema.optional(),
+  vite: z.record(z.string(), z.unknown()).optional(),
+})

package/src/node/schema/frontmatter.ts

@@ -0,0 +1,17 @@
+import { z } from 'zod'
+
+/**
+ * Schema for strict frontmatter validation.
+ */
+export const FrontmatterSchema = z.object({
+  title: z.string().max(200).optional(),
+  description: z.string().max(500).optional(),
+  sidebarPosition: z.number().optional(),
+  sidebarLabel: z.string().max(100).optional(),
+  category: z.string().max(50).optional(),
+  order: z.number().optional(),
+  badge: z.string().max(50).optional(),
+  icon: z.string().max(50).optional(),
+})
+
+export type FrontmatterData = z.infer<typeof FrontmatterSchema>

package/src/node/security/constants/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Security limits for file system operations.
+ */
+export const MAX_PATH_LENGTH = 260
+export const ALLOWED_PATH_CHARS = /^[a-zA-Z0-9\-_\/\.\(\)]+$/
+
+/**
+ * Security limits for document metadata (frontmatter).
+ */
+export const MAX_FRONTMATTER_SIZE = 10 * 1024 // 10KB

package/src/node/security/csp.ts

@@ -0,0 +1,31 @@
+import type { BoltdocsConfig } from '../config'
+
+/**
+ * Generates a Content Security Policy (CSP) header string based on the configuration.
+ * Automatically adapts to the environment (development vs production).
+ * 
+ * @param config - The Boltdocs configuration object.
+ * @returns The CSP header value.
+ */
+export function getCSPHeader(_config: BoltdocsConfig): string {
+  const isDev = process.env.NODE_ENV === 'development'
+  
+  const directives: Record<string, string[]> = {
+    'default-src': ["'self'"],
+    'script-src': ["'self'", "'unsafe-inline'"],
+    'style-src': ["'self'", "'unsafe-inline'"],
+    'img-src': ["'self'", "data:", "https:"],
+    'font-src': ["'self'"],
+    'connect-src': ["'self'"],
+  }
+
+  // Relax policies in development to support Vite's HMR (eval-based)
+  if (isDev) {
+    directives['script-src'] = ["'self'", "'unsafe-eval'", "'unsafe-inline'"]
+    directives['style-src'] = ["'self'", "'unsafe-inline'"]
+  }
+
+  return Object.entries(directives)
+    .map(([key, values]) => `${key} ${values.join(' ')}`)
+    .join('; ')
+}

package/src/node/security/headers.ts

@@ -0,0 +1,27 @@
+/**
+ * Standard Security Headers for hardened web applications.
+ * Recommended by OWASP and industry best practices to prevent common web attacks.
+ * 
+ * These can be applied as middleware in HTTP servers or as metadata in SSG deployments.
+ */
+export const SECURITY_HEADERS = {
+  /** Prevents MIME type sniffing by the browser. */
+  'X-Content-Type-Options': 'nosniff',
+  
+  /** Prevents the page from being embedded in iframes (anti-clickjacking). */
+  'X-Frame-Options': 'DENY',
+  
+  /** Enables XSS filtering in modern browsers (legacy support). */
+  'X-XSS-Protection': '1; mode=block',
+  
+  /** Controls how much referrer information is sent with requests. */
+  'Referrer-Policy': 'strict-origin-when-cross-origin',
+  
+  /** Restricts access to sensitive browser features (camera, mic, geo). */
+  'Permissions-Policy': 'camera=(), microphone=(), geolocation=()',
+  
+  /** Enforces HTTPS for the domain and all subdomains for 1 year. */
+  'Strict-Transport-Security': 'max-age=31536000; includeSubDomains',
+} as const;
+
+export type SecurityHeaderKey = keyof typeof SECURITY_HEADERS;