Release version 2.6.2

Code quality maintenance release applying all findings from the internal
code review:

- Extract MSTV_Binary_Stream trait to eliminate the stream_absolute_file()
  duplication between download and preview handlers
- Add server-side error_log() diagnostics for file-not-readable and
  stream-failure conditions in download and preview (server log only)
- Move storage notice dismiss script from inline <script> to a dedicated
  admin-notice-dismiss.js asset enqueued via wp_enqueue_script() and
  wp_localize_script(); improves CSP compatibility
- Cache orphaned-file count in a short-lived transient on the settings
  page to avoid O(n) filesystem stats on every page load; invalidated
  after cleanup
- Extract build_audit_csv_row() private method from handle_export_audit_csv()
- Add PHPDoc to security-critical filesystem methods (verify_path,
  get_verified_path, path_has_symlink) and bootstrap entry points
- Apply PHP 8.0 type hints (array, mixed) to MSTV_Settings properties
  and method signatures; replace last stripslashes() with wp_unslash()

Author: mikesoft-codex

README.md

@@ -9,7 +9,7 @@
 
 Private document workspace for WordPress teams, agencies, and operations that need controlled file sharing outside the Media Library.
 
-Current plugin version: `2.6.1`.
+Current plugin version: `2.6.2`.
 
 If TeamVault is useful to you, consider [sponsoring the project on GitHub](https://github.com/sponsors/TheStreamCode) — it is developed and maintained for free, and sponsorships help keep it going.
 

assets/js/admin-notice-dismiss.js

@@ -0,0 +1,15 @@
+/* global mstvNoticeData, ajaxurl */
+(function () {
+    document.addEventListener('DOMContentLoaded', function () {
+        document.querySelectorAll('.mstv-storage-security-notice').forEach(function (notice) {
+            notice.addEventListener('click', function (e) {
+                if (!e.target.classList.contains('notice-dismiss')) return;
+                fetch(ajaxurl, {
+                    method: 'POST',
+                    headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+                    body: 'action=mstv_dismiss_storage_notice&_ajax_nonce=' + encodeURIComponent(mstvNoticeData.dismissNonce),
+                });
+            });
+        });
+    });
+}());

changelog.txt

@@ -2,6 +2,15 @@ Mikesoft TeamVault Changelog
 
 Entries are ordered newest first. Release dates are included where recorded.
 
+## 2.6.2 - 2026-06-10
+- Code quality: extracted shared binary streaming logic into a reusable `MSTV_Binary_Stream` trait, eliminating duplicate `stream_absolute_file()` implementations across download and preview handlers.
+- Code quality: added server-side `error_log()` diagnostics for file-not-readable and stream-failure conditions in download and preview handlers; errors go to the server log only, not to the user.
+- Code quality: moved the storage security notice dismiss script from an inline `<script>` block to a dedicated `admin-notice-dismiss.js` asset loaded with `wp_enqueue_script()` and `wp_localize_script()`; improves compatibility with strict Content Security Policy headers.
+- Performance: cached the orphaned-file count in a short-lived transient so the settings page does not repeat a filesystem stat per database record on every load; the cache is invalidated immediately after running orphan cleanup.
+- Code quality: extracted the audit CSV row builder into a dedicated private method `build_audit_csv_row()` in the admin class.
+- Code quality: added PHPDoc to the security-critical filesystem methods (`verify_path`, `get_verified_path`, `path_has_symlink`) and the bootstrap entry points (`init`, `init_services`, `init_rest_api`).
+- Code quality: applied PHP 8.0 type hints (`array`, `mixed`) to the untyped `MSTV_Settings` properties and method signatures; replaced the last `stripslashes()` call with the canonical `wp_unslash()`.
+
 ## 2.6.1 - 2026-06-09
 - Admin UI: added a discreet Sponsor link to the plugin row on the Plugins screen and a "Support the project" line in the TeamVault settings Information box. Both stay inside plugin-owned surfaces, with no dashboard-wide notices. TeamVault remains free with all governance features included; sponsorships support continued development.
 - Code quality: annotated the governance repository queries (filtered activity log queries and the dynamic IN() placeholder list) for the WordPress Plugin Check static analysis. Comment-only changes with no runtime behavior differences.

includes/class-mstv-admin.php

@@ -66,24 +66,6 @@ public function render_storage_security_notice(): void
             'mikesoft-teamvault'
         );
         echo '</p></div>';
-        ?>
-        <script>
-        (function () {
-            document.addEventListener('DOMContentLoaded', function () {
-                document.querySelectorAll('.mstv-storage-security-notice').forEach(function (notice) {
-                    notice.addEventListener('click', function (e) {
-                        if (!e.target.classList.contains('notice-dismiss')) return;
-                        fetch(ajaxurl, {
-                            method: 'POST',
-                            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
-                            body: 'action=mstv_dismiss_storage_notice&_ajax_nonce=<?php echo esc_js(wp_create_nonce('mstv_dismiss_storage_notice')); ?>'
-                        });
-                    });
-                });
-            });
-        })();
-        </script>
-        <?php
     }
 
     public function handle_dismiss_storage_notice(): void
@@ -379,6 +361,8 @@ public function handle_cleanup_orphans(): void
 
         $deletedCount = $this->cleanup_orphaned_files();
 
+        delete_transient('mstv_orphan_count_' . get_current_blog_id());
+
         set_transient('mstv_cleanup_orphans_' . get_current_user_id(), [
             'deleted_count' => $deletedCount,
         ], MINUTE_IN_SECONDS);
@@ -518,21 +502,7 @@ public function handle_export_audit_csv(): void
         do {
             $result = $repo->find_filtered($filters, $page, 200);
             foreach ($result['items'] as $log) {
-                $context = json_decode($log->context ?? '{}', true);
-                $name = '';
-                if (is_array($context)) {
-                    $name = $context['filename'] ?? $context['name'] ?? $context['display_name'] ?? '';
-                }
-                fputcsv($out, [
-                    $log->created_at,
-                    $log->user_login ?? '',
-                    (int) $log->user_id,
-                    $log->action,
-                    $log->target_type,
-                    $log->target_id !== null ? (int) $log->target_id : '',
-                    $name,
-                    $log->ip_address ?? '',
-                ]);
+                fputcsv($out, $this->build_audit_csv_row($log));
             }
             $page++;
         } while ($page <= ($result['pagination']['total_pages'] ?? 0));
@@ -542,6 +512,26 @@ public function handle_export_audit_csv(): void
         exit;
     }
 
+    private function build_audit_csv_row(object $log): array
+    {
+        $context = json_decode($log->context ?? '{}', true);
+        $name = '';
+        if (is_array($context)) {
+            $name = $context['filename'] ?? $context['name'] ?? $context['display_name'] ?? '';
+        }
+
+        return [
+            $log->created_at,
+            $log->user_login ?? '',
+            (int) $log->user_id,
+            $log->action,
+            $log->target_type,
+            $log->target_id !== null ? (int) $log->target_id : '',
+            $name,
+            $log->ip_address ?? '',
+        ];
+    }
+
     private function guard_stream_request(): void
     {
         if (!$this->current_user_can_manage()) {
@@ -580,6 +570,13 @@ private function build_files_services(): array
 
     private function count_orphaned_files(): int
     {
+        $cacheKey = 'mstv_orphan_count_' . get_current_blog_id();
+        $cached = get_transient($cacheKey);
+
+        if ($cached !== false) {
+            return (int) $cached;
+        }
+
         $services = $this->build_files_services();
         $filesystem = $services['storage']->get_filesystem();
         $count = 0;
@@ -590,6 +587,8 @@ private function count_orphaned_files(): int
             }
         }
 
+        set_transient($cacheKey, $count, 5 * MINUTE_IN_SECONDS);
+
         return $count;
     }
 

includes/class-mstv-assets.php

@@ -38,6 +38,18 @@ public function enqueue_assets(string $hook): void
             true
         );
 
+        wp_enqueue_script(
+            'mstv-admin-notices',
+            MSTV_PLUGIN_URL . 'assets/js/admin-notice-dismiss.js',
+            [],
+            MSTV_VERSION,
+            true
+        );
+
+        wp_localize_script('mstv-admin-notices', 'mstvNoticeData', [
+            'dismissNonce' => wp_create_nonce('mstv_dismiss_storage_notice'),
+        ]);
+
         wp_localize_script('mstv-admin', 'mstvConfig', [
             'branding' => [
                 'name' => $this->settings->get_brand_name(),

includes/class-mstv-bootstrap.php

@@ -20,6 +20,10 @@ private function __construct()
     {
     }
 
+    /**
+     * Bootstrap the plugin: load all class files and register WP hooks.
+     * Called directly from the plugin entry point after the singleton is created.
+     */
     public function init(): void
     {
         $this->load_dependencies();
@@ -47,6 +51,7 @@ private function load_dependencies(): void
             'class-mstv-permissions',
             'class-mstv-quota',
             'class-mstv-notifications',
+            'trait-mstv-binary-stream',
             'class-mstv-download',
             'class-mstv-preview',
             'class-mstv-export',
@@ -109,6 +114,13 @@ public function deactivate(): void
         MSTV_Deactivator::deactivate();
     }
 
+    /**
+     * Instantiate core services and wire their WP hooks.
+     *
+     * Runs on `init` at priority 5 (after maybe_upgrade at priority 1). Admin-only services
+     * (MSTV_Admin, MSTV_Assets) are only instantiated when is_admin() is true to avoid loading
+     * unnecessary code on front-end requests.
+     */
     public function init_services(): void
     {
         if (!isset($this->services['settings'])) {
@@ -161,6 +173,14 @@ public function initialize_site(\WP_Site $newSite): void
         MSTV_Activator::initialize_site((int) $newSite->blog_id);
     }
 
+    /**
+     * Wire the REST API controllers with all required dependencies.
+     *
+     * Runs on `rest_api_init`. Builds the full dependency graph (settings → auth → storage →
+     * repos → permissions → quota → download/preview) and registers routes for both
+     * MSTV_REST_Controller (browser, files, exports) and MSTV_REST_Governance_Controller
+     * (groups, permissions, quotas, reports).
+     */
     public function init_rest_api(): void
     {
         $settings = $this->service('settings');

includes/class-mstv-download.php

@@ -4,6 +4,7 @@
 
 class MSTV_Download
 {
+    use MSTV_Binary_Stream;
     private MSTV_Storage $storage;
     private MSTV_Repository_Files $filesRepo;
     private MSTV_Auth $auth;
@@ -105,6 +106,8 @@ private function build_download_filename(string $displayName, string $extension)
     private function stream_file(string $path, string $filename, string $mimeType, int $fileSize): void
     {
         if (!is_readable($path)) {
+            // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log -- Server-side diagnostic; not exposed to users.
+            error_log('TeamVault: file not readable for download: ' . $path);
             wp_die(
                 esc_html__('Unable to read the file.', 'mikesoft-teamvault'),
                 esc_html__('Error', 'mikesoft-teamvault'),
@@ -126,6 +129,8 @@ private function stream_file(string $path, string $filename, string $mimeType, i
         header('X-Robots-Tag: noindex, nofollow');
 
         if (!$this->stream_absolute_file($path)) {
+            // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log -- Server-side diagnostic; not exposed to users.
+            error_log('TeamVault: stream failed for download: ' . $path);
             wp_die(
                 esc_html__('Unable to read the file.', 'mikesoft-teamvault'),
                 esc_html__('Error', 'mikesoft-teamvault'),
@@ -136,35 +141,6 @@ private function stream_file(string $path, string $filename, string $mimeType, i
         exit;
     }
 
-    private function stream_absolute_file(string $path): bool
-    {
-        // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fopen -- Authenticated binary downloads need chunked streaming; WP_Filesystem::get_contents() loads full files into memory.
-        $handle = @fopen($path, 'rb');
-
-        if ($handle === false) {
-            return false;
-        }
-
-        while (!feof($handle)) {
-            // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fread -- Authenticated binary downloads need chunked streaming; WP_Filesystem::get_contents() loads full files into memory.
-            $chunk = fread($handle, 1048576);
-            if ($chunk === false) {
-                // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fclose -- Closing a local stream opened only for chunked binary output.
-                fclose($handle);
-                return false;
-            }
-
-            // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- Binary files stream output must not be escaped.
-            echo $chunk;
-            flush();
-        }
-
-        // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fclose -- Closing a local stream opened only for chunked binary output.
-        fclose($handle);
-
-        return true;
-    }
-
     private function sanitize_filename(string $filename): string
     {
         return MSTV_Helpers::sanitize_archive_entry_segment($filename);

includes/class-mstv-filesystem.php

@@ -44,6 +44,16 @@ public function resolve(string $relativePath): string
         return wp_normalize_path($this->basePath . DIRECTORY_SEPARATOR . str_replace(['/', '\\'], DIRECTORY_SEPARATOR, $relativePath));
     }
 
+    /**
+     * Confirm that an absolute path lives inside the base storage directory.
+     *
+     * Uses realpath() to resolve symlinks and then a normalized prefix comparison to block
+     * traversal. Falls back to dirname()+basename() when the path does not yet exist (e.g.
+     * a file being written for the first time).
+     *
+     * @param string $path Absolute filesystem path to validate.
+     * @return bool True only if the path is inside the configured base directory.
+     */
     public function verify_path(string $path): bool
     {
         $realBase = realpath($this->basePath);
@@ -75,6 +85,18 @@ public function verify_path(string $path): bool
             || strpos(trailingslashit($normalizedPath), $normalizedBase) === 0;
     }
 
+    /**
+     * Resolve a relative path and run all security checks in one call.
+     *
+     * Combines verify_path() (boundary check), optional file-existence check, and
+     * path_has_symlink() (symlink traversal check). Returns false on any failure so
+     * callers can treat a false return as "access denied" without distinguishing the cause.
+     *
+     * @param string $relativePath  Path relative to the base storage directory.
+     * @param bool   $allowMissing  When true, skip the file-existence check (used for paths
+     *                              that are about to be created).
+     * @return string|false Absolute verified path, or false if any check fails.
+     */
     public function get_verified_path(string $relativePath, bool $allowMissing = false): string|false
     {
         $fullPath = $this->resolve($relativePath);
@@ -536,6 +558,16 @@ public function get_disk_stats(): array
         ];
     }
 
+    /**
+     * Walk each segment of a path and return true if any segment is a symlink.
+     *
+     * A simple is_link($path) is insufficient because an intermediate directory in the
+     * path could be a symlink pointing outside the base directory. This method iterates
+     * from the base root down to the target path, stopping at the first symlink found.
+     *
+     * @param string $path Absolute path to inspect (must already pass verify_path()).
+     * @return bool True if any segment of the path is a symlink, false if the path is clean.
+     */
     private function path_has_symlink(string $path): bool
     {
         $realBase = realpath($this->basePath);

includes/class-mstv-preview.php

@@ -4,6 +4,7 @@
 
 class MSTV_Preview
 {
+    use MSTV_Binary_Stream;
     private MSTV_Storage $storage;
     private MSTV_Repository_Files $filesRepo;
     private MSTV_Auth $auth;
@@ -115,6 +116,8 @@ public function serve(int $fileId): void
     private function stream_preview(string $path, string $filename, string $mimeType, int $fileSize): void
     {
         if (!is_readable($path)) {
+            // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log -- Server-side diagnostic; not exposed to users.
+            error_log('TeamVault: file not readable for preview: ' . $path);
             wp_die(
                 esc_html__('Unable to read the file.', 'mikesoft-teamvault'),
                 esc_html__('Error', 'mikesoft-teamvault'),
@@ -138,6 +141,8 @@ private function stream_preview(string $path, string $filename, string $mimeType
         }
 
         if (!$this->stream_absolute_file($path)) {
+            // phpcs:ignore WordPress.PHP.DevelopmentFunctions.error_log_error_log -- Server-side diagnostic; not exposed to users.
+            error_log('TeamVault: stream failed for preview: ' . $path);
             wp_die(
                 esc_html__('Unable to read the file.', 'mikesoft-teamvault'),
                 esc_html__('Error', 'mikesoft-teamvault'),
@@ -148,35 +153,6 @@ private function stream_preview(string $path, string $filename, string $mimeType
         exit;
     }
 
-    private function stream_absolute_file(string $path): bool
-    {
-        // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fopen -- Authenticated binary previews need chunked streaming; WP_Filesystem::get_contents() loads full files into memory.
-        $handle = @fopen($path, 'rb');
-
-        if ($handle === false) {
-            return false;
-        }
-
-        while (!feof($handle)) {
-            // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fread -- Authenticated binary previews need chunked streaming; WP_Filesystem::get_contents() loads full files into memory.
-            $chunk = fread($handle, 1048576);
-            if ($chunk === false) {
-                // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fclose -- Closing a local stream opened only for chunked binary output.
-                fclose($handle);
-                return false;
-            }
-
-            // phpcs:ignore WordPress.Security.EscapeOutput.OutputNotEscaped -- Binary preview stream output must not be escaped.
-            echo $chunk;
-            flush();
-        }
-
-        // phpcs:ignore WordPress.WP.AlternativeFunctions.file_system_operations_fclose -- Closing a local stream opened only for chunked binary output.
-        fclose($handle);
-
-        return true;
-    }
-
     private function sanitize_filename(string $filename): string
     {
         return MSTV_Helpers::sanitize_archive_entry_segment($filename);