@networkpro/web 1.24.4 → 1.25.0

package/.github/workflows/branch-guard.yml

@@ -0,0 +1,53 @@
+# .github/workflows/branch-guard.yml
+#
+# Copyright © 2025 Network Pro Strategies (Network Pro™)
+# SPDX-License-Identifier: CC-BY-4.0 OR GPL-3.0-or-later
+# This file is part of Network Pro
+#
+# Warns if commits are pushed directly to master/main instead of via PR.
+# Does NOT block the commit — it just posts a workflow summary and log warning.
+
+name: Branch Guard
+
+on:
+  push:
+    branches:
+      - master
+      - main
+
+permissions:
+  contents: read
+
+jobs:
+  warn-direct-commit:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Check commit source
+        run: |
+          commit_msg="${{ github.event.head_commit.message }}"
+          actor="${{ github.actor }}"
+          branch="${GITHUB_REF##*/}"
+
+          echo "📝 Commit message: $commit_msg"
+          echo "👤 Actor: $actor"
+          echo "🌿 Branch: $branch"
+
+          # Define known safe patterns (merge or bot commits)
+          if echo "$commit_msg" | grep -Eq "Merge pull request|See merge request|Merge branch|(#\d+)$"; then
+            echo "✅ Merge-related commit detected — no warning."
+            exit 0
+          fi
+
+          if [[ "$actor" == "dependabot[bot]" ]] || [[ "$actor" == "renovate[bot]" ]] || [[ "$actor" == "github-actions[bot]" ]]; then
+            echo "🤖 Bot commit detected — skipping warning."
+            exit 0
+          fi
+
+          # Otherwise, warn for direct commits
+          echo "::warning ::⚠️ Direct commit to $branch by $actor."
+          {
+            echo "### ⚠️ Direct Commit Detected"
+            echo "A commit was pushed directly to \`$branch\` by **$actor**."
+            echo ""
+            echo "💡 It's recommended to use pull requests for traceability and CI validation."
+          } >> $GITHUB_STEP_SUMMARY

package/CHANGELOG.md

@@ -22,6 +22,108 @@ This project attempts to follow [Keep a Changelog](https://keepachangelog.com/en
 
 ---
 
+## [1.25.0]
+
+### Added
+
+- Introduced unified environment detection utility (`src/lib/utils/env.js`) with full **JSDoc typing**.
+  - Normalizes `process.env` and `import.meta.env` usage across SSR (Node) and client contexts.
+  - Safely handles browser environments where `process` is undefined.
+  - Provides standardized flags for:
+    - `isDev`, `isProd`, `isAudit`, `isCI`, and `isTest`
+  - Enables consistent environment checks across analytics, CSP, and runtime logic.
+
+- Added hybrid **environment + host-based analytics guard** in `src/lib/stores/posthog.js`.
+  - Automatically disables PostHog tracking in `audit` mode or when hostname matches `*.audit.netwk.pro`.
+  - Prevents analytics initialization during development and test contexts.
+  - Uses the shared `detectEnvironment()` utility for centralized logic.
+  - Improves runtime logging for environment-specific behavior.
+
+### Changed
+
+- Updated `hooks.server.js` to include a dedicated **audit environment block** for Content Security Policy (CSP).
+  - Hardened audit CSP by removing all analytics-related sources (`posthog.com`, `posthog-assets.com`).
+  - Redirects CSP violation reporting to the mock endpoint (`/api/mock-csp`) in audit mode.
+  - Preserves full HSTS and other production security headers for audit deployments.
+  - Added clear separation between `test`, `audit`, and `prod` security policies.
+  - Improved console debugging for environment detection (`NODE_ENV`, `ENV_MODE`).
+
+- Refactored **environment detection logic** for improved reliability across client and server contexts.
+  - Added unified environment resolver at `src/lib/utils/env.js` to standardize detection for `dev`, `prod`, `audit`, `ci`, and `test` modes.
+  - Ensures consistent handling of both `process.env.*` (Node/SSR) and `import.meta.env.*` (Vite/client) variables.
+  - Prevents mismatched behavior between browser-side analytics (`posthog.js`) and server-side policies (`hooks.server.js`).
+  - Automatically falls back to `'unknown'` if no explicit mode is set, avoiding build-time exceptions.
+
+- Refactored **Branch Guard** workflow (`.github/workflows/branch-guard.yml`) for improved accuracy and reduced noise.
+  - Adjusted detection logic to **ignore merge commits**, Dependabot updates, and automated actions.
+  - Ensures workflow warnings are shown **only for true direct commits** to protected branches (`master`, `main`).
+  - Simplified step output and summary formatting for clearer reporting in the Actions log and job summary.
+  - Maintains lightweight permissions (`contents: read`) and executes entirely without repository writes.
+  - Improves reliability of branch protection monitoring without affecting CI or merge operations.
+
+### Fixed
+
+- Resolved client-side crash in browser environments caused by `process.env` being undefined.
+  - Implemented defensive checks in `env.js` for `process` availability.
+  - Eliminated reference errors during client-side initialization of analytics.
+
+### Developer Experience
+
+- Simplified future configuration by consolidating environment checks into a single typed utility.
+- Improved maintainability and Vercel compatibility by ensuring `.env.audit` and `PUBLIC_ENV_MODE` variables propagate correctly to both client and server environments.
+
+### Developer Notes
+
+- When deploying audit builds, ensure Vercel environment variables include:
+
+```bash
+ENV_MODE=audit
+PUBLIC_ENV_MODE=audit
+```
+
+This enables analytics filtering and CSP hardening for the audit environment.
+
+- Audit deployments retain full HTTPS and security headers but omit telemetry and external CSP reporting.
+
+---
+
+## [1.24.5]
+
+### Added
+
+- Introduced **Branch Guard workflow** (`.github/workflows/branch-guard.yml`) to automatically enforce branch protection policies.
+  - Ensures consistent branch naming conventions.
+  - Blocks direct pushes to protected branches (e.g., `master`, `main`, and `release/*`).
+  - Provides early validation for pull requests and feature branches to maintain repository integrity.
+- Introduced comprehensive pre-push checks for code consistency and style compliance.
+  - Added optional `simple-git-hooks` configuration to automate local linting before commits or pushes.
+  - Implemented `lint:all` script using `npm-run-all` for efficient, parallel execution of linters.
+  - Ensures **ESLint**, **Stylelint**, **Markdownlint**, and **Prettier** all run before code is committed, improving codebase hygiene and preventing formatting drift.
+  - Designed for **developer-side speed and reliability**, running linters in parallel while deferring `format` (Prettier) until after lint checks complete for safety.
+- Added **hybrid linting configuration**:
+  - Parallel execution for static lint tasks (`eslint`, `stylelint`, `markdownlint`).
+  - Sequential Prettier formatting step for deterministic, race-free execution.
+
+### Changed
+
+- Reorganized local linting commands for clarity and consistency, consolidating redundant sequential scripts into the `lint:all` aggregator.
+- Improved developer experience with faster pre-push validations and clearer script naming conventions.
+- Bumped project version to `v1.24.5`.
+
+### Developer Experience
+
+- Enhanced local development workflow by introducing **fast, parallel linting** and **optional pre-commit hooks**, reducing turnaround time for style and quality checks.
+- Simplified npm scripts for readability and maintainability by adopting `npm-run-all` as the central task runner.
+
+### Notes
+
+- For instructions on installing and configuring the new dependencies, please see the **[Editor Configuration](https://github.com/netwk-pro/netwk-pro.github.io/wiki/Editor-Configuration#automation)** section of the [Wiki](https://github.com/netwk-pro/netwk-pro.github.io/wiki).
+
+> **Note:** Version `1.24.4` was merged but not tagged or released.  
+> Subsequent updates are reflected in `v1.24.5` and later.
+
+---
+
 ## [1.24.4]
 
 ### Documentation
@@ -250,7 +352,7 @@ This project attempts to follow [Keep a Changelog](https://keepachangelog.com/en
 - Updated the text of `ServicesContent.svelte`.
 - Increased default Playwright test timeouts for navigation-sensitive suites (Desktop and Mobile) to improve stability under CI latency conditions.
 - Implemented `Promise.all()` pattern for combined click and navigation waits, reducing flakiness in route transition tests.
-- Updated the `'about' link` navigation tests in both Desktop and Mobile scenarios to include:
+- Updated the `about` link navigation tests in both Desktop and Mobile scenarios to include:
   - Explicit `page.waitForLoadState('domcontentloaded')` calls before assertions.
   - Extended per-suite timeouts (`90s`) using `test.setTimeout(90000)` for reliability on slower environments.
   - Added fallback `waitForURL('\*\*/about', { timeout: 60000 })` to ensure deterministic routing checks.
@@ -1481,7 +1583,9 @@ This project attempts to follow [Keep a Changelog](https://keepachangelog.com/en
 
 <!-- Link references -->
 
-[Unreleased]: https://github.com/netwk-pro/netwk-pro.github.io/compare/v1.24.4...HEAD
+[Unreleased]: https://github.com/netwk-pro/netwk-pro.github.io/compare/v1.25.0...HEAD
+[1.25.0]: https://github.com/netwk-pro/netwk-pro.github.io/releases/tag/v1.25.0
+[1.24.5]: https://github.com/netwk-pro/netwk-pro.github.io/releases/tag/v1.24.5
 [1.24.4]: https://github.com/netwk-pro/netwk-pro.github.io/releases/tag/v1.24.4
 [1.24.3]: https://github.com/netwk-pro/netwk-pro.github.io/releases/tag/v1.24.3
 [1.24.2]: https://github.com/netwk-pro/netwk-pro.github.io/releases/tag/v1.24.2

package/cspell.json

@@ -27,6 +27,7 @@
     "heliboard",
     "homescreen",
     "HREFTOP",
+    "HSTS",
     "Izzy",
     "Keybase",
     "keypair",

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@networkpro/web",
   "private": false,
-  "version": "1.24.4",
+  "version": "1.25.0",
   "description": "Locking Down Networks, Unlocking Confidence™ | Security, Networking, Privacy — Network Pro Strategies",
   "keywords": [
     "advisory",
@@ -35,22 +35,24 @@
   },
   "scripts": {
     "dev": "vite dev",
+    "dev:audit": "vite --mode audit",
     "start": "npm run dev",
     "dev:vercel": "vercel dev",
     "build": "vite build",
+    "build:audit": "vite build --mode audit",
     "build:vercel": "vercel build",
     "preview": "vite preview",
     "css:bundle": "node scripts/bundleCss.js",
-    "prepare": "svelte-kit sync || echo ''",
+    "prepare": "svelte-kit sync && npx simple-git-hooks || echo ''",
     "check": "svelte-kit sync && svelte-check --tsconfig ./jsconfig.json",
     "check:watch": "svelte-kit sync && svelte-check --tsconfig ./jsconfig.json --watch",
     "type-check": "svelte-check --tsconfig ./jsconfig.json",
     "lint:types": "npm run type-check",
     "check:env": "node scripts/checkEnv.js",
     "check:node": "node scripts/checkNode.js",
-    "checkout": "npm run check:node && npm run test:all && npm run lint:all && npm run check",
+    "checkout": "npm-run-all check:node test:all lint:all check",
     "verify": "npm run checkout",
-    "delete": "rm -rf build .svelte-kit node_modules package-lock.json",
+    "delete": "rm -rf .svelte-kit node_modules package-lock.json",
     "clean": "npm run delete && npm cache clean --force && npm install",
     "upgrade": "ncu -u --format group --color",
     "check:updates": "ncu --format group --color",
@@ -69,14 +71,18 @@
     "lint:jsdoc": "eslint . --ext .js,.cjs,.mjs,.svelte --max-warnings=0",
     "lint:css": "stylelint \"**/*.{css,svelte}\" --ignore-path .stylelintignore",
     "lint:md": "npx markdownlint-cli2 \"**/*.{md,markdown}\" \"#node_modules/**\" \"#playwright-report/**\" \"#test-results/**\"",
-    "lint:all": "npm run lint && npm run lint:md && npm run lint:css && npm run format",
     "format": "prettier --check .",
     "format:fix": "prettier --write .",
+    "lint:all": "npm-run-all --parallel --print-label lint lint:md lint:css --sequential format",
     "lhci": "lhci",
     "lhci:run": "lhci autorun --config=.lighthouserc.cjs",
     "audit:coverage": "vitest run tests/internal/auditCoverage.test.js",
     "postinstall": "npm run check:node"
   },
+  "simple-git-hooks": {
+    "pre-commit": "if [ \"$CI\" = \"true\" ]; then exit 0; else npm run lint:all; fi",
+    "pre-push": "if [ \"$CI\" = \"true\" ]; then exit 0; else npm run checkout; fi"
+  },
   "dependencies": {
     "dompurify": "^3.3.0",
     "posthog-js": "^1.284.0",
@@ -105,10 +111,12 @@
     "lightningcss": "^1.30.2",
     "markdownlint": "^0.39.0",
     "markdownlint-cli2": "^0.18.1",
+    "npm-run-all": "^4.1.5",
     "playwright": "^1.56.1",
     "postcss": "^8.5.6",
     "prettier": "3.6.2",
     "prettier-plugin-svelte": "^3.4.0",
+    "simple-git-hooks": "^2.13.1",
     "stylelint": "^16.25.0",
     "stylelint-config-html": "^1.1.0",
     "stylelint-config-recommended": "^17.0.0",

package/src/hooks.server.js

@@ -6,33 +6,25 @@ SPDX-License-Identifier: CC-BY-4.0 OR GPL-3.0-or-later
 This file is part of Network Pro.
 ========================================================================== */
 
+import { detectEnvironment } from '$lib/utils/env.js';
+
 /**
  * SvelteKit server hook to set Content Security Policy (CSP) header.
  * @type {import('@sveltejs/kit').Handle}
  */
 export async function handle({ event, resolve }) {
-  // Create the response
   const response = await resolve(event);
+  const { isAudit, isTest, isProd } = detectEnvironment();
 
-  // Determine environment flags
-  // Default to development policy if neither test nor prod
-  const isTestEnvironment =
-    process.env.NODE_ENV === 'development' ||
-    process.env.ENV_MODE === 'dev' ||
-    process.env.ENV_MODE === 'ci';
-  const isProdEnvironment =
-    process.env.NODE_ENV === 'production' || process.env.ENV_MODE === 'prod';
-
-  console.log('[CSP Debug] NODE_ENV:', process.env.NODE_ENV);
-  console.log('[CSP Debug] ENV_MODE:', process.env.ENV_MODE);
+  console.log('[CSP Debug ENV]', detectEnvironment());
 
   // Determine report URI
   const reportUri =
-    isProdEnvironment && !isTestEnvironment
+    isProd && !isTest && !isAudit
       ? 'https://csp.netwk.pro/.netlify/functions/csp-report'
       : '/api/mock-csp';
 
-  // Construct base policy
+  // Base hardened policy
   const cspDirectives = [
     "default-src 'self';",
     "script-src 'self' 'unsafe-inline' https://us.i.posthog.com https://us-assets.i.posthog.com;",
@@ -45,40 +37,45 @@ export async function handle({ event, resolve }) {
     "object-src 'none';",
     "frame-ancestors 'none';",
     'upgrade-insecure-requests;',
-    // Report CSP violations to external endpoint hosted at csp.netwk.pro
-    `report-uri ${reportUri};`,
-    'report-to csp-endpoint;',
   ];
 
-  // Loosen up CSP for test environments (and allow local PostHog proxy)
-  if (isTestEnvironment) {
+  // 🧪 Looser CSP for local/CI test environments
+  if (isTest) {
     cspDirectives[1] =
       "script-src 'self' 'unsafe-inline' 'unsafe-eval' http://localhost:* ws://localhost:*;";
-    cspDirectives[2] =
-      "script-src-elem 'self' 'unsafe-inline' 'unsafe-eval' http://localhost:* ws://localhost:*;";
-    cspDirectives[3] = "style-src 'self' 'unsafe-inline' http://localhost:*;";
-    cspDirectives[4] = "img-src 'self' data: http://localhost:*;";
-    cspDirectives[5] =
+    cspDirectives[2] = "style-src 'self' 'unsafe-inline' http://localhost:*;";
+    cspDirectives[3] = "img-src 'self' data: http://localhost:*;";
+    cspDirectives[4] =
       "connect-src 'self' http://localhost:* ws://localhost:* https://us.i.posthog.com https://us-assets.i.posthog.com;";
   }
 
-  response.headers.set(
-    'Report-To',
-    JSON.stringify({
-      group: 'csp-endpoint',
-      max_age: 10886400, // 18 weeks
-      endpoints: [
-        {
-          url: 'https://csp.netwk.pro/.netlify/functions/csp-report',
-        },
-      ],
-      include_subdomains: true,
-    }),
-  );
+  // 🧩 Hardened CSP for audit environment — no analytics, no CSP reporting
+  if (isAudit) {
+    cspDirectives[1] = "script-src 'self' 'unsafe-inline';";
+    cspDirectives[2] = "style-src 'self' 'unsafe-inline';";
+    cspDirectives[3] = "img-src 'self' data:;";
+    cspDirectives[4] = "connect-src 'self';";
+  }
+
+  // 📋 Attach CSP report directives ONLY in production
+  if (isProd && !isAudit && !isTest) {
+    cspDirectives.push(`report-uri ${reportUri};`, 'report-to csp-endpoint;');
 
+    response.headers.set(
+      'Report-To',
+      JSON.stringify({
+        group: 'csp-endpoint',
+        max_age: 10886400, // 18 weeks
+        endpoints: [{ url: reportUri }],
+        include_subdomains: true,
+      }),
+    );
+  }
+
+  // ✅ Apply final CSP
   response.headers.set('Content-Security-Policy', cspDirectives.join(' '));
 
-  // Set other security headers
+  // Standard security headers
   response.headers.set(
     'Permissions-Policy',
     [
@@ -103,10 +100,10 @@ export async function handle({ event, resolve }) {
   response.headers.set('Referrer-Policy', 'strict-origin-when-cross-origin');
   response.headers.set('X-Frame-Options', 'DENY');
 
-  if (process.env.ENV_MODE !== 'test' && process.env.ENV_MODE !== 'ci') {
+  if (!isTest) {
     response.headers.set(
       'Strict-Transport-Security',
-      'max-age=31536000; includeSubDomains;', // No preload here
+      'max-age=31536000; includeSubDomains;',
     );
   }
 
@@ -120,8 +117,5 @@ export async function handle({ event, resolve }) {
 export function handleError({ error, event }) {
   console.error('🔴 SSR Error in route:', event.url.pathname);
   console.error(error);
-
-  return {
-    message: 'A server-side error occurred',
-  };
+  return { message: 'A server-side error occurred' };
 }

package/src/lib/stores/posthog.js

@@ -15,6 +15,7 @@ import {
   remindUserToReconsent,
   trackingPreferences,
 } from '$lib/stores/trackingPreferences.js';
+import { detectEnvironment } from '$lib/utils/env.js';
 import { get, writable } from 'svelte/store';
 
 /**
@@ -38,24 +39,39 @@ let ph = null;
 /**
  * Initializes the PostHog analytics client if tracking is permitted.
  * Uses dynamic import to avoid SSR failures.
+ *
  * @returns {Promise<void>}
  */
 export async function initPostHog() {
   if (initialized || typeof window === 'undefined') return;
-  const isDev = import.meta.env.MODE === 'development';
-  if (isDev) {
-    console.info('[PostHog] Skipping init in development mode.');
+
+  const { isAudit, isDev, isTest, mode } = detectEnvironment();
+
+  // 🌐 Hybrid hostname + environment guard
+  const host = window.location.hostname;
+  const isAuditHost = /(^|\.)audit\.netwk\.pro$/i.test(host);
+  const effectiveAudit = isAudit || isAuditHost;
+
+  if (effectiveAudit) {
+    console.info(`[PostHog] Skipping analytics (${mode} mode, host: ${host}).`);
+    return;
+  }
+
+  // 🧱 Skip entirely in dev/test contexts
+  if (isDev || isTest) {
+    console.info('[PostHog] Skipping init in dev/test mode.');
     return;
   }
 
+  // 🚀 Production analytics logic (with user consent)
   initialized = true;
 
   const { enabled } = get(trackingPreferences);
   trackingEnabled.set(enabled);
-  showReminder.set(get(remindUserToReconsent)); // use derived store instead
+  showReminder.set(get(remindUserToReconsent));
 
   if (!enabled) {
-    console.log('[PostHog] Tracking is disabled — skipping init.');
+    console.log('[PostHog] Tracking disabled — user opted out.');
     return;
   }
 
@@ -63,6 +79,7 @@ export async function initPostHog() {
     const posthogModule = await import('posthog-js');
     ph = posthogModule.default;
 
+    // ✅ Initialize PostHog
     // cspell:disable-next-line
     ph.init('phc_Qshfo6AXzh4pS7aPigfqyeo4qj1qlyh7gDuHDeVMSR0', {
       api_host: '/relay-MSR0/',

package/src/lib/utils/env.js

@@ -0,0 +1,74 @@
+/* ==========================================================================
+src/lib/utils/env.js
+
+Copyright © 2025 Network Pro Strategies (Network Pro™)
+SPDX-License-Identifier: CC-BY-4.0 OR GPL-3.0-or-later
+This file is part of Network Pro.
+========================================================================== */
+
+/**
+ * @file env.js
+ * @description Unified environment detection utility.
+ * Normalizes process.env and import.meta.env for consistent behavior
+ * across SvelteKit server (SSR), client (browser), and build-time contexts.
+ *
+ * Supports: dev, prod, ci, test, audit.
+ *
+ * @module src/lib/utils
+ * @author Scott Lopez
+ * @updated 2025-11-02
+ *
+ * @example
+ * import { detectEnvironment } from '$lib/utils/env.js';
+ * const { isAudit, isProd } = detectEnvironment();
+ * if (isAudit) console.log('Running in audit mode');
+ */
+
+/**
+ * @typedef {object} EnvironmentInfo
+ * @property {string} mode - The detected environment mode (`dev`, `prod`, `audit`, etc.).
+ * @property {boolean} isDev - True when running in a development or local environment.
+ * @property {boolean} isProd - True when running in production.
+ * @property {boolean} isAudit - True when running in audit / staging environments.
+ * @property {boolean} isCI - True when running in continuous integration (CI) pipelines.
+ * @property {boolean} isTest - True when running under test or mock environments.
+ */
+
+/**
+ * Normalizes environment detection across client, SSR, and build contexts.
+ * Uses `import.meta.env` for Vite build-time vars and `process.env` for runtime vars.
+ *
+ * @returns {EnvironmentInfo} Normalized environment context flags.
+ */
+export function detectEnvironment() {
+  /** @type {string | undefined} */
+  const viteMode = import.meta.env?.MODE;
+  /** @type {string | undefined} */
+  const publicEnvMode = import.meta.env?.PUBLIC_ENV_MODE;
+
+  /** @type {string | undefined} */
+  const nodeEnv =
+    typeof process !== 'undefined' && process?.env?.NODE_ENV
+      ? process.env.NODE_ENV
+      : undefined;
+
+  /** @type {string | undefined} */
+  const envMode =
+    typeof process !== 'undefined' && process?.env?.ENV_MODE
+      ? process.env.ENV_MODE
+      : undefined;
+
+  // Fallback order — guarantees a mode string even if nothing is set
+  /** @type {string} */
+  const mode = envMode || publicEnvMode || viteMode || nodeEnv || 'unknown';
+
+  // Return a normalized, typed object
+  return {
+    mode,
+    isDev: ['development', 'dev'].includes(mode),
+    isProd: ['production', 'prod'].includes(mode),
+    isAudit: mode === 'audit',
+    isCI: mode === 'ci',
+    isTest: mode === 'test',
+  };
+}

package/src/service-worker.js

@@ -38,10 +38,11 @@ const IGNORE_PATHS = new Set([
   '/pgp/contact@s.neteng.pro.asc',
   '/pgp/github@sl.neteng.cc.asc',
   '/pgp/security@s.neteng.pro.asc',
-  '/pgp/support@neteng.pro.asc',
+  '/pgp/support@netwk.pro.asc',
   '/screenshots/desktop-foss.png',
   '/webfonts/fa-brands-400.ttf',
   '/webfonts/fa-solid-900.ttf',
+  '/7cbb39ce-750b-43da-83b8-8980e5554d4d.txt',
   '/robots.txt',
   '/sitemap.xml',
   '/CNAME',