nuid-sdk 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 77fc98b1337b47b0be5eb21ee7ff594b0debb6810712cfa898766bb36756c613
-  data.tar.gz: a5e97a583efa1a33afcd05a6946c0f6af49f74f536628feef0de294d45c25531
+  metadata.gz: d870c8df47c135af740aa98e693bfe2fea401eb1014002a719ea05d518bca0eb
+  data.tar.gz: f52d91f7d14c678daa906c173e1c5a058fbb4d952e132521aee32019d4a3944b
 SHA512:
-  metadata.gz: 594d9c967068b6e5044022b14b12a50f34dcc5c563498eba0218d7ede6e6102c2f495ecf58b48aac2e99aaf0fbf9e5e8ddb5f393c996218df635ecc73bbea3e0
-  data.tar.gz: 9271877573ed17b00843b0f8cf4c1cb56e56b67e6ba4bbcf1417f5801fff9f65bdc4ffe6facf2d3454616597b66ac34962f8b11d7dbb65736988d1a4dded50cb
+  metadata.gz: a7c35e9a6771a5c9b994c0e64844237f3948374343ee3941b72819b9f8f666cea1750078f2ac61ecfc4ca263d89e7b83c7c68bdc7ac2524a36acb22dfc0cbe6d
+  data.tar.gz: 64b7386e55889c4a597866e07661ced6008fc06abb65bb81977f65d83fbb21e1cb6713e993838e3f6fce511669e64a9f62c8038f50a10f324892de6b9aba16e7

data/.gitignore

@@ -1 +1,3 @@
 .env
+pkg/
+.yardoc/

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    nuid-sdk (0.1.0)
+    nuid-sdk (0.1.1)
       httparty (~> 0.18.1)
 
 GEM
@@ -16,6 +16,7 @@ GEM
     minitest (5.14.3)
     multi_xml (0.6.0)
     rake (12.3.3)
+    yard (0.9.26)
 
 PLATFORMS
   ruby
@@ -24,6 +25,7 @@ DEPENDENCIES
   minitest (~> 5.0)
   nuid-sdk!
   rake (~> 12.0)
+  yard (~> 0.9)
 
 BUNDLED WITH
    2.1.4

data/README.md

@@ -5,8 +5,8 @@
 This repo provides a Ruby Gem for interacting with NuID APIs within Ruby
 applications.
 
-Read the latest [package
-docs](http://libdocs.s3-website-us-east-1.amazonaws.com/sdk-ruby/v0.1.0/) or
+Read the latest [gem
+docs](https://rubydoc.info/gems/nuid-sdk/) or
 checkout the [platform docs](https://portal.nuid.io/docs) for API docs, guides,
 video tutorials, and more.
 
@@ -15,14 +15,14 @@ video tutorials, and more.
 From [rubygems](https://rubygems.org/gems/nuid-sdk):
 
 ```sh
-gem install nuid-sdk -v "0.1.0"
+gem install nuid-sdk -v "0.1.1"
 ```
 
 Or with bundler:
 
 ```ruby
 # Gemfile
-gem "nuid-sdk", "~> 0.1.0"
+gem "nuid-sdk", "~> 0.1.1"
 ```
 
 ## Usage
@@ -30,9 +30,8 @@ gem "nuid-sdk", "~> 0.1.0"
 Example rails auth controller.
 
 For a more detailed example visit the [Integrating with
-NuID](https://portal.nuid.io/docs/guides/integrating-with-nuid) guide and its
-accompanying repository
-[node-example](https://github.com/NuID/node-example/tree/bj/client-server-apps).
+NuID](https://portal.nuid.io/docs/guides/integrating-with-nuid) guide and the
+accompanying [examples repo](https://github.com/NuID/examples).
 A ruby-specific code example is coming soon.
 
 ```ruby
@@ -41,11 +40,19 @@ require "nuid-sdk"
 class UsersController < ApplicationController
   NUID_API = ::NuID::SDK::API::Auth.new(ENV["NUID_API_KEY"])
 
+  # The registration form should send the verified credential to be
+  # recorded in the NuID Auth API. The response to that interaction
+  # will provide a `nu/id` key in the response which should be stored
+  # with the newly created user record.
+  #
+  # The "verified credential" is generated by your client application
+  # using `Zk.verifiableFromSecret(password)` from the `@nuid/zk` npm
+  # package.
   def register
     credential_res = NUID_API.credential_create(params[:verified_credential])
     if credential_res.ok?
       user_params = params.require(:email, :first_name, :last_name)
-                          .merge({nuid: credential_res.body["nu/id"]})
+                          .merge({nuid: credential_res.parsed_response["nu/id"]})
       @current_user = User.create(user_params)
       render json: @current_user, status: :created
     else
@@ -55,6 +62,56 @@ class UsersController < ApplicationController
 end
 ```
 
+``` ruby
+require "nuid-sdk"
+
+class SessionsController < ApplicationController
+  NUID_API = ::NuID::SDK::API::Auth.new(ENV["NUID_API_KEY"])
+
+  # Get a challenge from the Auth API. The client form should request
+  # a challenge as the first of two phases to login. Once a succesful
+  # challenge has been fetched, return it to the client so a proof
+  # can be generated from the challenge claims and the user's password.
+  def login_challenge
+    user = User.find(email: params[:email])
+    return render(status: :unauthorized) unless user
+    
+    credential_res = NUID_API.credential_get(user.nuid)
+    return render(status: :unauthorized) unless credential_res.ok?
+
+    credential = credential_res.parsed_response["nuid/credential"]
+    challenge_res = NUID_API.challenge_get(credential)
+    return render(status: :unauthorized) unless credential_res.ok?
+
+    challenge_jwt = challenge_res.parsed_response["nuid.credential.challenge/jwt"]
+    render json: {challenge_jwt: challenge_jwt}
+  end
+
+  # Verify is the second part of the login process. The params
+  # provided here include the user identification param (email or
+  # username), the unaltered challenge_jwt retrieved in phase 1 of login
+  # (see #login_challenge above), and the proof that was generated from
+  # the challenge_jwt claims and the user secret.
+  #
+  # The "proof" is generated by your client application using
+  # `Zk.proofFromSecretAndChallenge(password, challenge_jwt)` from the
+  # `@nuid/zk` npm package.
+  def login_verify
+    user = User.find(email: params[:email])
+    return render(status: :unauthorized) unless user
+
+    verify_res = NUID_API.challenge_verify(params[:challenge_jwt], params[:proof])
+    if res.ok?
+      @current_user = user
+      # issue session ...
+      render(json: @current_user)
+    else
+      render(status: :unathorized)
+    end
+  end
+end
+```
+
 ## Development
 
 You'll want to download docker to run the tests, as we depend on the

data/lib/nuid/sdk.rb

@@ -1,5 +1,5 @@
 require "nuid/sdk/version"
+require "nuid/sdk/api/auth"
 
 module NuID::SDK
-  class Error < StandardError; end
 end

data/lib/nuid/sdk/api/auth.rb

@@ -1,12 +1,104 @@
 require "httparty"
 
 module NuID::SDK::API
+   
+  # This class wraps the NuID Auth API endpoints for simpler integration into
+  # existing authentication flows.
+  #
+  # @example User Registration
+  #   require "nuid-sdk"
+  #   
+  #   class UsersController < ApplicationController
+  #     NUID_API = ::NuID::SDK::API::Auth.new(ENV["NUID_API_KEY"])
+  #
+  #     # The registration form should send the verified credential to be
+  #     # recorded in the NuID Auth API. The response to that interaction
+  #     # will provide a `nu/id` key in the response which should be stored
+  #     # with the newly created user record.
+  #     #
+  #     # The "verified credential" is generated by your client application
+  #     # using `Zk.verifiableFromSecret(password)` from the `@nuid/zk` npm
+  #     # package.
+  #     def register
+  #       credential_res = NUID_API.credential_create(params[:verified_credential])
+  #       return render(status: :unauthorized) unless credential_res.ok?
+  #       if credential_res.ok?
+  #         user_params = params.require(:email, :first_name, :last_name)
+  #                             .merge({nuid: credential_res.parsed_response["nu/id"]})
+  #         @current_user = User.create(user_params)
+  #         render json: @current_user, status: :created
+  #       else
+  #         render status: :bad_request
+  #       end
+  #     end
+  #   end
+  #
+  # @example User Login
+  #   require "nuid-sdk"
+  #   
+  #   class SessionsController < ApplicationController
+  #     NUID_API = ::NuID::SDK::API::Auth.new(ENV["NUID_API_KEY"])
+  #   
+  #     # Get a challenge from the Auth API. The client form should request
+  #     # a challenge as the first of two phases to login. Once a succesful
+  #     # challenge has been fetched, return it to the client so a proof
+  #     # can be generated from the challenge claims and the user's password.
+  #     def login_challenge
+  #       user = User.find(email: params[:email])
+  #       return render(status: :unauthorized) unless user
+  #       
+  #       credential_res = NUID_API.credential_get(user.nuid)
+  #       return render(status: :unauthorized) unless credential_res.ok?
+  #
+  #       credential = credential_res.parsed_response["nuid/credential"]
+  #       challenge_res = NUID_API.challenge_get(credential)
+  #       return render(status: :unauthorized) unless credential_res.ok?
+  #
+  #       challenge_jwt = challenge_res.parsed_response["nuid.credential.challenge/jwt"]
+  #       render json: {challenge_jwt: challenge_jwt}
+  #     end
+  #
+  #     # Verify is the second part of the login process. The params
+  #     # provided here include the user identification param (email or
+  #     # username), the unaltered challenge_jwt retrieved in phase 1 of login
+  #     # (see #login_challenge above), and the proof that was generated from
+  #     # the challenge_jwt claims and the user secret.
+  #     #
+  #     # The "proof" is generated by your client application using
+  #     # `Zk.proofFromSecretAndChallenge(password, challenge_jwt)` from the
+  #     # `@nuid/zk` npm package.
+  #     def login_verify
+  #       user = User.find(email: params[:email])
+  #       return render(status: :unauthorized) unless user
+  #
+  #       verify_res = NUID_API.challenge_verify(params[:challenge_jwt], params[:proof])
+  #       if res.ok?
+  #         @current_user = user
+  #         # issue session ...
+  #         render(json: @current_user)
+  #       else
+  #         render(status: :unathorized)
+  #       end
+  #     end
+  #   end
+  #
+  #
+  # @see https://www.npmjs.com/package/@nuid/zk
+  # @see https://www.npmjs.com/package/@nuid/cli
   class Auth
     include HTTParty
     base_uri "https://auth.nuid.io"
 
     attr_reader :api_key
 
+    # Create an HTTParty instance for dispatching HTTP requests.
+    #
+    # All endpoints return the HTTParty Response object, with
+    # `HTTParty::Response#parsed_response` containing the JSON body converted to
+    # a hash.
+    #
+    # @param api_key [string] The Auth API Key
+    # @see https://portal.nuid.io
     def initialize(api_key)
       @api_key = api_key
       self.class.headers({
@@ -15,10 +107,37 @@ module NuID::SDK::API
       })
     end
 
+    # Get a credential `challenge` from the API, usually during login flow.
+    # The returned `challenge` can be used to generate a proof from the user's
+    # secret. Used in conjunction with #challenge_verify.
+    #
+    # @see https://www.npmjs.com/package/@nuid/zk
+    # @see https://www.npmjs.com/package/@nuid/cli
+    #
+    # @param credential [Hash] A `credential` is usually returned by the
+    #   #credential_get method
+    # @return [HTTParty::Response] use
+    #   HTTParty::Response#parsed_response["nuid.credential.challenge/jwt"] to
+    #   get the challenge JWT from the parsed response
     def challenge_get(credential)
       _post("/challenge", {"nuid/credential" => credential})
     end
 
+    # Verify a credential challenge with a proof generated from the challenge
+    # claims and the user's secret. Generated proof from the claims contained in
+    # the `challenge_jwt` and the user's secret. This proof is generated by
+    # `Zk.proofFromSecretAndChallenge(secret, challenge)` available in the npm
+    # package `@nuid/zk`.
+    #
+    # @see https://www.npmjs.com/package/@nuid/zk
+    # @see https://www.npmjs.com/package/@nuid/cli
+    #
+    # @param [String] challenge_jwt the `nuid.credential.challenge/jwt` returned
+    #   by #challenge_get
+    # @param [Hash] proof the generated proof from the challenge jwt claims and
+    #   user secret
+    # @return [HTTParty::Response] use `Response#parsed_response["nu/id"]` to get the
+    #   parsed JSON body
     def challenge_verify(challenge_jwt, proof)
       _post("/challenge/verify", {
         "nuid.credential.challenge/jwt" => challenge_jwt,
@@ -26,10 +145,34 @@ module NuID::SDK::API
       })
     end
 
+    # Create a credential from a verified credential (meaning a credential
+    # generated from the user's secret). Usually used during user registration.
+    # The parsed response body contains the new credential and the user's unique
+    # "nu/id" which should be used as a reference to the user's credential for
+    # later authentication attempts.
+    #
+    # @see #credential_get
+    # @see https://www.npmjs.com/package/@nuid/zk
+    # @see https://www.npmjs.com/package/@nuid/cli
+    #
+    # @param verified_credential [Hash] The hash returned by calling `Zk.verifiableFromSecret(secret)`
+    # @return [HTTParty::Response] use `Response#parsed_response` to get the
+    #   parsed JSON body
     def credential_create(verified_credential)
       _post("/credential", {"nuid.credential/verified" => verified_credential})
     end
 
+    # Fetch a credential by it's unique `nuid`. The `nu/id` paramter is extracted
+    # from the `#parsed_response` of #credential_create.
+    #
+    # Generally you will end up storing the nuid with your user record during
+    # registration. Later during login use the nuid to fetch the credential
+    # using this method, and pass the Response#parsed_response directly to
+    # #challenge_get.
+    #
+    # @param [String] nuid unique key for the credential
+    # @return [HTTParty::Response] use `Response#parsed_response` to get the
+    #   parsed JSON body
     def credential_get(nuid)
       self.class.get("/credential/#{nuid}")
     end

data/lib/nuid/sdk/version.rb

@@ -1,5 +1,5 @@
 module NuID
   module SDK
-    VERSION = "0.1.0"
+    VERSION = "0.1.1"
   end
 end

data/nuid-sdk.gemspec

@@ -18,6 +18,7 @@ Gem::Specification.new do |spec|
   spec.metadata["changelog_uri"] = "https://github.com/NuID/sdk-ruby/blob/master/CHANGELOG.md"
 
   spec.add_dependency "httparty", "~> 0.18.1"
+  spec.add_development_dependency "yard", "~> 0.9"
 
   # Specify which files should be added to the gem when it is released.
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: nuid-sdk
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - BJ Neilsen
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2021-02-04 00:00:00.000000000 Z
+date: 2021-02-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: httparty
@@ -24,6 +24,20 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: 0.18.1
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.9'
 description: 
 email:
 - bj.neilsen@gmail.com
@@ -71,7 +85,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.1.2
+rubygems_version: 3.2.8
 signing_key: 
 specification_version: 4
 summary: SDK for interacting with NuID APIs in Ruby