docs: update plugin system design with security enhancements

Added local network access control flag, plugin verification system, and capabilities declaration to the HLD. Updated implementation plan to remove UserPreference functionality from PoC scope while maintaining security features like local network control and hash verification. Added future extensions section outlining potential plugin types beyond metadata agents.

docs/plugins-implementation-plan.md

@@ -0,0 +1,305 @@
+# Navidrome Plugin System Implementation Plan
+
+## Progress Tracking
+
+### Phase 1: Foundational Infrastructure
+
+- [ ] 1.1: Plugin Manifest and Configuration
+- [ ] 1.2: Basic WebAssembly Runtime Integration
+- [ ] 1.3: Permission Management System
+  - [ ] 1.3.1: URL Allowlist Implementation
+  - [ ] 1.3.2: Local Network Access Control
+  - [ ] 1.3.3: Host Function Access Control
+- [ ] 1.4: Project Structure and CLI Commands
+- [ ] 1.5: Plugin Verification System
+
+### Phase 2: Protocol Definition and Host Functions
+
+- [ ] 2.1: Protocol Buffer Definitions
+- [ ] 2.2: Host Function Implementation
+- [ ] 2.3: Plugin Context Management
+
+### Phase 3: Plugin Loading and Execution
+
+- [ ] 3.1: WebAssembly Runtime Configuration
+- [ ] 3.2: Testing Infrastructure
+- [ ] 3.3: Plugin Developer Tools
+
+### Phase 4: Agent Plugin Integration
+
+- [ ] 4.1: Agent Plugin Adapter Implementation
+- [ ] 4.2: Plugin Registration with Agent System
+- [ ] 4.3: Last.fm Agent Plugin Implementation
+- [ ] 4.4: Integration Testing
+
+### Phase 5: Enhanced Management and User Experience
+
+- [ ] 5.1: Enhanced CLI Management
+- [ ] 5.2: Plugin Package Format
+- [ ] 5.3: Runtime Monitoring
+- [ ] 5.4: Administrative UI (Optional)
+
+### Phase 6: Documentation and Release
+
+- [ ] 6.1: User Documentation
+- [ ] 6.2: Developer Documentation
+- [ ] 6.3: Example Plugin Templates
+- [ ] 6.4: Final Testing and Feature Flags
+
+## Phase 1: Foundational Infrastructure
+
+**Goal:** Establish the core plugin infrastructure without affecting existing functionality.
+
+### 1.1: Plugin Manifest and Configuration
+
+- Create plugin manifest schema and validation functions
+- Add plugin-related configuration to `conf` package:
+  - Global plugin settings: enabled, directory, default limits
+  - Per-plugin settings: enabled, limits, configuration
+- Add tests for manifest validation and configuration parsing
+
+### 1.2: Basic WebAssembly Runtime Integration
+
+- Add `knqyf263/go-plugin` dependency
+- Create initial plugin loader that can:
+  - Discover plugin files in configured directory
+  - Read and validate manifests
+  - Basic security validation (no plugin execution yet)
+- Add unit tests for plugin discovery and manifest loading
+
+### 1.3: Permission Management System
+
+- Implement the `PermissionManager` component:
+  - URL allowlist validation
+  - Host function allowlist validation
+  - Internal network access prevention
+  - Configuration access control
+- Add comprehensive security tests for all permission rules
+- Implement local network access control feature:
+  - Add `allowLocalNetwork` flag to manifest schema
+  - Update permission checks in HTTP requests
+  - Add configuration option for default behavior
+- Add tests for local network access control
+
+### 1.4: Project Structure and CLI Commands
+
+- Create plugin-related directory structure:
+  ```
+  plugins/
+  ├── proto/       # Protocol Buffer definitions
+  ├── manager.go   # Plugin Manager implementation
+  ├── host.go      # Host function implementations
+  ├── permission.go # Permission manager
+  └── adapters/    # Adapters for different plugin types
+  ```
+- Implement basic CLI commands for plugin management:
+  - `navidrome plugin list`
+  - `navidrome plugin info [name]`
+
+### 1.5: Plugin Verification System
+
+- Implement plugin binary integrity verification:
+  - Add hash calculation and storage during installation
+  - Add verification during plugin loading
+  - Create a local store for plugin hashes
+- Add tests for plugin verification workflow
+- Update CLI commands to display verification status
+
+**Deliverable:** Foundation layer with security features including local network control and plugin verification.
+
+## Phase 2: Protocol Definition and Host Functions
+
+**Goal:** Define the communication protocol between Navidrome and plugins.
+
+### 2.1: Protocol Buffer Definitions
+
+- Define Protocol Buffer specifications for:
+  - Agent plugin interface
+  - Host functions interface
+  - Common request/response structures
+- Generate Go code from Protocol Buffers
+- Create test stubs for interface implementations
+
+### 2.2: Host Function Implementation
+
+- Implement core host functions:
+  - `GetConfig` for configuration access
+  - `Log` for plugin logging
+  - `HttpDo` for controlled HTTP access
+- Add comprehensive tests for each host function
+- Implement permission checks for all host functions
+
+### 2.3: Plugin Context Management
+
+- Create plugin context structure to track:
+  - Current plugin name
+  - Permission scope
+  - Runtime state
+- Implement proper isolation between plugin calls
+
+**Deliverable:** Complete protocol definition and host function implementations without executing actual plugins.
+
+## Phase 3: Plugin Loading and Execution (Minimal)
+
+**Goal:** Enable basic plugin loading and execution in isolation from the rest of the system.
+
+### 3.1: WebAssembly Runtime Configuration
+
+- Configure WebAssembly runtime with appropriate security settings
+- Implement plugin initialization with configuration passing
+- Add proper error handling for plugin loading failures
+
+### 3.2: Testing Infrastructure
+
+- Create test harness for plugin execution
+- Implement simple test plugins for validation
+- Add integration tests for plugin loading and execution
+- Add tests for local network access
+- Add tests for plugin verification and integrity checks
+
+### 3.3: Plugin Developer Tools
+
+- Implement development commands:
+  - `navidrome plugin dev [folder_path]`
+  - `navidrome plugin refresh [name]`
+- Create basic development documentation
+
+**Deliverable:** Working plugin loading and execution system that can be tested in isolation.
+
+## Phase 4: Agent Plugin Integration
+
+**Goal:** Connect the plugin system to the existing agent architecture.
+
+### 4.1: Agent Plugin Adapter Implementation
+
+- Create adapter that implements all agent interfaces:
+  - Convert between Protobuf and agent interfaces
+  - Implement proper error handling and timeouts
+  - Add trace logging for debugging
+- Add unit tests for all adapter methods
+- Update adapter to respect plugin's declared capabilities
+
+### 4.2: Plugin Registration with Agent System
+
+- Implement plugin registration with the existing agent system
+- Extend configuration to support plugin agent ordering
+- Make plugin agents respect the same priority system as built-in agents
+
+### 4.3: Last.fm Agent Plugin Implementation
+
+- Implement prototype Last.fm plugin as proof of concept
+- Create plugin manifest with necessary permissions
+- Add tests comparing plugin behavior to built-in agent
+
+### 4.4: Integration Testing
+
+- Add comprehensive integration tests for:
+  - Plugin discovery and loading
+  - Agent API functionality
+  - Error handling and recovery
+  - Configuration changes
+
+**Deliverable:** Working plugin system with Last.fm plugin implementation that can be toggled via configuration without breaking existing functionality.
+
+## Phase 5: Enhanced Management and User Experience
+
+**Goal:** Improve plugin management and user experience.
+
+### 5.1: Enhanced CLI Management
+
+- Complete remaining CLI commands:
+  - `navidrome plugin install [file]`
+  - `navidrome plugin remove [name]`
+  - `navidrome plugin config-template [name]`
+- Add command validation and error handling
+
+### 5.2: Plugin Package Format
+
+- Implement `.ndp` package format:
+  - Package creation
+  - Validation
+  - Installation
+- Add tests for package integrity checking
+
+### 5.3: Runtime Monitoring
+
+- Add runtime statistics:
+  - Plugin execution time
+  - Resource usage
+  - Error tracking
+- Implement health checks and recovery mechanisms
+
+### 5.4: Administrative UI (Optional)
+
+- Create basic admin UI for plugin management:
+  - View installed plugins
+  - Enable/disable plugins
+  - View permissions
+  - Configure plugins
+
+**Deliverable:** Complete plugin management tooling with good user experience.
+
+## Phase 6: Documentation and Release
+
+**Goal:** Prepare the plugin system for production use and developer adoption.
+
+### 6.1: User Documentation
+
+- Create comprehensive user documentation:
+  - Plugin installation and management
+  - Configuration options
+  - Security considerations
+  - Troubleshooting
+
+### 6.2: Developer Documentation
+
+- Create plugin development guide:
+  - API reference
+  - Development workflow
+  - Best practices
+  - Examples
+
+### 6.3: Example Plugin Templates
+
+- Create starter templates for common plugin types:
+  - Basic agent plugin
+  - Custom service plugin
+- Include CI/CD configurations
+- Add examples for different permission scenarios:
+  - Standard external API access
+  - Local network access (with `allowLocalNetwork: true`)
+  - Different capability declarations
+
+### 6.4: Final Testing and Feature Flags
+
+- Add feature flag to enable/disable plugin system
+- Perform comprehensive integration testing
+- Address any final security concerns
+
+**Deliverable:** Production-ready plugin system with documentation and examples.
+
+## Risk Assessment and Mitigation
+
+1. **Security Risks**
+
+   - **Risk**: Plugin execution could compromise system security
+   - **Mitigation**: Strict permission model, WebAssembly sandbox, URL validation
+
+2. **Performance Impact**
+
+   - **Risk**: WebAssembly execution might be slower than native code
+   - **Mitigation**: Benchmarking, caching mechanisms, performance monitoring
+
+3. **Backward Compatibility**
+
+   - **Risk**: Changes might break existing functionality
+   - **Mitigation**: Feature flags, phased integration, comprehensive testing
+
+4. **User Experience**
+
+   - **Risk**: Plugin management could be complex for users
+   - **Mitigation**: Clear documentation, intuitive CLI, potential UI integration
+
+5. **Developer Adoption**
+   - **Risk**: Plugin development might be too complex
+   - **Mitigation**: Clear documentation, example templates, developer tooling