al_email_protect 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 45eeb1de42070ef099e8c97dac39d19b382a24176bb366cae134999a44a8f563
+  data.tar.gz: '08d20381439a1b9f8338fa52b62a784fa021b7a6a00823867379d01cec833631'
+SHA512:
+  metadata.gz: f035867e44a23b79ea54a50e63fbb6370a284d469fdeb35eabd95daa8b78324c4ce072bd20d2a1f3d1fbd8626f8700636e79256bd3024de7fa1613c9c0d12c9e
+  data.tar.gz: cc611264e9d7fb0d5dcb0350b2cd93f50b38ae9bad99510715afb760b917b29bdabb880198e2a9291486d6f47b80353c1a6b4a3e93726f4146944cd0a25c566d

data/CHANGELOG.md

@@ -0,0 +1,10 @@
+# Changelog
+
+## 1.0.0 — 2026-08-02
+
+- Initial release of `al_email_protect`, implementing the email obfuscation proposed in
+  [alshedivat/al-folio#3540](https://github.com/alshedivat/al-folio/issues/3540) (source PR
+  [#3532](https://github.com/alshedivat/al-folio/pull/3532)).
+- Addresses are split server-side and never appear as `user@host` or `mailto:` in the built HTML.
+- `{% al_email_protect_link %}` tag, `al_email_obfuscate` filter, and `_styles` / `_scripts` asset tags.
+- Vanilla-JS runtime (no jQuery), with a clipboard fallback for non-secure contexts and keyboard activation.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) al-folio maintainers
+
+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.

data/README.md

@@ -0,0 +1,81 @@
+# al_email_protect
+
+Email obfuscation for [al-folio](https://github.com/alshedivat/al-folio) v1.x. Implements the plugin proposed in
+[al-folio#3540](https://github.com/alshedivat/al-folio/issues/3540).
+
+## What it does
+
+When `protect_email` is on, addresses are **never emitted as addresses**. The HTML contains no `user@host` string and no
+`mailto:` target; the two halves are carried in separate attributes and rejoined by the browser when a visitor clicks.
+
+This is the part that matters. An implementation that ships the plaintext address and rewrites it after
+`DOMContentLoaded` protects nobody — harvesters parse markup, they do not run your JavaScript. The obfuscation here
+happens at build time, in Liquid.
+
+Clicking an address copies it to the clipboard and shows a brief toast, rather than opening a mail client.
+
+## Install
+
+Add to your `Gemfile`:
+
+```ruby
+gem "al_email_protect", "= 1.0.0"
+```
+
+and to `_config.yml` — **both lists, or the plugin is inert**:
+
+```yaml
+plugins:
+  - al_email_protect
+
+protect_email: true # off by default
+```
+
+## Usage
+
+The al-folio theme calls the asset tags for you. In your own layouts:
+
+```liquid
+{% al_email_protect_link site.data.socials.email %}
+```
+
+Renders a click-to-copy element when enabled, and a plain `mailto:` link when disabled — so it is safe to call
+unconditionally.
+
+For contexts that show an address as text rather than a link (a CV contact block, say):
+
+```liquid
+{{ cv.email | al_email_obfuscate }}
+```
+
+gives `someone [at] example [dot] com` when enabled, and the address unchanged when not.
+
+## Behaviour worth knowing
+
+- **Splits on the last `@`.** A quoted local part may legally contain one (RFC 5321).
+- **Falls back rather than mangling.** A value that is not a usable address (`someone@localhost`, no dot in the domain)
+  renders as an ordinary `mailto:` link. Publishing a broken contact address is worse than publishing an unprotected one.
+- **Clipboard needs a secure context.** `navigator.clipboard` is undefined over plain HTTP, so the runtime falls back to
+  a hidden-textarea copy, and if even that fails it shows the address so the visitor can copy it by hand.
+- **Keyboard accessible.** The element is a focusable `<a>`; Enter and Space both activate it, and the toast is announced
+  via `role="status"`.
+
+## Scope
+
+This gem owns obfuscation of addresses it is asked to render. It does not scan arbitrary page text for things that look
+like addresses — that is unreliable and would corrupt legitimate content.
+
+`al_folio_cv` renders CV contact details; wiring `al_email_obfuscate` into those layouts is a change in that gem, not
+this one. See [`docs/BOUNDARIES.md`](https://github.com/alshedivat/al-folio/blob/main/docs/BOUNDARIES.md).
+
+## Development
+
+```bash
+bundle install
+bundle exec rake test
+npm ci && npm run lint:prettier
+```
+
+## License
+
+MIT

data/lib/al_email_protect/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module AlEmailProtect
+  VERSION = "1.0.0"
+end

data/lib/al_email_protect.rb

@@ -0,0 +1,163 @@
+# frozen_string_literal: true
+
+require "cgi"
+require "jekyll"
+require "liquid"
+require_relative "al_email_protect/version"
+
+# Keeps published email addresses away from harvesters.
+#
+# The scraper-facing half is deliberately server-side: when the feature is on,
+# no `mailto:` string and no `user@host` string is present in the HTML at all.
+# Address harvesters read markup, not JavaScript, so an approach that ships the
+# plaintext and merely rewrites it on DOMContentLoaded protects nobody. The
+# address is emitted as two halves and only rejoined in the browser.
+module AlEmailProtect
+  PLUGIN_ROOT = File.expand_path("..", __dir__)
+  # Jekyll writes a StaticFile to <dest>/<dir>/<name>, where <dir> is relative
+  # to the base below. That base must be lib/, not the gem root, or assets land
+  # at /lib/assets/... while every tag in this file points at /assets/... .
+  LIB_ROOT = __dir__
+  ASSETS_ROOT = File.join(LIB_ROOT, "assets")
+
+  class PluginStaticFile < Jekyll::StaticFile; end
+
+  module_function
+
+  def enabled?(site)
+    return false unless site
+
+    site.config["protect_email"] == true
+  end
+
+  # Splits "someone@example.ac.uk" into ["someone", "example.ac.uk"].
+  #
+  # Splits on the LAST "@" because the local part of an address may legally
+  # contain one when quoted (RFC 5321), and getting this backwards would emit a
+  # broken address rather than a protected one. Returns nil for anything not
+  # usable as an address, so callers can fall back to rendering it verbatim
+  # instead of silently publishing a mangled contact.
+  def split_address(value)
+    address = value.to_s.strip
+    return nil if address.empty?
+
+    local, _, domain = address.rpartition("@")
+    return nil if local.empty? || domain.empty?
+    return nil unless domain.include?(".")
+
+    [local, domain]
+  end
+
+  # "someone [at] example [dot] com", for places that show an address as text
+  # rather than as a link (CV contact blocks, for instance).
+  def obfuscate_text(value)
+    parts = split_address(value)
+    return value.to_s unless parts
+
+    local, domain = parts
+    "#{local} [at] #{domain.gsub(".", " [dot] ")}"
+  end
+
+  def escape(value)
+    CGI.escapeHTML(value.to_s)
+  end
+
+  # Builds "example [dot] com" as alternating styled spans.
+  def domain_markup(domain)
+    separator = %(<span class="al-email-sep"> [dot] </span>)
+    domain.split(".").map { |label| %(<span class="al-email-text">#{escape(label)}</span>) }.join(separator)
+  end
+
+  # [relative_dir, filename] for everything this gem publishes. Exposed so the
+  # destination path can be asserted without booting a full Jekyll site.
+  def asset_entries
+    Dir.glob(File.join(ASSETS_ROOT, "**", "*")).sort.reject { |p| File.directory?(p) }.map do |source_path|
+      [File.dirname(source_path).sub("#{LIB_ROOT}/", ""), File.basename(source_path)]
+    end
+  end
+
+  # Copies the runtime into the built site. Skipped entirely when the feature is
+  # off, so a site that never enables it does not carry the asset.
+  class AssetsGenerator < Jekyll::Generator
+    safe true
+    priority :low
+
+    def generate(site)
+      return unless AlEmailProtect.enabled?(site)
+
+      Dir.glob(File.join(ASSETS_ROOT, "**", "*")).sort.each do |source_path|
+        next if File.directory?(source_path)
+
+        relative_dir = File.dirname(source_path).sub("#{LIB_ROOT}/", "")
+        site.static_files << PluginStaticFile.new(site, LIB_ROOT, relative_dir, File.basename(source_path))
+      end
+    end
+  end
+
+  class StylesTag < Liquid::Tag
+    def render(context)
+      site = context.registers[:site]
+      return "" unless AlEmailProtect.enabled?(site)
+
+      baseurl = site.config["baseurl"] || ""
+      %(<link rel="stylesheet" href="#{baseurl}/assets/al_email_protect/css/email-protect.css">\n)
+    end
+  end
+
+  class ScriptsTag < Liquid::Tag
+    def render(context)
+      site = context.registers[:site]
+      return "" unless AlEmailProtect.enabled?(site)
+
+      baseurl = site.config["baseurl"] || ""
+      %(<script defer src="#{baseurl}/assets/al_email_protect/js/email-protect.js"></script>\n)
+    end
+  end
+
+  # {% al_email_protect_link site.data.socials.email %}
+  #
+  # Emits a click-to-copy element carrying the address in halves. Falls back to
+  # a plain mailto: link when the feature is off, so a layout can call this
+  # unconditionally and get correct markup either way.
+  class LinkTag < Liquid::Tag
+    def initialize(tag_name, markup, options)
+      super
+      @markup = markup.strip
+    end
+
+    def render(context)
+      value = context[@markup]
+      value = @markup.gsub(/\A["']|["']\z/, "") if value.nil?
+      return "" if value.to_s.strip.empty?
+
+      parts = AlEmailProtect.split_address(value)
+      unless AlEmailProtect.enabled?(context.registers[:site]) && parts
+        escaped = AlEmailProtect.escape(value)
+        return %(<a href="mailto:#{escaped}">#{escaped}</a>)
+      end
+
+      local, domain = parts
+      [
+        %(<a href="#" class="al-email-protect" data-eu="#{AlEmailProtect.escape(local)}" data-ed="#{AlEmailProtect.escape(domain)}">),
+        %(<span class="al-email-text">#{AlEmailProtect.escape(local)}</span>),
+        %(<span class="al-email-sep"> [at] </span>),
+        AlEmailProtect.domain_markup(domain),
+        %(</a>),
+      ].join
+    end
+  end
+
+  # {{ cv.email | al_email_obfuscate }}
+  module Filters
+    def al_email_obfuscate(value)
+      return value.to_s unless AlEmailProtect.enabled?(@context.registers[:site])
+
+      AlEmailProtect.obfuscate_text(value)
+    end
+  end
+end
+
+Liquid::Template.register_tag("al_email_protect_styles", AlEmailProtect::StylesTag)
+Liquid::Template.register_tag("al_email_protect_scripts", AlEmailProtect::ScriptsTag)
+Liquid::Template.register_tag("al_email_protect_link", AlEmailProtect::LinkTag)
+Liquid::Template.register_filter(AlEmailProtect::Filters)

data/lib/assets/al_email_protect/css/email-protect.css

@@ -0,0 +1,48 @@
+/* Styling for addresses rendered by al_email_protect.
+   Plain CSS with al-folio's CSS custom properties rather than Sass: _sass/ is
+   gem-owned by al_folio_core and a plugin must not add to the theme's build. */
+
+.al-email-protect {
+  cursor: pointer;
+  text-decoration: none;
+}
+
+.al-email-protect:hover .al-email-text {
+  text-decoration: underline;
+}
+
+.al-email-text {
+  color: var(--global-theme-color, inherit);
+}
+
+.al-email-sep {
+  color: var(--global-text-color, inherit);
+  /* The " [at] " / " [dot] " markers are a rendering of the address, not extra
+     words to read out; the surrounding link already carries the full value. */
+  user-select: none;
+}
+
+#al-email-copied-toast {
+  position: fixed;
+  bottom: 20px;
+  left: 50%;
+  transform: translateX(-50%) translateY(80px);
+  background: var(--global-theme-color, rgba(0, 0, 0, 0.85));
+  color: #fff;
+  padding: 8px 20px;
+  border-radius: 6px;
+  font-size: 0.875rem;
+  z-index: 9999;
+  transition: transform 0.25s ease;
+  pointer-events: none;
+}
+
+#al-email-copied-toast.is-visible {
+  transform: translateX(-50%) translateY(0);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  #al-email-copied-toast {
+    transition: none;
+  }
+}

data/lib/assets/al_email_protect/js/email-protect.js

@@ -0,0 +1,121 @@
+// Rejoins addresses that al_email_protect emitted in halves, and copies them to
+// the clipboard on click. Vanilla by design: al-folio v1 dropped jQuery from the
+// core runtime, and a plugin that reintroduced it would break sites that do not
+// load the bootstrap-compat shim.
+(function () {
+  "use strict";
+
+  var TOAST_ID = "al-email-copied-toast";
+  var TOAST_MS = 1800;
+  var toastTimer = null;
+
+  function showToast(message) {
+    var toast = document.getElementById(TOAST_ID);
+    if (!toast) {
+      toast = document.createElement("div");
+      toast.id = TOAST_ID;
+      // Announce politely so screen readers report the copy without stealing focus.
+      toast.setAttribute("role", "status");
+      toast.setAttribute("aria-live", "polite");
+      document.body.appendChild(toast);
+    }
+    toast.textContent = message;
+    toast.classList.add("is-visible");
+
+    // Restart the timer rather than stacking them, or a second click hides the
+    // toast early while it is still animating in from the first.
+    if (toastTimer) {
+      clearTimeout(toastTimer);
+    }
+    toastTimer = setTimeout(function () {
+      toast.classList.remove("is-visible");
+      toastTimer = null;
+    }, TOAST_MS);
+  }
+
+  function legacyCopy(text) {
+    var field = document.createElement("textarea");
+    field.value = text;
+    field.setAttribute("readonly", "");
+    field.style.cssText = "position:fixed;top:0;left:0;opacity:0";
+    document.body.appendChild(field);
+    field.select();
+    var copied = false;
+    try {
+      copied = document.execCommand("copy");
+    } catch (err) {
+      copied = false;
+    }
+    document.body.removeChild(field);
+    return copied;
+  }
+
+  function addressOf(element) {
+    var local = element.getAttribute("data-eu");
+    var domain = element.getAttribute("data-ed");
+    if (!local || !domain) {
+      return null;
+    }
+    return local + "@" + domain;
+  }
+
+  function copy(element) {
+    var address = addressOf(element);
+    if (!address) {
+      return;
+    }
+
+    // navigator.clipboard is undefined on any page not served over a secure
+    // context, which includes plain-HTTP self-hosting and some previews. Fall
+    // back rather than throwing, so the click still does something useful.
+    if (navigator.clipboard && window.isSecureContext) {
+      navigator.clipboard.writeText(address).then(
+        function () {
+          showToast("Email copied to clipboard");
+        },
+        function () {
+          // Permission can still be refused; surface the address so the visitor
+          // can copy it by hand instead of getting silence.
+          showToast(address);
+        }
+      );
+      return;
+    }
+
+    showToast(legacyCopy(address) ? "Email copied to clipboard" : address);
+  }
+
+  // Delegated so addresses rendered after load (search palette, lazy includes)
+  // are handled without re-binding.
+  function onActivate(event) {
+    var element = event.target.closest ? event.target.closest(".al-email-protect") : null;
+    if (!element) {
+      return;
+    }
+    event.preventDefault();
+    copy(element);
+  }
+
+  function ready() {
+    document.addEventListener("click", onActivate);
+
+    // The element is an <a href="#">, so it is already focusable and reachable
+    // by keyboard, but Enter fires click while Space does not. Handle Space too.
+    document.addEventListener("keydown", function (event) {
+      if (event.key !== " " && event.key !== "Spacebar") {
+        return;
+      }
+      var element = event.target.closest ? event.target.closest(".al-email-protect") : null;
+      if (element) {
+        event.preventDefault();
+        copy(element);
+      }
+    });
+  }
+
+  if (document.readyState === "loading") {
+    document.addEventListener("DOMContentLoaded", ready);
+  } else {
+    ready();
+  }
+})();

metadata

@@ -0,0 +1,142 @@
+--- !ruby/object:Gem::Specification
+name: al_email_protect
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- al-folio maintainers
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-08-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: jekyll
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '3.9'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: liquid
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '6.0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '3.0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+description: 'Hides mailto: addresses from scrapers and copies them to the clipboard
+  on click instead.'
+email:
+- maintainers@al-folio.dev
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/al_email_protect.rb
+- lib/al_email_protect/version.rb
+- lib/assets/al_email_protect/css/email-protect.css
+- lib/assets/al_email_protect/js/email-protect.js
+homepage: https://github.com/al-org-dev/al-email-protect
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/al-org-dev/al-email-protect
+  source_code_uri: https://github.com/al-org-dev/al-email-protect
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '2.7'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Email obfuscation plugin for al-folio v1.x
+test_files: []