NuID SDK for Ruby

This repo provides a Ruby Gem for interacting with NuID APIs within Ruby applications.

Read the latest gem docs or checkout the platform docs for API docs, guides, video tutorials, and more.

Install

From rubygems:

gem install nuid-sdk -v "0.1.1"

Or with bundler:

# Gemfile
gem "nuid-sdk", "~> 0.1.1"

Usage

Example rails auth controller.

For a more detailed example visit the Integrating with NuID guide and the accompanying examples repo. A ruby-specific code example is coming soon.

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.parsed_response["nu/id"]})
      @current_user = User.create(user_params)
      render json: @current_user, status: :created
    else
      render status: :bad_request
    end
  end
end
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 
    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 
    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 @nuid/cli npm package to provide a CLI you can shell out to in the tests for generating zk crypto. After checking out the repo, run bin/setup to install dependencies and create the docker environment. Then, run make test to run the tests inside the running container. You can also run bin/console for an interactive prompt that will allow you to experiment, but you'll probably want to run that in the container (use make shell to get a prompt in the container).

make clean will stop and destroy the container and image. make build run will rebuild the image and run the container.

To install this gem onto your local machine, run bundle exec rake install. To release a new version, update the version number in version.rb, and then run bundle exec rake release, which will create a git tag for the version, push git commits and tags, and push the .gem file to rubygems.org.

Contributing

Bug reports and pull requests are welcome on GitHub at https://github.com/NuID/sdk-ruby.

License

The gem is available as open source under the terms of the MIT License.