masks 0.3.2 → 0.5.0

data/lib/masks/client.rb

@@ -0,0 +1,51 @@
+require "base64"
+require "json"
+require "jwt"
+require "net/http"
+require "openssl"
+require "securerandom"
+require "uri"
+
+require_relative "version"
+require_relative "client/errors"
+require_relative "client/http"
+require_relative "client/pkce"
+require_relative "client/stores"
+require_relative "client/tracker"
+require_relative "client/issuer"
+require_relative "client/registry"
+require_relative "client/tokens"
+require_relative "client/claims"
+require_relative "client/introspection"
+require_relative "client/session"
+require_relative "client/verifier"
+require_relative "client/resource"
+require_relative "client/rack"
+require_relative "client/registration"
+require_relative "client/handshake"
+
+module Masks
+  module Client
+    class << self
+      def registry
+        @registry ||= Registry.new
+      end
+
+      def issuer(url, **options)
+        Issuer.resolve(url, **options)
+      end
+
+      def verifier(url, audience:, **options)
+        Verifier.new(issuer(url), audience: audience, **options)
+      end
+
+      def resource(url, issuer:, **options)
+        Resource.new(issuer: issuer, url: url, **options)
+      end
+
+      def handshake(url, **options)
+        Handshake.new(url, **options)
+      end
+    end
+  end
+end

data/lib/masks/rails/authentication.rb

@@ -0,0 +1,217 @@
+module Masks
+  module Rails
+    module Authentication
+      extend ActiveSupport::Concern
+      include Masks::Rails::Configurable
+
+      included do
+        if respond_to?(:helper_method)
+          helper_method :masks_signed_in?, :masks_identity, :masks_tenant, :masks_scopes
+        end
+      end
+
+      REQUESTS = "masks_requests".freeze
+      HANDSHAKES = "masks_handshakes".freeze
+
+      def masks_session
+        @masks_session ||= masks_config.session_for(request)
+      end
+
+      def masks_requests
+        @masks_requests ||= masks_tracker(REQUESTS)
+      end
+
+      def masks_handshakes
+        @masks_handshakes ||= masks_tracker(HANDSHAKES)
+      end
+
+      def masks_tracker(key)
+        Masks::Client::Tracker.new(Masks::Client::Stores::Session.new(session, key))
+      end
+
+      def masks_tokens
+        return @masks_tokens if defined?(@masks_tokens)
+
+        @masks_tokens = Masks::Client::Tokens.from_h(session[masks_config.session_key])
+      end
+
+      def masks_store(tokens, identity: nil)
+        held = tokens.to_h.except("id_token")
+        held["identity"] = identity&.slice(*IDENTITY) || masks_held["identity"]
+
+        session[masks_config.session_key] = held.compact
+        @masks_tokens = tokens
+        @masks_identity = held["identity"]
+      end
+
+      def masks_held
+        session[masks_config.session_key] || {}
+      end
+
+      IDENTITY = %w[sub name preferred_username email email_verified tenant].freeze
+
+      def masks_identity_from(tokens)
+        return nil if tokens.id_token.nil?
+
+        masks_session.identity(tokens)
+      end
+
+      def masks_forget
+        session.delete(masks_config.session_key)
+        @masks_tokens = nil
+        @masks_identity = nil
+      end
+
+      def masks_signed_in?
+        masks_tokens.present? && !masks_tokens.expired?
+      end
+
+      def masks_configured?
+        masks_config.configured?(request)
+      end
+
+      def masks_handshake_path
+        Masks::Rails::Engine.routes.url_helpers.handshake_path
+      end
+
+      def masks_identity
+        return @masks_identity if defined?(@masks_identity)
+
+        @masks_identity = masks_held["identity"]
+      end
+
+      def masks_tenant
+        masks_identity&.dig("tenant")
+      end
+
+      def masks_scopes
+        masks_tokens&.scopes || []
+      end
+
+      def masks_permits?(scope)
+        masks_scopes.include?(scope.to_s)
+      end
+
+      def masks_access_token
+        masks_tokens&.access_token
+      end
+
+      def masks_refresh!
+        return false unless masks_configured?
+        return false if masks_tokens&.refresh_token.nil?
+
+        masks_store(
+          masks_session.refresh(
+            masks_tokens.refresh_token,
+            resource: masks_config.resource_for(request)
+          )
+        )
+        true
+      rescue Masks::Client::Rejected
+        masks_forget
+        false
+      end
+
+      def masks_logout_url(return_to: nil)
+        return nil unless masks_configured?
+
+        masks_session.end_session_url(
+          post_logout_redirect_uri: masks_post_logout_redirect_uri,
+          state: SecureRandom.urlsafe_base64(16)
+        )
+      rescue Masks::Client::Error
+        nil
+      end
+
+      def masks_post_logout_redirect_uri
+        "#{request.base_url}#{masks_local_path(masks_config.after_sign_out) || '/'}"
+      end
+
+      def masks_login_url(return_to: nil)
+        path = Masks::Rails::Engine.routes.url_helpers.start_path
+        target = masks_local_path(return_to)
+
+        target ? "#{path}?return_to=#{CGI.escape(target)}" : path
+      end
+
+      def masks_account
+        identity = masks_identity || {}
+
+        {
+          "signed_in" => masks_signed_in?,
+          "subject" => identity["sub"],
+          "name" => identity["name"],
+          "nickname" => identity["preferred_username"],
+          "email" => identity["email"],
+          "email_verified" => identity["email_verified"],
+          "tenant" => masks_tenant,
+          "scopes" => masks_scopes,
+          "expires_at" => masks_tokens&.expires_at
+        }.compact
+      end
+
+      def authenticate_masks!
+        return true if masks_configured? && (masks_signed_in? || (masks_tokens && masks_refresh!))
+
+        masks_refuse
+        false
+      end
+
+      private
+
+        def masks_refuse
+          return masks_refuse_json if masks_wants_json?
+          return redirect_to(masks_handshake_path) unless masks_configured?
+
+          session[:masks_return_to] = request.fullpath if request.get?
+          redirect_to Masks::Rails::Engine.routes.url_helpers.start_path
+        end
+
+        def masks_refuse_json
+          response.headers["Cache-Control"] = "no-store"
+
+          render json: masks_refusal, status: :unauthorized
+        end
+
+        def masks_refusal
+          unless masks_configured?
+            return {
+              "signed_in" => false,
+              "error" => "handshake_required",
+              "handshake_url" => masks_handshake_path
+            }
+          end
+
+          {
+            "signed_in" => false,
+            "error" => "login_required",
+            "login_url" => masks_login_url(return_to: masks_referring_path)
+          }
+        end
+
+        def masks_wants_json?
+          request.xhr? ||
+            request.format.json? ||
+            request.content_mime_type&.symbol == :json ||
+            !request.format.html?
+        end
+
+        def masks_referring_path
+          return nil if request.referer.blank?
+
+          masks_local_path(URI.parse(request.referer).request_uri)
+        rescue URI::InvalidURIError
+          nil
+        end
+
+        def masks_local_path(value)
+          path = value.to_s
+
+          return nil unless path.start_with?("/")
+          return nil if path.start_with?("//", "/\\")
+
+          path
+        end
+    end
+  end
+end

data/lib/masks/rails/configurable.rb

@@ -0,0 +1,11 @@
+module Masks
+  module Rails
+    module Configurable
+      extend ActiveSupport::Concern
+
+      def masks_config
+        Masks::Rails.config
+      end
+    end
+  end
+end

data/lib/masks/rails/configuration.rb

@@ -0,0 +1,172 @@
+module Masks
+  module Rails
+    class Configuration
+      class Unconfigured < Masks::Client::Error; end
+
+      attr_accessor :scope, :resource, :resource_scopes, :after_sign_in, :after_sign_out,
+                    :session_key, :sign_out_of_issuer, :parent_controller,
+                    :credentials_path, :authenticate_everything
+      attr_writer :issuer, :redirect_uri, :name, :credentials, :store, :forget
+
+      def initialize
+        @scope = Masks::Client::Session::DEFAULT_SCOPE
+        @resource_scopes = []
+        @after_sign_in = "/"
+        @after_sign_out = "/"
+        @session_key = "masks"
+        @sign_out_of_issuer = false
+        @parent_controller = "ActionController::Base"
+        @authenticate_everything = false
+      end
+
+      # An app that has not said where to keep its credentials gets one file
+      # under the Rails root, so the handshake works before anybody writes a
+      # `store` lambda. `things` overrides both because it is multi-tenant,
+      # which is the interesting case rather than the common one.
+      def default_credentials
+        @default_credentials ||= Credentials.new(
+          credentials_path || ::Rails.root.join("config", "masks.json")
+        )
+      end
+
+      def name_for(request)
+        resolve(@name, request).presence || ::Rails.application.class.module_parent_name
+      end
+
+      def issuer_for(request)
+        resolve(@issuer, request) ||
+          raise(Unconfigured, "Masks::Rails.config.issuer is not set")
+      end
+
+      def redirect_uri_for(request)
+        resolve(@redirect_uri, request) ||
+          "#{request.base_url}#{routes.callback_path}"
+      end
+
+      def resource_for(request)
+        resolve(@resource, request)
+      end
+
+      def credentials_for(request)
+        held = @credentials ? resolve(@credentials, request) : default_credentials.read
+        held ||= {}
+
+        held.respond_to?(:to_h) ? held.to_h.transform_keys(&:to_s) : {}
+      end
+
+      def client_id_for(request)
+        credentials_for(request)["client_id"].presence
+      end
+
+      def client_secret_for(request)
+        credentials_for(request)["client_secret"].presence
+      end
+
+      def configured?(request)
+        client_id_for(request).present?
+      end
+
+      # An app that keeps its own credentials has to say how to drop them, and
+      # until it does the engine does not offer a button it cannot honour.
+      def can_forget?
+        @forget.respond_to?(:call) || !@store.respond_to?(:call)
+      end
+
+      def forget!(request)
+        return @forget.call(request) if @forget.respond_to?(:call)
+        raise Unconfigured, "Masks::Rails.config.forget is not set" if @store.respond_to?(:call)
+
+        default_credentials.clear!
+      end
+
+      def store!(request, registration)
+        return default_credentials.write(registration) unless @store.respond_to?(:call)
+
+        @store.call(request, registration)
+      end
+
+      # The engine depends on `handshake_endpoint` being in the discovery
+      # document, and on the approval flow behind it. An issuer that predates
+      # both should say so here rather than at the one screen that exists to
+      # be the first thing anybody touches.
+      MINIMUM_ISSUER = 1
+
+      def issuer_speaks!(request)
+        spoken = Masks::Client::Issuer.resolve(issuer_for(request))
+                                     .discovery["masks_protocol_version"].to_i
+
+        return true if spoken >= MINIMUM_ISSUER
+
+        raise Unconfigured,
+              "#{issuer_for(request)} speaks masks protocol #{spoken}, and masks " \
+              "#{Masks::VERSION} needs at least #{MINIMUM_ISSUER}"
+      end
+
+      def session_for(request)
+        raise Unconfigured, "this app has not shaken hands with #{issuer_for(request)}" unless configured?(request)
+
+        Masks::Client::Session.new(
+          issuer: issuer_for(request),
+          client_id: client_id_for(request),
+          client_secret: client_secret_for(request),
+          redirect_uri: redirect_uri_for(request),
+          scope: scope
+        )
+      end
+
+      def resource_server_for(request)
+        url = Array(resource_for(request)).first
+
+        raise Unconfigured, "Masks::Rails.config.resource is not set" if url.nil?
+
+        Masks::Client::Resource.new(
+          issuer: issuer_for(request),
+          url: url,
+          scopes: resource_scopes
+        )
+      end
+
+      def handshake_for(request)
+        Masks::Client::Handshake.new(
+          issuer_for(request),
+          name: name_for(request),
+          resource: Array(resource_for(request)).first ||
+            raise(Unconfigured, "Masks::Rails.config.resource is not set"),
+          redirect_uris: [ redirect_uri_for(request) ],
+          return_to: return_to_for(request),
+          scope: scope
+        )
+      end
+
+      def return_to_for(request)
+        uri = URI.parse(redirect_uri_for(request))
+        port = ":#{uri.port}" unless uri.port == uri.default_port
+
+        "#{uri.scheme}://#{uri.host}#{port}#{routes.handshake_callback_path}"
+      end
+
+      private
+
+        def routes
+          Masks::Rails::Engine.routes.url_helpers
+        end
+
+        def resolve(value, request)
+          return value unless value.respond_to?(:call)
+
+          value.arity.zero? ? value.call : value.call(request)
+        end
+    end
+
+    class << self
+      def config
+        @config ||= Configuration.new
+      end
+
+      def configure
+        yield config
+        config
+      end
+    end
+  end
+end

data/lib/masks/rails/credentials.rb

@@ -0,0 +1,60 @@
+module Masks
+  module Rails
+    # The default place a single-tenant app keeps what the handshake gives it,
+    # so `config.store` has something to be before a consumer writes one. An
+    # app with more than one issuer wants its own — `things` keeps these on
+    # `tenants`, because a handshake is per tenant there.
+    class Credentials
+      KEYS = %w[client_id client_secret registration_access_token registration_client_uri].freeze
+
+      attr_reader :path
+
+      def initialize(path)
+        @path = Pathname.new(path)
+        @lock = Mutex.new
+      end
+
+      def read
+        @lock.synchronize { held }
+      end
+
+      def write(registration)
+        @lock.synchronize do
+          @held = {
+            "client_id" => registration.client_id,
+            "client_secret" => registration.client_secret,
+            "registration_access_token" => registration.access_token,
+            "registration_client_uri" => registration.uri,
+            "connected_at" => Time.now.utc.iso8601
+          }.compact
+
+          path.dirname.mkpath
+          path.write(JSON.pretty_generate(@held))
+          path.chmod(0o600)
+          @held
+        end
+      end
+
+      def clear!
+        @lock.synchronize do
+          @held = nil
+          path.delete if path.exist?
+        end
+      end
+
+      def connected?
+        read["client_id"].present?
+      end
+
+      private
+
+        def held
+          return @held if defined?(@held) && @held
+
+          @held = path.exist? ? JSON.parse(path.read) : {}
+        rescue JSON::ParserError
+          @held = {}
+        end
+    end
+  end
+end

data/lib/masks/rails/engine.rb

@@ -0,0 +1,20 @@
+module Masks
+  module Rails
+    class Engine < ::Rails::Engine
+      isolate_namespace Masks::Rails
+
+      config.masks = Masks::Rails.config
+
+      # Opt-in, not blanket. This used to `include Masks::Rails::Authentication`
+      # into every controller in the host app, which lands twenty-five `masks_*`
+      # methods and four helper_methods on code the consumer owns, with no way
+      # to say no — and a name collision found that way is the kind of thing
+      # `grants:` versus `scope:` already cost this project once.
+      initializer "masks.authentication" do
+        ActiveSupport.on_load(:action_controller) do
+          include Masks::Rails::Authentication if Masks::Rails.config.authenticate_everything
+        end
+      end
+    end
+  end
+end

data/lib/masks/rails/protected_resource.rb

@@ -0,0 +1,51 @@
+module Masks
+  module Rails
+    module ProtectedResource
+      extend ActiveSupport::Concern
+      include Masks::Rails::Configurable
+
+      class_methods do
+        def masks_protect!(**options)
+          before_action(-> { masks_authenticate!(**options) }, **options.slice(:only, :except))
+        end
+      end
+
+      def masks_resource
+        @masks_resource ||= masks_config.resource_server_for(request)
+      end
+
+      def masks_claims
+        @masks_claims if defined?(@masks_claims)
+      end
+
+      def masks_authenticate!(scope: nil, **)
+        @masks_claims = masks_resource.authenticate(request.authorization, scope: scope)
+      rescue Masks::Client::Challenge => e
+        masks_challenge(e)
+        false
+      end
+
+      def masks_authenticate(scope: nil)
+        masks_resource.authenticate(request.authorization, scope: scope)
+      rescue Masks::Client::Unauthenticated
+        nil
+      end
+
+      def masks_challenge(error)
+        error = Masks::Client::Unauthorized.new(error.to_s) unless error.is_a?(Masks::Client::Challenge)
+
+        response.headers["WWW-Authenticate"] = masks_resource.challenge(error)
+        response.headers["Cache-Control"] = "no-store"
+
+        render json: {
+          "error" => error.code || "invalid_token",
+          "error_description" => error.description
+        }, status: error.status
+      end
+
+      def masks_resource_metadata
+        masks_resource.metadata
+      end
+    end
+  end
+end

data/lib/masks/rails.rb

@@ -0,0 +1,10 @@
+require "rails"
+
+require_relative "version"
+require_relative "client"
+require_relative "rails/credentials"
+require_relative "rails/configuration"
+require_relative "rails/configurable"
+require_relative "rails/authentication"
+require_relative "rails/protected_resource"
+require_relative "rails/engine"

data/lib/masks/version.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module Masks
-  VERSION = Gem::Version.new("0.3.2")
+  VERSION = "0.5.0".freeze
 end