sign_in_service 0.4.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 468897d228e6fcb4e60136303880ae7cc81ef29f134a270b5935e136971f4fd0
+  data.tar.gz: 952139fe857083c0765a3db19f50981d124abefefd2fb2153e3081d60c7a3a06
+SHA512:
+  metadata.gz: 85c5094f9a5366f63ebb4d02d1a782ac68e00be274ad46ee434f69332eb05ad11c8894cdb012d7aeccccebb5dac52b095f2ad6c59d2265799aad012f2a131742
+  data.tar.gz: a47ddae9310aa566e650f4219409fa3f5a7d9a3f3dc194078e9aca22bfbe4561bb6528fdd2120efb1bc547d2ed3d59747e9163190c9f28309a629419cb9aa955

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,40 @@
+require:
+  - rubocop-rspec
+  - rubocop-rake
+
+AllCops:
+  NewCops: disable
+
+Metrics/MethodLength:
+  Max: 20
+
+Style/Documentation:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/BlockLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+# RSpec Cops
+RSpec/ExampleLength:
+  Enabled: false
+
+RSpec/MultipleMemoizedHelpers:
+  Enabled: false
+
+RSpec/NestedGroups:
+  Enabled: false
+
+RSpec/DescribeClass:
+  Enabled: false
+
+RSpec/MultipleExpectations:
+  Enabled: false

data/.ruby-version

@@ -0,0 +1 @@
+3.3

data/Gemfile

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+git_source(:github) { |repo_name| "https://github.com/#{repo_name}.git" }
+
+source 'https://rubygems.org'
+
+gem 'faraday'
+gem 'jwt'
+gem 'rake'
+
+group :test do
+  gem 'rack-test'
+  gem 'rspec'
+end
+
+group :development, :test do
+  gem 'pry-byebug'
+  gem 'rubocop', require: false
+  gem 'rubocop-rake', require: false
+  gem 'rubocop-rspec', require: false
+  gem 'vcr', require: false
+  gem 'webmock', require: false
+end
+
+gemspec

data/Gemfile.lock

@@ -0,0 +1,115 @@
+PATH
+  remote: .
+  specs:
+    sign_in_service (0.4.0)
+      faraday (~> 2.7)
+      jwt (~> 2.8)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    addressable (2.8.6)
+      public_suffix (>= 2.0.2, < 6.0)
+    ast (2.4.2)
+    base64 (0.2.0)
+    bigdecimal (3.1.8)
+    byebug (11.1.3)
+    coderay (1.1.3)
+    crack (1.0.0)
+      bigdecimal
+      rexml
+    diff-lcs (1.5.1)
+    faraday (2.11.0)
+      faraday-net_http (>= 2.0, < 3.4)
+      logger
+    faraday-net_http (3.3.0)
+      net-http
+    hashdiff (1.1.0)
+    json (2.7.2)
+    jwt (2.8.2)
+      base64
+    language_server-protocol (3.17.0.3)
+    logger (1.6.0)
+    method_source (1.0.0)
+    net-http (0.4.1)
+      uri
+    parallel (1.25.1)
+    parser (3.3.4.0)
+      ast (~> 2.4.1)
+      racc
+    pry (0.14.2)
+      coderay (~> 1.1)
+      method_source (~> 1.0)
+    pry-byebug (3.10.1)
+      byebug (~> 11.0)
+      pry (>= 0.13, < 0.15)
+    public_suffix (5.0.5)
+    racc (1.8.1)
+    rack (3.0.9.1)
+    rack-test (2.1.0)
+      rack (>= 1.3)
+    rainbow (3.1.1)
+    rake (13.2.1)
+    regexp_parser (2.9.2)
+    rexml (3.3.6)
+      strscan
+    rspec (3.13.0)
+      rspec-core (~> 3.13.0)
+      rspec-expectations (~> 3.13.0)
+      rspec-mocks (~> 3.13.0)
+    rspec-core (3.13.0)
+      rspec-support (~> 3.13.0)
+    rspec-expectations (3.13.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-mocks (3.13.0)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.13.0)
+    rspec-support (3.13.0)
+    rubocop (1.65.1)
+      json (~> 2.3)
+      language_server-protocol (>= 3.17.0)
+      parallel (~> 1.10)
+      parser (>= 3.3.0.2)
+      rainbow (>= 2.2.2, < 4.0)
+      regexp_parser (>= 2.4, < 3.0)
+      rexml (>= 3.2.5, < 4.0)
+      rubocop-ast (>= 1.31.1, < 2.0)
+      ruby-progressbar (~> 1.7)
+      unicode-display_width (>= 2.4.0, < 3.0)
+    rubocop-ast (1.32.0)
+      parser (>= 3.3.1.0)
+    rubocop-rake (0.6.0)
+      rubocop (~> 1.0)
+    rubocop-rspec (3.0.4)
+      rubocop (~> 1.61)
+    ruby-progressbar (1.13.0)
+    strscan (3.1.0)
+    unicode-display_width (2.5.0)
+    uri (0.13.0)
+    vcr (6.2.0)
+    webmock (3.23.1)
+      addressable (>= 2.8.0)
+      crack (>= 0.3.2)
+      hashdiff (>= 0.4.0, < 2.0.0)
+
+PLATFORMS
+  ruby
+  x86_64-linux
+
+DEPENDENCIES
+  faraday
+  jwt
+  pry-byebug
+  rack-test
+  rake
+  rspec
+  rubocop
+  rubocop-rake
+  rubocop-rspec
+  sign_in_service!
+  vcr
+  webmock
+
+BUNDLED WITH
+   2.4.9

data/LICENSE.txt

@@ -0,0 +1,16 @@
+As a work of the United States Government, this project is in the public domain within the United States.
+
+Additionally, we waive copyright and related rights in the work worldwide through the CC0 1.0 Universal public domain dedication.
+
+CC0 1.0 Universal Summary
+This is a human-readable summary of the Legal Code (read the full text).
+
+No Copyright
+The person who associated a work with this deed has dedicated the work to the public domain by waiving all of his or her rights to the work worldwide under copyright law, including all related and neighboring rights, to the extent allowed by law.
+
+You can copy, modify, distribute and perform the work, even for commercial purposes, all without asking permission.
+
+Other Information
+In no way are the patent or trademark rights of any person affected by CC0, nor are the rights that other persons may have in the work or in how the work is used, such as publicity or privacy rights.
+
+Unless expressly stated otherwise, the person who associated a work with this deed makes no warranties about the work, and disclaims liability for all uses of the work, to the fullest extent permitted by applicable law. When using or citing the work, you should not imply endorsement by the author or the affirmer.

data/README.md

@@ -0,0 +1,88 @@
+Note: This repo is managed by the VA.gov Identity team. Please reference our main product page here for contact information and questions.
+
+# SignInService Ruby Client
+
+The SignInService Ruby client provides a simple and convenient way to interact with the SignInService API for handling OAuth flows.
+
+## Installation
+
+Add gem to your Gemfile
+```ruby
+gem 'sign_in_service', :git => 'git://github.com/department-of-veterans-affairs/sign-in-service-rb.git'
+```
+
+```bash
+bundle install
+```
+## Client Configuration
+
+Configure the SignInService client with your base URL, client ID, and authentication type in an initializer:
+
+```ruby
+require 'sign_in_service'
+
+SignInService::Client.configure do |config|
+  config.base_url = 'https://your_sign_in_service_url'
+  config.client_id = 'your_client_id'
+  config.auth_type = :cookie # or :api
+end
+```
+
+### Auth Types: Cookie vs API
+The SignInService client supports two authentication types: Cookie and API.
+
+#### Cookie Authentication
+With Cookie authentication, tokens are returned in the `Set-Cookie` headers of the response. This approach is typically used in web applications where cookies can be stored and managed directly by the browser.
+
+#### API Authentication
+With API authentication, tokens are returned in the response body. This approach is typically used in non-web applications or scenarios where the application handles the tokens directly, such as mobile apps, desktop apps, or server-side scripts.
+
+### Endpoints
+
+#### Authorization
+- [Authorize](docs/endpoints/authorize.md) - Initiate the OAuth flow
+- [Token](docs/endpoints/token.md) - Exchange authorization code for session tokens
+
+#### Session Management
+- [Refresh](docs/endpoints/refresh.md) - Refresh session tokens.
+- [Logout](docs/endpoints/logout.md) - Log out the user and revoke tokens.
+- [Revoke Token](docs/endpoints/revoke_token.md) - Revoke a sessions tokens.
+- [Revoke All Sessions](docs/endpoints/revoke_all_sessions.md) - Revoke all sessions associated with a user
+
+
+## STS Configuration
+
+```ruby
+
+SignInService::Sts.configure do |config|
+  config.base_url = 'https://api.va.gov' # Sign-in service URL
+  config.service_account_id = 'your_client_id'
+  config.issuer = 'your_client_secret',
+  config.scopes = ["https://api.va.gov/v0/some-path"]
+  config.user_attributes = ['icn'] # optional
+  config.private_key_path = 'path/to/private_key.pem'
+end
+```
+
+Or create a new instance of the STS client with the configuration (overrides the global configuration):
+
+```ruby
+sts_client = SignInService::Sts.new(
+  base_url: 'https://api.va.gov',
+  service_account_id: 'your_client_id',
+  issuer: 'your_client_secret',
+  scopes: ["https://api.va.gov/v0/some-path"],
+  user_attributes: ['icn'], # optional
+  private_key_path: 'path/to/private_key.pem'
+)
+```
+
+#### Token - `/v0/sign_in/token`
+
+When requesting a token you need to pass in a user_identifier to be used as the subject of the token. This can be an ICN, email, or any other unique identifier.
+
+```ruby
+sts = SignInService::Sts.new(user_identifier: '1234567890') # And other configuration options not in the global configuration
+
+token = sts.request_token
+```

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new(:spec)
+
+require 'rubocop/rake_task'
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/docs/endpoints/authorize.md

@@ -0,0 +1,62 @@
+# Authorize
+
+The Authorize Endpoint is responsible for initiating the OAuth 2.0 authorization flow. You can generate an authorization URL, or use the authorization endpoint.
+
+## Generating Authorize URL
+The `authorize_url` method is used to generate a URL.
+
+### Parameters
+
+- `type` (required): The CSP type.
+- `acr` (required): Level of authentication requested.
+- `code_challenge` (required): Used by SignInService to verify requests.
+- `state` (optional): Optional string that can be returned in the callback.
+
+### Example
+
+```ruby
+   client = SignInService::Client.new
+
+   type = "your_csp_type"
+   acr = "your_acr"
+   code_challenge = "your_code_challenge"
+   state = "your_state" # Optional
+
+   auth_url = client.authorize_uri(type: type, acr: acr, code_challenge: code_challenge, state: state)
+```
+
+## Handling Responses
+The `authorize_uri` method returns an authorization URL as a string. You can use this URL to redirect users to the SignInService authorization page.
+
+```ruby
+  redirect_to uri
+```
+
+## Authorize Endpoint
+The `authorize` method is used to interact with the Authorize Endpoint
+
+### Parameters
+- `type` (required): The CSP type.
+- `acr` (required): Level of authentication requested.
+- `code_challenge` (required): Used by SignInService to verify requests.
+- `state` (optional): Optional string that can be returned in the callback.
+
+### Example Usage
+```ruby
+  client = SignInService::Client.new
+
+  # Required parameters
+  type = "your_csp_type"
+  acr = "your_acr"
+  code_challenge = "your_code_challenge"
+  state = "your_state" # Optional
+
+  response = client.authorize(type: type, acr: acr, code_challenge: code_challenge, state: state)
+```
+
+## Handling Responses
+The `authorize` method returns a Faraday::Response object, which contains an HTML body used to redirect to the CSP
+
+```ruby
+  render response.body
+```

data/docs/endpoints/logout.md

@@ -0,0 +1,31 @@
+# Logout
+The Logout Endpoint is responsible for logging out the user and revoking tokens.
+## Usage
+
+##### Parameters
+
+- `access_token` (required): The access token for the associated user.
+- `anti_csrf_token` (optional): An optional token for client-side CSRF protection.
+
+##### Example Usage
+
+```ruby
+  client = SignInService::Client.new
+
+  access_token = "your_id_token_hint"
+  anti_csrf_token = "your_anti_csrf_token" # Optional
+
+  response = client.logout(access_token: access_token, anti_csrf_token: anti_csrf_token)
+```
+
+#### Handling Responses
+The `logout` method returns a Faraday::Response object.
+
+In the case of successful logout from login.gov you can expect an HTTP status code of 302. You will need to
+redirect to the location header and expect a callback
+
+```ruby
+  redirect_to response.headers['location'] if response.status == 302
+```
+
+In the case of id.me you will receive a 200 with an empty body

data/docs/endpoints/refresh.md

@@ -0,0 +1,46 @@
+# Refresh Token
+
+The Refresh Token Endpoint is responsible for refreshing session tokens.
+
+## Usage
+
+### Parameters
+- `refresh_token` (required): The refresh token associated with the user's session.
+- `anti_csrf_token` (optional): An optional token for client-side CSRF protection.
+
+### Example Usage
+``` ruby
+  client = SignInService::Client.new
+
+  refresh_token = "your_refresh_token"
+  anti_csrf_token = "your_anti_csrf_token" # Optional
+
+  response = client.refresh_token(refresh_token: refresh_token, anti_csrf_token: anti_csrf_token)
+```
+
+## Handling Responses
+The `refresh_token` method returns a Faraday::Response object.
+
+### `:cookie` auth type
+Tokens are returned in the `Set-Cookie` headers
+
+```ruby
+  response.headers['set-cookie']
+
+  # vagov_access_token=..., vagov_refresh_token=..., vagov_anti_csrf_token=..., vagov_info_token=...
+```
+
+### `:api` auth type
+Tokens are returned in the response body
+
+```ruby
+  JSON.parse(response.body)
+
+  # {
+  #   "data": {
+  #     "access_token": "<accessTokenHash>", // JWT eyJhbGci0... etc
+  #     "refresh_token": "<refreshTokenHash>", // v1:secure+data+AZX9...
+  #     "anti_csrf_token": "<antiCsrfTokenHash>" // be5aac9...
+  #   }
+  # }
+```

data/docs/endpoints/revoke_all_sessions.md

@@ -0,0 +1,22 @@
+# Revoke All Sessions
+The Revoke All Sessions Endpoint is responsible for revoking all sessions associated with a user.
+
+## Usage
+
+##### Parameters
+
+- `access_token` (required): The access token associated with the user's session.
+
+##### Example Usage
+
+```ruby
+  client = SignInService::Client.new
+
+  access_token access_token = "your_access_token"
+
+  response = client.revoke_all_sessions(access_token: access_token)
+```
+
+#### Handling Responses
+
+The `revoke_all_sessions` method returns a Faraday::Response object. If successful, the response contains an HTTP status code of 200.

data/docs/endpoints/revoke_token.md

@@ -0,0 +1,23 @@
+# Revoke Token
+
+The Revoke Token Endpoint is responsible for revoking a session.
+
+## Usage
+
+### Parameters
+
+- `refresh_token` (required): The refresh token associated with the user's session.
+- `anti_csrf_token` (optional): A token for client-side CSRF protection.
+
+### Example Usage
+
+```ruby
+  client = SignInService::Client.new
+  refresh_token refresh_token = "your_refresh_token"
+  anti_csrf_token = "your_anti_csrf_token" (optional)
+
+  response = client.revoke_token(refresh_token: refresh_token, anti_csrf_token: anti_csrf_token)
+```
+
+## Handling Responses
+The `revoke_token` method returns a Faraday::Response object. If successful, the response contains an HTTP status code of 200 and an empty body.

data/docs/endpoints/token.md

@@ -0,0 +1,48 @@
+# Token
+The Token Endpoint is responsible for exchanging an authorization code for session tokens.
+
+## Usage
+
+### Parameters
+
+- `code` (required): The code received from the authorize callback.
+- `code_verifier` (required): The string stored client-side from the code_challenge.
+
+### Example
+
+```ruby
+  client = SignInService::Client.new
+
+  # Assuming you have a valid authorization code and code_verifier
+  code = "your_authorization_code"
+  code_verifier = "your_code_verifier"
+
+  response = client.get_token(code: code, code_verifier: code_verifier)
+```
+
+## Handling Responses
+The `get_token` method returns a Faraday::Response object.
+
+### `:cookie` auth type
+Tokens are returned in the `Set-Cookie` headers
+
+```ruby
+  response.headers['set-cookie']
+
+  # vagov_access_token=..., vagov_refresh_token=..., vagov_anti_csrf_token=..., vagov_info_token=...
+```
+
+### `:api` auth type
+Tokens are returned in the response body
+
+```ruby
+  JSON.parse(response.body)
+
+  # {
+  #   "data": {
+  #     "access_token": "<accessTokenHash>", // JWT eyJhbGci0... etc
+  #     "refresh_token": "<refreshTokenHash>", // v1:secure+data+AZX9...
+  #     "anti_csrf_token": "<antiCsrfTokenHash>" // be5aac9...
+  #   }
+  # }
+```

data/lib/sign_in_service/client/authorize.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+module SignInService
+  class Client
+    module Authorize
+      AUTHORIZE_PATH = '/v0/sign_in/authorize'
+      TOKEN_PATH = '/v0/sign_in/token'
+
+      ##
+      # Generates an authorization URI.
+      # It is used in the OAuth 2.0 authorization code flow.
+      #
+      # @param type [String] The CSP type
+      # @param acr [String] Level of authentication requested
+      # @param code_challenge [String] Used by SiS to verify requests
+      # @param state [String] Optional string that can be returned in callback
+      #
+      # @return [String] URI to authorize client
+      #
+
+      def authorize_uri(type:, acr:, code_challenge: nil, state: nil)
+        uri = URI.join(base_url, AUTHORIZE_PATH)
+        params = {
+          acr:,
+          client_id:,
+          code_challenge:,
+          code_challenge_method:,
+          state:,
+          type:
+        }.compact
+
+        uri.query = URI.encode_www_form(params)
+
+        uri.to_s
+      end
+
+      ##
+      # Makes call to authorize path.
+      # For :api auth_type applications
+      #
+      # @param type [String] The CSP type
+      # @param acr [String] Level of authentication requested
+      # @param code_challenge [String] Used by SiS to verify requests
+      # @param state [String] Optional string that can be returned in callback
+      #
+      # @return [Faraday::Response] Contains 'code' parameter used to exchange for token
+      #
+      def authorize(type:, acr:, code_challenge:, state: nil)
+        params = {
+          acr:,
+          client_id:,
+          code_challenge:,
+          code_challenge_method:,
+          state:,
+          type:
+        }.compact
+
+        connection.get(AUTHORIZE_PATH, params)
+      end
+
+      ##
+      # Exchange code for session tokens
+      #
+      # @param code [String] The code received form the authorize callback
+      # @param code_verifier [String] String stored client side from code_challenge
+      #
+      # @return [Faraday::Response] Response with tokens in header or body
+      #
+      def get_token(code:, code_verifier: nil, client_assertion: nil)
+        params = {
+          code:,
+          code_verifier:,
+          grant_type:,
+          client_assertion:
+        }.compact
+
+        params[:client_assertion_type] = client_assertion_type unless client_assertion.nil?
+
+        connection.post(TOKEN_PATH, params)
+      end
+    end
+  end
+end

data/lib/sign_in_service/client/config.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+module SignInService
+  class Client
+    module Config
+      class << self
+        DEFAULT_BASE_URL = 'http://localhost:3000'
+        DEFAULT_CLIENT_ID = 'sample'
+        DEFAULT_AUTH_TYPE = :cookie
+        DEFAULT_AUTH_FLOW = :pkce
+
+        attr_writer :base_url, :client_id, :auth_type, :auth_flow
+
+        def base_url
+          @base_url || DEFAULT_BASE_URL
+        end
+
+        def client_id
+          @client_id || DEFAULT_CLIENT_ID
+        end
+
+        def auth_type
+          @auth_type || DEFAULT_AUTH_TYPE
+        end
+
+        def auth_flow
+          @auth_flow || DEFAULT_AUTH_FLOW
+        end
+
+        def to_h
+          {
+            base_url:,
+            client_id:,
+            auth_type:,
+            auth_flow:
+          }
+        end
+      end
+    end
+  end
+end

data/lib/sign_in_service/client/session.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module SignInService
+  class Client
+    module Session
+      LOGOUT_PATH = '/v0/sign_in/logout'
+      REFRESH_PATH = '/v0/sign_in/refresh'
+      REVOKE_PATH = '/v0/sign_in/revoke'
+      REVOKE_ALL_PATH = '/v0/sign_in/revoke_all_sessions'
+
+      ##
+      # Destroys the user session associated with the access token.
+      #
+      # @param access_token [String] Access token of session to logout of
+      # @param anti_csrf_token [String] Optional token if enabled on client
+      #
+      # @return [Faraday::Response] Empty body with a 200 status
+      #
+      def logout(access_token:, anti_csrf_token: nil)
+        connection.get(LOGOUT_PATH) do |req|
+          req.params[:client_id] = client_id
+          if cookie_auth?
+            req.headers = cookie_header({ access_token:, anti_csrf_token: })
+          else
+            req.params[:anti_csrf_token] = anti_csrf_token
+            req.headers = api_header(access_token)
+          end
+        end
+      end
+
+      ##
+      # Refresh session tokens
+      #
+      # @param refresh_token [String] URI-encoded refresh token
+      # @param anti_csrf_token [String] Optional token if enabled on client
+      #
+      # @return [Faraday::Response] Response with tokens in header or body
+      #
+      def refresh_token(refresh_token:, anti_csrf_token: nil)
+        connection.post(REFRESH_PATH) do |req|
+          if cookie_auth?
+            req.headers = cookie_header({ refresh_token:, anti_csrf_token: })
+          else
+            req.params[:refresh_token] = refresh_token
+            req.params[:anti_csrf_token] = anti_csrf_token if anti_csrf_token
+          end
+        end
+      end
+
+      ##
+      # Revokes a user session
+      #
+      # @param refresh_token [String] URI-encoded refresh token
+      # @param anti_csrf_token [String] Optional token if enabled on client
+      #
+      # @return [Faraday::Response] Empty body with a 200 status
+      #
+      def revoke_token(refresh_token:, anti_csrf_token:)
+        connection.post(REVOKE_PATH) do |req|
+          req.params[:refresh_token] = CGI.escape(refresh_token)
+          req.params[:anti_csrf_token] = CGI.escape(anti_csrf_token)
+        end
+      end
+
+      ##
+      # Revokes all sessions associated with a user
+      #
+      # @param access_token [String] Access token of session
+      #
+      # @return [Faraday::Response] Empty body with a 200 status
+      #
+      def revoke_all_sessions(access_token:)
+        connection.get(REVOKE_ALL_PATH) do |req|
+          req.headers = if cookie_auth?
+                          cookie_header({ access_token: })
+                        else
+                          api_header(access_token)
+                        end
+        end
+      end
+
+      private
+
+      def cookie_header(tokens)
+        {
+          Cookie: tokens.map do |name, value|
+                    "#{COOKIE_TOKEN_PREFIX}_#{name}=#{CGI.escape(value)}" unless value.nil?
+                  end.join(';')
+        }
+      end
+
+      def api_header(access_token)
+        {
+          Authorization: "Bearer #{CGI.escape(access_token)}"
+        }
+      end
+    end
+  end
+end

data/lib/sign_in_service/client.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require 'faraday'
+
+require_relative 'client/authorize'
+require_relative 'client/session'
+require_relative 'client/config'
+require_relative 'response/raise_error'
+
+module SignInService
+  class Client
+    include SignInService::Client::Config
+    include SignInService::Client::Authorize
+    include SignInService::Client::Session
+
+    COOKIE_TOKEN_PREFIX = 'vagov'
+    AUTH_TYPES = [COOKIE_AUTH = :cookie, API_AUTH = :api].freeze
+    AUTH_FLOWS = [PKCE_FLOW = :pkce, JWT_FLOW = :jwt].freeze
+
+    class << self
+      def configure
+        yield Config
+      end
+
+      def config
+        Config
+      end
+    end
+
+    attr_accessor :base_url, :client_id, :auth_type, :auth_flow
+
+    def initialize(**options)
+      @base_url = options[:base_url] || Config.base_url
+      @client_id = options[:client_id] || Config.client_id
+      @auth_type = options[:auth_type] || Config.auth_type
+      @auth_flow = options[:auth_flow] || Config.auth_flow
+    end
+
+    def grant_type
+      'authorization_code'
+    end
+
+    def code_challenge_method
+      'S256'
+    end
+
+    def client_assertion_type
+      'urn:ietf:params:oauth:client-assertion-type:jwt-bearer'
+    end
+
+    def connection
+      @connection ||= Faraday.new(base_url) do |conn|
+        conn.request :json
+        conn.response :json, content_type: /\bjson$/
+        conn.adapter Faraday.default_adapter
+        conn.use SignInService::Response::RaiseError
+      end
+    end
+
+    def api_auth?
+      auth_type.to_sym == API_AUTH
+    end
+
+    def cookie_auth?
+      auth_type.to_sym == COOKIE_AUTH
+    end
+  end
+end

data/lib/sign_in_service/error.rb

@@ -0,0 +1,113 @@
+# frozen_string_literal: true
+
+module SignInService
+  class Error < StandardError
+    attr_reader :response, :response_headers, :response_body, :errors
+
+    def self.from_response(response)
+      status = response[:status].to_i
+
+      klass = case status
+              when 400 then BadRequest
+              when 401 then Unauthorized
+              when 403 then Forbidden
+              when 404 then NotFound
+              when 422 then UnprocessableEntity
+              when 400..499 then ClientError
+              when 500 then InternalServerError
+              when 501 then NotImplemented
+              when 502 then BadGateway
+              when 503 then ServiceUnavailable
+              when 500..599 then ServerError
+              end
+
+      klass&.new(response)
+    end
+
+    def initialize(response)
+      @response = response
+      @response_headers = response[:response_headers]
+      @response_body = parsed_response_body
+      @errors = fetch_errors
+      super(error_message)
+    end
+
+    private
+
+    def fetch_errors
+      case parsed_response_body
+      when Hash
+        parsed_response_body[:errors]
+      when String
+        parsed_response_body
+      end
+    end
+
+    def error_message
+      case errors
+      when Hash
+        format_errors(errors)
+      when String
+        errors
+      end
+    end
+
+    def format_errors(errors)
+      case errors
+      when Hash
+        errors.flat_map do |key, values|
+          values.map { |message| "#{key} #{message}" }
+        end.join(', ')
+      when Array
+        errors.join(', ')
+      when String
+        errors
+      end
+    end
+
+    def parsed_response_body
+      @parsed_response_body ||= if response_headers && response_headers['content-type'] =~ /json/
+                                  begin
+                                    JSON.parse(response[:body], symbolize_names: true)
+                                  rescue JSON::ParserError
+                                    {}
+                                  end
+                                else
+                                  response[:body]
+                                end
+    end
+  end
+
+  # Raised on errors in the 400-499 range
+  class ClientError < Error; end
+
+  # Raised when SignInService returns a 400 HTTP status code
+  class BadRequest < ClientError; end
+
+  # Raised when SignInService returns a 401 HTTP status code
+  class Unauthorized < ClientError; end
+
+  # Raised when SignInService returns a 403 HTTP status code
+  class Forbidden < ClientError; end
+
+  # Raised when SignInService returns a 404 HTTP status code
+  class NotFound < ClientError; end
+
+  # Raised when SignInService returns a 422 HTTP status code
+  class UnprocessableEntity < ClientError; end
+
+  # Raised on SignInService in the 500-599 range
+  class ServerError < Error; end
+
+  # Raised when SignInService returns a 500 HTTP status code
+  class InternalServerError < ServerError; end
+
+  # Raised when SignInService returns a 501 HTTP status code
+  class NotImplemented < ServerError; end
+
+  # Raised when SignInService returns a 502 HTTP status code
+  class BadGateway < ServerError; end
+
+  # Raised when SignInService returns a 503 HTTP status code
+  class ServiceUnavailable < ServerError; end
+end

data/lib/sign_in_service/response/raise_error.rb

@@ -0,0 +1,16 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'sign_in_service/error'
+
+module SignInService
+  module Response
+    class RaiseError < Faraday::Middleware
+      def on_complete(response)
+        return unless (error = SignInService::Error.from_response(response))
+
+        raise error
+      end
+    end
+  end
+end

data/lib/sign_in_service/sts/config.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module SignInService
+  class Sts
+    module Config
+      class << self
+        DEFAULT_STS_BASE_URL = 'https://staging-api.va.gov/v0/sign_in'
+
+        attr_accessor :issuer, :scopes, :service_account_id, :user_attributes, :private_key_path
+
+        attr_writer :base_url
+
+        def base_url
+          @base_url || DEFAULT_STS_BASE_URL
+        end
+      end
+    end
+  end
+end

data/lib/sign_in_service/sts/token.rb

@@ -0,0 +1,54 @@
+# frozen_string_literal: true
+
+module SignInService
+  class Sts
+    module Token
+      TOKEN_PATH = '/v0/sign_in/token'
+      ACCESS_TOKEN_DURATION = 300
+      JWT_ENCODE_ALGORITHM = 'RS256'
+
+      def token
+        params = { grant_type:, assertion: }
+        response = connection.post(TOKEN_PATH, params)
+
+        response.body.dig('data', 'access_token')
+      end
+
+      private
+
+      def assertion
+        JWT.encode(assertion_payload, private_key, JWT_ENCODE_ALGORITHM)
+      end
+
+      def assertion_payload
+        {
+          iss: issuer,
+          sub: user_identifier,
+          aud:,
+          iat:,
+          exp:,
+          jti:,
+          scopes:,
+          service_account_id:,
+          user_attributes:
+        }.compact
+      end
+
+      def aud
+        "#{base_url}#{TOKEN_PATH}"
+      end
+
+      def iat
+        @iat ||= Time.now.to_i
+      end
+
+      def exp
+        iat + ACCESS_TOKEN_DURATION
+      end
+
+      def jti
+        SecureRandom.hex
+      end
+    end
+  end
+end

data/lib/sign_in_service/sts.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+require 'faraday'
+require 'jwt'
+
+require_relative 'sts/config'
+require_relative 'sts/token'
+
+module SignInService
+  class Sts
+    include Config
+    include Token
+
+    REQUIRED_ATTRIBUTES = %i[user_identifier issuer service_account_id private_key_path base_url].freeze
+
+    class << self
+      def configure
+        yield Config
+      end
+    end
+
+    attr_reader :user_identifier, :issuer, :scopes, :service_account_id,
+                :user_attributes, :private_key_path, :base_url
+
+    def initialize(user_identifier:, **options)
+      @user_identifier = user_identifier
+      @issuer = options[:issuer] || Config.issuer
+      @scopes = options[:scopes] || Config.scopes || []
+      @service_account_id = options[:service_account_id] || Config.service_account_id
+      @user_attributes = options[:user_attributes] || Config.user_attributes
+      @private_key_path = options[:private_key_path] || Config.private_key_path
+      @base_url = options[:base_url] || Config.base_url
+
+      validate_arguments!
+    end
+
+    private
+
+    def connection
+      @connection ||= Faraday.new(base_url) do |conn|
+        conn.adapter Faraday.default_adapter
+        conn.request :json
+        conn.response :json, content_type: /\bjson$/
+        conn.use SignInService::Response::RaiseError
+      end
+    end
+
+    def grant_type
+      'urn:ietf:params:oauth:grant-type:jwt-bearer'
+    end
+
+    def private_key
+      OpenSSL::PKey::RSA.new(File.read(private_key_path))
+    end
+
+    def validate_arguments!
+      REQUIRED_ATTRIBUTES.each do |attribute|
+        raise ArgumentError, "missing required attribute: #{attribute}" if send(attribute).nil?
+      end
+
+      raise ArgumentError, 'scopes must be an array' unless scopes.is_a?(Array)
+    end
+  end
+end

data/lib/sign_in_service/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module SignInService
+  VERSION = '0.4.0'
+end

data/lib/sign_in_service.rb

@@ -0,0 +1,4 @@
+# frozen_string_literal: true
+
+require 'sign_in_service/client'
+require 'sign_in_service/sts'

data/sign_in_service.gemspec

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require_relative 'lib/sign_in_service/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'sign_in_service'
+  spec.version = SignInService::VERSION
+  spec.authors = ['Riley Anderson']
+  spec.email = ['riley.anderson@oddball.io']
+
+  spec.summary = 'Wrapper for the VA SignInService API'
+  spec.homepage = 'https://github.com/department-of-veterans-affairs/sign-in-service-rb'
+  spec.license  = 'CC0-1.0'
+  spec.required_ruby_version = '>= 3.3'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = 'https://github.com/department-of-veterans-affairs/sign-in-service-rb'
+
+  # 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.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) || f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor])
+    end
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  # Uncomment to register a new dependency of your gem
+  spec.add_dependency 'faraday', '~> 2.7'
+  spec.add_dependency 'jwt', '~> 2.8'
+
+  # For more information and examples about making a new gem, check out our
+  # guide at: https://bundler.io/guides/creating_gem.html
+end

metadata

@@ -0,0 +1,99 @@
+--- !ruby/object:Gem::Specification
+name: sign_in_service
+version: !ruby/object:Gem::Version
+  version: 0.4.0
+platform: ruby
+authors:
+- Riley Anderson
+autorequire:
+bindir: exe
+cert_chain: []
+date: 2024-08-28 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: faraday
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.7'
+- !ruby/object:Gem::Dependency
+  name: jwt
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.8'
+description:
+email:
+- riley.anderson@oddball.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- ".ruby-version"
+- Gemfile
+- Gemfile.lock
+- LICENSE.txt
+- README.md
+- Rakefile
+- docs/endpoints/authorize.md
+- docs/endpoints/logout.md
+- docs/endpoints/refresh.md
+- docs/endpoints/revoke_all_sessions.md
+- docs/endpoints/revoke_token.md
+- docs/endpoints/token.md
+- lib/sign_in_service.rb
+- lib/sign_in_service/client.rb
+- lib/sign_in_service/client/authorize.rb
+- lib/sign_in_service/client/config.rb
+- lib/sign_in_service/client/session.rb
+- lib/sign_in_service/error.rb
+- lib/sign_in_service/response/raise_error.rb
+- lib/sign_in_service/sts.rb
+- lib/sign_in_service/sts/config.rb
+- lib/sign_in_service/sts/token.rb
+- lib/sign_in_service/version.rb
+- sign_in_service.gemspec
+homepage: https://github.com/department-of-veterans-affairs/sign-in-service-rb
+licenses:
+- CC0-1.0
+metadata:
+  homepage_uri: https://github.com/department-of-veterans-affairs/sign-in-service-rb
+  source_code_uri: https://github.com/department-of-veterans-affairs/sign-in-service-rb
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.11
+signing_key:
+specification_version: 4
+summary: Wrapper for the VA SignInService API
+test_files: []