lotus 0.0.12

data/lib/lotus/generator.rb

@@ -0,0 +1,53 @@
+module Lotus
+  # The generator element identifies the agent used to generate the feed.
+  class Generator
+    # Holds the base URI for relative URIs contained in uri.
+    attr_reader :base
+
+    # Holds the language of the name, when it exists. The language
+    # should be specified as RFC 3066 as either 2 or 3 letter codes.
+    # For example: 'en' for English or more specifically 'en-us'
+    attr_reader :lang
+
+    # Holds the optional uri that SHOULD produce a representation that is
+    # relevant to the agent.
+    attr_reader :uri
+
+    # Holds the optional string identifying the version of the generating
+    # agent.
+    attr_reader :version
+
+    # Holds the string that provides a human-readable name that identifies
+    # the generating agent. The content of this field is language sensitive.
+    attr_reader :name
+
+    # Creates a representation of a generator.
+    #
+    # options:
+    #   :base    => Optional base URI for use with a relative URI in uri.
+    #   :lang    => Optional string identifying the language of the name field.
+    #   :uri     => Optional string identifying the URL that SHOULD produce
+    #               a representation that is relevant to the agent.
+    #   :version => Optional string indicating the version of the generating
+    #               agent.
+    #   :name    => Optional name of the agent.
+    def initialize(options = {})
+      @base    = options[:base]
+      @lang    = options[:lang]
+      @uri     = options[:uri]
+      @version = options[:version]
+      @name    = options[:name]
+    end
+
+    # Yields a hash that represents the generator.
+    def to_hash
+      {
+        :base    => self.base,
+        :lang    => self.lang,
+        :version => self.version,
+        :uri     => self.uri,
+        :name    => self.name
+      }
+    end
+  end
+end

data/lib/lotus/identity.rb

@@ -0,0 +1,59 @@
+module Lotus
+  # Holds information about an Identity. This is more specific to identifying
+  # an Author than that structure. It is generally hosted in one place and
+  # not replicated. It holds identifying information that allow you to
+  # ensure verification of communication with the author.
+  class Identity
+    # Holds the public key for this identity.
+    attr_reader :public_key
+
+    # Holds the salmon endpoint used for direct notifications for this
+    # identity.
+    attr_reader :salmon_endpoint
+
+    # Holds the dialback endpoint used for capability transfer and
+    # authentication for this identity.
+    attr_reader :dialback_endpoint
+
+    # Holds the activity streams inbox endpoint for this identity.
+    attr_reader :activity_inbox_endpoint
+
+    # Holds the activity streams outbox endpoint for this identity.
+    attr_reader :activity_outbox_endpoint
+
+    # Holds the url to this identity's profile.
+    attr_reader :profile_page
+
+    # Create an instance of an Identity.
+    #
+    # options:
+    #   :public_key               => The identity's public key.
+    #   :salmon_endpoint          => The salmon endpoint for this identity.
+    #   :dialback_endpoint        => The dialback endpoint for this identity.
+    #   :activity_inbox_endpoint  => The activity streams inbox for this
+    #                                identity.
+    #   :activity_outbox_endpoint => The activity streams outbox for this
+    #                                identity.
+    #   :profile_page             => The url for this identity's profile page.
+    def initialize(options = {})
+      @public_key               = options[:public_key]
+      @salmon_endpoint          = options[:salmon_endpoint]
+      @dialback_endpoint        = options[:dialback_endpoint]
+      @activity_inbox_endpoint  = options[:activity_inbox_endpoint]
+      @activity_outbox_endpoint = options[:activity_outbox_endpoint]
+      @profile_page             = options[:profile_page]
+    end
+
+    # Returns a hash of the properties of the identity.
+    def to_hash
+      {
+        :public_key               => self.public_key,
+        :salmon_endpoint          => self.salmon_endpoint,
+        :dialback_endpoint        => self.dialback_endpoint,
+        :activity_inbox_endpoint  => self.activity_inbox_endpoint,
+        :activity_outbox_endpoint => self.activity_outbox_endpoint,
+        :profile_page             => self.profile_page
+      }
+    end
+  end
+end

data/lib/lotus/link.rb

@@ -0,0 +1,56 @@
+module Lotus
+  require 'atom'
+
+  class Link
+    # The URL for the related resource.
+    attr_reader :href
+
+    # A string indicating the relationship type with the current
+    # document.
+    #
+    # Standard:
+    #   "alternate" = Signifies that the URL in href identifies an alternative
+    #                 version of the resource described by the containing
+    #                 element.
+    #   "related"   = Signifies that the URL in href identifies a resource that
+    #                 is related to the contained resource. For example, the
+    #                 feed for a site that discusses the performance of the
+    #                 search engine at "http://search.example.com" might
+    #                 contain, as a link of Feed, a related link to that
+    #                 "http://search.example.com".
+    #   "self"      = Signifies that href contains a URL to the containing
+    #                 resource.
+    #   "enclosure" = Signifies that the URL in href identifies a related
+    #                 resource that is potentially large in size and
+    #                 require special handling. SHOULD use the length field.
+    #   "via"       = Signifies that the URL in href identifies a resource that
+    #                 is the source of the information provided in the
+    #                 containing element.
+    attr_reader :rel
+
+    # Advises to the content MIME type of the linked resource.
+    attr_reader :type
+
+    # Advises to the language of the linked resource. When used with
+    # rel="alternate" it depicts a translated version of the entry.
+    # Use with a RFC3066 language tag.
+    attr_reader :hreflang
+
+    # Conveys human-readable information about the linked resource.
+    attr_reader :title
+
+    # Advises the length of the linked content in number of bytes. It is simply
+    # a hint about the length based upon prior information. It may change, and
+    # cannot override the actual content length.
+    attr_reader :length
+
+    def initialize(options = {})
+      @href     = options[:href]
+      @rel      = options[:rel]
+      @type     = options[:type]
+      @hreflang = options[:hreflang]
+      @title    = options[:title]
+      @length   = options[:length]
+    end
+  end
+end

data/lib/lotus/notification.rb

@@ -0,0 +1,220 @@
+module Lotus
+  # This represents a notification that can be sent to a server when you wish
+  # to send information to a server that has not yet subscribed to you. Since
+  # this implies a lack of trust, a notification adds a layer so that the
+  # recipiant can verify the message contents.
+  class Notification
+    require 'xml'
+    require 'digest/sha2'
+
+    attr_reader :activity
+
+    # Create an instance for a particular Lotus::Activity.
+    def initialize activity, signature = nil, plaintext = nil
+      @activity = activity
+      @signature = signature
+      @plaintext = plaintext
+    end
+
+    # Creates an activity for following a particular Author.
+    def self.from_follow(user_author, followed_author)
+      activity = Lotus::Activity.new(
+        :verb => :follow,
+        :object => followed_author,
+        :actor    => user_author,
+        :title    => "Now following #{followed_author.name}",
+        :content  => "Now following #{followed_author.name}",
+        :content_type => "html"
+      )
+
+      self.new(activity)
+    end
+
+    # Creates an activity for unfollowing a particular Author.
+    def self.from_unfollow(user_author, followed_author)
+      activity = Lotus::Activity.new(
+        :verb => "http://ostatus.org/schema/1.0/unfollow",
+        :object => followed_author,
+        :actor    => user_author,
+        :title => "Stopped following #{followed_author.name}",
+        :content => "Stopped following #{followed_author.name}",
+        :content_type => "html"
+      )
+
+      self.new(activity)
+    end
+
+    # Creates an activity for a profile update.
+    def self.from_profile_update(user_author)
+      activity = Lotus::Activity.new(
+        :verb => "http://ostatus.org/schema/1.0/update-profile",
+        :actor    => user_author,
+        :title => "#{user_author.name} changed their profile information.",
+        :content => "#{user_author.name} changed their profile information.",
+        :content_type => "html"
+      )
+
+      self.new(activity)
+    end
+
+    # Will pull a Lotus::Activity from the given payload and MIME type.
+    def self.from_data(content, content_type)
+      case content_type
+      when 'xml',
+           'magic-envelope+xml',
+           'application/xml',
+           'application/text+xml',
+           'application/magic-envelope+xml'
+        self.from_xml content
+      when 'json',
+           'magic-envelope+json',
+           'application/json',
+           'application/text+json',
+           'application/magic-envelope+json'
+        self.from_json content
+      end
+    end
+
+    # Will pull a Lotus::Activity from a magic envelope described by the JSON.
+    def self.from_json(source)
+    end
+
+    # Will pull a Lotus::Activity from a magic envelope described by the XML.
+    def self.from_xml(source)
+      if source.is_a?(String)
+        if source.length == 0
+          return nil
+        end
+
+        source = XML::Document.string(source,
+                                      :options => XML::Parser::Options::NOENT)
+      else
+        return nil
+      end
+
+      # Retrieve the envelope
+      envelope = source.find('/me:env',
+                             'me:http://salmon-protocol.org/ns/magic-env').first
+
+      return nil unless envelope
+
+      data = envelope.find('me:data',
+                           'me:http://salmon-protocol.org/ns/magic-env').first
+      return nil unless data
+
+      data_type = data.attributes["type"]
+      if data_type.nil?
+        data_type = 'application/atom+xml'
+        armored_data_type = ''
+      else
+        armored_data_type = Base64::urlsafe_encode64(data_type)
+      end
+
+      encoding = envelope.find('me:encoding',
+                               'me:http://salmon-protocol.org/ns/magic-env').first
+
+      algorithm = envelope.find(
+                          'me:alg',
+                          'me:http://salmon-protocol.org/ns/magic-env').first
+
+      signature = source.find('me:sig',
+                           'me:http://salmon-protocol.org/ns/magic-env').first
+
+      # Parse fields
+
+      # Well, if we cannot verify, we don't accept
+      return nil unless signature
+
+      # XXX: Handle key_id attribute
+      signature = signature.content
+      signature = Base64::urlsafe_decode64(signature)
+
+      if encoding.nil?
+        # When the encoding is omitted, use base64url
+        # Cite: Magic Envelope Draft Spec Section 3.3
+        armored_encoding = ''
+        encoding = 'base64url'
+      else
+        armored_encoding = Base64::urlsafe_encode64(encoding.content)
+        encoding = encoding.content.downcase
+      end
+
+      if algorithm.nil?
+        # When algorithm is omitted, use 'RSA-SHA256'
+        # Cite: Magic Envelope Draft Spec Section 3.3
+        armored_algorithm = ''
+        algorithm = 'rsa-sha256'
+      else
+        armored_algorithm = Base64::urlsafe_encode64(algorithm.content)
+        algorithm = algorithm.content.downcase
+      end
+
+      # Retrieve and decode data payload
+
+      data = data.content
+      armored_data = data
+
+      case encoding
+      when 'base64url'
+        data = Base64::urlsafe_decode64(data)
+      else
+        # Unsupported data encoding
+        return nil
+      end
+
+      # Signature plaintext
+      plaintext = "#{armored_data}.#{armored_data_type}.#{armored_encoding}.#{armored_algorithm}"
+
+      # Interpret data payload
+      payload = XML::Reader.string(data)
+      self.new Lotus::Atom::Entry.new(payload).to_canonical, signature, plaintext
+    end
+
+    # Generate the xml for this notice and sign with the given private key.
+    def to_xml private_key
+      # Generate magic envelope
+      magic_envelope = XML::Document.new
+
+      magic_envelope.root = XML::Node.new 'env'
+
+      me_ns = XML::Namespace.new(magic_envelope.root,
+                   'me', 'http://salmon-protocol.org/ns/magic-env')
+
+      magic_envelope.root.namespaces.namespace = me_ns
+
+      # Armored Data <me:data>
+      data = @activity.to_atom
+      @plaintext = data
+      data_armored = Base64::urlsafe_encode64(data)
+      elem = XML::Node.new 'data', data_armored, me_ns
+      elem.attributes['type'] = 'application/atom+xml'
+      data_type_armored = 'YXBwbGljYXRpb24vYXRvbSt4bWw='
+      magic_envelope.root << elem
+
+      # Encoding <me:encoding>
+      magic_envelope.root << XML::Node.new('encoding', 'base64url', me_ns)
+      encoding_armored = 'YmFzZTY0dXJs'
+
+      # Signing Algorithm <me:alg>
+      magic_envelope.root << XML::Node.new('alg', 'RSA-SHA256', me_ns)
+      algorithm_armored = 'UlNBLVNIQTI1Ng=='
+
+      # Signature <me:sig>
+      plaintext =
+        "#{data_armored}.#{data_type_armored}.#{encoding_armored}.#{algorithm_armored}"
+
+      # Assign @signature to the signature generated from the plaintext
+      @signature = Lotus::Crypto.emsa_sign(plaintext, private_key)
+
+      signature_armored = Base64::urlsafe_encode64(@signature)
+      magic_envelope.root << XML::Node.new('sig', signature_armored, me_ns)
+
+      magic_envelope.to_s :indent => true, :encoding => XML::Encoding::UTF_8
+    end
+
+    # Check the origin of this notification.
+    def verified? key
+      Lotus::Crypto.emsa_verify(@plaintext, @signature, key)
+    end
+  end
+end

data/lib/lotus/publisher.rb

@@ -0,0 +1,40 @@
+module Lotus
+  class Publisher
+    require 'net/http'
+    require 'uri'
+
+    # The url of the feed.
+    attr_reader :url
+
+    # The array of feed urls used to push content. Default: []
+    attr_reader :hubs
+
+    # Creates a representation of a Publisher entity.
+    #
+    # options:
+    #   :feed => A feed to use to populate the other fields.
+    #   :url  => The url of the feed that will be published.
+    #   :hubs => An array of hub urls that are used to handle load
+    #            balancing pushes of new data. Default: []
+    def initialize(options = {})
+      if options[:feed]
+        @url  = options[:feed].url
+        @hubs = options[:feed].hubs
+      end
+
+      @url  ||= options[:url]
+      @hubs ||= options[:hubs] || []
+    end
+
+    # Will ping PuSH hubs so that they know there is new/updated content. The
+    # hub should respond by pulling the new data and then sending it to
+    # subscribers.
+    def ping_hubs
+      @hubs.each do |hub_url|
+        res = Net::HTTP.post_form(URI.parse(hub_url),
+                                  { 'hub.mode' => 'publish',
+                                    'hub.url' => @topic_url })
+      end
+    end
+  end
+end

data/lib/lotus/subscription.rb

@@ -0,0 +1,117 @@
+module Lotus
+  class Subscription
+    require 'net/http'
+    require 'uri'
+    require 'base64'
+    require 'hmac-sha1'
+
+    # The url that should be used to handle subscription handshakes.
+    attr_reader :callback_url
+
+    # The url of the feed one wishes to subscribe to.
+    attr_reader :topic_url
+
+    # The hub this subscription is made with.
+    attr_reader :hub
+
+    # Creates a representation of a subscription.
+    #
+    # options:
+    #   :callback_url => The url that should be used to handle subscription
+    #                    handshakes.
+    #   :topic_url    => The url of the feed one wishes to subscribe to.
+    #   :secret       => A secret that will be passed to the callback to better
+    #                    verify that communication is not replayed. Default:
+    #                    A secure random hex.
+    #   :hubs         => A list of hubs to negotiate the subscription with.
+    #                    Default: attempts to discover the hubs when it
+    #                    subscribes for the first time.
+    #   :hub          => The hub we have a subscription with already.
+    def initialize(options = {})
+      @tokens = []
+
+      secret = options[:secret] || SecureRandom.hex(32)
+      @secret = secret.to_s
+
+      @callback_url = options[:callback_url]
+      @topic_url    = options[:topic_url]
+      @tokens << options[:token] if options[:token]
+
+      @hubs = options[:hubs] || []
+
+      @hub  = options[:hub]
+    end
+
+    # Actively searches for hubs by talking to publisher directly
+    def discover_hubs_for_topic
+      @hubs = Lotus.feed_from_url(self.topic_url).hubs
+    end
+
+    # Subscribe to the topic through the given hub.
+    def subscribe
+      return unless self.hub.nil?
+
+      # Discover hubs if none exist
+      @hubs = discover_hubs_for_topic(self.topic_url) if self.hubs.empty?
+      @hub = self.hubs.first
+      change_subscription(:subscribe, token)
+
+      # TODO: Check response, if failed, try a different hub
+    end
+
+    # Unsubscribe to the topic.
+    def unsubscribe
+      return if self.hub.nil?
+
+      change_subscription(:unsubscribe)
+    end
+
+    # Change our subscription to this topic at a hub.
+    # mode:    Either :subscribe or :unsubscribe
+    # hub_url: The url of the hub to negotiate with
+    # token:   A token to verify the response from the hub.
+    def change_subscription(mode)
+      token ||= SecureRandom.hex(32)
+      @tokens << token.to_s
+
+      # TODO: Set up HTTPS foo
+      res = Net::HTTP.post_form(URI.parse(self.hub),
+                                {
+                                  'hub.mode' => mode.to_s,
+                                  'hub.callback' => @callback_url,
+                                  'hub.verify' => 'async',
+                                  'hub.verify_token' => token,
+                                  'hub.lease_seconds' => '',
+                                  'hub.secret' => @secret,
+                                  'hub.topic' => @topic_url
+                                })
+    end
+
+    # Verify that a subscription response is valid.
+    def verify_subscription(token)
+      # Is there a token?
+      result = @tokens.include?(token)
+
+      # Ensure we cannot reuse the token
+      @tokens.delete(token)
+
+      result
+    end
+
+    # Determines if the given body matches the signature.
+    def verify_content(body, signature)
+      hmac = HMAC::SHA1.hexdigest(@secret, body)
+      check = "sha1=" + hmac
+      check == signature
+    end
+
+    # Gives the content of a challenge response given the challenge
+    # body.
+    def challenge_response(challenge_code)
+      {
+        :body => challenge_code,
+        :status => 200
+      }
+    end
+  end
+end