// HTTP/Minimal Reference Server // A compliant server implementation for the HTTP/Minimal specification. // // Usage: // go run main.go -dir ./content -port 8080 // // The server will: // - Serve Markdown files from the content directory // - Content-negotiate between text/markdown and text/html // - Strip raw HTML from Markdown before serving // - Validate and enforce HTTP/Minimal constraints // - Serve /.well-known/http-minimal policy endpoint package main import ( "bytes" "encoding/json" "flag" "fmt" "html/template" "io" "log" "mime" "net/http" "os" "path/filepath" "regexp" "strings" "github.com/yuin/goldmark" "github.com/yuin/goldmark/extension" "github.com/yuin/goldmark/parser" "github.com/yuin/goldmark/renderer/html" "gopkg.in/yaml.v3" ) // Config holds server configuration type Config struct { Port string ContentDir string TemplateFile string BaseURL string Contact string } // FrontMatter represents YAML front matter in Markdown documents type FrontMatter struct { Title string `yaml:"title"` Author string `yaml:"author"` Date string `yaml:"date"` Lang string `yaml:"lang"` License string `yaml:"license"` Description string `yaml:"description"` } // WellKnown represents the /.well-known/http-minimal response type WellKnown struct { HTTPMinimal string `json:"http_minimal"` Compliant bool `json:"compliant"` Scope string `json:"scope"` Contact string `json:"contact,omitempty"` } // Server implements an HTTP/Minimal compliant server type Server struct { config Config markdown goldmark.Markdown htmlTmpl *template.Template } // defaultHTMLTemplate is the built-in fallback template for rendering Markdown to browsers const defaultHTMLTemplate = ` {{.Title}} {{if .URL}}{{end}} {{if .Description}}{{end}} {{if .Author}}{{end}} {{.Content}} ` func main() { config := Config{} flag.StringVar(&config.Port, "port", "8080", "Listen port") flag.StringVar(&config.ContentDir, "dir", "./content", "Content directory") flag.StringVar(&config.TemplateFile, "template", "", "HTML template file (default: built-in template)") flag.StringVar(&config.BaseURL, "base-url", "http://localhost:8080", "Base URL for the site") flag.StringVar(&config.Contact, "contact", "", "Contact email for /.well-known/http-minimal") flag.Parse() server, err := NewServer(config) if err != nil { log.Fatalf("Failed to create server: %v", err) } log.Printf("HTTP/Minimal server starting on %s", config.Port) log.Printf("Serving content from: %s", config.ContentDir) log.Fatal(http.ListenAndServe(":"+config.Port, server)) } // TemplateViolation represents a compliance issue found in a template type TemplateViolation struct { Rule string Details string } // validateTemplate checks a template for HTTP/Minimal compliance violations func validateTemplate(content string) []TemplateViolation { var violations []TemplateViolation contentLower := strings.ToLower(content) // Check for forbidden elements forbiddenElements := []struct { pattern string rule string }{ {" tags are forbidden"}, {" tags are forbidden"}, {" tags are forbidden"}, {" tags are forbidden"}, {" tags are forbidden"}, {" tags are forbidden"}, } for _, elem := range forbiddenElements { if strings.Contains(contentLower, elem.pattern) { violations = append(violations, TemplateViolation{ Rule: elem.rule, Details: fmt.Sprintf("Found '%s' in template", elem.pattern), }) } } // Check for inline JavaScript event handlers eventHandlers := []string{ "onclick", "onload", "onerror", "onmouseover", "onmouseout", "onsubmit", "onfocus", "onblur", "onchange", "onkeydown", "onkeyup", "onkeypress", "ondblclick", "onscroll", "onresize", } for _, handler := range eventHandlers { pattern := regexp.MustCompile(`(?i)\s` + handler + `\s*=`) if pattern.MatchString(content) { violations = append(violations, TemplateViolation{ Rule: "No JavaScript: inline event handlers are forbidden", Details: fmt.Sprintf("Found '%s' attribute in template", handler), }) } } // Check for javascript: URLs if strings.Contains(contentLower, "javascript:") { violations = append(violations, TemplateViolation{ Rule: "No JavaScript: javascript: URLs are forbidden", Details: "Found 'javascript:' URL in template", }) } // Check for common tracking/analytics patterns trackingPatterns := []struct { pattern string name string }{ {"google-analytics.com", "Google Analytics"}, {"googletagmanager.com", "Google Tag Manager"}, {"facebook.net", "Facebook tracking"}, {"plausible.io", "Plausible Analytics"}, {"analytics.", "Analytics service"}, {"tracking.", "Tracking service"}, {"pixel.", "Tracking pixel"}, {"beacon.", "Tracking beacon"}, } for _, tp := range trackingPatterns { if strings.Contains(contentLower, tp.pattern) { violations = append(violations, TemplateViolation{ Rule: "No tracking: external tracking services are forbidden", Details: fmt.Sprintf("Found reference to %s (%s)", tp.name, tp.pattern), }) } } // Check for external stylesheets (could be tracking vectors) externalCSSPattern := regexp.MustCompile(`(?i)]+rel\s*=\s*["']?stylesheet["']?[^>]+href\s*=\s*["']?https?://`) if externalCSSPattern.MatchString(content) { violations = append(violations, TemplateViolation{ Rule: "External resources: external stylesheets may enable tracking", Details: "Found external stylesheet link (warning)", }) } // Check for external fonts (could be tracking vectors) if strings.Contains(contentLower, "fonts.googleapis.com") || strings.Contains(contentLower, "fonts.gstatic.com") { violations = append(violations, TemplateViolation{ Rule: "External resources: external fonts may enable tracking", Details: "Found Google Fonts reference (warning)", }) } return violations } // NewServer creates a new HTTP/Minimal server func NewServer(config Config) (*Server, error) { // Initialize Goldmark with GFM extensions md := goldmark.New( goldmark.WithExtensions( extension.GFM, // Tables, strikethrough, autolinks extension.Footnote, // Footnotes ), goldmark.WithParserOptions( parser.WithAutoHeadingID(), ), goldmark.WithRendererOptions( html.WithUnsafe(), // We'll strip HTML ourselves for validation ), ) // Load HTML template var tmpl *template.Template var tmplContent string if config.TemplateFile != "" { // Load from file content, err := os.ReadFile(config.TemplateFile) if err != nil { return nil, fmt.Errorf("failed to read template file: %w", err) } tmplContent = string(content) tmpl, err = template.New("page").Parse(tmplContent) if err != nil { return nil, fmt.Errorf("failed to parse template file: %w", err) } log.Printf("Using custom template: %s", config.TemplateFile) } else { // Use built-in default tmplContent = defaultHTMLTemplate var err error tmpl, err = template.New("page").Parse(tmplContent) if err != nil { return nil, fmt.Errorf("failed to parse default template: %w", err) } } // Validate template for HTTP/Minimal compliance violations := validateTemplate(tmplContent) if len(violations) > 0 { log.Printf("Template validation found %d issue(s):", len(violations)) hasError := false for _, v := range violations { // Warnings don't block startup, errors do isWarning := strings.Contains(v.Details, "(warning)") if isWarning { log.Printf(" WARNING: %s - %s", v.Rule, v.Details) } else { log.Printf(" ERROR: %s - %s", v.Rule, v.Details) hasError = true } } if hasError { return nil, fmt.Errorf("template validation failed: %d compliance violation(s) found", len(violations)) } } return &Server{ config: config, markdown: md, htmlTmpl: tmpl, }, nil } // ServeHTTP implements http.Handler func (s *Server) ServeHTTP(w http.ResponseWriter, r *http.Request) { // Enforce method restrictions if r.Method != http.MethodGet && r.Method != http.MethodHead { http.Error(w, "Method not allowed", http.StatusMethodNotAllowed) return } // Strip forbidden request headers (log them for debugging) if cookie := r.Header.Get("Cookie"); cookie != "" { log.Printf("NOTICE: Stripped Cookie header from request to %s", r.URL.Path) } // Route handling switch { case r.URL.Path == "/.well-known/http-minimal": s.handleWellKnown(w, r) default: s.handleContent(w, r) } } // handleWellKnown serves the /.well-known/http-minimal endpoint func (s *Server) handleWellKnown(w http.ResponseWriter, r *http.Request) { wellKnown := WellKnown{ HTTPMinimal: "0.1", Compliant: true, Scope: "/", Contact: s.config.Contact, } w.Header().Set("Content-Type", "application/json; charset=utf-8") w.Header().Set("Cache-Control", "max-age=86400") s.setMinimalHeaders(w) json.NewEncoder(w).Encode(wellKnown) } // handleContent serves Markdown content with content negotiation func (s *Server) handleContent(w http.ResponseWriter, r *http.Request) { // Clean and resolve the path urlPath := filepath.Clean(r.URL.Path) if urlPath == "/" || urlPath == "." { urlPath = "/index" } // Try to find the markdown file mdPath := filepath.Join(s.config.ContentDir, urlPath+".md") if _, err := os.Stat(mdPath); os.IsNotExist(err) { // Try without .md extension (maybe it's a directory with index.md) indexPath := filepath.Join(s.config.ContentDir, urlPath, "index.md") if _, err := os.Stat(indexPath); err == nil { mdPath = indexPath } else { // Check if it's a static file (images, etc.) staticPath := filepath.Join(s.config.ContentDir, urlPath) if info, err := os.Stat(staticPath); err == nil && !info.IsDir() { s.serveStaticFile(w, r, staticPath) return } http.NotFound(w, r) return } } // Read the markdown file content, err := os.ReadFile(mdPath) if err != nil { log.Printf("Error reading file %s: %v", mdPath, err) http.Error(w, "Internal server error", http.StatusInternalServerError) return } // Parse front matter and content frontMatter, body := s.parseFrontMatter(content) // Strip raw HTML from markdown (HTTP/Minimal compliance) cleanBody := s.stripRawHTML(body) // Validate the document if errors := s.validateDocument(cleanBody); len(errors) > 0 { log.Printf("Validation warnings for %s: %v", mdPath, errors) } // Content negotiation accept := r.Header.Get("Accept") wantsMarkdown := s.prefersMarkdown(accept) // Get file modification time for caching headers info, _ := os.Stat(mdPath) modTime := info.ModTime() // Set common headers s.setMinimalHeaders(w) w.Header().Set("Last-Modified", modTime.UTC().Format(http.TimeFormat)) w.Header().Set("Cache-Control", "max-age=3600") w.Header().Set("Link", `; rel="profile"`) if wantsMarkdown { // Serve raw markdown w.Header().Set("Content-Type", "text/markdown; charset=utf-8; variant=CommonMark") w.Write(cleanBody) } else { // Render to HTML for browsers s.renderHTML(w, r, frontMatter, cleanBody) } } // serveStaticFile serves static files (images, etc.) func (s *Server) serveStaticFile(w http.ResponseWriter, r *http.Request, path string) { // Validate the file type is allowed ext := strings.ToLower(filepath.Ext(path)) allowedTypes := map[string]string{ ".jpg": "image/jpeg", ".jpeg": "image/jpeg", ".png": "image/png", ".gif": "image/gif", ".webp": "image/webp", ".avif": "image/avif", ".svg": "image/svg+xml", ".ico": "image/x-icon", } contentType, allowed := allowedTypes[ext] if !allowed { http.Error(w, "Forbidden file type", http.StatusForbidden) return } s.setMinimalHeaders(w) w.Header().Set("Content-Type", contentType) w.Header().Set("Cache-Control", "max-age=86400") http.ServeFile(w, r, path) } // parseFrontMatter extracts YAML front matter from markdown content func (s *Server) parseFrontMatter(content []byte) (FrontMatter, []byte) { fm := FrontMatter{ Lang: "en", // Default language } if !bytes.HasPrefix(content, []byte("---\n")) { return fm, content } // Find the closing --- rest := content[4:] end := bytes.Index(rest, []byte("\n---\n")) if end == -1 { return fm, content } // Parse YAML yamlContent := rest[:end] if err := yaml.Unmarshal(yamlContent, &fm); err != nil { log.Printf("Warning: failed to parse front matter: %v", err) return fm, content } // Return content after front matter body := rest[end+5:] return fm, body } // stripRawHTML removes raw HTML from Markdown content func (s *Server) stripRawHTML(content []byte) []byte { // Pattern to match HTML tags htmlBlockPattern := regexp.MustCompile(`(?s)<[a-zA-Z][^>]*>.*?|<[a-zA-Z][^>]*/?>`) // Pattern to match HTML comments commentPattern := regexp.MustCompile(`(?s)`) result := commentPattern.ReplaceAll(content, []byte{}) result = htmlBlockPattern.ReplaceAll(result, []byte{}) return result } // validateDocument checks for HTTP/Minimal compliance func (s *Server) validateDocument(content []byte) []string { var errors []string // Check for remaining HTML (shouldn't exist after stripping, but double-check) if bytes.Contains(content, []byte(" tag") } if bytes.Contains(content, []byte(" tag") } if bytes.Contains(content, []byte(" tag") } // Check for images without alt text imgPattern := regexp.MustCompile(`!\[\]\(`) if imgPattern.Match(content) { errors = append(errors, "Document contains images without alt text") } return errors } // prefersMarkdown checks if the client prefers markdown over HTML func (s *Server) prefersMarkdown(accept string) bool { if accept == "" { return false } // Parse Accept header types := strings.Split(accept, ",") for _, t := range types { mediaType, _, err := mime.ParseMediaType(strings.TrimSpace(t)) if err != nil { continue } switch mediaType { case "text/markdown", "text/x-markdown": return true case "text/html", "application/xhtml+xml": return false case "*/*": // Wildcard - prefer HTML for browsers return false } } return false } // renderHTML renders markdown to HTML using the template func (s *Server) renderHTML(w http.ResponseWriter, r *http.Request, fm FrontMatter, content []byte) { var htmlBuf bytes.Buffer if err := s.markdown.Convert(content, &htmlBuf); err != nil { log.Printf("Error converting markdown: %v", err) http.Error(w, "Internal server error", http.StatusInternalServerError) return } // Set title from front matter or first heading title := fm.Title if title == "" { title = s.extractTitle(content) } if title == "" { title = "Untitled" } lang := fm.Lang if lang == "" { lang = "en" } // Build canonical URL pageURL := s.config.BaseURL + r.URL.Path // Extract description from front matter or first paragraph description := fm.Description if description == "" { description = s.extractDescription(content) } data := struct { Title string Lang string Content template.HTML URL string Description string Author string }{ Title: title, Lang: lang, Content: template.HTML(htmlBuf.String()), URL: pageURL, Description: description, Author: fm.Author, } w.Header().Set("Content-Type", "text/html; charset=utf-8") var pageBuf bytes.Buffer if err := s.htmlTmpl.Execute(&pageBuf, data); err != nil { log.Printf("Error executing template: %v", err) http.Error(w, "Internal server error", http.StatusInternalServerError) return } io.Copy(w, &pageBuf) } // extractDescription extracts the first paragraph from markdown content func (s *Server) extractDescription(content []byte) string { lines := bytes.Split(content, []byte("\n")) var paragraph []byte inParagraph := false for _, line := range lines { trimmed := bytes.TrimSpace(line) // Skip headings, blank lines at start, and front matter markers if len(trimmed) == 0 { if inParagraph { break // End of first paragraph } continue } if bytes.HasPrefix(trimmed, []byte("#")) { continue } if bytes.HasPrefix(trimmed, []byte("---")) { continue } if bytes.HasPrefix(trimmed, []byte("-")) || bytes.HasPrefix(trimmed, []byte("*")) { if !inParagraph { continue // Skip list items at start } break } // Found paragraph text inParagraph = true if len(paragraph) > 0 { paragraph = append(paragraph, ' ') } paragraph = append(paragraph, trimmed...) } desc := string(paragraph) // Truncate to reasonable length for og:description if len(desc) > 200 { desc = desc[:197] + "..." } return desc } // extractTitle extracts the first heading from markdown content func (s *Server) extractTitle(content []byte) string { lines := bytes.Split(content, []byte("\n")) for _, line := range lines { line = bytes.TrimSpace(line) if bytes.HasPrefix(line, []byte("# ")) { return string(bytes.TrimPrefix(line, []byte("# "))) } } return "" } // setMinimalHeaders sets headers required by HTTP/Minimal and removes forbidden ones func (s *Server) setMinimalHeaders(w http.ResponseWriter) { // Explicitly delete any forbidden headers that might be set by middleware w.Header().Del("Set-Cookie") w.Header().Del("WWW-Authenticate") w.Header().Del("Content-Security-Policy") w.Header().Del("X-Frame-Options") w.Header().Del("Refresh") // Add security headers that don't conflict with the spec w.Header().Set("X-Content-Type-Options", "nosniff") }