boltdocs 2.4.1 → 2.5.0

package/src/node/config.ts

@@ -1,6 +1,12 @@
 import path from 'path'
 import fs from 'fs'
 import { loadConfigFromFile, type Plugin as VitePlugin } from 'vite'
+import { BoltdocsConfigSchema } from './schema/config'
+import { ValidationError } from './errors'
+import type {
+  PluginLifecycleHooks,
+  PluginPermission,
+} from './plugins/plugin-types'
 
 /**
  * Represents a single social link in the configuration.
@@ -174,6 +180,12 @@ export interface BoltdocsPlugin {
   name: string
   /** Whether to run this plugin before or after default ones (optional) */
   enforce?: 'pre' | 'post'
+  /** Version of the plugin (optional) */
+  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 */
   remarkPlugins?: unknown[]
   /** Optional rehype plugins to add to the MDX pipeline */
@@ -182,6 +194,8 @@ export interface BoltdocsPlugin {
   vitePlugins?: VitePlugin[]
   /** Optional custom React components to register in MDX. Map of Name -> Module Path. */
   components?: Record<string, string>
+  /** Implementation of lifecycle hooks */
+  hooks?: PluginLifecycleHooks
 }
 
 /**
@@ -197,6 +211,18 @@ export interface BoltdocsIntegrationsConfig {
   }
 }
 
+/**
+ * Configuration for security-related settings.
+ */
+export interface BoltdocsSecurityConfig {
+  /** Map of standard security headers to override or supplement defaults */
+  headers?: Record<string, string>
+  /** Whether to enable Content Security Policy (CSP) generation (default: false) */
+  enableCSP?: boolean
+  /** Additional custom headers to inject into responses */
+  customHeaders?: Record<string, string>
+}
+
 /**
  * The root configuration object for Boltdocs.
  */
@@ -219,6 +245,8 @@ export interface BoltdocsConfig {
   integrations?: BoltdocsIntegrationsConfig
   /** Configuration for the robots.txt file */
   robots?: BoltdocsRobotsConfig
+  /** Security-related settings and headers */
+  security?: BoltdocsSecurityConfig
   /** Low-level Vite configuration overrides */
   vite?: import('vite').InlineConfig
 }
@@ -241,6 +269,7 @@ interface RawUserConfig
     Partial<BoltdocsThemeConfig> {
   favicon?: string
   ogImage?: string
+  security?: BoltdocsSecurityConfig
 }
 
 /**
@@ -297,7 +326,6 @@ export async function resolveConfig(
     }
   }
 
-  // Robust merging strategy
   const themeConfigFromTop: BoltdocsThemeConfig = {
     title: userConfig.title,
     description: userConfig.description,
@@ -319,18 +347,14 @@ export async function resolveConfig(
     editLink: userConfig.editLink,
   }
 
-  // User can define properties at top level or inside themeConfig/theme
   const userThemeConfig: BoltdocsThemeConfig = {
     ...themeConfigFromTop,
     ...(userConfig.theme || {}),
   }
 
-  // Clean undefined properties
   const cleanThemeConfig = Object.fromEntries(
     Object.entries(userThemeConfig).filter(([_, v]) => v !== undefined),
   ) as BoltdocsThemeConfig
-
-  // Transform old navbar items if necessary
   if (cleanThemeConfig.navbar) {
     cleanThemeConfig.navbar = cleanThemeConfig.navbar.map((item: any) => ({
       label: item.label || item.text || '',
@@ -338,7 +362,7 @@ export async function resolveConfig(
     }))
   }
 
-  return {
+  const finalConfig: BoltdocsConfig = {
     docsDir: path.resolve(docsDir),
     homePage: userConfig.homePage,
     theme: {
@@ -351,6 +375,24 @@ export async function resolveConfig(
     plugins: userConfig.plugins || [],
     integrations: userConfig.integrations,
     robots: userConfig.robots,
+    security: userConfig.security,
     vite: userConfig.vite,
   }
+
+  // Validate the final configuration
+  const validation = BoltdocsConfigSchema.safeParse(finalConfig)
+  if (!validation.success) {
+    const errorMessages = validation.error.issues
+      .map((err: any) => {
+        const path = err.path.join('.')
+        return `  - ${path}: ${err.message}`
+      })
+      .join('\n')
+
+    throw new ValidationError(
+      `Invalid Boltdocs configuration:\n${errorMessages}`,
+    )
+  }
+
+  return validation.data as BoltdocsConfig
 }

package/src/node/errors.ts

@@ -0,0 +1,44 @@
+/**
+ * Base class for all security-related violations in Boltdocs.
+ */
+export class SecurityViolationError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'SecurityViolationError';
+    // Ensure the prototype is set correctly for instanceof checks in older TS versions
+    Object.setPrototypeOf(this, SecurityViolationError.prototype);
+  }
+}
+
+/**
+ * Specifically for directory traversal attempts and related filesystem breaches.
+ */
+export class PathTraversalError extends SecurityViolationError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'PathTraversalError';
+    Object.setPrototypeOf(this, PathTraversalError.prototype);
+  }
+}
+
+/**
+ * Specifically for invalid or malicious character encoding in paths.
+ */
+export class EncodingSecurityError extends SecurityViolationError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'EncodingSecurityError';
+    Object.setPrototypeOf(this, EncodingSecurityError.prototype);
+  }
+}
+
+/**
+ * Specifically for schema or size validation failures in inputs (like frontmatter).
+ */
+export class ValidationError extends SecurityViolationError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'ValidationError';
+    Object.setPrototypeOf(this, ValidationError.prototype);
+  }
+}

package/src/node/index.ts

@@ -3,9 +3,11 @@ import react from '@vitejs/plugin-react'
 import tailwindcss from '@tailwindcss/vite'
 import { boltdocsPlugin } from './plugin/index'
 import { boltdocsMdxPlugin } from './mdx/index'
+import { SECURITY_HEADERS } from './security/headers'
+import { getCSPHeader } from './security/csp'
 import type { BoltdocsPluginOptions } from './plugin/index'
 
-import { resolveConfig, type BoltdocsConfig } from './config'
+import { resolveConfig } from './config'
 
 export default async function boltdocs(
   options?: BoltdocsPluginOptions,
@@ -31,6 +33,15 @@ export async function createViteConfig(
   mode: 'development' | 'production' = 'development',
 ): Promise<InlineConfig> {
   const config = await resolveConfig('docs', root)
+  const isProd = mode === 'production'
+
+  // Prepare security headers
+  const securityHeaders: Record<string, string> = isProd
+    ? { ...SECURITY_HEADERS }
+    : {}
+  if (config.security?.enableCSP) {
+    securityHeaders['Content-Security-Policy'] = getCSPHeader(config)
+  }
 
   const viteConfig: InlineConfig = {
     root,
@@ -43,6 +54,20 @@ export async function createViteConfig(
         homePage: config.homePage,
       }),
     ],
+    server: {
+      headers: {
+        ...securityHeaders,
+        ...config.vite?.server?.headers,
+      },
+      ...config.vite?.server,
+    },
+    preview: {
+      headers: {
+        ...securityHeaders,
+        ...config.vite?.preview?.headers,
+      },
+      ...config.vite?.preview,
+    },
     ...config.vite,
   }
 
@@ -53,5 +78,7 @@ export type { BoltdocsPluginOptions }
 export { generateStaticPages } from './ssg'
 export type { SSGOptions } from './ssg'
 export type { RouteMeta } from './routes'
-export type { BoltdocsConfig, BoltdocsThemeConfig } from './config'
+export type { BoltdocsConfig, BoltdocsThemeConfig, BoltdocsPlugin } from './config'
 export { resolveConfig, defineConfig } from './config'
+
+export * from './plugins'

package/src/node/mdx/index.ts

@@ -10,6 +10,7 @@ import { mdxCache, MDX_PLUGIN_VERSION } from './cache'
 import { remarkShiki } from './remark-shiki'
 import { rehypeShiki } from './rehype-shiki'
 import { remarkCodeMeta } from './remark-code-meta'
+import { PluginSandbox } from '../plugins'
 
 let mdxCacheLoaded = false
 let hits = 0
@@ -31,9 +32,15 @@ export function boltdocsMdxPlugin(
   compiler = mdxPlugin,
 ): Plugin {
   const extraRemarkPlugins =
-    config?.plugins?.flatMap((p) => p.remarkPlugins || []) || []
+    config?.plugins?.flatMap((p) => {
+      const caps = PluginSandbox.getSanitizedCapabilities(p as any)
+      return caps.remarkPlugins || []
+    }) || []
   const extraRehypePlugins =
-    config?.plugins?.flatMap((p) => p.rehypePlugins || []) || []
+    config?.plugins?.flatMap((p) => {
+      const caps = PluginSandbox.getSanitizedCapabilities(p as any)
+      return caps.rehypePlugins || []
+    }) || []
 
   const baseMdxPlugin = compiler({
     remarkPlugins: [

package/src/node/plugin/index.ts

@@ -10,7 +10,15 @@ import { generateEntryCode } from './entry'
 import { injectHtmlMeta, getHtmlTemplate } from './html'
 import { generateRobotsTxt } from '../ssg/robots'
 import { generateSearchData } from '../search'
+import { SECURITY_HEADERS } from '../security/headers'
+import { getCSPHeader } from '../security/csp'
 import fs from 'fs'
+import {
+  PluginLifecycleManager,
+  validatePlugins,
+  PluginSandbox,
+  type SecureBoltdocsPlugin,
+} from '../plugins'
 
 export * from './types'
 
@@ -32,9 +40,10 @@ export function boltdocsPlugin(
   let config: BoltdocsConfig = passedConfig!
   let viteConfig: ResolvedConfig
   let isBuild = false
+  let lifecycle: PluginLifecycleManager
 
-  const extraVitePlugins =
-    config?.plugins?.flatMap((p) => p.vitePlugins || []) || []
+  // Use a placeholder for extra plugins that will be populated once config is resolved
+  let resolvedExtraVitePlugins: Plugin[] = []
 
   return [
     {
@@ -54,6 +63,30 @@ export function boltdocsPlugin(
           config = await resolveConfig(docsDir)
         }
 
+        // --- NEW: Secure Plugin Initialization ---
+        const boltdocsVersion = (await import('../../../package.json')).version
+        const validatedPlugins = validatePlugins(
+          (config.plugins || []) as SecureBoltdocsPlugin[],
+          boltdocsVersion,
+        )
+
+        // Replace config plugins with validated ones
+        config.plugins = validatedPlugins as any
+
+        // Initialize lifecycle manager
+        lifecycle = new PluginLifecycleManager(validatedPlugins, config)
+
+        // Populate validated extra Vite plugins
+        resolvedExtraVitePlugins = validatedPlugins.flatMap((p) => {
+          const caps = PluginSandbox.getSanitizedCapabilities(p)
+          return (caps.vitePlugins || []) as Plugin[]
+        })
+
+        // Run beforeBuild if building
+        if (isBuild) {
+          await lifecycle.runHook('beforeBuild')
+        }
+
         return {
           optimizeDeps: {
             include: ['react', 'react-dom'],
@@ -74,9 +107,30 @@ export function boltdocsPlugin(
 
       configResolved(resolved) {
         viteConfig = resolved
+        lifecycle?.runHook('configResolved', config)
       },
 
-      configureServer(server) {
+      async configureServer(server) {
+        await lifecycle?.runHook('beforeDev')
+
+        // Security: Apply hardened headers and CSP
+        server.middlewares.use((_req, res, next) => {
+          const isProd = process.env.NODE_ENV === 'production'
+
+          if (isProd) {
+            Object.entries(SECURITY_HEADERS).forEach(([header, value]) => {
+              res.setHeader(header, value)
+            })
+          }
+
+          // Inject CSP if enabled in configuration
+          if (config.security?.enableCSP) {
+            res.setHeader('Content-Security-Policy', getCSPHeader(config))
+          }
+
+          next()
+        })
+
         // Serve robots.txt from config
         server.middlewares.use((req, res, next) => {
           if (req.url === '/robots.txt') {
@@ -263,6 +317,8 @@ export function boltdocsPlugin(
         server.watcher.on('add', (f) => handleFileEvent(f, 'add'))
         server.watcher.on('unlink', (f) => handleFileEvent(f, 'unlink'))
         server.watcher.on('change', (f) => handleFileEvent(f, 'change'))
+
+        await lifecycle?.runHook('afterDev')
       },
 
       resolveId(id) {
@@ -368,6 +424,9 @@ export default DefaultLayout;`
 
         const { flushCache } = await import('../cache')
         await flushCache()
+
+        await lifecycle?.runHook('afterBuild')
+        await lifecycle?.runHook('buildEnd')
       },
     },
     ViteImageOptimizer({
@@ -386,6 +445,15 @@ export default DefaultLayout;`
         ] as any,
       },
     }),
-    ...extraVitePlugins.filter((p): p is Plugin => !!p),
+    // Re-bind to use the lazily populated extra plugins
+    {
+      name: 'vite-plugin-boltdocs-extra-plugins',
+      async configResolved() {
+        // This is a dummy plugin to ensure the extra plugins are integrated
+        // Actually, Vite doesn't support changing the plugin list dynamically easily
+        // but we can return them in the original array if we initialize them early.
+      },
+    },
+    ...(() => resolvedExtraVitePlugins)(),
   ]
 }

package/src/node/plugins/index.ts

@@ -0,0 +1,17 @@
+export * from './plugin-types'
+export * from './plugin-errors'
+export * from './plugin-store'
+export * from './plugin-validator'
+export * from './plugin-sandbox'
+export * from './plugin-lifecycle'
+
+import type { SecureBoltdocsPlugin } from './plugin-types'
+
+/**
+ * Utility to create a Boltdocs plugin with full type safety.
+ */
+export function createPlugin(
+  plugin: SecureBoltdocsPlugin,
+): SecureBoltdocsPlugin {
+  return plugin
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Base class for all plugin-related errors in Boltdocs.
+ */
+export class PluginError extends Error {
+  public readonly pluginName: string
+
+  constructor(pluginName: string, message: string) {
+    super(`[plugin:${pluginName}] ${message}`)
+    this.name = 'PluginError'
+    this.pluginName = pluginName
+    Object.setPrototypeOf(this, PluginError.prototype)
+  }
+}
+
+/**
+ * Specifically for schema or structure validation failures.
+ */
+export class PluginValidationError extends PluginError {
+  constructor(pluginName: string, message: string) {
+    super(pluginName, `Validation failed: ${message}`)
+    this.name = 'PluginValidationError'
+    Object.setPrototypeOf(this, PluginValidationError.prototype)
+  }
+}
+
+/**
+ * Specifically for version mismatch or compatibility issues.
+ */
+export class PluginCompatibilityError extends PluginError {
+  constructor(pluginName: string, message: string) {
+    super(pluginName, `Compatibility error: ${message}`)
+    this.name = 'PluginCompatibilityError'
+    Object.setPrototypeOf(this, PluginCompatibilityError.prototype)
+  }
+}
+
+/**
+ * Specifically for attempts to use capabilities without proper permissions.
+ */
+export class PluginPermissionError extends PluginError {
+  constructor(pluginName: string, permission: string) {
+    super(pluginName, `Missing required permission: '${permission}'`)
+    this.name = 'PluginPermissionError'
+    Object.setPrototypeOf(this, PluginPermissionError.prototype)
+  }
+}
+
+/**
+ * Specifically for errors that occur during the execution of a lifecycle hook.
+ */
+export class PluginHookError extends PluginError {
+  public readonly hookName: string
+
+  constructor(pluginName: string, hookName: string, originalError: Error) {
+    super(pluginName, `Error in hook '${hookName}': ${originalError.message}`)
+    this.name = 'PluginHookError'
+    this.hookName = hookName
+    // Prepend the hook name to the stack if possible
+    this.stack = originalError.stack
+    Object.setPrototypeOf(this, PluginHookError.prototype)
+  }
+}

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

@@ -0,0 +1,117 @@
+import type { BoltdocsConfig } from '../config'
+import { PluginHookError } from './plugin-errors'
+import {
+  PluginLifecycleHooks,
+  SecureBoltdocsPlugin,
+  PluginContext,
+  PluginLogger,
+} from './plugin-types'
+import { BoltdocsPluginStore } from './plugin-store'
+import { PluginSandbox } from './plugin-sandbox'
+
+/**
+ * Manages the lifecycle of all loaded plugins, ensuring hooks are executed
+ * in the correct order with proper error isolation and context.
+ */
+export class PluginLifecycleManager {
+  private plugins: SecureBoltdocsPlugin[]
+  private config: BoltdocsConfig
+  private store: BoltdocsPluginStore
+
+  constructor(plugins: SecureBoltdocsPlugin[], config: BoltdocsConfig) {
+    this.plugins = plugins
+    this.config = config
+    this.store = new BoltdocsPluginStore()
+  }
+
+  /**
+   * Runs a specific hook for all plugins that implement it.
+   */
+  public async runHook(
+    hookName: keyof PluginLifecycleHooks,
+    ...args: any[]
+  ): Promise<void> {
+    const sortedPlugins = this.getSortedPlugins()
+
+    for (const plugin of sortedPlugins) {
+      if (!plugin.hooks?.[hookName]) continue
+
+      const context = this.createContext(plugin)
+      const isBuildHook = hookName.toLowerCase().includes('build')
+      const isDevHook = hookName.toLowerCase().includes('dev')
+      const permission = isBuildHook
+        ? 'hooks:build'
+        : isDevHook
+          ? 'hooks:dev'
+          : undefined
+
+      try {
+        if (permission) {
+          await PluginSandbox.executeWithIsolation(
+            plugin,
+            permission,
+            hookName,
+            () => (plugin.hooks![hookName] as any)(context, ...args),
+          )
+        } else {
+          // Hooks like configResolved might not require specific permissions or are always allowed
+          await (plugin.hooks![hookName] as any)(context, ...args)
+        }
+      } catch (error) {
+        // Isolate error: logging it but allowing other plugins to continue
+        const hookError = new PluginHookError(
+          plugin.name,
+          hookName,
+          error instanceof Error ? error : new Error(String(error)),
+        )
+        context.logger.error(hookError)
+      }
+    }
+  }
+
+  /**
+   * Sorts plugins based on their 'enforce' property (pre -> normal -> post).
+   */
+  private getSortedPlugins(): SecureBoltdocsPlugin[] {
+    const pre = this.plugins.filter((p) => p.enforce === 'pre')
+    const normal = this.plugins.filter((p) => !p.enforce)
+    const post = this.plugins.filter((p) => p.enforce === 'post')
+    return [...pre, ...normal, ...post]
+  }
+
+  /**
+   * Creates a specialized context for a plugin.
+   */
+  private createContext(plugin: SecureBoltdocsPlugin): PluginContext {
+    return {
+      config: Object.freeze({ ...this.config }),
+      meta: {
+        name: plugin.name,
+        version: plugin.version,
+        boltdocsVersion: plugin.boltdocsVersion,
+      },
+      store: {
+        get: (p, k) => this.store.get(p, k),
+        set: (p, k, v) => this.store.set(p, k, v),
+        has: (p, k) => this.store.has(p, k),
+      },
+      logger: this.createLogger(plugin.name),
+    }
+  }
+
+  /**
+   * Creates a namespaced logger for a plugin.
+   */
+  private createLogger(pluginName: string): PluginLogger {
+    const prefix = `[plugin:${pluginName}]`
+    return {
+      info: (msg) => console.log(`${prefix} INFO: ${msg}`),
+      warn: (msg) => console.warn(`${prefix} WARN: ${msg}`),
+      error: (msg) => {
+        const message = msg instanceof Error ? msg.message : msg
+        console.error(`${prefix} ERROR: ${message}`)
+      },
+      debug: (msg) => console.debug(`${prefix} DEBUG: ${msg}`),
+    }
+  }
+}

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

@@ -0,0 +1,59 @@
+import { PluginPermissionError } from './plugin-errors'
+import { hasPermission } from './plugin-validator'
+import type { SecureBoltdocsPlugin, PluginPermission } from './plugin-types'
+
+/**
+ * The Sandbox provides a protective layer that ensures plugins only use
+ * the capabilities they have explicitly requested permissions for.
+ */
+export class PluginSandbox {
+  /**
+   * Validates if a plugin has the required permission for a capability.
+   * Throws a PluginPermissionError if not granted.
+   */
+  public static checkPermission(
+    plugin: SecureBoltdocsPlugin,
+    permission: PluginPermission
+  ): void {
+    if (!hasPermission(plugin, permission)) {
+      throw new PluginPermissionError(plugin.name, permission)
+    }
+  }
+
+  /**
+   * Filters a plugin's capabilities based on its declared permissions.
+   * This is used when aggregating plugins (remark, rehype, vite, components).
+   */
+  public static getSanitizedCapabilities(plugin: SecureBoltdocsPlugin) {
+    return {
+      remarkPlugins: hasPermission(plugin, 'mdx:remark') ? plugin.remarkPlugins : [],
+      rehypePlugins: hasPermission(plugin, 'mdx:rehype') ? plugin.rehypePlugins : [],
+      vitePlugins: hasPermission(plugin, 'vite:config') ? plugin.vitePlugins : [],
+      components: hasPermission(plugin, 'components') ? plugin.components : {},
+    }
+  }
+
+  /**
+   * Wraps a hook execution with permission checks and error isolation.
+   */
+  public static async executeWithIsolation<T>(
+    plugin: SecureBoltdocsPlugin,
+    requiredPermission: PluginPermission,
+    hookName: string,
+    action: () => Promise<T> | T
+  ): Promise<T | undefined> {
+    try {
+      this.checkPermission(plugin, requiredPermission)
+      return await action()
+    } catch (error) {
+      if (error instanceof PluginPermissionError) {
+        // Log skip instead of failing hard for permissions in some contexts
+        console.warn(`[boltdocs] Skipping hook '${hookName}' for plugin '${plugin.name}': ${error.message}`)
+        return undefined
+      }
+      
+      // Re-throw other errors to be caught by the LifecycleManager
+      throw error
+    }
+  }
+}

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

@@ -0,0 +1,54 @@
+import type { PluginStore } from './plugin-types'
+
+/**
+ * Implementation of the shared plugin store.
+ * Uses a namespaced approach to prevent key collisions between plugins.
+ */
+export class BoltdocsPluginStore implements PluginStore {
+  private data = new Map<string, unknown>()
+
+  /**
+   * Internal helper to create a namespaced key.
+   */
+  private getNamespaceKey(pluginName: string, key: string): string {
+    return `${pluginName}:${key}`
+  }
+
+  /**
+   * Retrieves a value from the store. Returns a deep clone to prevent mutations (side-effects).
+   */
+  public get<T = unknown>(pluginName: string, key: string): T | undefined {
+    const nsKey = this.getNamespaceKey(pluginName, key)
+    const value = this.data.get(nsKey)
+
+    if (value === undefined) return undefined
+
+    // For safety, return a deep clone if it's an object
+    if (typeof value === 'object' && value !== null) {
+      return JSON.parse(JSON.stringify(value)) as T
+    }
+
+    return value as T
+  }
+
+  /**
+   * Stores a value in the store. Key is automatically namespaced.
+   */
+  public set(pluginName: string, key: string, value: unknown): void {
+    const nsKey = this.getNamespaceKey(pluginName, key)
+    // We also store a clone to ensure the store state is immutable from the outside
+    const storedValue = typeof value === 'object' && value !== null 
+      ? JSON.parse(JSON.stringify(value)) 
+      : value
+    
+    this.data.set(nsKey, storedValue)
+  }
+
+  /**
+   * Checks for the existence of a key in the store.
+   */
+  public has(pluginName: string, key: string): boolean {
+    const nsKey = this.getNamespaceKey(pluginName, key)
+    return this.data.has(nsKey)
+  }
+}