@fydemy/cms 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [1.0.0] - 2024-12-06
+
+### Added
+
+- Initial stable release of @fydemy/cms
+- File-based CMS for Next.js with markdown support
+- GitHub integration for production deployments
+- Simple authentication with username/password from environment variables
+- TypeScript support with full type definitions
+- Local and GitHub storage providers
+- API handlers for content management (CRUD operations)
+- Authentication middleware for protecting admin routes
+- Session management with JWT
+- File upload functionality
+- Collection and directory listing utilities
+
+### Security
+
+- Timing-safe password comparison using `crypto.timingSafeEqual` to prevent timing attacks
+- Rate limiting on login endpoint (5 attempts per 15 minutes)
+- Input validation and sanitization for all user inputs
+- Path validation to prevent directory traversal attacks
+- File size limits (10MB maximum)
+- Frontmatter sanitization to prevent injection attacks
+- Secure session cookies with httpOnly, sameSite, and secure flags
+- Length limits on username (100 chars) and password (1000 chars) inputs
+- Generic error messages to prevent username enumeration
+
+### Documentation
+
+- Comprehensive README with installation and usage instructions
+- JSDoc documentation for all public APIs
+- Security policy and vulnerability reporting guidelines
+- MIT License
+
+## [0.1.0] - 2024-12-05
+
+### Added
+
+- Initial development release
+- Basic file-based CMS functionality
+- Simple authentication
+- Markdown file operations

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 Fydemy
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/dist/index.d.mts

@@ -0,0 +1,431 @@
+import { NextRequest, NextResponse } from 'next/server';
+
+interface MarkdownData {
+    content: string;
+    data: Record<string, any>;
+}
+/**
+ * Parse markdown content with frontmatter
+ * @param rawContent - Raw markdown content to parse
+ * @returns Parsed markdown data with frontmatter and content
+ */
+declare function parseMarkdown(rawContent: string): MarkdownData;
+/**
+ * Convert data and content back to markdown with frontmatter
+ */
+declare function stringifyMarkdown(data: Record<string, any>, content: string): string;
+/**
+ * Read and parse a markdown file
+ * @param filePath - Path to the markdown file
+ * @returns Parsed markdown data
+ * @throws Error if file path is invalid or file is too large
+ */
+declare function getMarkdownContent(filePath: string): Promise<MarkdownData>;
+/**
+ * Write markdown file with frontmatter
+ * @param filePath - Path to the markdown file
+ * @param data - Frontmatter data object
+ * @param content - Markdown content
+ * @throws Error if file path is invalid or content is too large
+ */
+declare function saveMarkdownContent(filePath: string, data: Record<string, any>, content: string): Promise<void>;
+/**
+ * Delete a markdown file
+ * @param filePath - Path to the markdown file
+ * @throws Error if file path is invalid
+ */
+declare function deleteMarkdownContent(filePath: string): Promise<void>;
+/**
+ * List all markdown files in a directory
+ * @param directory - Directory path (optional, defaults to root)
+ * @returns Array of file paths
+ * @throws Error if directory path is invalid
+ */
+declare function listMarkdownFiles(directory?: string): Promise<string[]>;
+/**
+ * Check if a markdown file exists
+ * @param filePath - Path to the markdown file
+ * @returns True if file exists, false otherwise
+ * @throws Error if file path is invalid
+ */
+declare function markdownFileExists(filePath: string): Promise<boolean>;
+
+/**
+ * Represents a file or directory entry
+ */
+interface FileEntry {
+    /** Relative path from base content directory */
+    path: string;
+    /** File or directory name */
+    name: string;
+    /** Type of entry */
+    type: "file" | "directory";
+}
+/**
+ * Interface for file storage operations
+ */
+interface StorageProvider {
+    /** Read file content as string */
+    readFile(filePath: string): Promise<string>;
+    /** Write content to file, creating parent directories if needed */
+    writeFile(filePath: string, content: string): Promise<void>;
+    /** Delete a file */
+    deleteFile(filePath: string): Promise<void>;
+    /** List files in a directory */
+    listFiles(directory: string): Promise<FileEntry[]>;
+    /** Check if a file exists */
+    exists(filePath: string): Promise<boolean>;
+    /** Upload a binary file */
+    uploadFile(filePath: string, buffer: Buffer): Promise<string>;
+}
+/**
+ * Local file system storage (for development)
+ */
+declare class LocalStorage implements StorageProvider {
+    private baseDir;
+    constructor(baseDir?: string);
+    private getFullPath;
+    readFile(filePath: string): Promise<string>;
+    writeFile(filePath: string, content: string): Promise<void>;
+    deleteFile(filePath: string): Promise<void>;
+    listFiles(directory: string): Promise<FileEntry[]>;
+    exists(filePath: string): Promise<boolean>;
+    uploadFile(filePath: string, buffer: Buffer): Promise<string>;
+}
+/**
+ * GitHub storage (for production)
+ */
+declare class GitHubStorage implements StorageProvider {
+    private octokit;
+    private owner;
+    private repo;
+    private branch;
+    private baseDir;
+    constructor();
+    private getGitHubPath;
+    readFile(filePath: string): Promise<string>;
+    writeFile(filePath: string, content: string): Promise<void>;
+    deleteFile(filePath: string): Promise<void>;
+    listFiles(directory: string): Promise<FileEntry[]>;
+    exists(filePath: string): Promise<boolean>;
+    uploadFile(filePath: string, buffer: Buffer): Promise<string>;
+}
+/**
+ * Get the appropriate storage provider based on environment
+ */
+declare function getStorageProvider(): StorageProvider;
+
+/**
+ * List all files and directories in a directory
+ * @param directory - Relative path to the directory (default: root)
+ * @returns Array of file entries (files and directories)
+ */
+declare function listDirectory(directory?: string): Promise<FileEntry[]>;
+
+/**
+ * Base interface for collection items with flexible frontmatter
+ */
+interface CollectionItem<T = Record<string, any>> {
+    /** The markdown content body */
+    content: string;
+    /** Frontmatter data with dynamic fields */
+    data: T;
+    /** File slug (filename without extension) */
+    slug: string;
+}
+/**
+ * Fetch all markdown files from a specific folder/collection
+ * @param folderName - The folder name under public/content (e.g., "blog", "pages")
+ * @returns Array of collection items with parsed frontmatter and content
+ *
+ * @example
+ * ```ts
+ * // Fetch all blog posts
+ * const posts = await getCollectionItems("blog");
+ * posts.forEach(post => {
+ *   console.log(post.data.title); // Access any frontmatter field
+ *   console.log(post.slug);       // Filename without .md
+ * });
+ *
+ * // With type inference for known fields
+ * interface BlogPost {
+ *   title: string;
+ *   date: string;
+ *   author?: string;
+ *   [key: string]: any; // Allow any other fields
+ * }
+ * const typedPosts = await getCollectionItems<BlogPost>("blog");
+ * ```
+ */
+declare function getCollectionItems<T = Record<string, any>>(folderName: string): Promise<CollectionItem<T>[]>;
+/**
+ * Fetch a single item from a collection by slug
+ * @param folderName - The folder name under public/content
+ * @param slug - The filename without .md extension
+ * @returns Single collection item or null if not found
+ *
+ * @example
+ * ```ts
+ * // Fetch a specific blog post
+ * const post = await getCollectionItem("blog", "my-first-post");
+ * if (post) {
+ *   console.log(post.data.title);
+ * }
+ * ```
+ */
+declare function getCollectionItem<T = Record<string, any>>(folderName: string, slug: string): Promise<CollectionItem<T> | null>;
+/**
+ * Get all unique folder names (collections) in the content directory
+ * @param baseDir - Base directory to scan (default: "")
+ * @returns Array of folder names
+ *
+ * @example
+ * ```ts
+ * const collections = await getCollections();
+ * // Returns: ["blog", "pages", "docs", ...]
+ * ```
+ */
+declare function getCollections(baseDir?: string): Promise<string[]>;
+
+/**
+ * Upload a file and return its public URL
+ * @param fileName - Original filename
+ * @param buffer - File content buffer
+ * @returns Public URL path to the uploaded file
+ */
+declare function uploadFile(fileName: string, buffer: Buffer): Promise<string>;
+
+/**
+ * Session payload structure for JWT
+ */
+interface SessionPayload {
+    /** Username of the authenticated user */
+    username: string;
+    /** Expiration timestamp (Unix time) */
+    exp: number;
+}
+/**
+ * Create a new session token for the given username
+ * @param username - The username to create a session for
+ * @returns Signed JWT string
+ */
+declare function createSession(username: string): Promise<string>;
+/**
+ * Verify and decode a session token
+ * @param token - The JWT token to verify
+ * @returns Decoded payload if valid, null otherwise
+ */
+declare function verifySession(token: string): Promise<SessionPayload | null>;
+/**
+ * Get session from Next.js request cookies
+ */
+declare function getSessionFromCookies(): Promise<SessionPayload | null>;
+/**
+ * Set session cookie
+ */
+declare function setSessionCookie(token: string): Promise<void>;
+/**
+ * Clear session cookie
+ */
+declare function clearSessionCookie(): Promise<void>;
+
+/**
+ * Validate username and password against environment variables using timing-safe comparison
+ * @param username - Username to validate
+ * @param password - Password to validate
+ * @returns True if credentials are valid, false otherwise
+ * @throws Error if environment variables are not configured
+ */
+declare function validateCredentials(username: string, password: string): boolean;
+
+/**
+ * Login endpoint with rate limiting
+ */
+declare function handleLogin(request: NextRequest): Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    success: boolean;
+}>>;
+/**
+ * Logout endpoint
+ */
+declare function handleLogout(): Promise<NextResponse<{
+    success: boolean;
+}>>;
+/**
+ * Get content endpoint
+ */
+declare function handleGetContent(_request: NextRequest, filePath: string): Promise<NextResponse<{
+    error: string;
+}> | NextResponse<MarkdownData>>;
+/**
+ * Save content endpoint
+ */
+declare function handleSaveContent(request: NextRequest, filePath: string): Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    success: boolean;
+}>>;
+/**
+ * Delete content endpoint
+ */
+declare function handleDeleteContent(_request: NextRequest, filePath: string): Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    success: boolean;
+}>>;
+/**
+ * List files endpoint
+ */
+declare function handleListFiles(directory?: string): Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    entries: FileEntry[];
+}>>;
+/**
+ * Create API route handlers for Next.js App Router
+ */
+declare function createContentApiHandlers(): {
+    GET(request: NextRequest, { params }: {
+        params: {
+            path: string[];
+        };
+    }): Promise<NextResponse<{
+        error: string;
+    }> | NextResponse<MarkdownData>>;
+    POST(request: NextRequest, { params }: {
+        params: {
+            path: string[];
+        };
+    }): Promise<NextResponse<{
+        error: string;
+    }> | NextResponse<{
+        success: boolean;
+    }>>;
+    DELETE(request: NextRequest, { params }: {
+        params: {
+            path: string[];
+        };
+    }): Promise<NextResponse<{
+        error: string;
+    }> | NextResponse<{
+        success: boolean;
+    }>>;
+};
+/**
+ * Create list API handlers
+ */
+declare function createListApiHandlers(): {
+    GET(_request: NextRequest, { params }: {
+        params: {
+            path?: string[];
+        };
+    }): Promise<NextResponse<{
+        error: string;
+    }> | NextResponse<{
+        entries: FileEntry[];
+    }>>;
+};
+
+/**
+ * Handle file upload
+ */
+declare function handleUpload(request: NextRequest): Promise<NextResponse<{
+    error: string;
+}> | NextResponse<{
+    success: boolean;
+    url: string;
+    filename: string;
+}>>;
+
+/**
+ * Create middleware to protect admin routes
+ */
+declare function createAuthMiddleware(options?: {
+    loginPath?: string;
+    protectedPaths?: string[];
+}): (request: NextRequest) => Promise<NextResponse<unknown>>;
+
+interface InitCMSConfig {
+    /** Directory where content is stored (default: "public/content") */
+    contentDir?: string;
+}
+/**
+ * Initialize CMS in a Next.js project
+ * Creates the content directory and an example markdown file.
+ * @param config - Configuration options
+ */
+declare function initCMS(config?: InitCMSConfig): Promise<void>;
+
+/**
+ * Maximum username length (prevents DoS)
+ */
+declare const MAX_USERNAME_LENGTH = 100;
+/**
+ * Maximum password length (prevents DoS)
+ */
+declare const MAX_PASSWORD_LENGTH = 1000;
+/**
+ * Maximum file size in bytes (10MB)
+ */
+declare const MAX_FILE_SIZE: number;
+/**
+ * Validate and sanitize file path to prevent directory traversal
+ * @param filePath - The file path to validate
+ * @returns Sanitized file path
+ * @throws Error if path is invalid or attempts directory traversal
+ */
+declare function validateFilePath(filePath: string): string;
+/**
+ * Validate username input
+ * @param username - The username to validate
+ * @returns True if valid
+ * @throws Error if invalid
+ */
+declare function validateUsername(username: string): boolean;
+/**
+ * Validate password input
+ * @param password - The password to validate
+ * @returns True if valid
+ * @throws Error if invalid
+ */
+declare function validatePassword(password: string): boolean;
+/**
+ * Validate file size
+ * @param size - File size in bytes
+ * @returns True if valid
+ * @throws Error if too large
+ */
+declare function validateFileSize(size: number): boolean;
+/**
+ * Sanitize frontmatter data to prevent injection
+ * @param data - The data object to sanitize
+ * @returns Sanitized data
+ */
+declare function sanitizeFrontmatter(data: Record<string, any>): Record<string, any>;
+
+/**
+ * Simple in-memory rate limiter for login attempts
+ */
+/**
+ * Check if IP/identifier is rate limited
+ * @param identifier - IP address or other unique identifier
+ * @returns Object with isLimited and remaining attempts
+ */
+declare function checkRateLimit(identifier: string): {
+    isLimited: boolean;
+    remaining: number;
+    resetTime: number;
+};
+/**
+ * Increment rate limit counter for identifier
+ * @param identifier - IP address or other unique identifier
+ */
+declare function incrementRateLimit(identifier: string): void;
+/**
+ * Reset rate limit for identifier (use after successful login)
+ * @param identifier - IP address or other unique identifier
+ */
+declare function resetRateLimit(identifier: string): void;
+
+export { type CollectionItem, type FileEntry, GitHubStorage, type InitCMSConfig, LocalStorage, MAX_FILE_SIZE, MAX_PASSWORD_LENGTH, MAX_USERNAME_LENGTH, type MarkdownData, type StorageProvider, checkRateLimit, clearSessionCookie, createAuthMiddleware, createContentApiHandlers, createListApiHandlers, createSession, deleteMarkdownContent, getCollectionItem, getCollectionItems, getCollections, getMarkdownContent, getSessionFromCookies, getStorageProvider, handleDeleteContent, handleGetContent, handleListFiles, handleLogin, handleLogout, handleSaveContent, handleUpload, incrementRateLimit, initCMS, listDirectory, listMarkdownFiles, markdownFileExists, parseMarkdown, resetRateLimit, sanitizeFrontmatter, saveMarkdownContent, setSessionCookie, stringifyMarkdown, uploadFile, validateCredentials, validateFilePath, validateFileSize, validatePassword, validateUsername, verifySession };