# MD Hub Secure - Project Plan

**Version:** 1.0  
**Date:** 2026-04-28  
**Status:** Draft

## Vision

A minimal-dependency, ultra-fast documentation platform that publishes markdown notes as a responsive web application. Features wiki-style linking, collaborative comments, offline-capable sync, and fine-grained access control — all deployable via a single `docker-compose.yml` with zero vendor lock-in.

## Design Principles

1. **Paranoid Security**: Cryptographic content verification, battle-tested dependencies only, supply-chain attack mitigation through minimal external code
2. **Operational Simplicity**: Single binary, single SQLite database, filesystem storage — nothing that can't be understood in an afternoon
3. **Performance First**: Sub-100ms initial page loads, instant client-side navigation, no JavaScript required for reading
4. **Offline Capability**: Read cached, sync when connected
5. **No Vendor Lock-in**: Works on any Docker host; no cloud-specific APIs

---

## Milestones

### Milestone 1: Foundation (Weeks 1-2)
**Goal:** Working server that can serve markdown files as HTML

- Go HTTP server with chi router
- libsql database with schema migration system
- Markdown-to-HTML pipeline with all extensions
- Static file serving for attachments
- Basic Dockerfile and docker-compose.yml

**Acceptance Criteria:**
- [ ] Server starts and listens on configurable port
- [ ] Database auto-migrates on startup
- [ ] Markdown files with wiki-links, tags, callouts, mermaid, math render correctly
- [ ] Attachments served securely with content-type headers
- [ ] Docker compose brings up full stack with one command
- [ ] All dependencies pinned with checksum verification
- [ ] Build reproducible (same input → same binary hash)

---

### Milestone 2: Sync Protocol (Weeks 3-4)
**Goal:** Bidirectional file sync between server and filesystem/web client

- Content-addressed storage (SHA-256 filesystem layout)
- WebSocket sync protocol implementation
- File watcher for local filesystem sync
- Client-side IndexedDB cache
- Offline queue with conflict detection

**Acceptance Criteria:**
- [ ] File changes on disk automatically sync to server within 5 seconds
- [ ] Web client can sync after reconnection, even with changes made offline
- [ ] Concurrent edits to different files succeed without conflict
- [ ] Concurrent edits to same file detected and queued for resolution
- [ ] All synced content verified against SHA-256 hashes
- [ ] Sync protocol documented with state machine diagrams

---

### Milestone 3: Authentication & Authorization (Weeks 5-6)
**Goal:** Secure access control with passkeys and granular permissions

- Passkey (WebAuthn) primary authentication
- Password fallback with Argon2id
- Session management with signed cookies
- Role-based access control (RBAC)
- Content signing with Ed25519 (optional per-user)

**Acceptance Criteria:**
- [ ] Users can register and log in with passkeys on modern browsers
- [ ] Password fallback works with proper hashing
- [ ] Sessions expire securely and are revocable
- [ ] Read/write/admin permissions work per-document and per-collection
- [ ] All auth endpoints rate-limited and logged
- [ ] Security audit: no plaintext secrets, no timing attacks on auth

---

### Milestone 4: Collaboration Features (Weeks 7-8)
**Goal:** Comments, notifications, and conflict resolution

- Comment system linked to file versions (by hash)
- Email notifications via Postmark adapter
- Web-based conflict resolution UI
- Notification preferences (per-file, per-folder, global, digest)
- Comment threading and email replies

**Acceptance Criteria:**
- [ ] Users can comment on specific lines/sections of a document
- [ ] Comments persist and are linked to document versions
- [ ] Email notifications sent for watched file changes
- [ ] Replying to notification email creates a comment
- [ ] Conflicts display side-by-side diff with resolution actions
- [ ] Digest mode batches notifications by time window

---

### Milestone 5: Search & UI Polish (Weeks 9-10)
**Goal:** Fast search, design system, and production readiness

- Full-text search with SQLite FTS5
- Client-side search index sync
- Design system with browser-based CSS editor
- Responsive mobile layout
- Error boundaries and loading states
- Performance benchmarking

**Acceptance Criteria:**
- [ ] Search returns results in <50ms on client
- [ ] Search works offline after initial sync
- [ ] Design system documented at `/design` route
- [ ] All screens responsive down to 320px width
- [ ] Lighthouse score >90 on all metrics
- [ ] Initial page load <100ms (server-rendered HTML)

---

### Milestone 6: Production Hardening (Weeks 11-12)
**Goal:** Deploy with confidence

- Comprehensive test suite (unit, integration, e2e)
- Security audit and penetration testing guide
- Backup and restore procedures
- Monitoring and health checks
- Documentation for operators

**Acceptance Criteria:**
- [ ] >80% test coverage
- [ ] No critical or high-severity security findings
- [ ] Backup script exports database + attachments as tar.gz
- [ ] Health check endpoint returns status of all dependencies
- [ ] Operator docs cover: install, upgrade, backup, security incident response
- [ ] Load test: 1000 concurrent readers, 100 concurrent editors

---

## Architecture Overview

```
┌─────────────────────────────────────────────────────────────┐
│                        Client Browser                        │
│  ┌──────────────┐  ┌──────────────┐  ┌─────────────────┐   │
│  │   Preact UI  │  │  File Sync   │  │  Search Index   │   │
│  │  (hydrated)  │  │  (IndexedDB) │  │    (FTS5)       │   │
│  └──────────────┘  └──────────────┘  └─────────────────┘   │
└─────────────────────────────────────────────────────────────┘
                            │
                     WebSocket / HTTP
                            │
┌─────────────────────────────────────────────────────────────┐
│                      Go Application Server                   │
│  ┌────────────┐ ┌────────────┐ ┌────────────┐ ┌──────────┐ │
│  │   HTTP     │ │ WebSocket  │ │  Markdown  │ │   Auth   │ │
│  │   Router   │ │   Sync     │ │  Renderer  │ │ (WebAuthn)│ │
│  └────────────┘ └────────────┘ └────────────┘ └──────────┘ │
│  ┌────────────┐ ┌────────────┐ ┌────────────┐              │
│  │   Email    │ │  Search    │ │ File Watch │              │
│  │  (Postmark)│ │   (FTS5)   │ │   (fsnotify)│             │
│  └────────────┘ └────────────┘ └────────────┘              │
└─────────────────────────────────────────────────────────────┘
                            │
         ┌──────────────────┴──────────────────┐
         │                                     │
  ┌──────────────┐                    ┌──────────────┐
  │   libsql     │                    │  Content-    │
  │  (SQLite)    │                    │  Addressed   │
  │              │                    │  Filesystem  │
  └──────────────┘                    └──────────────┘
```

See [architecture-overview.md](architecture-overview.md) for detailed component design.

---

## Technology Stack

### Backend (Go 1.22+)
| Component | Library | Justification |
|-----------|---------|---------------|
| HTTP Router | `github.com/go-chi/chi` | Minimal, idiomatic, stdlib-compatible |
| Database | `github.com/tursodatabase/libsql-client-go` | Embedded SQLite with replication option |
| Migrations | `github.com/golang-migrate/migrate` | Battle-tested, version-controlled schema |
| Auth/Passkeys | `github.com/go-webauthn/webauthn` | Reference implementation, well-audited |
| Password Hash | `golang.org/x/crypto/argon2` | Winner of Password Hashing Competition |
| Markdown | `github.com/yuin/goldmark` + extensions | Fast, extensible, CommonMark compliant |
| WebSocket | `github.com/gorilla/websocket` | Most widely used Go WS library |
| File Watch | `github.com/fsnotify/fsnotify` | Cross-platform, stdlib-adjacent |
| Email | `github.com/keighl/postmark` + `net/smtp` | Postmark adapter + SMTP fallback |
| Crypto | `crypto/ed25519`, `crypto/sha256` | Standard library, no external deps |
| Templates | `html/template` | Stdlib, auto-escaping, SSR-safe |

### Frontend (Preact + TypeScript)
| Component | Library | Justification |
|-----------|---------|---------------|
| Framework | `preact` (10KB) | React API, tiny bundle, fast hydration |
| Routing | `preact-iso` | Lightweight isomorphic routing |
| Markdown | `marked` + `micromark` | Server+client compatible |
| Search | `flexsearch` | Client-side full-text, zero server load |
| Styling | Native CSS + custom properties | No build-time CSS processing needed |
| Icons | Inline SVG | No icon font dependency |
| Build | `vite` | Fast HMR, modern output, minimal config |

### Infrastructure
| Component | Technology | Justification |
|-----------|-----------|---------------|
| Container | Docker + Compose | Universal deployment target |
| Reverse Proxy | Traefik (optional) | Auto-HTTPS, included in compose |
| Database | libsql/SQLite | Single file, zero external dependency |
| Storage | Local filesystem | Content-addressed, immutable, backup-friendly |

---

## Security Model

### Threats Addressed
1. **Supply Chain Attacks**: Minimal external dependencies; all pinned with go.sum; vendored if needed
2. **Data Tampering**: All document versions SHA-256 hashed; optional Ed25519 signatures
3. **Unauthorized Access**: RBAC with principle of least privilege; content never served without auth check
4. **Session Hijacking**: Signed cookies with HttpOnly, Secure, SameSite=Strict; short expiry with refresh
5. **CSRF**: Double-submit cookie pattern for state-changing operations
6. **XSS**: Go html/template auto-escaping; strict CSP headers; no inline scripts except nonce-tagged
7. **DoS**: Rate limiting on auth endpoints; file upload size limits; query timeouts

### Content Security
- Attachment uploads: Magic number validation, extension whitelist, size limits
- Markdown rendering: Sanitized HTML output; no raw HTML injection
- File paths: Canonicalization prevents directory traversal

### Audit & Compliance
- Every data modification logged with user, timestamp, IP, and content hash
- Immutable history table — updates are inserts
- GDPR-compliant: full data export and deletion capability

---

## Performance Targets

| Metric | Target | Measurement |
|--------|--------|-------------|
| Initial Page Load | <100ms | TTFB + First Contentful Paint |
| Time to Interactive | <200ms | Hydration complete |
| Search Query | <50ms | Client-side after initial sync |
| File Sync | <5s | From disk save to server persist |
| Bundle Size | <100KB | Gzipped JS + CSS |
| Concurrent Users | 1000 readers, 100 editors | Load tested |

---

## Monorepo Structure

```
md-hub-secure/
├── README.md
├── docker-compose.yml
├── Dockerfile
├── Makefile
├── docs/                          # Project documentation
│   ├── project-plan.md            # This file
│   ├── architecture-overview.md   # System architecture
│   ├── adrs/                      # Architecture Decision Records
│   ├── milestones/                # Detailed milestone plans
│   └── specs/                     # Technical specifications
├── apps/
│   ├── server/                    # Go HTTP application
│   │   ├── main.go
│   │   ├── internal/
│   │   │   ├── api/               # HTTP handlers
│   │   │   ├── auth/              # Authentication & authorization
│   │   │   ├── config/            # Configuration management
│   │   │   ├── db/                # Database models & migrations
│   │   │   ├── markdown/          # Markdown rendering pipeline
│   │   │   ├── search/            # Full-text search
│   │   │   ├── sync/              # SimpleSync protocol
│   │   │   ├── email/             # Postmark integration
│   │   │   └── fs/                # Content-addressed filesystem
│   │   └── web/static/            # Built frontend assets
│   └── web/                       # Preact frontend application
│       ├── src/
│       │   ├── components/        # Reusable UI components
│       │   ├── pages/             # Route-level components
│       │   ├── lib/               # Utilities & API client
│       │   ├── stores/            # State management
│       │   └── styles/            # CSS custom properties & themes
│       ├── design-system.html     # Browser-based design tool
│       └── index.html
└── packages/
    └── protocol/                  # Shared sync protocol spec
        ├── sync.proto             # Protocol buffer definition
        └── go/                    # Go generated types
```

---

## Risk Register

| Risk | Likelihood | Impact | Mitigation |
|------|-----------|--------|------------|
| WebAuthn/passkey adoption issues | Medium | Medium | Password fallback always available; extensive browser testing |
| SQLite performance at scale | Low | High | libsql replication path; FTS5 for search; benchmark early |
| Markdown extension parser bugs | Medium | Medium | Fuzz testing; strict CommonMark base; gradual feature rollout |
| Email deliverability | Medium | Medium | Postmark reputation monitoring; SPF/DKIM setup; SMTP fallback |
| Frontend bundle bloat | Medium | Medium | Bundle analysis in CI; tree-shaking enforced; lazy loading |
| File sync conflicts in teams | High | Medium | Clear UX for conflict resolution; email notification; automatic merge when possible |

---

## Next Steps

1. Review and approve this plan
2. Set up repository structure and CI pipeline
3. Begin Milestone 1: Foundation
4. Schedule weekly architecture review meetings during Milestone 2 (sync protocol)

---

## Glossary

- **ADR**: Architecture Decision Record
- **CRDT**: Conflict-free Replicated Data Type (not used, but considered)
- **CSRF**: Cross-Site Request Forgery
- **CSP**: Content Security Policy
- **FTS5**: SQLite Full-Text Search version 5
- **RBAC**: Role-Based Access Control
- **SSR**: Server-Side Rendering
- **TTFB**: Time to First Byte
- **WebAuthn**: Web Authentication API (passkeys)