bridgetown-webfinger 0.1.0

data/lib/bridgetown/webfinger/uri/acct.rb

@@ -0,0 +1,138 @@
+# frozen_string_literal: true
+
+require "uri"
+
+# A module providing classes to handle Uniform Resource Identifiers ([RFC2396][1])
+#
+# [1]: https://datatracker.ietf.org/doc/html/rfc2396
+module URI
+  # A URI for an account on a system
+  #
+  # @since 0.1.0
+  # @api public
+  #
+  # @example Parsing an acct URI from a string
+  #
+  #   URI.parse("acct:bilbo@bagend.com")
+  #
+  # See [RFC7565](https://datatracker.ietf.org/doc/html/rfc7565) for more
+  # information.
+  class Acct < Generic
+    # The components of the URI
+    #
+    # @private
+    COMPONENT = [:scheme, :account, :host].freeze
+
+    # Builds a {URI::Acct} from components
+    #
+    # Note: Do not enter already percent-encoded data as a component for the
+    # account because the implementation will do this step for you. If you're
+    # building from components received externally, consider using
+    # `URI.decode_uri_component` before using it to build a URI with this
+    # method.
+    #
+    # @since 0.1.0
+    # @api public
+    #
+    # @example Building an acct URI from an array of attributes
+    #
+    #   URI::Acct.build(["bilbo", "bagend.com"])
+    #
+    # @example Building an acct URI from a hash of attributes
+    #
+    #   URI::Acct.build({ account: "bilbo", host: "bagend.com" })
+    #
+    # @param args [Hash<Symbol, String>, Array<String>] the components to use,
+    #   either as a Hash of `{account: String, host: String}` or a positional,
+    #   2-element `Array` of the form `[account, host]`
+    # @return [URI::Acct] the built URI
+    # @raise [ArgumentError] when the components are incorrect
+    def self.build(args)
+      components = Util.make_components_hash(self, args)
+
+      components[:account] ||= ""
+      components[:account] &&= URI.encode_uri_component(components[:account])
+      components[:host] ||= ""
+      components[:opaque] = "#{components.delete(:account)}@#{components.delete(:host)}"
+
+      super(components)
+    end
+
+    # Instantiates a new {URI::Acct} from a long list of components
+    #
+    # @since 0.1.0
+    # @api public
+    #
+    # @example Manually constructing a URI — with value checking — for the masochistic
+    #   URI::Acct.new(["acct", nil, nil, nil, nil, nil, "bilbo@bagend.com", nil, nil, nil, true])
+    #
+    # @param args [Array<String>] the components to set for the URI
+    # @return [URI::Acct]
+    # @raise [InvalidComponentError] when the account name is malformed
+    def initialize(*args)
+      super
+
+      raise InvalidComponentError, "missing opaque part for acct URI" unless @opaque
+
+      account, _, host = @opaque.rpartition("@")
+      @opaque = nil
+
+      if args[10] # arg_check
+        self.account = account
+        self.host = host
+      else
+        @account = account
+        @host = host
+      end
+    end
+
+    # The account part (also known as the userpart) of the URI
+    #
+    # @since 0.1.0
+    # @api public
+    #
+    # @example Checking the account for a URI
+    #
+    #  URI.parse("acct:bilbo@bagend.com").account #=> "bilbo"
+    #
+    # @return [String]
+    attr_reader :account
+
+    # Sets the account part of the URI
+    #
+    # @since 0.1.0
+    # @api public
+    #
+    # @example Setting the account for a URI
+    #
+    #  uri = URI.parse("acct:bilbo@bagend.com")
+    #  uri.account = "frodo"
+    #  uri.account #=> "frodo"
+    #
+    # @param value [String] a percent-encoded account name for the URI
+    # @return [void]
+    # @raise [InvalidComponentError] when the value is malformed
+    def account=(value)
+      raise InvalidComponentError, "missing account part for acct URI" if value.empty?
+      raise InvalidComponentError, "account part not percent-encoded for acct URI" if value.include?("@")
+
+      @account = URI.decode_uri_component(value)
+    end
+
+    # Converts the URI into a string
+    #
+    # @since 0.1.0
+    # @api public
+    #
+    # @example Converting a URI to a string
+    #
+    #   URI.parse("acct:bilbo@bagend.com").to_s
+    #
+    # @return [String] the formatted version of the {URI::Acct}
+    def to_s
+      @scheme + ":" + URI.encode_uri_component(account) + "@" + host
+    end
+  end
+
+  register_scheme "ACCT", Acct
+end

data/lib/bridgetown/webfinger/version.rb

@@ -0,0 +1,8 @@
+# frozen_string_literal: true
+
+module Bridgetown
+  module Webfinger
+    # The version of the bridgetown-webfinger gem
+    VERSION = "0.1.0"
+  end
+end

data/lib/bridgetown-webfinger.rb

@@ -0,0 +1,49 @@
+# frozen_string_literal: true
+
+require "bridgetown"
+require "zeitwerk"
+
+require_relative "bridgetown/webfinger/uri/acct"
+
+# A progressive site generator and fullstack framework
+#
+# @see https://www.bridgetownrb.com/
+module Bridgetown
+  # A Bridgetown plugin that adds support for serving [Webfinger][1] requests
+  #
+  # The plugin handles either static or dynamic requests, served with data backed
+  # by your Bridgetown site's data.
+  #
+  # [1]: https://datatracker.ietf.org/doc/html/rfc7033
+  module Webfinger
+    # The Zeitwerk loader responsible for auto-loading constants
+    #
+    # @private
+    Loader = Zeitwerk::Loader.for_gem(warn_on_extra_files: false).tap do |loader|
+      loader.ignore(__FILE__)
+      loader.ignore(File.join(__dir__, "roda", "plugins", "bridgetown_webfinger"))
+      loader.ignore(File.join(__dir__, "bridgetown", "webfinger", "initializer"))
+      loader.ignore(File.join(__dir__, "bridgetown", "webfinger", "uri", "acct"))
+      loader.inflector.inflect("jrd" => "JRD")
+      loader.setup
+    end
+
+    # Checks whether a given string is a URI of a registered type
+    #
+    # This will not convert the item into a URI object and it is able to
+    # properly handle when there are multiple URIs in the string (by returning
+    # false).
+    #
+    # @since 0.1.0
+    # @api private
+    #
+    # @param uri [String] the string to check as a URI
+    # @return [Boolean] true when it is a URI, false when it is not
+    def self.uri?(uri)
+      uri.is_a?(String) &&
+        uri == URI.extract(uri).first
+    end
+  end
+end
+
+require_relative "bridgetown/webfinger/initializer"

data/lib/roda/plugins/bridgetown_webfinger.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+# A routing tree for building Rack applications
+#
+# @see https://roda.jeremyevans.net/
+class Roda
+  # The namespace Roda uses for loading plugins by convention
+  module RodaPlugins
+    # A plugin that integrates Webfinger behavior into a Bridgetown Roda app
+    #
+    # This plugin requires the Bridgetown SSR plugin to be enabled before it.
+    #
+    # It reads data from the `authors` data for the Bridgetown site to validate
+    # author accounts, then extracts the `webfinger` key from the author to
+    # build the JSON Resource Descriptor.
+    module BridgetownWebfinger
+      # The Roda hook for configuring the plugin
+      #
+      # @since 0.1.0
+      # @api private
+      #
+      # @param app [::Roda] the Roda application to configure
+      # @return [void]
+      def self.configure(app)
+        return unless app.opts[:bridgetown_site].nil?
+
+        # :nocov: Because it's difficult to set up multiple contexts
+        raise(
+          "Roda app failure: the bridgetown_ssr plugin must be registered before " \
+          "bridgetown_webfinger"
+        )
+        # :nocov:
+      end
+
+      # Methods included in to the Roda request
+      #
+      # @see http://roda.jeremyevans.net/rdoc/classes/Roda/RodaPlugins/Base/RequestMethods.html
+      module RequestMethods
+        # Builds the Webfinger route within the Roda application
+        #
+        # @since 0.1.0
+        # @api public
+        #
+        # @example Enabling the Webfinger route
+        #
+        #   class RodaApp < Bridgetown::Rack::Roda
+        #     plugin :bridgetown_ssr
+        #     plugin :bridgetown_webfinger
+        #
+        #     route do |r|
+        #       r.bridgetown_webfinger
+        #     end
+        #   end
+        #
+        # @return [void]
+        def bridgetown_webfinger
+          bridgetown_site = roda_class.opts[:bridgetown_site]
+
+          on(".well-known/webfinger") do
+            is do
+              get do
+                params = Bridgetown::Webfinger::Parameters.from_query_string(query_string)
+                host = URI(bridgetown_site.config.url).host
+                response["Access-Control-Allow-Origin"] =
+                  bridgetown_site.config.webfinger.allowed_origins
+
+                unless (resource = params.resource)
+                  next response.webfinger_error("Missing required parameter: resource", status: 400)
+                end
+
+                if (jrd = webfinger_maybe_jrd(resource, host: host, params: params, site: bridgetown_site))
+                  response.webfinger_success(jrd)
+                else
+                  response.webfinger_error("Unknown resource: #{resource}", status: 404)
+                end
+              end
+            end
+          end
+        end
+
+        private
+
+        # Constructs a JRD for the appropriate account from author metadata
+        #
+        # @since 0.1.0
+        # @api private
+        #
+        # @param resource [String] the resource URI from the parameters
+        # @param host [String] the host domain from the site configuration
+        # @param params [Bridgetown::Webfinger::Parameters] the parameters for the request
+        # @param site [Bridgetown::Site] the site for the Bridgetown instance
+        # @return [Bridgetown::Webfinger::JRD, nil] the JRD when possible, nil otherwise
+        def webfinger_maybe_jrd(resource, host:, params:, site:)
+          return unless (uri = URI.parse(resource)).instance_of?(URI::Acct)
+          return unless (authors = site.data.authors)
+
+          webfinger =
+            if (acct = authors[uri.account])
+              acct.webfinger
+            elsif uri.account.empty? && uri.host == host && authors.length == 1
+              uri.account = uri.host
+              authors.values.first.webfinger
+            else
+              return
+            end
+
+          jrd = Bridgetown::Webfinger::JRD.parse(uri.to_s, webfinger)
+          jrd.links&.select! { |link| params.rel.include?(link.rel) } if params.rel
+          jrd
+        end
+      end
+
+      # Methods included in to the Roda response
+      #
+      # @see http://roda.jeremyevans.net/rdoc/classes/Roda/RodaPlugins/Base/ResponseMethods.html
+      module ResponseMethods
+        # Renders an error in the style of Bridgetown Webfinger
+        #
+        # @since 0.1.0
+        # @api private
+        #
+        # @param message [String] the error message for the response
+        # @param status [Integer] the status code for the response
+        # @return [String] the response body
+        def webfinger_error(message, status:)
+          self["Content-Type"] = "application/json"
+          self.status = status
+
+          JSON.pretty_generate({error: message})
+        end
+
+        # Renders a JSON Resource Descriptor for Webfinger
+        #
+        # @since 0.1.0
+        # @api private
+        #
+        # @param jrd [Bridgetown::Webfinger::JRD] the JRD to render
+        # @return [String] the response body
+        def webfinger_success(jrd)
+          self["Content-Type"] = "application/jrd+json"
+
+          JSON.pretty_generate(jrd.to_h)
+        end
+      end
+    end
+
+    register_plugin :bridgetown_webfinger, BridgetownWebfinger
+  end
+end

metadata

@@ -0,0 +1,131 @@
+--- !ruby/object:Gem::Specification
+name: bridgetown-webfinger
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Michael Herold
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2023-02-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: bridgetown
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '1.2'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+- !ruby/object:Gem::Dependency
+  name: uri
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.12.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.12.0
+- !ruby/object:Gem::Dependency
+  name: zeitwerk
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '2'
+description:
+email: opensource@michaeljherold.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- CONTRIBUTING.md
+- LICENSE.md
+- README.md
+- bridgetown-webfinger.gemspec
+- lib/bridgetown-webfinger.rb
+- lib/bridgetown/webfinger/alias.rb
+- lib/bridgetown/webfinger/builder.rb
+- lib/bridgetown/webfinger/href.rb
+- lib/bridgetown/webfinger/initializer.rb
+- lib/bridgetown/webfinger/jrd.rb
+- lib/bridgetown/webfinger/link.rb
+- lib/bridgetown/webfinger/link_relation_type.rb
+- lib/bridgetown/webfinger/logging.rb
+- lib/bridgetown/webfinger/model.rb
+- lib/bridgetown/webfinger/parameters.rb
+- lib/bridgetown/webfinger/properties.rb
+- lib/bridgetown/webfinger/titles.rb
+- lib/bridgetown/webfinger/uri/acct.rb
+- lib/bridgetown/webfinger/version.rb
+- lib/roda/plugins/bridgetown_webfinger.rb
+homepage: https://github.com/michaelherold/bridgetown-webfinger
+licenses:
+- MIT
+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/0.1.0
+  homepage_uri: https://github.com/michaelherold/bridgetown-webfinger
+  rubygems_mfa_required: 'true'
+  source_code_uri: https://github.com/michaelherold/bridgetown-webfinger
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.2.32
+signing_key:
+specification_version: 4
+summary: Adds structured support for Webfinger to Bridgetown sites
+test_files: []