masks 0.6.0 → 0.8.0

data/lib/masks/client/delegations/fake.rb

@@ -0,0 +1,91 @@
+require "masks/client"
+
+module Masks
+  module Client
+    class Delegations
+      class Fake
+        Connected = Struct.new(:connection, :provider, :subject, :secret, :refused, :unavailable, keyword_init: true)
+
+        attr_reader :releases, :redirect_uri
+
+        def initialize(redirect_uri: "https://app.test/connect/callback", lifetime: 3600)
+          @redirect_uri = redirect_uri
+          @lifetime = lifetime
+          @codes = {}
+          @connections = {}
+          @releases = 0
+          @lock = Mutex.new
+        end
+
+        def start(provider:, prompt: nil, max_age: nil, state: SecureRandom.urlsafe_base64(24))
+          query = URI.encode_www_form({ "provider" => provider, "state" => state, "prompt" => prompt, "max_age" => max_age }.compact)
+
+          { "url" => "https://masks.fake/authorize?#{query}", "state" => state, "verifier" => SecureRandom.hex(16), "provider" => provider.to_s }
+        end
+
+        def approve(started, subject: "fake-subject", connection: SecureRandom.uuid)
+          code = SecureRandom.hex(12)
+
+          @lock.synchronize do
+            @codes[code] = { "provider" => started["provider"], "subject" => subject, "connection" => connection }
+          end
+
+          { "code" => code, "state" => started["state"] }
+        end
+
+        def deny(started, error: "access_denied", description: "the person declined")
+          { "error" => error, "error_description" => description, "state" => started["state"] }
+        end
+
+        def finish(params:, started:)
+          params = params.to_h.transform_keys(&:to_s)
+
+          raise Refused.new(params["error"], params["error_description"]) if params["error"].to_s != ""
+          raise Refused.new("invalid_state", "the state did not match the one this connection started with") unless params["state"] == started["state"]
+
+          granted = @lock.synchronize { @codes.delete(params["code"]) }
+
+          raise Refused.new("invalid_grant", "that code is not valid") if granted.nil?
+
+          secret = SecureRandom.hex(16)
+
+          @lock.synchronize do
+            @connections[granted["connection"]] = Connected.new(
+              connection: granted["connection"], provider: granted["provider"], subject: granted["subject"], secret: secret
+            )
+          end
+
+          Held.new(connection: granted["connection"], provider: granted["provider"], provider_name: granted["provider"].to_s.capitalize,
+                   label: nil, subject: granted["subject"], secret: secret)
+        end
+
+        def token(secret, connection:)
+          held = @lock.synchronize { @connections[connection.to_s] }
+
+          raise Refused.new("invalid_grant", "that connection is unknown") if held.nil?
+          raise Unavailable.new("masks is not answering", secret: secret) if held.unavailable
+          raise Refused.new("invalid_grant", held.refused, secret: secret) if held.refused
+          raise Refused.new("invalid_grant", "that refresh token is not valid or has expired") unless held.secret == secret.to_s
+
+          rotated = SecureRandom.hex(16)
+
+          @lock.synchronize do
+            held.secret = rotated
+            @releases += 1
+          end
+
+          Upstream.new(access_token: "#{held.provider}-access-#{@releases}", expires_at: Time.now.to_i + @lifetime,
+                       scope: "", secret: rotated)
+        end
+
+        def revoke(connection, reason: "the person stopped this application using that account")
+          @lock.synchronize { @connections.fetch(connection.to_s).refused = reason }
+        end
+
+        def unavailable(connection, now: true)
+          @lock.synchronize { @connections.fetch(connection.to_s).unavailable = now }
+        end
+      end
+    end
+  end
+end

data/lib/masks/client/delegations.rb

@@ -0,0 +1,117 @@
+module Masks
+  module Client
+    class Delegations
+      SCOPE = "masks:delegate:".freeze
+      UPSTREAM_ACCESS_TOKEN = "urn:masks:params:oauth:token-type:upstream_access_token".freeze
+      REFUSALS = %w[invalid_grant insufficient_scope invalid_target unauthorized_client access_denied
+                    login_required interaction_required consent_required invalid_scope].freeze
+
+      class Refused < Error
+        attr_reader :code, :description, :secret
+
+        def initialize(code, description, secret: nil)
+          super([ code, description ].compact.join(": "))
+
+          @code = code
+          @description = description
+          @secret = secret
+        end
+
+        def signed_in_again?
+          %w[login_required interaction_required].include?(code)
+        end
+      end
+
+      class Unavailable < Error
+        attr_reader :secret
+
+        def initialize(message, secret: nil)
+          super(message)
+
+          @secret = secret
+        end
+      end
+
+      Held = Struct.new(:connection, :provider, :provider_name, :label, :subject, :secret, keyword_init: true)
+
+      Upstream = Struct.new(:access_token, :expires_at, :scope, :secret, keyword_init: true) do
+        def expired?(leeway: 60)
+          Time.now.to_i + leeway >= expires_at.to_i
+        end
+      end
+
+      attr_reader :issuer, :client_id, :client_secret, :redirect_uri
+
+      def initialize(issuer:, client_id:, client_secret:, redirect_uri:)
+        @issuer = Issuer.resolve(issuer)
+        @client_id = client_id
+        @client_secret = client_secret
+        @redirect_uri = redirect_uri
+      end
+
+      def start(provider:, prompt: nil, max_age: nil, state: SecureRandom.urlsafe_base64(24))
+        started = session.start(scope: [ "openid", "offline_access", "#{SCOPE}#{provider}" ], prompt: prompt,
+                                max_age: max_age, state: state)
+
+        { "url" => started[:url], "state" => started[:state], "verifier" => started[:verifier], "provider" => provider.to_s }
+      end
+
+      def finish(params:, started:)
+        params = params.to_h.transform_keys(&:to_s)
+        started = started.to_h.transform_keys(&:to_s)
+
+        raise Refused.new(params["error"], params["error_description"]) if params["error"].to_s != ""
+
+        unless params["state"].to_s != "" && OpenSSL.secure_compare(params["state"].to_s, started["state"].to_s)
+          raise Refused.new("invalid_state", "the state did not match the one this connection started with")
+        end
+
+        tokens = answered { session.complete(code: params["code"].to_s, verifier: started["verifier"].to_s) }
+        held = tokens.delegations.find { |one| one["provider"] == started["provider"] }
+
+        raise Refused.new("access_denied", "masks connected nothing for #{started['provider']}") if held.nil?
+        raise Refused.new("invalid_grant", "masks issued no refresh token to keep the connection with") if tokens.refresh_token.to_s == ""
+
+        Held.new(
+          connection: held["connection"], provider: held["provider"], provider_name: held["provider_name"],
+          label: held["label"], subject: held["subject"], secret: tokens.refresh_token
+        )
+      end
+
+      def token(secret, connection:)
+        refreshed = answered { session.refresh(secret.to_s) }
+        rotated = refreshed.refresh_token.to_s == "" ? secret : refreshed.refresh_token
+
+        released = answered(secret: rotated) do
+          session.exchange(refreshed.access_token, requested_token_type: UPSTREAM_ACCESS_TOKEN, audience: connection.to_s)
+        end
+
+        Upstream.new(access_token: released.access_token, expires_at: released.expires_at, scope: released.scope, secret: rotated)
+      end
+
+      private
+
+        def session
+          @session ||= Session.new(issuer: issuer, client_id: client_id, client_secret: client_secret, redirect_uri: redirect_uri)
+        end
+
+        def answered(secret: nil)
+          yield
+        rescue Unregistered
+          raise
+        rescue Rejected => e
+          raise Unavailable.new("masks answered #{e.status}: #{e.message}", secret: secret) if unavailable?(e)
+
+          raise Refused.new(e.code, e.description, secret: secret)
+        rescue Unreachable => e
+          raise Unavailable.new(e.message, secret: secret)
+        end
+
+        def unavailable?(rejection)
+          return false if REFUSALS.include?(rejection.code)
+
+          rejection.code == "temporarily_unavailable" || rejection.status.to_i >= 500 || rejection.status.to_i == 429
+        end
+    end
+  end
+end

data/lib/masks/client/handshake.rb

@@ -5,16 +5,18 @@ module Masks
       GRANT_TYPES = %w[authorization_code refresh_token].freeze
       AUTH_METHOD = "client_secret_basic".freeze
 
-      attr_reader :issuer, :name, :resource, :redirect_uris, :scope, :return_to
+      attr_reader :issuer, :name, :resource, :redirect_uris, :scope, :return_to,
+                  :backchannel_logout_uri
 
       def initialize(issuer, name:, resource:, redirect_uris:, return_to:,
-                     scope: Session::DEFAULT_SCOPE)
+                     scope: Session::DEFAULT_SCOPE, backchannel_logout_uri: nil)
         @issuer = Issuer.resolve(issuer)
         @name = name.to_s
         @resource = resource.to_s
         @redirect_uris = Array(redirect_uris).map(&:to_s)
         @scope = Array(scope).flat_map { |value| value.to_s.split(/\s+/) }.reject(&:empty?)
         @return_to = return_to.to_s
+        @backchannel_logout_uri = backchannel_logout_uri&.to_s
       end
 
       def endpoint
@@ -34,6 +36,7 @@ module Masks
           [ "state", state ]
         ]
 
+        query << [ "backchannel_logout_uri", backchannel_logout_uri ] if backchannel_logout_uri
         redirect_uris.each { |uri| query << [ "redirect_uris", uri ] }
 
         "#{endpoint}?#{URI.encode_www_form(query)}"
@@ -61,7 +64,8 @@ module Masks
           redirect_uris: redirect_uris,
           grant_types: GRANT_TYPES,
           scope: scope,
-          token_endpoint_auth_method: AUTH_METHOD
+          token_endpoint_auth_method: AUTH_METHOD,
+          backchannel_logout_uri: backchannel_logout_uri
         )
       end
 

data/lib/masks/client/introspection.rb

@@ -5,7 +5,7 @@ module Masks
         to_h["active"] == true
       end
 
-      def username
+      def nickname
         self["username"]
       end
 
@@ -24,6 +24,12 @@ module Masks
 
         super
       end
+
+      def member!(*roles, organization: nil)
+        raise Unauthorized.new("the issuer reports this token is not active") unless active?
+
+        super
+      end
     end
   end
 end

data/lib/masks/client/issuer.rb

@@ -51,6 +51,10 @@ module Masks
         discovery.fetch(name) { raise Rejected.new("invalid_issuer", "#{url} publishes no #{name}") }
       end
 
+      def backchannel_logout?
+        discovery["backchannel_logout_supported"] == true
+      end
+
       def avatar_styles
         discovery["avatar_styles_supported"] || Claims::Avatars::STYLES
       end

data/lib/masks/client/logout.rb

@@ -0,0 +1,60 @@
+module Masks
+  module Client
+    class Logout
+      EVENT = "http://schemas.openid.net/event/backchannel-logout".freeze
+      ALGORITHMS = Verifier::ALGORITHMS
+      LEEWAY = 60
+
+      class << self
+        def verify(token, issuer:, audience:, algorithms: ALGORITHMS)
+          held = Verifier
+            .new(issuer, audience: audience, algorithms: algorithms)
+            .verify(token, required: %w[iss aud iat jti events], typ: Verifier::LOGOUT_TOKEN)
+
+          new(held).validate!
+        end
+      end
+
+      attr_reader :claims
+
+      def initialize(claims)
+        @claims = claims
+      end
+
+      def subject
+        claims["sub"]
+      end
+
+      def sid
+        claims["sid"]
+      end
+
+      def jti
+        claims["jti"]
+      end
+
+      def issued_at
+        Time.at(claims["iat"].to_i).utc
+      end
+
+      def validate!
+        refuse!("logout token carries a nonce, so it is an id token") if claims.key?("nonce")
+        refuse!("logout token names neither a subject nor a session") if subject.nil? && sid.nil?
+        refuse!("logout token was issued in the future") if issued_at > Time.now.utc + LEEWAY
+
+        held = claims["events"]
+
+        refuse!("logout token has no events claim") unless held.is_a?(Hash)
+        refuse!("logout token is not about a logout") unless held[EVENT].is_a?(Hash)
+
+        self
+      end
+
+      private
+
+        def refuse!(said)
+          raise InvalidToken, said
+        end
+    end
+  end
+end

data/lib/masks/client/registration.rb

@@ -23,7 +23,8 @@ module Masks
           "token_endpoint_auth_method" => attributes[:token_endpoint_auth_method],
           "application_type" => attributes[:application_type],
           "client_uri" => attributes[:client_uri],
-          "logo_uri" => attributes[:logo_uri]
+          "logo_uri" => attributes[:logo_uri],
+          "backchannel_logout_uri" => attributes[:backchannel_logout_uri]
         }.reject { |_, value| value.nil? || (value.respond_to?(:empty?) && value.empty?) }
       end
 
@@ -32,8 +33,6 @@ module Masks
         list.empty? ? default : list
       end
 
-      # Rebuild a registration from what a consumer stored, so RFC 7592's read,
-      # update and delete are reachable without having just created it.
       def self.held(issuer, credentials)
         held = credentials.to_h.transform_keys(&:to_s)
         return nil if held["registration_client_uri"].blank? || held["registration_access_token"].blank?

data/lib/masks/client/resource.rb

@@ -18,10 +18,11 @@ module Masks
         @verifier = verifier || Verifier.new(@issuer, audience: @url, algorithms: algorithms)
       end
 
-      def authenticate(authorization, scope: nil)
-        claims = Claims.new(@verifier.verify(token!(authorization), required: @required))
+      def authenticate(authorization, scope: nil, role: nil, organization: nil)
+        claims = Claims.new(@verifier.verify(token!(authorization), required: @required, typ: Verifier::ACCESS_TOKEN))
 
         Array(scope).each { |name| claims.permit!(name) }
+        claims.member!(*Array(role), organization: organization) if role || organization
 
         claims
       rescue InvalidToken => e

data/lib/masks/client/session.rb

@@ -2,21 +2,37 @@ module Masks
   module Client
     class Session
       DEFAULT_SCOPE = %w[openid profile email].freeze
+      ORGANIZATION = "organization".freeze
+      ORGANIZATION_KEY = /\A[a-z0-9][a-z0-9-]*\z/
 
-      attr_reader :issuer, :client_id, :client_secret, :redirect_uri, :scope
+      def self.organization_key(value)
+        key = value.to_s.strip.downcase
+
+        key.match?(ORGANIZATION_KEY) ? key : nil
+      end
+      ASSERTION_TYPE = "urn:ietf:params:oauth:client-assertion-type:jwt-bearer".freeze
+      ASSERTION_LIFETIME = 60
+
+      attr_reader :issuer, :client_id, :client_secret, :redirect_uri, :scope, :private_key, :key_id
+
+      def initialize(issuer:, client_id:, redirect_uri: nil, client_secret: nil, private_key: nil, key_id: nil,
+                     scope: DEFAULT_SCOPE)
+        raise ArgumentError, "a client authenticates with a secret or a private key, not both" if client_secret && private_key
 
-      def initialize(issuer:, client_id:, redirect_uri:, client_secret: nil, scope: DEFAULT_SCOPE)
         @issuer = Issuer.resolve(issuer)
         @client_id = client_id
         @client_secret = client_secret
+        @private_key = private_key.is_a?(String) ? OpenSSL::PKey.read(private_key) : private_key
+        @key_id = key_id
         @redirect_uri = redirect_uri
         @scope = Array(scope)
       end
 
       def start(resource: nil, prompt: nil, scope: nil, state: SecureRandom.urlsafe_base64(24),
-                nonce: SecureRandom.urlsafe_base64(24))
+                nonce: SecureRandom.urlsafe_base64(24), max_age: nil, organization: nil)
         pkce = Pkce.generate
         scopes = Array(scope || self.scope)
+        organization = Session.organization_key(organization)
         nonce = nil unless scopes.include?("openid")
 
         pairs = [
@@ -33,6 +49,8 @@ module Masks
 
         Array(resource).each { |value| pairs << [ "resource", value ] }
         pairs << [ "prompt", prompt ] if prompt
+        pairs << [ "max_age", max_age.to_i ] if max_age
+        pairs << [ "organization", organization ] if organization
 
         {
           url: "#{issuer.endpoint('authorization_endpoint')}?#{URI.encode_www_form(pairs)}",
@@ -53,7 +71,16 @@ module Masks
 
         Array(resource).each { |value| form << [ "resource", value ] }
 
-        Tokens.granted(HTTP.post_form(issuer.endpoint("token_endpoint"), form, authorization))
+        Tokens.granted(post("token_endpoint", form))
+      end
+
+      def client_credentials(scope: nil, resource: nil)
+        form = [ [ "grant_type", "client_credentials" ], [ "client_id", client_id ] ]
+
+        form << [ "scope", Array(scope).join(" ") ] if scope
+        Array(resource).each { |value| form << [ "resource", value ] }
+
+        Tokens.granted(post("token_endpoint", form))
       end
 
       def refresh(refresh_token, resource: nil, scope: nil)
@@ -66,32 +93,42 @@ module Masks
         form << [ "scope", Array(scope).join(" ") ] if scope
         Array(resource).each { |value| form << [ "resource", value ] }
 
-        Tokens.granted(HTTP.post_form(issuer.endpoint("token_endpoint"), form, authorization))
+        Tokens.granted(post("token_endpoint", form))
       end
 
-      def exchange(subject_token, scope: nil, resource: nil, lifetime: nil)
+      def exchange(subject_token, scope: nil, resource: nil, lifetime: nil, requested_token_type: nil, audience: nil,
+                   subject_token_type: Tokens::ACCESS_TOKEN, actor_token: nil, actor_token_type: Tokens::ACCESS_TOKEN)
         form = [
           [ "grant_type", Tokens::EXCHANGE ],
           [ "client_id", client_id ],
           [ "subject_token", subject_token ],
-          [ "subject_token_type", Tokens::ACCESS_TOKEN ]
+          [ "subject_token_type", subject_token_type ]
         ]
 
+        form.push([ "actor_token", actor_token ], [ "actor_token_type", actor_token_type ]) if actor_token
+
+        form << [ "requested_token_type", requested_token_type ] if requested_token_type
+        Array(audience).each { |value| form << [ "audience", value ] }
+
         form << [ "scope", Array(scope).join(" ") ] if scope
         form << [ "requested_lifetime", lifetime.to_i ] if lifetime
         Array(resource).each { |value| form << [ "resource", value ] }
 
-        Tokens.granted(HTTP.post_form(issuer.endpoint("token_endpoint"), form, authorization))
+        Tokens.granted(post("token_endpoint", form))
       end
 
       def revoke(token, hint: nil)
         form = [ [ "token", token ], [ "client_id", client_id ] ]
         form << [ "token_type_hint", hint ] if hint
 
-        HTTP.post_form(issuer.endpoint("revocation_endpoint"), form, authorization)
+        post("revocation_endpoint", form)
         true
       end
 
+      def logout_token(token)
+        Logout.verify(token, issuer: issuer, audience: client_id)
+      end
+
       def end_session_url(post_logout_redirect_uri: nil, state: nil, id_token_hint: nil)
         pairs = [ [ "client_id", client_id ] ]
         pairs << [ "id_token_hint", id_token_hint ] if id_token_hint
@@ -106,7 +143,7 @@ module Masks
         form << [ "token_type_hint", hint ] if hint
 
         Introspection.new(
-          HTTP.post_form(issuer.endpoint("introspection_endpoint"), form, authorization)
+          post("introspection_endpoint", form)
         )
       end
 
@@ -132,6 +169,36 @@ module Masks
 
       private
 
+        def post(endpoint, form)
+          url = issuer.endpoint(endpoint)
+
+          HTTP.post_form(url, form + assertion, authorization)
+        end
+
+        def assertion
+          return [] if private_key.nil?
+
+          now = Time.now.to_i
+          claims = {
+            "iss" => client_id, "sub" => client_id, "aud" => issuer.url,
+            "iat" => now, "exp" => now + ASSERTION_LIFETIME, "jti" => SecureRandom.uuid
+          }
+          header = key_id ? { kid: key_id } : {}
+
+          [
+            [ "client_assertion_type", ASSERTION_TYPE ],
+            [ "client_assertion", JWT.encode(claims, private_key, signing_algorithm, header) ]
+          ]
+        end
+
+        def signing_algorithm
+          return "RS256" if private_key.is_a?(OpenSSL::PKey::RSA)
+
+          { "prime256v1" => "ES256", "secp384r1" => "ES384", "secp521r1" => "ES512" }.fetch(private_key.group.curve_name) do
+            raise ArgumentError, "#{private_key.group.curve_name} is not a curve masks checks assertions for"
+          end
+        end
+
         def authorization
           return {} if client_secret.nil?
 

data/lib/masks/client/tokens.rb

@@ -3,8 +3,10 @@ module Masks
     class Tokens
       EXCHANGE = "urn:ietf:params:oauth:grant-type:token-exchange".freeze
       ACCESS_TOKEN = "urn:ietf:params:oauth:token-type:access_token".freeze
+      ID_TOKEN = "urn:ietf:params:oauth:token-type:id_token".freeze
 
-      attr_reader :access_token, :id_token, :refresh_token, :token_type, :scope, :expires_in, :obtained_at
+      attr_reader :access_token, :id_token, :refresh_token, :token_type, :scope, :expires_in, :obtained_at,
+                  :delegations
 
       def self.granted(body)
         token = new(body)
@@ -26,6 +28,7 @@ module Masks
         @token_type = body["token_type"] || "Bearer"
         @scope = body["scope"].to_s
         @expires_in = body["expires_in"].to_i
+        @delegations = Array(body["delegations"])
         @obtained_at = Time.now.to_i
       end
 

data/lib/masks/client/verifier.rb

@@ -2,6 +2,9 @@ module Masks
   module Client
     class Verifier
       ALGORITHMS = %w[RS256 ES256].freeze
+      ACCESS_TOKEN = "at+jwt".freeze
+      LOGOUT_TOKEN = "logout+jwt".freeze
+      ID_TOKEN = [ "jwt", nil ].freeze
 
       attr_reader :issuer, :audience
 
@@ -11,8 +14,8 @@ module Masks
         @algorithms = algorithms
       end
 
-      def verify(token, required: %w[iss sub exp])
-        JWT.decode(
+      def verify(token, required: %w[iss sub exp], typ: ID_TOKEN)
+        claims, header = JWT.decode(
           token, nil, true,
           algorithms: @algorithms,
           jwks: keys,
@@ -20,7 +23,11 @@ module Masks
           aud: audience, verify_aud: true,
           verify_expiration: true,
           required_claims: required
-        ).first
+        )
+
+        typed!(header["typ"], Array(typ))
+
+        claims
       rescue JWT::DecodeError => e
         raise InvalidToken, e.message
       end
@@ -31,6 +38,14 @@ module Masks
 
       private
 
+        def typed!(held, accepted)
+          named = held&.to_s&.downcase&.delete_prefix("application/")
+
+          return if accepted.include?(named)
+
+          raise InvalidToken, "that token is typed #{held.inspect}, not #{accepted.compact.join(' or ')}"
+        end
+
         def keys
           ->(options) do
             issuer.refresh! if options[:invalidate]