diaspora_federation 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 35ffb28db27478325eaf2f2d61290b125f2e20e2
+  data.tar.gz: cfaca21b0289d178044895bbb91326b51520fed7
+SHA512:
+  metadata.gz: 0ef15d9756b8174572d54d926388e8dffbeabea94f342ceb62ef536f5c52f6c9003e904b208c22a277c4c4906c1723ea7bf7f82181dae3726a9b5aeaa51b77a0
+  data.tar.gz: 1e77ba30e7745f64927b58ab0c110fa9467f0b8981e539ce24500754d5a61f548ac63e362c84ad5cfb7b6bbbca92ac065b1aa1e4a9debf1599150dbad27a1f5b

data/LICENSE

@@ -0,0 +1,18 @@
+Diaspora Federation Rails Engine
+Copyright (C) 2015  Benjamin Neff
+
+This program is free software: you can redistribute it and/or modify
+it under the terms of the GNU Affero General Public License as
+published by the Free Software Foundation, either version 3 of the
+License, or (at your option) any later version.
+
+This program is distributed in the hope that it will be useful,
+but WITHOUT ANY WARRANTY; without even the implied warranty of
+MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+GNU Affero General Public License for more details.
+
+You should have received a copy of the GNU Affero General Public License
+along with this program.  If not, see <http://www.gnu.org/licenses/>.
+
+Some parts are based on an older federation gem from Florian Staudacher:
+https://github.com/Raven24/diaspora-federation

data/README.md

@@ -0,0 +1,18 @@
+# diaspora* federation rails engine
+
+#### A rails engine that adds the diaspora* federation protocol to a rails app
+
+[![Build Status](https://travis-ci.org/SuperTux88/diaspora_federation.svg?branch=master)](https://travis-ci.org/SuperTux88/diaspora_federation)
+[![Code Climate](https://codeclimate.com/github/SuperTux88/diaspora_federation/badges/gpa.svg)](https://codeclimate.com/github/SuperTux88/diaspora_federation)
+[![Test Coverage](https://codeclimate.com/github/SuperTux88/diaspora_federation/badges/coverage.svg)](https://codeclimate.com/github/SuperTux88/diaspora_federation/coverage)
+[![Dependency Status](https://gemnasium.com/SuperTux88/diaspora_federation.svg)](https://gemnasium.com/SuperTux88/diaspora_federation)
+[![Inline docs](https://inch-ci.org/github/SuperTux88/diaspora_federation.svg?branch=master)](https://inch-ci.org/github/SuperTux88/diaspora_federation)
+
+[Documentation](http://www.rubydoc.info/github/SuperTux88/diaspora_federation/master) |
+[Project site](https://diasporafoundation.org) |
+[Wiki](https://wiki.diasporafoundation.org) |
+[Bugtracker](https://github.com/SuperTux88/diaspora_federation/issues)
+
+## License
+
+This gem is published under the terms of the "GNU Affero General Public License". See the LICENSE file for the exact wording.

data/Rakefile

@@ -0,0 +1,26 @@
+begin
+  require "bundler/setup"
+rescue LoadError
+  puts "You must `gem install bundler` and `bundle install` to run rake tasks"
+end
+
+require "rdoc/task"
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = "rdoc"
+  rdoc.title    = "DiasporaFederation"
+  rdoc.options << "--line-numbers"
+  rdoc.rdoc_files.include("lib/**/*.rb")
+end
+
+APP_RAKEFILE = File.expand_path("../test/dummy/Rakefile", __FILE__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+Bundler::GemHelper.install_tasks
+
+Rails.application.load_tasks
+
+task test: %w(spec:prepare spec)
+task default: :test

data/app/controllers/diaspora_federation/application_controller.rb

@@ -0,0 +1,6 @@
+module DiasporaFederation
+  ##
+  # Base-Controller for all DiasporaFederation-Controller
+  class ApplicationController < ActionController::Base
+  end
+end

data/app/controllers/diaspora_federation/h_card_controller.rb

@@ -0,0 +1,20 @@
+require_dependency "diaspora_federation/application_controller"
+
+module DiasporaFederation
+  ##
+  # this controller generates the hcard
+  class HCardController < ApplicationController
+    ##
+    # returns the hcard of the user
+    #
+    # GET /hcard/users/:guid
+    def hcard
+      person = DiasporaFederation.person_class.find_local_by_guid(params[:guid])
+
+      return render nothing: true, status: 404 if person.nil?
+
+      logger.info "hcard profile request for: #{person.diaspora_handle}"
+      render html: WebFinger::HCard.from_profile(person.hcard_profile_hash).to_html.html_safe
+    end
+  end
+end

data/app/controllers/diaspora_federation/receive_controller.rb

@@ -0,0 +1,35 @@
+require_dependency "diaspora_federation/application_controller"
+
+module DiasporaFederation
+  ##
+  # this controller processes receiving messages
+  class ReceiveController < ApplicationController
+    before_action :check_for_xml
+
+    ##
+    # receives public messages
+    #
+    # POST /receive/public
+    def public
+      logger.info "received a public message"
+      logger.debug CGI.unescape(params[:xml])
+      render nothing: true, status: :ok
+    end
+
+    ##
+    # receives private messages for a user
+    #
+    # POST /receive/users/:guid
+    def private
+      logger.info "received a private message for #{params[:guid]}"
+      logger.debug CGI.unescape(params[:xml])
+      render nothing: true, status: :ok
+    end
+
+    private
+
+    def check_for_xml
+      render nothing: true, status: 422 if params[:xml].nil?
+    end
+  end
+end

data/app/controllers/diaspora_federation/webfinger_controller.rb

@@ -0,0 +1,60 @@
+require_dependency "diaspora_federation/application_controller"
+
+module DiasporaFederation
+  ##
+  # this controller handles all webfinger-specific requests
+  class WebfingerController < ApplicationController
+    ##
+    # returns the host-meta xml
+    #
+    # example:
+    #   <?xml version="1.0" encoding="UTF-8"?>
+    #   <XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0">
+    #        <Link rel="lrdd" type="application/xrd+xml" template="https://server.example/webfinger?q={uri}"/>
+    #   </XRD>
+    #
+    # GET /.well-known/host-meta
+    def host_meta
+      render body: WebfingerController.host_meta_xml, content_type: "application/xrd+xml"
+    end
+
+    ##
+    # @deprecated this is the pre RFC 7033 webfinger
+    #
+    # example:
+    #   <?xml version="1.0" encoding="UTF-8"?>
+    #   <XRD xmlns="http://docs.oasis-open.org/ns/xri/xrd-1.0">
+    #     <Subject>acct:alice@localhost:3000</Subject>
+    #     <Alias>http://localhost:3000/people/c8e87290f6a20132963908fbffceb188</Alias>
+    #     <Link rel="http://microformats.org/profile/hcard" type="text/html" href="http://localhost:3000/hcard/users/c8e87290f6a20132963908fbffceb188"/>
+    #     <Link rel="http://joindiaspora.com/seed_location" type="text/html" href="http://localhost:3000/"/>
+    #     <Link rel="http://joindiaspora.com/guid" type="text/html" href="c8e87290f6a20132963908fbffceb188"/>
+    #     <Link rel="http://webfinger.net/rel/profile-page" type="text/html" href="http://localhost:3000/u/alice"/>
+    #     <Link rel="http://schemas.google.com/g/2010#updates-from" type="application/atom+xml" href="http://localhost:3000/public/alice.atom"/>
+    #     <Link rel="salmon" href="http://localhost:3000/receive/users/c8e87290f6a20132963908fbffceb188"/>
+    #     <Link rel="diaspora-public-key" type="RSA" href="LS0tLS1CRU......"/>
+    #   </XRD>
+    # GET /webfinger?q=<uri>
+    def legacy_webfinger
+      person = find_person(params[:q]) if params[:q]
+
+      return render nothing: true, status: 404 if person.nil?
+
+      logger.info "webfinger profile request for: #{person.diaspora_handle}"
+      render body: WebFinger::WebFinger.from_person(person.webfinger_hash).to_xml, content_type: "application/xrd+xml"
+    end
+
+    private
+
+    ##
+    # creates the host-meta xml with the configured server_uri and caches it
+    # @return [String] XML string
+    def self.host_meta_xml
+      @host_meta_xml ||= WebFinger::HostMeta.from_base_url(DiasporaFederation.server_uri.to_s).to_xml
+    end
+
+    def find_person(query)
+      DiasporaFederation.person_class.find_local_by_diaspora_handle(query.strip.downcase.gsub("acct:", ""))
+    end
+  end
+end

data/config/routes.rb

@@ -0,0 +1,15 @@
+DiasporaFederation::Engine.routes.draw do
+  controller :receive do
+    post "receive-new/public"      => :public,  :as => "receive_public"
+    post "receive-new/users/:guid" => :private, :as => "receive_private"
+  end
+
+  controller :webfinger do
+    get ".well-known/host-meta" => :host_meta,        :as => "host_meta"
+    get "webfinger"             => :legacy_webfinger, :as => "legacy_webfinger"
+  end
+
+  controller :h_card do
+    get "hcard/users/:guid" => :hcard, :as => "hcard"
+  end
+end

data/lib/diaspora_federation.rb

@@ -0,0 +1,120 @@
+require "diaspora_federation/engine"
+require "diaspora_federation/logging"
+
+require "diaspora_federation/web_finger"
+
+##
+# diaspora* federation rails engine
+module DiasporaFederation
+  extend Logging
+
+  class << self
+    ##
+    # the pod url
+    #
+    # Example:
+    #   config.server_uri = URI("http://localhost:3000/")
+    # or
+    #   config.server_uri = AppConfig.pod_uri
+    attr_accessor :server_uri
+
+    ##
+    # the class to use as +Person+
+    #
+    # Example:
+    #   config.person_class = Person.to_s
+    #
+    # This class must have the following methods:
+    #
+    # *find_local_by_diaspora_handle*
+    # This should return a +Person+, which is on this pod and the account is not closed.
+    #
+    # *find_local_by_guid*
+    # This should return a +Person+, which is on this pod and the account is not closed.
+    #
+    # *webfinger_hash*
+    # This should return a +Hash+ with the following information:
+    #   {
+    #     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-----"
+    #   }
+    #
+    # *hcard_profile_hash*
+    # This should return a +Hash+ with the following information:
+    #   {
+    #     guid:             "0123456789abcdef",
+    #     nickname:         "user",
+    #     full_name:        "User Name",
+    #     url:              "https://server.example/",
+    #     photo_large_url:  "https://server.example/uploads/f.jpg",
+    #     photo_medium_url: "https://server.example/uploads/m.jpg",
+    #     photo_small_url:  "https://server.example/uploads/s.jpg",
+    #     pubkey:           "-----BEGIN PUBLIC KEY-----\nABCDEF==\n-----END PUBLIC KEY-----",
+    #     searchable:       true,
+    #     first_name:       "User",
+    #     last_name:        "Name"
+    #   }
+    attr_accessor :person_class
+    def person_class
+      const_get(@person_class)
+    end
+
+    ##
+    # configure the federation engine
+    #
+    #   DiasporaFederation.configure do |config|
+    #     config.server_uri = "http://localhost:3000/"
+    #   end
+    def configure
+      yield self
+    end
+
+    ##
+    # validates if the engine is configured correctly
+    #
+    # called from after_initialize
+    # @raise [ConfigurationError] if the configuration is incomplete or invalid
+    def validate_config
+      configuration_error "missing server_uri" unless @server_uri.respond_to? :host
+      validate_class(@person_class, "person_class", %i(
+        find_local_by_diaspora_handle
+        find_local_by_guid
+        webfinger_hash
+        hcard_profile_hash
+      ))
+      logger.info "successfully configured the federation engine"
+    end
+
+    private
+
+    def validate_class(klass, name, methods)
+      configuration_error "missing #{name}" unless klass
+      entity = const_get(klass)
+
+      return logger.warn "table for #{entity} doesn't exist, skip validation" unless entity.table_exists?
+
+      methods.each {|method| entity_respond_to?(entity, name, method) }
+    end
+
+    def entity_respond_to?(entity, name, method)
+      valid = entity.respond_to?(method) || entity.column_names.include?(method.to_s) || entity.method_defined?(method)
+      configuration_error "the configured class #{entity} for #{name} doesn't respond to #{method}" unless valid
+    end
+
+    def configuration_error(message)
+      logger.fatal("diaspora federation configuration error: #{message}")
+      raise ConfigurationError, message
+    end
+  end
+
+  # raised, if the engine is not configured correctly
+  class ConfigurationError < RuntimeError
+  end
+end

data/lib/diaspora_federation/engine.rb

@@ -0,0 +1,15 @@
+module DiasporaFederation
+  ##
+  # diaspora* federation rails engine
+  class Engine < ::Rails::Engine
+    isolate_namespace DiasporaFederation
+
+    config.generators do |g|
+      g.test_framework :rspec
+    end
+
+    config.after_initialize do
+      DiasporaFederation.validate_config
+    end
+  end
+end

data/lib/diaspora_federation/logging.rb

@@ -0,0 +1,25 @@
+module DiasporaFederation
+  ##
+  # logging module for the diaspora federation engine
+  #
+  # it uses the logging-gem if available
+  module Logging
+    private
+
+    ##
+    # get the logger for this class
+    #
+    # use the logging-gem if available, else use a default logger
+    def logger
+      @logger ||= begin
+                    # use logging-gem if available
+                    return ::Logging::Logger[self] if Object.const_defined?("::Logging::Logger")
+
+                    # fallback logger
+                    @logger = Logger.new(STDOUT)
+                    @logger.level = Logger.const_get(Rails.configuration.log_level.to_s.upcase)
+                    @logger
+                  end
+    end
+  end
+end

data/lib/diaspora_federation/version.rb

@@ -0,0 +1,5 @@
+module DiasporaFederation
+  ##
+  # the gem version
+  VERSION = "0.0.1"
+end

data/lib/diaspora_federation/web_finger.rb

@@ -0,0 +1,14 @@
+module DiasporaFederation
+  ##
+  # This module provides the namespace for the various classes implementing
+  # WebFinger and other protocols used for metadata discovery on remote servers
+  # in the Diaspora* network.
+  module WebFinger
+  end
+end
+
+require "diaspora_federation/web_finger/exceptions"
+require "diaspora_federation/web_finger/xrd_document"
+require "diaspora_federation/web_finger/host_meta"
+require "diaspora_federation/web_finger/web_finger"
+require "diaspora_federation/web_finger/h_card"

data/lib/diaspora_federation/web_finger/exceptions.rb

@@ -0,0 +1,19 @@
+module DiasporaFederation
+  module WebFinger
+    ##
+    # Raised, if the XML structure is invalid
+    class InvalidDocument < RuntimeError
+    end
+
+    ##
+    # Raised, if something is wrong with the webfinger data
+    #
+    # * if the +webfinger_url+ is missing or malformed in {HostMeta.from_base_url} or {HostMeta.from_xml}
+    # * if the +data+ given to {WebFinger.from_person} is an invalid type or doesn't contain all required entries
+    # * if the parsed XML from {WebFinger.from_xml} is incomplete
+    # * if the params passed to {HCard.from_profile} or {HCard.from_html}
+    #   are in some way malformed, invalid or incomplete.
+    class InvalidData < RuntimeError
+    end
+  end
+end

data/lib/diaspora_federation/web_finger/h_card.rb

@@ -0,0 +1,319 @@
+module DiasporaFederation
+  module WebFinger
+    ##
+    # This class provides the means of generating an parsing account data to and
+    # from the hCard format.
+    # hCard is based on +RFC 2426+ (vCard) which got superseded by +RFC 6350+.
+    # There is a draft for a new h-card format specification, that makes use of
+    # the new vCard standard.
+    #
+    # @note The current implementation contains a huge amount of legacy elements
+    #   and classes, that should be removed and cleaned up in later iterations.
+    #
+    # @todo This needs some radical restructuring. The generated HTML is not
+    #   correctly nested according to the hCard standard and class names are
+    #   partially wrong. Also, apart from that, it's just ugly.
+    #
+    # @example Creating a hCard document from account data
+    #   hc = HCard.from_profile({
+    #     guid:             "0123456789abcdef",
+    #     nickname:         "user",
+    #     full_name:        "User Name",
+    #     url:              "https://server.example/",
+    #     photo_large_url:  "https://server.example/uploads/l.jpg",
+    #     photo_medium_url: "https://server.example/uploads/m.jpg",
+    #     photo_small_url:  "https://server.example/uploads/s.jpg",
+    #     pubkey:           "-----BEGIN PUBLIC KEY-----\nABCDEF==\n-----END PUBLIC KEY-----",
+    #     searchable:       true,
+    #     first_name:       "User",
+    #     last_name:        "Name"
+    #   })
+    #   html_string = hc.to_html
+    #
+    # @example Create a HCard instance from an hCard document
+    #   hc = HCard.from_html(html_string)
+    #   ...
+    #   full_name = hc.full_name
+    #   ...
+    #
+    # @see http://microformats.org/wiki/hCard "hCard 1.0"
+    # @see http://microformats.org/wiki/h-card "h-card" (draft)
+    # @see http://www.ietf.org/rfc/rfc2426.txt "vCard MIME Directory Profile" (obsolete)
+    # @see http://www.ietf.org/rfc/rfc6350.txt "vCard Format Specification"
+    class HCard
+      private_class_method :new
+
+      # 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
+
+      # the first part of the diaspora handle
+      # @return [String] nickname
+      attr_reader :nickname
+
+      # @return [String] display name of the user
+      attr_reader :full_name
+
+      # @deprecated should be changed to the profile url. The pod url is in
+      #   the WebFinger (see {WebFinger#seed_url}, will affect older Diaspora*
+      #   installations).
+      #
+      # @return [String] link to the pod
+      attr_reader :url
+
+      # 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
+
+      # @return [String] url to the big avatar (300x300)
+      attr_reader :photo_large_url
+      # @return [String] url to the medium avatar (100x100)
+      attr_reader :photo_medium_url
+      # @return [String] url to the small avatar (50x50)
+      attr_reader :photo_small_url
+
+      # @deprecated We decided to only use one name field, these should be removed
+      #   in later iterations (will affect older Diaspora* installations).
+      #
+      # @see #full_name
+      # @return [String] first name
+      attr_reader :first_name
+
+      # @deprecated We decided to only use one name field, these should be removed
+      #   in later iterations (will affect older Diaspora* installations).
+      #
+      # @see #full_name
+      # @return [String] last name
+      attr_reader :last_name
+
+      # @deprecated As this is a simple property, consider move to WebFinger instead
+      #   of HCard. vCard has no comparable field for this information, but
+      #   Webfinger may declare arbitrary properties (will affect older Diaspora*
+      #   installations).
+      #
+      # flag if a user is searchable by name
+      # @return [Boolean] searchable flag
+      attr_reader :searchable
+
+      # CSS selectors for finding all the hCard fields
+      SELECTORS = {
+        uid:          ".uid",
+        nickname:     ".nickname",
+        fn:           ".fn",
+        given_name:   ".given_name",
+        family_name:  ".family_name",
+        url:          "#pod_location[href]",
+        photo:        ".entity_photo .photo[src]",
+        photo_medium: ".entity_photo_medium .photo[src]",
+        photo_small:  ".entity_photo_small .photo[src]",
+        key:          ".key",
+        searchable:   ".searchable"
+      }
+
+      # Create the HTML string from the current HCard instance
+      # @return [String] HTML string
+      def to_html
+        builder = create_builder
+
+        content = builder.doc.at_css("#content_inner")
+
+        add_simple_property(content, :uid, "uid", @guid)
+        add_simple_property(content, :nickname, "nickname", @nickname)
+        add_simple_property(content, :full_name, "fn", @full_name)
+        add_simple_property(content, :searchable, "searchable", @searchable)
+
+        add_property(content, :key) do |html|
+          html.pre(@pubkey.to_s, class: "key")
+        end
+
+        # TODO: remove me!  ###################
+        add_simple_property(content, :first_name, "given_name", @first_name)
+        add_simple_property(content, :family_name, "family_name", @last_name)
+        #######################################
+
+        add_property(content, :url) do |html|
+          html.a(@url.to_s, id: "pod_location", class: "url", rel: "me", href: @url.to_s)
+        end
+
+        add_photos(content)
+
+        builder.doc.to_xhtml(indent: 2, indent_text: " ")
+      end
+
+      # Creates a new HCard instance from the given Hash containing profile data
+      # @param [Hash] data account data
+      # @return [HCard] HCard instance
+      # @raise [InvalidData] if the account data Hash is invalid or incomplete
+      def self.from_profile(data)
+        raise InvalidData unless account_data_complete?(data)
+
+        hc = allocate
+        hc.instance_eval {
+          @guid             = data[:guid]
+          @nickname         = data[:nickname]
+          @full_name        = data[:full_name]
+          @url              = data[:url]
+          @photo_large_url   = data[:photo_large_url]
+          @photo_medium_url = data[:photo_medium_url]
+          @photo_small_url  = data[:photo_small_url]
+          @pubkey           = data[:pubkey]
+          @searchable       = data[:searchable]
+
+          # TODO: remove me!  ###################
+          @first_name       = data[:first_name]
+          @last_name        = data[:last_name]
+          #######################################
+        }
+        hc
+      end
+
+      # Creates a new HCard instance from the given HTML string.
+      # @param html_string [String] HTML string
+      # @return [HCard] HCard instance
+      # @raise [InvalidData] if the HTML string is invalid or incomplete
+      def self.from_html(html_string)
+        doc = parse_html_and_validate(html_string)
+
+        hc = allocate
+        hc.instance_eval {
+          @guid             = content_from_doc(doc, :uid)
+          @nickname         = content_from_doc(doc, :nickname)
+          @full_name        = content_from_doc(doc, :fn)
+          @url              = element_from_doc(doc, :url)["href"]
+          @photo_large_url  = photo_from_doc(doc, :photo)
+          @photo_medium_url = photo_from_doc(doc, :photo_medium)
+          @photo_small_url  = photo_from_doc(doc, :photo_small)
+          @pubkey           = content_from_doc(doc, :key) unless element_from_doc(doc, :key).nil?
+          @searchable       = content_from_doc(doc, :searchable) == "true"
+
+          # TODO: change me!  ###################
+          @first_name       = content_from_doc(doc, :given_name)
+          @last_name        = content_from_doc(doc, :family_name)
+          #######################################
+        }
+        hc
+      end
+
+      private
+
+      # Creates the base HCard html structure
+      # @return [Nokogiri::HTML::Builder] HTML Builder instance
+      def create_builder
+        Nokogiri::HTML::Builder.new do |html|
+          html.html {
+            html.head {
+              html.meta(charset: "UTF-8")
+              html.title(@full_name)
+            }
+
+            html.body {
+              html.div(id: "content") {
+                html.h1(@full_name)
+                html.div(id: "content_inner", class: "entity_profile vcard author") {
+                  html.h2("User profile")
+                }
+              }
+            }
+          }
+        end
+      end
+
+      # Add a property to the hCard document. The element will be added to the given
+      # container element and a "definition list" structure will be created around
+      # it. A Nokogiri::HTML::Builder instance will be passed to the given block,
+      # which should be used to add the element(s) containing the property data.
+      #
+      # @param container [Nokogiri::XML::Element] parent element for added property HTML
+      # @param name [Symbol] property name
+      # @param block [Proc] block returning an element
+      def add_property(container, name, &block)
+        Nokogiri::HTML::Builder.with(container) do |html|
+          html.dl(class: "entity_#{name}") {
+            html.dt(name.to_s.capitalize)
+            html.dd {
+              block.call(html)
+            }
+          }
+        end
+      end
+
+      # Calls {HCard#add_property} for a simple text property.
+      # @param container [Nokogiri::XML::Element] parent element
+      # @param name [Symbol] property name
+      # @param class_name [String] HTML class name
+      # @param value [#to_s] property value
+      # @see HCard#add_property
+      def add_simple_property(container, name, class_name, value)
+        add_property(container, name) do |html|
+          html.span(value.to_s, class: class_name)
+        end
+      end
+
+      # Calls {HCard#add_property} to add the photos
+      # @param container [Nokogiri::XML::Element] parent element
+      # @see HCard#add_property
+      def add_photos(container)
+        add_property(container, :photo) do |html|
+          html.img(class: "photo avatar", width: "300", height: "300", src: @photo_large_url.to_s)
+        end
+
+        add_property(container, :photo_medium) do |html|
+          html.img(class: "photo avatar", width: "100", height: "100", src: @photo_medium_url.to_s)
+        end
+
+        add_property(container, :photo_small) do |html|
+          html.img(class: "photo avatar", width: "50", height: "50", src: @photo_small_url.to_s)
+        end
+      end
+
+      # 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(
+            guid nickname full_name url
+            photo_large_url photo_medium_url photo_small_url
+            pubkey searchable first_name last_name
+          ).all? {|k| data.key? k }
+      end
+      private_class_method :account_data_complete?
+
+      # Make sure some of the most important elements are present in the parsed
+      # HTML document.
+      # @param [LibXML::XML::Document] doc HTML document
+      # @return [Boolean] validation result
+      def self.html_document_complete?(doc)
+        !(doc.at_css(SELECTORS[:fn]).nil? || doc.at_css(SELECTORS[:nickname]).nil? ||
+          doc.at_css(SELECTORS[:url]).nil? || doc.at_css(SELECTORS[:photo]).nil?)
+      end
+      private_class_method :html_document_complete?
+
+      def self.parse_html_and_validate(html_string)
+        raise ArgumentError, "hcard html is not a string" unless html_string.instance_of?(String)
+
+        doc = Nokogiri::HTML::Document.parse(html_string)
+        raise InvalidData, "hcard html incomplete" unless html_document_complete?(doc)
+        doc
+      end
+      private_class_method :parse_html_and_validate
+
+      def element_from_doc(doc, selector)
+        doc.at_css(SELECTORS[selector])
+      end
+
+      def content_from_doc(doc, content_selector)
+        element_from_doc(doc, content_selector).content
+      end
+
+      def photo_from_doc(doc, photo_selector)
+        element_from_doc(doc, photo_selector)["src"]
+      end
+    end
+  end
+end