@networkpro/web 1.7.9 → 1.9.0

package/README.md

@@ -17,6 +17,8 @@ This file is part of Network Pro.
 [![Code Style: Prettier](https://img.shields.io/badge/code_style-prettier-ff69b4.svg?style=flat)](https://github.com/prettier/prettier) [![stylelint](https://img.shields.io/badge/stylelint-%23747474?style=flat&logo=stylelint&logoSize=auto&labelColor=%23263238)](https://stylelint.io/)
 [![Contributor Covenant](https://img.shields.io/badge/Contributor%20Covenant-2.1-4baaaa.svg)](https://github.com/netwk-pro/netwk-pro.github.io/blob/master/CODE_OF_CONDUCT.md)
 
+<section id="top">
+
 ## 🚀 Project Overview
 
 This GitHub repository powers the official web presence of **[Network Pro Strategies](https://netwk.pro/about)** — a privacy-first consultancy specializing in cybersecurity, network engineering, and information security. We also lead public advocacy efforts promoting digital privacy and responsible cyber policy.
@@ -26,36 +28,64 @@ Built with [SvelteKit](https://kit.svelte.dev/) and deployed via [Netlify](https
 
 All infrastructure and data flows are designed with **maximum transparency, self-hosting, and user privacy** in mind.
 
-### 📁 Repository Structure
+</section>
+
+### Table of Contents
+
+- [Repository Structure](#structure)
+- [Getting Started](#getting-started)
+- [Configuration](#configuration)
+- [Service Worker Utilities](#sw-utilities)
+- [CSP Report Handler](#cspreport)
+- [Testing](#testing)
+- [Recommended Toolchain](#toolchain)
+- [Tooling Configuration](#toolconfig)
+- [Available Scripts](#scripts)
+- [License](#license)
+- [Questions](#questions)
+
+---
+
+<section id="structure">
+
+## 📁 Repository Structure
 
 ```bash
-.
-├── .github/workflows/     # CI workflows and automation
-├── .vscode/
-│   ├── customData.json    # Custom CSS data for FontAwesome icons
-│   ├── extensions.json    # Recommended VSCodium / VS Code extensions
-│   ├── extensions.jsonc   # Commented version of extensions.json for reference
-│   └── settings.json      # User settings for VSCodium / VS Code
-├── netlify-functions/
-│   └── cspReport.js       # Serverless function to receive and log CSP violation reports
-├── scripts/               # General utility scripts
-├── src/
-│   ├── lib/               # Reusable components, styles, utilities
-│   ├── routes/            # SvelteKit routes (+page.svelte, +page.server.js)
-│   ├── hooks.client.ts    # Handles PWA install prompt and logs client errors
-│   ├── hooks.server.js    # Injects CSP headers and permissions policy
-│   ├── app.html           # SvelteKit entry HTML with CSP/meta/bootentry
-│   └── service-worker.js  # Custom Service Worker
-├── static/                # Static assets served at root
-│   ├── manifest.json      # Manifest file for PWA configuration
-│   ├── robots.txt         # Instructions for web robots
-│   └── sitemap.xml        # Sitemap for search engines
-├── tests/
-│   ├── e2e/               # End-to-end Playwright tests
-│   └── unit/              # Vite unit tests
-├── _redirects             # Netlify redirects
-├── netlify.toml           # Netlify configuration
-└── ...
+  .
+  ├── .github/
+  │   └── workflows/                # CI workflows (e.g. test, deploy)
+  ├── .vscode/
+  │   ├── customData.json           # Custom CSS IntelliSense (e.g. FontAwesome)
+  │   ├── extensions.json           # Recommended VS Code / VSCodium extensions
+  │   ├── extensions.jsonc          # Commented version of extensions.json
+  │   └── settings.json             # Workspace settings
+  ├── netlify/
+  │   ├── edge-functions/
+  │   │   └── csp-report.js         # Receives CSP violation reports
+  │   └── netlify.toml              # Netlify configuration
+  ├── scripts/                      # General-purpose utility scripts
+  ├── src/
+  │   ├── app.html                  # Entry HTML (CSP meta, bootstrapping)
+  │   ├── hooks.client.ts           # PWA install prompt & client-side logging
+  │   ├── hooks.server.js           # Injects CSP headers and permissions policy
+  │   ├── lib/                      # Components, utilities, types, styles
+  │   │   ├── components/           # Svelte components
+  │   │   ├── data/                 # Custom data (e.g. JSON, metadata, constants)
+  │   │   └── utils/                # Helper utilities
+  │   ├── routes/                   # SvelteKit pages (+page.svelte, +server.js)
+  │   └── service-worker.js         # Custom PWA service worker
+  ├── static/                       # Public assets served at site root
+  │   ├── disableSw.js              # Service worker bypass (via ?nosw param)
+  │   ├── manifest.json             # PWA metadata
+  │   ├── robots.txt                # SEO: allow/disallow crawlers
+  │   └── sitemap.xml               # SEO: full site map
+  ├── tests/
+  │   ├── e2e/                      # Playwright end-to-end tests
+  │   ├── internal/                 # Internal audit/test helpers
+  │   │   └── auditCoverage.test.js # Warns about untested source modules
+  │   └── unit/                     # Vitest unit tests
+  ├── _redirects                    # Netlify redirect rules
+  └── package.json                  # Project manifest (scripts, deps, etc.)
 ```
 
 &nbsp;
@@ -74,8 +104,14 @@ tests/
 └── ...
 ```
 
+</section>
+
+<sub>[Back to top](#top)</sub>
+
 ---
 
+<section id="getting-started">
+
 ## 🛠 Getting Started
 
 ### 📦 Environment Setup
@@ -119,9 +155,9 @@ npm install
 > You can also use `bootstrap.local.sh` to automate the steps above and more (optional).  
 > `ENV_MODE` controls local tooling behavior — it is not used by the app runtime directly.
 
----
+&nbsp;
 
-#### 💾 Version Enforcement
+### 💾 Version Enforcement
 
 To ensure consistent environments across contributors and CI systems, this project enforces specific Node.js and npm versions via the `"engines"` field in `package.json`:
 
@@ -185,7 +221,13 @@ node -v     # Should fall within engines.node
 npm -v      # Should fall within engines.npm
 ```
 
-&nbsp;
+</section>
+
+<sub>[Back to top](#top)</sub>
+
+---
+
+<section id="configuration">
 
 ## 🛡️ Configuration
 
@@ -208,36 +250,117 @@ To re-enable nonce generation for inline scripts in the future:
 
 > 💡 The `[headers]` block in `netlify.toml` has been deprecated — all headers are now set dynamically from within SvelteKit.
 
----
+&nbsp;
 
 ### 🧭 `hooks.client.ts`
 
-This lightweight hook enhances client experience:
+Located at `src/hooks.client.ts`, this file is currently limited to handling uncaught client-side errors via the `handleError()` lifecycle hook.
+
+Client-side PWA logic (such as handling the `beforeinstallprompt` event, checking browser compatibility, and registering the service worker) has been moved to `src/lib/registerServiceWorker.js` for better modularity and testability.
 
-- Handles the `beforeinstallprompt` event to support progressive web app (PWA) install flows
-- Provides a `handleError()` hook that logs uncaught client-side errors
+> 💡 This separation ensures that error handling is isolated from PWA lifecycle logic, making both concerns easier to maintain.
 
-Located at `src/hooks.client.ts`, it is automatically used by the SvelteKit runtime during client boot.
+</section>
+
+<sub>[Back to top](#top)</sub>
 
 ---
 
-### 📣 CSP Report Handler
+<section id="sw-utilities">
+
+## ⚙️ Service Worker Utilities
+
+This project includes modular service worker management to support PWA functionality, update lifecycles, and debugging workflows.
+
+### ✅ `registerServiceWorker.js`
+
+Located at `src/lib/registerServiceWorker.js`, this module handles:
+
+- **Service worker registration** (`service-worker.js`)
+- **Update lifecycle**: prompts users when new content is available
+- **Cache hygiene**: removes unexpected caches not prefixed with `cache-`
+- **Install prompt support**: dispatches a `pwa-install-available` event for custom handling
+- **Firefox compatibility**: skips registration in Firefox during localhost development
+
+This function is typically called during client boot from `+layout.svelte` or another root-level component.
+
+> ℹ️ The service worker will not register if the `?nosw` flag is present or if `window.__DISABLE_SW__` is set (see below).
+
+&nbsp;
+
+### 🧹 `unregisterServiceWorker.js`
+
+Located at `src/lib/unregisterServiceWorker.js`, this utility allows for manual deactivation of service workers during debugging or user opt-out flows.
+
+It unregisters **all active service worker registrations** and logs the result.
+
+&nbsp;
+
+### 🚫 `disableSw.js`
+
+Located at `static/disableSw.js`, this file sets a global flag if the URL contains the `?nosw` query parameter:
+
+```js
+if (location.search.includes("nosw")) {
+  window.__DISABLE_SW__ = true;
+}
+```
+
+This flag is used by `registerServiceWorker.js` to bypass registration. It's helpful for testing environments, browser compatibility checks, or simulating first-load conditions without service worker interference.
+
+To use:
+
+```bash
+https://netwk.pro/?nosw
+```
+
+> 💡 `disableSw.js` is loaded via a `<script>` tag in `app.html` from the `static` directory. This ensures the `__DISABLE_SW__` flag is set before any service worker logic runs.
+
+&nbsp;
+
+#### 🔧 Example Usage
+
+To register the service worker conditionally, call the function from client code:
+
+```js
+import { registerServiceWorker } from "$lib/registerServiceWorker.js";
+
+registerServiceWorker();
+```
+
+You can optionally import unregisterServiceWorker() in a debug menu or settings panel to let users opt out of offline behavior.
+
+</section>
+
+<sub>[Back to top](#top)</sub>
+
+---
+
+<section id="cspreport">
+
+## 📣 CSP Report Handler
 
 To receive and inspect CSP violation reports in development or production, the repo includes a Netlify-compatible function at:
 
 ```bash
-netlify-functions/cspReport.js
+netlify/edge-functions/csp-report.js
 ```
 
-This function receives reports sent to `/functions/cspReport` and logs them to the console. You can later integrate with logging tools or alerts (e.g., via email, Slack, or SIEM ingestion).
+This Edge Function receives Content Security Policy (CSP) violation reports at `/api/csp-report` and logs relevant details to the console. High-risk violations (e.g., `script-src`, `form-action`) also trigger real-time alerts via `ntfy`. You can further integrate with logging tools, SIEM platforms, or notification systems as needed.
 
 Make sure to include the `report-uri` directive in your CSP header:
 
 ```bash
-Content-Security-Policy: ...; report-uri /.netlify/functions/cspReport;
+Content-Security-Policy: ...; report-uri /api/csp-report;
 ```
 
-&nbsp;
+</section>
+
+<sub>[Back to top](#top)</sub>
+
+---
+
+<section id="testing">
 
 ## 🧪 Testing
 
@@ -299,8 +422,14 @@ npm run test:coverage   # Collect code coverage reports
 npm run test:e2e        # Runs Playwright E2E tests (with one retry on failure)
 ```
 
+<!-- markdownlint-disable MD028 -->
+
+> The unit test suite includes a coverage audit (`auditCoverage.test.js`) that warns when source files in `src/` or `scripts/` do not have corresponding unit tests. This helps track test completeness without failing CI.
+
 > Playwright will retry failed tests once `(--retries=1)` to reduce false negatives from transient flakiness (network, render delay, etc.).
 
+<!-- markdownlint-enable MD028 -->
+
 Audit your app using Lighthouse:
 
 ```bash
@@ -332,8 +461,14 @@ You can also audit locally using Chrome DevTools → Lighthouse tab for on-the-f
 
 <!-- markdownlint-disable MD028 -->
 
+</section>
+
+<sub>[Back to top](#top)</sub>
+
 ---
 
+<section id="toolchain">
+
 ## 🛠 Recommended Toolchain
 
 To streamline development and align with project conventions, we recommend the following setup — especially for contributors without a strong existing preference.
@@ -371,8 +506,14 @@ npm run lint:fix
 npm run format:fix
 ```
 
+</section>
+
+<sub>[Back to top](#top)</sub>
+
 ---
 
+<section id="toolconfig">
+
 ## ⚙️ Tooling Configuration
 
 All linting, formatting, and version settings are defined in versioned project config files:
@@ -395,8 +536,14 @@ These are the same rules used by CI and automation, so aligning your local setup
 
 > Note: `.vscode/extensions.json` defines a minimal recommended dev stack for VSCodium / VS Code. These extensions are **optional but thoughtfully curated** to improve developer experience without introducing bloat.
 
+</section>
+
+<sub>[Back to top](#top)</sub>
+
 ---
 
+<section id="scripts">
+
 ## 📜 Available Scripts
 
 The following CLI commands are available via `npm run <script>` or `pnpm run <script>`.
@@ -412,20 +559,20 @@ The following CLI commands are available via `npm run <script>` or `pnpm run <sc
 | `build:netlify` | Build using Netlify CLI                                                  |
 | `css:bundle`    | Bundle and minify CSS                                                    |
 
----
+&nbsp;
 
 ### ✅ Pre-check / Sync
 
-| Script        | Description                                                  |
-| ------------- | ------------------------------------------------------------ |
-| `prepare`     | Run SvelteKit sync                                           |
-| `check`       | Run SvelteKit sync and type check with `svelte-check`        |
-| `check:watch` | Watch mode for type checks                                   |
-| `check:node`  | Validate Node & npm versions match package.json `engines`    |
-| `checkout`    | Full local validation: check versions, test, lint, typecheck |
-| `verify`      | Alias for `checkout`                                         |
+| Script        | Description                                                                         |
+| ------------- | ----------------------------------------------------------------------------------- |
+| `prepare`     | Run SvelteKit sync                                                                  |
+| `check`       | Run SvelteKit sync and type check with `svelte-check`                               |
+| `check:watch` | Watch mode for type checks                                                          |
+| `check:node`  | Validate Node & npm versions match package.json `engines`                           |
+| `checkout`    | Full local validation: check versions, test (incl. audit coverage), lint, typecheck |
+| `verify`      | Alias for `checkout`                                                                |
 
----
+&nbsp;
 
 ### 🧹 Cleanup & Maintenance
 
@@ -435,7 +582,7 @@ The following CLI commands are available via `npm run <script>` or `pnpm run <sc
 | `clean`   | Fully reset environment and reinstall           |
 | `upgrade` | Update all dependencies via `npm-check-updates` |
 
----
+&nbsp;
 
 <!-- markdownlint-disable MD024 -->
 
@@ -443,17 +590,17 @@ The following CLI commands are available via `npm run <script>` or `pnpm run <sc
 
 <!-- markdownlint-enable MD024 -->
 
-| Script          | Description                                            |
-| --------------- | ------------------------------------------------------ |
-| `test`          | Alias for `test:all`                                   |
-| `test:all`      | Run both client and server test suites                 |
-| `test:client`   | Run client tests with Vitest                           |
-| `test:server`   | Run server-side tests with Vitest                      |
-| `test:watch`    | Watch mode for client tests                            |
-| `test:coverage` | Collect coverage from both client and server           |
-| `test:e2e`      | Runs E2E tests with up to 1 automatic retry on failure |
+| Script          | Description                                                   |
+| --------------- | ------------------------------------------------------------- |
+| `test`          | Alias for `test:all`                                          |
+| `test:all`      | Run both client and server test suites (incl. audit coverage) |
+| `test:client`   | Run client tests with Vitest                                  |
+| `test:server`   | Run server-side tests with Vitest                             |
+| `test:watch`    | Watch mode for client tests                                   |
+| `test:coverage` | Collect coverage from both client and server                  |
+| `test:e2e`      | Runs E2E tests with up to 1 automatic retry on failure        |
 
----
+&nbsp;
 
 ### 🧼 Linting & Formatting
 
@@ -468,7 +615,7 @@ The following CLI commands are available via `npm run <script>` or `pnpm run <sc
 | `format`     | Run Prettier formatting check           |
 | `format:fix` | Auto-format code using Prettier         |
 
----
+&nbsp;
 
 ### 💡 Lighthouse / Performance
 
@@ -477,17 +624,17 @@ The following CLI commands are available via `npm run <script>` or `pnpm run <sc
 | `lhci`     | Alias for Lighthouse CI   |
 | `lhci:run` | Run Lighthouse CI autorun |
 
----
+&nbsp;
 
 ### 📋 Audits / Validation
 
-| Script          | Description                                  |
-| --------------- | -------------------------------------------- |
-| `audit:scripts` | Check for untested utility scripts           |
-| `head:flatten`  | Flatten headers for Netlify                  |
-| `head:validate` | Validate headers file against project config |
+| Script           | Description                                          |
+| ---------------- | ---------------------------------------------------- |
+| `audit:coverage` | Warn about untested modules in `src/` and `scripts/` |
+| `head:flatten`   | Flatten headers for Netlify                          |
+| `head:validate`  | Validate headers file against project config         |
 
----
+&nbsp;
 
 ### 🔄 Lifecycle Hooks
 
@@ -495,10 +642,14 @@ The following CLI commands are available via `npm run <script>` or `pnpm run <sc
 | ------------- | ----------------------------------- |
 | `postinstall` | Ensures version check after install |
 
-&nbsp;
+</section>
+
+<sub>[Back to top](#top)</sub>
 
 ---
 
+<section id="license">
+
 ## 🧾 License
 
 This project is licensed under:
@@ -509,11 +660,21 @@ This project is licensed under:
 
 Source code, branding, and visual assets are subject to reuse and distribution terms specified on our [Legal, Copyright, and Licensing page](https://netwk.pro/license).
 
-&nbsp;
+</section>
+
+<sub>[Back to top](#top)</sub>
+
+---
+
+<section id="questions">
 
 ## 🙋‍♂️Questions?
 
-Reach out via [netwk.pro/contact](https://netwk.pro/contact), open an issue on this repo, or email us directly at `contact (at) s.neteng.pro`.
+Reach out via our [Contact Form](https://netwk.pro/contact), open an issue on this repo, or email us directly at `support (at) neteng.pro`.
+
+</section>
+
+<sub>[Back to top](#top)</sub>
 
 &nbsp;
 
@@ -522,7 +683,7 @@ _Designed for professionals. Hardened for privacy. Built with intent._
 
 ---
 
-<div style="font-size: 12px; text-align: center;">
+<span style="font-size: 12px; text-align: center;">
 
 Copyright &copy; 2025  
 **[Network Pro Strategies](https://netwk.pro) (Network Pro&trade;)**
@@ -531,4 +692,6 @@ Network Pro&trade;, the shield logo, and the "Locking Down Networks&trade;" slog
 
 Licensed under **[CC BY 4.0](https://netwk.pro/license#cc-by)** and the **[GNU GPL](https://netwk.pro/license#gnu-gpl)**, as published by the [Free Software Foundation](https://www.fsf.org), either version 3 of the License, or (at your option) any later version.
 
-</div>
+</span>
+
+<!-- cspell:ignore cspreport toolconfig -->

package/cspell.json

@@ -19,6 +19,7 @@
     "homescreen",
     "Izzy",
     "lhci",
+    "lifecycles",
     "lighthouseci",
     "lighthouserc",
     "lightningcss",
@@ -35,6 +36,7 @@
     "nosniff",
     "nosw",
     "npmjs",
+    "ntfy",
     "obtainium",
     "posthog",
     "SIEM",
@@ -45,6 +47,7 @@
     "subsites",
     "Supercookie",
     "supercookies",
+    "unregisters",
     "urlcheck",
     "vcard",
     "vite",

package/netlify/edge-functions/csp-report.js

@@ -0,0 +1,151 @@
+/* ==========================================================================
+edge-functions/csp-report.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 csp-report.js
+ * @description Netlify Edge Function to handle CSP violation reports.
+ *
+ * Accepts POST requests to /api/csp-report and logs relevant CSP reports.
+ * Filters out common low-value reports (e.g., img-src) to reduce invocation
+ * cost. Alerts on high-risk violations via ntfy topic.
+ *
+ * @module netlify/edge-functions
+ * @author SunDevil311
+ * @updated 2025-05-31
+ */
+
+/**
+ * Netlify Edge Function entry point for CSP reporting.
+ *
+ * @param {Request} request - The incoming HTTP request object
+ * @param {import('@netlify/edge-functions').Context} _context - The Netlify Edge Function context (unused)
+ * @returns {Promise<Response>} HTTP Response with status 204 or 405
+ */
+export default async (request, _context) => {
+  if (request.method !== "POST") {
+    return new Response("Method Not Allowed", { status: 405 });
+  }
+
+  try {
+    const body = await request.json();
+    const report = body["csp-report"];
+
+    // Ignore if report is missing or malformed
+    if (!report || typeof report !== "object") {
+      return new Response(null, { status: 204 });
+    }
+
+    const violated = report["violated-directive"] ?? "";
+    const blockedUri = report["blocked-uri"] ?? "";
+
+    // Filter: Skip img-src violations and empty URIs
+    const ignored = [
+      violated.startsWith("img-src"),
+      blockedUri === "",
+      blockedUri === "about",
+      blockedUri.startsWith("chrome-extension://"),
+      blockedUri.startsWith("moz-extension://"),
+    ].some(Boolean);
+
+    if (ignored) {
+      return new Response(null, { status: 204 });
+    }
+
+    // Send alert for high-risk directives
+    await sendToNtfy(violated, blockedUri, report);
+
+    // Log useful violations
+    console.log("[CSP-Edge] Violation:", {
+      directive: violated,
+      uri: blockedUri,
+      referrer: report["referrer"],
+      source: report["source-file"],
+      line: report["line-number"],
+    });
+  } catch (err) {
+    console.warn("[CSP-Edge] Failed to parse CSP report:", err.message);
+  }
+
+  return new Response(null, { status: 204 });
+};
+
+const recentViolations = new Map();
+const VIOLATION_TTL_MS = 60_000;
+
+/**
+ * Sends a high-priority alert to your ntfy topic for high-risk CSP violations.
+ * Applies rate-limiting to avoid sending duplicate alerts within 60 seconds.
+ *
+ * @param {string} violated - The violated CSP directive
+ * @param {string} blockedUri - The URI that was blocked
+ * @param {Record<string, any>} report - The full CSP report object
+ */
+async function sendToNtfy(violated, blockedUri, report) {
+  const highRiskDirectives = [
+    "script-src",
+    "form-action",
+    "frame-ancestors",
+    "base-uri",
+  ];
+
+  const directiveKey = violated.split(" ")[0]; // strip fallback values or sources
+  const isHighRisk = highRiskDirectives.includes(directiveKey);
+  console.log(`[CSP-Edge] Checking directive: ${directiveKey}`);
+  if (!isHighRisk) return;
+
+  const key = `${violated}|${blockedUri}`;
+  const now = Date.now();
+
+  // Skip and log if violation was reported recently
+  if (
+    recentViolations.has(key) &&
+    now - recentViolations.get(key) < VIOLATION_TTL_MS
+  ) {
+    console.log(`[CSP-Edge] Skipped duplicate alert for ${key}`);
+    return;
+  }
+
+  // Record the current timestamp
+  recentViolations.set(key, now);
+
+  // Cleanup old entries (memory-safe for low volume)
+  for (const [k, t] of recentViolations.entries()) {
+    if (now - t > VIOLATION_TTL_MS) {
+      recentViolations.delete(k);
+    }
+  }
+
+  const topicUrl = "https://ntfy.neteng.pro/csp-alerts";
+
+  const message = [
+    `🚨 CSP Violation Detected`,
+    `Directive: ${violated}`,
+    `Blocked URI: ${blockedUri}`,
+    `Referrer: ${report.referrer || "N/A"}`,
+    `Source: ${report["source-file"] || "N/A"}`,
+    `Line: ${report["line-number"] || "N/A"}`,
+  ].join("\n");
+
+  await fetch(topicUrl, {
+    method: "POST",
+    headers: {
+      "Content-Type": "text/plain",
+      "X-Title": "High-Risk CSP Violation",
+      "X-Priority": "5",
+    },
+    body: message,
+  });
+}
+
+/**
+ * Configuration block for the Edge Function.
+ * This sets the endpoint route to /api/csp-report
+ */
+export const config = {
+  path: "/api/csp-report",
+};

package/netlify.toml

@@ -11,9 +11,9 @@
   targetPort = 5173
   port = 8888
 
-[functions."*"]
-  node_bundler = "esbuild"
-  included_files = ["netlify-functions/**"]
+[[edge_functions]]
+  path = "/api/csp-report"
+  function = "csp-report"
 
 [[plugins]]
   package = "netlify-plugin-submit-sitemap"