diaspora_federation 0.0.1

data/lib/diaspora_federation/web_finger/host_meta.rb

@@ -0,0 +1,100 @@
+
+module DiasporaFederation
+  module WebFinger
+    ##
+    # Generates and parses Host Meta documents.
+    #
+    # This is a minimal implementation of the standard, only to the degree of what
+    # is used for the purposes of the Diaspora* protocol. (e.g. WebFinger)
+    #
+    # @example Creating a Host Meta document
+    #   doc = HostMeta.from_base_url("https://pod.example.tld/")
+    #   doc.to_xml
+    #
+    # @example Parsing a Host Meta document
+    #   doc = HostMeta.from_xml(xml_string)
+    #   webfinger_tpl = doc.webfinger_template_url
+    #
+    # @see http://tools.ietf.org/html/rfc6415 RFC 6415: "Web Host Metadata"
+    # @see XrdDocument
+    class HostMeta
+      private_class_method :new
+
+      # URL fragment to append to the base URL
+      WEBFINGER_SUFFIX = "webfinger?q={uri}"
+
+      ##
+      # Returns the WebFinger URL that was used to build this instance (either from
+      # xml or by giving a base URL).
+      # @return [String] WebFinger template URL
+      def webfinger_template_url
+        @webfinger_url
+      end
+
+      ##
+      # Produces the XML string for the Host Meta instance with a +Link+ element
+      # containing the +webfinger_url+.
+      # @return [String] XML string
+      def to_xml
+        doc = XrdDocument.new
+        doc.links << {rel:      "lrdd",
+                      type:     "application/xrd+xml",
+                      template: @webfinger_url}
+        doc.to_xml
+      end
+
+      ##
+      # Builds a new HostMeta instance and constructs the WebFinger URL from the
+      # given base URL by appending HostMeta::WEBFINGER_SUFFIX.
+      # @return [HostMeta]
+      # @raise [InvalidData] if the webfinger url is malformed
+      def self.from_base_url(base_url)
+        raise ArgumentError, "base_url is not a String" unless base_url.instance_of?(String)
+
+        base_url += "/" unless base_url.end_with?("/")
+        webfinger_url = base_url + WEBFINGER_SUFFIX
+        raise InvalidData, "invalid webfinger url: #{webfinger_url}" unless webfinger_url_valid?(webfinger_url)
+
+        hm = allocate
+        hm.instance_variable_set(:@webfinger_url, webfinger_url)
+        hm
+      end
+
+      ##
+      # Reads the given Host Meta XML document string and populates the
+      # +webfinger_url+.
+      # @param [String] hostmeta_xml Host Meta XML string
+      # @raise [InvalidData] if the xml or the webfinger url is malformed
+      def self.from_xml(hostmeta_xml)
+        data = XrdDocument.xml_data(hostmeta_xml)
+        raise InvalidData, "received an invalid xml" unless data.key?(:links)
+
+        webfinger_url = webfinger_url_from_xrd(data)
+        raise InvalidData, "invalid webfinger url: #{webfinger_url}" unless webfinger_url_valid?(webfinger_url)
+
+        hm = allocate
+        hm.instance_variable_set(:@webfinger_url, webfinger_url)
+        hm
+      end
+
+      ##
+      # Applies some basic sanity-checking to the given URL
+      # @param [String] url validation subject
+      # @return [Boolean] validation result
+      def self.webfinger_url_valid?(url)
+        !url.nil? && url.instance_of?(String) && url =~ %r{^https?:\/\/.*\{uri\}}i
+      end
+      private_class_method :webfinger_url_valid?
+
+      ##
+      # Gets the webfinger url from an XRD data structure
+      # @param [Hash] data extracted data
+      # @return [String] webfinger url
+      def self.webfinger_url_from_xrd(data)
+        link = data[:links].find {|l| (l[:rel] == "lrdd" && l[:type] == "application/xrd+xml") }
+        return link[:template] unless link.nil?
+      end
+      private_class_method :webfinger_url_from_xrd
+    end
+  end
+end

data/lib/diaspora_federation/web_finger/web_finger.rb

@@ -0,0 +1,263 @@
+module DiasporaFederation
+  module WebFinger
+    ##
+    # The WebFinger document used for Diaspora* user discovery is based on an older
+    # draft of the specification you can find in the wiki of the "webfinger" project
+    # on {http://code.google.com/p/webfinger/wiki/WebFingerProtocol Google Code}
+    # (from around 2010).
+    #
+    # In the meantime an actual RFC draft has been in development, which should
+    # serve as a base for all future changes of this implementation.
+    #
+    # @example Creating a WebFinger document from account data
+    #   wf = WebFinger.from_person({
+    #     acct_uri:    "acct:user@server.example",
+    #     alias_url:   "https://server.example/people/0123456789abcdef",
+    #     hcard_url:   "https://server.example/hcard/users/0123456789abcdef",
+    #     seed_url:    "https://server.example/",
+    #     profile_url: "https://server.example/u/user",
+    #     atom_url:    "https://server.example/public/user.atom",
+    #     salmon_url:  "https://server.example/receive/users/0123456789abcdef",
+    #     guid:        "0123456789abcdef",
+    #     pubkey:      "-----BEGIN PUBLIC KEY-----\nABCDEF==\n-----END PUBLIC KEY-----"
+    #   })
+    #   xml_string = wf.to_xml
+    #
+    # @example Creating a WebFinger instance from an xml document
+    #   wf = WebFinger.from_xml(xml_string)
+    #   ...
+    #   hcard_url = wf.hcard_url
+    #   ...
+    #
+    # @see http://tools.ietf.org/html/draft-jones-appsawg-webfinger "WebFinger" -
+    #   current draft
+    # @see http://code.google.com/p/webfinger/wiki/CommonLinkRelations
+    # @see http://www.iana.org/assignments/link-relations/link-relations.xhtml
+    #   official list of IANA link relations
+    class WebFinger
+      private_class_method :new
+
+      # The Subject element should contain the webfinger address that was asked
+      # for. If it does not, then this webfinger profile MUST be ignored.
+      # @return [String]
+      attr_reader :acct_uri
+
+      # @return [String] link to the users profile
+      attr_reader :alias_url, :profile_url
+
+      # @return [String] link to the +hCard+
+      attr_reader :hcard_url
+
+      # @return [String] link to the pod
+      attr_reader :seed_url
+
+      # This atom feed is an Activity Stream of the user's public posts. Diaspora
+      # pods SHOULD publish an Activity Stream of public posts, but there is
+      # currently no requirement to be able to read Activity Streams.
+      # @see http://activitystrea.ms/ Activity Streams specification
+      #
+      # Note that this feed MAY also be made available through the PubSubHubbub
+      # mechanism by supplying a <link rel="hub"> in the atom feed itself.
+      # @return [String] atom feed url
+      attr_reader :atom_url
+
+      # @return [String] salmon endpoint url
+      # @see http://salmon-protocol.googlecode.com/svn/trunk/draft-panzer-salmon-00.html#SMLR
+      #   Panzer draft for Salmon, paragraph 3.3
+      attr_reader :salmon_url
+
+      # @deprecated Either convert these to +Property+ elements or move to the
+      #   +hCard+, which actually has fields for an +UID+ defined in the +vCard+
+      #   specification (will affect older Diaspora* installations).
+      #
+      # @see HCard#guid
+      #
+      # This is just the guid. When a user creates an account on a pod, the pod
+      # MUST assign them a guid - a random hexadecimal string of at least 8
+      # hexadecimal digits.
+      # @return [String] guid
+      attr_reader :guid
+
+      # @deprecated Either convert these to +Property+ elements or move to the
+      #   +hCard+, which actually has fields for an +KEY+ defined in the +vCard+
+      #   specification (will affect older Diaspora* installations).
+      #
+      # @see HCard#pubkey
+      #
+      # When a user is created on the pod, the pod MUST generate a pgp keypair
+      # for them. This key is used for signing messages. The format is a
+      # DER-encoded PKCS#1 key beginning with the text
+      # "-----BEGIN PUBLIC KEY-----" and ending with "-----END PUBLIC KEY-----".
+      # @return [String] public key
+      attr_reader :pubkey
+
+      # +hcard_url+ link relation
+      REL_HCARD = "http://microformats.org/profile/hcard"
+
+      # +seed_url+ link relation
+      REL_SEED = "http://joindiaspora.com/seed_location"
+
+      # @deprecated This should be a +Property+ or moved to the +hCard+, but +Link+
+      #   is inappropriate according to the specification (will affect older
+      #   Diaspora* installations).
+      # +guid+ link relation
+      REL_GUID = "http://joindiaspora.com/guid"
+
+      # +profile_url+ link relation.
+      # @note This might just as well be an +Alias+ instead of a +Link+.
+      REL_PROFILE = "http://webfinger.net/rel/profile-page"
+
+      # +atom_url+ link relation
+      REL_ATOM = "http://schemas.google.com/g/2010#updates-from"
+
+      # +salmon_url+ link relation
+      REL_SALMON = "salmon"
+
+      # @deprecated This should be a +Property+ or moved to the +hcard+, but +Link+
+      #   is inappropriate according to the specification (will affect older
+      #   Diaspora* installations).
+      # +pubkey+ link relation
+      REL_PUBKEY = "diaspora-public-key"
+
+      # Create the XML string from the current WebFinger instance
+      # @return [String] XML string
+      def to_xml
+        doc = XrdDocument.new
+        doc.subject = @acct_uri
+        doc.aliases << @alias_url
+
+        add_links_to(doc)
+
+        doc.to_xml
+      end
+
+      # Create a WebFinger instance from the given person data Hash.
+      # @param [Hash] data account data
+      # @return [WebFinger] WebFinger instance
+      # @raise [InvalidData] if the given data Hash is invalid or incomplete
+      def self.from_person(data)
+        raise InvalidData, "person data incomplete" unless account_data_complete?(data)
+
+        wf = allocate
+        wf.instance_eval {
+          @acct_uri    = data[:acct_uri]
+          @alias_url   = data[:alias_url]
+          @hcard_url   = data[:hcard_url]
+          @seed_url    = data[:seed_url]
+          @profile_url = data[:profile_url]
+          @atom_url    = data[:atom_url]
+          @salmon_url  = data[:salmon_url]
+
+          # TODO: remove me!  #########
+          @guid        = data[:guid]
+          @pubkey      = data[:pubkey]
+          #############################
+        }
+        wf
+      end
+
+      # Create a WebFinger instance from the given XML string.
+      # @param [String] webfinger_xml WebFinger XML string
+      # @return [WebFinger] WebFinger instance
+      # @raise [InvalidData] if the given XML string is invalid or incomplete
+      def self.from_xml(webfinger_xml)
+        data = parse_xml_and_validate(webfinger_xml)
+
+        hcard_url, seed_url, guid, profile_url, atom_url, salmon_url, pubkey = parse_links(data)
+
+        wf = allocate
+        wf.instance_eval {
+          @acct_uri    = data[:subject]
+          @alias_url   = data[:aliases].first
+          @hcard_url   = hcard_url
+          @seed_url    = seed_url
+          @profile_url = profile_url
+          @atom_url    = atom_url
+          @salmon_url  = salmon_url
+
+          # TODO: remove me!  ##########
+          @guid        = guid
+          @pubkey      = Base64.strict_decode64(pubkey)
+          ##############################
+        }
+        wf
+      end
+
+      private
+
+      # Checks the given account data Hash for correct type and completeness.
+      # @param [Hash] data account data
+      # @return [Boolean] validation result
+      def self.account_data_complete?(data)
+        data.instance_of?(Hash) &&
+          %i(
+            acct_uri alias_url hcard_url seed_url
+            guid profile_url atom_url salmon_url pubkey
+          ).all? {|k| data.key? k }
+      end
+      private_class_method :account_data_complete?
+
+      # Parses the XML string to a Hash and does some rudimentary checking on
+      # the data Hash.
+      # @param [String] webfinger_xml WebFinger XML string
+      # @return [Hash] data XML data
+      # @raise [InvalidData] if the given XML string is invalid or incomplete
+      def self.parse_xml_and_validate(webfinger_xml)
+        data = XrdDocument.xml_data(webfinger_xml)
+        valid = data.key?(:subject) && data.key?(:aliases) && data.key?(:links)
+        raise InvalidData, "webfinger xml is incomplete" unless valid
+        data
+      end
+      private_class_method :parse_xml_and_validate
+
+      def add_links_to(doc)
+        doc.links << {rel:  REL_HCARD,
+                      type: "text/html",
+                      href: @hcard_url}
+        doc.links << {rel:  REL_SEED,
+                      type: "text/html",
+                      href: @seed_url}
+
+        # TODO: remove me!  ##############
+        doc.links << {rel:  REL_GUID,
+                      type: "text/html",
+                      href: @guid}
+        ##################################
+
+        doc.links << {rel:  REL_PROFILE,
+                      type: "text/html",
+                      href: @profile_url}
+        doc.links << {rel:  REL_ATOM,
+                      type: "application/atom+xml",
+                      href: @atom_url}
+        doc.links << {rel:  REL_SALMON,
+                      href: @salmon_url}
+
+        # TODO: remove me!  ##############
+        doc.links << {rel:  REL_PUBKEY,
+                      type: "RSA",
+                      href: Base64.strict_encode64(@pubkey)}
+        ##################################
+      end
+
+      def self.parse_links(data)
+        links = data[:links]
+        hcard   = parse_link(links, REL_HCARD)
+        seed    = parse_link(links, REL_SEED)
+        guid    = parse_link(links, REL_GUID)
+        profile = parse_link(links, REL_PROFILE)
+        atom    = parse_link(links, REL_ATOM)
+        salmon  = parse_link(links, REL_SALMON)
+        pubkey  = parse_link(links, REL_PUBKEY)
+        raise InvalidData, "webfinger xml is incomplete" unless [hcard, seed, guid, profile, atom, salmon, pubkey].all?
+        [hcard[:href], seed[:href], guid[:href], profile[:href], atom[:href], salmon[:href], pubkey[:href]]
+      end
+      private_class_method :parse_links
+
+      def self.parse_link(links, rel)
+        links.find {|l| l[:rel] == rel }
+      end
+      private_class_method :parse_link
+    end
+  end
+end

data/lib/diaspora_federation/web_finger/xrd_document.rb

@@ -0,0 +1,181 @@
+module DiasporaFederation
+  module WebFinger
+    ##
+    # This class implements basic handling of XRD documents as far as it is
+    # necessary in the context of the protocols used with Diaspora* federation.
+    #
+    # @note {http://tools.ietf.org/html/rfc6415 RFC 6415} recommends that servers
+    #   should also offer the JRD format in addition to the XRD representation.
+    #   Implementing +XrdDocument#to_json+ and +XrdDocument.json_data+ should
+    #   be almost trivial due to the simplicity of the format and the way the data
+    #   is stored internally already. See
+    #   {http://tools.ietf.org/html/rfc6415#appendix-A RFC 6415, Appendix A}
+    #   for a description of the JSON format.
+    #
+    # @example Creating a XrdDocument
+    #   doc = XrdDocument.new
+    #   doc.expires = DateTime.new(2020, 1, 15, 0, 0, 1)
+    #   doc.subject = "http://example.tld/articles/11"
+    #   doc.aliases << "http://example.tld/cool_article"
+    #   doc.aliases << "http://example.tld/authors/2/articles/3"
+    #   doc.properties["http://x.example.tld/ns/version"] = "1.3"
+    #   doc.links << { rel: "author", type: "text/html", href: "http://example.tld/authors/2" }
+    #   doc.links << { rel: "copyright", template: "http://example.tld/copyright?id={uri}" }
+    #
+    #   doc.to_xml
+    #
+    # @example Parsing a XrdDocument
+    #   data = XrdDocument.xml_data(xml_string)
+    #
+    # @see http://docs.oasis-open.org/xri/xrd/v1.0/xrd-1.0.html Extensible Resource Descriptor (XRD) Version 1.0
+    class XrdDocument
+      # xml namespace url
+      XMLNS = "http://docs.oasis-open.org/ns/xri/xrd-1.0"
+
+      # +Link+ element attributes
+      LINK_ATTRS = %i(rel type href template)
+
+      # format string for datetime (+Expires+ element)
+      DATETIME_FORMAT = "%Y-%m-%dT%H:%M:%SZ"
+
+      # The <Expires> element contains a time value which specifies the instant at
+      # and after which the document has expired and SHOULD NOT be used.
+      # @param [DateTime] value
+      attr_writer :expires
+      # The <Subject> element contains a URI value which identifies the resource
+      # described by this XRD.
+      # @param [String] value
+      attr_writer :subject
+
+      # @return [Array<String>] list of alias URIs
+      attr_reader :aliases
+
+      # @return [Hash<String => mixed>] list of properties. Hash key represents the
+      #   +type+ attribute, and the value is the element content
+      attr_reader :properties
+
+      # @return [Array<Hash<attr => val>>] list of +Link+ element hashes. Each
+      #   hash contains the attributesa and their associated values for the +Link+
+      #   element.
+      attr_reader :links
+
+      def initialize
+        @aliases = []
+        @links = []
+        @properties = {}
+      end
+
+      ##
+      # Generates an XML document from the current instance and returns it as string
+      # @return [String] XML document
+      def to_xml
+        builder = Nokogiri::XML::Builder.new(encoding: "UTF-8") do |xml|
+          xml.XRD("xmlns" => XMLNS) {
+            xml.Expires(@expires.strftime(DATETIME_FORMAT)) if @expires.instance_of?(DateTime)
+
+            xml.Subject(@subject) if !@subject.nil? && !@subject.empty?
+
+            add_aliases_to(xml)
+            add_properties_to(xml)
+            add_links_to(xml)
+          }
+        end
+        builder.to_xml
+      end
+
+      ##
+      # Parse the XRD document from the given string and create a hash containing
+      # the extracted data.
+      #
+      # Small bonus: the hash structure that comes out of this method is the same
+      # as the one used to produce a JRD (JSON Resource Descriptor) or parsing it.
+      #
+      # @param [String] xrd_doc XML string
+      # @return [Hash] extracted data
+      # @raise [InvalidDocument] if the XRD is malformed
+      def self.xml_data(xrd_doc)
+        doc = parse_xrd_document(xrd_doc)
+        data = {}
+
+        exp_elem = doc.at_xpath("xrd:XRD/xrd:Expires", NS)
+        data[:expires] = DateTime.strptime(exp_elem.content, DATETIME_FORMAT) unless exp_elem.nil?
+
+        subj_elem = doc.at_xpath("xrd:XRD/xrd:Subject", NS)
+        data[:subject] = subj_elem.content unless subj_elem.nil?
+
+        parse_aliases_from_xml_doc(doc, data)
+        parse_properties_from_xml_doc(doc, data)
+        parse_links_from_xml_doc(doc, data)
+
+        data
+      end
+
+      private
+
+      NS = {xrd: XMLNS}
+
+      def add_aliases_to(xml)
+        @aliases.each do |a|
+          next if !a.instance_of?(String) || a.empty?
+          xml.Alias(a.to_s)
+        end
+      end
+
+      def add_properties_to(xml)
+        @properties.each do |type, val|
+          xml.Property(val.to_s, type: type)
+        end
+      end
+
+      def add_links_to(xml)
+        @links.each do |l|
+          attrs = {}
+          LINK_ATTRS.each do |attr|
+            attrs[attr.to_s] = l[attr] if l.key?(attr)
+          end
+          xml.Link(attrs)
+        end
+      end
+
+      def self.parse_xrd_document(xrd_doc)
+        raise ArgumentError unless xrd_doc.instance_of?(String)
+
+        doc = Nokogiri::XML::Document.parse(xrd_doc)
+        raise InvalidDocument, "Not an XRD document" if !doc.root || doc.root.name != "XRD"
+        doc
+      end
+      private_class_method :parse_xrd_document
+
+      def self.parse_aliases_from_xml_doc(doc, data)
+        aliases = []
+        doc.xpath("xrd:XRD/xrd:Alias", NS).each do |node|
+          aliases << node.content
+        end
+        data[:aliases] = aliases unless aliases.empty?
+      end
+      private_class_method :parse_aliases_from_xml_doc
+
+      def self.parse_properties_from_xml_doc(doc, data)
+        properties = {}
+        doc.xpath("xrd:XRD/xrd:Property", NS).each do |node|
+          properties[node[:type]] = node.children.empty? ? nil : node.content
+        end
+        data[:properties] = properties unless properties.empty?
+      end
+      private_class_method :parse_properties_from_xml_doc
+
+      def self.parse_links_from_xml_doc(doc, data)
+        links = []
+        doc.xpath("xrd:XRD/xrd:Link", NS).each do |node|
+          link = {}
+          LINK_ATTRS.each do |attr|
+            link[attr] = node[attr.to_s] if node.key?(attr.to_s)
+          end
+          links << link
+        end
+        data[:links] = links unless links.empty?
+      end
+      private_class_method :parse_links_from_xml_doc
+    end
+  end
+end