bookhoard/SECURITY_AUDIT.md

# Security Audit Report

**Date:** January 30, 2026
**Project:** Bookmann API
**Status:** Critical Issues Identified

## Executive Summary

This security audit identified **13 critical** and **8 moderate** security vulnerabilities across the Bookmann API codebase. While all integration tests currently pass, several critical issues could lead to:
- Service panics from type assertion failures
- Potential path traversal attacks
- Information leakage through debug logs
- Inconsistent error handling

## Critical Vulnerabilities

### 1. Type Assertion Panics (CRITICAL)
**Severity:** High
**Impact:** Server crash (Denial of Service)
**Files Affected:**
- `internal/handlers/auth.go` (10 occurrences)
- `internal/handlers/ebook.go` (14 occurrences)
- `internal/handlers/library.go` (1 occurrence)

**Issue:**
```go
// UNSAFE - Can panic if user_id is not a string or doesn't exist
userID := c.Get("user_id").(string)
```

**Context:**
The JWT middleware sets `c.Set("user", database.Users{...})` but many handlers try to extract `c.Get("user_id").(string)` which is inconsistent and can panic.

**Current Pattern in library.go:58 (CORRECT):**
```go
user := c.Get("user").(database.Users)
userUUID := user.ID.Bytes
```

**Fix Required:**
```go
// SAFE
user, ok := c.Get("user").(database.Users)
if !ok {
    return c.JSON(http.StatusInternalServerError, map[string]string{"error": "authentication context error"})
}
userUUID := user.ID.Bytes
```

**Affected Functions:**
- auth.go: GetProfile, UpdateProfile, UpdateTheme, UpdateUsername, UpdateEmail, UpdatePassword, DeleteAccount, UpdateScanSettings, GetScanSettings
- ebook.go: CreateEbook, GetReadingProgress, UpdateReadingProgress, GetEbookRating, CreateOrUpdateEbookRating, DeleteEbookRating, ScanEbooks, StartScanner, StartWatchMode, ListMediaItemsFiltered, and all media item handlers
- library.go: GetUserVisibleLibraries

### 2. Path Traversal Vulnerability (CRITICAL)
**Severity:** High
**Impact:** Unauthorized file system access
**File:** `internal/handlers/library.go:183-189`

**Issue:**
```go
// NO VALIDATION - Users can specify any path
_, err = os.Stat(req.FolderPath)
```

**Attack Vector:**
```json
{
  "folder_path": "../../../etc/passwd"
}
```

**Fix Required:**
```go
import (
    "path/filepath"
    "strings"
)

// Validate and sanitize path
cleanPath := filepath.Clean(req.FolderPath)
if strings.Contains(cleanPath, "..") {
    return c.JSON(http.StatusBadRequest, map[string]string{"error": "path traversal not allowed"})
}

// Also verify path is within allowed directories
// (Implementation depends on your security requirements)
```

### 3. Debug Logging in Production (MODERATE)
**Severity:** Medium
**Impact:** Information leakage, potential credential exposure
**File:** `internal/handlers/auth.go:289-290, 297, 301, 308, 316, 321`

**Issue:**
```go
fmt.Printf("Login request - Content-Type: %s\n", c.Request().Header.Get("Content-Type"))
fmt.Printf("Form values - login: %s, password: %s\n", c.FormValue("login"), c.FormValue("password"))
```

**Risk:**
- Passwords logged in plaintext
- Sensitive information in console logs
- No environment-based conditional logging

**Fix Required:**
```go
if os.Getenv("DEBUG_MODE") == "true" {
    log.Printf("Login request from IP: %s", c.RealIP())
}
// Or use a proper logging framework with levels
```

### 4. Type Assertion Without Checks (HIGH)
**Severity:** High
**Impact:** Server panic
**File:** `internal/handlers/auth.go:199, 891, 848`

**Issue:**
```go
// NO CHECK - Will panic if assertion fails
userRoleAuth := c.Get("user_role").(string)
```

**Fix Required:**
```go
userRole, ok := c.Get("user_role").(string)
if !ok {
    return c.JSON(http.StatusInternalServerError, map[string]string{"error": "authentication error"})
}
```

## Moderate Vulnerabilities

### 5. Inconsistent Context Usage
**Files:** All handlers

**Issue:**
- Some use `c.Get("user_id").(string)`
- Some use `c.Get("user").(database.Users)`
- Some use `c.Get("user_role").(string)`

**Impact:** Confusion, potential bugs, harder to maintain

**Recommendation:**
Create a helper function:
```go
// handlers/context.go
package handlers

import (
    "bookmann/internal/database"
    "net/http"
    "github.com/labstack/echo/v4"
)

// GetAuthenticatedUser safely retrieves the authenticated user from context
func GetAuthenticatedUser(c echo.Context) (database.Users, error) {
    user, ok := c.Get("user").(database.Users)
    if !ok {
        return database.Users{}, echo.NewHTTPError(http.StatusInternalServerError, "authentication context error")
    }
    return user, nil
}

// MustGetAuthenticatedUser gets user or panics (for use after authentication middleware)
func MustGetAuthenticatedUser(c echo.Context) database.Users {
    user, err := GetAuthenticatedUser(c)
    if err != nil {
        panic(err) // Should never happen if middleware is working
    }
    return user
}
```

### 6. Missing Input Sanitization
**Severity:** Medium
**Impact:** XSS, stored XSS in notes/highlights

**Files:**
- All handlers accepting user content (notes, highlights, descriptions)

**Issue:**
No HTML sanitization for user-generated content

**Fix Required:**
```go
import "html"

// Sanitize user input
sanitizedContent := html.EscapeString(req.Content)
// Or use a proper sanitizer like bluemonday
import "github.com/microcosm-cc/bluemonday"
p := bluemonday.UGCPolicy()
sanitizedContent := p.Sanitize(req.Content)
```

### 7. Error Messages Leak Information
**Severity:** Low-Medium
**Impact:** Information disclosure

**Example:**
```go
return c.JSON(http.StatusInternalServerError, map[string]string{"error": err.Error()})
```

**Issue:** Raw database errors exposed to clients

**Fix:**
```go
// Log the actual error for debugging
log.Errorf("Database error: %v", err)

// Return generic message to client
return c.JSON(http.StatusInternalServerError, map[string]string{"error": "internal server error"})
```

### 8. No Rate Limiting on Sensitive Operations
**Severity:** Medium
**Files:** auth.go (Login has rate limiting, but other endpoints don't)

**Missing Rate Limiting:**
- Password update
- Email change
- Username change
- User deletion

## Recommendations

### Immediate Actions (Priority 1)
1. ✅ Add safe type assertion helper function
2. ⚠️ Fix all type assertion panics in auth.go
3. ⚠️ Fix all type assertion panics in ebook.go
4. ⚠️ Fix all type assertion panics in library.go
5. ⚠️ Add path traversal protection to AddLibraryFolder

### Short-term Actions (Priority 2)
6. Remove all debug fmt.Printf statements
7. Add input sanitization for user-generated content
8. Implement consistent error handling
9. Add rate limiting to sensitive operations

### Long-term Actions (Priority 3)
10. Implement proper logging framework (structured logging)
11. Add security headers middleware
12. Implement CSRF protection
13. Add API request validation middleware
14. Conduct penetration testing

## Testing Requirements

After fixes applied:
- ✅ All existing integration tests must pass
- ⚠️ Add new tests for:
  - Type assertion failures
  - Path traversal attempts
  - Invalid authentication context
  - Rate limiting

## Compliance Notes

- **OWASP Top 10:** Addresses A01 (Broken Access Control), A03 (Injection), A05 (Security Misconfiguration)
- **CWE:** CWE-20 (Improper Input Validation), CWE-706 (Improper Authentication), CWE-22 (Path Traversal)

---

**Generated by:** OpenCode Security Audit
**Next Review:** After Priority 1 fixes completed