@fydemy/cms 0.0.0

package/.env.local.example

@@ -0,0 +1,20 @@
+# CMS Authentication (Required)
+CMS_ADMIN_USERNAME=admin
+CMS_ADMIN_PASSWORD=your_secure_password_here
+CMS_SESSION_SECRET=your-secret-key-must-be-at-least-32-characters-long
+
+# ===== STORAGE OPTIONS (Choose one) =====
+
+# Option 1: GitHub Storage (Production)
+# Uncomment these if you want to use GitHub for storage
+# GITHUB_TOKEN=ghp_your_github_token_here
+# GITHUB_REPO=username/repository
+# GITHUB_BRANCH=main
+
+# Option 2: Cloudflare R2 Storage (Production)
+# Uncomment these if you want to use Cloudflare R2 for storage
+# CLOUDFLARE_ACCOUNT_ID=your-cloudflare-account-id
+# CLOUDFLARE_ACCESS_KEY_ID=your-r2-access-key-id
+# CLOUDFLARE_SECRET_ACCESS_KEY=your-r2-secret-access-key
+# NEXT_PUBLIC_R2_PUBLIC_URL=https://your-bucket.r2.dev
+# R2_BUCKET_NAME=my-cms-bucket

package/.github/workflows/cd.yml

@@ -0,0 +1,41 @@
+name: CD
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      id-token: write
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v3
+        with:
+          version: 9
+
+      - name: Use Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20.x"
+          registry-url: "https://registry.npmjs.org"
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Build
+        run: pnpm build
+        working-directory: packages/core
+
+      - name: Create .npmrc
+        run: echo "//registry.npmjs.org/:_authToken=${{ secrets.NPM_TOKEN }}" > .npmrc
+        working-directory: packages/core
+
+      - name: Publish to NPM
+        run: pnpm publish --access public --no-git-checks
+        working-directory: packages/core

package/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+
+    strategy:
+      matrix:
+        node-version: [18.x, 20.x]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: pnpm/action-setup@v3
+        with:
+          version: 9
+
+      - name: Use Node.js ${{ matrix.node-version }}
+        uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node-version }}
+          cache: "pnpm"
+
+      - name: Install dependencies
+        run: pnpm install --frozen-lockfile
+
+      - name: Type Check
+        run: pnpm type-check
+        working-directory: packages/core
+
+      - name: Run Tests
+        run: pnpm test
+        working-directory: packages/core
+
+      - name: Build
+        run: pnpm build
+        working-directory: packages/core

package/CLOUDFLARE_R2_SETUP.md

@@ -0,0 +1,92 @@
+# Cloudflare R2 Storage Integration
+
+## Summary
+
+The CMS has been updated to strictly support **Cloudflare R2** storage (removing references to S3 and Vercel Blob). The environment variables have been updated to match your requested format.
+
+## Environment Variables
+
+When setting up Cloudflare R2 storage, use these environment variables:
+
+```env
+# Cloudflare R2 Storage
+CLOUDFLARE_ACCOUNT_ID=your-account-id
+CLOUDFLARE_ACCESS_KEY_ID=your-access-key-id
+CLOUDFLARE_SECRET_ACCESS_KEY=your-secret-access-key
+NEXT_PUBLIC_R2_PUBLIC_URL=https://your-public-url.r2.dev
+R2_BUCKET_NAME=my-bucket
+```
+
+## How to Get These Values
+
+### 1. CLOUDFLARE_ACCOUNT_ID
+
+- Log in to your Cloudflare dashboard
+- Your Account ID is visible in the URL or in the right sidebar
+
+### 2. CLOUDFLARE_ACCESS_KEY_ID & CLOUDFLARE_SECRET_ACCESS_KEY
+
+- Go to R2 in your Cloudflare dashboard
+- Click "Manage R2 API Tokens"
+- Create a new API token with read/write permissions
+- Save both the Access Key ID and Secret Access Key
+
+### 3. NEXT_PUBLIC_R2_PUBLIC_URL
+
+- In your R2 bucket settings, go to "Settings"
+- Under "Public Access", enable public access if needed
+- Copy the public bucket URL (e.g., `https://pub-xxxxx.r2.dev`)
+- Or set up a custom domain for your R2 bucket
+
+### 4. R2_BUCKET_NAME
+
+- The name of your R2 bucket (e.g., `my-cms-content`)
+
+## Changes Made
+
+### 1. `/packages/core/src/init/setup.ts`
+
+- Updated storage provider selection to only show "GitHub" or "Cloudflare R2"
+- Changed environment variable names from generic `STORAGE_*` to Cloudflare-specific names
+- Removed references to S3 and Vercel Blob
+
+### 2. `/packages/core/src/content/storage.ts`
+
+- Added `CloudflareR2Storage` class that implements the `StorageProvider` interface
+- Uses AWS S3 SDK (already installed) to communicate with Cloudflare R2
+- Implements all required methods:
+  - `readFile()` - Read markdown files from R2
+  - `writeFile()` - Write markdown files to R2
+  - `deleteFile()` - Delete files from R2
+  - `listFiles()` - List files and directories in R2
+  - `exists()` - Check if a file exists
+  - `uploadFile()` - Upload binary files (images, PDFs, etc.)
+- Updated `getStorageProvider()` to detect and use Cloudflare R2 when credentials are present
+
+## Storage Provider Priority
+
+The system will automatically select the storage provider in this order:
+
+1. **Cloudflare R2** - If `CLOUDFLARE_ACCOUNT_ID`, `CLOUDFLARE_ACCESS_KEY_ID`, and `CLOUDFLARE_SECRET_ACCESS_KEY` are set
+2. **GitHub** - If `NODE_ENV=production` and `GITHUB_TOKEN` is set
+3. **Local Storage** - Default for development
+
+## File Structure in R2
+
+- Content files: `content/your-file.md`
+- Uploaded files: `uploads/filename.ext`
+
+## Public URL Format
+
+Uploaded files will be accessible at:
+
+```
+{NEXT_PUBLIC_R2_PUBLIC_URL}/uploads/filename.ext
+```
+
+## Notes
+
+- The AWS S3 SDK (`@aws-sdk/client-s3`) is already installed as a dependency
+- Cloudflare R2 is S3-compatible, so we use the S3 client with R2 endpoints
+- The implementation automatically sets the region to "auto" for R2
+- Content-Type headers are automatically set for uploaded files

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/QUICKSTART.md

@@ -0,0 +1,80 @@
+# @fydemy/cms - Quick Start
+
+## What You Have
+
+A complete, minimal CMS package for Next.js:
+
+```
+📦 @fydemy/cms (packages/core)
+   - File-based markdown storage
+   - GitHub integration for production
+   - Simple auth (env username/password)
+   - TypeScript support
+
+🚀 Demo App (apps/dev)
+   - Example Next.js application
+   - Admin dashboard at /admin
+   - Login page, editor, file manager
+```
+
+## Run the Demo
+
+1. **Copy environment file:**
+
+   ```bash
+   cd apps/dev
+   cp .env.local.example .env.local
+   ```
+
+2. **Edit `.env.local`** with your credentials:
+
+   ```env
+   CMS_ADMIN_USERNAME=admin
+   CMS_ADMIN_PASSWORD=your_password
+   CMS_SESSION_SECRET=your-32-char-secret
+   ```
+
+3. **Start development server:**
+
+   ```bash
+   cd ../..
+   pnpm dev
+   ```
+
+4. **Open browser:**
+   - Home: http://localhost:3000
+   - Admin: http://localhost:3000/admin
+   - Login with your credentials
+
+## Use in Your Own Project
+
+See [README.md](../README.md) for installation and setup instructions.
+
+## Features
+
+- ✅ Create, edit, delete markdown files
+- ✅ Frontmatter support (JSON)
+- ✅ Session-based authentication
+- ✅ Local storage (dev) + GitHub (production)
+- ✅ TypeScript types included
+- ✅ Vercel-compatible
+
+## API Example
+
+```typescript
+import { getMarkdownContent } from "@fydemy/cms";
+
+// Read content
+const post = await getMarkdownContent("example.md");
+console.log(post.data.title); // "Example Post"
+console.log(post.content); // markdown content
+```
+
+## Next Steps
+
+1. Test the admin dashboard locally
+2. Deploy to Vercel with GitHub token
+3. Use the utilities in your pages
+4. Customize the admin UI as needed
+
+Built with TypeScript, minimal dependencies, zero database! 🎉

package/README.md

@@ -0,0 +1,293 @@
+# @fydemy/cms
+
+[![npm version](https://badge.fury.io/js/@fydemy%2Fcms.svg)](https://www.npmjs.com/package/@fydemy/cms)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![TypeScript](https://img.shields.io/badge/TypeScript-5.3-blue.svg)](https://www.typescriptlang.org/)
+[![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
+
+A minimal, secure, file-based CMS for Next.js without database requirements. Store content as markdown files with GitHub integration for production deployments.
+
+## Features
+
+- 📝 **File-based Storage** - Markdown files with frontmatter in `/public/content`
+- 🔐 **Secure Authentication** - Timing-safe password comparison, rate limiting, input validation
+- 🚀 **Vercel Compatible** - Deploy without any database setup
+- 🐙 **GitHub Integration** - Automatic file commits in production
+- 📦 **Zero Config** - Minimal setup required
+- 🎯 **TypeScript First** - Full type safety with comprehensive type definitions
+- ⚡ **Lightweight** - Small bundle size (~30KB), minimal dependencies
+- 🛡️ **Security Hardened** - Built with security best practices
+
+## Installation
+
+```bash
+npm install @fydemy/cms
+# or
+pnpm add @fydemy/cms
+# or
+yarn add @fydemy/cms
+```
+
+## Quick Start
+
+### 1. Initialize the CMS
+
+Run the initialization command in your Next.js App Router project:
+
+```bash
+npx fydemy-cms init
+```
+
+This command will automatically:
+
+- Create the content directory
+- Scaffold Admin UI pages (`/app/admin`)
+- Create API routes (`/app/api/cms`)
+- Create a `.env.local.example` file
+- Provide instructions for updating `middleware.ts`
+
+### 2. Configure Environment
+
+Copy `.env.local.example` to `.env.local` and set your credentials:
+
+```bash
+cp .env.local.example .env.local
+```
+
+Update variables in `.env.local`:
+
+```env
+# Required for authentication
+CMS_ADMIN_USERNAME=admin
+CMS_ADMIN_PASSWORD=your_secure_password
+CMS_SESSION_SECRET=your-secret-key-must-be-at-least-32-characters-long
+
+# Optional: For production (GitHub integration)
+GITHUB_TOKEN=ghp_your_github_token
+GITHUB_REPO=username/repository
+GITHUB_BRANCH=main
+```
+
+> **Security Note**: Use strong passwords and keep `CMS_SESSION_SECRET` at least 32 characters long.
+
+### 3. Read Content in Your App
+
+```typescript
+import { getMarkdownContent } from "@fydemy/cms";
+
+export default async function BlogPost({
+  params,
+}: {
+  params: { slug: string };
+}) {
+  const post = await getMarkdownContent(`${params.slug}.md`);
+
+  return (
+    <article>
+      <h1>{post.data.title}</h1>
+      <p>{post.data.description}</p>
+      <div>{post.content}</div>
+    </article>
+  );
+}
+```
+
+## Security Features
+
+### Built-in Security
+
+- **Timing-Safe Authentication**: Uses `crypto.timingSafeEqual` to prevent timing attacks
+- **Rate Limiting**: 5 login attempts per 15 minutes per IP address
+- **Input Validation**: All inputs validated and sanitized
+- **Path Validation**: Prevents directory traversal attacks
+- **File Size Limits**: Default 10MB maximum file size
+- **Secure Sessions**: httpOnly, sameSite, and secure cookies in production
+- **No Username Enumeration**: Generic error messages
+
+### Security Best Practices
+
+1. **Strong Credentials**: Use strong, unique passwords for `CMS_ADMIN_PASSWORD`
+2. **Secret Management**: Keep `CMS_SESSION_SECRET` at least 32 characters
+3. **GitHub Token Security**: Use minimal permissions (only `repo` scope)
+4. **HTTPS Only**: Always use HTTPS in production
+5. **Regular Updates**: Keep dependencies up to date
+6. **Environment Variables**: Never commit `.env` files
+
+For more security information, see [SECURITY.md](./SECURITY.md).
+
+## API Reference
+
+### Content Management
+
+```typescript
+// Read markdown file
+const content = await getMarkdownContent("blog/post.md");
+// Returns: { data: {...}, content: "..." }
+
+// Write markdown file
+await saveMarkdownContent(
+  "blog/post.md",
+  { title: "My Post", date: "2024-01-01" },
+  "# Hello World"
+);
+
+// Delete file
+await deleteMarkdownContent("blog/post.md");
+
+// List files
+const files = await listMarkdownFiles("blog");
+// Returns: ['blog/post1.md', 'blog/post2.md']
+
+// Check if file exists
+const exists = await markdownFileExists("blog/post.md");
+```
+
+### Parsing Utilities
+
+```typescript
+import { parseMarkdown, stringifyMarkdown } from "@fydemy/cms";
+
+// Parse markdown string
+const { data, content } = parseMarkdown(rawMarkdown);
+
+// Convert to markdown
+const markdown = stringifyMarkdown({ title: "Post" }, "Content here");
+```
+
+### Authentication
+
+```typescript
+import { validateCredentials, createSession } from "@fydemy/cms";
+
+// Validate credentials
+const isValid = validateCredentials("admin", "password");
+
+// Create session (returns JWT)
+const token = await createSession("admin");
+```
+
+### Validation Utilities
+
+```typescript
+import {
+  validateFilePath,
+  validateUsername,
+  validatePassword,
+  sanitizeFrontmatter,
+} from "@fydemy/cms";
+
+// Validate file path (prevents directory traversal)
+const safePath = validateFilePath("blog/post.md");
+
+// Validate username
+validateUsername("admin"); // throws if invalid
+
+// Sanitize frontmatter data
+const safe = sanitizeFrontmatter({ title: "Test", script: "<script>" });
+```
+
+## Storage
+
+### Development
+
+Files are stored locally in `/public/content` directory.
+
+### Production
+
+When `NODE_ENV=production` and `GITHUB_TOKEN` is set, all file operations are performed via GitHub API, creating commits directly to your repository.
+
+## Environment Variables
+
+| Variable             | Required   | Description                     |
+| -------------------- | ---------- | ------------------------------- |
+| `CMS_ADMIN_USERNAME` | Yes        | Admin username                  |
+| `CMS_ADMIN_PASSWORD` | Yes        | Admin password                  |
+| `CMS_SESSION_SECRET` | Yes        | JWT secret (min 32 chars)       |
+| `GITHUB_TOKEN`       | Production | GitHub personal access token    |
+| `GITHUB_REPO`        | Production | Repository (format: owner/repo) |
+| `GITHUB_BRANCH`      | Production | Branch name (default: main)     |
+
+## GitHub Setup
+
+1. Create a GitHub Personal Access Token with `repo` permissions
+2. Add the token to your environment variables
+3. Deploy to Vercel and configure the environment variables
+
+## FAQ
+
+### Is this suitable for production?
+
+Yes! The package includes security hardening, rate limiting, and has been tested for production use. Make sure to follow security best practices.
+
+### Can I use this with other frameworks?
+
+This package is designed for Next.js App Router (13+). For other frameworks, you can use the core utilities but will need to implement your own API routes.
+
+### How do I customize the file size limit?
+
+```typescript
+import { MAX_FILE_SIZE } from "@fydemy/cms";
+// Default is 10MB, you can check this constant
+```
+
+To change it, you'll need to implement your own validation layer.
+
+### Does it support images?
+
+Yes! The package includes file upload functionality. Images can be uploaded and stored in `/public/uploads` (local) or via GitHub API (production).
+
+### How do I backup my content?
+
+Since content is stored in your GitHub repository (in production), it's automatically backed up with full version history. In development, the `/public/content` directory can be committed to git.
+
+### What about rate limiting in production?
+
+The built-in rate limiter is memory-based and resets on server restart. For production with multiple instances, consider implementing Redis-based rate limiting.
+
+### Can I add more admin users?
+
+Currently, the package supports a single admin user via environment variables. For multi-user support, you'd need to implement a custom authentication layer.
+
+## Example Admin UI
+
+Check the `/apps/dev` directory in this repository for a complete example with:
+
+- Login page
+- Admin dashboard
+- File editor
+- File management
+
+## Troubleshooting
+
+### "CMS_SESSION_SECRET must be at least 32 characters"
+
+Make sure your session secret is long enough. Generate a secure random string:
+
+```bash
+node -e "console.log(require('crypto').randomBytes(32).toString('hex'))"
+```
+
+### Rate limiting not working across restarts
+
+The rate limiter is in-memory. For persistent rate limiting, implement Redis storage.
+
+### GitHub API rate limits
+
+GitHub API has rate limits. For high-traffic sites, consider caching content or using a CDN.
+
+## License
+
+MIT
+
+## Contributing
+
+Contributions welcome! This is a minimal CMS focused on simplicity and maintainability.
+
+Please report security vulnerabilities privately to fydemy@gmail.com or via GitHub security advisories.
+
+## Links
+
+- [GitHub Repository](https://github.com/fydemy/cms)
+- [npm Package](https://www.npmjs.com/package/@fydemy/cms)
+- [Report Issues](https://github.com/fydemy/cms/issues)
+- [Security Policy](https://github.com/fydemy/cms/blob/main/SECURITY.md)

package/SECURITY.md

@@ -0,0 +1,79 @@
+# Security Policy
+
+## Supported Versions
+
+We release patches for security vulnerabilities for the following versions:
+
+| Version | Supported          |
+| ------- | ------------------ |
+| 1.x.x   | :white_check_mark: |
+| < 1.0   | :x:                |
+
+## Reporting a Vulnerability
+
+**Please do not report security vulnerabilities through public GitHub issues.**
+
+If you discover a security vulnerability in @fydemy/cms, please report it by emailing fydemy@gmail.com (or create a private security advisory on GitHub).
+
+Please include the following information:
+
+- Type of vulnerability
+- Full paths of source file(s) related to the vulnerability
+- Location of the affected source code (tag/branch/commit or direct URL)
+- Step-by-step instructions to reproduce the issue
+- Proof-of-concept or exploit code (if possible)
+- Impact of the issue, including how an attacker might exploit it
+
+We will acknowledge your email within 48 hours and send a more detailed response within 7 days indicating the next steps in handling your report.
+
+## Security Best Practices
+
+When using @fydemy/cms, follow these security best practices:
+
+### Environment Variables
+
+- Use strong, random values for `CMS_SESSION_SECRET` (minimum 32 characters)
+- Use strong passwords for `CMS_ADMIN_PASSWORD`
+- Never commit `.env` files to version control
+- Rotate credentials regularly
+
+### GitHub Token
+
+- Use GitHub Personal Access Tokens with minimal required permissions (only `repo` scope)
+- Use fine-grained personal access tokens when possible
+- Store tokens securely in your deployment platform's secret management
+
+### Network Security
+
+- Always use HTTPS in production
+- Configure your Next.js app behind a reverse proxy or CDN
+- Enable security headers (CSP, HSTS, X-Frame-Options, etc.)
+
+### Rate Limiting
+
+- The built-in rate limiter is memory-based and resets on server restart
+- For production, consider implementing Redis-based rate limiting
+- Monitor failed login attempts
+
+### File Uploads
+
+- The default file size limit is 10MB
+- Validate file types on the client and server
+- Consider implementing virus scanning for uploaded files
+- Use Content Security Policy headers to prevent XSS from uploaded content
+
+### Session Security
+
+- Session cookies are httpOnly, sameSite=lax, and secure in production
+- Sessions expire after 7 days
+- Consider shorter session duration for sensitive applications
+
+## Disclosure Policy
+
+When we receive a security bug report, we will:
+
+1. Confirm the problem and determine affected versions
+2. Audit code to find similar problems
+3. Prepare fixes for all supported versions
+4. Release new versions as soon as possible
+5. Credit the reporter (unless they prefer to remain anonymous)

package/package.json

@@ -0,0 +1,21 @@
+{
+  "name": "@fydemy/cms",
+  "version": "0.0.0",
+  "description": "Simple file-based CMS for Next.js",
+  "scripts": {
+    "dev": "pnpm --filter dev dev",
+    "build": "pnpm --filter @fydemy/cms build",
+    "build:all": "pnpm -r build"
+  },
+  "keywords": [
+    "cms",
+    "nextjs",
+    "markdown",
+    "vercel"
+  ],
+  "author": "",
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.3.3"
+  }
+}