th7-clerk-sdk-ruby 4.2.2

data/README.md

@@ -0,0 +1,278 @@
+<p align="center">
+  <a href="https://www.clerk.com/?utm_source=github&utm_medium=starter_repos&utm_campaign=sdk_ruby" target="_blank" align="center">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="./docs/clerk-logo-dark.png">
+      <img src="./docs/clerk-logo-light.png" height="64">
+    </picture>
+  </a>
+  <br />
+</p>
+
+# Clerk Ruby SDK
+
+This SDK allows you to call the [Clerk](https://www.clerk.com/?utm_source=github&utm_medium=starter_repos&utm_campaign=sdk_ruby) Backend API from Ruby code without having to implement the calls yourself.
+
+[![chat on Discord](https://img.shields.io/discord/856971667393609759.svg?logo=discord)](https://discord.com/invite/b5rXHjAg7A)
+[![documentation](https://img.shields.io/badge/documentation-clerk-green.svg)](https://clerk.com/docs)
+[![twitter](https://img.shields.io/twitter/follow/ClerkDev?style=social)](https://twitter.com/intent/follow?screen_name=ClerkDev)
+
+---
+
+**Clerk is Hiring!**
+
+Would you like to work on Open Source software and help maintain this repository? [Apply today!](https://apply.workable.com/clerk-dev/)
+
+---
+
+**Note**: You're looking at the main branch, which requires that you use [Auth
+v2](https://clerk.com/docs/upgrade-guides/auth-v2).
+
+If you're looking for the legacy authentication scheme, refer to the
+[`v1`](https://github.com/clerkinc/clerk-sdk-ruby/tree/v1) branch.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'clerk-sdk-ruby', require: "clerk"
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install clerk-sdk-ruby
+
+## Quick Start
+
+First, you need to get an API key for a Clerk instance. This is done via the
+[Clerk dashboard](https://dashboard.clerk.com/applications).
+
+Then you can instantiate a `Clerk::SDK` instance and access all
+[Backend API](https://clerk.com/docs/reference/backend-api) endpoints.
+Here's a quick example:
+
+```ruby
+clerk = Clerk::SDK.new(api_key: "your_api_key")
+# List all users
+clerk.users.get_user_list
+# Get your first user
+user = clerk.users.get_user_list(limit: 1).first
+# Extract their primary email address ID
+email_id = user["primary_email_address_id"]
+
+# Create an organization
+p Clerk::SDK.organizations.create_organization({
+  create_organization_request: ClerkHttpClient::CreateOrganizationRequest.new({
+    name: 'example'
+  })
+})
+```
+
+## Configuration
+
+The SDK can be configured in three ways: environment variables, configuration
+singleton and constructor arguments. The priority goes like this:
+
+1. Constructor arguments
+2. Configuration object
+3. Environment variables
+
+If an argument is not provided, the configuration object is looked up, which
+falls back to the associated environment variable. Here's an example with all
+supported configuration settings their environment variable equivalents:
+
+```ruby
+Clerk.configure do |c|
+  c.secret_key = "sk_(test|live)_...." # if omitted: ENV["CLERK_SECRET_KEY"] - API calls will fail if unset
+  c.publishable_key = "pk_(test|live)_...." # if omitted: ENV["CLERK_PUBLISHABLE_KEY"] - Handshake mechanism (check section below) will fail if unset
+  c.logger = Logger.new(STDOUT) # if omitted, no logging
+  c.middleware_cache_store = ActiveSupport::Cache::FileStore.new("/tmp/clerk_middleware_cache") # if omitted: no caching
+  c.excluded_routes ["/foo", "/bar/*"]
+end
+```
+
+You can customize each instance of the `Clerk::SDK` object by passing keyword
+arguments to the constructor:
+
+```ruby
+clerk = Clerk::SDK.new(
+    logger: Logger.new()
+    secret_key: "X",
+)
+```
+
+For full customization, you can instead pass a `Faraday` object directly, which
+will ignore all the other arguments, if passed:
+
+```ruby
+faraday = Faraday.new()
+clerk = Clerk::SDK.new(connection: faraday)
+```
+
+Refer to the [Faraday documentation](https://lostisland.github.io/faraday/usage/#customizing-faradayconnection)
+for details.
+
+## Rack middleware
+
+The SDK comes with a Rack middleware which lazily loads the Clerk session and
+user. It inserts a `clerk` key in the Rack environment, which is an instance
+of `Clerk::Proxy`. To get the session or the user of the session, you call
+`session` or `user` respectively. In case there is no session, you can retrieve
+the API error with the `error` getter method.
+
+```ruby
+use Clerk::Rack::Middleware
+```
+
+### Reverification middleware
+
+The SDK comes with a revalidation middleware which will automatically revalidate the session when the user navigates to a protected route.
+
+```ruby
+use Clerk::Rack::Reverification,
+  preset: Clerk::StepUp::Preset::LAX,
+  routes: ["/*"]
+```
+
+
+
+## Rails integration
+
+The SDK will automatically add the [Rack middleware](#rack-middleware) to the
+middleware stack. For easier access to the Clerk session and user, include the
+`Clerk::Authenticatable` concern in your controller:
+
+```ruby
+class ApplicationController < ActionController::Base
+  include Clerk::Authenticatable
+end
+
+class AdminController < ApplicationController
+  before_action :require_reverification!, only: [:protected]
+
+  def index
+    @user = clerk.user
+  end
+
+  def protected
+    render json: {message: clerk.user? ? "Valid session" : "Not logged in"}
+  end
+end
+```
+
+This gives your controller and views access to the following methods and more:
+
+- `clerk.sdk.*`
+- `clerk.user?`
+- `clerk.user`: NOTE: This makes an additional request and attempts to cache it.
+- `clerk.user_id`
+- `clerk.organization?`
+- `clerk.organization` NOTE: This makes an additional request and attempts to cache it.
+- `clerk.organization_id`
+- `clerk.organization_role`
+- `clerk.organization_permissions`
+
+### Skipping the Railtie
+
+There are cases where you might not want to use the Railtie, for example, only using the SDK in a Rails application. To accomplish this, you can set the `CLERK_SKIP_RAILTIE` environment variable to `true`.
+
+This will prevent the Railtie from being loaded and the Rack middleware from being added to the middleware stack.
+
+You can still configure the SDK as normal, but you will need to call the SDK using `Clerk::SDK.new` instead of the `clerk.sdk` helper.
+
+## Sinatra integration
+
+The SDK enables the use of Extensions to add Clerk support to your Sinatra application.
+
+`Sinatra::Clerk` will automatically add the [Rack middleware](#rack-middleware)to the
+middleware stack and enable easy access to the Clerk session and user helper methods.
+
+```ruby
+class App < Sinatra::Base
+  register Sinatra::Clerk
+
+  get "/" do
+    erb :index, format: :html5
+  end
+
+  get "/admin" do
+    @user = clerk.user
+    erb :index, format: :html5
+  end
+
+  get "/protected" do
+    require_reverification!
+    {message: clerk.user? ? "Valid session" : "Not logged in"}.to_json
+  end
+end
+```
+
+## Internals
+
+The API client depends on the excellent [Faraday](https://rubygems.org/gems/faraday)
+gem for HTTP requests. You can swap out the original implementation with your
+own customized instance.
+
+The API client sends all requests as `application/x-www-form-urlencoded`. The
+API then responds with JSON which is then converted and returned as a Ruby
+`Hash`, or `Array` of hashes. Errors are also returned as a JSON object, with a
+single key (`errors`) containing an array of error objects.
+
+Read the [API documentation](https://clerk.com/docs/reference/backend-api)
+for details on expected parameters and response formats.
+
+<a name="handshake"></a>
+
+### Handshake
+
+The Client Handshake is a mechanism that is used to resolve a request’s authentication state from “unknown” to definitively signed in or signed out. Clerk’s session management architecture relies on a short-lived session JWT to validate requests, along with a long-lived session that is used to keep the session JWT fresh by interacting with the Frontend API. The long-lived session token is stored in an HttpOnly cookie associated with the Frontend API domain. If a short-lived session JWT is expired on a request to an application’s backend, the SDK doesn’t know if the session has ended, or if a new short-lived JWT needs to be issued. When an SDK gets into this state, it triggers the handshake.
+
+With the handshake, we can resolve the authentication state on the backend and ensure the request is properly handled as signed in or out, instead of being in a potentially “unknown” state. The handshake flow relies on redirects to exchange session information between FAPI and the application, ensuring the resolution of unknown authentication states minimizes performance impact and behaves consistently across different framework and language implementations.
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run
+`bundle exec rake spec` to run the tests. You can also run `bin/console` for an
+interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. 
+
+To run the example applications, run:
+
+```bash
+rake app:rack    
+rake app:rails  
+rake app:rails:api
+rake app:sinatra
+```
+
+## Release
+
+To release a new version:
+- update the version number in `version.rb`
+- update `CHANGELOG.md` to include information about the changes
+- merge changes into main
+- run `bundle exec rake release`
+
+If gem publishing is NOT executed automatically:
+- run `gem push pkg/clerk-sdk-ruby-{version}.gem` to push the `.gem` file to [rubygems.org](https://rubygems.org)
+
+The `bundle exec rake release` command:
+- creates a git tag with the version found in `version.rb`
+- pushes the git tag
+
+## Yank release
+
+We should avoid yanking a releasing but if it's necessary execute `gem yank clerk-sdk-ruby -v {version}`
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/clerkinc/clerk-sdk-ruby.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,56 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "standard/rake"
+
+################################
+# COVERAGE
+################################
+
+desc "Open coverage report"
+task(:cov) { system "open coverage/index.html" }
+
+################################
+# TESTING
+################################
+
+desc "Run all tests"
+task spec: "spec:all"
+
+namespace :spec do
+  task(:all) { system "bundle exec rspec" }
+
+  desc "Run tests on file changes"
+  task(:watch) { system "bundle exec guard -g spec" }
+
+  desc "Run failed tests only"
+  task(:failed) { system "bundle exec rspec --only-failures" }
+end
+
+################################
+# PLAYGROUND APPLICATIONS
+################################
+
+namespace :app do
+  desc "Run Rails (full stack) application"
+  task rails: "rails:full"
+
+  namespace :rails do
+    task :full do
+      cd ("apps/rails-full") { system "bin/rails server" }
+    end
+
+    desc "Run Rails (API only) application"
+    task :api do
+      cd ("apps/rails-api") { system "bin/rails server" }
+    end
+  end
+
+  desc "Run Rack application"
+  task(:rack) { system "rerun --dir lib,apps/rack --pattern '**/*.{rb,ru}' -- bundle exec puma apps/rack/config.ru -p 3000" }
+
+  desc "Run Sinatra application"
+  task(:sinatra) { system "rerun --dir lib,apps/sinatra --pattern '**/*.{erb,rb,ru}' -- bundle exec puma apps/sinatra/config.ru -p 3000 -v" }
+end
+
+

data/apps/rack/app.rb

@@ -0,0 +1,67 @@
+require "erb"
+require "clerk"
+
+class App
+  def call(env)
+    # # Example: Without using `Clerk::Rack::Reverification` Middleware
+    # preset = Clerk::StepUp::Preset::LAX
+    # if env["clerk"].user_needs_reverification?(preset)
+    #   return env["clerk"].user_reverification_rack_response(preset)
+    # end
+
+    respond_with(200) do
+      user = env["clerk"].user
+      user ? "Authenticated User: #{user.first_name} (#{user.id})" : "Not Authenticated"
+    end
+  end
+
+  private
+
+  def respond_with(status, plain_body = nil, &html_body)
+    return [status, {"Content-Type" => "text/plain; charset=utf-8"}, [plain_body]] unless block_given?
+
+    compiled = <<-HTML
+      <html>
+        <head>
+          <title>Rack</title>
+          <style>
+            html { font-family: monospace; }
+            @media (prefers-color-scheme: dark) {
+              html {
+                color: #FFE6E6FF;
+                background-color: #201D1E;
+              }
+            }
+          </style>
+          <script
+            async 
+            crossorigin="anonymous"
+            data-clerk-publishable-key="#{ENV["CLERK_PUBLISHABLE_KEY"]}"
+            src="#{ENV["CLERK_JS_URL"]}"
+            type="text/javascript"
+          ></script>
+          <script>
+            window.addEventListener('load', async function () {
+              await Clerk.load()
+              const container = document.getElementById('auth-container')
+              if (Clerk.user) {
+                container.innerHTML = `<div id="user-button"></div>`
+                Clerk.mountUserButton(document.getElementById('user-button'))
+              } else {
+                container.innerHTML = `<div id="sign-in"></div>`
+                Clerk.mountSignIn(document.getElementById('sign-in'))
+              }
+            })
+          </script>
+        </head>
+        <body>
+          <h1>Rack</h1>
+          <h2>#{yield}</h2>
+          <div id="auth-container"></div>
+        </body>
+      </html>
+    HTML
+
+    [status, {"Content-Type" => "text/html; charset=utf-8"}, [compiled]]
+  end
+end

data/apps/rack/config.ru

@@ -0,0 +1,17 @@
+require "active_support"
+require "rack"
+require "clerk/rack"
+require "dotenv"
+
+require_relative "app"
+require_relative "middleware/disable_paths"
+
+Dotenv.load(".env")
+
+use DisablePaths, paths: ["/favicon.ico"]
+use Clerk::Rack::Middleware
+use Clerk::Rack::Reverification,
+  preset: Clerk::StepUp::Preset::LAX,
+  routes: ["/*"]
+
+run App.new

data/apps/rack/middleware/disable_paths.rb

@@ -0,0 +1,13 @@
+class DisablePaths
+  def initialize(app, paths: [])
+    @app = app
+    @paths = {}
+
+    paths.each { |p| @paths[p] = true }
+  end
+
+  def call(env)
+    return [404, {}, []] if @paths[env["PATH_INFO"]]
+    @app.call(env)
+  end
+end

data/apps/rails-api/.dockerignore

@@ -0,0 +1,41 @@
+# See https://docs.docker.com/engine/reference/builder/#dockerignore-file for more about ignoring files.
+
+# Ignore git directory.
+/.git/
+/.gitignore
+
+# Ignore bundler config.
+/.bundle
+
+# Ignore all environment files.
+/.env*
+
+# Ignore all default key files.
+/config/master.key
+/config/credentials/*.key
+
+# Ignore all logfiles and tempfiles.
+/log/*
+/tmp/*
+!/log/.keep
+!/tmp/.keep
+
+# Ignore pidfiles, but keep the directory.
+/tmp/pids/*
+!/tmp/pids/.keep
+
+# Ignore storage (uploaded files in development and any SQLite databases).
+/storage/*
+!/storage/.keep
+/tmp/storage/*
+!/tmp/storage/.keep
+
+# Ignore CI service files.
+/.github
+
+# Ignore development files
+/.devcontainer
+
+# Ignore Docker-related files
+/.dockerignore
+/Dockerfile*

data/apps/rails-api/.gitattributes

@@ -0,0 +1,9 @@
+# See https://git-scm.com/docs/gitattributes for more about git attribute files.
+
+# Mark the database schema as having been generated.
+db/schema.rb linguist-generated
+
+# Mark any vendored files as having been vendored.
+vendor/* linguist-vendored
+config/credentials/*.yml.enc diff=rails_credentials
+config/credentials.yml.enc diff=rails_credentials

data/apps/rails-api/.gitignore

@@ -0,0 +1,32 @@
+# See https://help.github.com/articles/ignoring-files for more about ignoring files.
+#
+# Temporary files generated by your text editor or operating system
+# belong in git's global ignore instead:
+# `$XDG_CONFIG_HOME/git/ignore` or `~/.config/git/ignore`
+
+# Ignore bundler config.
+/.bundle
+
+# Ignore all environment files.
+/.env*
+
+# Ignore all logfiles and tempfiles.
+/log/*
+/tmp/*
+!/log/.keep
+!/tmp/.keep
+
+# Ignore pidfiles, but keep the directory.
+/tmp/pids/*
+!/tmp/pids/
+!/tmp/pids/.keep
+
+# Ignore storage (uploaded files in development and any SQLite databases).
+/storage/*
+!/storage/.keep
+/tmp/storage/*
+!/tmp/storage/
+!/tmp/storage/.keep
+
+# Ignore master key for decrypting credentials and more.
+/config/master.key

data/apps/rails-api/.kamal/hooks/docker-setup.sample

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+echo "Docker set up on $KAMAL_HOSTS..."

data/apps/rails-api/.kamal/hooks/post-deploy.sample

@@ -0,0 +1,14 @@
+#!/bin/sh
+
+# A sample post-deploy hook
+#
+# These environment variables are available:
+# KAMAL_RECORDED_AT
+# KAMAL_PERFORMER
+# KAMAL_VERSION
+# KAMAL_HOSTS
+# KAMAL_ROLE (if set)
+# KAMAL_DESTINATION (if set)
+# KAMAL_RUNTIME
+
+echo "$KAMAL_PERFORMER deployed $KAMAL_VERSION to $KAMAL_DESTINATION in $KAMAL_RUNTIME seconds"

data/apps/rails-api/.kamal/hooks/post-proxy-reboot.sample

@@ -0,0 +1,3 @@
+#!/bin/sh
+
+echo "Rebooted kamal-proxy on $KAMAL_HOSTS"

data/apps/rails-api/.kamal/hooks/pre-build.sample

@@ -0,0 +1,51 @@
+#!/bin/sh
+
+# A sample pre-build hook
+#
+# Checks:
+# 1. We have a clean checkout
+# 2. A remote is configured
+# 3. The branch has been pushed to the remote
+# 4. The version we are deploying matches the remote
+#
+# These environment variables are available:
+# KAMAL_RECORDED_AT
+# KAMAL_PERFORMER
+# KAMAL_VERSION
+# KAMAL_HOSTS
+# KAMAL_ROLE (if set)
+# KAMAL_DESTINATION (if set)
+
+if [ -n "$(git status --porcelain)" ]; then
+  echo "Git checkout is not clean, aborting..." >&2
+  git status --porcelain >&2
+  exit 1
+fi
+
+first_remote=$(git remote)
+
+if [ -z "$first_remote" ]; then
+  echo "No git remote set, aborting..." >&2
+  exit 1
+fi
+
+current_branch=$(git branch --show-current)
+
+if [ -z "$current_branch" ]; then
+  echo "Not on a git branch, aborting..." >&2
+  exit 1
+fi
+
+remote_head=$(git ls-remote $first_remote --tags $current_branch | cut -f1)
+
+if [ -z "$remote_head" ]; then
+  echo "Branch not pushed to remote, aborting..." >&2
+  exit 1
+fi
+
+if [ "$KAMAL_VERSION" != "$remote_head" ]; then
+  echo "Version ($KAMAL_VERSION) does not match remote HEAD ($remote_head), aborting..." >&2
+  exit 1
+fi
+
+exit 0

data/apps/rails-api/.kamal/hooks/pre-connect.sample

@@ -0,0 +1,47 @@
+#!/usr/bin/env ruby
+
+# A sample pre-connect check
+#
+# Warms DNS before connecting to hosts in parallel
+#
+# These environment variables are available:
+# KAMAL_RECORDED_AT
+# KAMAL_PERFORMER
+# KAMAL_VERSION
+# KAMAL_HOSTS
+# KAMAL_ROLE (if set)
+# KAMAL_DESTINATION (if set)
+# KAMAL_RUNTIME
+
+hosts = ENV["KAMAL_HOSTS"].split(",")
+results = nil
+max = 3
+
+elapsed = Benchmark.realtime do
+  results = hosts.map do |host|
+    Thread.new do
+      tries = 1
+
+      begin
+        Socket.getaddrinfo(host, 0, Socket::AF_UNSPEC, Socket::SOCK_STREAM, nil, Socket::AI_CANONNAME)
+      rescue SocketError
+        if tries < max
+          puts "Retrying DNS warmup: #{host}"
+          tries += 1
+          sleep rand
+          retry
+        else
+          puts "DNS warmup failed: #{host}"
+          host
+        end
+      end
+
+      tries
+    end
+  end.map(&:value)
+end
+
+retries = results.sum - hosts.size
+nopes = results.count { |r| r == max }
+
+puts "Prewarmed %d DNS lookups in %.2f sec: %d retries, %d failures" % [ hosts.size, elapsed, retries, nopes ]