diaspora_federation 0.2.7 → 1.0.0

data/lib/diaspora_federation/validators/rules/guid.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Validation
   module Rule
     # GUID validation rule
@@ -9,7 +11,7 @@ module Validation
     # Special chars aren't allowed at the end.
     class Guid
       # Allowed chars to validate a GUID with a regex
-      VALID_CHARS = "[0-9A-Za-z\\-_@.:]{15,254}[0-9A-Za-z]".freeze
+      VALID_CHARS = "[0-9A-Za-z\\-_@.:]{15,254}[0-9A-Za-z]"
 
       # The error key for this rule
       # @return [Symbol] error key

data/lib/diaspora_federation/validators/rules/not_nil.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Validation
   module Rule
     # Validates that a property is not +nil+

data/lib/diaspora_federation/validators/rules/public_key.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Validation
   module Rule
     # Public key validation rule

data/lib/diaspora_federation/validators/rules/tag_count.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module Validation
   module Rule
     # Rule for validating the number of tags in a string.

data/lib/diaspora_federation/validators/status_message_validator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DiasporaFederation
   module Validators
     # This validates a {Entities::StatusMessage}.

data/lib/diaspora_federation/validators/web_finger_validator.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 module DiasporaFederation
   module Validators
     # This validates a {Discovery::WebFinger}.

data/lib/diaspora_federation/validators.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "validation"
 require "validation/rule/regular_expression"
 require "validation/rule/length"

data/lib/diaspora_federation/version.rb

@@ -1,4 +1,6 @@
+# frozen_string_literal: true
+
 module DiasporaFederation
   # the gem version
-  VERSION = "0.2.7".freeze
+  VERSION = "1.0.0"
 end

data/lib/diaspora_federation.rb

@@ -1,3 +1,5 @@
+# frozen_string_literal: true
+
 require "nokogiri"
 require "openssl"
 
@@ -182,13 +184,11 @@ module DiasporaFederation
     # queue_public_receive
     #   Queue a public salmon xml to process in background
     #   @param [String] data salmon slap xml or magic envelope xml
-    #   @param [Boolean] legacy true if it is a legacy salmon slap, false if it is a magic envelope xml
     #
     # queue_private_receive
     #   Queue a private salmon xml to process in background
     #   @param [String] guid guid of the receiver person
     #   @param [String] data salmon slap xml or encrypted magic envelope json
-    #   @param [Boolean] legacy true if it is a legacy salmon slap, false if it is a encrypted magic envelope json
     #   @return [Boolean] true if successful, false if the user was not found
     #
     # receive_entity
@@ -256,6 +256,7 @@ module DiasporaFederation
       configuration_error "http_timeout: please configure a number" unless @http_timeout.is_a?(Integer)
 
       return unless !@http_verbose.is_a?(TrueClass) && !@http_verbose.is_a?(FalseClass)
+
       configuration_error "http_verbose: please configure a boolean"
     end
 

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: diaspora_federation
 version: !ruby/object:Gem::Version
-  version: 0.2.7
+  version: 1.0.0
 platform: ruby
 authors:
 - Benjamin Neff
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2021-10-24 00:00:00.000000000 Z
+date: 2022-07-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: faraday
@@ -16,40 +16,34 @@ dependencies:
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: '1.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 0.9.0
+        version: '1.0'
     - - "<"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '3'
 - !ruby/object:Gem::Dependency
-  name: faraday_middleware
+  name: faraday-follow_redirects
   requirement: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.10.0
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '0.3'
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: 0.10.0
-    - - "<"
+    - - "~>"
       - !ruby/object:Gem::Version
-        version: '1.0'
+        version: '0.3'
 - !ruby/object:Gem::Dependency
   name: nokogiri
   requirement: !ruby/object:Gem::Requirement
@@ -116,7 +110,6 @@ files:
 - lib/diaspora_federation/discovery/discovery.rb
 - lib/diaspora_federation/discovery/exceptions.rb
 - lib/diaspora_federation/discovery/h_card.rb
-- lib/diaspora_federation/discovery/host_meta.rb
 - lib/diaspora_federation/discovery/web_finger.rb
 - lib/diaspora_federation/discovery/xrd_document.rb
 - lib/diaspora_federation/entities.rb
@@ -142,12 +135,9 @@ files:
 - lib/diaspora_federation/entities/profile.rb
 - lib/diaspora_federation/entities/related_entity.rb
 - lib/diaspora_federation/entities/relayable.rb
-- lib/diaspora_federation/entities/relayable_retraction.rb
-- lib/diaspora_federation/entities/request.rb
 - lib/diaspora_federation/entities/reshare.rb
 - lib/diaspora_federation/entities/retraction.rb
 - lib/diaspora_federation/entities/signable.rb
-- lib/diaspora_federation/entities/signed_retraction.rb
 - lib/diaspora_federation/entities/status_message.rb
 - lib/diaspora_federation/entity.rb
 - lib/diaspora_federation/federation.rb
@@ -172,11 +162,8 @@ files:
 - lib/diaspora_federation/salmon.rb
 - lib/diaspora_federation/salmon/aes.rb
 - lib/diaspora_federation/salmon/encrypted_magic_envelope.rb
-- lib/diaspora_federation/salmon/encrypted_slap.rb
 - lib/diaspora_federation/salmon/exceptions.rb
 - lib/diaspora_federation/salmon/magic_envelope.rb
-- lib/diaspora_federation/salmon/slap.rb
-- lib/diaspora_federation/salmon/xml_payload.rb
 - lib/diaspora_federation/validators.rb
 - lib/diaspora_federation/validators/account_deletion_validator.rb
 - lib/diaspora_federation/validators/account_migration_validator.rb
@@ -216,23 +203,24 @@ files:
 homepage: https://github.com/diaspora/diaspora_federation
 licenses:
 - AGPL-3.0
-metadata: {}
+metadata:
+  rubygems_mfa_required: 'true'
 post_install_message:
 rdoc_options: []
 require_paths:
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
-  - - "~>"
+  - - ">="
     - !ruby/object:Gem::Version
-      version: '2.1'
+      version: '2.7'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.9
+rubygems_version: 3.3.7
 signing_key:
 specification_version: 4
 summary: diaspora* federation library

data/lib/diaspora_federation/discovery/host_meta.rb

@@ -1,90 +0,0 @@
-module DiasporaFederation
-  module Discovery
-    # 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
-
-      # Creates a new host-meta instance
-      # @param [String] webfinger_url the webfinger-url
-      def initialize(webfinger_url)
-        @webfinger_url = webfinger_url
-      end
-
-      # URL fragment to append to the base URL
-      WEBFINGER_SUFFIX = "/.well-known/webfinger.xml?resource={uri}".freeze
-
-      # 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.
-      # @param [String, URL] base_url the base-url for the webfinger-url
-      # @return [HostMeta]
-      # @raise [InvalidData] if the webfinger url is malformed
-      def self.from_base_url(base_url)
-        webfinger_url = "#{base_url.to_s.chomp('/')}#{WEBFINGER_SUFFIX}"
-        raise InvalidData, "invalid webfinger url: #{webfinger_url}" unless webfinger_url_valid?(webfinger_url)
-
-        new(webfinger_url)
-      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)
-
-        new(webfinger_url)
-      end
-
-      # Applies some basic sanity-checking to the given URL
-      # @param [String] url validation subject
-      # @return [Boolean] validation result
-      private_class_method def self.webfinger_url_valid?(url)
-        !url.nil? && url.instance_of?(String) && url =~ %r{\Ahttps?:\/\/.*\/.*\{uri\}.*}i
-      end
-
-      # Gets the webfinger url from an XRD data structure
-      # @param [Hash] data extracted data
-      # @return [String] webfinger url
-      private_class_method def self.webfinger_url_from_xrd(data)
-        link = data[:links].find {|l| l[:rel] == "lrdd" }
-        return link[:template] unless link.nil?
-      end
-    end
-  end
-end

data/lib/diaspora_federation/entities/relayable_retraction.rb

@@ -1,66 +0,0 @@
-module DiasporaFederation
-  module Entities
-    # This entity represents a claim of deletion of a previously federated
-    # relayable entity. ({Entities::Comment}, {Entities::Like})
-    #
-    # There are two cases of federation of the RelayableRetraction.
-    # Retraction from the dowstream object owner is when an author of the
-    # relayable (e.g. Comment) deletes it themself. In this case only target_author_signature
-    # is filled and a retraction is sent to the commented post's author. Here
-    # the upstream object owner signs it with the parent's author key, puts
-    # the signature in parent_author_signature and sends it to other pods where
-    # other participating people are present. This is the second case - retraction
-    # from the upstream object owner.
-    # Retraction from the upstream object owner can also be performed by the
-    # upstream object owner themself - they have a right to delete comments on their posts.
-    # In any case in the retraction by the upstream author target_author_signature
-    # is not checked, only parent_author_signature is checked.
-    #
-    # @see Validators::RelayableRetractionValidator
-    # @deprecated will be replaced with {Entities::Retraction}
-    class RelayableRetraction < Entity
-      # @!attribute [r] parent_author_signature
-      #   Contains a signature of the entity using the private key of the author of a parent post.
-      #   This signature is mandatory only when federating from an upstream author to the subscribers.
-      #   @see Relayable#parent_author_signature
-      #   @return [String] parent author signature
-      property :parent_author_signature, :string, default: nil
-
-      # @!attribute [r] target_guid
-      #   Guid of a relayable to be deleted
-      #   @see Comment#guid
-      #   @return [String] target guid
-      property :target_guid, :string
-
-      # @!attribute [r] target_type
-      #   A string describing a type of the target
-      #   @see Retraction#target_type
-      #   @return [String] target type
-      property :target_type, :string
-
-      # @!attribute [r] author
-      #   The diaspora* ID of the person who deletes a relayable
-      #   @see Person#author
-      #   @return [String] diaspora* ID
-      property :author, :string, xml_name: :sender_handle
-
-      # @!attribute [r] target_author_signature
-      #   Contains a signature of the entity using the private key of the
-      #   author of a federated relayable entity. ({Entities::Comment}, {Entities::Like})
-      #   This signature is mandatory only when federation from the subscriber to an upstream
-      #   author is done.
-      #   @see Relayable#author_signature
-      #   @return [String] target author signature
-      property :target_author_signature, :string, default: nil
-
-      def initialize(*)
-        raise "Sending RelayableRetraction is not supported anymore! Use Retraction instead!"
-      end
-
-      # @return [Retraction] instance
-      def self.from_hash(hash)
-        Retraction.from_hash(hash)
-      end
-    end
-  end
-end

data/lib/diaspora_federation/entities/request.rb

@@ -1,31 +0,0 @@
-module DiasporaFederation
-  module Entities
-    # This entity represents a sharing request for a user. A user issues it
-    # when they start sharing with another user.
-    #
-    # @see Validators::RequestValidator
-    # @deprecated will be replaced with {Contact}
-    class Request < Entity
-      # @!attribute [r] author
-      #   The diaspora* ID of the person who share their profile
-      #   @see Person#author
-      #   @return [String] sender ID
-      property :author, :string, xml_name: :sender_handle
-
-      # @!attribute [r] recipient
-      #   The diaspora* ID of the person who will be shared with
-      #   @see Validation::Rule::DiasporaId
-      #   @return [String] recipient ID
-      property :recipient, :string, xml_name: :recipient_handle
-
-      def initialize(*)
-        raise "Sending Request is not supported anymore! Use Contact instead!"
-      end
-
-      # @return [Retraction] instance
-      def self.from_hash(hash)
-        Contact.new(hash)
-      end
-    end
-  end
-end

data/lib/diaspora_federation/entities/signed_retraction.rb

@@ -1,43 +0,0 @@
-module DiasporaFederation
-  module Entities
-    # This entity represents a claim of deletion of a previously federated
-    # entity of post type. ({Entities::StatusMessage})
-    #
-    # @see Validators::SignedRetractionValidator
-    # @deprecated will be replaced with {Entities::Retraction}
-    class SignedRetraction < Entity
-      # @!attribute [r] target_guid
-      #   Guid of a post to be deleted
-      #   @see Retraction#target_guid
-      #   @return [String] target guid
-      property :target_guid, :string
-
-      # @!attribute [r] target_type
-      #   A string describing the type of the target
-      #   @see Retraction#target_type
-      #   @return [String] target type
-      property :target_type, :string
-
-      # @!attribute [r] author
-      #   The diaspora* ID of the person who deletes a post
-      #   @see Person#author
-      #   @return [String] diaspora* ID
-      property :author, :string, xml_name: :sender_handle
-
-      # @!attribute [r] author_signature
-      #   Contains a signature of the entity using the private key of the author of a post
-      #   This signature is mandatory.
-      #   @return [String] author signature
-      property :target_author_signature, :string, default: nil
-
-      def initialize(*)
-        raise "Sending SignedRetraction is not supported anymore! Use Retraction instead!"
-      end
-
-      # @return [Retraction] instance
-      def self.from_hash(hash)
-        Retraction.from_hash(hash)
-      end
-    end
-  end
-end

data/lib/diaspora_federation/salmon/encrypted_slap.rb

@@ -1,109 +0,0 @@
-require "json"
-
-module DiasporaFederation
-  module Salmon
-    # +EncryptedSlap+ provides class methods for generating and parsing encrypted
-    # Slaps. (In principle the same as {Slap}, but with encryption.)
-    #
-    # The basic encryption mechanism used here is based on the knowledge that
-    # asymmetrical encryption is slow and symmetrical encryption is fast. Keeping in
-    # mind that a message we want to de-/encrypt may greatly vary in length,
-    # performance considerations must play a part of this scheme.
-    #
-    # A diaspora*-flavored encrypted magic-enveloped XML message looks like the following:
-    #
-    #   <?xml version="1.0" encoding="UTF-8"?>
-    #   <diaspora xmlns="https://joindiaspora.com/protocol" xmlns:me="http://salmon-protocol.org/ns/magic-env">
-    #     <encrypted_header>{encrypted_header}</encrypted_header>
-    #     {magic_envelope with encrypted data}
-    #   </diaspora>
-    #
-    # The encrypted header is encoded in JSON like this (when in plain text):
-    #
-    #   {
-    #     "aes_key"    => "...",
-    #     "ciphertext" => "..."
-    #   }
-    #
-    # +aes_key+ is encrypted using the recipients public key, and contains the AES
-    # +key+ and +iv+ used to encrypt the +ciphertext+ also encoded as JSON.
-    #
-    #   {
-    #     "key" => "...",
-    #     "iv"  => "..."
-    #   }
-    #
-    # +ciphertext+, once decrypted, contains the +author_id+, +aes_key+ and +iv+
-    # relevant to the decryption of the data in the magic_envelope and the
-    # verification of its signature.
-    #
-    # The decrypted cyphertext has this XML structure:
-    #
-    #   <decrypted_header>
-    #     <iv>{iv}</iv>
-    #     <aes_key>{aes_key}</aes_key>
-    #     <author_id>{author_id}</author_id>
-    #   </decrypted_header>
-    #
-    # Finally, before decrypting the magic envelope payload, the signature should
-    # first be verified.
-    #
-    # @example Parsing a Salmon Slap
-    #   recipient_privkey = however_you_retrieve_the_recipients_private_key()
-    #   entity = EncryptedSlap.from_xml(slap_xml, recipient_privkey).payload
-    #
-    # @deprecated
-    class EncryptedSlap < Slap
-      # Creates a {MagicEnvelope} instance from the data within the given XML string
-      # containing an encrypted payload.
-      #
-      # @param [String] slap_xml encrypted Salmon xml
-      # @param [OpenSSL::PKey::RSA] privkey recipient private_key for decryption
-      #
-      # @return [MagicEnvelope] magic envelope instance with payload and sender
-      #
-      # @raise [ArgumentError] if any of the arguments is of the wrong type
-      # @raise [MissingHeader] if the +encrypted_header+ element is missing in the XML
-      # @raise [MissingMagicEnvelope] if the +me:env+ element is missing in the XML
-      def self.from_xml(slap_xml, privkey)
-        raise ArgumentError unless slap_xml.instance_of?(String) && privkey.instance_of?(OpenSSL::PKey::RSA)
-        doc = Nokogiri::XML(slap_xml)
-
-        header_elem = doc.at_xpath("d:diaspora/d:encrypted_header", Slap::NS)
-        raise MissingHeader if header_elem.nil?
-        header = header_data(header_elem.content, privkey)
-        sender = header[:author_id]
-        cipher_params = {key: Base64.decode64(header[:aes_key]), iv: Base64.decode64(header[:iv])}
-
-        MagicEnvelope.unenvelop(magic_env_from_doc(doc), sender, cipher_params)
-      end
-
-      # Decrypts and reads the data from the encrypted XML header
-      # @param [String] data base64 encoded, encrypted header data
-      # @param [OpenSSL::PKey::RSA] privkey private key for decryption
-      # @return [Hash] { iv: "...", aes_key: "...", author_id: "..." }
-      private_class_method def self.header_data(data, privkey)
-        header_elem = decrypt_header(data, privkey)
-        raise InvalidHeader unless header_elem.name == "decrypted_header"
-
-        iv = header_elem.at_xpath("iv").content
-        key = header_elem.at_xpath("aes_key").content
-        author_id = header_elem.at_xpath("author_id").content
-
-        {iv: iv, aes_key: key, author_id: author_id}
-      end
-
-      # Decrypts the xml header
-      # @param [String] data base64 encoded, encrypted header data
-      # @param [OpenSSL::PKey::RSA] privkey private key for decryption
-      # @return [Nokogiri::XML::Element] header xml document
-      private_class_method def self.decrypt_header(data, privkey)
-        cipher_header = JSON.parse(Base64.decode64(data))
-        key = JSON.parse(privkey.private_decrypt(Base64.decode64(cipher_header["aes_key"])))
-
-        xml = AES.decrypt(cipher_header["ciphertext"], Base64.decode64(key["key"]), Base64.decode64(key["iv"]))
-        Nokogiri::XML(xml).root
-      end
-    end
-  end
-end

data/lib/diaspora_federation/salmon/slap.rb

@@ -1,55 +0,0 @@
-module DiasporaFederation
-  module Salmon
-    # +Slap+ provides class methods to create unencrypted Slap XML from payload
-    # data and parse incoming XML into a Slap instance.
-    #
-    # A diaspora* flavored magic-enveloped XML message looks like the following:
-    #
-    #   <?xml version="1.0" encoding="UTF-8"?>
-    #   <diaspora xmlns="https://joindiaspora.com/protocol" xmlns:me="http://salmon-protocol.org/ns/magic-env">
-    #     <header>
-    #       <author_id>{author}</author_id>
-    #     </header>
-    #     {magic_envelope}
-    #   </diaspora>
-    #
-    # @example Parsing a Salmon Slap
-    #   entity = Slap.from_xml(slap_xml).payload
-    #
-    # @deprecated
-    class Slap
-      # Namespaces
-      NS = {d: Salmon::XMLNS, me: MagicEnvelope::XMLNS}.freeze
-
-      # Parses an unencrypted Salmon XML string and returns a new instance of
-      # {MagicEnvelope} with the XML data.
-      #
-      # @param [String] slap_xml Salmon XML
-      #
-      # @return [MagicEnvelope] magic envelope instance with payload and sender
-      #
-      # @raise [ArgumentError] if the argument is not a String
-      # @raise [MissingAuthor] if the +author_id+ element is missing from the XML
-      # @raise [MissingMagicEnvelope] if the +me:env+ element is missing from the XML
-      def self.from_xml(slap_xml)
-        raise ArgumentError unless slap_xml.instance_of?(String)
-        doc = Nokogiri::XML(slap_xml)
-
-        author_elem = doc.at_xpath("d:diaspora/d:header/d:author_id", Slap::NS)
-        raise MissingAuthor if author_elem.nil? || author_elem.content.empty?
-        sender = author_elem.content
-
-        MagicEnvelope.unenvelop(magic_env_from_doc(doc), sender)
-      end
-
-      # Parses the magic envelop from the document.
-      #
-      # @param [Nokogiri::XML::Document] doc Salmon XML Document
-      private_class_method def self.magic_env_from_doc(doc)
-        doc.at_xpath("d:diaspora/me:env", Slap::NS).tap do |env|
-          raise MissingMagicEnvelope if env.nil?
-        end
-      end
-    end
-  end
-end

data/lib/diaspora_federation/salmon/xml_payload.rb

@@ -1,41 +0,0 @@
-module DiasporaFederation
-  module Salmon
-    # +XmlPayload+ provides methods to wrap a XML-serialized {Entity} inside a
-    # common XML structure that will become the payload for federation messages.
-    #
-    # The wrapper looks like so:
-    #   <XML>
-    #     <post>
-    #       {data}
-    #     </post>
-    #   </XML>
-    #
-    # (The +post+ element is there for historic reasons...)
-    # @deprecated
-    module XmlPayload
-      # Extracts the Entity XML from the wrapping XML structure, parses the entity
-      # XML and returns a new instance of the Entity that was packed inside the
-      # given payload.
-      #
-      # @param [Nokogiri::XML::Element] xml payload XML root node
-      # @return [Entity] re-constructed Entity instance
-      # @raise [ArgumentError] if the argument is not an
-      #   {http://www.rubydoc.info/gems/nokogiri/Nokogiri/XML/Element Nokogiri::XML::Element}
-      # @raise [UnknownEntity] if the class for the entity contained inside the
-      #   XML can't be found
-      def self.unpack(xml)
-        raise ArgumentError, "only Nokogiri::XML::Element allowed" unless xml.instance_of?(Nokogiri::XML::Element)
-
-        data = xml_wrapped?(xml) ? xml.at_xpath("post/*[1]") : xml
-
-        Entity.entity_class(data.name).from_xml(data)
-      end
-
-      # @param [Nokogiri::XML::Element] element
-      private_class_method def self.xml_wrapped?(element)
-        (element.name == "XML" && !element.at_xpath("post").nil? &&
-         !element.at_xpath("post").children.empty?)
-      end
-    end
-  end
-end