Release 3.4.0: folder-aware notifications

CITATION.cff

@@ -7,8 +7,8 @@ authors:
     given-names: Michael
 url: "https://github.com/TheStreamCode/mikesoft-teamvault"
 repository-code: "https://github.com/TheStreamCode/mikesoft-teamvault"
-version: "3.3.0"
-date-released: "2026-10-11"
+version: "3.4.0"
+date-released: "2026-10-21"
 keywords:
   - WordPress
   - document management

README.de.md

@@ -11,7 +11,7 @@
 
 Privater Dokumenten-Arbeitsbereich für WordPress-Teams, Agenturen und Betriebsabläufe, die eine kontrollierte Dateifreigabe außerhalb der Mediathek benötigen.
 
-Aktuelle Plugin-Version: `3.3.0`.
+Aktuelle Plugin-Version: `3.4.0`.
 
 Direkt über WordPress.org verfügbar und für aktuelle WordPress-Versionen gepflegt.
 
@@ -61,6 +61,8 @@ Governance-Funktionen (alle kostenlos, seit 2.6):
 
 ## Neueste Version
 
+Version `3.4.0` macht E-Mail-Benachrichtigungen ordnerbewusst: Ausgewählte Benutzer und Gruppen erhalten ein Ereignis nur, wenn sie den Ordner, in dem es entstanden ist, anzeigen dürfen; Administratoren bleiben eingeschlossen, wenn sie aktiviert sind. Eine neue Einstellung unter Benachrichtigungen stellt das bisherige globale Verhalten wieder her, und der Filter `mstv_notification_recipients` ermöglicht seitenspezifische Weiterleitungen. Weitere Konfigurationsänderungen sind nicht erforderlich.
+
 Version `3.3.0` beschränkt die Verwaltung von Zugriffsregeln auf Administratoren oder Benutzer mit einer expliziten Verwaltungsregel, behebt ZIP-Exporte auf Servern, auf denen der temporäre Archivpfad nicht erstellt werden konnte, zeigt bei fehlgeschlagenen Aktionen die spezifischen Servermeldungen an und ergänzt Ordner in den Suchergebnissen. Konfigurationsänderungen sind nicht erforderlich.
 
 Version `3.2.5` schließt die in 3.2.4 begonnene Ausgabekodierung ab: Das Detailfenster maskiert die gespeicherte Dateiendung nun vor der Darstellung. Der Wert ist durch die Upload- und Reindex-Validierung bereits auf `[a-z0-9]` beschränkt; es handelt sich also um Verteidigung in der Tiefe und nicht um die Behebung einer ausnutzbaren Schwachstelle. Konfigurationsänderungen sind nicht erforderlich.

README.es.md

@@ -11,7 +11,7 @@
 
 Espacio de trabajo de documentos privados para equipos, agencias y operaciones de WordPress que necesitan compartir archivos de forma controlada fuera de la Biblioteca de medios.
 
-Versión actual del plugin: `3.3.0`.
+Versión actual del plugin: `3.4.0`.
 
 Disponible directamente en WordPress.org y mantenido para las versiones actuales de WordPress.
 
@@ -61,6 +61,8 @@ Capacidades de gobernanza (todas gratuitas, desde la versión 2.6):
 
 ## Última versión
 
+La versión `3.4.0` hace que las notificaciones por correo tengan en cuenta la carpeta: los usuarios y grupos seleccionados solo reciben un evento si pueden ver la carpeta que lo originó, mientras que los administradores siguen incluidos cuando están activados. Un nuevo ajuste en Notificaciones restaura el comportamiento global anterior y el filtro `mstv_notification_recipients` permite enrutamientos específicos por sitio. No se requieren otros cambios de configuración.
+
 La versión `3.3.0` reserva la gestión de las reglas de permisos a los administradores o a los usuarios con una regla de gestión explícita, corrige las exportaciones ZIP en servidores donde no se podía crear la ruta temporal del archivo, muestra los mensajes específicos del servidor en las acciones fallidas y añade las carpetas a los resultados de búsqueda. No se requieren cambios de configuración.
 
 La versión `3.2.5` completa el trabajo de codificación de salida iniciado en la 3.2.4: el panel de detalles del archivo ahora escapa la extensión almacenada antes de mostrarla. El valor ya está limitado a `[a-z0-9]` por la validación de subida y reindexación, por lo que se trata de defensa en profundidad y no de la corrección de una vulnerabilidad explotable. No se requieren cambios de configuración.

README.fr.md

@@ -11,7 +11,7 @@
 
 Espace de travail documentaire privé pour les équipes, agences et services d'exploitation WordPress qui ont besoin d'un partage de fichiers contrôlé en dehors de la Médiathèque.
 
-Version actuelle du plugin : `3.3.0`.
+Version actuelle du plugin : `3.4.0`.
 
 Disponible directement sur WordPress.org et maintenu pour les versions actuelles de WordPress.
 
@@ -61,6 +61,8 @@ Fonctionnalités de gouvernance (toutes gratuites, depuis la 2.6) :
 
 ## Dernière version
 
+La version `3.4.0` rend les notifications par e-mail conscientes du dossier : les utilisateurs et groupes sélectionnés ne reçoivent un événement que s'ils peuvent consulter le dossier qui l'a produit, tandis que les administrateurs restent inclus lorsqu'ils sont activés. Un nouveau réglage dans Notifications rétablit le comportement global précédent et le filtre `mstv_notification_recipients` permet un routage propre à chaque site. Aucune autre modification de configuration n'est nécessaire.
+
 La version `3.3.0` réserve la gestion des règles d'autorisation aux administrateurs ou aux utilisateurs disposant d'une règle de gestion explicite, corrige les exports ZIP sur les serveurs où le chemin temporaire de l'archive ne pouvait pas être créé, affiche les messages spécifiques du serveur en cas d'échec des actions et ajoute les dossiers aux résultats de recherche. Aucune modification de configuration n'est nécessaire.
 
 La version `3.2.5` achève le travail d'encodage des sorties entamé en 3.2.4 : le panneau de détails du fichier échappe désormais l'extension enregistrée avant de l'afficher. Cette valeur est déjà limitée à `[a-z0-9]` par la validation de téléversement et de réindexation ; il s'agit donc d'une défense en profondeur et non de la correction d'une faille exploitable. Aucune modification de configuration n'est nécessaire.

README.it.md

@@ -11,7 +11,7 @@
 
 Spazio di lavoro documentale privato per team, agenzie e reparti operativi WordPress che hanno bisogno di condividere file in modo controllato al di fuori della Libreria Media.
 
-Versione attuale del plugin: `3.3.0`.
+Versione attuale del plugin: `3.4.0`.
 
 Disponibile direttamente su WordPress.org e mantenuto per le versioni correnti di WordPress.
 
@@ -61,6 +61,8 @@ Funzionalità di governance (tutte gratuite, dalla versione 2.6):
 
 ## Ultima versione
 
+La versione `3.4.0` rende le notifiche email consapevoli della cartella: utenti e gruppi selezionati ricevono un evento solo se possono visualizzare la cartella che lo ha generato, mentre gli amministratori restano inclusi se abilitati. Una nuova impostazione in Notifiche ripristina il precedente comportamento globale e il filtro `mstv_notification_recipients` consente routing specifici per sito. Non sono richieste altre modifiche alla configurazione.
+
 La versione `3.3.0` riserva la gestione delle regole di permesso agli amministratori o agli utenti con una regola di gestione esplicita, corregge gli export ZIP sui server in cui il percorso temporaneo dell'archivio non poteva essere creato, mostra i messaggi specifici del server per le azioni non riuscite e aggiunge le cartelle ai risultati di ricerca. Non sono richieste modifiche alla configurazione.
 
 La versione `3.2.5` completa il lavoro di codifica dell'output iniziato con la 3.2.4: il pannello dei dettagli file applica ora l'escaping all'estensione memorizzata prima di visualizzarla. Il valore è già limitato a `[a-z0-9]` dalla validazione di upload e reindicizzazione, quindi si tratta di difesa in profondità e non della correzione di una vulnerabilità sfruttabile. Non sono richieste modifiche alla configurazione.

README.md

@@ -26,7 +26,7 @@
 > [!NOTE]
 > This is the public source mirror for TeamVault. Installations and updates are distributed through [WordPress.org](https://wordpress.org/plugins/mikesoft-teamvault/); user support is handled in the [official support forum](https://wordpress.org/support/plugin/mikesoft-teamvault/).
 
-Current plugin version: `3.3.0`.
+Current plugin version: `3.4.0`.
 
 ![TeamVault file manager — folder tree, file cards with type-aware icons and image thumbnails, and the details panel with inline preview](.wordpress-org/assets/screenshot-1.jpg)
 
@@ -57,15 +57,15 @@ Typical uses include internal company documents, agency-to-client delivery, part
 - validated drag-and-drop uploads and inline previews, including PDFs
 - preview-only access that blocks downloads and ZIP exports
 - per-user and per-group storage quotas enforced before upload
-- access reports, activity logging, CSV export, and event notifications
+- access reports, activity logging, CSV export, and folder-aware event notifications
 - ZIP export plus orphan cleanup and storage reindex maintenance tools
 - English, Italian, French, Spanish, and German admin interfaces
 
 All governance capabilities are included in the free plugin.
 
 ## Latest Release
 
-Version `3.3.0` restricts permission-rule management to administrators or users with an explicit manage rule, fixes ZIP exports on servers where the temporary archive path could not be created, surfaces specific server messages on failed actions, and adds folder results to search. No configuration changes are required.
+Version `3.4.0` makes email notifications folder-aware: selected users and groups receive an event only if they can view the folder that produced it, while administrators remain included when enabled. A new Notifications setting restores the previous global behavior, and the `mstv_notification_recipients` filter allows site-specific routing. No other configuration changes are required.
 
 See the [full changelog](changelog.txt) and [GitHub releases](https://github.com/TheStreamCode/mikesoft-teamvault/releases) for complete history.
 

assets/js/admin-app-governance.js

@@ -623,6 +623,7 @@
                 this._notif = res.success ? res.data : null;
                 if (this._notif) {
                     this._notif.recipients = this._notif.recipients || { admins: true, users: [], groups: [] };
+                    this._notif.folder_aware = this._notif.folder_aware !== false;
                     this.renderNotifications();
                 }
             } catch (e) {
@@ -664,6 +665,10 @@
                         <input type="checkbox" id="mstv-notif-admins" ${n.recipients.admins ? 'checked' : ''}>
                         <span class="pdm-checkbox-text">${i18n.notifAdmins}</span>
                     </label>
+                    <label class="pdm-checkbox-label">
+                        <input type="checkbox" id="mstv-notif-folder-aware" ${n.folder_aware ? 'checked' : ''}>
+                        <span class="pdm-checkbox-text">${i18n.notifFolderAware}</span>
+                    </label>
                     <div class="pdm-field">
                         <label class="pdm-field-label">${i18n.notifUsers}</label>
                         <div class="pdm-perm-add-user" style="max-width:360px">
@@ -692,6 +697,7 @@
 
             root.querySelector('#mstv-notif-enabled').addEventListener('change', e => { n.enabled = e.target.checked; });
             root.querySelector('#mstv-notif-admins').addEventListener('change', e => { n.recipients.admins = e.target.checked; });
+            root.querySelector('#mstv-notif-folder-aware').addEventListener('change', e => { n.folder_aware = e.target.checked; });
 
             root.querySelectorAll('.mstv-notif-event').forEach(cb => cb.addEventListener('change', () => {
                 n.events = Array.from(root.querySelectorAll('.mstv-notif-event:checked')).map(c => c.value);
@@ -736,6 +742,7 @@
             const n = this._notif;
             const payload = {
                 enabled: !!n.enabled,
+                folder_aware: n.folder_aware !== false,
                 events: n.events,
                 recipients: {
                     admins: !!n.recipients.admins,

changelog.txt

@@ -2,6 +2,12 @@ Mikesoft TeamVault Changelog
 
 Entries are ordered newest first. Release dates are included where recorded.
 
+## 3.4.0 - 2026-10-21
+- Feature: email notifications are folder-aware by default. Selected users and groups receive an upload, download, delete, or access-denied event only when they can view the folder that produced it, so a document name is not disclosed to a group without access. Administrators remain included when the administrator recipient option is enabled.
+- Feature: a Notifications setting restores the previous global recipient behavior; the `mstv_notification_recipients` filter lets site code refine the final recipient list.
+- Improvement: download notifications include folder context, and queued events are grouped by recipient set so files from folders with different access rules are never combined in one email.
+- Tests: expanded notification coverage for folder filtering, administrator bypass, direct recipients, download context, opt-out behavior, and cross-folder batching.
+
 ## 3.3.0 - 2026-10-11
 - Security: permission-rule management is now restricted to administrators or users whose manage grant comes from an explicit folder rule; the capability-based free fallback no longer delegates rule management, and the interface hides the rule editor accordingly.
 - Fix: ZIP exports build their temporary archive through a correctly separated temp directory path, restoring folder and library exports on servers where the previous malformed path could not be created.

docs/developer/hooks.md

@@ -78,6 +78,7 @@ Parameters:
 Payload keys currently include:
 
 - `display_name`
+- `folder_id`
 - `extension`
 - `mime_type`
 
@@ -276,10 +277,33 @@ add_filter('mstv_upload_validation', function (array $result, array $files): arr
 }, 10, 2);
 ```
 
+### `mstv_notification_recipients`
+
+Filters the email addresses that will receive a notification event after the
+configured administrators, users, and groups have been resolved and, when
+folder-aware delivery is enabled, filtered by folder access.
+
+Parameters:
+
+- `string[] $emails`
+- `string $event` (`upload`, `download`, `delete`, or `access_denied`)
+- `?int $folderId`
+
+```php
+add_filter('mstv_notification_recipients', function (array $emails, string $event, ?int $folderId): array {
+    if ($event === 'access_denied') {
+        return array_values(array_intersect($emails, ['security@example.test']));
+    }
+
+    return $emails;
+}, 10, 3);
+```
+
 ## Notes
 
 - These hooks are intended for WordPress customizations and must be used from site code, custom plugins, or mu-plugins.
 - Hook payloads reflect the current implementation and may expand in future releases.
+- Email notifications are folder-aware by default: selected users and groups receive an event only when they can view the folder that produced it, while administrators remain included if the administrator recipient option is enabled. Site owners can disable this behavior in TeamVault → Notifications, and `mstv_notification_recipients` can refine the final list.
 - Since 3.3.0, folder permission rules can only be read or changed through the
   governance REST endpoints by administrators or users whose `manage` grant
   comes from an explicit folder rule (`MSTV_Permissions::has_rule_based_manage()`).

docs/maintainer/security-review.md

@@ -1,8 +1,8 @@
-# Security Review — 2026-10-11
+# Security Review — 2026-10-21
 
 ## Scope and Method
 
-This review covers the 3.3.0 working tree: the permission resolver and governance REST surface, the export/temp-path handling, the validator messages, the admin JavaScript rendering layer, and the test infrastructure. It combines manual source review with the expanded PHPUnit suite (186 tests), behavioral node tests for the shared helpers, PHP lint on the full tree, live HTTP verification against a WordPress 7.1.3 staging site (upload, preview, download, REST, governance, exports, maintenance, uninstall), WordPress Plugin Check (zero errors), and scripted browser QA of the refactored interface.
+This review covers the 3.4.0 working tree: the folder-aware notification path, the permission resolver and governance REST surface, the export/temp-path handling, the validator messages, the admin JavaScript rendering layer, and the test infrastructure. It combines manual source review with the expanded PHPUnit suite, behavioral node tests for the shared helpers, PHP lint on the full tree, Composer validation and audit, JavaScript syntax checks, WordPress Plugin Check on an active local staging installation (no errors), and a WP-CLI functional notification test on that installation. It was not exercised through a browser session or a real mail transport in this cycle; those release checks remain required before publication.
 
 No critical issue remains open in this cycle. The findings below were fixed in the reviewed tree and carry regression coverage where practical. This document is a point-in-time engineering review, not a guarantee against every vulnerability or a substitute for production configuration testing.
 
@@ -41,8 +41,18 @@ No critical issue remains open in this cycle. The findings below were fixed in t
 - Evidence: localized strings interpolated into HTML attributes, governance enum fallbacks, and REST-derived identifiers reached sinks without mechanical escaping (all values server-controlled, so defense in depth rather than an exploitable path).
 - Resolution: attribute sinks route through the shared escaper; enum fallbacks are escaped; IDs are normalized with `parseInt`; the preview download binding is null-guarded. Shared pure helpers now carry behavioral node tests, and the packaging excludes repository-only metadata files (the only WordPress Plugin Check warning).
 
+### SEC-009 — Notifications: recipients could receive document names from folders they cannot view
+
+- Severity: Medium (information disclosure)
+- Status: Fixed in 3.4.0
+- Location: `includes/class-mstv-notifications.php`, `includes/class-mstv-bootstrap.php`, `includes/class-mstv-download.php`
+- Evidence: notification recipients were resolved once from the global administrator/user/group selection and reused for every event. A group selected for upload notifications received the document name even when the folder that produced the event was governed by rules that excluded that group. The existing `mstv_folder_notifications` option was not used for routing.
+- Resolution: each queued event now carries its `folder_id`; non-administrator recipients are filtered through `MSTV_Permissions::user_can($userId, $folderId, 'view')`, administrators bypass the filter when the administrator recipient option is enabled, and events are grouped by recipient set so one email cannot mix files from folders with different access rules. Download events now include the folder in their hook payload. The behavior is enabled by default and can be disabled with the Notifications setting; the `mstv_notification_recipients` filter is the documented extension point. Regression tests cover group filtering, administrator bypass, direct recipients, downloads, opt-out, and cross-folder batching.
+- Compatibility note: existing sites begin filtering after the update; the setting restores the previous global behavior. This behavior change is called out in the upgrade notice.
+
 ## Residual Risks
 
 - Storage protection still depends on server configuration: the generated `.htaccess`/`web.config` cover Apache/IIS, while Nginx requires an equivalent deny rule (surfaced to operators by the settings notice).
 - Header semantics for private streams remain guarded by source-level tests plus live HTTP verification; a CLI unit test cannot observe `header()` output.
 - The whitelist, quota, and notification surfaces rely on the capability floor plus, where applicable, database advisory locks; they were re-verified through the live governance battery but not fuzzed beyond their regression suites.
+- The notification filter resolves access per recipient and folder, which adds one cached permission lookup per event recipient; very large selected-recipient sets are bounded by the notification configuration and were not benchmarked at extreme scale.

includes/class-mstv-activator.php

@@ -281,6 +281,7 @@ private static function set_default_options(): void
             'mstv_notify_enabled' => false,
             'mstv_notify_events' => '',
             'mstv_notify_recipients' => ['admins' => true, 'users' => [], 'groups' => []],
+            'mstv_notify_folder_aware' => true,
             'mstv_folder_notifications' => [],
             self::VERSION_OPTION => MSTV_VERSION,
         ];