zevauth 0.1.0

data/lib/zevauth/client.rb

@@ -0,0 +1,149 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module ZevAuth
+  # The ZevAuth backend API, called with your secret key.
+  #
+  #   client = ZevAuth::Client.new(secret_key: ENV.fetch("ZEVAUTH_SECRET_KEY"))
+  #   client.users.get("user_123")
+  #   client.users.each { |user| ... }          # every page, followed for you
+  #
+  # Server-side only. A secret key in a browser is a key anyone can read.
+  class Client
+    RETRYABLE = [429, 502, 503, 504].freeze
+    DEFAULT_CODES = {
+      400 => "invalid_request", 401 => "unauthorized", 403 => "forbidden", 404 => "not_found",
+      409 => "conflict", 429 => "rate_limited"
+    }.freeze
+
+    attr_reader :users, :organizations
+
+    # secret_key:  sk_test_… or sk_live_…
+    # api_url:     default https://api.zevauth.net
+    # timeout:     seconds per attempt, default 15
+    # max_retries: default 2
+    # transport:   see Transport; injectable for tests
+    # sleeper:     -> (seconds) {}; injectable so tests do not wait
+    def initialize(secret_key: nil, api_url: nil, timeout: 15, max_retries: 2, transport: nil, sleeper: nil)
+      secret_key ||= ZevAuth.config.secret_key
+      if secret_key.nil? || secret_key.to_s.empty?
+        raise ConfigurationError.new("The ZevAuth client needs your secret key (sk_test_… or sk_live_…).", code: "missing_secret_key")
+      end
+      if secret_key.start_with?("pk_")
+        raise ConfigurationError.new(
+          "That is a publishable key. The backend API takes your secret key (sk_…), which must never reach a browser.",
+          code: "wrong_key_type"
+        )
+      end
+
+      @secret_key = secret_key
+      @api_url = (api_url || ZevAuth.config.api_url || ZevAuth::DEFAULT_API_URL).chomp("/")
+      @timeout = timeout
+      @max_retries = max_retries
+      @transport = transport || Transport.new
+      @sleeper = sleeper || ->(seconds) { sleep(seconds) }
+      @users = Resources::Users.new(self)
+      @organizations = Resources::Organizations.new(self)
+    end
+
+    def get(path, query = nil) = request(:get, path, query: query)
+    def post(path, body = nil) = request(:post, path, body: body)
+    def patch(path, body = nil) = request(:patch, path, body: body)
+    def delete(path, query = nil) = request(:delete, path, query: query)
+
+    # Retries only what certainly did not run: 429, 502, 503, 504 and
+    # network failures. Never a 500: the server ran and failed, possibly
+    # after writing, and retrying is how one create becomes two.
+    def request(method, path, query: nil, body: nil)
+      url = "#{@api_url}#{path}#{query_string(query)}"
+      payload = body.nil? ? nil : JSON.generate(body)
+      attempt = 0
+      wait = nil
+
+      loop do
+        @sleeper.call(wait || backoff(attempt)) if attempt.positive?
+        wait = nil
+
+        begin
+          response = @transport.call(method: method, url: url, headers: headers, body: payload, timeout: @timeout)
+        rescue Transport::Failure => e
+          raise APIError.new("Could not reach ZevAuth: #{e.message}", code: "network_error", status: 0) if attempt >= @max_retries
+
+          attempt += 1
+          next
+        end
+
+        return parse_success(response) if response.status < 400
+
+        error = Client.error_from(response)
+        raise error unless RETRYABLE.include?(response.status) && attempt < @max_retries
+
+        wait = Client.retry_after(response.header("retry-after"))
+        attempt += 1
+      end
+    end
+
+    # Turns an error response into an APIError. Public so the conformance
+    # fixtures can check it directly.
+    def self.error_from(response)
+      parsed = begin
+        JSON.parse(response.body.to_s)
+      rescue JSON::ParserError
+        nil
+      end
+      envelope = parsed.is_a?(Hash) ? parsed["error"] : nil
+      code = envelope.is_a?(Hash) ? envelope["code"] : nil
+      message = (envelope.is_a?(Hash) && envelope["message"]) || "ZevAuth returned #{response.status}."
+      APIError.new(message, code: code || "request_failed", status: response.status, request_id: response.header("x-request-id"))
+    end
+
+    # Seconds from a Retry-After header, capped at 10, or nil.
+    def self.retry_after(value)
+      return nil if value.nil?
+
+      seconds = Float(value, exception: false)
+      return nil unless seconds && seconds >= 0
+
+      [seconds, 10].min
+    end
+
+    def self.retryable?(status) = RETRYABLE.include?(status)
+
+    private
+
+    def headers
+      {
+        "authorization" => "Bearer #{@secret_key}",
+        "content-type" => "application/json",
+        "accept" => "application/json",
+        "user-agent" => "zevauth-ruby/#{ZevAuth::VERSION}"
+      }
+    end
+
+    # 200 ms, 400 ms, 800 ms … capped at 4 s.
+    def backoff(attempt)
+      [0.2 * (2**(attempt - 1)), 4.0].min
+    end
+
+    def parse_success(response)
+      return nil if response.status == 204 || response.body.to_s.empty?
+
+      JSON.parse(response.body)
+    end
+
+    def query_string(query)
+      return "" if query.nil?
+
+      pairs = query.compact.flat_map do |key, value|
+        if value.is_a?(Hash)
+          value.map { |k, v| ["#{key}[#{k}]", v.to_s] }
+        else
+          [[key.to_s, value.to_s]]
+        end
+      end
+      pairs.empty? ? "" : "?#{URI.encode_www_form(pairs)}"
+    end
+  end
+end

data/lib/zevauth/errors.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module ZevAuth
+  # Base class for everything this gem raises.
+  class Error < StandardError
+    # A stable, machine-readable reason, the same string in every ZevAuth
+    # SDK (see the server SDK contract). Match on this, not the message.
+    attr_reader :code
+
+    def initialize(message = nil, code: nil)
+      super(message)
+      @code = code
+    end
+  end
+
+  # Something about the setup, not the request: no environment id, a
+  # publishable key where a secret key belongs. Raised loudly on purpose,
+  # because getting it wrong is a deploy bug, not a signed-out visitor.
+  class ConfigurationError < Error; end
+
+  # A session token was refused. `code` is one of VerifyError::CODES.
+  class VerifyError < Error
+    CODES = %w[
+      malformed_token
+      unsupported_algorithm
+      unknown_key
+      invalid_signature
+      invalid_issuer
+      invalid_audience
+      token_expired
+      token_not_yet_valid
+      jwks_unavailable
+    ].freeze
+  end
+
+  # A request refused by `require_auth`: not signed in, a pending task,
+  # or two-step verification required. Carries the HTTP status and the
+  # error envelope the framework integrations turn into a response.
+  class AuthRefused < Error
+    attr_reader :status, :pending_tasks
+
+    def initialize(message, code:, status:, pending_tasks: nil)
+      super(message, code: code)
+      @status = status
+      @pending_tasks = pending_tasks
+    end
+
+    # `{ "error": { "code": …, "message": … } }`, the envelope the ZevAuth
+    # API itself uses, plus `pendingTasks` for a pending-task refusal.
+    def body
+      error = { "code" => code, "message" => message }
+      body = { "error" => error }
+      body["pendingTasks"] = pending_tasks if pending_tasks
+      body
+    end
+
+    def to_rack
+      [status, { "content-type" => "application/json", "cache-control" => "no-store" }, [JSON.generate(body)]]
+    end
+  end
+
+  # The backend API answered with an error, or could not be reached.
+  class APIError < Error
+    # HTTP status, or 0 when the request never got an answer.
+    attr_reader :status
+    # The `x-request-id` the API sent, for support conversations.
+    attr_reader :request_id
+
+    def initialize(message, code:, status:, request_id: nil)
+      super(message, code: code)
+      @status = status
+      @request_id = request_id
+    end
+  end
+
+  # A webhook delivery whose signature did not check out. `code` is one of
+  # `webhook_malformed_signature`, `webhook_timestamp_out_of_range`,
+  # `webhook_signature_mismatch`.
+  class WebhookError < Error; end
+end

data/lib/zevauth/key_set.rb

@@ -0,0 +1,139 @@
+# frozen_string_literal: true
+
+require "json"
+require "jwt"
+
+module ZevAuth
+  # The environment's signing keys, by `kid`.
+  #
+  # Two kinds: a local set handed in (tests, air-gapped servers), or a
+  # remote one found through the discovery document and cached.
+  class KeySet
+    def self.local(jwks)
+      LocalKeySet.new(jwks)
+    end
+
+    # JWK hash -> OpenSSL public key. Only RSA signing keys are kept; a key
+    # set that also publishes something else must not make RS256 tokens
+    # verifiable with it.
+    def self.public_keys_from(jwks)
+      jwks = JSON.parse(jwks) if jwks.is_a?(String)
+      keys = jwks.fetch("keys") { jwks.fetch(:keys, []) }
+      keys.each_with_object({}) do |jwk, out|
+        jwk = jwk.transform_keys(&:to_s)
+        next unless jwk["kty"] == "RSA" && jwk["kid"]
+        next if jwk["use"] && jwk["use"] != "sig"
+
+        imported = JWT::JWK.import(jwk)
+        out[jwk["kid"]] = imported.respond_to?(:verify_key) ? imported.verify_key : imported.public_key
+      end
+    end
+  end
+
+  class LocalKeySet
+    def initialize(jwks)
+      @keys = KeySet.public_keys_from(jwks)
+    end
+
+    def find(kid)
+      @keys[kid]
+    end
+  end
+
+  # Discovery once per process, then the key set cached for at most ten
+  # minutes. A token whose `kid` is not in the cache forces one refetch,
+  # at most once per cooldown (30 seconds by default), so a token with a
+  # made-up `kid` cannot turn every request into a fetch.
+  class RemoteKeySet
+    CACHE_SECONDS = 600
+
+    attr_reader :issuer
+
+    def initialize(api_url:, environment_id:, transport:, clock:, cooldown_seconds: 30, timeout: 15)
+      @api_url = api_url.chomp("/")
+      @environment_id = environment_id
+      @transport = transport
+      @clock = clock
+      @cooldown = cooldown_seconds
+      @timeout = timeout
+      @lock = Mutex.new
+      @keys = nil
+      @fetched_at = nil
+      @last_forced_at = nil
+    end
+
+    # The issuer is read from discovery, never built from the API URL:
+    # self-hosted and local setups are allowed to have them differ.
+    def discovered_issuer
+      discover
+      @issuer
+    end
+
+    def find(kid)
+      # One lock around fetching means concurrent first requests share a
+      # single fetch: the second waits, then finds the cache filled.
+      @lock.synchronize do
+        refresh if @keys.nil? || stale?
+        return @keys[kid] if @keys.key?(kid)
+        return nil if cooling_down?
+
+        @last_forced_at = now
+        refresh
+        @keys[kid]
+      end
+    end
+
+    private
+
+    def now
+      @clock.call.to_f
+    end
+
+    def stale?
+      now - @fetched_at > CACHE_SECONDS
+    end
+
+    def cooling_down?
+      @last_forced_at && now - @last_forced_at < @cooldown
+    end
+
+    def discover
+      return if @jwks_uri
+
+      @lock.synchronize { discover_unlocked }
+    end
+
+    def refresh
+      discover_unlocked
+      @keys = KeySet.public_keys_from(get_json(@jwks_uri, "key set"))
+      @fetched_at = now
+    end
+
+    # Callers hold the lock (Mutex is not re-entrant). Both values are
+    # assigned only after the document is read, so a failed fetch is not
+    # cached and the next request tries again.
+    def discover_unlocked
+      return if @jwks_uri
+
+      document = get_json("#{@api_url}/v1/#{@environment_id}/.well-known/openid-configuration", "discovery document")
+      issuer = document.fetch("issuer")
+      jwks_uri = document.fetch("jwks_uri")
+      @issuer = issuer
+      @jwks_uri = jwks_uri
+    end
+
+    def get_json(url, what)
+      response = @transport.call(method: :get, url: url, headers: { "accept" => "application/json" }, timeout: @timeout)
+      unless response.status == 200
+        raise VerifyError.new(
+          "Could not read the ZevAuth #{what} for #{@environment_id} (#{response.status}). " \
+          "Check the environment id and api_url.",
+          code: "jwks_unavailable"
+        )
+      end
+      JSON.parse(response.body)
+    rescue Transport::Failure, JSON::ParserError, KeyError => e
+      raise VerifyError.new("Could not read the ZevAuth #{what}: #{e.message}", code: "jwks_unavailable")
+    end
+  end
+end

data/lib/zevauth/rack/middleware.rb

@@ -0,0 +1,90 @@
+# frozen_string_literal: true
+
+module ZevAuth
+  module Rack
+    # Puts who is signed in on every request, at `env["zevauth.auth"]`.
+    #
+    #   use ZevAuth::Rack::Middleware
+    #
+    # It also serves the session bridge (POST /zevauth/session) and the
+    # handshake page (GET /zevauth/handshake), and sends a page request
+    # through the handshake when the session cookie lapsed. So a Sinatra,
+    # Roda or Hanami app gets server-rendered sessions from this one line.
+    # It never refuses a request; protect routes with RequireAuth or
+    # `ZevAuth::Rack.refusal`.
+    class Middleware
+      ENV_KEY = "zevauth.auth"
+
+      # handshake:     send lapsed-cookie page requests through the handshake
+      # serve_bridge:  answer the bridge and handshake paths itself
+      # bridge_path:   default ZevAuth.config.bridge_path (/zevauth/session)
+      def initialize(app, authenticator: nil, handshake: true, serve_bridge: true, bridge_path: nil, handshake_page: nil)
+        @app = app
+        @authenticator = authenticator
+        @handshake = handshake
+        @serve_bridge = serve_bridge
+        @bridge_path = bridge_path
+        @handshake_page = handshake_page
+      end
+
+      def call(env)
+        authenticator = @authenticator || ZevAuth.authenticator
+
+        if @serve_bridge
+          path = env["PATH_INFO"]
+          return Bridge::Endpoint.new(authenticator).call(env) if path == bridge_path
+          return handshake_page.call(env) if path == authenticator.bridge.handshake_path && env["REQUEST_METHOD"] == "GET"
+        end
+
+        auth, handshake = @handshake ? authenticator.authenticate_request(env) : [authenticator.get_auth(env), nil]
+        return handshake if handshake
+
+        env[ENV_KEY] = auth
+        @app.call(env)
+      end
+
+      private
+
+      def bridge_path
+        @bridge_path || ZevAuth.config.bridge_path
+      end
+
+      def handshake_page
+        @handshake_page ||= Bridge::HandshakePage.new(bridge_path: bridge_path)
+      end
+    end
+
+    # Refuses requests that do not pass `require_auth`, with the shared
+    # JSON envelope (401 / 403). Put it in front of what it protects:
+    #
+    #   map "/api" do
+    #     use ZevAuth::Rack::RequireAuth, require_mfa: true
+    #     run Api
+    #   end
+    class RequireAuth
+      def initialize(app, allow_pending_tasks: false, require_mfa: false, authenticator: nil)
+        @app = app
+        @options = { allow_pending_tasks: allow_pending_tasks, require_mfa: require_mfa }
+        @authenticator = authenticator
+      end
+
+      def call(env)
+        refused = Rack.refusal(env, authenticator: @authenticator, **@options)
+        refused || @app.call(env)
+      end
+    end
+
+    # nil when the request passes, else the Rack response to send:
+    #
+    #   refused = ZevAuth::Rack.refusal(env, require_mfa: true)
+    #   halt(*refused) if refused        # Sinatra
+    def self.refusal(env, allow_pending_tasks: false, require_mfa: false, authenticator: nil)
+      auth = env[Middleware::ENV_KEY] || (authenticator || ZevAuth.authenticator).get_auth(env)
+      env[Middleware::ENV_KEY] ||= auth
+      ZevAuth.check!(auth, allow_pending_tasks: allow_pending_tasks, require_mfa: require_mfa)
+      nil
+    rescue AuthRefused => e
+      e.to_rack
+    end
+  end
+end

data/lib/zevauth/rails/config/routes.rb

@@ -0,0 +1,11 @@
+# frozen_string_literal: true
+
+# Mounted with `mount ZevAuth::Engine => "/zevauth"`, these become
+# POST /zevauth/session (the bridge) and GET /zevauth/handshake.
+ZevAuth::Engine.routes.draw do
+  # Rack apps, not controllers: they behave the same under Rails as under
+  # plain Rack, and need nothing from ActionController.
+  post "session", to: ZevAuth::Bridge::Endpoint.new
+  match "session", to: ZevAuth::Bridge::Endpoint.new, via: %i[get put patch delete]
+  get "handshake", to: ->(env) { ZevAuth::Rails.handshake_page.call(env) }
+end

data/lib/zevauth/rails/controller.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+require "active_support/concern"
+
+module ZevAuth
+  module Rails
+    # Included into every controller by the engine.
+    #
+    #   before_action :require_zevauth!                       # signed in
+    #   require_zevauth only: :destroy, require_mfa: true     # with options
+    #
+    #   zevauth_auth.user_id
+    #   zevauth_auth.has?(permission: "org:members:manage")
+    #
+    # Views get `zevauth_auth`, `zevauth_signed_in?` and `zevauth_user_id`.
+    module Controller
+      extend ActiveSupport::Concern
+
+      included do
+        helper_method :zevauth_auth, :zevauth_signed_in?, :zevauth_user_id if respond_to?(:helper_method)
+        rescue_from ZevAuth::AuthRefused, with: :zevauth_refused
+      end
+
+      class_methods do
+        # `before_action` with options:
+        #   require_zevauth except: :index, require_mfa: true
+        def require_zevauth(require_mfa: false, allow_pending_tasks: false, **filter_options)
+          before_action(**filter_options) do
+            require_zevauth!(require_mfa: require_mfa, allow_pending_tasks: allow_pending_tasks)
+          end
+        end
+      end
+
+      # Who is signed in on this request. Never raises.
+      def zevauth_auth
+        @zevauth_auth ||= request.env[ZevAuth::Rack::Middleware::ENV_KEY] || ZevAuth.get_auth(request)
+      end
+
+      def zevauth_signed_in?
+        zevauth_auth.signed_in?
+      end
+
+      def zevauth_user_id
+        zevauth_auth.user_id
+      end
+
+      # Refuses the request unless it passes (401 not signed in, 403 a
+      # pending task, 403 two-step required). A page whose session cookie
+      # lapsed goes through the handshake first, so the browser can refresh
+      # it and come straight back.
+      def require_zevauth!(require_mfa: false, allow_pending_tasks: false)
+        auth, handshake = ZevAuth.authenticate_request(request)
+        if handshake
+          status, headers, = handshake
+          return redirect_to(headers["location"], status: status) if status == 302
+
+          return render(json: JSON.parse(handshake[2].join), status: status)
+        end
+
+        @zevauth_auth = auth
+        ZevAuth.check!(auth, require_mfa: require_mfa, allow_pending_tasks: allow_pending_tasks)
+      end
+
+      # The verified event from a webhook delivery. Reads the raw body:
+      # never verify `params`, which is parsed and re-encoded.
+      #
+      #   def create
+      #     event = zevauth_webhook_event
+      #     ...
+      #   rescue ZevAuth::WebhookError
+      #     head :bad_request
+      #   end
+      def zevauth_webhook_event(secret: nil, tolerance_seconds: ZevAuth::Webhooks::DEFAULT_TOLERANCE)
+        ZevAuth::Webhooks.construct_event(
+          payload: request.raw_post,
+          signature: request.headers[ZevAuth::Webhooks::SIGNATURE_HEADER],
+          secret: secret,
+          tolerance_seconds: tolerance_seconds
+        )
+      end
+
+      private
+
+      def zevauth_refused(error)
+        render json: error.body, status: error.status
+      end
+    end
+  end
+end

data/lib/zevauth/rails/railtie.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require "rails/engine"
+require_relative "controller"
+
+module ZevAuth
+  # Rails integration. Loaded only when Rails is present; the gem itself
+  # never depends on Rails.
+  #
+  #   # config/routes.rb
+  #   mount ZevAuth::Engine => "/zevauth"     # bridge + handshake
+  #
+  #   class ApplicationController < ActionController::Base
+  #     before_action :require_zevauth!
+  #   end
+  class Engine < ::Rails::Engine
+    isolate_namespace ZevAuth
+    # The engine's routes live in rails/config/routes.rb next to this file,
+    # so Rails loads (and reloads) them like any engine's.
+    config.root = File.expand_path(__dir__)
+  end
+
+  # Every controller gets the helpers (`zevauth_auth`, `require_zevauth!`
+  # and friends). Nothing is enforced until a controller asks. Registered
+  # when this file loads rather than in an initializer, so a controller
+  # class loaded early (a gem's, or one defined during boot) has them too.
+  ActiveSupport.on_load(:action_controller_base) { include ZevAuth::Rails::Controller }
+  ActiveSupport.on_load(:action_controller_api) { include ZevAuth::Rails::Controller }
+
+  module Rails
+    # The handshake page posts to wherever the engine is mounted, so its
+    # bridge path follows `ZevAuth.config.bridge_path`.
+    def self.handshake_page
+      Bridge::HandshakePage.new(bridge_path: ZevAuth.config.bridge_path)
+    end
+  end
+end

data/lib/zevauth/rails.rb

@@ -0,0 +1,6 @@
+# frozen_string_literal: true
+
+# Explicit entry point for apps that load this gem before Rails:
+#   gem "zevauth", require: "zevauth/rails"
+require_relative "../zevauth"
+require_relative "rails/railtie"