abqari 1.1.0

data/lib/abqari/folio.rb

@@ -0,0 +1,195 @@
+# frozen_string_literal: true
+
+require 'net/http'
+require 'json'
+require 'openssl'
+require 'yaml'
+require 'fileutils'
+require 'set'
+
+module Abqari
+  # Folio integration. Folio (foliobooks.app) is a publishing/storefront app
+  # that exposes a public read-only JSON API for embedding book metadata on
+  # author websites. This class fetches that data at build time and stashes
+  # it in `site.data` keyed by slug, so layouts can render books / bundles /
+  # series without hitting Folio at runtime — and the visitor never makes a
+  # request to Folio either.
+  #
+  # API endpoints used:
+  #   GET /api/v1/authors/:slug/publications.json
+  #   GET /api/v1/authors/:slug/bundles.json
+  #   GET /api/v1/authors/:slug/series.json
+  #
+  # Cache-first design (matches the Jekyll plugin in apps/memoirs):
+  #   1. Fresh build, network OK     → 200 → write cache → use it
+  #   2. Subsequent build, no change → 304 → use cache
+  #   3. Folio briefly unreachable   → use cache, log warning
+  #   4. First build, no network     → empty data; layouts fall back to front matter
+  #
+  # Cache files live in `vendor/folio/` (gitignored) so each CI runner
+  # rebuilds its own cache and there's no version-control churn.
+  class Folio
+    OPEN_TIMEOUT = 5
+    READ_TIMEOUT = 10
+    # 8 MB is enormously generous for Folio's JSON shape — a prolific
+    # author with hundreds of titles plus full metadata still fits well
+    # under 1 MB. The cap exists so a compromised or misconfigured
+    # upstream can't exhaust the CI runner's memory.
+    MAX_RESPONSE_BYTES = 8 * 1024 * 1024
+    USER_AGENT = "abqari-folio-fetcher/#{Abqari::VERSION}"
+
+    def initialize(site)
+      @site = site
+      @cfg  = site.config['folio'] || {}
+    end
+
+    def enabled?
+      base_url && author_slug
+    end
+
+    def base_url
+      @cfg['base_url']
+    end
+
+    def author_slug
+      @cfg['author_slug']
+    end
+
+    def config
+      @cfg
+    end
+
+    def cache_dir
+      # Folio cache is site-specific (different sites pull different
+      # publications), so it lives under the site root.
+      File.join(@site.site_root, 'vendor', 'folio')
+    end
+
+    # Fetches publications + bundles, derives series, populates site.data.
+    # Called from Site#build before page rendering so layouts can read
+    # site.data['folio_publications'] etc. when they render.
+    #
+    # Slug filtering. An author may have multiple imprints under one Folio
+    # account (e.g. fiction + non-fiction) but want a given site to show
+    # only some. Configure either of:
+    #
+    #   folio:
+    #     include_slugs: [memoirs-of-an-assassin, the-russia-assignment]
+    #     exclude_slugs: [some-other-book]
+    #
+    # `include_slugs` (when set) wins — only those publications survive,
+    # and only the bundles/series that reference them are kept. Otherwise
+    # `exclude_slugs` removes the listed publications. Both default to
+    # empty (all publications kept) so existing sites are unaffected.
+    def fetch
+      return unless enabled?
+
+      FileUtils.mkdir_p(cache_dir)
+
+      pubs    = filter_publications(fetch_endpoint('publications'))
+      bundles = filter_bundles(fetch_endpoint('bundles'), pubs)
+      series  = filter_series(fetch_endpoint('series'), pubs)
+
+      @site.data['folio_publications'] = index_by_slug(pubs)
+      @site.data['folio_bundles']      = index_by_slug(bundles)
+      @site.data['folio_series']       = index_by_slug(series)
+
+      pubs_count    = @site.data['folio_publications'].size
+      bundles_count = @site.data['folio_bundles'].size
+      series_count  = @site.data['folio_series'].size
+      Log.info "Folio: loaded #{pubs_count} publication(s), #{bundles_count} bundle(s), #{series_count} series"
+    end
+
+    private
+
+    # Apply include/exclude slug filters to the fetched publications list.
+    # `include_slugs` (when present) is treated as the only-keep set;
+    # `exclude_slugs` removes named slugs. Both arrays of strings.
+    def filter_publications(pubs)
+      include = Array(config['include_slugs']).map(&:to_s)
+      exclude = Array(config['exclude_slugs']).map(&:to_s)
+
+      pubs = pubs.select { |p| include.include?(p['slug'].to_s) } if include.any?
+      pubs = pubs.reject { |p| exclude.include?(p['slug'].to_s) } if exclude.any?
+      pubs
+    end
+
+    # Drop bundles whose `publications` array would be empty after filtering
+    # (otherwise we ship empty-bundle pages). Bundles that retain at least
+    # one publication keep all their original publications array — we
+    # don't surgically rewrite the bundle's contents.
+    def filter_bundles(bundles, kept_pubs)
+      kept_slugs = kept_pubs.map { |p| p['slug'].to_s }.to_set
+      bundles.select do |b|
+        Array(b['publications']).any? { |p| kept_slugs.include?(p['slug'].to_s) }
+      end
+    end
+
+    # Drop series with zero remaining publications.
+    def filter_series(series_list, kept_pubs)
+      kept_slugs = kept_pubs.map { |p| p['slug'].to_s }.to_set
+      series_list.select do |s|
+        Array(s['publications']).any? { |p| kept_slugs.include?(p['slug'].to_s) }
+      end
+    end
+
+    # Endpoint name → list-payload key mapping (matches Folio's API response shape):
+    ENDPOINTS = {
+      'publications' => 'publications',
+      'bundles'      => 'bundles',
+      'series'       => 'series'
+    }.freeze
+
+    def fetch_endpoint(name)
+      cache_path = File.join(cache_dir, "#{name}.yml")
+      etag_path  = File.join(cache_dir, "etag-#{name}")
+      cached     = File.exist?(cache_path) ? (YAML.safe_load_file(cache_path, permitted_classes: Abqari::YAML_PERMITTED_CLASSES) || {}) : {}
+      etag       = File.exist?(etag_path) ? File.read(etag_path).strip : nil
+
+      uri = URI("#{base_url.sub(%r{/\z}, '')}/api/v1/authors/#{author_slug}/#{name}.json")
+      headers = { 'Accept' => 'application/json', 'User-Agent' => USER_AGENT }
+      headers['If-None-Match'] = etag if etag
+
+      # HttpSafe streams the body, caps it at MAX_RESPONSE_BYTES, and
+      # applies timeouts. TooLargeError bubbles to the rescue below so
+      # we fall back to cached data rather than crashing the build.
+      res = HttpSafe.get(uri,
+                         headers: headers,
+                         max_bytes: MAX_RESPONSE_BYTES,
+                         open_timeout: OPEN_TIMEOUT,
+                         read_timeout: READ_TIMEOUT)
+
+      case res.code
+      when '304'
+        cached[ENDPOINTS[name]] || []
+      when '200'
+        body = JSON.parse(res.body)
+        items = body[ENDPOINTS[name]] || []
+        File.write(cache_path, { ENDPOINTS[name] => items }.to_yaml)
+        File.write(etag_path, res['etag'].to_s) if res['etag']
+        items
+      else
+        Log.warn "Folio: unexpected HTTP #{res.code} from /#{name} — using cached data"
+        cached[ENDPOINTS[name]] || []
+      end
+    # Narrowed rescue list: the expected failure modes for a Folio
+    # fetch are network (timeouts, DNS, TCP/TLS), an oversized
+    # response, malformed JSON, or filesystem failure writing the
+    # cache. Anything else (a Ruby bug, a programming error) should
+    # surface so we don't silently mask it as "Folio unreachable."
+    # Backtrace logged at debug so `ABQARI_LOG=debug` surfaces the
+    # full stack when triaging upstream issues.
+    rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNRESET, Errno::ECONNREFUSED,
+           Errno::EHOSTUNREACH, Errno::ENETUNREACH, SocketError, IOError,
+           OpenSSL::SSL::SSLError, HttpSafe::TooLargeError,
+           JSON::ParserError, Psych::SyntaxError, SystemCallError => e
+      Log.warn "Folio: fetch /#{name} failed (#{e.class}: #{e.message}) — using cached data"
+      e.backtrace&.first(5)&.each { |line| Log.debug "  #{line}" }
+      cached[ENDPOINTS[name]] || []
+    end
+
+    def index_by_slug(items)
+      items.each_with_object({}) { |item, h| h[item['slug']] = item if item['slug'] }
+    end
+  end
+end

data/lib/abqari/font_pipeline.rb

@@ -0,0 +1,104 @@
+# frozen_string_literal: true
+
+require 'uri'
+require 'fileutils'
+
+module Abqari
+  class FontPipeline
+    GOOGLE_CSS_API = 'https://fonts.googleapis.com/css2'
+    USER_AGENT = 'Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 ' \
+                 '(KHTML, like Gecko) Chrome/120.0.0.0 Safari/537.36'
+
+    # Timeouts and per-response cap. CSS responses are <10 KB and woff2
+    # files <500 KB typically; 8 MB is far above worst-case and exists so
+    # a misbehaving upstream can't hang the build or fill memory.
+    OPEN_TIMEOUT       = 5
+    READ_TIMEOUT       = 10
+    MAX_RESPONSE_BYTES = 8 * 1024 * 1024
+
+    def initialize(site)
+      @site = site
+      # Font cache is site-specific — populated from the site's own
+      # `fonts:` config.
+      @cache_dir = File.join(@site.site_root, 'vendor', 'fonts')
+    end
+
+    def fetch
+      fonts = Array(@site.config['fonts'])
+      if fonts.empty?
+        Log.info 'No fonts configured. Add a `fonts:` array to config/site.yml.'
+        return
+      end
+
+      FileUtils.mkdir_p(@cache_dir)
+      generated = fonts.map { |font| download_font(font) }
+      File.write(File.join(@cache_dir, 'fonts.css'), generated.join("\n\n"))
+      Log.info "Fetched #{fonts.size} font family/families → vendor/fonts/"
+    end
+
+    private
+
+    def download_font(font)
+      family = font['family'] || raise(ArgumentError, "Font config missing 'family'")
+      weights = Array(font['weights'] || [400])
+      style = font['style'] || 'normal'
+
+      css = fetch_css(family, weights, style)
+      rewrite_and_download(css)
+    end
+
+    def fetch_css(family, weights, style)
+      family_param = "#{family.gsub(' ', '+')}:#{weight_spec(weights, style)}"
+      uri = URI("#{GOOGLE_CSS_API}?family=#{family_param}&display=swap")
+
+      response = http_get(uri)
+      response.body
+    end
+
+    # Build the family axis spec for the Google Fonts CSS API.
+    #
+    # Normal: `wght@300;400;700`            — one weight per entry
+    # Italic: `ital,wght@1,300;1,400;1,700` — each (ital, weight) tuple on
+    # its own, separated by `;`. Google rejects `ital,wght@1,300;400;700`
+    # with a 400 Bad Request because every entry past the first must
+    # carry its own ital flag.
+    def weight_spec(weights, style)
+      sorted = weights.sort
+      if style == 'italic'
+        "ital,wght@#{sorted.map { |w| "1,#{w}" }.join(';')}"
+      else
+        "wght@#{sorted.join(';')}"
+      end
+    end
+
+    def rewrite_and_download(css)
+      css.gsub(%r{url\((https://fonts\.gstatic\.com/[^)]+\.woff2)\)}) do
+        url = ::Regexp.last_match(1)
+        filename = File.basename(URI(url).path)
+        dest = File.join(@cache_dir, filename)
+
+        download(url, dest) unless File.exist?(dest)
+
+        "url(/assets/fonts/#{filename})"
+      end
+    end
+
+    def download(url, dest)
+      response = http_get(URI(url))
+      File.binwrite(dest, response.body)
+    end
+
+    def http_get(uri)
+      response = HttpSafe.get(uri,
+                              headers: { 'User-Agent' => USER_AGENT },
+                              max_bytes: MAX_RESPONSE_BYTES,
+                              open_timeout: OPEN_TIMEOUT,
+                              read_timeout: READ_TIMEOUT)
+      unless response.success?
+        raise "Fetch failed for #{uri}: #{response.code} #{response.message}"
+      end
+
+      response
+    end
+  end
+end

data/lib/abqari/headers_file.rb

@@ -0,0 +1,324 @@
+# frozen_string_literal: true
+
+require 'uri'
+
+require_relative 'theme_bootstrap'
+require_relative 'plausible_script'
+
+module Abqari
+  class HeadersFile
+    # The CSP is built per-build based on which optional features are
+    # configured (Plausible analytics, etc.). The base policy is strict:
+    # 'self' only, with the inline theme-bootstrap script pinned by SHA256
+    # so we don't need 'unsafe-inline'. Each opt-in feature extends the
+    # policy minimally — Plausible adds plausible.io to script-src and
+    # connect-src plus the inline init script's hash, and that's it.
+    #
+    # To allow an origin the engine doesn't model, add it to `csp:` in
+    # config/site.yml — additive, so everything computed here survives.
+    # `media:` does the same for off-origin audio / video.
+    #
+    # Override the whole thing by setting `headers:` in config/site.yml
+    # — that disables this dynamic build entirely and ships your structure
+    # verbatim. Reach for it only when you need to weaken a hardening
+    # directive or use a non-http scheme; `csp:` covers adding origins
+    # without losing the pinned script hashes.
+    BASE_HEADERS = {
+      'X-Content-Type-Options'    => 'nosniff',
+      'Referrer-Policy'           => 'strict-origin-when-cross-origin',
+      'Permissions-Policy'        => 'camera=(), microphone=(), geolocation=(), interest-cohort=()',
+      'Strict-Transport-Security' => 'max-age=31536000; includeSubDomains'
+    }.freeze
+
+    def initialize(site)
+      @site = site
+    end
+
+    def write
+      File.write(File.join(@site.output_dir, '_headers'), build)
+    end
+
+    private
+
+    def build
+      # User override wins outright — no merging.
+      if (custom = @site.config['headers'])
+        return custom.map { |path, hdrs| section(path, hdrs) }.join("\n\n") + "\n"
+      end
+
+      sections = [
+        section('/*',        BASE_HEADERS.merge('Content-Security-Policy' => csp_policy)),
+        section('/assets/*', { 'Cache-Control' => 'public, max-age=31536000, immutable' })
+      ]
+      sections.join("\n\n") + "\n"
+    end
+
+    def section(path, hdrs)
+      lines = [path.to_s]
+      hdrs.each { |k, v| lines << "  #{k}: #{v}" }
+      lines.join("\n")
+    end
+
+    # Build the CSP from a structured representation so opt-in features
+    # can extend it cleanly. Returns the serialized policy string.
+    #
+    # Static-site defence in depth:
+    #   - `object-src 'none'`  — never load <object>/<embed>/<applet>.
+    #     A static site has no legitimate reason to embed plugins; the
+    #     directive blocks an attacker who somehow lands HTML on the
+    #     site from pulling in a Flash/PDF/etc.
+    #   - `form-action 'self'` — `<form action="https://evil.com">`
+    #     becomes a no-op. Abqari emits only same-origin / same-provider
+    #     newsletter forms, so the constraint is invisible to honest
+    #     templates and stops a content-injection from doubling as a
+    #     phishing redirect.
+    def csp_policy
+      policy = {
+        'default-src'     => ["'self'"],
+        'img-src'         => ["'self'", 'data:'],
+        'style-src'       => ["'self'"],
+        'script-src'      => ["'self'", "'#{ThemeBootstrap::SHA256}'", "'#{SpeculationRulesGuard::SHA256}'"],
+        'font-src'        => ["'self'"],
+        'connect-src'     => ["'self'"],
+        'object-src'      => ["'none'"],
+        'frame-ancestors' => ["'none'"],
+        'form-action'     => ["'self'"],
+        'base-uri'        => ["'self'"]
+      }
+
+      apply_plausible(policy)        if plausible_key
+      apply_folio(policy)            if folio_enabled?
+      apply_fontawesome_kit(policy)  if fontawesome_kit?
+      apply_search(policy)           if search_enabled?
+      apply_speculation_rules(policy) if speculation_rules_enabled?
+      apply_newsletter(policy)
+      apply_media(policy)
+      # Last, so an operator-declared origin can extend a directive that
+      # a feature rule above created.
+      apply_csp_extensions(policy)
+
+      policy.map { |k, vs| "#{k} #{vs.join(' ')}" }.join('; ')
+    end
+
+    # Off-origin audio / video. Media served from the site itself needs
+    # no directive at all — it falls under `default-src 'self'`, which is
+    # why the base policy declares no `media-src`. Setting `media.host`
+    # creates it as `'self' <host>` (`add_origin` seeds `'self'` on any
+    # directive it has to create), so colocated bundle audio keeps
+    # working alongside the CDN.
+    #
+    # Accepts one host or a list:
+    #
+    #   media:
+    #     host: https://media.example.com
+    #
+    #   media:
+    #     host:
+    #       - https://audio.example.com
+    #       - https://video.example.com
+    def apply_media(policy)
+      cfg = @site.config['media']
+      return unless cfg.is_a?(Hash)
+
+      Array(cfg['host']).each { |host| add_origin(policy, 'media-src', host) }
+    end
+
+    # Directives an operator may extend via `csp:`. The omissions are
+    # deliberate: `default-src` would silently widen every directive
+    # that inherits from it, and `object-src` / `frame-ancestors` /
+    # `base-uri` are the static-site hardening directives documented on
+    # `csp_policy` — making those easy to weaken is exactly what this
+    # key must not do. A site that genuinely needs to change them owns
+    # the whole header via `headers:`.
+    EXTENDABLE_DIRECTIVES = %w[
+      child-src connect-src font-src form-action frame-src img-src
+      manifest-src media-src script-src style-src worker-src
+    ].freeze
+
+    # Operator-declared extra origins:
+    #
+    #   csp:
+    #     img-src:     [https://cdn.example.com]
+    #     connect-src: [https://api.example.com]
+    #
+    # Additive only. Values are appended to the computed policy, so
+    # `'self'`, the pinned inline-script hashes and every feature-derived
+    # origin survive. That's the point of the key: before it existed the
+    # only way to allow an unmodelled origin was `headers:`, which
+    # replaces the built policy wholesale and takes the theme-bootstrap
+    # hash, `'wasm-unsafe-eval'` and the Plausible hash down with it.
+    #
+    # Raises on an unknown directive or a value that isn't an http(s)
+    # origin. A malformed CSP fails open — the browser ignores the parts
+    # it can't parse — so skipping bad config silently would ship a
+    # policy the operator believes is in force. Fail the build instead.
+    def apply_csp_extensions(policy)
+      cfg = @site.config['csp']
+      return unless cfg.is_a?(Hash)
+
+      cfg.each do |directive, values|
+        name = directive.to_s
+        unless EXTENDABLE_DIRECTIVES.include?(name)
+          raise ArgumentError,
+                "csp: #{name.inspect} is not an extendable directive. " \
+                "Extendable: #{EXTENDABLE_DIRECTIVES.join(', ')}. " \
+                'Set `headers:` to take over the whole header instead.'
+        end
+
+        Array(values).each do |value|
+          assert_http_origin!(name, value)
+          add_origin(policy, name, value)
+        end
+      end
+    end
+
+    # `add_origin` is deliberately silent for feature-derived values (a
+    # relative `newsletter.action` is legitimately same-origin). Values
+    # typed directly into `csp:` get the opposite treatment: anything
+    # that isn't a scheme + host is an operator error worth stopping the
+    # build for, and rejecting everything else is what keeps `*`,
+    # `data:` and `'unsafe-inline'` out of this path by construction.
+    def assert_http_origin!(directive, value)
+      uri = begin
+        URI.parse(value.to_s)
+      rescue URI::InvalidURIError
+        nil
+      end
+      return if (uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)) && !uri.host.to_s.empty?
+
+      raise ArgumentError,
+            "csp: #{directive} value #{value.inspect} is not an http(s) origin. " \
+            'Use scheme + host (e.g. https://cdn.example.com). CSP keywords and ' \
+            "non-http schemes ('unsafe-inline', data:, blob:, *) are rejected here — " \
+            'set `headers:` if you need them.'
+    end
+
+    # Pagefind (opt-in via `search: true`) loads its runtime from the
+    # same origin, but that runtime compiles a WebAssembly module —
+    # and WASM compilation is governed by `script-src` regardless of
+    # origin. Without `'wasm-unsafe-eval'` the search box silently
+    # fails with a CSP violation on any host that enforces `_headers`
+    # (Cloudflare Pages, Netlify). Same-origin does NOT exempt WASM.
+    def apply_search(policy)
+      policy['script-src'] << "'wasm-unsafe-eval'"
+    end
+
+    def search_enabled?
+      @site.config['search'] == true
+    end
+
+    # The `<script type="speculationrules">` block the head emits is an
+    # inline script as far as CSP is concerned, so `script-src` must
+    # carry `'inline-speculation-rules'` (Chrome's keyword for exactly
+    # this) or the block is rejected — no prerender, plus a console
+    # error on every page. Its content is config-dependent (posts slug,
+    # eagerness), so a static hash can't cover it. On by default; the
+    # head gates on `speculation_rules.enabled` not being false.
+    def apply_speculation_rules(policy)
+      policy['script-src'] << "'inline-speculation-rules'"
+    end
+
+    def speculation_rules_enabled?
+      cfg = @site.config['speculation_rules']
+      return true unless cfg.is_a?(Hash)
+
+      cfg['enabled'] != false
+    end
+
+    # Plausible: external tracker + inline init script. Both need explicit
+    # CSP allowlisting. Outbound tracking events also hit plausible.io's
+    # API endpoint, which is why connect-src is extended.
+    def apply_plausible(policy)
+      policy['script-src']  << 'https://plausible.io'
+      policy['script-src']  << "'#{PlausibleScript::SHA256}'"
+      policy['connect-src'] << 'https://plausible.io'
+    end
+
+    # Folio cover images are served from a separate cover host. Layouts
+    # emit them as `<img src="https://…">`, so img-src needs the host
+    # explicitly. Defaults to the hosted foliobooks.app cover CDN; a
+    # Folio instance on another domain sets `folio.covers_host` to its
+    # own. Buy / cart URLs are anchor navigations (no CSP) — only
+    # img-src needs extension.
+    DEFAULT_FOLIO_COVERS_HOST = 'https://covers.foliobooks.app'
+
+    def apply_folio(policy)
+      cfg = @site.config['folio'] || {}
+      covers = cfg['covers_host'].to_s
+      covers = DEFAULT_FOLIO_COVERS_HOST if covers.empty?
+      add_origin(policy, 'img-src', covers)
+    end
+
+    def folio_enabled?
+      cfg = @site.config['folio'] || {}
+      !cfg['base_url'].to_s.empty? && !cfg['author_slug'].to_s.empty?
+    end
+
+    # Font Awesome Pro kit. Loaded via JS from kit.fontawesome.com, which
+    # injects styles into the page (so style-src needs 'unsafe-inline')
+    # and pulls woff2s from ka-f.fontawesome.com (font-src). The trade-off
+    # vs the vendored Free dist: PRO icons + auto-versioning, in exchange
+    # for a weaker CSP. Sites that want strict CSP should use the
+    # `fontawesome: true` (Free vendored) path instead.
+    def apply_fontawesome_kit(policy)
+      policy['script-src'] << 'https://kit.fontawesome.com'
+      policy['style-src']  << "'unsafe-inline'"
+      policy['font-src']   << 'https://ka-f.fontawesome.com'
+      policy['connect-src'] << 'https://ka-f.fontawesome.com'
+    end
+
+    def fontawesome_kit?
+      kit = (@site.config['icons'] || {})['fontawesome_kit']
+      kit.is_a?(String) && !kit.empty?
+    end
+
+    # `_newsletter_subscribe.html.erb` lets the operator point the form at
+    # any third-party provider (Mailchimp, Buttondown, ConvertKit, …). The
+    # default `form-action 'self'` would block those POSTs. We trust the
+    # operator-configured `newsletter.action` (and the optional `script:`
+    # URL) and add their origins to the matching directives — narrowly,
+    # not via `unsafe-inline` or wildcards.
+    def apply_newsletter(policy)
+      cfg = @site.config['newsletter']
+      return unless cfg.is_a?(Hash)
+
+      add_origin(policy, 'form-action', cfg['action'])
+      add_origin(policy, 'script-src',  cfg['script'])
+      add_origin(policy, 'connect-src', cfg['script'])
+    end
+
+    # Parse `value` as an http(s) URL and append its `scheme://host`
+    # origin to `directive` if it isn't already there. Silent no-op for
+    # anything that doesn't parse as http(s) — same-origin / relative
+    # values fall under `'self'`, scheme-based attacks (javascript:,
+    # data:) never get past the URI type-check.
+    def add_origin(policy, directive, value)
+      return if value.nil? || value.to_s.empty?
+
+      uri = URI.parse(value.to_s)
+      return unless uri.is_a?(URI::HTTP) || uri.is_a?(URI::HTTPS)
+      return if uri.host.to_s.empty?
+
+      origin = "#{uri.scheme}://#{uri.host}"
+      policy[directive] ||= ["'self'"]
+      policy[directive] << origin unless policy[directive].include?(origin)
+    rescue URI::InvalidURIError
+      # Malformed config — let it through unguarded; the form just won't
+      # work, which is the same surface visitors would see anyway.
+      nil
+    end
+
+    # The Plausible script key when the analytics block is fully
+    # configured — both `enabled: true` AND `key:` set. Used to gate
+    # the CSP extension (plausible.io added to script-src + connect-src
+    # only when we're actually emitting the tracker).
+    def plausible_key
+      cfg = @site.config['plausible']
+      return nil unless cfg.is_a?(Hash)
+      return nil unless cfg['enabled'] == true
+
+      key = cfg['key'].to_s
+      key.empty? ? nil : key
+    end
+  end
+end