@networkpro/web 1.5.2 → 1.6.0

package/CODE_OF_CONDUCT.md

@@ -1,6 +1,7 @@
 <!-- =========================================================================
 CODE_OF_CONDUCT.md
 
+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.
 ========================================================================== -->

package/LICENSE.md

@@ -1,47 +1,10 @@
 <!-- =========================================================================
 LICENSE.md
 
+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.
-========================================================================== -->
-
-<!--
-Copyright © 2025 Network Pro Strategies (Network Pro)
-
----
-
-I. Creative Commons Attribution 4.0 International
-
-Network Pro (the "Licensed Material") is licensed under Creative Commons Attribution 4.0 International ("CC BY 4.0"). To view a copy of this license, visit https://creativecommons.org/licenses/by/4.0/.
-
-Per the terms of the License, you are free to distribute, remix, adapt, and build upon the Licensed Material for any purpose, even commercially. You must give appropriate credit, provide a link to the License, and indicate if changes were made.
-
-The Licensor offers the Licensed Material as-is and as-available, and makes no representations or warranties of any kind concerning the Licensed Material, whether express, implied, statutory, or other. This includes, without limitation, warranties of title, merchantability, fitness for a particular purpose, non-infringement, absence of latent or other defects, accuracy, or the presence or absence of errors, whether or not known or discoverable.
-
-Permissions beyond the scope of this License—or instead of those permitted by this License—may be available as further defined within this document.
-
-  SPDX Reference: https://spdx.org/licenses/CC-BY-4.0.html
-  Canonical URL: https://creativecommons.org/licenses/by/4.0/
-
----
-
-II. GNU General Public License
-
-Network Pro is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License ("GNU GPL") as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
-
-This material is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
-
-See the GNU General Public License for more details.
-
-  SPDX Reference: https://spdx.org/licenses/GPL-3.0-or-later.html
-  Canonical URL: https://www.gnu.org/licenses/gpl-3.0.html
-
----
-
-Author: Scott Lopez
-Email: <contact@neteng.pro>
-Web: <https://bio.neteng.pro>
--->
+====================================================================== -->
 
 [SPDX-License-Identifier](https://spdx.dev/learn/handling-license-info/):
 `CC-BY-4.0 OR GPL-3.0-or-later`
@@ -53,6 +16,9 @@ Web: <https://bio.neteng.pro>
 **Network Pro Strategies**  
 **Effective Date:** May 18, 2025
 
+**Official Version Notice**  
+This document is provided for convenience only. In the event of any discrepancy, the authoritative version is the one published at [https://netwk.pro](https://netwk.pro).
+
 &nbsp;
 
 <!-- markdownlint-disable MD001 -->

package/README.md

@@ -1,7 +1,15 @@
-# 🌐 Network Pro — Web Presence
+<!-- =====================================================================
+README.md
 
-> **Locking Down Networks, Unlocking Confidence™**  
-> _Security, Networking, Privacy — Network Pro™_
+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.
+====================================================================== -->
+
+# 🌐 Network Pro&trade; — Web Presence
+
+> **Locking Down Networks, Unlocking Confidence&trade;**  
+> _Security, Networking, Privacy — Network Pro&trade;_
 
 &nbsp;
 
@@ -11,29 +19,38 @@
 
 ## 🚀 Project Overview
 
-This is the official web presence for **[Network Pro Strategies](https://netwk.pro/about)**, a privacy-forward consultancy specializing in network engineering, information security, and public advocacy focused on cybersecurity and digital privacy.
+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.
 
 Built with [SvelteKit](https://kit.svelte.dev/) and deployed via [Netlify](https://www.netlify.com/).  
-Blog and documentation subsites built with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) and deployed via [GitHub Pages](https://pages.github.com/).  
+[Blog](https://github.com/netwk-pro/blog) and [documentation](https://github.com/netwk-pro/docs) subsites built with [Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) and deployed via [GitHub Pages](https://pages.github.com/).
+
 All infrastructure and data flows are designed with **maximum transparency, self-hosting, and user privacy** in mind.
 
 ### 📁 Repository Structure
 
 ```bash
 .
+├── .github/workflows     # CI workflows and automation
+├── .vscode/              # Recommended VS Code settings, extensions
+├── netlify-functions/
+│   └── cspReport.js     # Serverless function to receive and log CSP violation reports
+├── scripts/              # Utility scripts
 ├── src/
-│   ├── lib/             # Reusable components, styles, utilities
-│   ├── routes/          # SvelteKit routes (+page.svelte, +page.server.js)
-│   ├── hooks.client.ts  # Client-only lifecycle hooks (e.g., SW control)
-│   └── app.html         # SvelteKit entry HTML with CSP/meta/bootstrap
-├── tests/               # Vitest test suites
-├── public/              # Static assets served at root
-├── netlify.toml         # Netlify configuration
-├── .github/             # CI workflows and automation
+│   ├── 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
+├── tests/
+│   ├── e2e/              # End-to-end Playwright tests
+│   └── unit/             # Vite unit tests
+├── netlify.toml          # Netlify configuration
 └── ...
 ```
 
-&nbsp;
+---
 
 ## 🛠 Getting Started
 
@@ -52,27 +69,287 @@ 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.
+> `ENV_MODE` is used for tooling and workflows — not by SvelteKit itself.  
+> Use `VITE_`-prefixed env variables for runtime values.
 
 &nbsp;
 
-### 📐 Node.js Version Management
+### 🧰 Local Setup Scripts
+
+To streamline onboarding and enforce project conventions, you may use the optional helper scripts:
+
+| File/Script                        | Description                                                                       |
+| ---------------------------------- | --------------------------------------------------------------------------------- |
+| `.env.template`                    | Template for local environment variables                                          |
+| `scripts/checkNode.js`             | Validates your Node.js and npm versions                                           |
+| `scripts/bootstrap.local.sh` (TBD) | Interactive setup for local configuration and tooling                             |
+| `.vscode/`                         | Editor recommendations compatible with [VSCodium](https://vscodium.com) / VS Code |
+
+To get started quickly:
+
+```bash
+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`:
+
+```json
+"engines": {
+  "node": ">=22.0.0 <25",
+  "npm": ">=11.0.0 <12"
+}
+```
+
+Version compliance is **softly enforced** after installation via a postinstall lifecycle hook:
+
+```bash
+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`)_**
+
+```javascript
+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:
+
+```bash
+node -v     # Should fall within engines.node
+npm -v      # Should fall within engines.npm
+```
+
+&nbsp;
+
+## 🛡️ 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:
+
+- Content Security Policy (CSP) with support for relaxed directives (inline scripts allowed)
+- Permissions Policy to explicitly disable unnecessary browser APIs
+- X-Content-Type-Options, X-Frame-Options, and Referrer-Policy headers
+
+> 💡 The CSP nonce feature has been disabled. Inline scripts are now allowed through the policy using the "script-src 'self' 'unsafe-inline'" directive. If you wish to use nonces in the future, you can re-enable them by uncommenting the relevant sections in hooks.server.js and modifying your inline <script> tags.
+
+To re-enable nonce generation for inline scripts in the future:
+
+1. Uncomment the nonce generation and injection logic in hooks.server.js.
+2. Add nonce="**cspNonce**" to inline <script> blocks in app.html or route templates.
+
+> 💡 The `[headers]` block in `netlify.toml` has been deprecated — all headers are now set dynamically from within SvelteKit.
+
+---
+
+### 🧭 `hooks.client.ts`
+
+This lightweight hook enhances client experience:
+
+- Handles the `beforeinstallprompt` event to support progressive web app (PWA) install flows
+- Provides a `handleError()` hook that logs uncaught client-side errors
+
+Located at `src/hooks.client.ts`, it is automatically used by the SvelteKit runtime during client boot.
+
+---
+
+### 📣 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/csp-report.js
+```
 
-This repo uses .nvmrc and .node-version for version consistency with tools like:
+This function receives reports sent to `/functions/csp-report` and logs them to the console. You can later integrate with logging tools or alerts (e.g., via email, Slack, or SIEM ingestion).
 
-- nvm
-- asdf
-- Volta
-- GitHub Actions
+Make sure to include the `report-uri` directive in your CSP header:
 
 ```bash
-node -v     # Should match "engines" in package.json
-npm -v
+Content-Security-Policy: ...; report-uri /.netlify/functions/csp-report;
 ```
 
 &nbsp;
 
+## 🧪 Testing
+
+This project uses a mix of automated performance, accessibility, and end-to-end testing tools to maintain quality across environments and deployments.
+
+| Tool                                                         | Purpose                                              | Usage Context       |
+| ------------------------------------------------------------ | ---------------------------------------------------- | ------------------- |
+| [`@playwright/test`](https://playwright.dev/docs/test-intro) | End-to-end testing framework with browser automation | Local + CI          |
+| [`@lhci/cli`](https://github.com/GoogleChrome/lighthouse-ci) | Lighthouse CI — automated performance audits         | CI (optional local) |
+| [`lighthouse`](https://github.com/GoogleChrome/lighthouse)   | Manual/scripted Lighthouse runs via CLI              | Local (global)      |
+
+> **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.
+
+<!-- markdownlint-disable MD028 -->
+
+> CI uses Chrome for Lighthouse audits. For local experimentation, you may run Lighthouse manually using [Brave](https://brave.com), which can reveal differences related to privacy features or tracking protection.
+
+<!-- markdownlint-enable MD028 -->
+
+&nbsp;
+
+### Testing Configuration Files
+
+| File                   | Description                                                              | Usage Context |
+| ---------------------- | ------------------------------------------------------------------------ | ------------- |
+| `playwright.config.js` | Configures Playwright test environment (browsers, timeouts, base URL)    | Local + CI    |
+| `.lighthouserc.cjs`    | Lighthouse CI config for defining audit targets, budgets, and assertions | CI            |
+
+&nbsp;
+
+### Running Tests
+
+Local testing via Playwright:
+
+```bash
+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
+```
+
+Audit your app using Lighthouse:
+
+```bash
+# Run Lighthouse CI (via @lhci/cli) using the current build
+npm run lhci:run
+```
+
+Manual auditing with Lighthouse (e.g., via Brave or Chrome):
+
+```bash
+# 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.
+
+<!-- markdownlint-disable MD028 -->
+
+> To trace the exact Chrome version and audit timestamp used in CI:
+>
+> ```bash
+> cat .lighthouseci/chrome-version.txt
+> ```
+
+<!-- markdownlint-disable MD028 -->
+
+---
+
+## 🛠 Recommended Toolchain
+
+To streamline development and align with project conventions, we recommend the following setup — especially for contributors without a strong existing preference.
+
+| Tool                                                                     | Description                                               |
+| ------------------------------------------------------------------------ | --------------------------------------------------------- |
+| **[VSCodium](https://vscodium.com/)**                                    | Fully open-source alternative to VS Code (telemetry-free) |
+| **[Prettier](https://prettier.io/)**                                     | Code formatter for JS, TS, Svelte, Markdown, etc.         |
+| **[ESLint](https://eslint.org/)**                                        | JavaScript/TypeScript linter with Svelte support          |
+| **[Stylelint](https://stylelint.io/)**                                   | Linting for CSS, SCSS, and inline styles in Svelte        |
+| **[markdownlint](https://github.com/DavidAnson/markdownlint)**           | Markdown style checker and linter                         |
+| **[markdownlint-cli2](https://github.com/DavidAnson/markdownlint-cli2)** | Config-based CLI linter for Markdown                      |
+| **[EditorConfig](https://editorconfig.org/)**                            | Consistent line endings, spacing, and indentation         |
+| **[Volta](https://volta.sh) / [nvm](https://github.com/nvm-sh/nvm)**     | Node.js version manager for consistent tooling            |
+
+> 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:
+
+```bash
+npm install --include=dev
+```
+
+Run all format and lint checks:
+
+```bash
+npm run lint:all
+npm run format
+```
+
+To auto-fix issues:
+
+```bash
+npm run lint:fix
+npm run format:fix
+```
+
+---
+
+## ⚙️ Tooling Configuration
+
+All linting, formatting, and version settings are defined in versioned project config files:
+
+| File                      | Purpose                                                    |
+| ------------------------- | ---------------------------------------------------------- |
+| `.prettierrc`             | Prettier formatting rules                                  |
+| `.prettierignore`         | Files that should be ignored by Prettier                   |
+| `eslint.config.mjs`       | ESLint config with SvelteKit support                       |
+| `stylelint.config.js`     | CSS/SASS/Svelte style rules                                |
+| `.stylelintignore`        | Files that should be ignored by Stylelint                  |
+| `.editorconfig`           | Base indentation and line ending settings                  |
+| `.nvmrc`, `.node-version` | Node.js version constraints for `nvm`, `asdf`, and `Volta` |
+| `.vscode/extensions.json` | Suggested extensions for VSCodium                          |
+| `.vscode/settings.json`   | Default workspace settings (non-binding)                   |
+| `.vscode/customData.json` | Custom CSS data for FontAwesome classes                    |
+| `cspell.json`             | Custom words and exclusions for spell checking             |
+
+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
@@ -81,13 +358,14 @@ The following CLI commands are available via `npm run <script>` or `pnpm run <sc
 
 ### 🔄 Development
 
-| Script          | Description                        |
-| --------------- | ---------------------------------- |
-| `dev`           | Start development server with Vite |
-| `preview`       | Preview production build locally   |
-| `build`         | Build the project with Vite        |
-| `build:netlify` | Build using Netlify CLI            |
-| `css:bundle`    | Bundle and minify CSS              |
+| Script          | Description                                                              |
+| --------------- | ------------------------------------------------------------------------ |
+| `dev`           | Start development server with Vite                                       |
+| `preview`       | Preview production build locally                                         |
+| `build`         | Build the project with Vite                                              |
+| `dev:netlify`   | Start local dev server using Netlify Dev (emulates serverless + headers) |
+| `build:netlify` | Build using Netlify CLI                                                  |
+| `css:bundle`    | Bundle and minify CSS                                                    |
 
 ---
 
@@ -98,7 +376,7 @@ The following CLI commands are available via `npm run <script>` or `pnpm run <sc
 | `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`    |
+| `check:node`  | Validate Node & npm versions match package.json `engines`    |
 | `checkout`    | Full local validation: check versions, test, lint, typecheck |
 | `verify`      | Alias for `checkout`                                         |
 
@@ -114,8 +392,12 @@ The following CLI commands are available via `npm run <script>` or `pnpm run <sc
 
 ---
 
+<!-- markdownlint-disable MD024 -->
+
 ### 🧪 Testing
 
+<!-- markdownlint-enable MD024 -->
+
 | Script          | Description                                  |
 | --------------- | -------------------------------------------- |
 | `test`          | Alias for `test:all`                         |
@@ -144,12 +426,10 @@ The following CLI commands are available via `npm run <script>` or `pnpm run <sc
 
 ### 💡 Lighthouse / Performance
 
-| Script             | Description                                     |
-| ------------------ | ----------------------------------------------- |
-| `lhci`             | Alias for Lighthouse CI                         |
-| `lighthouse`       | Run local Lighthouse test and launch viewer     |
-| `lighthouse:local` | Build site, preview, and run Lighthouse locally |
-| `lhci:run`         | Run Lighthouse CI autorun                       |
+| Script     | Description               |
+| ---------- | ------------------------- |
+| `lhci`     | Alias for Lighthouse CI   |
+| `lhci:run` | Run Lighthouse CI autorun |
 
 ---
 
@@ -185,7 +465,7 @@ Source code, branding, and visual assets are subject to reuse and distribution t
 
 &nbsp;
 
-## 🙋‍♂️ 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`.
 

package/cspell.json

@@ -0,0 +1,65 @@
+{
+  "version": "0.2",
+  "language": "en",
+  "words": [
+    "acode",
+    "autorun",
+    "beforeinstallprompt",
+    "bootentry",
+    "Embedder",
+    "Ente",
+    "esbuild",
+    "foss",
+    "geolocation",
+    "homescreen",
+    "lhci",
+    "lighthouseci",
+    "lighthouserc",
+    "lightningcss",
+    "linksheet",
+    "Maricopa",
+    "mdsvex",
+    "neteng",
+    "NETPRO",
+    "netwk",
+    "networkpro",
+    "Nextcloud",
+    "noopener",
+    "noreferrer",
+    "nosniff",
+    "nosw",
+    "obtainium",
+    "SIEM",
+    "stylelintignore",
+    "Subsite",
+    "subsites",
+    "urlcheck",
+    "vcard",
+    "vite",
+    "vitest",
+    "webfonts"
+  ],
+  "ignorePaths": [
+    ".gitignore",
+    ".gitattributes",
+    "static/sitemap.xml",
+    "static/robots.txt",
+    "src/lib/styles/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/.svelte-kit/**",
+    "**/.vite/**",
+    "**/coverage/**",
+    "**/playwright-report/**"
+  ],
+  "ignoreWords": [],
+  "enableFiletypes": [
+    "javascript",
+    "typescript",
+    "json",
+    "markdown",
+    "html",
+    "svelte"
+  ],
+  "useGitignore": true
+}

package/eslint.config.mjs

@@ -1,9 +1,10 @@
 /* ==========================================================================
 eslint.config.mjs
 
+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.
-========================================================================== */
+========================================================================= */
 
 import js from "@eslint/js"; // Provides ESLint core rules and recommended config
 import eslintConfigPrettier from "eslint-config-prettier"; // Prettier config to disable conflicting ESLint rules

package/jsconfig.json

@@ -18,7 +18,8 @@ This file is part of Network Pro.
     "strict": true,
     "moduleResolution": "bundler"
   },
-  "exclude": ["vite.config.js"] // Exclude the config file if needed
+  "exclude": ["vite.config.js"], // Exclude the config file if needed
+  "include": ["src", "src/global.d.ts", "src/service-worker.js"]
 
   // Path aliases are handled by https://svelte.dev/docs/kit/configuration#alias
   // except $lib which is handled by https://svelte.dev/docs/kit/configuration#files

package/netlify-functions/cspReport.js

@@ -0,0 +1,68 @@
+/* ==========================================================================
+netlify-functions/cspReport.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.
+========================================================================== */
+
+import nodemailer from "nodemailer";
+
+/**
+ * Netlify Function: CSP violation report handler
+ *
+ * @param {import('@netlify/functions').HandlerEvent} event - Incoming Netlify request
+ * @returns {Promise<import('@netlify/functions').HandlerResponse>} - Netlify-compatible HTTP response
+ */
+export async function handler(event) {
+  try {
+    if (event.httpMethod !== "POST") {
+      return {
+        statusCode: 405,
+        body: "Method Not Allowed",
+      };
+    }
+
+    if (!event.body) {
+      return {
+        statusCode: 400,
+        body: "No body provided",
+      };
+    }
+
+    /** @type {Record<string, any>} */
+    const report = JSON.parse(event.body);
+    const violation = report["csp-report"] || report;
+
+    const shouldSendEmail =
+      process.env.MAIL_ENABLED !== "false" && process.env.NODE_ENV !== "test";
+
+    if (shouldSendEmail) {
+      const transporter = nodemailer.createTransport({
+        host: process.env.SMTP_HOST,
+        port: 465,
+        secure: true,
+        auth: {
+          user: process.env.SMTP_USER,
+          pass: process.env.SMTP_PASS,
+        },
+      });
+
+      await transporter.sendMail({
+        from: `"CSP Reporter" <${process.env.SMTP_USER}>`,
+        to: process.env.NOTIFY_EMAIL,
+        subject: "🚨 CSP Violation Detected",
+        text: JSON.stringify(violation, null, 2),
+      });
+    }
+
+    return {
+      statusCode: 204,
+    };
+  } catch (error) {
+    return {
+      statusCode: 400,
+      body: `Invalid JSON: ${error instanceof Error ? error.message : "Unknown error"}`,
+    };
+  }
+}