🚀 Project Overview

This GitHub repository powers the official web presence of Network Pro Strategies — 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.

Built with SvelteKit and deployed via Netlify.
Blog and documentation subsites built with Material for MkDocs and deployed via GitHub Pages.

All infrastructure and data flows are designed with maximum transparency, self-hosting, and user privacy in mind.

📝 Changelog

For a history of changes to the Network Pro™ Web Presence, see the CHANGELOG. All notable updates are documented there.

This project follows the principles of Keep a Changelog, though formatting and versioning may occasionally vary.

📁 Repository Structure

  .
  ├── .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
  ├── scripts/                      # General-purpose utility scripts
  ├── src/
  │   ├── 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)
  │   ├── app.html                  # Entry HTML (CSP meta, bootstrapping)
  │   ├── hooks.client.ts           # Client-side error handling
  │   ├── hooks.server.js           # Injects CSP headers and permissions policy
  │   └── service-worker.js         # Custom PWA service worker
  ├── static/                       # Public assets served at site root
  │   ├── pgp/
  │   ├── 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
  ├── CHANGELOG.md                  # Chronological record of notable project changes
  ├── netlify.toml                  # Netlify configuration
  ├── package.json                  # Project manifest (scripts, deps, etc.)
  └── ...

🔐 static/pgp/ Directory Structure

This directory contains public PGP key files and their corresponding QR codes.

static/
├── pgp/
│   ├── contact@s.neteng.pro.asc       # Public key for secure email
│   ├── pgp-contact.png                # QR code (PNG) for secure email key
│   ├── pgp-contact.webp               # Optimized WebP version of the QR code
│   ├── pgp-security.png               # QR code (PNG) for security contact key
│   ├── pgp-security.webp              # WebP version of the security QR code
│   ├── pgp-support.png                # QR code (PNG) for support key
│   ├── pgp-support.webp               # WebP version of the support QR code
│   ├── security@s.neteng.pro.asc      # Public key for security contact
│   ├── support@neteng.pro.asc         # Public key for general support
└── ...

• .asc files are excluded from service worker precaching but served directly via the /pgp/[key] route.
• QR code images are served statically by the /pgp route using <picture> elements.
• WebP versions are also used in the /pgp route, while the /about route imports dynamic equivalents from src/lib/img/qr.
• This route does not use fallback rendering; only explicitly defined files are available and expected to resolve.
• A dynamic [key]/+server.js handler under src/routes/pgp/ serves the .asc files with appropriate Content-Type and download headers.

E2E Test Structure

End-to-end tests are located in tests/e2e/ and organized by feature or route:

tests/
├── e2e/
│   ├── app.spec.js       # Desktop and mobile route tests
│   ├── mobile.spec.js    # Mobile-specific assertions
│   └── shared/
│       └── helpers.js    # Shared test utilities (e.g., getFooter, setDesktopView, setMobileView)
└── ...

🛠 Getting Started

📦 Environment Setup

git clone https://github.com/netwk-pro/netwk-pro.github.io.git
cd netwk-pro.github.io
cp .env.template .env
npm install

Edit .env to configure your environment mode:

ENV_MODE=dev  # Options: dev, test, ci, preview, prod

ENV_MODE is used for tooling and workflows — not by SvelteKit itself.
Use VITE_-prefixed env variables for runtime values.

🧰 Local Setup Scripts

To streamline onboarding and enforce project conventions, you may use the optional helper scripts:

To get started quickly:

cp .env.template .env
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.

💾 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:

"engines": {
  "node": ">=22.0.0 <25",
  "npm": ">=11.0.0 <12"
}

Version compliance is softly enforced after installation via a postinstall lifecycle hook:

npm run check:node

This script runs scripts/checkNode.js, which compares your current Node.js and npm versions against the required ranges. During the install phase, it will log warnings for out-of-range versions but allow installation to continue. In all other contexts (manual runs, CI workflows, etc.), it will fail with a descriptive error if the versions are out of spec.

Node Version Check (snippet from scripts/checkNode.js)

const semver = require('semver');
const { engines } = require('../package.json');

const requiredNode = engines.node;
const requiredNpm = engines.npm;
const isPostInstall = process.env.npm_lifecycle_event === 'postinstall';

let hasError = false;

if (!semver.satisfies(process.version, requiredNode)) {
  const msg = `Node.js ${process.version} does not satisfy required range: ${requiredNode}`;
  isPostInstall ? console.warn(`⚠️  ${msg}`) : console.error(`❌ ${msg}`);
  if (!isPostInstall) hasError = true;
}

const npmVersion = require('child_process')
  .execSync('npm -v')
  .toString()
  .trim();

if (!semver.satisfies(npmVersion, requiredNpm)) {
  const msg = `npm ${npmVersion} does not satisfy required range: ${requiredNpm}`;
  isPostInstall ? console.warn(`⚠️  ${msg}`) : console.error(`❌ ${msg}`);
  if (!isPostInstall) hasError = true;
}

if (!hasError) {
  console.log('✅ Node and npm versions are valid.');
} else {
  process.exit(1);
}

For full compatibility, .nvmrc and .node-version files are provided to work seamlessly with version managers like nvm, asdf, and Volta. This ensures consistent environments across local development, CI pipelines, and deployment targets.

To manually verify your environment:

node -v     # Should fall within engines.node
npm -v      # Should fall within engines.npm

🛡️ Configuration

This project includes custom runtime configuration files for enhancing security, error handling, and PWA functionality. These modules are used by the framework during server- and client-side lifecycle hooks.

🔐 hooks.server.js

Located at src/hooks.server.js, this file is responsible for injecting dynamic security headers. It includes:

• A Content Security Policy (CSP) configured with relaxed directives to permit inline scripts and styles ('unsafe-inline')
• A Permissions Policy to explicitly disable unnecessary browser APIs
• Standard security headers such as X-Content-Type-Options, X-Frame-Options, and Referrer-Policy

ℹ️ A stricter CSP (excluding 'unsafe-inline') was attempted but reverted due to framework-level and third-party script compatibility issues. The current policy allows inline scripts to ensure stability across SvelteKit and analytics features such as PostHog.

Future Improvements

To implement a strict nonce-based CSP in the future:

1. Add nonce generation and injection logic in hooks.server.js
2. Update all inline <script> tags (e.g. in app.html) to include nonce="__cspNonce__"
3. Ensure any analytics libraries or dynamic scripts support nonced or external loading

Note: Strict CSP adoption may require restructuring third-party integrations and deeper framework coordination.

💡 The [headers] block in netlify.toml has been deprecated — all headers are now set dynamically from within SvelteKit.

🧭 hooks.client.ts

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.

💡 This separation ensures that error handling is isolated from PWA lifecycle logic, making both concerns easier to maintain.

⚙️ 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).

🧹 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.

🚫 disableSw.js

Located at static/disableSw.js, this file sets a global flag if the URL contains the ?nosw query parameter:

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:

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.

🔧 Example Usage

To register the service worker conditionally, call the function from client code:

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.

📣 CSP Report Handler

To receive and inspect CSP violation reports in development or production, the repo includes a Netlify-compatible Edge Function at:

netlify/edge-functions/csp-report.js

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:

Content-Security-Policy: ...; report-uri /api/csp-report;

🧪 Testing

This project uses a mix of automated performance, accessibility, and end-to-end testing tools to maintain quality across environments and deployments.

Note: lighthouse is intended to be installed globally (npm i -g lighthouse) or run via the lighthouse npm script, which uses the locally installed binary if available. You can also run Lighthouse through Chrome DevTools manually if preferred.

CI uses Chrome for Lighthouse audits. For local experimentation, you may run Lighthouse manually using Brave, which can reveal differences related to privacy features or tracking protection.

Testing Configuration Files

E2E Setup

Playwright is included in devDependencies and installed automatically with:

npm install

To install browser dependencies (required once):

npx playwright install

This downloads the browser binaries (Chromium, Firefox, WebKit) used for testing. You only need to run this once per machine or after a fresh clone.

Running Tests

Local testing via Vitest and Playwright:

npm run test:client     # Run client-side unit tests with Vitest
npm run test:server     # Run server-side unit tests with Vitest
npm run test:all        # Run full test suite
npm run test:watch      # Watch mode for client tests
npm run test:coverage   # Collect code coverage reports
npm run test:e2e        # Runs Playwright E2E tests (with one retry on failure)

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.).

Audit your app using Lighthouse:

# Run Lighthouse CI (via @lhci/cli) using the current build
npm run lhci:run

Manual auditing with Lighthouse (e.g., via Brave or Chrome):

# Install globally (if not already installed)
npm install -g lighthouse

# Run Lighthouse manually against a deployed site
lighthouse https://netwk.pro --view

You can also audit locally using Chrome DevTools → Lighthouse tab for on-the-fly testing and preview reports.

The repo uses @lhci/cli for CI-based audits. It is installed as a dev dependency and does not require a global install.

To trace the exact Chrome version and audit timestamp used in CI:

cat .lighthouseci/chrome-version.txt

🛠 Recommended Toolchain

To streamline development and align with project conventions, we recommend the following setup — especially for contributors without a strong existing preference.

The .vscode/ folder includes editor recommendations compatible with VSCodium. These are non-enforced and optional, but align with our formatter, linter, and language server configs.

Install dev tooling:

npm install --include=dev

Run all format and lint checks:

npm run lint:all
npm run format

To auto-fix issues:

npm run lint:fix
npm run format:fix

⚙️ Tooling Configuration

All linting, formatting, and version settings are defined in versioned project config files:

These are the same rules used by CI and automation, so aligning your local setup avoids surprises later.

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.

📜 Available Scripts

The following CLI commands are available via npm run <script> or pnpm run <script>.

🔄 Development

✅ Pre-check / Sync

🧹 Cleanup & Maintenance

🧪 Testing

🧼 Linting & Formatting

💡 Lighthouse / Performance

📋 Audits / Validation

🔄 Lifecycle Hooks

🧾 License

This project is licensed under:

• Creative Commons BY 4.0

• Or optionally, GNU GPL v3 or later

Source code, branding, and visual assets are subject to reuse and distribution terms specified on our Legal, Copyright, and Licensing page.

🙋‍♂️Questions?

Reach out via our Contact Form, open an issue on this repo, or email us directly at support (at) neteng.pro.