astro-mail-obfuscation

Astro Mail Obfuscation:

An Astro integration that effectively obfuscates email addresses in the source code by hiding them during the static build using XOR obfuscation. The email addresses are only revealed on the client side through JavaScript.

The XOR obfuscation method is effective against basic bots that scour the internet for email addresses, as many of these bots do not execute JavaScript (often for efficiency reasons).

Lightweight and easy to use:

This integration allows Astro developers to automate the obfuscation of email addresses, and in its current version, it is stable and production-ready.

Recommended Installation:

Installation with Astro CLI:

npx astro add astro-mail-obfuscation

Done!

Manual Installation:

1. Install with a Node package manager:

npm install astro-mail-obfuscation

2. Adjust your Astro configuration:

// astro.config.mjs
import mailObfuscation from "astro-mail-obfuscation";
export default defineConfig({
  integrations: [mailObfuscation()],
});

Done!

Usage:

By default, the integration does not automatically obfuscate email addresses. Email addresses you want to obfuscate must be marked with the attribute data-obfuscation="1".

Example:

// Within .astro files
<a href="mailto:mail1@..." data-obfuscation="1">mail1@...</a>
<a href="mailto:mail2@..." data-obfuscation="1">Contact us!</a>

The number 1 currently holds no special function, but it ensures that XOR is used as the default obfuscation method. The attribute is required for the obfuscation to work.

After running npm run build and opening the website in the browser, you'll notice that the email addresses no longer appear in the source code. They are only visible if JavaScript is enabled.

Configuration:

Once installed, the integration works out-of-the-box, and no adjustments are required. However, there are two optional configuration options:

fallbackText:

You can customize the text shown when JavaScript is disabled.

userKey:

The XOR key is automatically generated by default. It can be manually set but this is not recommended.

// astro.config.mjs
export default defineConfig({
  integrations: [
    astroMailObfuscation({
      fallbackText: "...", // Default: "Please enable JavaScript!"
      // userKey: "A1B3C2..." (Optional, changes not recommended!)
    }),
  ],
});

Comparison:

Here is a comparison of the source code with and without the integration:

Without integration:

<a href="mailto:mail@...">mail@...</a>

The email address is visible in the source code and easily accessible to bots.

With integration:

<a data-obfuscation="1">
  <noscript>Please enable JavaScript!</noscript>
  <span data-...="5b09c..." data-...="12d9A..."></span>
</a>

The email address is no longer visible in the source code, making it difficult for bots to extract it.

Obfuscation Technique:

This integration uses an XOR-based obfuscation technique during the build process. Email addresses marked with data-obfuscation="1" are obfuscated both in the link and the HTML content. A client-side JavaScript script then decodes the content and restores it in the browser, with the decryption key stored as a meta tag in the HTML.

Notes:

This integration is not intended to protect against targeted attacks. However, it provides an effective layer of protection against most email-harvesting bots that do not execute JavaScript.