masks 0.6.0 → 0.8.0

data/lib/masks/client.rb

@@ -19,33 +19,79 @@ require_relative "client/claims"
 require_relative "client/introspection"
 require_relative "client/session"
 require_relative "client/verifier"
+require_relative "client/logout"
 require_relative "client/resource"
 require_relative "client/rack"
 require_relative "client/registration"
 require_relative "client/handshake"
+require_relative "client/delegations"
 
 module Masks
+  # = Masks::Client
+  #
+  # The protocol half of the gem: plain Ruby, no \Rails, no database. Every
+  # entry point here is a class method that builds one of the objects below.
+  #
+  # Which one you want depends on what the application is doing:
+  #
+  # [issuer]    an app signing people in — discovery, PKCE, the code exchange
+  # [verifier]  an API checking a bearer it was handed
+  # [resource]  an API publishing what it is and which scopes it takes
+  # [handshake] an app registering itself, once, without a copied secret
+  #
+  # Everything reachable from here talks HTTP to a masks issuer and holds no
+  # state of its own beyond the discovery cache in ::registry.
   module Client
     class << self
+      # The process-wide cache of resolved issuers, so discovery is fetched
+      # once rather than per request.
+      #
+      # @return [Masks::Client::Registry]
       def registry
         @registry ||= Registry.new
       end
 
+      # Resolves +url+ through its discovery document and returns the issuer
+      # it describes. Cached in ::registry, so calling this per request is
+      # cheap after the first.
+      #
+      #   issuer = Masks::Client.issuer("https://auth.example")
+      #   issuer.authorization_url(client_id: id, redirect_uri: uri)
+      #
+      # @return [Masks::Client::Issuer]
       def issuer(url, **options)
         Issuer.resolve(url, **options)
       end
 
+      # Checks tokens minted by the issuer at +url+ against +audience+ — the
+      # API's own URL, which the token names in +aud+. A token issued for
+      # anything else is refused rather than merely noted.
+      #
+      # @return [Masks::Client::Verifier]
       def verifier(url, audience:, **options)
         Verifier.new(issuer(url), audience: audience, **options)
       end
 
+      # Describes this API to callers: the scopes it accepts and the issuer
+      # that may mint tokens for it, served as RFC 9728 metadata.
+      #
+      # @return [Masks::Client::Resource]
       def resource(url, issuer:, **options)
         Resource.new(issuer: issuer, url: url, **options)
       end
 
+      # Registers this application against a masks issuer. A person approves
+      # it in their browser and the credentials come back server to server, so
+      # no secret is pasted between the two.
+      #
+      # @return [Masks::Client::Handshake]
       def handshake(url, **options)
         Handshake.new(url, **options)
       end
+
+      def delegations(issuer, **options)
+        Delegations.new(issuer: issuer, **options)
+      end
     end
   end
 end

data/lib/masks/rails/authentication.rb

@@ -7,7 +7,15 @@ module Masks
       included do
         if respond_to?(:helper_method)
           helper_method :masks_signed_in?, :masks_identity, :masks_tenant, :masks_scopes,
-                        :masks_claims
+                        :masks_claims, :masks_organization, :masks_organizations, :masks_role?,
+                        :masks_login_url
+        end
+      end
+
+      class_methods do
+        def masks_members_only!(role: nil, organization: nil, **options)
+          before_action(-> { authorize_masks_member!(*Array(role), organization: organization) },
+                        **options.slice(:only, :except))
         end
       end
 
@@ -43,6 +51,7 @@ module Masks
         session[masks_config.session_key] = held.compact
         @masks_tokens = tokens
         @masks_identity = held["identity"]
+        @masks_claims = nil
       end
 
       def masks_held
@@ -51,7 +60,8 @@ module Masks
 
       IDENTITY = [
         "sub", "name", "preferred_username", "email", "email_verified", "tenant",
-        "picture", Masks::Client::Claims::AVATARS
+        "picture", Masks::Client::Claims::AVATARS, Masks::Client::Claims::ORGANIZATION,
+        Masks::Client::Claims::ORGANIZATIONS
       ].freeze
 
       def masks_identity_from(tokens)
@@ -64,6 +74,7 @@ module Masks
         session.delete(masks_config.session_key)
         @masks_tokens = nil
         @masks_identity = nil
+        @masks_claims = nil
       end
 
       def masks_signed_in?
@@ -122,6 +133,20 @@ module Masks
         @masks_claims ||= Masks::Client::Claims.new(masks_identity || {})
       end
 
+      def masks_organization
+        held = masks_claims.organization
+
+        held.present? ? held : nil
+      end
+
+      def masks_organizations
+        masks_claims.organizations
+      end
+
+      def masks_role?(*roles)
+        masks_organization&.role?(*roles) || false
+      end
+
       def masks_scopes
         masks_tokens&.scopes || []
       end
@@ -138,12 +163,12 @@ module Masks
         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)
-          )
+        refreshed = masks_session.refresh(
+          masks_tokens.refresh_token,
+          resource: masks_config.resource_for(request)
         )
+
+        masks_store(refreshed, identity: masks_refreshed_identity(refreshed))
         true
       rescue Masks::Client::Unregistered
         masks_disconnect!
@@ -153,6 +178,16 @@ module Masks
         false
       end
 
+      def masks_refreshed_identity(tokens)
+        held = masks_held["identity"]
+
+        return nil unless held.is_a?(Hash)
+
+        profile = masks_session.profile(tokens)
+
+        profile.empty? ? nil : held.merge(profile.slice(*IDENTITY))
+      end
+
       def masks_logout_url(return_to: nil)
         return nil unless masks_configured?
 
@@ -168,11 +203,14 @@ module Masks
         "#{request.base_url}#{masks_local_path(masks_config.after_sign_out) || '/'}"
       end
 
-      def masks_login_url(return_to: nil)
+      def masks_login_url(return_to: nil, organization: nil)
         path = Masks::Rails::Engine.routes.url_helpers.start_path
-        target = masks_local_path(return_to)
+        query = {
+          "return_to" => masks_local_path(return_to),
+          "organization" => Masks::Client::Session.organization_key(organization)
+        }.compact
 
-        target ? "#{path}?return_to=#{CGI.escape(target)}" : path
+        query.empty? ? path : "#{path}?#{URI.encode_www_form(query)}"
       end
 
       def masks_account
@@ -188,11 +226,20 @@ module Masks
           "picture" => masks_claims.picture,
           "avatars" => masks_claims.avatars.to_h.presence,
           "tenant" => masks_tenant,
+          "organization" => masks_organization&.to_h,
+          "organizations" => masks_organizations.map(&:to_h).presence,
           "scopes" => masks_scopes,
-          "expires_at" => masks_tokens&.expires_at
+          "expires_at" => masks_tokens&.expires_at,
+          "account_url" => masks_account_url
         }.compact
       end
 
+      def masks_account_url
+        "#{masks_config.issuer_for(request).to_s.chomp('/')}/"
+      rescue Masks::Rails::Configuration::Unconfigured
+        nil
+      end
+
       def authenticate_masks!
         return true if masks_configured? && (masks_signed_in? || (masks_tokens && masks_refresh!))
 
@@ -200,8 +247,28 @@ module Masks
         false
       end
 
+      def authorize_masks_member!(*roles, organization: nil)
+        return false unless authenticate_masks!
+
+        masks_claims.member!(*roles, organization: organization)
+        true
+      rescue Masks::Client::Forbidden => e
+        masks_forbid(e)
+        false
+      end
+
       private
 
+        def masks_forbid(error)
+          response.headers["Cache-Control"] = "no-store"
+
+          if masks_wants_json?
+            render json: { "error" => error.code, "error_description" => error.description }, status: :forbidden
+          else
+            render plain: error.description, status: :forbidden
+          end
+        end
+
         def masks_refuse
           return masks_refuse_json if masks_wants_json?
           return redirect_to(masks_handshake_path) unless masks_configured?

data/lib/masks/rails/configuration.rb

@@ -5,8 +5,9 @@ module Masks
 
       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
-      attr_writer :issuer, :redirect_uri, :name, :credentials, :store, :forget
+                    :credentials_path, :authenticate_everything, :delegates
+      attr_writer :issuer, :redirect_uri, :name, :credentials, :store, :forget, :logged_out,
+                  :delegation_redirect_uri, :organization
 
       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,10 +41,20 @@ 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
 
+      def organization_for(request)
+        resolve(@organization, request)
+      end
+
       def credentials_for(request)
         held = @credentials ? resolve(@credentials, request) : default_credentials.read
         held ||= {}
@@ -66,8 +74,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 +106,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,22 +149,21 @@ 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: approved_scope
+          scope: approved_scope,
+          backchannel_logout_uri: backchannel_logout_uri_for(request)
         )
       end
 
-      # What the handshake asks to be approved for, which is not what a sign-in
-      # requests. An app that owns a namespace asks for the namespace once, so
-      # that adding a capability later is a deployment rather than an approval
-      # round; the authorize request still names the scopes it actually wants.
       def approved_scope
-        return scope if namespace.blank?
+        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 ]
+        outside + [ namespace ] + delegated
       end
 
       def return_to_for(request)

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/protected_resource.rb

@@ -18,15 +18,16 @@ module Masks
         @masks_claims if defined?(@masks_claims)
       end
 
-      def masks_authenticate!(scope: nil, **)
-        @masks_claims = masks_resource.authenticate(request.authorization, scope: scope)
+      def masks_authenticate!(scope: nil, role: nil, organization: nil, **)
+        @masks_claims = masks_resource.authenticate(request.authorization, scope: scope, role: role,
+                                                                           organization: organization)
       rescue Masks::Client::Challenge => e
         masks_challenge(e)
         false
       end
 
-      def masks_authenticate(scope: nil)
-        masks_resource.authenticate(request.authorization, scope: scope)
+      def masks_authenticate(scope: nil, role: nil, organization: nil)
+        masks_resource.authenticate(request.authorization, scope: scope, role: role, organization: organization)
       rescue Masks::Client::Unauthenticated
         nil
       end

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. The provider is the masks-server gem, whether
+  # it runs elsewhere or is mounted on a subdomain of this app.
+  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.6.0".freeze
+  VERSION = "0.8.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 the masks-server gem, which runs
+# as an app of its own or mounted inside another Rails app.
+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.6.0
+  version: 0.8.0
 platform: ruby
 authors:
-- geiger
+- the masks authors
 bindir: bin
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
@@ -25,7 +25,8 @@ dependencies:
         version: '3.1'
 description: Discovery, PKCE authorization, token exchange, and token verification
   against a masks issuer, with Rack middleware for a resource server and a Rails engine
-  that mounts the consumer half of the code flow. The auth server itself stays standalone.
+  that mounts the consumer half of the code flow. The auth server itself is the masks-server
+  gem.
 executables: []
 extensions: []
 extra_rdoc_files: []
@@ -36,6 +37,7 @@ files:
 - 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
@@ -46,11 +48,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