masks 0.7.0 → 0.9.1

data/lib/masks/client/claims.rb

@@ -60,7 +60,51 @@ module Masks
         end
       end
 
+      class Organization
+        OWNER = "owner".freeze
+
+        attr_reader :to_h
+
+        def initialize(hash)
+          @to_h = hash.is_a?(Hash) ? hash.transform_keys(&:to_s) : {}
+        end
+
+        def id
+          to_h["id"]
+        end
+
+        def key
+          to_h["key"]
+        end
+
+        def name
+          to_h["name"]
+        end
+
+        def role
+          to_h["role"]
+        end
+
+        def role?(*roles)
+          roles.flatten.map(&:to_s).include?(role)
+        end
+
+        def owner?
+          role?(OWNER)
+        end
+
+        def present?
+          !id.nil? && !key.nil? && !role.nil?
+        end
+
+        def ==(other)
+          other.is_a?(Organization) ? to_h == other.to_h : false
+        end
+      end
+
       AVATARS = "masks:avatars".freeze
+      ORGANIZATION = "org".freeze
+      ORGANIZATIONS = "orgs".freeze
 
       attr_reader :to_h
 
@@ -104,6 +148,31 @@ module Masks
         @avatars ||= Avatars.new(self[AVATARS])
       end
 
+      def organization
+        @organization ||= Organization.new(self[ORGANIZATION])
+      end
+
+      def organizations
+        @organizations ||= Array(self[ORGANIZATIONS]).map { |held| Organization.new(held) }.select(&:present?).freeze
+      end
+
+      def member!(*roles, organization: nil)
+        held = self.organization
+
+        unless held.present?
+          raise Forbidden.new("insufficient_organization", "this token names no organization",
+                              scope: Session::ORGANIZATION)
+        end
+
+        if organization && held.key != organization.to_s && held.id != organization.to_s
+          raise Forbidden.new("insufficient_organization", "this token was issued for #{held.key}, not #{organization}")
+        end
+
+        return held if roles.flatten.empty? || held.role?(*roles)
+
+        raise Forbidden.new("insufficient_role", "#{held.role} in #{held.key} is not #{roles.flatten.join(' or ')}")
+      end
+
       def picture
         self["picture"] || avatars.photo || avatars.identicon
       end

data/lib/masks/client/errors.rb

@@ -29,13 +29,18 @@ module Masks
     class Challenge < Error
       attr_reader :code, :description, :status, :scope
 
-      def initialize(code, description, status:, scope: nil)
+      def initialize(code, description, status:, scope: nil, dpop: false)
         super([ code, description ].compact.join(": "))
 
         @code = code
         @description = description
         @status = status
         @scope = scope
+        @dpop = dpop
+      end
+
+      def dpop?
+        @dpop
       end
     end
 
@@ -46,8 +51,8 @@ module Masks
     end
 
     class Unauthorized < Challenge
-      def initialize(description, code: "invalid_token")
-        super(code, description, status: 401)
+      def initialize(description, code: "invalid_token", dpop: false)
+        super(code, description, status: 401, dpop: dpop)
       end
     end
 

data/lib/masks/client/introspection.rb

@@ -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/logout.rb

@@ -9,7 +9,7 @@ module Masks
         def verify(token, issuer:, audience:, algorithms: ALGORITHMS)
           held = Verifier
             .new(issuer, audience: audience, algorithms: algorithms)
-            .verify(token, required: %w[iss aud iat jti events])
+            .verify(token, required: %w[iss aud iat jti events], typ: Verifier::LOGOUT_TOKEN)
 
           new(held).validate!
         end

data/lib/masks/client/pkce.rb

@@ -14,9 +14,7 @@ module Masks
       end
 
       def challenge
-        Base64.urlsafe_encode64(
-          OpenSSL::Digest::SHA256.digest(verifier), padding: false
-        )
+        Proof.digest(verifier)
       end
 
       def method

data/lib/masks/client/proof.rb

@@ -0,0 +1,153 @@
+module Masks
+  module Client
+    class Proof
+      class Invalid < Error; end
+
+      SCHEME = "DPoP".freeze
+      TYPE = "dpop+jwt".freeze
+      ALGORITHMS = %w[ES256 ES384 ES512 PS256 PS384 PS512 RS256].freeze
+      SECRET = %w[d p q dp dq qi k].freeze
+      THUMBED = { "EC" => %w[crv kty x y], "RSA" => %w[e kty n] }.freeze
+      LEEWAY = 30
+      WINDOW = 60
+      MEMORY = WINDOW + (LEEWAY * 2)
+
+      class Memory
+        def initialize
+          @held = {}
+          @lock = Mutex.new
+          @swept = 0.0
+        end
+
+        def first?(key, expires_in:)
+          now = Time.now.to_f
+
+          @lock.synchronize do
+            sweep(now) if now - @swept > 1
+            return false if @held.key?(key) && @held[key] >= now
+
+            @held[key] = now + expires_in
+            true
+          end
+        end
+
+        private
+
+          def sweep(now)
+            @held.delete_if { |_, until_at| until_at < now }
+            @swept = now
+          end
+      end
+
+      MEMORY_LOCK = Mutex.new
+
+      def self.memory
+        MEMORY_LOCK.synchronize { @memory ||= Memory.new }
+      end
+
+      def self.thumbprint(jwk)
+        named = THUMBED[jwk["kty"]] || raise(Invalid, "the proof key is of a kind this resource does not read")
+        held = named.to_h { |field| [ field, jwk[field] ] }
+
+        raise Invalid, "the proof key is missing part of itself" if held.any? { |_, value| value.to_s.empty? }
+
+        digest(JSON.generate(held))
+      end
+
+      def self.digest(value)
+        Base64.urlsafe_encode64(OpenSSL::Digest::SHA256.digest(value.to_s), padding: false)
+      end
+
+      def initialize(proof, method:, url:, replay: nil)
+        held = proof.to_s.split(",").map(&:strip).reject(&:empty?)
+
+        raise Invalid, "exactly one DPoP proof is required" unless held.size == 1
+
+        @proof = held.first
+        @method = method.to_s.upcase
+        @url = url.to_s
+        @replay = replay
+      end
+
+      def check!(access_token:, jkt:)
+        header = keyed
+        claims = verified(header)
+        thumbprint = self.class.thumbprint(header["jwk"])
+
+        raise Invalid, "that proof was made with another key than the token is bound to" unless same?(thumbprint, jkt)
+
+        matches!(claims)
+        timely!(claims)
+        raise Invalid, "that proof was made for another token" unless same?(claims["ath"].to_s, self.class.digest(access_token))
+
+        once!(claims, thumbprint)
+
+        self
+      end
+
+      private
+
+        def keyed
+          header = JWT.decode(@proof, nil, false).last
+
+          raise Invalid, "a proof must be typed #{TYPE}" unless header["typ"].to_s.casecmp?(TYPE)
+          raise Invalid, "#{header['alg'] || 'that'} is not an algorithm a proof may use" unless ALGORITHMS.include?(header["alg"].to_s)
+
+          jwk = header["jwk"]
+
+          raise Invalid, "a proof must carry the public key that signed it" unless jwk.is_a?(Hash)
+          raise Invalid, "a proof key must be public" if jwk["kty"].to_s == "oct" || jwk.keys.any? { |field| SECRET.include?(field.to_s) }
+
+          header
+        rescue JWT::DecodeError
+          raise Invalid, "that proof is not a readable JWT"
+        end
+
+        def verified(header)
+          JWT.decode(@proof, JWT::JWK.new(header["jwk"]).verify_key, true,
+                     algorithms: [ header["alg"].to_s ], verify_expiration: false).first
+        rescue JWT::DecodeError, JWT::JWKError, OpenSSL::PKey::PKeyError, ArgumentError
+          raise Invalid, "that proof was not signed by the key it carries"
+        end
+
+        def matches!(claims)
+          raise Invalid, "that proof was made for another method" unless claims["htm"].to_s.upcase == @method
+          raise Invalid, "that proof was made for another URL" unless tidied(claims["htu"]) == tidied(@url)
+        end
+
+        def tidied(value)
+          uri = URI.parse(value.to_s)
+          raise Invalid, "that proof names no URL" if uri.host.nil?
+
+          port = ":#{uri.port}" unless uri.port.nil? || uri.port == uri.default_port
+          path = uri.path.to_s == "/" ? "" : uri.path.to_s
+
+          "#{uri.scheme.to_s.downcase}://#{uri.host.downcase}#{port}#{path}"
+        rescue URI::InvalidURIError
+          raise Invalid, "that proof names a URL this resource cannot read"
+        end
+
+        def timely!(claims)
+          made = claims["iat"]
+
+          raise Invalid, "a proof must say when it was made" unless made.is_a?(Numeric)
+          raise Invalid, "that proof was made too long ago" if made < Time.now.to_i - WINDOW - LEEWAY
+          raise Invalid, "that proof was made in the future" if made > Time.now.to_i + LEEWAY
+        end
+
+        def once!(claims, thumbprint)
+          jti = claims["jti"].to_s
+
+          raise Invalid, "a proof must carry a jti" if jti.empty?
+          return if @replay.nil? || @replay.first?("#{thumbprint}:#{jti}", expires_in: MEMORY)
+
+          raise Invalid, "that proof has already been used"
+        end
+
+        def same?(held, expected)
+          !held.to_s.empty? && held.bytesize == expected.to_s.bytesize &&
+            OpenSSL.fixed_length_secure_compare(held, expected.to_s)
+        end
+    end
+  end
+end

data/lib/masks/client/rack.rb

@@ -15,7 +15,10 @@ module Masks
       def call(env)
         return @app.call(env) unless guards?(env)
 
-        env[CLAIMS] = resource(env).authenticate(env["HTTP_AUTHORIZATION"], scope: @scope)
+        env[CLAIMS] = resource(env).authenticate(
+          env["HTTP_AUTHORIZATION"], scope: @scope,
+          proof: env["HTTP_DPOP"], method: env["REQUEST_METHOD"], url: url(env)
+        )
 
         @app.call(env)
       rescue Challenge => e
@@ -32,6 +35,17 @@ module Masks
           @only.call(env)
         end
 
+        def url(env)
+          if defined?(::Rack::Request)
+            request = ::Rack::Request.new(env)
+            return "#{request.base_url}#{request.path}"
+          end
+
+          host = env["HTTP_HOST"] || "#{env['SERVER_NAME']}:#{env['SERVER_PORT']}"
+
+          "#{env['rack.url_scheme'] || 'http'}://#{host}#{env['SCRIPT_NAME']}#{env['PATH_INFO']}"
+        end
+
         def passthrough(env, error)
           env[ERROR] = error
 

data/lib/masks/client/registry.rb

@@ -16,10 +16,6 @@ module Masks
         @lock.synchronize { @issuers.clear }
         self
       end
-
-      def urls
-        @lock.synchronize { @issuers.keys }
-      end
     end
   end
 end

data/lib/masks/client/resource.rb

@@ -1,14 +1,14 @@
 module Masks
   module Client
     class Resource
-      BEARER = /\ABearer[ \t]+([^\s,]+)[ \t]*\z/i.freeze
+      PRESENTED = /\A(Bearer|DPoP)[ \t]+([^\s,]+)[ \t]*\z/i.freeze
       METADATA_PATH = "/.well-known/oauth-protected-resource".freeze
       REQUIRED = %w[iss sub exp].freeze
 
       attr_reader :issuer, :url, :scopes
 
       def initialize(issuer:, url:, scopes: [], metadata_url: nil,
-                     algorithms: Verifier::ALGORITHMS, required: REQUIRED, verifier: nil)
+                     algorithms: Verifier::ALGORITHMS, required: REQUIRED, verifier: nil, replay: Proof.memory)
         @issuer = Issuer.resolve(issuer)
         @url = url.to_s
         @descriptions = describe(scopes)
@@ -16,12 +16,17 @@ module Masks
         @metadata_url = metadata_url
         @required = Array(required)
         @verifier = verifier || Verifier.new(@issuer, audience: @url, algorithms: algorithms)
+        @replay = replay
       end
 
-      def authenticate(authorization, scope: nil)
-        claims = Claims.new(@verifier.verify(token!(authorization), required: @required))
+      def authenticate(authorization, scope: nil, role: nil, organization: nil, proof: nil, method: nil, url: nil)
+        scheme, token = presented!(authorization)
+        held = @verifier.verify(token, required: @required, typ: Verifier::ACCESS_TOKEN)
+        bound!(held, scheme, token, proof: proof, method: method, url: url)
+        claims = Claims.new(held)
 
         Array(scope).each { |name| claims.permit!(name) }
+        claims.member!(*Array(role), organization: organization) if role || organization
 
         claims
       rescue InvalidToken => e
@@ -29,7 +34,7 @@ module Masks
       end
 
       def token(authorization)
-        authorization.to_s[BEARER, 1]
+        authorization.to_s[PRESENTED, 2]
       end
 
       def metadata_url
@@ -42,7 +47,8 @@ module Masks
           "authorization_servers" => [ issuer.url ],
           "scopes_supported" => scopes,
           "scope_descriptions" => @descriptions,
-          "bearer_methods_supported" => [ "header" ]
+          "bearer_methods_supported" => [ "header" ],
+          "dpop_signing_alg_values_supported" => Proof::ALGORITHMS
         }.reject { |_, value| value.respond_to?(:empty?) && value.empty? }
       end
 
@@ -56,7 +62,9 @@ module Masks
           [ "resource_metadata", metadata_url ]
         ]
 
-        "Bearer " + parameters.filter_map { |name, value|
+        scheme = error.dpop? ? "#{Proof::SCHEME} algs=\"#{Proof::ALGORITHMS.join(' ')}\", " : "Bearer "
+
+        scheme + parameters.filter_map { |name, value|
           %(#{name}="#{quote(value)}") if value && !value.to_s.empty?
         }.join(", ")
       end
@@ -71,8 +79,22 @@ module Masks
           end.freeze
         end
 
-        def token!(authorization)
-          token(authorization) || raise(Unauthenticated.new)
+        def presented!(authorization)
+          match = authorization.to_s.match(PRESENTED) || raise(Unauthenticated.new)
+
+          [ match[1].casecmp?(Proof::SCHEME) ? :dpop : :bearer, match[2] ]
+        end
+
+        def bound!(claims, scheme, token, proof:, method:, url:)
+          jkt = claims.dig("cnf", "jkt")
+
+          raise Unauthorized.new("that token is not bound to a key, so it is presented as Bearer") if jkt.nil? && scheme == :dpop
+          raise Unauthorized.new("that token is bound to a key, so it is presented as DPoP with a proof", dpop: true) if jkt && scheme != :dpop
+          return if jkt.nil?
+
+          Proof.new(proof, method: method, url: url || self.url, replay: @replay).check!(access_token: token, jkt: jkt)
+        rescue Proof::Invalid => e
+          raise Unauthorized.new(e.message, code: "invalid_dpop_proof", dpop: true)
         end
 
         def origin

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), max_age: nil)
+                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 = [
@@ -34,6 +50,7 @@ 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)}",
@@ -54,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)
@@ -67,17 +93,20 @@ 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, requested_token_type: nil, audience: 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 ] }
 
@@ -85,14 +114,14 @@ module Masks
         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
 
@@ -114,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
 
@@ -140,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,6 +3,7 @@ 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,
                   :delegations

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,17 +23,25 @@ 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
 
-      def tenant(token)
-        verify(token)["tenant"]
-      end
-
       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]

data/lib/masks/client.rb

@@ -19,6 +19,7 @@ require_relative "client/claims"
 require_relative "client/introspection"
 require_relative "client/session"
 require_relative "client/verifier"
+require_relative "client/proof"
 require_relative "client/logout"
 require_relative "client/resource"
 require_relative "client/rack"