ruby-safenet 0.0.3 → 0.0.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 4a3aaf208f93f8c870707fc7a0708a59cc8f3fa1
-  data.tar.gz: 4b761d4aefa387c4f2f10d841791a15d38ae24ee
+  metadata.gz: 2fd845e03b3d1254c4a2d51007b7a7626a31efa0
+  data.tar.gz: cb52f9349cf546fe6ef203a06fd983b3d9305033
 SHA512:
-  metadata.gz: 4f6e198c3ca9d0886c4623453fce84dbbf1562dec157a7d1fc34cca107a3abae80343ef98e7909b867cd59328471a48ffe5688433bb4ac1cb11dfa520de35eb2
-  data.tar.gz: 6d5690268fa7543968ee7a9d962cf6546aaab115db0e54b31b89ef2da30ab44414a1ff0851773fdaa51f07e0aca863a7cc748777dca0a653ba63040435eba433
+  metadata.gz: 3b0c0aa75968b2c8db96d1cfd49d79f7ab8e780b290dd2a7495a1f29f7f176ef0f4802977305cd14adb785b8ebda24784474b49ec15f11b7f2ee893ddcdaa32c
+  data.tar.gz: 403be8627d2416aefefdcf47f8d803a09f0444db5946ce13ff97d7483d05bf7c6752ec938d83c56510adcf2952cb1265525d2c709cf9cc299e6a7d7cbb4c89df

data/README.md

@@ -3,8 +3,9 @@
 A Ruby library for accessing the SAFE network
 
 ## Installation
-
+```
   $ gem install safenet
+```
 
 ## Usage
 
@@ -18,14 +19,16 @@ SafeNet.set_app_info({
   id:        "org.thevendor.demo",
 })
 
-SafeNet.create_directory("/mydir")
+SafeNet.create_directory("/mydir", is_private: false)
 SafeNet.file("/mydir/index.html", is_private: false)
 SafeNet.update_file_content("/mydir/index.html", "Hello world!<br>I'm a webpage :D")
-SafeNet.register_service("mywonderfulapp", "www", "/mydir")
+SafeNet.register_service("my-wonderful-app", "www", "/mydir")
 SafeNet.get_file("/mydir/index.html")
+
+# Then, open http://www.my-wonderful-app.safenet/
 ```
 
-*Upload / Download:*
+*File Upload / Download:*
 ```ruby
 # upload
 SafeNet.file("/mydir/dog.jpg")

data/lib/safenet.rb

@@ -12,7 +12,7 @@ module SafeNet
   @@VERSION = "0.0.1"
   @@VENDOR = "Vendor's Name"
   @@ID = "org.thevendor.demo"
-  @@LAUCHER_SERVER = "http://localhost:8100/"
+  @@LAUNCHER_SERVER = "http://localhost:8100/"
   @@CONF_PATH = File.join(File.expand_path('..', __FILE__), "conf.json")
 
   def self.set_app_info(options)
@@ -20,16 +20,42 @@ module SafeNet
     @@VERSION = options[:version] if options.has_key?(:version)
     @@VENDOR = options[:vendor] if options.has_key?(:vendor)
     @@ID = options[:id] if options.has_key?(:id)
-    @@LAUCHER_SERVER = options[:server] if options.has_key?(:server)
+    @@LAUNCHER_SERVER = options[:server] if options.has_key?(:server)
     @@CONF_PATH = options[:conf_file] if options.has_key?(:conf_file)
   end
 
+  #
+  # An application exchanges data with the SAFE Launcher using symmetric key
+  #   encryption. The symmetric key is session based and is securely transferred
+  #   from the SAFE Launcher to the application using ECDH Key Exchange.
+  # Applications will generate an asymmetric key pair and a nonce for ECDH Key
+  #   Exchange with the SAFE Launcher.
+  #
+  # The application will initiate the authorisation request with the generated
+  #   nonce and public key, along with information about the application and the
+  #   required permissions.
+  #
+  # The SAFE Launcher will prompt to the user with the application information
+  #   along with the requested permissions. Once the user authorises the
+  #   request, the symmetric keys for encryption are received. If the user
+  #   denies the request then the SAFE Launcher sends an unauthorised error
+  #   response.
+  #
+  # Usage: SafeNet.auth()
+  # Fail: nil
+  # Success: {token: "1222", encryptedKey: "232", "publicKey": "4323", "permissions": []}
+  #
+  # Reference: https://maidsafe.readme.io/docs/auth
+  #
   def self.auth
-    url = "#{@@LAUCHER_SERVER}auth"
+    # entry point
+    url = "#{@@LAUNCHER_SERVER}auth"
 
+    # new random key
     private_key = RbNaCl::PrivateKey.generate
     nonce = RbNaCl::Random.random_bytes(24)
 
+    # payload
     payload = {
       app: {
         name: @@NAME,
@@ -42,12 +68,14 @@ module SafeNet
       permissions: []
     }
 
+    # api call
     uri = URI(url)
     http = Net::HTTP.new(uri.host, uri.port)
     req = Net::HTTP::Post.new(uri.path, {'Content-Type' => 'application/json'})
     req.body = payload.to_json
     res = http.request(req)
 
+    # return's parser
     if res.code == "200"
       response = JSON.parse(res.body)
 
@@ -57,18 +85,33 @@ module SafeNet
       conf["privateKey"] = Base64.strict_encode64(private_key)
       File.open(@@CONF_PATH, "w") { |f| f << JSON.pretty_generate(conf) }
 
+      # invalidates @@keys
+      @@keys = {}
     else
       # puts "ERROR #{res.code}: #{res.message}"
       response = nil
     end
 
+    # return
     response
   end
 
 
+  #
+  # To check whether the authorisation token obtained is valid.
+  # The Authorization header must be present in the request.
+  #
+  # Usage: SafeNet.is_token_valid()
+  # Fail: false
+  # Success: true
+  #
+  # Reference: https://maidsafe.readme.io/docs/is-token-valid
+  #
   def self.is_token_valid
-    url = "#{@@LAUCHER_SERVER}auth"
+    # entry point
+    url = "#{@@LAUNCHER_SERVER}auth"
 
+    # api call
     uri = URI(url)
     http = Net::HTTP.new(uri.host, uri.port)
     req = Net::HTTP::Get.new(uri.path, {
@@ -79,9 +122,20 @@ module SafeNet
   end
 
 
+  #
+  # Removes the token from the SAFE Launcher.
+  #
+  # Usage: SafeNet.revoke_token()
+  # Fail: false
+  # Success: true
+  #
+  # Reference: https://maidsafe.readme.io/docs/revoke-token
+  #
   def self.revoke_token
-    url = "#{@@LAUCHER_SERVER}auth"
+    # entry point
+    url = "#{@@LAUNCHER_SERVER}auth"
 
+    # api call
     uri = URI(url)
     http = Net::HTTP.new(uri.host, uri.port)
     req = Net::HTTP::Delete.new(uri.path, {
@@ -91,13 +145,25 @@ module SafeNet
     res.code == "200"
   end
 
+
+  #
+  # Create a directory using the NFS API.
+  # Only authorised requests can create a directory.
+  #
+  # Usage: SafeNet.get_directory("/photos", is_path_shared: false)
+  # Fail: {"errorCode"=>-1502, "description"=>"FfiError::PathNotFound"}
+  # Success: {"info"=> {"name"=> "Ruby Demo App-Root-Dir", ...}, ...}
+  #
+  # Reference: https://maidsafe.readme.io/docs/nfs-create-directory
+  #
   def self.get_directory(dir_path, options = {})
     # default values
-    options[:is_path_shared] ||= false
+    options[:is_path_shared] = false if ! options.has_key?(:is_path_shared)
 
     # entry point
-    url = "#{@@LAUCHER_SERVER}nfs/directory/#{CGI.escape(dir_path)}/#{options[:is_path_shared]}"
+    url = "#{@@LAUNCHER_SERVER}nfs/directory/#{CGI.escape(dir_path)}/#{options[:is_path_shared]}"
 
+    # api call
     uri = URI(url)
     http = Net::HTTP.new(uri.host, uri.port)
     req = Net::HTTP::Get.new(uri.path, {
@@ -108,21 +174,30 @@ module SafeNet
   end
 
 
-  # options = is_private, metadata, is_versioned, is_path_shared
+  #
+  # Create a File using the NFS API.
+  # Only authorised requests can invoke the API.
+  #
+  # Usage: SafeNet.file("/photos/cat.jpg", metadata: {item1: "ad sad"}, is_path_shared: false, is_private: true, is_versioned: false)
+  # Fail: {"errorCode"=>-505, "description"=>"NfsError::FileAlreadyExistsWithSameName"}
+  # Success: true
+  #
+  # Reference: https://maidsafe.readme.io/docs/nfsfile
+  #
   def self.file(file_path, options = {})
-    url = "#{@@LAUCHER_SERVER}nfs/file"
+    url = "#{@@LAUNCHER_SERVER}nfs/file"
 
     # default values
-    options[:is_private]     ||= true
-    options[:is_versioned]   ||= false
-    options[:is_path_shared] ||= false
+    options[:is_private]     = true  if ! options.has_key?(:is_private)
+    options[:is_versioned]   = false if ! options.has_key?(:is_versioned)
+    options[:is_path_shared] = false if ! options.has_key?(:is_path_shared)
 
     # payload
     payload = {
       filePath: file_path,
-      isPrivate: options[:is_private].to_s,
-      isVersioned: options[:is_versioned].to_s,
-      isPathShared: options[:is_path_shared].to_s
+      isPrivate: options[:is_private],
+      isVersioned: options[:is_versioned],
+      isPathShared: options[:is_path_shared]
     }
 
     # optional
@@ -141,22 +216,31 @@ module SafeNet
   end
 
 
-  # options = is_private, metadata, is_versioned, is_path_shared
-  # ex.: create_directory("/photos")
+  #
+  # Create a directory using the NFS API.
+  # Only authorised requests can create a directory.
+  #
+  # Usage: SafeNet.create_directory("/photos", metadata: {entry1: "2323"}, is_private: true, is_path_shared: false, is_versioned: false)
+  # Fail: {"errorCode"=>-505, "description"=>"NfsError::FileAlreadyExistsWithSameName"}
+  # Success: true
+  #
+  # Reference: https://maidsafe.readme.io/docs/nfs-create-directory
+  #
   def self.create_directory(dir_path, options = {})
-    url = "#{@@LAUCHER_SERVER}nfs/directory"
+    # entry point
+    url = "#{@@LAUNCHER_SERVER}nfs/directory"
 
     # default values
-    options[:is_private]     ||= true
-    options[:is_versioned]   ||= false
-    options[:is_path_shared] ||= false
+    options[:is_private]     = true  if ! options.has_key?(:is_private)
+    options[:is_versioned]   = false if ! options.has_key?(:is_versioned)
+    options[:is_path_shared] = false if ! options.has_key?(:is_path_shared)
 
     # payload
     payload = {
       dirPath: dir_path,
-      isPrivate: options[:is_private].to_s,
-      isVersioned: options[:is_versioned].to_s,
-      isPathShared: options[:is_path_shared].to_s
+      isPrivate: options[:is_private],
+      isVersioned: options[:is_versioned],
+      isPathShared: options[:is_path_shared]
     }
 
     # optional
@@ -178,10 +262,10 @@ module SafeNet
   # ex.: delete_directory("/photos")
   def self.delete_directory(dir_path, options = {})
     # default values
-    options[:is_path_shared] ||= false
+    options[:is_path_shared] = false if ! options.has_key?(:is_path_shared)
 
     # entry point
-    url = "#{@@LAUCHER_SERVER}nfs/directory/#{CGI.escape(dir_path)}/#{options[:is_path_shared]}"
+    url = "#{@@LAUNCHER_SERVER}nfs/directory/#{CGI.escape(dir_path)}/#{options[:is_path_shared]}"
 
     # api call
     uri = URI(url)
@@ -196,11 +280,11 @@ module SafeNet
   # options: offset, length, is_path_shared
   def self.get_file(file_path, options = {})
     # default values
-    options[:offset]         ||= 0
-    options[:is_path_shared] ||= false
+    options[:offset]         = 0     if ! options.has_key?(:offset)
+    options[:is_path_shared] = false if ! options.has_key?(:is_path_shared)
 
     # entry point
-    url = "#{@@LAUCHER_SERVER}nfs/file/#{CGI.escape(file_path)}/#{options[:is_path_shared]}?"
+    url = "#{@@LAUNCHER_SERVER}nfs/file/#{CGI.escape(file_path)}/#{options[:is_path_shared]}?"
 
     # query params are encrypted
     query = []
@@ -220,11 +304,11 @@ module SafeNet
 
   def self.update_file_content(file_path, contents, options = {})
     # default values
-    options[:offset]         ||= 0
-    options[:is_path_shared] ||= false
+    options[:offset]         = 0     if ! options.has_key?(:offset)
+    options[:is_path_shared] = false if ! options.has_key?(:is_path_shared)
 
     # entry point
-    url = "#{@@LAUCHER_SERVER}nfs/file/#{CGI.escape(file_path)}/#{options[:is_path_shared]}?offset=#{options[:offset]}"
+    url = "#{@@LAUNCHER_SERVER}nfs/file/#{CGI.escape(file_path)}/#{options[:is_path_shared]}?offset=#{options[:offset]}"
 
     # api call
     uri = URI(url)
@@ -240,10 +324,10 @@ module SafeNet
 
   def self.delete_file(file_path, options = {})
     # default values
-    options[:is_path_shared] ||= false
+    options[:is_path_shared] = false if ! options.has_key?(:is_path_shared)
 
     # entry point
-    url = "#{@@LAUCHER_SERVER}nfs/file/#{CGI.escape(file_path)}/#{options[:is_path_shared]}"
+    url = "#{@@LAUNCHER_SERVER}nfs/file/#{CGI.escape(file_path)}/#{options[:is_path_shared]}"
 
     # api call
     uri = URI(url)
@@ -257,7 +341,8 @@ module SafeNet
 
 
   def self.create_long_name(long_name)
-    url = "#{@@LAUCHER_SERVER}dns/#{CGI.escape(long_name)}"
+    # entry point
+    url = "#{@@LAUNCHER_SERVER}dns/#{CGI.escape(long_name)}"
 
     # api call
     uri = URI(url)
@@ -273,17 +358,18 @@ module SafeNet
 
   # ex.: register_service("thegoogle", "www", "/www")
   def self.register_service(long_name, service_name, service_home_dir_path, options = {})
-    url = "#{@@LAUCHER_SERVER}dns"
+    # entry point
+    url = "#{@@LAUNCHER_SERVER}dns"
 
     # default values
-    options[:is_path_shared] ||= false
+    options[:is_path_shared] = false if ! options.has_key?(:is_path_shared)
 
     # payload
     payload = {
       longName: long_name,
       serviceName: service_name,
       serviceHomeDirPath: service_home_dir_path,
-      isPathShared: options[:is_path_shared].to_s
+      isPathShared: options[:is_path_shared]
     }
 
     # optional
@@ -303,7 +389,8 @@ module SafeNet
 
 
   def self.list_long_names
-    url = "#{@@LAUCHER_SERVER}dns"
+    # entry point
+    url = "#{@@LAUNCHER_SERVER}dns"
 
     # api call
     uri = URI(url)
@@ -317,7 +404,8 @@ module SafeNet
 
 
   def self.list_services(long_name)
-    url = "#{@@LAUCHER_SERVER}dns/#{CGI.escape(long_name)}"
+    # entry point
+    url = "#{@@LAUNCHER_SERVER}dns/#{CGI.escape(long_name)}"
 
     # api call
     uri = URI(url)
@@ -331,7 +419,8 @@ module SafeNet
 
 
   def self.get_home_dir(long_name, service_name)
-    url = "#{@@LAUCHER_SERVER}dns/#{CGI.escape(service_name)}/#{CGI.escape(long_name)}"
+    # entry point
+    url = "#{@@LAUNCHER_SERVER}dns/#{CGI.escape(service_name)}/#{CGI.escape(long_name)}"
 
     # api call
     uri = URI(url)
@@ -345,10 +434,10 @@ module SafeNet
   # get_file_unauth("thegoogle", "www", "index.html", offset: 3, length: 5)
   def self.get_file_unauth(long_name, service_name, file_path, options = {})
     # default values
-    options[:offset] ||= 0
+    options[:offset] = 0 if ! options.has_key?(:offset)
 
     # entry point
-    url = "#{@@LAUCHER_SERVER}dns/#{CGI.escape(service_name)}/#{CGI.escape(long_name)}/#{CGI.escape(file_path)}?"
+    url = "#{@@LAUNCHER_SERVER}dns/#{CGI.escape(service_name)}/#{CGI.escape(long_name)}/#{CGI.escape(file_path)}?"
 
     # query params are encrypted
     query = []

data/lib/safenet/version.rb

@@ -1,3 +1,3 @@
 module Safenet
-  VERSION = "0.0.3"
+  VERSION = "0.0.4"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: ruby-safenet
 version: !ruby/object:Gem::Version
-  version: 0.0.3
+  version: 0.0.4
 platform: ruby
 authors:
 - Daniel Loureiro