diaspora_federation 0.0.8 → 0.0.9

data/lib/diaspora_federation/entities/poll.rb

@@ -0,0 +1,24 @@
+module DiasporaFederation
+  module Entities
+    # this entity represents a poll ant it is federated as an optional part of a status message
+    #
+    # @see Validators::PollValidator
+    class Poll < Entity
+      # @!attribute [r] guid
+      #   a random string of at least 16 chars.
+      #   @see Validation::Rule::Guid
+      #   @return [String] poll guid
+      property :guid
+
+      # @!attribute [r] question
+      #   Text of the question posed by a user
+      #   @return [String] question
+      property :question
+
+      # @!attribute [r] poll_answers
+      #   array of possible answer to the poll
+      #   @return [[Entities::PollAnswer]] poll answers
+      entity :poll_answers, [Entities::PollAnswer]
+    end
+  end
+end

data/lib/diaspora_federation/entities/poll_answer.rb

@@ -0,0 +1,19 @@
+module DiasporaFederation
+  module Entities
+    # this entity represents a poll answer and is federated as a part of the Poll entity
+    #
+    # @see Validators::PollAnswerValidator
+    class PollAnswer < Entity
+      # @!attribute [r] guid
+      #   a random string of at least 16 chars.
+      #   @see Validation::Rule::Guid
+      #   @return [String] guid
+      property :guid
+
+      # @!attribute [r] answer
+      #   Text of the answer
+      #   @return [String] answer
+      property :answer
+    end
+  end
+end

data/lib/diaspora_federation/entities/poll_participation.rb

@@ -0,0 +1,28 @@
+module DiasporaFederation
+  module Entities
+    # this entity represents a participation in poll, i.e. it is issued when a user votes for an answer in a poll
+    #
+    # @see Validators::PollParticipationValidator
+    class PollParticipation < Entity
+      # @!attribute [r] guid
+      #   a random string of at least 16 chars.
+      #   @see Validation::Rule::Guid
+      #   @return [String] guid
+      property :guid
+
+      include Relayable
+
+      # @!attribute [r] diaspora_id
+      #   The diaspora ID of the person who voted in the poll
+      #   @see Person#diaspora_id
+      #   @return [String] diaspora ID
+      property :diaspora_id, xml_name: :diaspora_handle
+
+      # @!attribute [r] poll_answer_guid
+      #   guid of the answer selected by the user.
+      #   @see PollAnswer#guid
+      #   @return [String] poll answer guid
+      property :poll_answer_guid
+    end
+  end
+end

data/lib/diaspora_federation/entities/profile.rb

@@ -11,29 +11,31 @@ module DiasporaFederation
       property :diaspora_id, xml_name: :diaspora_handle
 
       # @!attribute [r] first_name
-      #   @deprecated
+      #   @deprecated We decided to only use one name field, these should be removed
+      #     in later iterations (will affect older Diaspora* installations).
       #   @see #full_name
-      #   @see HCard#first_name
+      #   @see Discovery::HCard#first_name
       #   @return [String] first name
       property :first_name, default: nil
 
       # @!attribute [r] last_name
-      #   @deprecated
+      #   @deprecated We decided to only use one name field, these should be removed
+      #     in later iterations (will affect older Diaspora* installations).
       #   @see #full_name
-      #   @see HCard#last_name
+      #   @see Discovery::HCard#last_name
       #   @return [String] last name
       property :last_name, default: nil
 
       # @!attribute [r] image_url
-      #   @see HCard#photo_large_url
+      #   @see Discovery::HCard#photo_large_url
       #   @return [String] url to the big avatar (300x300)
       property :image_url, default: nil
       # @!attribute [r] image_url_medium
-      #   @see HCard#photo_medium_url
+      #   @see Discovery::HCard#photo_medium_url
       #   @return [String] url to the medium avatar (100x100)
       property :image_url_medium, default: nil
       # @!attribute [r] image_url_small
-      #   @see HCard#photo_small_url
+      #   @see Discovery::HCard#photo_small_url
       #   @return [String] url to the small avatar (50x50)
       property :image_url_small, default: nil
 
@@ -43,7 +45,7 @@ module DiasporaFederation
       property :location, default: nil
 
       # @!attribute [r] searchable
-      #   @see HCard#searchable
+      #   @see Discovery::HCard#searchable
       #   @return [Boolean] searchable flag
       property :searchable, default: true
 

data/lib/diaspora_federation/entities/relayable.rb

@@ -0,0 +1,101 @@
+module DiasporaFederation
+  module Entities
+    # this is a module that defines common properties for relayable entities
+    # which include Like, Comment, Participation, Message, etc. Each relayable
+    # has a parent, identified by guid. Relayables also are signed and signing/verificating
+    # logic is embedded into Salmon XML processing code.
+    module Relayable
+      # on inclusion of this module the required properties for a relayable are added to the object that includes it
+      #
+      # @!attribute [r] parent_guid
+      #   @see StatusMessage#guid
+      #   @return [String] parent guid
+      #
+      # @!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 required only when federation from upstream (parent) post author to
+      #   downstream subscribers. This is the case when the parent author has to resend a relayable
+      #   received from one of his subscribers to all others.
+      #
+      #   @return [String] parent author signature
+      #
+      # @!attribute [r] author_signature
+      #   Contains a signature of the entity using the private key of the author of a post itself.
+      #   The presence of this signature is mandatory. Without it the entity won't be accepted by
+      #   a target pod.
+      #   @return [String] author signature
+      #
+      # @param [Entity] entity the entity in which it is included
+      def self.included(entity)
+        entity.class_eval do
+          property :parent_guid
+          property :parent_author_signature, default: nil
+          property :author_signature, default: nil
+        end
+      end
+
+      # Generates XML and updates signatures
+      # @see Entity#to_xml
+      # @return [Nokogiri::XML::Element] root element containing properties as child elements
+      def to_xml
+        entity_xml.tap do |xml|
+          hash = to_h
+          Relayable.update_signatures!(hash)
+
+          xml.at_xpath("author_signature").content = hash[:author_signature]
+          xml.at_xpath("parent_author_signature").content = hash[:parent_author_signature]
+        end
+      end
+
+      # Exception raised when verify_signatures fails to verify signatures (signatures are wrong)
+      class SignatureVerificationFailed < ArgumentError
+      end
+
+      # verifies the signatures (+author_signature+ and +parent_author_signature+ if needed)
+      # @param [Hash] data hash with data to verify
+      # @raise [SignatureVerificationFailed] if the signature is not valid or no public key is found
+      def self.verify_signatures(data)
+        pkey = DiasporaFederation.callbacks.trigger(:fetch_public_key_by_diaspora_id, data[:diaspora_id])
+        raise SignatureVerificationFailed, "failed to fetch public key for #{data[:diaspora_id]}" if pkey.nil?
+        raise SignatureVerificationFailed, "wrong author_signature" unless Signing.verify_signature(
+          data, data[:author_signature], pkey
+        )
+
+        author_is_local = DiasporaFederation.callbacks.trigger(:entity_author_is_local?, "Post", data[:parent_guid])
+        verify_parent_signature(data) unless author_is_local
+      end
+
+      # this happens only on downstream federation
+      # @param [Hash] data hash with data to verify
+      def self.verify_parent_signature(data)
+        pkey = DiasporaFederation.callbacks.trigger(:fetch_author_public_key_by_entity_guid, "Post", data[:parent_guid])
+        raise SignatureVerificationFailed,
+              "failed to fetch public key for author of #{data[:parent_guid]}" if pkey.nil?
+        raise SignatureVerificationFailed, "wrong parent_author_signature" unless Signing.verify_signature(
+          data, data[:parent_author_signature], pkey
+        )
+      end
+      private_class_method :verify_parent_signature
+
+      # Adds signatures to a given hash with the keys of the author and the parent
+      # if the signatures are not in the hash yet and if the keys are available.
+      #
+      # @param [Hash] data hash given for a signing
+      def self.update_signatures!(data)
+        if data[:author_signature].nil?
+          pkey = DiasporaFederation.callbacks.trigger(:fetch_private_key_by_diaspora_id, data[:diaspora_id])
+          data[:author_signature] = Signing.sign_with_key(data, pkey) unless pkey.nil?
+        end
+
+        if data[:parent_author_signature].nil?
+          pkey = DiasporaFederation.callbacks.trigger(
+            :fetch_author_private_key_by_entity_guid,
+            "Post",
+            data[:parent_guid]
+          )
+          data[:parent_author_signature] = Signing.sign_with_key(data, pkey) unless pkey.nil?
+        end
+      end
+    end
+  end
+end

data/lib/diaspora_federation/entities/relayable_retraction.rb

@@ -0,0 +1,95 @@
+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 himself. In this case only target_author_signature
+    # is filled and retraction is sent to the commented post's author. Here
+    # he (upstream object owner) signes it with parent's author key and fills
+    # signature in parent_author_signature and sends it to other pods where
+    # other participating people 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 himself - he has a right to delete comments on his 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 federation from an upstream author to the subscribers.
+      #   @see Relayable#parent_author_signature
+      #   @return [String] parent author signature
+      property :parent_author_signature, default: nil
+
+      # @!attribute [r] target_guid
+      #   guid of a relayable to be deleted
+      #   @see Comment#guid
+      #   @return [String] target guid
+      property :target_guid
+
+      # @!attribute [r] target_type
+      #   a string describing a type of the target
+      #   @see Retraction#target_type
+      #   @return [String] target type
+      property :target_type
+
+      # @!attribute [r] diaspora_id
+      #   The diaspora ID of the person who deletes a relayable
+      #   @see Person#diaspora_id
+      #   @return [String] diaspora ID
+      property :diaspora_id, 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, default: nil
+
+      # Generates XML and updates signatures
+      # @see Entity#to_xml
+      # @return [Nokogiri::XML::Element] root element containing properties as child elements
+      def to_xml
+        entity_xml.tap do |xml|
+          hash = to_h
+          RelayableRetraction.update_signatures!(hash)
+          xml.at_xpath("target_author_signature").content = hash[:target_author_signature]
+          xml.at_xpath("parent_author_signature").content = hash[:parent_author_signature]
+        end
+      end
+
+      # Adds signatures to a given hash with the keys of the author and the parent
+      # if the signatures are not in the hash yet and if the keys are available.
+      #
+      # @param [Hash] hash hash given for a signing
+      def self.update_signatures!(hash)
+        target_author = DiasporaFederation.callbacks.trigger(
+          :fetch_entity_author_id_by_guid,
+          hash[:target_type],
+          hash[:target_guid]
+        )
+        pkey = DiasporaFederation.callbacks.trigger(:fetch_private_key_by_diaspora_id, hash[:diaspora_id])
+
+        fill_required_signature(target_author, pkey, hash) unless pkey.nil?
+      end
+
+      def self.fill_required_signature(target_author, pkey, hash)
+        if target_author == hash[:diaspora_id] && hash[:target_author_signature].nil?
+          hash[:target_author_signature] =
+            Signing.sign_with_key(SignedRetraction.apply_signable_exceptions(hash), pkey)
+        elsif target_author != hash[:diaspora_id] && hash[:parent_author_signature].nil?
+          hash[:parent_author_signature] =
+            Signing.sign_with_key(SignedRetraction.apply_signable_exceptions(hash), pkey)
+        end
+      end
+      private_class_method :fill_required_signature
+    end
+  end
+end

data/lib/diaspora_federation/entities/request.rb

@@ -0,0 +1,21 @@
+module DiasporaFederation
+  module Entities
+    # this entity represents a sharing request for a user. A user issues it
+    # when he starts sharing with another user.
+    #
+    # @see Validators::RequestValidator
+    class Request < Entity
+      # @!attribute [r] sender_id
+      #   The diaspora ID of the person who shares his profile
+      #   @see Person#diaspora_id
+      #   @return [String] sender ID
+      property :sender_id, xml_name: :sender_handle
+
+      # @!attribute [r] recipient_id
+      #   The diaspora ID of the person who will be shared with
+      #   @see Person#diaspora_id
+      #   @return [String] recipient ID
+      property :recipient_id, xml_name: :recipient_handle
+    end
+  end
+end

data/lib/diaspora_federation/entities/reshare.rb

@@ -0,0 +1,49 @@
+module DiasporaFederation
+  module Entities
+    # this entity represents the fact the a user reshared some other user's post
+    #
+    # @see Validators::ReshareValidator
+    class Reshare < Entity
+      # @!attribute [r] diaspora_id
+      #   The diaspora ID of the person who posted the original post
+      #   @see Person#diaspora_id
+      #   @return [String] diaspora ID
+      property :root_diaspora_id # inconsistent, everywhere else it's "handle"
+
+      # @!attribute [r] root_guid
+      #   guid of the original post
+      #   @see StatusMessage#guid
+      #   @return [String] root guid
+      property :root_guid
+
+      # @!attribute [r] guid
+      #   a random string of at least 16 chars.
+      #   @see Validation::Rule::Guid
+      #   @see StatusMessage#guid
+      #   @return [String] guid
+      property :guid
+
+      # @!attribute [r] diaspora_id
+      #   The diaspora ID of the person who reshares a post
+      #   @see Person#diaspora_id
+      #   @return [String] diaspora ID
+      property :diaspora_id, xml_name: :diaspora_handle
+
+      # @!attribute [r] public
+      #   has no meaning at the moment
+      #   @return [Boolean] public
+      property :public, default: true # always true? (we only reshare public posts)
+
+      # @!attribute [r] created_at
+      #   reshare entity creation time
+      #   @return [Time] creation time
+      property :created_at, default: -> { Time.now.utc }
+
+      # @!attribute [r] provider_display_name
+      #   a string that describes a means by which a user has posted the reshare
+      #   @see StatusMessage#provider_display_name
+      #   @return [String] provider display name
+      property :provider_display_name, default: nil
+    end
+  end
+end

data/lib/diaspora_federation/entities/retraction.rb

@@ -0,0 +1,24 @@
+module DiasporaFederation
+  module Entities
+    # this entity represents a claim of deletion of a previously federated entity
+    #
+    # @see Validators::RetractionValidator
+    class Retraction < Entity
+      # @!attribute [r] target_guid
+      #   guid of the entity to be deleted
+      #   @return [String] target guid
+      property :target_guid, xml_name: :post_guid
+
+      # @!attribute [r] diaspora_id
+      #   The diaspora ID of the person who deletes the entity
+      #   @see Person#diaspora_id
+      #   @return [String] diaspora ID
+      property :diaspora_id, xml_name: :diaspora_handle
+
+      # @!attribute [r] target_type
+      #   A string describing the type of the target.
+      #   @return [String] target type
+      property :target_type, xml_name: :type
+    end
+  end
+end

data/lib/diaspora_federation/entities/signed_retraction.rb

@@ -0,0 +1,66 @@
+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
+
+      # @!attribute [r] target_type
+      #   A string describing the type of the target.
+      #   @see Retraction#target_type
+      #   @return [String] target type
+      property :target_type
+
+      # @!attribute [r] diaspora_id
+      #   The diaspora ID of the person who deletes a post
+      #   @see Person#diaspora_id
+      #   @return [String] diaspora ID
+      property :diaspora_id, 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, default: nil
+
+      # Generates XML and updates signatures
+      # @see Entity#to_xml
+      # @return [Nokogiri::XML::Element] root element containing properties as child elements
+      def to_xml
+        entity_xml.tap do |xml|
+          hash = to_h
+          SignedRetraction.update_signatures!(hash)
+
+          xml.at_xpath("target_author_signature").content = hash[:target_author_signature]
+        end
+      end
+
+      # Adds signature to a given hash with the key of the author
+      # if the signature is not in the hash yet and if the key is available.
+      #
+      # @param [Hash] data hash given for a signing
+      def self.update_signatures!(data)
+        if data[:target_author_signature].nil?
+          pkey = DiasporaFederation.callbacks.trigger(:fetch_private_key_by_diaspora_id, data[:diaspora_id])
+          data[:target_author_signature] = Signing.sign_with_key(apply_signable_exceptions(data), pkey) unless pkey.nil?
+        end
+      end
+
+      # Deletes :diaspora_id (xml_name: sender_handle) from the hash in order to compute
+      # a signature since it is included from signable_string for SignedRetraction and RelayableRetraction
+      #
+      # @param [Hash] data hash of the retraction properties
+      # @return [Hash] hash copy without :diaspora_id member
+      def self.apply_signable_exceptions(data)
+        data.dup.tap {|data| data.delete(:diaspora_id) }
+      end
+    end
+  end
+end