mcp-outline-postgresql/CHANGELOG.md

# Changelog

All notable changes to this project will be documented in this file.

## [1.2.4] - 2026-01-31

### Security

- **SQL Injection Prevention (Pagination):** Fixed critical SQL injection vulnerability in cursor pagination
  - `pagination.ts`: Added `validateFieldName()` function to sanitize field names
  - Field names (`cursorField`, `secondaryField`) are now validated against alphanumeric + underscore + dot pattern
  - Rejects dangerous SQL keywords (SELECT, INSERT, UPDATE, DELETE, DROP, UNION, etc.)
  - Prevents injection via cursor field names in ORDER BY clauses

- **Cryptographic Random (Transaction Retry):** Replaced `Math.random()` with `crypto.randomBytes()` for jitter calculation
  - `transaction.ts`: Retry jitter now uses cryptographically secure random generation
  - Maintains consistency with project security standards

### Fixed

- **Memory Leak (Pool Monitoring):** Added `.unref()` to `setInterval` in `PoolMonitor`
  - `monitoring.ts`: Pool monitoring interval now allows process to exit gracefully
  - Prevents memory leak and hanging processes on shutdown

## [1.2.3] - 2026-01-31

### Security

- **Cryptographic Random Generation:** Replaced `Math.random()` with `crypto.randomBytes()` for secure secret generation
  - `oauth.ts`: OAuth client secrets now use cryptographically secure random generation
  - `api-keys.ts`: API keys now use cryptographically secure random generation
  - API keys now store only the hash, not the plain text secret (prevents database breach exposure)

- **URL Validation:** Added `isValidHttpUrl()` to reject dangerous URL protocols
  - `emojis.ts`: Emoji URLs must be HTTP(S) - prevents javascript:, data:, file: protocols
  - `webhooks.ts`: Webhook URLs must be HTTP(S) - both create and update operations
  - `users.ts`: Avatar URLs must be HTTP(S) or null

- **Integer Validation:** Added validation for numeric IDs from external systems
  - `desk-sync.ts`: `desk_project_id` and `desk_task_id` validated as positive integers
  - Prevents injection via numeric parameters

- **Memory Leak Fix:** Fixed `setInterval` memory leak in rate limiting
  - Rate limit cleanup interval now properly managed with start/stop functions
  - Uses `unref()` to allow process to exit cleanly
  - Added graceful shutdown handler to clean up intervals

### Fixed

- **parseInt Radix:** Added explicit radix (10) to all `parseInt()` calls across 5 files
  - `collections.ts`, `groups.ts`, `revisions.ts`, `users.ts`, `security.ts`

- **Savepoint SQL Injection:** Added `sanitizeSavepointName()` to prevent SQL injection in savepoints
  - Validates savepoint names against PostgreSQL identifier rules

- **Share URL Generation:** Replaced `Math.random()` with `crypto.randomBytes()` for share URL IDs
  - Also replaced deprecated `.substr()` with modern approach

## [1.2.2] - 2026-01-31

### Security

- **SQL Injection Prevention:** Fixed 21 SQL injection vulnerabilities across analytics, advanced-search, and search-queries modules
  - Replaced string interpolation with parameterized queries for all user inputs
  - Added `validateDaysInterval()` function for safe interval validation
  - Added `isValidISODate()` function for date format validation
  - Added `validatePeriod()` function for period parameter validation
  - All UUID validations now occur BEFORE string construction
  - Using `make_interval(days => N)` for safe interval expressions

- **Transaction Support:** Added atomic operations for bulk operations
  - `bulk-operations.ts`: All 6 bulk operations now use transactions
  - `desk-sync.ts`: Create project doc and link task use transactions
  - `export-import.ts`: Import markdown folder uses transactions

- **Rate Limiting:** Added automatic cleanup of expired entries (every 5 minutes)

### Added

- **Transaction Helper (`src/utils/transaction.ts`):** Centralized transaction management with advanced features
  - `withTransaction()`: Execute operations with automatic retry for deadlocks (exponential backoff + jitter)
  - `withTransactionNoRetry()`: Execute without retry for operations with side effects
  - `withReadOnlyTransaction()`: Read-only transactions with SERIALIZABLE isolation
  - `Savepoint` class: Support for nested transaction-like behavior
  - Configurable retry (maxRetries, baseDelayMs, maxDelayMs, timeoutMs)
  - Automatic detection of retryable PostgreSQL errors (40001, 40P01, 55P03)

- **SafeQueryBuilder (`src/utils/query-builder.ts`):** Helper class for building parameterized queries
  - Automatic parameter index management
  - Built-in UUID validation (`buildUUIDEquals`, `buildUUIDIn`)
  - ILIKE helpers for case-insensitive search (`buildILike`, `buildILikePrefix`)
  - Comparison operators (`buildEquals`, `buildBetween`, `buildGreaterThan`, etc.)
  - Array operators (`buildIn`, `buildNotIn`)
  - NULL checks (`buildIsNull`, `buildIsNotNull`)
  - Condition builder with `addCondition()` and `addConditionIf()`

- **Input Validation (`src/utils/validation.ts`):** Zod-based validation system
  - Common schemas: uuid, email, pagination, isoDate, permission, userRole
  - `withValidation()` middleware for automatic tool input validation
  - Helper functions: `validateUUIDs()`, `validateEnum()`, `validateStringLength()`, `validateNumberRange()`
  - `toolSchemas` with pre-built schemas for common operations

- **Audit Logging (`src/utils/audit.ts`):** Automatic logging of write operations
  - `logAudit()`: Log single audit event to Outline's events table
  - `logAuditBatch()`: Batch logging for bulk operations
  - `withAuditLog()` middleware for automatic logging on tools
  - `AuditEvents` constants for all operation types
  - `createTeamAuditLogger()`: Team-scoped audit logger factory

- **Database Indexes (`migrations/001_indexes.sql`):** Performance optimization indexes
  - Full-text search GIN index for documents (10-100x faster searches)
  - Collection and membership lookup indexes (10x faster permission checks)
  - Event/audit log indexes (5-20x faster analytics)
  - User interaction indexes (stars, pins, views)
  - Composite indexes for common query patterns
  - See `migrations/README.md` for usage instructions

- **Pool Monitoring (`src/utils/monitoring.ts`):** Connection pool health monitoring
  - `PoolMonitor` class: Continuous monitoring with configurable alerts
  - `monitorPool()`: Quick setup function to start monitoring
  - `checkPoolHealth()`: One-time health check with issues list
  - `logPoolStats()`: Debug helper for current pool status
  - Configurable thresholds (warning at 80%, critical at 95%)
  - Automatic alerting for saturation and waiting connections
  - Statistics history with averages over time

- **Cursor-Based Pagination (`src/utils/pagination.ts`):** Efficient pagination for large datasets
  - `paginateWithCursor()`: High-level pagination helper
  - `buildCursorQuery()`: Build query parts for cursor pagination
  - `processCursorResults()`: Process results with cursor generation
  - `encodeCursor()` / `decodeCursor()`: Base64url cursor encoding
  - Compound cursors with secondary field for stable sorting
  - Bidirectional pagination (next/prev cursors)
  - Optional total count with extra query
  - Configurable limits (default 25, max 100)

### Changed

- Refactored security utilities with new validation functions
- Improved error messages for invalid input parameters
- Consolidated transaction helpers from individual tool files to centralized module
- Updated utils/index.ts to export all new modules

## [1.2.1] - 2026-01-31

### Added

- **Export/Import (2 tools):** export_collection_to_markdown, import_markdown_folder - Advanced Markdown export/import with hierarchy
- **Desk Sync (2 tools):** create_desk_project_doc, link_desk_task - Desk CRM integration for project documentation

### Changed

- Total tools increased from 160 to 164

## [1.2.0] - 2026-01-31

### Added

- **Teams (5 tools):** get, update, stats, domains, settings - Team/workspace management
- **Integrations (6 tools):** list, get, create, update, delete, sync - External integrations (Slack, embeds)
- **Notifications (4 tools):** list, mark read, mark all read, settings - User notification management
- **Subscriptions (4 tools):** list, subscribe, unsubscribe, settings - Document subscription management
- **Templates (5 tools):** list, get, create from, convert to/from - Document template management
- **Imports (4 tools):** list, status, create, cancel - Import job management
- **Emojis (3 tools):** list, create, delete - Custom emoji management
- **User Permissions (3 tools):** list, grant, revoke - Document/collection permission management
- **Bulk Operations (6 tools):** archive, delete, move, restore documents; add/remove users from collection
- **Advanced Search (6 tools):** advanced search, facets, recent, user activity, orphaned, duplicates
- **Analytics (6 tools):** overview, user activity, content insights, collection stats, growth metrics, search analytics

### Changed

- Total tools increased from 108 to 160
- Updated module exports and index files
- Improved database schema compatibility

## [1.1.0] - 2026-01-31

### Added

- **Stars (3 tools):** list, create, delete - Bookmark documents/collections for quick access
- **Pins (3 tools):** list, create, delete - Pin important documents to collection tops
- **Views (2 tools):** list, create - Track document views and view counts
- **Reactions (3 tools):** list, create, delete - Emoji reactions on comments
- **API Keys (4 tools):** list, create, update, delete - Manage programmatic access
- **Webhooks (4 tools):** list, create, update, delete - Event notification subscriptions
- **Backlinks (1 tool):** list - View document link references (read-only view)
- **Search Queries (2 tools):** list, stats - Search analytics and popular queries

### Changed

- Total tools increased from 86 to 108

## [1.0.1] - 2026-01-31

### Fixed

- **Users:** Adapted to Outline schema - use `role` enum instead of `isAdmin`/`isViewer`/`isSuspended` booleans
- **Users:** Removed non-existent `username` column
- **Groups:** Fixed `group_users` table queries - no `deletedAt` column, composite PK
- **Groups:** Fixed ambiguous column references in subqueries
- **Attachments:** Removed non-existent `url` and `deletedAt` columns
- **Attachments:** Changed delete to hard delete (no soft delete support)
- **Auth:** Use `suspendedAt IS NOT NULL` for suspended count, return `role` instead of `isAdmin`
- **Comments:** Use `role='admin'` for admin user queries
- **Documents:** Use `suspendedAt IS NULL` for active user checks
- **Events:** Return `actorRole` instead of `actorIsAdmin`
- **Shares:** Use `role='admin'` for admin user queries

### Changed

- Users suspend/activate now use `suspendedAt` column instead of boolean
- Groups member count uses correct join without deletedAt filter
- All modules validated against Outline v0.78 PostgreSQL schema

## [1.0.0] - 2026-01-31

### Added

- Initial release of MCP Outline PostgreSQL
- 86 tools across 12 modules for direct PostgreSQL access to Outline Wiki
- **Documents (19 tools):** CRUD, search, archive, move, templates, memberships
- **Collections (14 tools):** CRUD, user/group memberships, export
- **Users (9 tools):** CRUD, suspend, activate, promote, demote
- **Groups (8 tools):** CRUD, memberships management
- **Comments (6 tools):** CRUD, resolve functionality
- **Shares (5 tools):** CRUD, revoke public links
- **Revisions (3 tools):** list, info, compare versions
- **Events (3 tools):** audit log, statistics
- **Attachments (5 tools):** CRUD, storage statistics
- **File Operations (4 tools):** import/export job management
- **OAuth (8 tools):** OAuth clients and authentications
- **Auth (2 tools):** authentication info and config
- PostgreSQL client with connection pooling
- Rate limiting and security utilities
- Full TypeScript implementation with type safety
- MCP SDK v1.0.0 compatibility

### Technical

- Direct SQL access (not Outline API) for better performance
- Parameterized queries for SQL injection protection
- Soft delete support across all entities
- Full-text search using PostgreSQL tsvector
- Pagination and sorting on all list operations

---

*Developed by Descomplicar® | descomplicar.pt*