nuid-sdk 0.1.0 → 0.1.1

Sign up to get free protection for your applications and to get access to all the features.
Files changed (9) hide show
  1. checksums.yaml +4 -4
  2. data/.gitignore +2 -0
  3. data/Gemfile.lock +3 -1
  4. data/README.md +65 -8
  5. data/lib/nuid/sdk.rb +1 -1
  6. data/lib/nuid/sdk/api/auth.rb +143 -0
  7. data/lib/nuid/sdk/version.rb +1 -1
  8. data/nuid-sdk.gemspec +1 -0
  9. metadata +17 -3
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 77fc98b1337b47b0be5eb21ee7ff594b0debb6810712cfa898766bb36756c613
4
- data.tar.gz: a5e97a583efa1a33afcd05a6946c0f6af49f74f536628feef0de294d45c25531
3
+ metadata.gz: d870c8df47c135af740aa98e693bfe2fea401eb1014002a719ea05d518bca0eb
4
+ data.tar.gz: f52d91f7d14c678daa906c173e1c5a058fbb4d952e132521aee32019d4a3944b
5
5
  SHA512:
6
- metadata.gz: 594d9c967068b6e5044022b14b12a50f34dcc5c563498eba0218d7ede6e6102c2f495ecf58b48aac2e99aaf0fbf9e5e8ddb5f393c996218df635ecc73bbea3e0
7
- data.tar.gz: 9271877573ed17b00843b0f8cf4c1cb56e56b67e6ba4bbcf1417f5801fff9f65bdc4ffe6facf2d3454616597b66ac34962f8b11d7dbb65736988d1a4dded50cb
6
+ metadata.gz: a7c35e9a6771a5c9b994c0e64844237f3948374343ee3941b72819b9f8f666cea1750078f2ac61ecfc4ca263d89e7b83c7c68bdc7ac2524a36acb22dfc0cbe6d
7
+ data.tar.gz: 64b7386e55889c4a597866e07661ced6008fc06abb65bb81977f65d83fbb21e1cb6713e993838e3f6fce511669e64a9f62c8038f50a10f324892de6b9aba16e7
data/.gitignore CHANGED
@@ -1 +1,3 @@
1
1
  .env
2
+ pkg/
3
+ .yardoc/
data/Gemfile.lock CHANGED
@@ -1,7 +1,7 @@
1
1
  PATH
2
2
  remote: .
3
3
  specs:
4
- nuid-sdk (0.1.0)
4
+ nuid-sdk (0.1.1)
5
5
  httparty (~> 0.18.1)
6
6
 
7
7
  GEM
@@ -16,6 +16,7 @@ GEM
16
16
  minitest (5.14.3)
17
17
  multi_xml (0.6.0)
18
18
  rake (12.3.3)
19
+ yard (0.9.26)
19
20
 
20
21
  PLATFORMS
21
22
  ruby
@@ -24,6 +25,7 @@ DEPENDENCIES
24
25
  minitest (~> 5.0)
25
26
  nuid-sdk!
26
27
  rake (~> 12.0)
28
+ yard (~> 0.9)
27
29
 
28
30
  BUNDLED WITH
29
31
  2.1.4
data/README.md CHANGED
@@ -5,8 +5,8 @@
5
5
  This repo provides a Ruby Gem for interacting with NuID APIs within Ruby
6
6
  applications.
7
7
 
8
- Read the latest [package
9
- docs](http://libdocs.s3-website-us-east-1.amazonaws.com/sdk-ruby/v0.1.0/) or
8
+ Read the latest [gem
9
+ docs](https://rubydoc.info/gems/nuid-sdk/) or
10
10
  checkout the [platform docs](https://portal.nuid.io/docs) for API docs, guides,
11
11
  video tutorials, and more.
12
12
 
@@ -15,14 +15,14 @@ video tutorials, and more.
15
15
  From [rubygems](https://rubygems.org/gems/nuid-sdk):
16
16
 
17
17
  ```sh
18
- gem install nuid-sdk -v "0.1.0"
18
+ gem install nuid-sdk -v "0.1.1"
19
19
  ```
20
20
 
21
21
  Or with bundler:
22
22
 
23
23
  ```ruby
24
24
  # Gemfile
25
- gem "nuid-sdk", "~> 0.1.0"
25
+ gem "nuid-sdk", "~> 0.1.1"
26
26
  ```
27
27
 
28
28
  ## Usage
@@ -30,9 +30,8 @@ gem "nuid-sdk", "~> 0.1.0"
30
30
  Example rails auth controller.
31
31
 
32
32
  For a more detailed example visit the [Integrating with
33
- NuID](https://portal.nuid.io/docs/guides/integrating-with-nuid) guide and its
34
- accompanying repository
35
- [node-example](https://github.com/NuID/node-example/tree/bj/client-server-apps).
33
+ NuID](https://portal.nuid.io/docs/guides/integrating-with-nuid) guide and the
34
+ accompanying [examples repo](https://github.com/NuID/examples).
36
35
  A ruby-specific code example is coming soon.
37
36
 
38
37
  ```ruby
@@ -41,11 +40,19 @@ require "nuid-sdk"
41
40
  class UsersController < ApplicationController
42
41
  NUID_API = ::NuID::SDK::API::Auth.new(ENV["NUID_API_KEY"])
43
42
 
43
+ # The registration form should send the verified credential to be
44
+ # recorded in the NuID Auth API. The response to that interaction
45
+ # will provide a `nu/id` key in the response which should be stored
46
+ # with the newly created user record.
47
+ #
48
+ # The "verified credential" is generated by your client application
49
+ # using `Zk.verifiableFromSecret(password)` from the `@nuid/zk` npm
50
+ # package.
44
51
  def register
45
52
  credential_res = NUID_API.credential_create(params[:verified_credential])
46
53
  if credential_res.ok?
47
54
  user_params = params.require(:email, :first_name, :last_name)
48
- .merge({nuid: credential_res.body["nu/id"]})
55
+ .merge({nuid: credential_res.parsed_response["nu/id"]})
49
56
  @current_user = User.create(user_params)
50
57
  render json: @current_user, status: :created
51
58
  else
@@ -55,6 +62,56 @@ class UsersController < ApplicationController
55
62
  end
56
63
  ```
57
64
 
65
+ ``` ruby
66
+ require "nuid-sdk"
67
+
68
+ class SessionsController < ApplicationController
69
+ NUID_API = ::NuID::SDK::API::Auth.new(ENV["NUID_API_KEY"])
70
+
71
+ # Get a challenge from the Auth API. The client form should request
72
+ # a challenge as the first of two phases to login. Once a succesful
73
+ # challenge has been fetched, return it to the client so a proof
74
+ # can be generated from the challenge claims and the user's password.
75
+ def login_challenge
76
+ user = User.find(email: params[:email])
77
+ return render(status: :unauthorized) unless user
78
+
79
+ credential_res = NUID_API.credential_get(user.nuid)
80
+ return render(status: :unauthorized) unless credential_res.ok?
81
+
82
+ credential = credential_res.parsed_response["nuid/credential"]
83
+ challenge_res = NUID_API.challenge_get(credential)
84
+ return render(status: :unauthorized) unless credential_res.ok?
85
+
86
+ challenge_jwt = challenge_res.parsed_response["nuid.credential.challenge/jwt"]
87
+ render json: {challenge_jwt: challenge_jwt}
88
+ end
89
+
90
+ # Verify is the second part of the login process. The params
91
+ # provided here include the user identification param (email or
92
+ # username), the unaltered challenge_jwt retrieved in phase 1 of login
93
+ # (see #login_challenge above), and the proof that was generated from
94
+ # the challenge_jwt claims and the user secret.
95
+ #
96
+ # The "proof" is generated by your client application using
97
+ # `Zk.proofFromSecretAndChallenge(password, challenge_jwt)` from the
98
+ # `@nuid/zk` npm package.
99
+ def login_verify
100
+ user = User.find(email: params[:email])
101
+ return render(status: :unauthorized) unless user
102
+
103
+ verify_res = NUID_API.challenge_verify(params[:challenge_jwt], params[:proof])
104
+ if res.ok?
105
+ @current_user = user
106
+ # issue session ...
107
+ render(json: @current_user)
108
+ else
109
+ render(status: :unathorized)
110
+ end
111
+ end
112
+ end
113
+ ```
114
+
58
115
  ## Development
59
116
 
60
117
  You'll want to download docker to run the tests, as we depend on the
data/lib/nuid/sdk.rb CHANGED
@@ -1,5 +1,5 @@
1
1
  require "nuid/sdk/version"
2
+ require "nuid/sdk/api/auth"
2
3
 
3
4
  module NuID::SDK
4
- class Error < StandardError; end
5
5
  end
data/lib/nuid/sdk/api/auth.rb CHANGED
@@ -1,12 +1,104 @@
1
1
  require "httparty"
2
2
 
3
3
  module NuID::SDK::API
4
+
5
+ # This class wraps the NuID Auth API endpoints for simpler integration into
6
+ # existing authentication flows.
7
+ #
8
+ # @example User Registration
9
+ # require "nuid-sdk"
10
+ #
11
+ # class UsersController < ApplicationController
12
+ # NUID_API = ::NuID::SDK::API::Auth.new(ENV["NUID_API_KEY"])
13
+ #
14
+ # # The registration form should send the verified credential to be
15
+ # # recorded in the NuID Auth API. The response to that interaction
16
+ # # will provide a `nu/id` key in the response which should be stored
17
+ # # with the newly created user record.
18
+ # #
19
+ # # The "verified credential" is generated by your client application
20
+ # # using `Zk.verifiableFromSecret(password)` from the `@nuid/zk` npm
21
+ # # package.
22
+ # def register
23
+ # credential_res = NUID_API.credential_create(params[:verified_credential])
24
+ # return render(status: :unauthorized) unless credential_res.ok?
25
+ # if credential_res.ok?
26
+ # user_params = params.require(:email, :first_name, :last_name)
27
+ # .merge({nuid: credential_res.parsed_response["nu/id"]})
28
+ # @current_user = User.create(user_params)
29
+ # render json: @current_user, status: :created
30
+ # else
31
+ # render status: :bad_request
32
+ # end
33
+ # end
34
+ # end
35
+ #
36
+ # @example User Login
37
+ # require "nuid-sdk"
38
+ #
39
+ # class SessionsController < ApplicationController
40
+ # NUID_API = ::NuID::SDK::API::Auth.new(ENV["NUID_API_KEY"])
41
+ #
42
+ # # Get a challenge from the Auth API. The client form should request
43
+ # # a challenge as the first of two phases to login. Once a succesful
44
+ # # challenge has been fetched, return it to the client so a proof
45
+ # # can be generated from the challenge claims and the user's password.
46
+ # def login_challenge
47
+ # user = User.find(email: params[:email])
48
+ # return render(status: :unauthorized) unless user
49
+ #
50
+ # credential_res = NUID_API.credential_get(user.nuid)
51
+ # return render(status: :unauthorized) unless credential_res.ok?
52
+ #
53
+ # credential = credential_res.parsed_response["nuid/credential"]
54
+ # challenge_res = NUID_API.challenge_get(credential)
55
+ # return render(status: :unauthorized) unless credential_res.ok?
56
+ #
57
+ # challenge_jwt = challenge_res.parsed_response["nuid.credential.challenge/jwt"]
58
+ # render json: {challenge_jwt: challenge_jwt}
59
+ # end
60
+ #
61
+ # # Verify is the second part of the login process. The params
62
+ # # provided here include the user identification param (email or
63
+ # # username), the unaltered challenge_jwt retrieved in phase 1 of login
64
+ # # (see #login_challenge above), and the proof that was generated from
65
+ # # the challenge_jwt claims and the user secret.
66
+ # #
67
+ # # The "proof" is generated by your client application using
68
+ # # `Zk.proofFromSecretAndChallenge(password, challenge_jwt)` from the
69
+ # # `@nuid/zk` npm package.
70
+ # def login_verify
71
+ # user = User.find(email: params[:email])
72
+ # return render(status: :unauthorized) unless user
73
+ #
74
+ # verify_res = NUID_API.challenge_verify(params[:challenge_jwt], params[:proof])
75
+ # if res.ok?
76
+ # @current_user = user
77
+ # # issue session ...
78
+ # render(json: @current_user)
79
+ # else
80
+ # render(status: :unathorized)
81
+ # end
82
+ # end
83
+ # end
84
+ #
85
+ #
86
+ # @see https://www.npmjs.com/package/@nuid/zk
87
+ # @see https://www.npmjs.com/package/@nuid/cli
4
88
  class Auth
5
89
  include HTTParty
6
90
  base_uri "https://auth.nuid.io"
7
91
 
8
92
  attr_reader :api_key
9
93
 
94
+ # Create an HTTParty instance for dispatching HTTP requests.
95
+ #
96
+ # All endpoints return the HTTParty Response object, with
97
+ # `HTTParty::Response#parsed_response` containing the JSON body converted to
98
+ # a hash.
99
+ #
100
+ # @param api_key [string] The Auth API Key
101
+ # @see https://portal.nuid.io
10
102
  def initialize(api_key)
11
103
  @api_key = api_key
12
104
  self.class.headers({
@@ -15,10 +107,37 @@ module NuID::SDK::API
15
107
  })
16
108
  end
17
109
 
110
+ # Get a credential `challenge` from the API, usually during login flow.
111
+ # The returned `challenge` can be used to generate a proof from the user's
112
+ # secret. Used in conjunction with #challenge_verify.
113
+ #
114
+ # @see https://www.npmjs.com/package/@nuid/zk
115
+ # @see https://www.npmjs.com/package/@nuid/cli
116
+ #
117
+ # @param credential [Hash] A `credential` is usually returned by the
118
+ # #credential_get method
119
+ # @return [HTTParty::Response] use
120
+ # HTTParty::Response#parsed_response["nuid.credential.challenge/jwt"] to
121
+ # get the challenge JWT from the parsed response
18
122
  def challenge_get(credential)
19
123
  _post("/challenge", {"nuid/credential" => credential})
20
124
  end
21
125
 
126
+ # Verify a credential challenge with a proof generated from the challenge
127
+ # claims and the user's secret. Generated proof from the claims contained in
128
+ # the `challenge_jwt` and the user's secret. This proof is generated by
129
+ # `Zk.proofFromSecretAndChallenge(secret, challenge)` available in the npm
130
+ # package `@nuid/zk`.
131
+ #
132
+ # @see https://www.npmjs.com/package/@nuid/zk
133
+ # @see https://www.npmjs.com/package/@nuid/cli
134
+ #
135
+ # @param [String] challenge_jwt the `nuid.credential.challenge/jwt` returned
136
+ # by #challenge_get
137
+ # @param [Hash] proof the generated proof from the challenge jwt claims and
138
+ # user secret
139
+ # @return [HTTParty::Response] use `Response#parsed_response["nu/id"]` to get the
140
+ # parsed JSON body
22
141
  def challenge_verify(challenge_jwt, proof)
23
142
  _post("/challenge/verify", {
24
143
  "nuid.credential.challenge/jwt" => challenge_jwt,
@@ -26,10 +145,34 @@ module NuID::SDK::API
26
145
  })
27
146
  end
28
147
 
148
+ # Create a credential from a verified credential (meaning a credential
149
+ # generated from the user's secret). Usually used during user registration.
150
+ # The parsed response body contains the new credential and the user's unique
151
+ # "nu/id" which should be used as a reference to the user's credential for
152
+ # later authentication attempts.
153
+ #
154
+ # @see #credential_get
155
+ # @see https://www.npmjs.com/package/@nuid/zk
156
+ # @see https://www.npmjs.com/package/@nuid/cli
157
+ #
158
+ # @param verified_credential [Hash] The hash returned by calling `Zk.verifiableFromSecret(secret)`
159
+ # @return [HTTParty::Response] use `Response#parsed_response` to get the
160
+ # parsed JSON body
29
161
  def credential_create(verified_credential)
30
162
  _post("/credential", {"nuid.credential/verified" => verified_credential})
31
163
  end
32
164
 
165
+ # Fetch a credential by it's unique `nuid`. The `nu/id` paramter is extracted
166
+ # from the `#parsed_response` of #credential_create.
167
+ #
168
+ # Generally you will end up storing the nuid with your user record during
169
+ # registration. Later during login use the nuid to fetch the credential
170
+ # using this method, and pass the Response#parsed_response directly to
171
+ # #challenge_get.
172
+ #
173
+ # @param [String] nuid unique key for the credential
174
+ # @return [HTTParty::Response] use `Response#parsed_response` to get the
175
+ # parsed JSON body
33
176
  def credential_get(nuid)
34
177
  self.class.get("/credential/#{nuid}")
35
178
  end
data/lib/nuid/sdk/version.rb CHANGED
@@ -1,5 +1,5 @@
1
1
  module NuID
2
2
  module SDK
3
- VERSION = "0.1.0"
3
+ VERSION = "0.1.1"
4
4
  end
5
5
  end
data/nuid-sdk.gemspec CHANGED
@@ -18,6 +18,7 @@ Gem::Specification.new do |spec|
18
18
  spec.metadata["changelog_uri"] = "https://github.com/NuID/sdk-ruby/blob/master/CHANGELOG.md"
19
19
 
20
20
  spec.add_dependency "httparty", "~> 0.18.1"
21
+ spec.add_development_dependency "yard", "~> 0.9"
21
22
 
22
23
  # Specify which files should be added to the gem when it is released.
23
24
  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: nuid-sdk
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.1.0
4
+ version: 0.1.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - BJ Neilsen
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2021-02-04 00:00:00.000000000 Z
11
+ date: 2021-02-05 00:00:00.000000000 Z
12
12
  dependencies:
13
13
  - !ruby/object:Gem::Dependency
14
14
  name: httparty
@@ -24,6 +24,20 @@ dependencies:
24
24
  - - "~>"
25
25
  - !ruby/object:Gem::Version
26
26
  version: 0.18.1
27
+ - !ruby/object:Gem::Dependency
28
+ name: yard
29
+ requirement: !ruby/object:Gem::Requirement
30
+ requirements:
31
+ - - "~>"
32
+ - !ruby/object:Gem::Version
33
+ version: '0.9'
34
+ type: :development
35
+ prerelease: false
36
+ version_requirements: !ruby/object:Gem::Requirement
37
+ requirements:
38
+ - - "~>"
39
+ - !ruby/object:Gem::Version
40
+ version: '0.9'
27
41
  description:
28
42
  email:
29
43
  - bj.neilsen@gmail.com
@@ -71,7 +85,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
71
85
  - !ruby/object:Gem::Version
72
86
  version: '0'
73
87
  requirements: []
74
- rubygems_version: 3.1.2
88
+ rubygems_version: 3.2.8
75
89
  signing_key:
76
90
  specification_version: 4
77
91
  summary: SDK for interacting with NuID APIs in Ruby