release(v3.6.0): Gateway Shares v2 + Automation APIs, MCP core seam, and runtime hardening

- pro(api): add managed gateway + MCP service/user/job endpoints and Automation wrappers via Domain services
- mcp(core): add McpOpsContext + McpCoreOpsService seam with ACL-scoped operations and fast-list paging/cache path
- api(refactor): centralize Pro endpoint guards/emit helpers and move gateway/automation orchestration into src/FileRise/Domain
- runtime/security: add gnupg to Docker runtime image for managed rclone signature verification support
- style/docs: targeted PSR-12 cleanup in new core seam files and docs refresh for Gateway Shares + Automation

Author: error311

CHANGELOG.md

@@ -1,28 +1,75 @@
 # Changelog
 
-## Changes 02/26/2026 (v3.5.2)
+## Changes 03/02/2026 (v3.6.0)
 
-`release(v3.5.2): relax username validation + stdClass namespace fix`
+`release(v3.6.0): Gateway Shares v2 + Automation APIs, MCP core seam, and runtime hardening`
 
-**Commit message**  
+**Commit message**
 
 ```text
-release(v3.5.2): relax username validation + stdClass namespace fix
+release(v3.6.0): Gateway Shares v2 + Automation APIs, MCP core seam, and runtime hardening
 
-- users(core): allow dots/@ in usernames and block "." / ".." to prevent path-like edge cases
-- php(core): namespace stdClass return to \stdClass for consistency under FileRise\Domain
-- admin: update sponsor list (add Stefan)
+- pro(api): add managed gateway + MCP service/user/job endpoints and Automation wrappers via Domain services
+- mcp(core): add McpOpsContext + McpCoreOpsService seam with ACL-scoped operations and fast-list paging/cache path
+- api(refactor): centralize Pro endpoint guards/emit helpers and move gateway/automation orchestration into src/FileRise/Domain
+- runtime/security: add gnupg to Docker runtime image for managed rclone signature verification support
+- style/docs: targeted PSR-12 cleanup in new core seam files and docs refresh for Gateway Shares + Automation
 ```
 
-**Changed**  
-
-- **Username validation**
-  - Updated `REGEX_USER` to allow `.` and `@` in usernames (and spaces/underscores/dashes as before).
-  - Added a negative lookahead to reject `.` and `..` as standalone usernames.
-- **PHP namespace correctness**
-  - `UserModel::getUserPermissions()` now returns `\stdClass` (global) instead of `stdClass` to avoid namespace resolution issues under `FileRise\Domain`.
-- **Admin sponsor page**
-  - Added “Stefan” to the sponsors list in `public/js/adminSponsor.js`.
+**Added**
+
+- **Gateway Shares v2 + MCP API surface (Core integration for Pro)**
+  - Added managed runtime endpoints:
+    - `/api/pro/gateways/managed/status.php`
+    - `/api/pro/gateways/managed/action.php`
+    - `/api/pro/gateways/managed/rcloneInstall.php`
+    - `/api/pro/gateways/managed/rcloneCheck.php`
+    - `/api/pro/gateways/managed/rcloneUpload.php`
+  - Added MCP service/user/job endpoints:
+    - `/api/pro/gateways/mcp/service/{status,action}.php`
+    - `/api/pro/gateways/mcp/users/{list,save,delete}.php`
+    - `/api/pro/gateways/jobs/{cleanup,autotag}.php`
+- **Automation API surface (Core integration for Pro)**
+  - Added endpoint wrappers under:
+    - `/api/pro/automation/webhooks/*`
+    - `/api/pro/automation/jobs/*`
+    - `/api/pro/automation/worker/*`
+    - `/api/pro/automation/scans/*`
+    - `/api/pro/automation/security/*`
+    - `/api/pro/automation/metrics.php`
+- **Core service seam for Pro orchestration**
+  - Added:
+    - `src/FileRise/Domain/ProGatewayApiService.php`
+    - `src/FileRise/Domain/ProAutomationApiService.php`
+    - `src/FileRise/Domain/McpOpsContext.php`
+    - `src/FileRise/Domain/McpCoreOpsService.php`
+  - Added shared helpers:
+    - `public/api/pro/_common.php`
+    - `public/api/pro/gateways/_common.php`
+    - `public/api/pro/automation/_common.php`
+
+**Changed**
+
+- **Gateway admin UX**
+  - Gateway Shares now includes Shares/MCP tabs with managed status/actions, logs, rclone install/update/upload controls, and job queue actions.
+  - MCP tab now includes `AI Integration Templates` with copy/download snippets for OpenAI, Claude, Gemini, and direct curl testing.
+- **Runtime image prerequisites**
+  - Added `gnupg` to `Dockerfile` package install list to support managed rclone signature verification in container deployments.
+- **Version hint alignment**
+  - Updated admin latest Pro bundle UI hint to `v1.9.0`.
+
+**Fixed**
+
+- **Core bootstrap/order and API guard regressions**
+  - Fixed Pro API bootstrap ordering edge cases around `PROJECT_ROOT`/shared guard bootstrap usage.
+- **Gateway admin runtime regressions**
+  - Fixed managed gateway admin UI helper scope issues (`setManagedStatus`/`setManagedLog`).
+- **Style/lint**
+  - Applied targeted PSR-12 declaration/brace/EOF fixes in newly added Core seam files.
+
+**Docs**
+
+- Updated admin/wiki docs for Gateway Shares v2 + Automation coverage.
 
 ---
 

Dockerfile

@@ -53,7 +53,7 @@ RUN if [ -f /etc/apt/sources.list.d/ubuntu.sources ]; then \
     apt-get install -y --no-install-recommends \
       apache2 \
       php php-json php-curl php-zip php-mbstring php-gd php-xml \
-      ca-certificates curl openssl \
+      ca-certificates curl openssl gnupg \
       ${extra_pkgs} \
     && apt-get clean && rm -rf /var/lib/apt/lists/*
 

README.md

@@ -66,21 +66,25 @@ Built for homelabs, teams, and client portals that need fast browsing, strict AC
   - If the proxy strips the prefix, set `FR_BASE_PATH` or send `X-Forwarded-Prefix`
   - Explicit “Published URL” setting for proxy / firewall environments
   - Works with `X-Forwarded-*` headers and Kubernetes ingress setups
-- 👥 **Pro: user groups, client portals, global search, storage explorer & audit logs** –  
+- 👥 **Pro: user groups, client portals, global search, storage explorer & audit logs** –
   Group-based ACLs, brandable client upload portals, **ACL-aware global search across files, folders, users, and permissions**, an ncdu-style storage explorer for identifying large folders/files and reclaiming disk space directly from the UI, and **Pro Audit Logs** (configurable activity logging with filters + CSV export for tracking key actions across web, WebDAV, shares, and portals).
-- 🌐 **Sources (Core + Pro adapters)** –  
+- ⚙️ **Pro: Automation (Webhooks + Jobs)** –
+  Send FileRise events to other apps/services using managed webhook endpoints with async delivery, retries, queue visibility, and job history from Admin.
+- 🌐 **Sources (Core + Pro adapters)** –
   Turn FileRise into a storage hub by connecting multiple backends and switching between them in the UI:
   - **Core:** Multiple local roots (additional local paths)
   - **Core:** **WebDAV** sources (Nextcloud / ownCloud / FileRise)
   - **Pro:** **S3-compatible** (AWS S3 / MinIO / Wasabi / Backblaze B2 S3 / etc.)
   - **Pro:** **SMB/CIFS**, **SFTP**, **FTP**
   - **Pro:** **Google Drive**, **OneDrive**, **Dropbox**
   - Works with **dual-pane** so you can copy/move via drag & drop or toolbar actions **between sources**, with **per-source Trash**
-- 🔌 **Pro: Gateway Shares (SFTP / S3 / MCP)** –  
+- 🔌 **Pro: Gateway Shares v2 (SFTP / S3 / MCP)** –
   Expose selected source roots through managed gateways for external clients and workflows:
+  - Managed **start/stop/restart/status/log** controls from Admin
   - **SFTP gateway** for tools like FileZilla, WinSCP, and rclone
   - **S3 gateway** for S3-compatible clients and automation
-  - **MCP gateway** for emerging AI/tool integrations
+  - **Scoped MCP users/tokens** mapped to FileRise user + source/root scope
+  - AI/tool integrations stay **ACL-scoped and auditable**
 
 Full list of features: [Full Feature Wiki](https://github.com/error311/FileRise/wiki/Features)
 
@@ -107,6 +111,7 @@ Full list of features: [Full Feature Wiki](https://github.com/error311/FileRise/
   - [Common env vars](https://github.com/error311/FileRise/wiki/Common-Env-Variables)
   - [Env vars (full reference)](https://github.com/error311/FileRise/wiki/Environment-Variables-Full-Reference)
   - [Admin Panel](https://github.com/error311/FileRise/wiki/Admin-Panel)
+  - [Pro MCP AI quickstart](https://github.com/error311/FileRise/wiki/Pro-MCP-AI-Quickstart)
   - [ACL & permissions](https://github.com/error311/FileRise/wiki/ACL-and-Permissions)
   - [ACL recipes](https://github.com/error311/FileRise/wiki/ACL-Recipes)
   - [WebDAV (mount)](https://github.com/error311/FileRise/wiki/WebDAV)

config/config.php

@@ -199,6 +199,9 @@ function decryptData($encryptedData, $encryptionKey)
 } else {
     $encryptionKey = $envKey;
 }
+// Ensure encryption key is always available via $GLOBALS, even when this file
+// is required from function scope (e.g. API helper bootstrap wrappers).
+$GLOBALS['encryptionKey'] = $encryptionKey;
 
 // Optional: ignore regex for indexing/listing (env wins; admin config as fallback)
 if (!defined('FR_IGNORE_REGEX')) {
@@ -528,7 +531,9 @@ function fr_read_admin_config_raw(): array
         if (!is_file($configFile)) return [];
         $encryptedContent = @file_get_contents($configFile);
         if (!is_string($encryptedContent) || $encryptedContent === '') return [];
-        $dec = decryptData($encryptedContent, $GLOBALS['encryptionKey']);
+        $key = isset($GLOBALS['encryptionKey']) ? (string)$GLOBALS['encryptionKey'] : '';
+        if ($key === '') return [];
+        $dec = decryptData($encryptedContent, $key);
         if ($dec === false) return [];
         $cfg = json_decode($dec, true);
         return is_array($cfg) ? $cfg : [];
@@ -593,6 +598,55 @@ function fr_read_admin_config_raw(): array
     define('FR_PRO_BUNDLE_DIR', $proDir);
 }
 
+// Optional core event-bus seam for guarded Pro registration.
+if (!function_exists('fr_eventbus_register')) {
+    function fr_eventbus_register(callable $listener): void
+    {
+        if (!class_exists(\FileRise\Support\EventBus::class)) {
+            return;
+        }
+        \FileRise\Support\EventBus::register($listener);
+    }
+}
+
+// Guarded Core MCP ops seam for Pro runtimes.
+if (!function_exists('fr_mcp_core_ops_dispatch')) {
+    function fr_mcp_core_ops_dispatch(string $operation, array $payload = [], array $authContext = []): array
+    {
+        if (!class_exists(\FileRise\Domain\McpCoreOpsService::class)) {
+            return [
+                'ok' => false,
+                'error' => 'Core MCP ops service unavailable.',
+                'status' => 500,
+            ];
+        }
+        return \FileRise\Domain\McpCoreOpsService::dispatch($operation, $payload, $authContext);
+    }
+}
+
+// ------------------------------------------------------------
+// Early Pro/Core API-level guards for bootstrap-time calls
+// ------------------------------------------------------------
+if (!defined('FR_PRO_API_REQUIRE_DISK_USAGE')) {
+    define('FR_PRO_API_REQUIRE_DISK_USAGE', 2);
+}
+if (!defined('FR_PRO_API_REQUIRE_SEARCH')) {
+    define('FR_PRO_API_REQUIRE_SEARCH', 3);
+}
+if (!defined('FR_PRO_API_REQUIRE_AUDIT')) {
+    define('FR_PRO_API_REQUIRE_AUDIT', 4);
+}
+if (!defined('FR_PRO_API_REQUIRE_SOURCES')) {
+    define('FR_PRO_API_REQUIRE_SOURCES', 5);
+}
+if (!function_exists('fr_pro_api_level_at_least')) {
+    function fr_pro_api_level_at_least(int $required): bool
+    {
+        $current = defined('FR_PRO_API_LEVEL') ? (int)FR_PRO_API_LEVEL : 0;
+        return $current >= $required;
+    }
+}
+
 // Try to load Pro bootstrap if enabled + present
 $proBootstrap = FR_PRO_BUNDLE_DIR . '/bootstrap_pro.php';
 if (@is_file($proBootstrap)) {

docs/wiki/Admin-Panel.md

@@ -76,10 +76,23 @@ The Admin Panel is where you manage users, folder access, authentication, integr
 - Enable Sources, add/edit/test connections, set source read-only, and optionally bypass trash (permanent delete).
 - See [Pro Sources](https://github.com/error311/FileRise/wiki/Pro-Sources) for details.
 
-### Pro Features
+### Gateway Shares
 
-- **Search Everywhere**: enable/disable and default limit (env-locked when set).
-- **Audit logs**: enable, level, and size caps.
+- Build and manage SFTP/S3/MCP gateway records.
+- Managed runtime controls are available in-panel (start/stop/restart, logs, autostart, rclone install/update checks).
+- Includes MCP service/user/job tooling and AI starter template generation in the MCP tab.
+- See [Pro gateway shares](https://github.com/error311/FileRise/wiki/Pro-Gateway-Shares) for full setup and runtime details.
+
+### Automation
+
+- **Webhooks tab**: endpoint CRUD, event filters, test sends, recent delivery history, and webhook security controls (global enable, allowlist, hard public-target mode).
+- **Jobs tab**: queue ClamAV scans, start worker, set recurring scan interval override, filter/inspect/retry/cancel jobs, and cleanup history/worker heartbeats.
+- See [Pro automation](https://github.com/error311/FileRise/wiki/Pro-Automation) for flow details and operator guidance.
+
+### Search Everywhere & Audit Logging
+
+- **Search Everywhere**: enable/disable and default result limit (env-locked when set).
+- **Audit logging**: enable/disable, level, and rotation caps; includes activity history view + CSV export.
 
 ### FileRise Pro
 

docs/wiki/Pro-Automation.md

@@ -0,0 +1,51 @@
+# Pro Automation
+
+Automation in FileRise Pro provides two connected capabilities:
+
+- **Webhooks** for outbound event delivery.
+- **Async jobs** for background processing and retries.
+
+You manage both from **Admin Panel -> Automation**.
+
+## Webhooks tab
+
+The Webhooks tab lets you:
+
+- Create and edit webhook endpoints (name, URL, secret, timeout, retry attempts, enabled flag).
+- Choose event filters (for example `file.uploaded`, `file.deleted`, `share.created`, `job.failed`).
+- Queue a test delivery for an endpoint.
+- Review recent deliveries (status code, duration, error snippet).
+
+Security controls are also in this tab:
+
+- Global webhook enable/disable.
+- Host allowlist enforcement (exact host and `*.example.com` wildcard support).
+- Force-public-target mode to block private/local targets globally.
+
+## Jobs tab
+
+The Jobs tab lets you:
+
+- Queue a ClamAV scan job by source/folder.
+- Start the automation worker.
+- Set or unset recurring scan interval override.
+- Filter jobs by status (`queued`, `running`, `succeeded`, `dead`, `canceled`).
+- View job details and retry/cancel jobs.
+- Cleanup old finished jobs, logs, delivery records, and stale worker heartbeat entries.
+
+## How it works
+
+- Webhook events are queued as jobs and delivered asynchronously.
+- Failed deliveries are retried based on endpoint max-attempt settings.
+- Worker heartbeat and queue metrics are surfaced in the Admin panel so you can monitor backlog and health.
+
+## Operational notes
+
+- Keep webhook allowlist enabled unless you explicitly need broad outbound targets.
+- Use endpoint secrets so receivers can verify signatures.
+- For large environments, monitor queued/running counts and cleanup history regularly.
+
+## Related
+
+- /docs/?page=admin-panel
+- /docs/?page=pro-gateway-shares