algoliasearch 1.2.4 → 1.2.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 5f84365c51f1592ac0bd372b32ef668eae0831ec
-  data.tar.gz: 315a6fbb785510696b8a9d1717de2cf09e208fd2
+  metadata.gz: ffcea70e1e16052463f966167245f0d0412bb1d1
+  data.tar.gz: a37adf050adb92682c8ddd48990b093606ba800d
 SHA512:
-  metadata.gz: 3e4bf583e3651c8b02c76e8bc6a50c038c54ab40766bc14ad1ca8ad6f8608e90984827aa4f8a5474d956af1ac4ebf9e5ff48e93696132fd12bb229769ad193e3
-  data.tar.gz: 6adcdf51f0a2702b5a7adbdebae0387a6d05a2c6957a44cdb388e37c0650aba41df48223ab110dccbaf13b7b53f39f16a5b211b5bbcc991e9d57e1303b7fb49d
+  metadata.gz: fc1fbead2ee31e7e503b7864d7779c9455d99f1925de7f5ca765c0a0229dc0c4b81680a9b814c029a0b06152b8729565dae1f8ecb342a07c46f650771ec4df07
+  data.tar.gz: 79a73010bbaa3b99227c9693ea9f71ba9c6627b02faf4dd4a9f772bef98b0cb9af637e67e65049fa797d056bd22cafa6415b6a28db23164a1810c1e7a3a3288f

data/ChangeLog

@@ -1,5 +1,10 @@
 CHANGELOG
 
+2014-02-24  1.2.5
+
+      * Ability to generate secured API key from a list of tags + optional user_token
+      * Ability to specify a list of indexes targeted by the user key
+
 2014-02-21  1.2.4
 
       * Added delete_objects

data/README.md

@@ -295,6 +295,8 @@ The server response will look like:
 
 
 
+
+
 Get an object
 -------------
 
@@ -494,13 +496,18 @@ You can also create an API Key with advanced restrictions:
   Note: If you are sending the query through your servers, you must use the `Algolia.with_rate_limits("EndUserIP", "APIKeyWithRateLimit") do ... end` block to enable rate-limit.
 
  * Specify the maximum number of hits this API key can retrieve in one call. Defaults to 0 (unlimited). This parameter can be used to protect you from attempts at retrieving your entire content by massively querying the index.
+ * Specify the list of targeted indexes. Defaults to all indexes if empty of blank.
 
 ```ruby
 # Creates a new global API key that is valid for 300 seconds
 res = Algolia.add_user_key(["search"], 300)
 puts res['key']
-# Creates a new index specific API key valid for 300 seconds, with a rate limit of 100 calls per hour per IP and a maximum of 20 hits
-res = index.add_user_key(["search"], 300, 100, 20)
+# Creates a new index specific API key:
+#  - valid for 300 seconds
+#  - rate limit of 100 calls per hour per IP
+#  - maximum of 20 hits
+#  - valid on 'my_index1' and 'my_index2'
+res = index.add_user_key(["search"], 300, 100, 20, ['my_index1', 'my_index2'])
 puts res['key']
 ```
 
@@ -520,6 +527,49 @@ Algolia.delete_user_key("f420238212c54dcfad07ea0aa6d5c45f")
 index.delete_user_key("71671c38001bf3ac857bc82052485107")
 ```
 
+You may have a single index containing per-user data. In that case, all records should be tagged with their associated user_id in order to add a `tagFilters=(public,user_42)` filter at query time to retrieve only what a user has access to. If you're using the [JavaScript client](http://github.com/algolia/algoliasearch-client-js), it will result in a security breach since the user is able to modify the `tagFilters` you've set modifying the code from the browser. To keep using the JavaScript client (recommended for optimal latency) and target secured records, you can generate secured API key from your backend:
+
+```ruby
+# generate a public API key for user 42. Here, records are tagged with:
+#  - 'public' if they are visible by all users
+#  - 'user_XXXX' if they are visible by user XXXX
+public_key = Algolia.generate_secured_api_key 'YourSearchOnlyApiKey', '(public,user_42)'
+```
+
+This public API key must then be used in your JavaScript code as follow:
+
+```javascript
+<script type="text/javascript">
+  var algolia = new AlgoliaSearch('YourApplicationID', '<%= public_api_key %>');
+  algolia.setSecurityTags('(public,user_42)'); // must be same than those used at generation-time
+  algolia.initIndex('YourIndex').search($('#q').val(), function(success, content) {
+    // [...]
+  });
+</script>
+```
+
+You can mix rate limits and secured API keys setting an extra `user_token` attribute both at API key generation-time and query-time. When set, a uniq user will be identified by her `IP + user_token` instead of only her `IP`. It allows you to restrict a single user to perform maximum `N` API calls per hour, even if she share her `IP` with another user.
+
+```ruby
+# generate a public API key for user 42. Here, records are tagged with:
+#  - 'public' if they are visible by all users
+#  - 'user_XXXX' if they are visible by user XXXX
+public_key = Algolia.generate_secured_api_key 'YourRateLimitedApiKey', '(public,user_42)', 'user_42'
+```
+
+This public API key must then be used in your JavaScript code as follow:
+
+```javascript
+<script type="text/javascript">
+  var algolia = new AlgoliaSearch('YourApplicationID', '<%= public_api_key %>');
+  algolia.setSecurityTags('(public,user_42)'); // must be same than those used at generation-time
+  algolia.setUserToken('user_42')              // must be same than the one used at generation-time
+  algolia.initIndex('YourIndex').search($('#q').val(), function(success, content) {
+    // [...]
+  });
+</script>
+```
+
 Copy or rename an index
 -------------
 

data/algoliasearch.gemspec

@@ -6,12 +6,12 @@
 
 Gem::Specification.new do |s|
   s.name = "algoliasearch"
-  s.version = "1.2.4"
+  s.version = "1.2.5"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.require_paths = ["lib"]
   s.authors = ["Algolia"]
-  s.date = "2014-02-21"
+  s.date = "2014-02-24"
   s.description = "A simple Ruby client for the algolia.com REST API"
   s.email = "contact@algolia.com"
   s.extra_rdoc_files = [

data/lib/algolia/client.rb

@@ -148,6 +148,22 @@ module Algolia
     end
   end
 
+  #
+  # Generate a secured and public API Key from a list of tagFilters and an
+  # optional user token identifying the current user
+  #
+  # @param private_api_key your private API Key
+  # @param tag_filters the list of tags applied to the query (used as security)
+  # @param user_token an optional token identifying the current user
+  #
+  def Algolia.generate_secured_api_key(private_api_key, tag_filters, user_token = nil)
+    if tag_filters.is_a?(Array)
+      tag_filters = tag_filters.map { |t| t.is_a?(Array) ? "(#{t.join(',')})" : t }.join(',')
+    end
+    raise ArgumentError.new('Attribute "tag_filters" must be a list of tags') if !tag_filters.is_a?(String)
+    Digest::SHA256.hexdigest "#{private_api_key}#{tag_filters}#{user_token.to_s}"
+  end
+
   #
   # List all existing indexes
   # return an Answer object with answer in the form 
@@ -213,9 +229,17 @@ module Algolia
   #  @param validity the number of seconds after which the key will be automatically removed (0 means no time limit for this key)
   #  @param maxQueriesPerIPPerHour the maximum number of API calls allowed from an IP address per hour (0 means unlimited)
   #  @param maxHitsPerQuery  the maximum number of hits this API key can retrieve in one call (0 means unlimited)
+  #  @param indexes the optional list of targeted indexes
   #
-  def Algolia.add_user_key(acls, validity = 0, maxQueriesPerIPPerHour = 0, maxHitsPerQuery = 0)
-      Algolia.client.post(Protocol.keys_uri, {"acl" => acls, "validity" => validity.to_i, "maxQueriesPerIPPerHour" => maxQueriesPerIPPerHour.to_i, "maxHitsPerQuery" => maxHitsPerQuery.to_i}.to_json)
+  def Algolia.add_user_key(acls, validity = 0, maxQueriesPerIPPerHour = 0, maxHitsPerQuery = 0, indexes = nil)
+    params = {
+      :acl => acls,
+      :validity => validity.to_i,
+      :maxQueriesPerIPPerHour => maxQueriesPerIPPerHour.to_i,
+      :maxHitsPerQuery => maxHitsPerQuery.to_i
+    }
+    params[:indexes] = indexes if indexes
+    Algolia.client.post(Protocol.keys_uri, params.to_json)
   end
 
   # Delete an existing user key

data/lib/algolia/version.rb

@@ -1,3 +1,3 @@
 module Algolia
-  VERSION = "1.2.3"
+  VERSION = "1.2.5"
 end

data/spec/client_spec.rb

@@ -214,6 +214,9 @@ describe 'Client' do
   end 
 
   it "should get logs" do
+    host = Algolia.client.send(:thread_local_hosts).first
+    puts host[:session].get(host[:base_url] + Algolia::Protocol.logs(0, 10), { :header => Algolia.client.headers }).content
+
     res = Algolia.get_logs
 
     res['logs'].size.should > 0
@@ -561,4 +564,15 @@ describe 'Client' do
     logs['logs'][0].should have_key('sha1')
     logs['logs'][0]['sha1'].should be_a(String)
   end
+
+  it 'should generate secured api keys' do
+    key = Algolia.generate_secured_api_key('my_api_key', '(public,user1)')
+    key.should eq(Digest::SHA256.hexdigest 'my_api_key(public,user1)')
+    key = Algolia.generate_secured_api_key('my_api_key', '(public,user1)', 42)
+    key.should eq(Digest::SHA256.hexdigest 'my_api_key(public,user1)42')
+    key = Algolia.generate_secured_api_key('my_api_key', ['public'])
+    key.should eq(Digest::SHA256.hexdigest 'my_api_keypublic')
+    key = Algolia.generate_secured_api_key('my_api_key', ['public', ['premium','vip']])
+    key.should eq(Digest::SHA256.hexdigest 'my_api_keypublic,(premium,vip)')
+  end
 end

metadata

@@ -1,85 +1,85 @@
 --- !ruby/object:Gem::Specification
 name: algoliasearch
 version: !ruby/object:Gem::Version
-  version: 1.2.4
+  version: 1.2.5
 platform: ruby
 authors:
 - Algolia
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
-date: 2014-02-21 00:00:00.000000000 Z
+date: 2014-02-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httpclient
-  requirement: !ruby/object:Gem::Requirement
+  version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
         version: '2.3'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
         version: '2.3'
+  prerelease: false
+  type: :runtime
 - !ruby/object:Gem::Dependency
   name: json
-  requirement: !ruby/object:Gem::Requirement
+  version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
       - !ruby/object:Gem::Version
         version: 1.5.1
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
       - !ruby/object:Gem::Version
         version: 1.5.1
+  prerelease: false
+  type: :runtime
 - !ruby/object:Gem::Dependency
   name: travis
-  requirement: !ruby/object:Gem::Requirement
+  version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
+  prerelease: false
+  type: :development
 - !ruby/object:Gem::Dependency
   name: rake
-  requirement: !ruby/object:Gem::Requirement
+  version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
+  prerelease: false
+  type: :development
 - !ruby/object:Gem::Dependency
   name: rdoc
-  requirement: !ruby/object:Gem::Requirement
+  version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
+  requirement: !ruby/object:Gem::Requirement
     requirements:
     - - '>='
       - !ruby/object:Gem::Version
         version: '0'
+  prerelease: false
+  type: :development
 description: A simple Ruby client for the algolia.com REST API
 email: contact@algolia.com
 executables: []
@@ -115,7 +115,7 @@ homepage: http://github.com/algolia/algoliasearch-client-ruby
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -130,9 +130,9 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.1.11
-signing_key: 
+rubyforge_project:
+rubygems_version: 2.2.1
+signing_key:
 specification_version: 4
 summary: A simple Ruby client for the algolia.com REST API
 test_files: []