specra 0.1.13 → 0.2.0

package/dist/mdx-security.d.ts

@@ -0,0 +1,76 @@
+/**
+ * MDX Security Layer
+ *
+ * Protects against:
+ * - XSS via malicious MDX expressions
+ * - Path traversal attacks
+ * - Dangerous component usage
+ * - Cross-domain vulnerabilities
+ */
+/**
+ * Sanitize file paths to prevent path traversal attacks
+ * Blocks: ../, ..\, absolute paths, encoded traversal attempts
+ */
+export declare function sanitizePath(userPath: string): string;
+/**
+ * Validate that a file path is within allowed directory
+ */
+export declare function validatePathWithinDirectory(filePath: string, allowedDir: string): boolean;
+/**
+ * Scan MDX content for dangerous patterns
+ * Returns array of detected issues
+ * Note: Skips content inside code blocks to avoid false positives
+ */
+export declare function scanMDXForDangerousPatterns(content: string): string[];
+/**
+ * Sanitize MDX content by removing/escaping dangerous patterns
+ * This is a defensive measure - ideally content should be rejected if dangerous
+ */
+export declare function sanitizeMDXContent(content: string, strict?: boolean): string;
+/**
+ * Content Security Policy configuration
+ * Use this in your Next.js middleware or headers config
+ */
+export declare const CSP_DIRECTIVES: {
+    readonly "default-src": readonly ["'self'"];
+    readonly "script-src": readonly ["'self'", "'unsafe-inline'", "'unsafe-eval'"];
+    readonly "style-src": readonly ["'self'", "'unsafe-inline'"];
+    readonly "img-src": readonly ["'self'", "data:", "https:"];
+    readonly "font-src": readonly ["'self'", "data:"];
+    readonly "connect-src": readonly ["'self'"];
+    readonly "frame-src": readonly ["'self'"];
+    readonly "object-src": readonly ["'none'"];
+    readonly "base-uri": readonly ["'self'"];
+    readonly "form-action": readonly ["'self'"];
+    readonly "frame-ancestors": readonly ["'self'"];
+    readonly "upgrade-insecure-requests": readonly [];
+};
+/**
+ * Generate CSP header value from directives
+ */
+export declare function generateCSPHeader(customDirectives?: Partial<typeof CSP_DIRECTIVES>, production?: boolean): string;
+/**
+ * Allowlist of safe MDX components
+ * Only these components can be used in MDX files
+ */
+export declare const SAFE_MDX_COMPONENTS: Set<string>;
+/**
+ * Validate component usage in MDX
+ */
+export declare function validateMDXComponents(content: string): {
+    valid: boolean;
+    issues: string[];
+};
+/**
+ * Comprehensive MDX security check
+ * Use this before processing MDX content
+ */
+export declare function validateMDXSecurity(content: string, options?: {
+    strictMode?: boolean;
+    allowCustomComponents?: boolean;
+    blockDangerousPatterns?: boolean;
+}): {
+    valid: boolean;
+    issues: string[];
+    sanitized?: string;
+};

package/dist/mdx-security.js

@@ -0,0 +1,217 @@
+/**
+ * MDX Security Layer
+ *
+ * Protects against:
+ * - XSS via malicious MDX expressions
+ * - Path traversal attacks
+ * - Dangerous component usage
+ * - Cross-domain vulnerabilities
+ */
+import path from "path";
+/**
+ * Sanitize file paths to prevent path traversal attacks
+ * Blocks: ../, ..\, absolute paths, encoded traversal attempts
+ */
+export function sanitizePath(userPath) {
+    // Decode URI components to catch encoded traversal attempts
+    const decoded = decodeURIComponent(userPath);
+    // Block path traversal patterns
+    if (decoded.includes("../") ||
+        decoded.includes("..\\") ||
+        decoded.includes("%2e%2e") ||
+        decoded.includes("%252e%252e") ||
+        path.isAbsolute(decoded)) {
+        throw new Error("Path traversal detected");
+    }
+    // Normalize and validate the path
+    const normalized = path.normalize(decoded).replace(/\\/g, "/");
+    // Ensure path doesn't escape after normalization
+    if (normalized.startsWith("..") || normalized.includes("/../")) {
+        throw new Error("Invalid path detected");
+    }
+    return normalized;
+}
+/**
+ * Validate that a file path is within allowed directory
+ */
+export function validatePathWithinDirectory(filePath, allowedDir) {
+    const resolvedPath = path.resolve(allowedDir, filePath);
+    const resolvedDir = path.resolve(allowedDir);
+    return resolvedPath.startsWith(resolvedDir + path.sep) || resolvedPath === resolvedDir;
+}
+/**
+ * Dangerous MDX patterns that should be blocked
+ * These patterns can execute arbitrary code during SSR
+ */
+const DANGEROUS_PATTERNS = [
+    // JavaScript execution
+    /eval\s*\(/gi,
+    /Function\s*\(/gi,
+    /import\s*\(/gi,
+    /require\s*\(/gi,
+    // File system access
+    /fs\.[a-z]+/gi,
+    /readFile/gi,
+    /writeFile/gi,
+    /process\.env/gi,
+    // Network requests during SSR (legitimate client-side usage should use components)
+    /fetch\s*\(/gi,
+    // Dangerous Node.js modules
+    /child_process/gi,
+    /exec\s*\(/gi,
+    /spawn\s*\(/gi,
+    // Script tag injection
+    /<script[>\s]/gi,
+    /javascript:/gi,
+    /\bon(abort|blur|cancel|canplay|canplaythrough|change|click|close|contextmenu|cuechange|dblclick|drag|dragend|dragenter|dragleave|dragover|dragstart|drop|durationchange|emptied|ended|error|focus|input|invalid|keydown|keypress|keyup|load|loadeddata|loadedmetadata|loadstart|mousedown|mouseenter|mouseleave|mousemove|mouseout|mouseover|mouseup|mousewheel|pause|play|playing|progress|ratechange|reset|resize|scroll|seeked|seeking|select|show|stalled|submit|suspend|timeupdate|toggle|volumechange|waiting|wheel)\s*=/gi, // onclick, onerror, onload, etc.
+];
+/**
+ * Remove code blocks from content to avoid scanning code examples
+ * This prevents false positives from documentation code examples
+ */
+function removeCodeBlocks(content) {
+    // Remove fenced code blocks (```...```)
+    let withoutCodeBlocks = content.replace(/```[\s\S]*?```/g, '');
+    // Remove inline code (`...`)
+    withoutCodeBlocks = withoutCodeBlocks.replace(/`[^`]*`/g, '');
+    return withoutCodeBlocks;
+}
+/**
+ * Scan MDX content for dangerous patterns
+ * Returns array of detected issues
+ * Note: Skips content inside code blocks to avoid false positives
+ */
+export function scanMDXForDangerousPatterns(content) {
+    const issues = [];
+    // Remove code blocks before scanning to avoid false positives
+    const contentWithoutCode = removeCodeBlocks(content);
+    for (const pattern of DANGEROUS_PATTERNS) {
+        const matches = contentWithoutCode.match(pattern);
+        if (matches) {
+            issues.push(`Dangerous pattern detected: ${pattern.source}`);
+        }
+    }
+    return issues;
+}
+/**
+ * Sanitize MDX content by removing/escaping dangerous patterns
+ * This is a defensive measure - ideally content should be rejected if dangerous
+ */
+export function sanitizeMDXContent(content, strict = false) {
+    if (strict) {
+        const issues = scanMDXForDangerousPatterns(content);
+        if (issues.length > 0) {
+            throw new Error(`MDX content contains dangerous patterns: ${issues.join(", ")}`);
+        }
+    }
+    // Remove inline script tags
+    let sanitized = content.replace(/<script[^>]*>[\s\S]*?<\/script>/gi, "");
+    // Remove event handlers from HTML tags
+    sanitized = sanitized.replace(/\s+on\w+\s*=\s*["'][^"']*["']/gi, "");
+    // Remove javascript: protocol
+    sanitized = sanitized.replace(/javascript:/gi, "");
+    return sanitized;
+}
+/**
+ * Content Security Policy configuration
+ * Use this in your Next.js middleware or headers config
+ */
+export const CSP_DIRECTIVES = {
+    "default-src": ["'self'"],
+    "script-src": [
+        "'self'",
+        "'unsafe-inline'", // Required for Next.js
+        "'unsafe-eval'", // Required for dev mode - remove in production
+    ],
+    "style-src": ["'self'", "'unsafe-inline'"], // Required for styled-components/emotion
+    "img-src": ["'self'", "data:", "https:"],
+    "font-src": ["'self'", "data:"],
+    "connect-src": ["'self'"],
+    "frame-src": ["'self'"],
+    "object-src": ["'none'"],
+    "base-uri": ["'self'"],
+    "form-action": ["'self'"],
+    "frame-ancestors": ["'self'"],
+    "upgrade-insecure-requests": [],
+};
+/**
+ * Generate CSP header value from directives
+ */
+export function generateCSPHeader(customDirectives, production = true) {
+    const directives = { ...CSP_DIRECTIVES, ...customDirectives };
+    // Remove unsafe-eval in production
+    if (production && directives["script-src"]) {
+        directives["script-src"] = directives["script-src"].filter((src) => src !== "'unsafe-eval'");
+    }
+    return Object.entries(directives)
+        .map(([key, values]) => `${key} ${values.join(" ")}`)
+        .join("; ");
+}
+/**
+ * Allowlist of safe MDX components
+ * Only these components can be used in MDX files
+ */
+export const SAFE_MDX_COMPONENTS = new Set([
+    // Standard HTML elements (automatically allowed by MDX)
+    "h1", "h2", "h3", "h4", "h5", "h6",
+    "p", "a", "ul", "ol", "li", "code", "pre",
+    "blockquote", "table", "thead", "tbody", "tr", "th", "td",
+    "img", "video", "audio", "br", "hr", "strong", "em",
+    // Custom safe components
+    "Callout", "CodeBlock", "Accordion", "AccordionItem",
+    "Tabs", "Tab", "Image", "Video", "Card", "CardGrid",
+    "ImageCard", "ImageCardGrid", "Steps", "Step",
+    "Icon", "Mermaid", "Math", "Columns", "Column",
+    "Badge", "Tooltip", "Frame",
+    "ApiEndpoint", "ApiParams", "ApiResponse", "ApiPlayground", "ApiReference",
+]);
+/**
+ * Validate component usage in MDX
+ */
+export function validateMDXComponents(content) {
+    const issues = [];
+    // Find all JSX-like component usage
+    const componentRegex = /<([A-Z][a-zA-Z0-9]*)/g;
+    let match;
+    while ((match = componentRegex.exec(content)) !== null) {
+        const componentName = match[1];
+        if (!SAFE_MDX_COMPONENTS.has(componentName)) {
+            issues.push(`Unsafe component detected: ${componentName}`);
+        }
+    }
+    return {
+        valid: issues.length === 0,
+        issues,
+    };
+}
+/**
+ * Comprehensive MDX security check
+ * Use this before processing MDX content
+ */
+export function validateMDXSecurity(content, options = {}) {
+    const { strictMode = false, allowCustomComponents = true, blockDangerousPatterns = true, } = options;
+    const issues = [];
+    // Check for dangerous patterns
+    if (blockDangerousPatterns) {
+        const patternIssues = scanMDXForDangerousPatterns(content);
+        issues.push(...patternIssues);
+    }
+    // Validate components
+    if (!allowCustomComponents) {
+        const componentValidation = validateMDXComponents(content);
+        if (!componentValidation.valid) {
+            issues.push(...componentValidation.issues);
+        }
+    }
+    // In strict mode, reject any issues
+    if (strictMode && issues.length > 0) {
+        return { valid: false, issues };
+    }
+    // Otherwise, sanitize and warn
+    const sanitized = sanitizeMDXContent(content, false);
+    return {
+        valid: true,
+        issues,
+        sanitized,
+    };
+}

package/dist/mdx.d.ts

@@ -0,0 +1,73 @@
+import type { I18nConfig } from "./config.types";
+/**
+ * Structured node type for MDX content rendering.
+ * Used to pass a JSON-serializable tree from server to client,
+ * allowing the client-side recursive renderer to instantiate
+ * real Svelte components for custom tags.
+ */
+export interface MdxNode {
+    type: 'html' | 'component';
+    content?: string;
+    name?: string;
+    props?: Record<string, any>;
+    children?: MdxNode[];
+}
+export interface DocMeta {
+    title: string;
+    description?: string;
+    slug?: string;
+    section?: string;
+    group?: string;
+    sidebar?: string;
+    order?: number;
+    sidebar_position?: number;
+    content?: string;
+    last_updated?: string;
+    draft?: boolean;
+    authors?: Array<{
+        id: string;
+        name?: string;
+    }>;
+    tags?: string[];
+    redirect_from?: string[];
+    reading_time?: number;
+    word_count?: number;
+    icon?: string;
+    tab_group?: string;
+    locale?: string;
+    protected?: boolean;
+    isProtected?: boolean;
+}
+export interface Doc {
+    slug: string;
+    filePath: string;
+    title: string;
+    meta: DocMeta;
+    content: string;
+    contentNodes?: MdxNode[];
+    categoryLabel?: string;
+    categoryPosition?: number;
+    categoryCollapsible?: boolean;
+    categoryCollapsed?: boolean;
+    categoryIcon?: string;
+    categoryTabGroup?: string;
+    locale?: string;
+}
+export interface TocItem {
+    id: string;
+    title: string;
+    level: number;
+}
+export declare function getVersions(): string[];
+export declare function getI18nConfig(): I18nConfig | null;
+export declare function getDocBySlug(slug: string, version?: string, locale?: string): Promise<Doc | null>;
+export declare function getAllDocs(version?: string, locale?: string): Doc[];
+export declare function getAdjacentDocs(currentSlug: string, allDocs: Doc[]): {
+    previous?: Doc;
+    next?: Doc;
+};
+export declare function extractTableOfContents(content: string): TocItem[];
+/**
+ * Check if a slug represents a category (has child documents)
+ */
+export declare function isCategoryPage(slug: string, allDocs: Doc[]): boolean;