bridgetown-webfinger 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3c1086d7e337e4a0654b54bac8d38521cbe18c7502cfd816d8c6f164a40553b4
+  data.tar.gz: b014d6ffbb34b2b839af88730993d376d2dd1a4ff0ad43e51110eb397e03c6e2
+SHA512:
+  metadata.gz: 1dd3dbc3a4097dbeb8283cf3c92bc1a8d9eb9d88e3555a1f3a61a65a13f2a048f25e09d69c4e1c25def7d68748ac9c1f32a494a3ff314e812c463c27e9b3311a
+  data.tar.gz: e3452f05f6cedd25bf31e99752aedec2d30b4e747fe7f9e094995ad2909b7a89dccf38203b70b47288a1c07f802f69654b8f722ee95c7dd8f889283e1b6acc58

data/CHANGELOG.md

@@ -0,0 +1,15 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.1.0](https://github.com/michaelherold/bridgetown-webfinger/tree/v0.1.0) - 2023-02-25
+
+### Added
+
+- Static file support for rendering a `.well-known/webfinger` file that always responds with the same information.
+- Dynamic support via a Roda plugin for handling multiple authors and proper filtering for `rel` filters. This includes the ability to set `Access-Control-Allow-Origin` headers via the `allowed_hosts` option.
+- Validation of all Webfinger properties and printed warnings for invalid values to help ensure you write interoperable Webfinger properties.
+- An automation to quickly bootstrap your site's Webfinger capabilities.

data/CONTRIBUTING.md

@@ -0,0 +1,55 @@
+# Contributing
+
+In the spirit of [free software](http://www.fsf.org/licensing/essays/free-sw.html), we encourage **everyone** to help improve this project. Here are some ways _you_ can contribute:
+
+* Use alpha, beta, and pre-release versions.
+* Report bugs.
+* Suggest new features.
+* Write or edit documentation.
+* Write specifications.
+* Write code (**no patch is too small**: fix typos, add comments, clean up inconsistent whitespace).
+* Refactor code.
+* Fix [issues].
+* Review patches.
+
+[issues]: https://github.com/michaelherold/bridgetown-webfinger/issues
+
+## Submitting an Issue
+
+We use the [GitHub issue tracker][issues] to track bugs and features. Before submitting a bug report or feature request, check to make sure no one has already submitted it.
+
+When submitting a bug report, please include a `<details>` block that includes a stack trace and any details that may be necessary to reproduce the bug, including your gem version, Ruby version, and operating system. This looks like the following:
+
+```markdown
+<details>
+<summary>A description of the details block</summary>
+
+All of the content that you want in here, perhaps with code fences. Note that
+if you only have a code fence in here, you _must_ separate it from the <summary>
+tag and the closing </details> or it won't render correctly.
+
+Notice the empty line here ↓
+
+</details>
+```
+
+Ideally, a bug report should include a pull request with failing specs.
+
+## Submitting a Pull Request
+
+1. Fork the repository.
+2. Create a topic branch.
+3. Add specs for your unimplemented feature or bug fix.
+4. Run `bundle exec rake test`. If your specs pass, return to step 3.
+5. Implement your feature or bug fix.
+6. Run `bundle exec rake`. If your specs or any of the linters fail, return to step 5.
+7. Open `coverage/index.html`. If your changes are not fully covered by your tests, return to step 3.
+8. Add documentation for your feature or bug fix.
+9. Commit and push your changes.
+10. Submit a pull request.
+
+## Tools to Help You Succeed
+
+After checking out the repository, run `bin/setup` to install dependencies. Then, run `bundle exec rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+Before committing code, run `bundle exec rake` to check that the code conforms to the style guidelines of the project, that all of the tests are green (if you're writing a feature; if you're only submitting a failing test, then it does not have to pass!), and that you sufficiently documented the changes.

data/LICENSE.md

@@ -0,0 +1,22 @@
+# The MIT License (MIT)
+
+Copyright © 2023-present
+
+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,125 @@
+# Bridgetown Webfinger plugin
+
+A [Bridgetown][1] plugin for handling [Webfinger][2] requests for the Fediverse and [IndieWeb][3].
+
+Whether you run a single-author, statically rendered site or a multi-author site with a dynamic backend, this is your one-stop shop for Webfinger support.
+
+This plugin allows for hosting Webfinger lookups on your website for [`acct:` URIs][4]. This is the first step to giving your site the ability to post to Fediverse apps like [Mastodon][5], [Pleroma][6], or [PeerTube][7]. While not all Fediverse apps use Webfinger, enough do that adding Webfinger support will be necessary to have your site participate in the Fediverse.
+
+[1]: https://www.bridgetownrb.com
+[2]: https://webfinger.net/
+[3]: https://indieweb.org/
+[4]: https://datatracker.ietf.org/doc/html/rfc7565
+[5]: https://joinmastodon.org/
+[6]: https://pleroma.social/
+[7]: https://joinpeertube.org/
+
+## Installation
+
+Run this command to add this plugin to your site's Gemfile:
+
+    bundle add bridgetown-webfinger
+
+Or you can use [an automation script][8] instead for guided setup:
+
+    bin/bt apply https://github.com/michaelherold/bridgetown-webfinger
+
+[8]: https://www.bridgetownrb.com/docs/automations
+
+## Usage
+
+This plugin runs in one of two modes: static mode or dynamic mode.
+
+Static mode is for when you run a single-author, fully static website without using any of Bridgetown's Server-Side Rendering (SSR) capabilities. It is mildly non-compliant with the Webfinger specification, but is an accepted practice for static sites.
+
+Dynamic mode uses a Roda plugin to serve author data for all accounts defined in your `src/_data/authors.yml` file.
+
+### Authors data file
+
+Within your authors data file, each author requires a `webfinger` associative array with data about the account. For example, for the account `bilbo`, who has a Twitter account at `https://twitter.com/bilbobaggins` and hosts an avatar at `https://bagend.com/bilbo.png`, the authors data file entry might look like:
+
+```yaml
+# src/_data/authors.yml
+---
+bilbo:
+  webfinger:
+    aliases:
+      - https://twitter.com/bilbobaggins
+    links:
+      - href: https://bagend.com/bilbo.png
+        rel: http://webfinger.net/rel/avatar
+        type: image/png
+```
+
+You may configure any number of authors in this way, however static mode works with only a single author.
+
+### Static mode
+
+To use static mode, configure your [authors data file](#authors-data-file) and add the following to your `config/initializers.rb` file:
+
+```ruby
+# config/initializers.rb
+Bridgetown.configure do
+  init "bridgetown-webfinger", static: true
+end
+```
+
+Bridgetown will now generate a `.well-known/webfinger` file using your first author's information when building the site.
+
+#### Deploying to Netlify
+
+To have the correct headers for your static file, add the following to your `netlify.toml`.
+
+```toml
+[[headers]]
+for = "/.well-known/webfinger"
+
+[headers.values]
+Access-Control-Allow-Origin = "*"
+Content-Type = "application/jrd+json"
+```
+
+See [the allowed hosts section below](#allowed-hosts) for more information about the access control header.
+
+### Dynamic mode
+
+To use dynamic mode, configure your [authors data file](#authors-data-file) and add the following to your `config/initializers.rb` file:
+
+```ruby
+# config/initializers.rb
+Bridgetown.configure do
+  init "bridgetown-webfinger", static: false, allowed_hosts: "*"
+end
+```
+
+Then, add the `bridgetown_webfinger` plugin to your `RodaApp` and call the `bridgetown_webfinger` request method:
+
+```ruby
+# server/roda_app.rb
+class RodaApp < Bridgetown::Rack::Roda
+  plugin :bridgetown_ssr  # required
+  plugin :bridgetown_webfinger
+  
+  route do |r|
+    r.bridgetown_webfinger
+  end
+end
+```
+
+This generates a `.well-known/webfinger` route that serves `acct:` URI requests for authors on your site.
+
+#### Allowed hosts
+
+The [Webfinger specification][9] states that [servers must include the `Access-Control-Allow-Origin`][10] header to enable Cross-Origin Resource Sharing (CORS) requests and that they should use the least restrictive setting.
+
+Unless you are hosting private Webfinger information — e.g. within a corporate network, to only authenticated followers, or for any other reason — you should set this to `"*"` using the configuration above.
+
+If this is private information that you wish to restrict [set the header value appropriately][11].
+
+[9]: https://datatracker.ietf.org/doc/html/rfc7033
+[10]: https://datatracker.ietf.org/doc/html/rfc7033#section-5
+[11]: https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Access-Control-Allow-Origin
+
+## Contributing
+
+So you're interested in contributing to Bridgetown Webfinger? Check out our [contributing guidelines](CONTRIBUTING.md) for more information on how to do that.

data/bridgetown-webfinger.gemspec

@@ -0,0 +1,35 @@
+# frozen_string_literal: true
+
+require_relative "lib/bridgetown/webfinger/version"
+
+Gem::Specification.new do |spec|
+  spec.name = "bridgetown-webfinger"
+  spec.version = Bridgetown::Webfinger::VERSION
+  spec.author = "Michael Herold"
+  spec.email = "opensource@michaeljherold.com"
+  spec.summary = "Adds structured support for Webfinger to Bridgetown sites"
+  spec.homepage = "https://github.com/michaelherold/bridgetown-webfinger"
+  spec.license = "MIT"
+
+  spec.files = %w[CHANGELOG.md CONTRIBUTING.md LICENSE.md README.md]
+  spec.files += %w[bridgetown-webfinger.gemspec]
+  spec.files += Dir["lib/**/*.rb"]
+  spec.require_paths = ["lib"]
+
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.add_dependency "bridgetown", ">= 1.2", "< 2.0"
+  spec.add_dependency "uri", ">= 0.12.0"
+  spec.add_dependency "zeitwerk"
+
+  spec.add_development_dependency "bundler", ">= 2"
+
+  spec.metadata = {
+    "bug_tracker_uri" => "https://github.com/michaelherold/bridgetown-webfinger/issues",
+    "changelog_uri" => "https://github.com/michaelherold/bridgetown-webfinger/blob/main/CHANGELOG.md",
+    "documentation_uri" => "https://rubydoc.info/gems/bridgetown-webfinger/#{Bridgetown::Webfinger::VERSION}",
+    "homepage_uri" => "https://github.com/michaelherold/bridgetown-webfinger",
+    "rubygems_mfa_required" => "true",
+    "source_code_uri" => "https://github.com/michaelherold/bridgetown-webfinger"
+  }
+end

data/lib/bridgetown/webfinger/alias.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module Webfinger
+    # Wraps an `alias` member within a {JRD}, which is a URI identifying the same subject
+    class Alias < Model
+      # Parses and maybe-returns an {Alias} when the value is one
+      #
+      # Aliases [must be URIs][1] so when the value is not a proper URI, it is
+      # ignored.
+      #
+      # [1]: https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.2
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @return [Alias, nil] an {Alias} when the value is a URI, nil otherwise
+      def self.parse(moniker)
+        if Webfinger.uri?(moniker)
+          new(moniker)
+        else
+          warn(
+            "Webfinger alias is malformed: #{moniker.inspect}, ignoring"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/bridgetown/webfinger/builder.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module Webfinger
+    # The [builder class][1] for working with Webfinger in Bridgetown
+    #
+    # [1]: https://www.bridgetownrb.com/docs/plugins#introduction-to-the-builder-api
+    class Builder < Bridgetown::Builder
+      include Logging
+
+      # The hook method for enabling the builder's behavior
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @return [void]
+      def build
+        generator :static_file
+      end
+
+      private
+
+      # Builds a static Webfinger file when correctly configured
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @return [void]
+      def static_file
+        return unless config.webfinger.static
+        return unless (host = extract_site_host)
+        return unless (account, data = extract_authors_from_site_data)
+
+        site.add_generated_page StaticFile.new(site, account: account, data: data, host: host)
+      end
+
+      # Extracts the site's host from its configuration
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @return [String, nil] String when configured correctly, nil otherwise
+      def extract_site_host
+        host = site.config.url
+
+        if !host || host.empty?
+          warn(
+            "bridgetown-webfinger did not find your site's host configured at " \
+            "`site.config.url`; this is unsupported by static files so will be ignored"
+          )
+          return
+        end
+
+        uri = URI(host)
+
+        if uri.is_a?(URI::HTTP)
+          uri.host
+        elsif uri.instance_of?(URI::Generic)
+          uri.to_s
+        else
+          warn(
+            "bridgetown-webfinger detected a malformed host in your site configuration " \
+            "(#{uri} from `site.config.url`); this is unsupported and will be ignored"
+          )
+        end
+      end
+
+      # Extracts the author from the site's data
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @return [HashWithDotAccess::Hash, nil] Hash when configured correctly, nil otherwise
+      def extract_authors_from_site_data
+        unless (authors = site.data.authors) && !authors.empty?
+          warn(
+            "bridgetown-webfinger did not detect any authors at `site.data.authors`; " \
+            "this is unsupported by static files so will be ignored"
+          )
+          return
+        end
+
+        unless authors.size == 1
+          warn(
+            "bridgetown-webfinger discovered multiple authors; this is unsupported " \
+            "by static files so will be ignored"
+          )
+          return
+        end
+
+        authors.first
+      end
+
+      # The static Webfinger file to serve
+      class StaticFile < Bridgetown::GeneratedPage
+        # Initializes a new static Webfinger file
+        #
+        # @since 0.1.0
+        # @api private
+        #
+        # @param site [Bridgetown::Site] the site object
+        # @param account [String] the account for the {URI::Acct}
+        # @param data [HashWithDotAccess::Hash] the data for the Webfinger JRD
+        # @param host [String] the host for the {URI::Acct}
+        # @return [void]
+        def initialize(site, account:, data:, host:)
+          super(site, __dir__, "/.well-known", "webfinger", from_plugin: true)
+
+          @subject = URI::Acct.build({account: account, host: host}).to_s
+          @jrd = JRD.parse(@subject, data.webfinger)
+
+          self.content = JSON.pretty_generate(@jrd.to_h)
+        end
+
+        # The {JRD} forming the data model for the static Webfinger page
+        #
+        # @since 0.1.0
+        # @api private
+        #
+        # @return [JRD] the JSON Resource Descriptor to serve for Webfinger
+        attr_reader :jrd
+
+        # The subject of the {JRD}
+        #
+        # @since 0.1.0
+        # @api private
+        #
+        # @return [String] the subject for the JRD to serve
+        attr_reader :subject
+      end
+    end
+  end
+end

data/lib/bridgetown/webfinger/href.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module Webfinger
+    # Wraps an `href` member within a {Link}, which is the target URI
+    class Href < Model
+      # Parses and maybe-returns an {Href} when the value is one
+      #
+      # Hrefs [must be URIs][1] so when the value is not a proper URI, it is
+      # ignored.
+      #
+      # [1]: https://datatracker.ietf.org/doc/html/rfc7033#section-4.4.4.3
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @return [Href, nil] an {Href} when the value is a URI, nil otherwise
+      def self.parse(href)
+        if Webfinger.uri?(href)
+          new(href)
+        else
+          warn(
+            "Webfinger link href is malformed: #{href.inspect}, ignoring"
+          )
+        end
+      end
+    end
+  end
+end

data/lib/bridgetown/webfinger/initializer.rb

@@ -0,0 +1,23 @@
+# frozen_string_literal: true
+
+# @param config [Bridgetown::Configuration::ConfigurationDSL]
+# @param allowed_origins [String] the value to use for the
+#   `Access-Control-Allow-Origin` header in the Roda plugin. Only override this
+#   if you're hosting private Webfinger data due to the [spec][1] saying, "servers
+#   SHOULD support the least restrictive setting"
+# @param static [Boolean] whether to use static file rendering or not
+#
+# [1]: https://datatracker.ietf.org/doc/html/rfc7033#section-5
+Bridgetown.initializer "bridgetown-webfinger" do |config, allowed_origins: "*", static: true|
+  options = {allowed_origins: allowed_origins, static: static}
+
+  # :nocov: Because it's not possible to show coverage for both branches
+  if config.webfinger
+    config.webfinger Bridgetown::Utils.deep_merge_hashes(options, config.webfinger)
+  else
+    config.webfinger(options)
+  end
+  # :nocov:
+
+  config.builder Bridgetown::Webfinger::Builder
+end

data/lib/bridgetown/webfinger/jrd.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module Webfinger
+    # A model of a [JSON Resource Descriptor][1]
+    #
+    # [1]: https://datatracker.ietf.org/doc/html/rfc7033#section-4.4
+    class JRD
+      include Logging
+
+      # Parses and maybe-returns a {JRD} when the subject and data form one
+      #
+      # {JRD}s can describe any resource identifiable via a URI, whether you want
+      # to give public directory information about people via `acct:` URIs,
+      # copyright information about an article, or perhaps license information
+      # about a library.
+      #
+      # @since 0.1.0
+      # @api public
+      #
+      # @example Convert a Hash into a sanitized {JRD}
+      #
+      #    Bridgetown::Webfinger::JRD.parse(
+      #      "acct:bilbo@bagend.com",
+      #      {
+      #        aliases: ["https://bilbobaggins.com/"],
+      #        links: [
+      #          {
+      #            href: "https://bagend.com/bilbo",
+      #            rel: "http://webfinger.net/rel/profile-page",
+      #            type: "text/html",
+      #            properties: {
+      #              "http://packetizer.com/ns/name" => "Bilbo @ Bag End"
+      #            },
+      #            titles: {
+      #              "en-us" => "Bilbo Baggins's blog"
+      #            }
+      #          }
+      #        ],
+      #        properties: {
+      #          "http://packetizer.com/ns/name" => "Bilbo Baggins"
+      #        }
+      #      }
+      #    )
+      #
+      # @param subject [String] the (nominally) optional subject identified by
+      #   the JRD; _should_ be present but is not _required_
+      # @param data [Hash] the data hash containing information to add to the
+      #   JRD
+      # @return [JRD, nil] a {JRD} when the information is valid, nil otherwise
+      def self.parse(subject, data)
+        aliases = Array(data[:aliases]).filter_map { |moniker| Alias.parse(moniker) }
+        links = Array(data[:links]).filter_map { |link| Link.parse(link) }
+        properties = Properties.parse(data[:properties])
+        subject = Webfinger.uri?(subject) ? subject : nil
+
+        new(
+          aliases: (!aliases.empty?) ? aliases : nil,
+          links: (!links.empty?) ? links : nil,
+          properties: properties,
+          subject: subject
+        )
+      end
+
+      # Creates a new {JRD}
+      #
+      # @since 0.1.0
+      # @api public
+      #
+      # @example Creating a new {JRD} without parsing a Hash
+      #
+      #   Bridgetown::Webfinger::JRD.new(
+      #     subject: "acct:bilbo@bagend.com",
+      #     aliases: [Bridgetown::Webfinger::Alias.new("https://bilbobaggins.com/")]
+      #   )
+      #
+      # @param aliases [Array<Alias>, nil] the optional {Alias}es for the resource
+      # @param links [Array<Link>, nil] the optional {Link}s related to the resource
+      # @param properties [Properties] the optional {Properties} describing the resource
+      # @param subject [String, nil] the (nominally) optional subject URI for the resource
+      def initialize(aliases: nil, links: nil, properties: nil, subject: nil)
+        @aliases = aliases
+        @links = links
+        @properties = properties
+        @subject = subject
+      end
+
+      # The list of {Alias}es for the resource
+      #
+      # @since 0.1.0
+      # @api public
+      #
+      # @example Read the {Alias}es for a {JRD}
+      #
+      #   jrd = Bridgetown::Webfinger::JRD.parse(
+      #     "acct:bilbo@bagend.com",
+      #     {aliases: ["https://bilbobaggins.com"]}
+      #   )
+      #   jrd.aliases
+      #
+      # @return [Array<Alias>, nil] the optional {Alias}es for the resource
+      attr_reader :aliases
+
+      # The list of {Link}s for the resource
+      #
+      # @since 0.1.0
+      # @api public
+      #
+      # @example Read the {Link}s for a {JRD}
+      #
+      #   jrd = Bridgetown::Webfinger::JRD.parse(
+      #     "acct:bilbo@bagend.com",
+      #     {links: [{href: "https://bilbobaggins.com", rel: "https://webfinger.net/rel/avatar"}]}
+      #   )
+      #   jrd.links
+      #
+      # @return [Array<Link>, nil] the optional {Link}s related to the resource
+      attr_reader :links
+
+      # The list of {Properties} for the resource
+      #
+      # @since 0.1.0
+      # @api public
+      #
+      # @example Read the {Properties} for a {JRD}
+      #
+      #   jrd = Bridgetown::Webfinger::JRD.parse(
+      #     "acct:bilbo@bagend.com",
+      #     {properties: {"http://packetizer.com/ns/name" => "Bilbo Baggins"}}
+      #   )
+      #   jrd.properties
+      #
+      # @return [Properties, nil] the optional {Properties} describing the resource
+      attr_reader :properties
+
+      # The subject of the {JRD}
+      #
+      # @since 0.1.0
+      # @api public
+      #
+      # @example Read the subject for a {JRD}
+      #
+      #   jrd = Bridgetown::Webfinger::JRD.parse("acct:bilbo@bagend.com")
+      #   jrd.subject  #=> "acct:bilbo@bagend.com"
+      #
+      # @return [String, nil] the (nominally) optional subject URI for the resource
+      attr_reader :subject
+
+      # Converts the {JRD} to a JSON-serializable Hash
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @return [Hash] the JRD as a JSON-compatible Hash
+      def to_h
+        result = {subject: subject}
+        result[:aliases] = aliases if aliases
+        result[:links] = links.map(&:to_h) if links
+        result[:properties] = properties.to_h if properties
+        result
+      end
+    end
+  end
+end