astro-noemail 0.1.0

package/LICENSE.md

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Velohost
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,184 @@
+# astro-noemail
+
+**Build-time email address obfuscation for Astro**
+
+`astro-noemail` is a tiny, static-first Astro integration that protects email addresses from basic scrapers by converting them into HTML entities **at build time**.
+
+There is:
+- no JavaScript at runtime
+- no hydration
+- no DOM mutation in the browser
+- no adapter dependency
+
+Just safer HTML.
+
+---
+
+## Why this exists
+
+Email addresses published in plain HTML are routinely harvested by simple bots.
+
+Most solutions rely on:
+- JavaScript obfuscation
+- runtime DOM rewriting
+- client-side decoding
+
+These approaches:
+- increase page weight
+- break with JS disabled
+- add unnecessary complexity
+
+`astro-noemail` solves this once, **during the build**, and produces static, cache-safe output.
+
+---
+
+## What it does
+
+On `astro build`, the plugin:
+
+- scans generated `.html` files in the output directory
+- finds plain-text email addresses
+- replaces them with numeric HTML entities
+
+Example:
+
+```html
+info@velohost.co.uk
+```
+
+becomes:
+
+```html
+info@velohost.co.uk
+```
+
+Browsers render this normally, but basic scrapers do not.
+
+---
+
+## What it does NOT do
+
+This plugin deliberately does **not**:
+
+- run at runtime
+- inject JavaScript
+- parse the DOM
+- modify Astro source files
+- touch files outside the build output
+- expose environment variables
+- interfere with adapters or rendering
+
+It operates **only** on final HTML output.
+
+---
+
+## Safety guarantees
+
+The obfuscation logic is hardened to:
+
+- skip `<script>`, `<style>`, and `<noscript>` blocks
+- avoid double-encoding existing HTML entities
+- only mutate files when a change is required
+- never crash or fail a build
+
+Astro-specific HTML rewriting is respected.
+
+---
+
+## Installation
+
+```bash
+npm install astro-noemail
+```
+
+---
+
+## Usage
+
+Add the integration to your Astro config:
+
+```js
+import { defineConfig } from "astro/config";
+import astroNoEmail from "astro-noemail";
+
+export default defineConfig({
+  integrations: [
+    astroNoEmail()
+  ]
+});
+```
+
+That’s it.
+
+No configuration is required.
+
+---
+
+## Optional configuration
+
+### Disable the plugin
+
+```js
+astroNoEmail({
+  enabled: false
+})
+```
+
+This can be useful for local testing or special builds.
+
+---
+
+## Mailto links
+
+Email addresses inside visible text **and** `mailto:` links are obfuscated.
+
+The links continue to function normally in browsers.
+
+---
+
+## `<noscript>` behaviour
+
+Astro may rewrite `<noscript>` content during compilation.
+
+If an email address is moved outside of a `<noscript>` block by Astro itself, it will be treated as normal HTML text and obfuscated.
+
+This behaviour is intentional and considered safe.
+
+---
+
+## CDN & caching
+
+Because all changes are static:
+
+- output can be cached aggressively
+- the plugin works behind any CDN
+- Cloudflare, Netlify, Vercel, S3, and similar platforms are fully supported
+
+---
+
+## Failure behaviour
+
+If a file cannot be processed:
+
+- the error is logged
+- the build continues
+- the site is not broken
+
+The plugin must never block a deployment.
+
+---
+
+## License
+
+MIT
+
+---
+
+## Author
+
+Built and maintained by **Velohost**
+
+Website: https://velohost.co.uk/
+
+Project page:
+https://velohost.co.uk/plugins/astro-noemail/

package/dist/index.d.ts

@@ -0,0 +1,10 @@
+import type { AstroIntegration } from "astro";
+type NoEmailOptions = {
+    /**
+     * Enable or disable the plugin.
+     * Default: true
+     */
+    enabled?: boolean;
+};
+export default function astroNoEmail(options?: NoEmailOptions): AstroIntegration;
+export {};

package/dist/index.js

@@ -0,0 +1,62 @@
+import fs from "node:fs";
+import path from "node:path";
+export default function astroNoEmail(options = {}) {
+    const { enabled = true } = options;
+    return {
+        name: "astro-noemail",
+        hooks: {
+            "astro:build:done"({ dir }) {
+                if (!enabled)
+                    return;
+                const outDir = new URL(dir).pathname;
+                if (!outDir || !fs.existsSync(outDir))
+                    return;
+                walk(outDir, filePath => {
+                    if (!filePath.endsWith(".html"))
+                        return;
+                    const original = fs.readFileSync(filePath, "utf-8");
+                    const updated = obfuscateEmailsSafely(original);
+                    if (updated !== original) {
+                        fs.writeFileSync(filePath, updated, "utf-8");
+                    }
+                });
+                console.log("[astro-noemail] email obfuscation complete");
+            }
+        }
+    };
+}
+/* ---------------------------------------------
+   Helpers
+--------------------------------------------- */
+function walk(dir, cb) {
+    for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const fullPath = path.join(dir, entry.name);
+        entry.isDirectory() ? walk(fullPath, cb) : cb(fullPath);
+    }
+}
+/**
+ * Safely obfuscate emails:
+ * - skips script/style/noscript
+ * - avoids double-encoding
+ */
+function obfuscateEmailsSafely(html) {
+    const BLOCK_TAGS = /<(script|style|noscript)[^>]*>[\s\S]*?<\/\1>/gi;
+    const emailRegex = /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/gi;
+    const blocks = [];
+    // Temporarily remove unsafe blocks
+    const stripped = html.replace(BLOCK_TAGS, match => {
+        blocks.push(match);
+        return `__ASTRO_NOEMAIL_BLOCK_${blocks.length - 1}__`;
+    });
+    const processed = stripped.replace(emailRegex, match => {
+        // Prevent double-encoding
+        if (match.includes("&#"))
+            return match;
+        return match
+            .split("")
+            .map(char => `&#${char.charCodeAt(0)};`)
+            .join("");
+    });
+    // Restore blocks untouched
+    return processed.replace(/__ASTRO_NOEMAIL_BLOCK_(\d+)__/g, (_, i) => blocks[Number(i)]);
+}

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "astro-noemail",
+  "version": "0.1.0",
+  "description": "Prevents email address harvesting by obfuscating emails in generated Astro HTML at build time",
+  "homepage": "https://velohost.co.uk/plugins/astro-noemail/",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/velohost/astro-noemail.git"
+  },
+  "bugs": {
+    "url": "https://github.com/velohost/astro-noemail/issues"
+  },
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "withastro",
+    "astro-integration",
+    "security",
+    "email",
+    "spam",
+    "scraping",
+    "static-site"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc"
+  },
+  "peerDependencies": {
+    "astro": "^4.0.0 || ^5.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.0.3",
+    "typescript": "^5.0.0"
+  }
+}