masks 0.5.0 → 0.7.0

data/lib/masks/rails/authentication.rb

@@ -6,7 +6,8 @@ module Masks
 
       included do
         if respond_to?(:helper_method)
-          helper_method :masks_signed_in?, :masks_identity, :masks_tenant, :masks_scopes
+          helper_method :masks_signed_in?, :masks_identity, :masks_tenant, :masks_scopes,
+                        :masks_claims
         end
       end
 
@@ -48,7 +49,10 @@ module Masks
         session[masks_config.session_key] || {}
       end
 
-      IDENTITY = %w[sub name preferred_username email email_verified tenant].freeze
+      IDENTITY = [
+        "sub", "name", "preferred_username", "email", "email_verified", "tenant",
+        "picture", Masks::Client::Claims::AVATARS
+      ].freeze
 
       def masks_identity_from(tokens)
         return nil if tokens.id_token.nil?
@@ -70,6 +74,36 @@ module Masks
         masks_config.configured?(request)
       end
 
+      def masks_registration
+        Masks::Client::Registration.held(
+          masks_config.issuer_for(request),
+          masks_config.credentials_for(request)
+        )
+      end
+
+      def masks_registered?
+        held = masks_registration
+
+        held.nil? || held.known?
+      rescue Masks::Client::Error
+        true
+      end
+
+      def masks_disconnect!
+        return false unless masks_configured? && masks_config.can_forget?
+
+        masks_config.forget!(request)
+        masks_forget
+
+        true
+      end
+
+      def masks_reconnect!
+        return false if masks_registered?
+
+        masks_disconnect!
+      end
+
       def masks_handshake_path
         Masks::Rails::Engine.routes.url_helpers.handshake_path
       end
@@ -84,6 +118,10 @@ module Masks
         masks_identity&.dig("tenant")
       end
 
+      def masks_claims
+        @masks_claims ||= Masks::Client::Claims.new(masks_identity || {})
+      end
+
       def masks_scopes
         masks_tokens&.scopes || []
       end
@@ -107,6 +145,9 @@ module Masks
           )
         )
         true
+      rescue Masks::Client::Unregistered
+        masks_disconnect!
+        false
       rescue Masks::Client::Rejected
         masks_forget
         false
@@ -144,6 +185,8 @@ module Masks
           "nickname" => identity["preferred_username"],
           "email" => identity["email"],
           "email_verified" => identity["email_verified"],
+          "picture" => masks_claims.picture,
+          "avatars" => masks_claims.avatars.to_h.presence,
           "tenant" => masks_tenant,
           "scopes" => masks_scopes,
           "expires_at" => masks_tokens&.expires_at

data/lib/masks/rails/configuration.rb

@@ -3,10 +3,11 @@ module Masks
     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
+      attr_accessor :scope, :namespace, :resource, :resource_scopes, :after_sign_in,
+                    :after_sign_out, :session_key, :sign_out_of_issuer, :parent_controller,
+                    :credentials_path, :authenticate_everything, :delegates
+      attr_writer :issuer, :redirect_uri, :name, :credentials, :store, :forget, :logged_out,
+                  :delegation_redirect_uri
 
       def initialize
         @scope = Masks::Client::Session::DEFAULT_SCOPE
@@ -17,12 +18,9 @@ module Masks
         @sign_out_of_issuer = false
         @parent_controller = "ActionController::Base"
         @authenticate_everything = false
+        @delegates = 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")
@@ -43,6 +41,12 @@ module Masks
           "#{request.base_url}#{routes.callback_path}"
       end
 
+      def delegation_redirect_uri_for(request)
+        return nil unless delegates
+
+        resolve(@delegation_redirect_uri, request)
+      end
+
       def resource_for(request)
         resolve(@resource, request)
       end
@@ -66,8 +70,21 @@ module Masks
         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 backchannel_logout_uri_for(request)
+        return nil unless @logged_out.respond_to?(:call)
+        return nil unless Masks::Client::Issuer.resolve(issuer_for(request)).backchannel_logout?
+
+        "#{request.base_url}#{routes.backchannel_logout_path}"
+      end
+
+      def logged_out!(request, logout)
+        return false unless @logged_out.respond_to?(:call)
+
+        @logged_out.arity == 1 ? @logged_out.call(logout) : @logged_out.call(request, logout)
+
+        true
+      end
+
       def can_forget?
         @forget.respond_to?(:call) || !@store.respond_to?(:call)
       end
@@ -85,10 +102,6 @@ module Masks
         @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)
@@ -132,12 +145,23 @@ module Masks
           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) ],
+          redirect_uris: [ redirect_uri_for(request), delegation_redirect_uri_for(request) ].compact.uniq,
           return_to: return_to_for(request),
-          scope: scope
+          scope: approved_scope,
+          backchannel_logout_uri: backchannel_logout_uri_for(request)
         )
       end
 
+      def approved_scope
+        delegated = delegates ? [ Masks::Client::Delegations::SCOPE ] : []
+
+        return Array(scope) + delegated if namespace.blank?
+
+        outside = Array(scope).reject { |name| name.to_s.start_with?(namespace) }
+
+        outside + [ namespace ] + delegated
+      end
+
       def return_to_for(request)
         uri = URI.parse(redirect_uri_for(request))
         port = ":#{uri.port}" unless uri.port == uri.default_port

data/lib/masks/rails/credentials.rb

@@ -1,9 +1,5 @@
 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
 

data/lib/masks/rails/engine.rb

@@ -5,11 +5,6 @@ module Masks
 
       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

data/lib/masks/rails.rb

@@ -1,5 +1,31 @@
 require "rails"
 
+module Masks
+  # = Masks::Rails
+  #
+  # The consumer half: a \Rails engine that mounts the code flow into an
+  # application, so signing in against a masks issuer is configuration rather
+  # than a controller you write.
+  #
+  # It loads only when +Rails::Engine+ is already defined. Requiring the gem
+  # from a plain Ruby process gets Masks::Client and nothing else.
+  #
+  # Three pieces do the work:
+  #
+  # [Configuration]    the issuer, credentials and routes, set once in an
+  #                    initializer and validated on boot rather than on the
+  #                    first request that needs them
+  # [Authentication]   +masks_login_url+, the callback, and the session the
+  #                    app reads +current_actor+ from
+  # [ProtectedResource] the other direction — checking a bearer this app was
+  #                    handed, for an API rather than a browser
+  #
+  # This engine is the client. It never runs in the same process as the
+  # provider, which is a standalone deployable holding its own database.
+  module Rails
+  end
+end
+
 require_relative "version"
 require_relative "client"
 require_relative "rails/credentials"

data/lib/masks/version.rb

@@ -1,3 +1,3 @@
 module Masks
-  VERSION = "0.5.0".freeze
+  VERSION = "0.7.0".freeze
 end

data/lib/masks.rb

@@ -1,3 +1,20 @@
+# = \Masks
+#
+# Signs an application in against a masks issuer.
+#
+# The gem is two halves. Masks::Client is plain Ruby and speaks the protocol —
+# discovery, PKCE, the code exchange, token verification. Masks::Rails mounts
+# that flow into a \Rails app, and loads only when +Rails::Engine+ is already
+# defined, so requiring this gem outside \Rails costs nothing.
+#
+#   issuer = Masks::Client.issuer("https://auth.example")
+#   issuer.authorization_url(client_id: id, redirect_uri: uri)
+#
+# The provider itself is not in here. It is a deployable that holds a database
+# and the per-tenant signing keys, and it stays standalone.
+module Masks
+end
+
 require_relative "masks/version"
 require_relative "masks/client"
 

metadata

@@ -1,10 +1,10 @@
 --- !ruby/object:Gem::Specification
 name: masks
 version: !ruby/object:Gem::Version
-  version: 0.5.0
+  version: 0.7.0
 platform: ruby
 authors:
-- geiger
+- the masks authors
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
@@ -33,8 +33,10 @@ files:
 - CHANGELOG.md
 - LICENSE
 - README.md
+- app/controllers/masks/rails/avatars_controller.rb
 - app/controllers/masks/rails/base_controller.rb
 - app/controllers/masks/rails/handshakes_controller.rb
+- app/controllers/masks/rails/logouts_controller.rb
 - app/controllers/masks/rails/sessions_controller.rb
 - app/views/layouts/masks/rails/plain.html.erb
 - app/views/masks/rails/handshakes/refused.html.erb
@@ -45,11 +47,14 @@ files:
 - lib/masks.rb
 - lib/masks/client.rb
 - lib/masks/client/claims.rb
+- lib/masks/client/delegations.rb
+- lib/masks/client/delegations/fake.rb
 - lib/masks/client/errors.rb
 - lib/masks/client/handshake.rb
 - lib/masks/client/http.rb
 - lib/masks/client/introspection.rb
 - lib/masks/client/issuer.rb
+- lib/masks/client/logout.rb
 - lib/masks/client/pkce.rb
 - lib/masks/client/rack.rb
 - lib/masks/client/registration.rb