cogitate 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b72f297200afd3bfebdda28808cde1bd0c23a105
-  data.tar.gz: 2096455e488ce567637e4762e187fa511cd9ac29
+  metadata.gz: bd4f1bc648d721edb5b1d0887b0cd1612182dff4
+  data.tar.gz: a8cd537d72bebc2a4557539220442f7d406409fa
 SHA512:
-  metadata.gz: a7819b9a0cc1b86e7c232f6662182ec5f69fc8e739360f501a0aada1bfef9437e01ee3126dcab49f24db78c8eeb8a7ba47bfdeaa72d37c5691fda7c1134d35d0
-  data.tar.gz: b20bb82409bb415fb3434d3c04ec14ca0b47b81544bb435f506b7026c331f88f1e872ec0c1ad3eaf2045428aa7955ceeae609c9417d2424e044c2bddae57ea4e
+  metadata.gz: 190c6832b7674aaa581f1a0bfc8793c08f3178cb3c69f9b980a9a6098314dd1397046ebcbaa05f29b9bf43bce53d0532643ccc47b7d0d1201656671f85881775
+  data.tar.gz: e04fddd3eddef8e429a87787f400d4184ff97435b8723bb315382f01d70e42bc9d3dedc10ebadf19d9f63791dfe7dc52f2987607b39c8569f8c71402d07ef5aa

data/README.md

@@ -16,6 +16,19 @@ Welcome to Cogitate, a federated identity management system for managing:
   * Parroted identities (ask for the identity of a Kroger Card number, you'll get back a Kroger card number)
 * User authentication through various providers
 
+## Heads Up
+
+Mixed within this repository are two concerns:
+
+* Cogitate Rails application, the core of which is in `app/` though it leverages `lib/` files
+* Cogitate client gem, which is contained within `lib/`
+
+For now these are kept together for ease of application development.
+The cogitate gem can be published via this repository (see cogitate.gemspec) for additional information.
+
+In keeping these together, it is important to understand that files in `lib/` should not reference files in `app/`.
+That is a general best practice, however it is a requirement of the cogitate gem.
+
 ## Documentation and Semantic Versioning
 
 A note on documentation and semantic versioning.
@@ -47,12 +60,24 @@ def method_signature_and_return_value_may_be_changed
 end
 ```
 
+## Authentication
+
+Authentication through Cogitate is a multi-step affair:
+
+1. Client application requests `/authenticate?after_authentication_callback_url=<after_authentication_callback_url>` from Cogitate
+1. Cogitate prompts user to choose authentication mechanism; **At present Cogitate makes the decision and redirects to CAS**
+1. Authentication Service (i.e. CAS, OAuth2 Provider, etc.) handles authentication and reports back to Cogitate
+1. Cogitate issues a ticket to the requesting Client via the given `:after_authentication_callback_url`
+1. The Client application claims the ticket from Cogitate via `/claim?ticket=<ticket>`
+1. Cogitate processes the claim and responds with a token
+1. The Client application parses the token into an Agent
+
 ## API
 
-### GET /auth?after_authentication_callback_url=<cgi escaped URL>
+### GET /authenticate?after_authentication_callback_url=<cgi escaped URL>
 
 ```console
-GET /auth?after_authentication_callback_url=https%3A%2F%2Fdeposit.library.nd.edu%2Fafter_authenticate
+GET /authenticate?after_authentication_callback_url=https%3A%2F%2Fdeposit.library.nd.edu%2Fafter_authenticate
 ```
 
 This resource is responsible for brokering the actual authentication service.
@@ -64,6 +89,14 @@ Cogitate will redirect to the URL specified in the `GET /auth` request's `after_
 The payload will be a JSON Web Token.
 That token should contain enough information for your application to adjudicate authorization questions.
 
+### GET /claim?ticket=<cgi escaped TICKET>
+
+```console
+GET /claim?ticket=123456789
+```
+
+This resource is responsible for transforming a ticket into a token.
+
 ### GET Agents
 
 #### Request
@@ -86,8 +119,8 @@ urlsafe_base64_encoded_identifiers = Base64.urlsafe_encode64(identifier)
 
 ```ruby
 require 'base64'
-Base64.urlsafe_encode64("orcid\t0000-0002-1191-0873")
-=> "b3JjaWQJMDAwMC0wMDAyLTExOTEtMDg3Mw=="
+Base64.urlsafe_encode64("netid\thworld")
+=> "bmV0aWQJaHdvcmxk"
 ```
 
 **Note:** Delimit multiple identifiers with a new line (i.e. `\n`).
@@ -97,22 +130,43 @@ Base64.urlsafe_encode64("orcid\t0000-0002-1191-0873")
 ```json
 {
   "links": {
-    "self": "http://localhost:3000/api/agents/b3JjaWQJMDAwMC0wMDAyLTExOTEtMDg3Mw=="
+    "self": "http://localhost:3000/api/agents/bmV0aWQJaHdvcmxk"
   },
   "data": [{
     "type": "agents",
-    "id": "b3JjaWQJMDAwMC0wMDAyLTExOTEtMDg3Mw==",
+    "id": "bmV0aWQJaHdvcmxk",
+    "links": {
+      "self": "http://localhost:3000/api/agents/bmV0aWQJaHdvcmxk"
+    },
     "attributes": {
-      "strategy": "orcid",
-      "identifying_value": "0000-0002-1191-0873"
+      "strategy": "netid",
+      "identifying_value": "hworld",
+      "emails": ["hworld@nd.edu"]
     },
     "relationships": {
-      "identities": [{
-        "type": "unverified/orcid",
-        "id": "0000-0002-1191-0873"
+      "identifiers": [{
+        "type": "identifiers",
+        "id": "bmV0aWQJaHdvcmxk"
       }],
-      "verified_identities": []
-    }
+      "verified_identifiers": [{
+        "type": "identifiers",
+        "id": "bmV0aWQJaHdvcmxk"
+      }]
+    },
+    "included": [{
+      "type": "identifiers",
+      "id": "bmV0aWQJaHdvcmxk",
+      "attributes": {
+        "identifying_value": "hworld",
+        "strategy": "netid",
+        "first_name": "Hello",
+        "last_name": "World",
+        "netid": "hworld",
+        "full_name": "Hello World",
+        "ndguid": "nd.edu.hworld",
+        "email": "hworld@nd.edu"
+      }
+    }]
   }]
 }
 ```
@@ -137,8 +191,8 @@ It was also clear that our institutional service was inadequate due to the natur
 * Communication Channels
   * ~~Extract email from NetID identifier~~
 * Client library
-  * Decode the JSON Web Token (JWT) into a "User" object and related information
-    * Levarage RSA public key for decoding the JWT
+  * ~~Decode the JSON Web Token (JWT) into a "User" object and related information~~
+    * ~~Levarage RSA public key for decoding the JWT~~
 
 ### Phase 2
 

data/lib/cogitate.rb

@@ -1,3 +1,5 @@
+require 'cogitate/configuration'
+
 # Cogitate is a federated identity management system for managing:
 #   * User identities through:
 #     * Group membership
@@ -6,6 +8,20 @@
 #     * Parroted identities (ask for the identity of a Kroger Card number, you'll get back a Kroger card number)
 #   * User authentication through various providers
 module Cogitate
-  # Used as a namespace grab
-  VERSION = '0.0.1'.freeze
+  # This version reflects the gem version for release
+  VERSION = '0.0.2'.freeze
+
+  def self.configure
+    yield(configuration)
+  end
+
+  def self.configuration=(input)
+    @configuration = input
+  end
+
+  def self.configuration
+    @configuration ||= Cogitate::Configuration.new
+  end
 end
+
+require 'cogitate/railtie' if defined?(Rails)

data/lib/cogitate/README.md

@@ -0,0 +1,8 @@
+Welcome to the Cogitate gem.
+
+If you are looking at the code repository this gem may look a little unusual.
+It is embedded inside a Rails application (Cogitate).
+
+The goal is that the initial development shares many concerns, so I don't want to separate Client and Server side responsibilities.
+
+**Note:** Any files in the lib/cogitate directory will be included in the cogitate gem.

data/lib/cogitate/client.rb

@@ -0,0 +1,97 @@
+require 'base64'
+require 'cogitate'
+require 'cogitate/exceptions'
+require 'cogitate/client/ticket_to_token_coercer'
+require 'cogitate/client/token_to_object_coercer'
+require 'cogitate/client/response_parsers'
+require 'cogitate/client/request'
+
+module Cogitate
+  # Responsible for collecting the various client related behaviors.
+  module Client
+    # @api public
+    #
+    # Allows for a predictable and repeatable way for a developer to alter the configuration of Cogitate.
+    # This is something most helpful under tests.
+    #
+    # @example
+    #   Coigtate::Client.with_custom_configuration do
+    #     Do things with the alternate Cogitate end-point
+    #   end
+    #
+    # @param remote_server_base_url [String] Where is a remote instance of Cogitate running?
+    # @param keywords [Hash] See Cogitate::Configuration for the detailed parameters.
+    # @return void
+    #
+    # @note This is a convenience method for testing; Woe is yeah that uses this in a non-test environment
+    def self.with_custom_configuration(remote_server_base_url: 'http://localhost:3000', **keywords)
+      old_configuration = Cogitate.configuration
+      configuration = Cogitate::Configuration.new(remote_server_base_url: remote_server_base_url, **keywords)
+      Cogitate.configuration = configuration
+      yield
+    ensure
+      Cogitate.configuration = old_configuration
+    end
+
+    # @api public
+    #
+    # A URL safe encoding of the given `strategy` and `identifying_value`
+    #
+    # @param strategy [String]
+    # @param identifying_value [String]
+    #
+    # @return [String] a URL safe encoding of the object's identifying attributes
+    #
+    # @see Cogitate::Models::Identifier
+    def self.encoded_identifier_for(strategy:, identifying_value:)
+      Base64.urlsafe_encode64("#{strategy.to_s.downcase}\t#{identifying_value}")
+    end
+
+    # @api public
+    def self.extract_strategy_and_identifying_value(encoded_string)
+      Base64.urlsafe_decode64(encoded_string).split("\t")
+    rescue ArgumentError
+      raise Cogitate::InvalidIdentifierEncoding, encoded_string: encoded_string
+    end
+
+    # @api public
+    def self.retrieve_token_from(ticket:)
+      TicketToTokenCoercer.call(ticket: ticket)
+    end
+
+    # @api public
+    def self.extract_agent_from(token:)
+      TokenToObjectCoercer.call(token: token)
+    end
+
+    # @api public
+    #
+    # @param identifiers [Array<String>]
+    # @param response_parser [#call(response:)]
+    def self.request(identifiers:, response_parser: :AgentsWithDetailedIdentfiers)
+      coerced_parser = response_parser_for(response_parser)
+      Request.call(identifiers: identifiers, response_parser: coerced_parser)
+    end
+
+    # @api public
+    # @param object [String, Symbol, #call]
+    # @return #call(identifier:)
+    def self.response_parser_for(object)
+      ResponseParsers.fetch(object)
+    end
+
+    # @api public
+    #
+    # @param identifiers [Array<String>]
+    def self.retrieve_primary_emails_associated_with(identifiers:, response_parser: :Email)
+      request(identifiers: identifiers, response_parser: response_parser)
+    end
+
+    # @api public
+    #
+    # @param identifiers [Array<String>]
+    def self.request_agents_without_group_membership(identifiers:, response_parser: :AgentsWithoutGroupMembership)
+      request(identifiers: identifiers, response_parser: response_parser)
+    end
+  end
+end

data/lib/cogitate/client/agent_builder.rb

@@ -0,0 +1,86 @@
+module Cogitate
+  module Client
+    # Responsible for transforming a well formed Hash into an Agent and its constituent parts.
+    #
+    # @see Cogitate::Models::Agent
+    # @see Cogitate::Client::AgentBuilder.call
+    class AgentBuilder
+      # @api public
+      #
+      # Responsible for transforming a well formed Hash into an Agent and its constituent parts.
+      #
+      # @param data [Hash] with string keys
+      # @param [Hash] keywords
+      # @option keywords [#call] :identifier_builder converts the 'id' into an Cogitate::Models::Identifier
+      # @return [Cogitate::Models::Agent]
+      # @raise KeyError if the input data is not well formed
+      def self.call(data, **keywords)
+        new(data, **keywords).call
+      end
+
+      # @api private
+      def initialize(data, identifier_guard: default_identifier_guard, **keywords)
+        self.data = data
+        self.identifier_guard = identifier_guard
+        self.identifier_builder = keywords.fetch(:identifier_builder) { default_identifier_builder }
+        self.agent_builder = keywords.fetch(:agent_builder) { default_agent_builder }
+        set_agent!
+      end
+
+      # @api private
+      def call
+        assign_identifiers_to_agent
+        assign_verified_identifiers_to_agent
+        agent
+      end
+
+      private
+
+      def assign_identifiers_to_agent
+        with_assigning_relationship_for(key: 'identifiers') do |identifier|
+          agent.add_identifier(identifier)
+        end
+      end
+
+      def assign_verified_identifiers_to_agent
+        with_assigning_relationship_for(key: 'verified_identifiers') do |identifier|
+          agent.add_verified_identifier(identifier)
+          next unless identifier.respond_to?(:email)
+          agent.add_email(identifier.email)
+        end
+      end
+
+      def with_assigning_relationship_for(key:)
+        data.fetch('relationships').fetch(key).each do |relationship|
+          identifier = identifier_builder.call(encoded_identifier: relationship.fetch('id'), included: data.fetch('included', []))
+          next unless identifier_guard.call(identifier: identifier)
+          yield(identifier)
+        end
+      end
+
+      attr_accessor :data, :identifier_builder, :identifier_guard, :agent_builder
+      attr_reader :agent
+
+      def set_agent!
+        @agent = agent_builder.call(encoded_identifier: data.fetch('id'))
+      end
+
+      # @api private
+      # Because the identifiers decoder returns an array; However I want a single object.
+      def default_identifier_builder
+        require 'cogitate/client/identifier_builder' unless defined? Services::IdentifierBuilder
+        Client::IdentifierBuilder
+      end
+
+      # @api private
+      def default_agent_builder
+        require 'cogitate/models/agent' unless defined? Cogitate::Models::Agent
+        Cogitate::Models::Agent.method(:build_with_encoded_id)
+      end
+
+      def default_identifier_guard
+        -> (*) { true }
+      end
+    end
+  end
+end

data/lib/cogitate/client/data_to_object_coercer.rb

@@ -0,0 +1,38 @@
+require 'cogitate/client/agent_builder'
+
+module Cogitate
+  module Client
+    # Responsible for coercing a JSON hash into a Cogitate::Client object
+    #
+    # @see Cogitate::Client::DataToObjectCoercer.call
+    module DataToObjectCoercer
+      module_function
+
+      # @api public
+      #
+      # Responsible for coercing a JSON hash into a Cogitate::Client object
+      #
+      # @param data [Hash] with string keys
+      # @param type_to_builder_map [Hash] a lookup table of key to constant
+      # @return the result of building the object as per the :type_to_builder_map
+      # @raise KeyError if `data` does not have 'type' key or if `type_to_builder_map` does not have `data['type']` key
+      def call(data, type_to_builder_map: default_type_to_builder_map, **keywords)
+        type = data.fetch('type')
+        builder = type_to_builder_map.fetch(type.to_s)
+        builder.call(data, **keywords)
+      end
+
+      TYPE_TO_BUILDER_MAP = {
+        'agents' => AgentBuilder,
+        'agent' => AgentBuilder
+      }.freeze
+      private_constant :TYPE_TO_BUILDER_MAP
+
+      # @api private
+      def default_type_to_builder_map
+        TYPE_TO_BUILDER_MAP
+      end
+      private_class_method :default_type_to_builder_map
+    end
+  end
+end

data/lib/cogitate/client/exceptions.rb

@@ -0,0 +1,10 @@
+module Cogitate
+  module Client
+    # Unable to find the parser give hints
+    class ResponseParserNotFound < NameError
+      def initialize(name, namespace)
+        super("Unable to find #{name.inspect} parser in #{namespace}")
+      end
+    end
+  end
+end

data/lib/cogitate/client/identifier_builder.rb

@@ -0,0 +1,26 @@
+require 'cogitate/models/identifiers/with_attribute_hash'
+
+module Cogitate
+  module Client
+    # Responsible for transforming an encoded identifier into an identifier
+    # then decorating that identifier with attributes that may be found in the
+    # array of :included objects
+    #
+    # @see Cogitate::Models::Identifier
+    # @see Cogitate::Client::IdentifierBuilder.call
+    module IdentifierBuilder
+      # @api public
+      def self.call(encoded_identifier:, included: [], identifier_decoder: default_identifier_decoder)
+        base_identifier = identifier_decoder.call(encoded_identifier: encoded_identifier)
+        included_object = included.detect { |obj| obj['id'] == encoded_identifier }
+        return base_identifier unless included_object
+        Models::Identifiers::WithAttributeHash.new(identifier: base_identifier, attributes: included_object.fetch('attributes', {}))
+      end
+
+      def self.default_identifier_decoder
+        require 'cogitate/services/identifiers_decoder' unless defined? Services::IdentifiersDecoder
+        ->(encoded_identifier:) { Services::IdentifiersDecoder.call(encoded_identifier).first }
+      end
+    end
+  end
+end