zevauth 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c1c4f39c408d4398f5f65cd0a1d1b23e56f959dee0c25e8e82889ca80cb967f4
+  data.tar.gz: 97dc9e1a1614a986a40489838bfbb1b145a848c1ec9d8301abc40e7b1d371905
+SHA512:
+  metadata.gz: 5ac39af131e5d96b2074ccec8a57241fe25b3b497c86a43c41891f8b6a91de1c9d61079090dc5972ebc7a8c51e7d951eb9ebad525889f5599613d5dff2555c94
+  data.tar.gz: f28f89f5a54a8a11d6c28af5d8a08942d2155ec8fd929bb1942829c011a9c26664690d716957fc17b16442a6b041f4c02f9d5ffa8c914fe5b1acf36c5e48ae2f

data/CHANGELOG.md

@@ -0,0 +1,20 @@
+# Changelog
+
+## 0.1.0 (unreleased)
+
+First release.
+
+- Session verification: RS256 only, issuer from discovery, audience
+  enforced, 5 s clock skew, keys cached 10 minutes with an unknown-kid
+  refetch at most every 30 s. Passes every shared conformance fixture.
+- `ZevAuth.get_auth` / `ZevAuth.require_auth`, with `has?`,
+  `mfa_verified?` and pending tasks.
+- Backend API client: users and organizations, cursor iteration with
+  `each`, retries on 429/502/503/504 and network failures (never on 500),
+  `Retry-After`, `request_id`.
+- Webhook verification over the raw body, in constant time.
+- Session bridge endpoint and handshake page, as Rack apps.
+- Rack middleware (`ZevAuth::Rack::Middleware`, `ZevAuth::Rack::RequireAuth`).
+- Rails engine: `mount ZevAuth::Engine`, `require_zevauth!`,
+  `require_zevauth only: …, require_mfa: true`, view helpers,
+  `zevauth_webhook_event`.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ZevOp Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,135 @@
+# ZevAuth for Ruby
+
+Verify ZevAuth sessions, call the ZevAuth backend API and check webhook
+signatures from Rails, Rack apps (Sinatra, Roda, Hanami) or plain Ruby.
+
+```ruby
+gem "zevauth"
+```
+
+Ruby 3.1 or later. One runtime dependency (`jwt`, to read published keys);
+Rack and Rails are used when your app has them and never required.
+
+## Configure
+
+```ruby
+ZevAuth.configure do |c|
+  c.environment_id  = ENV.fetch("ZEVAUTH_ENVIRONMENT_ID")   # env_live_…
+  c.secret_key      = ENV.fetch("ZEVAUTH_SECRET_KEY")       # sk_live_…, backend API only
+  c.publishable_key = ENV.fetch("ZEVAUTH_PUBLISHABLE_KEY")  # pk_live_…, for the handshake page
+  c.webhook_secret  = ENV.fetch("ZEVAUTH_WEBHOOK_SECRET")   # whsec_…
+end
+```
+
+## Who is signed in
+
+```ruby
+auth = ZevAuth.get_auth(request)   # never raises for a missing or bad token
+auth.signed_in?
+auth.user_id                       # "user_…"
+auth.organization_id
+auth.has?(permission: "org:members:manage")
+auth.mfa_verified?
+```
+
+`require_auth` refuses instead, with the same responses in every ZevAuth SDK:
+401 `unauthorized`, 403 `session_task_pending`, 403 `mfa_required`.
+
+```ruby
+ZevAuth.require_auth(request, require_mfa: true)   # raises ZevAuth::AuthRefused
+```
+
+Tokens are checked locally against your environment's published keys (RS256
+only, keys cached and rotated for you), so this costs no network call per
+request.
+
+## Rails
+
+```ruby
+# config/routes.rb
+mount ZevAuth::Engine => "/zevauth"
+
+# app/controllers/application_controller.rb
+class ApplicationController < ActionController::Base
+  before_action :require_zevauth!
+end
+
+class BillingController < ApplicationController
+  require_zevauth only: :update, require_mfa: true
+end
+```
+
+Views get `zevauth_signed_in?`, `zevauth_user_id` and `zevauth_auth`.
+
+## Rack
+
+```ruby
+use ZevAuth::Rack::Middleware        # env["zevauth.auth"] on every request
+
+map "/api" do
+  use ZevAuth::Rack::RequireAuth      # 401 / 403 with the JSON envelope
+  run Api
+end
+```
+
+## Backend API
+
+```ruby
+client = ZevAuth.client
+client.users.get("user_123")
+client.users.each(metadata: { plan: "pro" }) { |user| puts user["email"] }
+client.organizations.add_member("org_123", user_id: "user_123", role: "org:admin")
+```
+
+Errors are `ZevAuth::APIError` with `code`, `status` and `request_id`.
+Rate limits and brief outages are retried for you; a 500 never is, so a
+create cannot run twice.
+
+## Webhooks
+
+Verify the raw body, never parsed params:
+
+```ruby
+event = ZevAuth::Webhooks.construct_event(
+  payload: request.raw_post,
+  signature: request.headers["zevauth-signature"]
+)
+```
+
+In a Rails controller, `zevauth_webhook_event` does the same.
+
+## Server-rendered pages
+
+With the session bridge, the browser SDK hands each new access token to your
+server, which keeps it in its own HttpOnly cookie, so a page knows who is
+signed in before it renders. Mount the engine (Rails) or the middleware
+(Rack), and set `sessionBridge: { url: "/zevauth/session" }` in the browser
+SDK. Your server never refreshes a token; the browser does.
+
+## Documentation
+
+- Ruby: <https://docs.zevauth.com/sdk/ruby>
+- Rails: <https://docs.zevauth.com/sdk/rails>
+- The contract every ZevAuth server SDK follows:
+  <https://github.com/zevop/zevauth-sdk/tree/main/spec>
+
+## Development
+
+```sh
+bundle install
+bundle exec rake test       # includes the shared conformance fixtures
+bundle exec rubocop
+```
+
+`test/fixtures` is a copy of the shared conformance fixtures from
+[zevauth-sdk](https://github.com/zevop/zevauth-sdk/tree/main/spec/fixtures).
+Never edit it by hand: change the fixture in zevauth-sdk, then run
+`script/sync-fixtures` here.
+
+## Support
+
+Questions and bug reports: open an issue here, or contact ZevAuth support.
+
+## License
+
+[MIT](LICENSE). Copyright (c) 2026 ZevOp Inc.

data/lib/zevauth/auth.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module ZevAuth
+  # Who is signed in on this request, or that nobody is.
+  #
+  # A signed-out Auth is a real object with the same methods, not nil, so a
+  # view can ask `auth.signed_in?` without guarding against nil first.
+  class Auth
+    attr_reader :user_id, :session_id, :organization_id, :organization_role, :claims, :pending_tasks
+
+    def self.signed_out(needs_handshake: false)
+      new(nil, needs_handshake: needs_handshake)
+    end
+
+    def self.from_claims(claims)
+      new(claims)
+    end
+
+    def initialize(claims, needs_handshake: false)
+      @claims = claims&.freeze
+      @user_id = claims && claims["sub"]
+      @session_id = claims && claims["sid"]
+      @organization_id = claims && claims["org_id"]
+      @organization_role = claims && claims["org_role"]
+      # Absent means empty, never nil: code written before a claim existed
+      # keeps working when it starts appearing.
+      @pending_tasks = Array(claims && claims["pending_tasks"]).freeze
+      @permissions = Array(claims && claims["org_permissions"]).freeze
+      @mfa = Array(claims && claims["amr"]).include?("mfa")
+      @needs_handshake = needs_handshake
+    end
+
+    def signed_in?
+      !@claims.nil?
+    end
+
+    # The session passed a second factor at sign-in (`amr` contains `mfa`).
+    def mfa_verified?
+      @mfa
+    end
+
+    # True when the session cookie lapsed but the browser still holds a
+    # session: a page request should go through the handshake so the
+    # browser can refresh it. See ZevAuth::Bridge.
+    def needs_handshake?
+      @needs_handshake
+    end
+
+    # Role and permission checks against the active organization.
+    #
+    #   auth.has?(permission: "org:members:manage")
+    #   auth.has?(role: "org:admin")
+    #
+    # False with no active organization, and false when neither is given:
+    # an empty check granting access would be a bug waiting to be written.
+    def has?(role: nil, permission: nil)
+      return false unless @organization_id
+      return false if role.nil? && permission.nil?
+      return false if role && @organization_role != role
+      return false if permission && !@permissions.include?(permission)
+
+      true
+    end
+
+    def to_h
+      {
+        signed_in: signed_in?,
+        user_id: user_id,
+        session_id: session_id,
+        organization_id: organization_id,
+        organization_role: organization_role,
+        pending_tasks: pending_tasks,
+        mfa_verified: mfa_verified?
+      }
+    end
+  end
+end

data/lib/zevauth/authenticator.rb

@@ -0,0 +1,133 @@
+# frozen_string_literal: true
+
+require "uri"
+
+module ZevAuth
+  # Reads and checks the session on a request: the `Authorization` header
+  # first, then the session-bridge cookie for server-rendered pages.
+  #
+  # Works with a Rack env Hash, a Rack::Request or an ActionDispatch::Request.
+  class Authenticator
+    HANDSHAKE_MARKER = "__zevauth_handshake"
+
+    attr_reader :verifier, :bridge
+
+    def initialize(verifier, bridge: Bridge::Config.new)
+      @verifier = verifier
+      @bridge = bridge
+    end
+
+    # Who is signed in. Never raises for a missing, expired or bad token:
+    # each of those means "nobody", and a page deciding what to render must
+    # not crash because a session lapsed.
+    def get_auth(request)
+      env = ZevAuth.env_of(request)
+      header = ZevAuth.bearer_from(env["HTTP_AUTHORIZATION"])
+      cookies = ZevAuth.parse_cookies(env["HTTP_COOKIE"])
+      names = @bridge.cookie_names
+      token = header || present(cookies[names[:session]])
+      has_client = cookies[names[:client]] == "1"
+
+      return Auth.signed_out(needs_handshake: header.nil? && has_client) unless token
+
+      Auth.from_claims(@verifier.verify(token))
+    rescue VerifyError => e
+      Auth.signed_out(needs_handshake: header.nil? && (e.code == "token_expired" || has_client))
+    end
+
+    # The same, but refuses with AuthRefused: 401 `unauthorized`, 403
+    # `session_task_pending`, then 403 `mfa_required`, in that order.
+    #
+    # allow_pending_tasks: serve a session that still has a task to finish
+    #                      (only for the routes that help finish it)
+    # require_mfa:         refuse unless the session passed a second factor
+    def require_auth(request, allow_pending_tasks: false, require_mfa: false)
+      auth = request.is_a?(Auth) ? request : get_auth(request)
+      ZevAuth.check!(auth, allow_pending_tasks: allow_pending_tasks, require_mfa: require_mfa)
+      auth
+    end
+
+    # For server-rendered pages: the auth, plus a Rack response to send
+    # instead when the session cookie lapsed and the browser should refresh
+    # it first. `handshake` is nil when the page can render as it is.
+    def authenticate_request(request)
+      env = ZevAuth.env_of(request)
+      auth = get_auth(env)
+      return [auth, nil] unless auth.needs_handshake?
+
+      query = env["QUERY_STRING"].to_s
+      # Back from a handshake already: render signed out rather than loop.
+      return [auth, nil] if URI.decode_www_form(query).any? { |key, _| key == HANDSHAKE_MARKER }
+
+      method = env["REQUEST_METHOD"]
+      navigation = %w[GET HEAD].include?(method) && env["HTTP_ACCEPT"].to_s.include?("text/html")
+      unless navigation
+        body = {
+          "error" => {
+            "code" => "session_refresh_required",
+            "message" => "The session cookie expired. Send the SDK token in Authorization, or reload the page."
+          }
+        }
+        return [auth, [401, { "content-type" => "application/json", "cache-control" => "no-store" }, [JSON.generate(body)]]]
+      end
+
+      path = env["SCRIPT_NAME"].to_s + env["PATH_INFO"].to_s
+      target = path + (query.empty? ? "" : "?#{query}")
+      location = "#{@bridge.handshake_path}?#{URI.encode_www_form('redirect_url' => target)}"
+      [auth, [302, { "location" => location, "cache-control" => "no-store" }, []]]
+    end
+
+    private
+
+    def present(value)
+      value.nil? || value.empty? ? nil : value
+    end
+  end
+
+  class << self
+    # Raises AuthRefused unless the auth passes; see Authenticator#require_auth.
+    def check!(auth, allow_pending_tasks: false, require_mfa: false)
+      raise AuthRefused.new("Sign in to continue.", code: "unauthorized", status: 401) unless auth.signed_in?
+
+      if !allow_pending_tasks && !auth.pending_tasks.empty?
+        raise AuthRefused.new(
+          "Finish setting up your account to continue.",
+          code: "session_task_pending", status: 403, pending_tasks: auth.pending_tasks
+        )
+      end
+
+      return unless require_mfa && !auth.mfa_verified?
+
+      raise AuthRefused.new("Two-step verification is required for this.", code: "mfa_required", status: 403)
+    end
+
+    # `Authorization: Bearer <token>` -> the token, or nil. The scheme is
+    # case-sensitive, whitespace is trimmed, and an API key in the header
+    # (`pk_…`, `sk_…`) is not a session, so it reads as none.
+    def bearer_from(header)
+      return nil unless header.is_a?(String) && header.start_with?("Bearer ")
+
+      token = header.delete_prefix("Bearer ").strip
+      return nil if token.empty? || token.start_with?("pk_", "sk_")
+
+      token
+    end
+
+    # The Rack env behind whatever request object a framework hands us.
+    def env_of(request)
+      return request if request.is_a?(Hash)
+      return request.env if request.respond_to?(:env)
+
+      raise ArgumentError, "Expected a Rack env or a request object, got #{request.class}."
+    end
+
+    def parse_cookies(header)
+      header.to_s.split(";").each_with_object({}) do |part, out|
+        at = part.index("=")
+        next unless at&.positive?
+
+        out[part[0...at].strip] = part[(at + 1)..].strip
+      end
+    end
+  end
+end

data/lib/zevauth/bridge.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "json"
+require "uri"
+
+module ZevAuth
+  # The session bridge, for server-rendered apps.
+  #
+  # The browser SDK keeps the session (and its refresh token) and posts
+  # each new access token to an endpoint on your own site, which stores it
+  # in your own HttpOnly cookie. Your pages then read who is signed in from
+  # that cookie, before they render.
+  #
+  # Your server never refreshes a token. Refresh tokens rotate on every use
+  # and a refresh token used twice ends the whole session, so a server
+  # refreshing alongside the browser would sign the person out. Only the
+  # browser refreshes; when the cookie lapses, the handshake page lets it
+  # do so and sends the visitor straight back.
+  module Bridge
+    HEADER = "HTTP_X_ZEVAUTH_BRIDGE"
+    CLIENT_COOKIE_SECONDS = 30 * 24 * 60 * 60
+    DEFAULT_UI_SCRIPT = "https://cdn.jsdelivr.net/npm/@zevauth/ui@0/dist/zevauth-ui.global.js"
+
+    # allowed_origins: origins allowed to post sessions; default the
+    #                  request's own origin
+    # cookie_domain:   share the cookies with subdomains (`.example.com`)
+    # secure:          false only for plain-http local development
+    # handshake_path:  where the handshake page is served
+    Config = Struct.new(:allowed_origins, :cookie_domain, :secure, :handshake_path, keyword_init: true) do
+      def initialize(allowed_origins: nil, cookie_domain: nil, secure: true, handshake_path: "/zevauth/handshake")
+        super
+      end
+
+      # `__Host-` cookies by default: no Domain, Secure, Path=/, so nothing
+      # on another subdomain can set or read them. `__Secure-` when shared
+      # across subdomains, and no prefix for plain-http development.
+      def cookie_names
+        prefix = if secure == false then ""
+                 elsif cookie_domain then "__Secure-"
+                 else "__Host-"
+                 end
+        { session: "#{prefix}zevauth_session", client: "#{prefix}zevauth_client" }
+      end
+    end
+
+    # POST {token} -> sets or clears the cookies. Mount it at the URL you
+    # give the browser SDK as `sessionBridge: { url }`.
+    class Endpoint
+      def initialize(authenticator = nil)
+        @authenticator = authenticator
+      end
+
+      def call(env)
+        authenticator = @authenticator || ZevAuth.authenticator
+        config = authenticator.bridge
+
+        return error(405, "method_not_allowed", "The session bridge accepts POST only.", { "allow" => "POST" }) unless env["REQUEST_METHOD"] == "POST"
+
+        unless env[HEADER] == "1"
+          return error(403, "bridge_header_missing", "Send the x-zevauth-bridge: 1 header. The ZevAuth browser SDK does this for you.")
+        end
+
+        # With the header, this stops login CSRF: a page elsewhere posting
+        # its own valid token to sign the visitor in as someone else.
+        origin = env["HTTP_ORIGIN"]
+        allowed = config.allowed_origins || [own_origin(env)]
+        if origin && !allowed.include?(origin)
+          return error(403, "bridge_origin_not_allowed", "#{origin} may not post sessions here. Add it to allowed_origins.")
+        end
+
+        body = read_json(env)
+        return error(400, "invalid_request", 'Expected a JSON body: { "token": string | null }.') unless body.is_a?(Hash)
+
+        names = config.cookie_names
+        token = body["token"]
+        cleared = [Bridge.cookie(names[:session], "", 0, config), Bridge.cookie(names[:client], "", 0, config)]
+        return empty(204, cleared) if token.nil? || token == ""
+        return error(400, "invalid_request", "`token` must be a string or null.") unless token.is_a?(String)
+
+        begin
+          claims = authenticator.verifier.verify(token)
+        rescue VerifyError => e
+          return error(401, "unauthorized", "That session token was refused.", {}, cleared, reason: e.code)
+        end
+
+        max_age = [claims["exp"].to_i - authenticator.verifier.now_seconds.floor, 0].max
+        empty(204, [
+                Bridge.cookie(names[:session], token, max_age, config),
+                Bridge.cookie(names[:client], "1", CLIENT_COOKIE_SECONDS, config)
+              ])
+      end
+
+      private
+
+      def own_origin(env)
+        scheme = first_value(env["HTTP_X_FORWARDED_PROTO"]) || env["rack.url_scheme"] || "http"
+        host = first_value(env["HTTP_X_FORWARDED_HOST"]) || env["HTTP_HOST"] || env["SERVER_NAME"]
+        "#{scheme}://#{host}"
+      end
+
+      # Proxies append to these headers; the first value is the client's.
+      def first_value(header)
+        header.nil? ? nil : header.split(",").first&.strip
+      end
+
+      def read_json(env)
+        input = env["rack.input"]
+        raw = input ? input.read.to_s : ""
+        input.rewind if input.respond_to?(:rewind)
+        JSON.parse(raw)
+      rescue JSON::ParserError
+        nil
+      end
+
+      def error(status, code, message, headers = {}, cookies = [], reason: nil)
+        error = { "code" => code, "message" => message }
+        error["reason"] = reason if reason
+        response(status, JSON.generate("error" => error), { "content-type" => "application/json" }.merge(headers), cookies)
+      end
+
+      def empty(status, cookies)
+        response(status, nil, {}, cookies)
+      end
+
+      def response(status, body, headers, cookies)
+        headers = { "cache-control" => "no-store" }.merge(headers)
+        headers["set-cookie"] = Bridge.set_cookie_value(cookies) unless cookies.empty?
+        [status, headers, body ? [body] : []]
+      end
+    end
+
+    # GET {redirect_url} -> a tiny page that lets the browser SDK refresh the
+    # session, post it to the bridge, and go back. Plain HTML and one script
+    # tag, so it works with any framework or none.
+    class HandshakePage
+      def initialize(publishable_key: nil, bridge_path: "/zevauth/session", api_url: nil, ui_script_url: nil)
+        @publishable_key = publishable_key
+        @bridge_path = bridge_path
+        @api_url = api_url
+        @ui_script_url = ui_script_url || DEFAULT_UI_SCRIPT
+      end
+
+      def call(env)
+        publishable_key = @publishable_key || ZevAuth.config.publishable_key
+        raise ConfigurationError.new("The handshake page needs your publishable key (pk_…).", code: "missing_publishable_key") unless publishable_key
+
+        requested = URI.decode_www_form(env["QUERY_STRING"].to_s).to_h["redirect_url"] || "/"
+        # Same-site paths only: anything else is an open redirect.
+        safe = requested.match?(%r{\A/(?![/\\])}) ? requested : "/"
+        back = "#{safe}#{safe.include?('?') ? '&' : '?'}#{Authenticator::HANDSHAKE_MARKER}=1"
+
+        config = JSON.generate(
+          "publishableKey" => publishable_key,
+          "apiUrl" => @api_url || ZevAuth.config.frontend_api_url,
+          "bridge" => @bridge_path,
+          "back" => back
+        ).gsub("<", "\\u003c")
+
+        html = <<~HTML
+          <!doctype html><meta charset="utf-8"><meta name="robots" content="noindex"><title>Signing in…</title>
+          <script src="#{escape_attribute(@ui_script_url)}"></script>
+          <script>
+          (async function () {
+            var c = #{config};
+            try {
+              window.ZevAuthUI.init({ publishableKey: c.publishableKey, apiUrl: c.apiUrl || undefined, sessionBridge: { url: c.bridge } });
+              var client = window.ZevAuthUI.getClient();
+              await client.load();
+              await client.syncSessionBridge();
+            } catch (e) {}
+            location.replace(c.back);
+          })();
+          </script>
+        HTML
+
+        [200, { "content-type" => "text/html; charset=utf-8", "cache-control" => "no-store", "referrer-policy" => "same-origin" }, [html]]
+      end
+
+      private
+
+      def escape_attribute(value)
+        value.gsub(/[&"<>]/, "&" => "&amp;", '"' => "&quot;", "<" => "&lt;", ">" => "&gt;")
+      end
+    end
+
+    # Rack 3 takes several Set-Cookie values as an Array; Rack 2 as one
+    # newline-joined String (and Rack 3's linter refuses newlines).
+    def self.set_cookie_value(cookies)
+      rack3 = defined?(::Rack::RELEASE) && Gem::Version.new(::Rack::RELEASE) >= Gem::Version.new("3")
+      rack3 || !defined?(::Rack::RELEASE) ? cookies : cookies.join("\n")
+    end
+
+    def self.cookie(name, value, max_age, config)
+      parts = ["#{name}=#{value}", "Path=/", "Max-Age=#{max_age}", "HttpOnly", "SameSite=Lax"]
+      parts << "Secure" unless config.secure == false
+      parts << "Domain=#{config.cookie_domain}" if config.cookie_domain
+      parts.join("; ")
+    end
+  end
+end