masks 0.10.0 → 0.11.0

data/lib/masks/client/key.rb

@@ -0,0 +1,100 @@
+module Masks
+  module Client
+    class Key
+      CURVE = "prime256v1".freeze
+      ALGORITHM = "ES256".freeze
+      PUBLIC = %w[kty crv x y].freeze
+
+      def self.generate
+        new(OpenSSL::PKey::EC.generate(CURVE))
+      end
+
+      def self.parse(data)
+        held = data.is_a?(String) && !data.lstrip.start_with?("{") ? OpenSSL::PKey.read(data) : imported(data)
+
+        new(held)
+      rescue OpenSSL::PKey::PKeyError, JSON::ParserError, JWT::JWKError, ArgumentError
+        raise ArgumentError, "a key is a private P-256 key, as a PEM or a JWK"
+      end
+
+      def self.from(value)
+        case value
+        when self then value
+        when OpenSSL::PKey::PKey then new(value)
+        else parse(value)
+        end
+      end
+
+      def self.imported(data)
+        held = data.is_a?(String) ? JSON.parse(data) : data.to_h
+
+        JWT::JWK.import(held.transform_keys(&:to_sym)).signing_key
+      end
+
+      def self.htu(url)
+        uri = URI.parse(url.to_s)
+        uri.query = nil
+        uri.fragment = nil
+
+        uri.to_s
+      end
+
+      attr_reader :private_key, :thumbprint
+
+      def initialize(private_key)
+        unless private_key.is_a?(OpenSSL::PKey::EC) && private_key.private? && private_key.group.curve_name == CURVE
+          raise ArgumentError, "a key is a private P-256 key"
+        end
+
+        @private_key = private_key
+        @public = JWT::JWK.new(private_key).export.transform_keys(&:to_s).slice(*PUBLIC).freeze
+        @thumbprint = Proof.thumbprint(@public)
+      end
+
+      alias_method :kid, :thumbprint
+
+      def public_jwk
+        @public.merge("kid" => thumbprint, "alg" => ALGORITHM, "use" => "sig")
+      end
+
+      def jwks
+        { "keys" => [ public_jwk ] }
+      end
+
+      def to_h
+        JWT::JWK.new(private_key).export(include_private: true).transform_keys(&:to_s)
+                .merge("kid" => thumbprint, "alg" => ALGORITHM, "use" => "sig")
+      end
+
+      def to_json(*)
+        JSON.generate(to_h)
+      end
+
+      def to_pem
+        private_key.private_to_pem
+      end
+
+      def inspect
+        "#<#{self.class.name} #{thumbprint}>"
+      end
+
+      def sign(claims, header = {})
+        JWT.encode(claims, private_key, ALGORITHM, header)
+      end
+
+      def proof(method, url, access_token: nil, nonce: nil)
+        claims = {
+          "jti" => SecureRandom.urlsafe_base64(24),
+          "htm" => method.to_s.upcase,
+          "htu" => self.class.htu(url),
+          "iat" => Time.now.to_i
+        }
+
+        claims["ath"] = Proof.digest(access_token) unless access_token.to_s.empty?
+        claims["nonce"] = nonce unless nonce.to_s.empty?
+
+        sign(claims, { typ: Proof::TYPE, jwk: @public })
+      end
+    end
+  end
+end

data/lib/masks/client/nonces.rb

@@ -0,0 +1,31 @@
+module Masks
+  module Client
+    class Nonces
+      HEADER = "DPoP-Nonce".freeze
+
+      def self.origin(url)
+        uri = url.is_a?(URI::Generic) ? url : URI.parse(url.to_s)
+        port = ":#{uri.port}" unless uri.port.nil? || uri.port == uri.default_port
+
+        "#{uri.scheme.to_s.downcase}://#{uri.host.to_s.downcase}#{port}"
+      end
+
+      def initialize
+        @held = {}
+        @lock = Mutex.new
+      end
+
+      def [](url)
+        @lock.synchronize { @held[self.class.origin(url)] }
+      end
+
+      def learn(url, response)
+        wanted = response[HEADER].to_s.strip
+
+        return nil if wanted.empty?
+
+        @lock.synchronize { @held[self.class.origin(url)] = wanted }
+      end
+    end
+  end
+end

data/lib/masks/client/proof.rb

@@ -139,11 +139,17 @@ module Masks
           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)
+          return if @replay.nil? || first?("#{thumbprint}:#{jti}")
 
           raise Invalid, "that proof has already been used"
         end
 
+        def first?(key)
+          @replay.first?(key, expires_in: MEMORY)
+        rescue StandardError => e
+          raise ReplayUnavailable, "the replay store could not say whether that proof is new (#{e.class})"
+        end
+
         def same?(held, expected)
           !held.to_s.empty? && held.bytesize == expected.to_s.bytesize &&
             OpenSSL.fixed_length_secure_compare(held, expected.to_s)

data/lib/masks/client/rack.rb

@@ -25,6 +25,8 @@ module Masks
         return passthrough(env, e) if @optional && e.is_a?(Unauthenticated)
 
         refuse(resource(env), e)
+      rescue ReplayUnavailable
+        unavailable
       end
 
       private
@@ -56,6 +58,12 @@ module Masks
           @resource.respond_to?(:call) ? @resource.call(env) : @resource
         end
 
+        def unavailable
+          body = JSON.generate({ "error" => "temporarily_unavailable", "error_description" => "the token could not be checked" })
+
+          [ 503, { "content-type" => "application/json", "cache-control" => "no-store" }, [ body ] ]
+        end
+
         def refuse(resource, error)
           body = JSON.generate(
             { "error" => error.code, "error_description" => error.description }.compact

data/lib/masks/client/registration.rb

@@ -6,31 +6,41 @@ module Masks
       def self.create(issuer, token: nil, **attributes)
         issuer = Issuer.resolve(issuer)
         headers = token ? { "Authorization" => "Bearer #{token}" } : {}
-        body = HTTP.post_json(
-          issuer.endpoint("registration_endpoint"), stringify(attributes), headers
-        )
+        body = HTTP.post_json(endpoint(issuer, token), stringify(attributes), headers)
 
         new(issuer, body)
       end
 
+      def self.endpoint(issuer, token)
+        return issuer.endpoint("registration_endpoint") if token.nil? || issuer.discovery["registration_endpoint"]
+
+        "#{issuer.url}/register"
+      end
+
       def self.stringify(attributes)
         {
           "client_name" => attributes[:name] || attributes[:client_name],
           "redirect_uris" => Array(attributes[:redirect_uris]),
-          "grant_types" => fallback(attributes[:grant_types], %w[authorization_code]),
-          "response_types" => fallback(attributes[:response_types], %w[code]),
+          "grant_types" => Array(attributes[:grant_types]),
+          "response_types" => Array(attributes[:response_types]),
           "scope" => Array(attributes[:scope]).join(" "),
           "token_endpoint_auth_method" => attributes[:token_endpoint_auth_method],
           "application_type" => attributes[:application_type],
           "client_uri" => attributes[:client_uri],
           "logo_uri" => attributes[:logo_uri],
-          "backchannel_logout_uri" => attributes[:backchannel_logout_uri]
+          "backchannel_logout_uri" => attributes[:backchannel_logout_uri],
+          "jwks" => keyset(attributes[:jwks]),
+          "dpop_bound_access_tokens" => attributes[:dpop_bound_access_tokens]
         }.reject { |_, value| value.nil? || (value.respond_to?(:empty?) && value.empty?) }
       end
 
-      def self.fallback(value, default)
-        list = Array(value)
-        list.empty? ? default : list
+      def self.keyset(value)
+        case value
+        when nil then nil
+        when Key then value.jwks
+        when Array then { "keys" => value.map { |key| key.is_a?(Key) ? key.public_jwk : key } }
+        else value
+        end
       end
 
       def self.held(issuer, credentials)
@@ -62,18 +72,18 @@ module Masks
       GONE = (REFUSED + [ 404 ]).freeze
 
       def read
-        still_ours(REFUSED) { HTTP.get(uri, authorization) }
+        still_ours(REFUSED) { HTTP.get(owned, authorization) }
       end
 
       def update(**attributes)
         @metadata = metadata.merge(
-          still_ours(REFUSED) { HTTP.put_json(uri, self.class.stringify(attributes), authorization) }
+          still_ours(REFUSED) { HTTP.put_json(owned, self.class.stringify(attributes), authorization) }
         )
         self
       end
 
       def delete
-        still_ours(GONE) { HTTP.delete(uri, authorization) }
+        still_ours(GONE) { HTTP.delete(owned, authorization) }
         true
       end
 
@@ -88,18 +98,25 @@ module Masks
         { "Authorization" => "Bearer #{access_token}" }
       end
 
-      def session(redirect_uri:, scope: Session::DEFAULT_SCOPE)
+      def session(redirect_uri: nil, scope: Session::DEFAULT_SCOPE, **options)
         Session.new(
           issuer: issuer,
           client_id: client_id,
-          client_secret: client_secret,
+          client_secret: (client_secret unless options[:private_key]),
           redirect_uri: redirect_uri,
-          scope: scope
+          scope: scope,
+          **options
         )
       end
 
       private
 
+        def owned
+          return uri if Nonces.origin(uri) == Nonces.origin(issuer.url)
+
+          raise Foreign, "the registration names #{Nonces.origin(uri)}, which is not #{issuer.url}"
+        end
+
         def still_ours(statuses)
           yield
         rescue Unregistered

data/lib/masks/client/session.rb

@@ -13,17 +13,21 @@ module Masks
       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
+      NO_NONCE = "use_dpop_nonce".freeze
+
+      attr_reader :issuer, :client_id, :client_secret, :redirect_uri, :scope, :private_key, :key_id, :dpop
 
       def initialize(issuer:, client_id:, redirect_uri: nil, client_secret: nil, private_key: nil, key_id: nil,
-                     scope: DEFAULT_SCOPE)
+                     dpop: nil, scope: DEFAULT_SCOPE)
         raise ArgumentError, "a client authenticates with a secret or a private key, not both" if client_secret && private_key
 
         @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
+        @private_key = private_key.is_a?(Key) ? private_key.private_key : private_key
+        @private_key = OpenSSL::PKey.read(@private_key) if @private_key.is_a?(String)
+        @key_id = key_id || (private_key.thumbprint if private_key.is_a?(Key))
+        @dpop = dpop && Key.from(dpop)
         @redirect_uri = redirect_uri
         @scope = Array(scope)
       end
@@ -71,7 +75,7 @@ module Masks
 
         Array(resource).each { |value| form << [ "resource", value ] }
 
-        Tokens.granted(post("token_endpoint", form))
+        token(form)
       end
 
       def client_credentials(scope: nil, resource: nil)
@@ -80,7 +84,23 @@ module Masks
         form << [ "scope", Array(scope).join(" ") ] if scope
         Array(resource).each { |value| form << [ "resource", value ] }
 
-        Tokens.granted(post("token_endpoint", form))
+        token(form)
+      end
+
+      def enroll(scope:, name: nil, expires_in: nil)
+        form = [ [ "client_id", client_id ], [ "scope", Array(scope).join(" ") ] ]
+
+        form << [ "client_name", name ] if name
+        form << [ "expires_in", expires_in.to_i ] if expires_in
+
+        Enrollment.issued(post("enrollment_endpoint", form))
+      end
+
+      def unenroll(machine_id)
+        url = "#{issuer.endpoint('enrollment_endpoint')}/#{URI.encode_www_form_component(machine_id)}"
+
+        HTTP.delete_form(url, [ [ "client_id", client_id ] ] + assertion, authorization)
+        true
       end
 
       def refresh(refresh_token, resource: nil, scope: nil)
@@ -93,7 +113,7 @@ module Masks
         form << [ "scope", Array(scope).join(" ") ] if scope
         Array(resource).each { |value| form << [ "resource", value ] }
 
-        Tokens.granted(post("token_endpoint", form))
+        token(form)
       end
 
       def exchange(subject_token, scope: nil, resource: nil, lifetime: nil, requested_token_type: nil, audience: nil,
@@ -114,7 +134,46 @@ module Masks
         form << [ "requested_lifetime", lifetime.to_i ] if lifetime
         Array(resource).each { |value| form << [ "resource", value ] }
 
-        Tokens.granted(post("token_endpoint", form))
+        token(form)
+      end
+
+      def device_authorization(scope: nil, resource: nil)
+        form = [ [ "client_id", client_id ] ]
+
+        form << [ "scope", Array(scope).join(" ") ] if scope
+        Array(resource).each { |value| form << [ "resource", value ] }
+
+        Device.issued(post("device_authorization_endpoint", form))
+      end
+
+      def await_device(device, pause: Device::INTERVAL)
+        form = [ [ "grant_type", Device::GRANT_TYPE ], [ "device_code", device.device_code ], [ "client_id", client_id ] ]
+        interval = device.interval.positive? ? device.interval : pause
+
+        loop do
+          raise Rejected.new("expired_token", "the code expired before anyone approved it") if device.expired?
+
+          sleep(interval)
+
+          begin
+            return token(form)
+          rescue Rejected => e
+            case e.code
+            when "authorization_pending" then next
+            when "slow_down" then interval += pause
+            else raise
+            end
+          end
+        end
+      end
+
+      def transport(*origins, tokens: nil, scope: nil, resource: nil, &keep)
+        Transport.new(*origins, tokens: tokens, key: dpop) do |held|
+          renewed = tokens ? renew(held, scope: scope, resource: resource) : client_credentials(scope: scope, resource: resource)
+
+          keep&.call(renewed)
+          renewed
+        end
       end
 
       def revoke(token, hint: nil)
@@ -147,8 +206,13 @@ module Masks
         )
       end
 
-      def userinfo(access_token)
-        HTTP.get(issuer.endpoint("userinfo_endpoint"), "Authorization" => "Bearer #{access_token}")
+      def userinfo(tokens)
+        url = issuer.endpoint("userinfo_endpoint")
+
+        return HTTP.get(url, "Authorization" => "Bearer #{tokens}") unless tokens.is_a?(Tokens)
+        return HTTP.get(url, "Authorization" => "Bearer #{tokens.access_token}") unless tokens.bound?
+
+        HTTP.parse(Transport.new(url, tokens: tokens, key: dpop).request("GET", url, limit: HTTP::READ_LIMIT))
       end
 
       def identity(tokens)
@@ -162,19 +226,64 @@ module Masks
       def profile(tokens)
         return {} if tokens.access_token.nil?
 
-        userinfo(tokens.access_token)
+        userinfo(tokens)
       rescue Masks::Client::Error
         {}
       end
 
       private
 
+        def renew(held, scope:, resource:)
+          if held&.refresh_token.to_s.empty?
+            raise Rejected.new("invalid_grant", "there is no refresh token to renew these tokens with")
+          end
+
+          renewed = refresh(held.refresh_token, scope: scope, resource: resource)
+
+          return renewed if renewed.refresh_token
+
+          Tokens.from_h(renewed.to_h.merge("refresh_token" => held.refresh_token))
+        end
+
+        def token(form)
+          tokens = Tokens.granted(dpop ? proven(issuer.endpoint("token_endpoint"), form) : post("token_endpoint", form))
+
+          if dpop && !tokens.bound?
+            raise Rejected.new("invalid_dpop_proof", "the token endpoint answered with a token that is not held to this key")
+          end
+
+          tokens
+        end
+
         def post(endpoint, form)
           url = issuer.endpoint(endpoint)
 
           HTTP.post_form(url, form + assertion, authorization)
         end
 
+        def proven(url, form)
+          nonce = issuer.nonces[url]
+          response = HTTP.deliver(proven_request(url, form, nonce))
+          wanted = issuer.nonces.learn(url, response)
+
+          begin
+            HTTP.parse(response)
+          rescue Rejected => e
+            raise unless e.code == NO_NONCE && wanted && wanted != nonce
+
+            response = HTTP.deliver(proven_request(url, form, wanted))
+            issuer.nonces.learn(url, response)
+
+            HTTP.parse(response)
+          end
+        end
+
+        def proven_request(url, form, nonce)
+          headers = authorization.merge("DPoP" => dpop.proof("POST", url, nonce: nonce))
+
+          HTTP.form_request(Net::HTTP::Post, url, form + assertion, headers)
+        end
+
         def assertion
           return [] if private_key.nil?
 

data/lib/masks/client/tokens.rb

@@ -44,6 +44,10 @@ module Masks
         scope.split(/\s+/).reject(&:empty?)
       end
 
+      def bound?
+        token_type.to_s.casecmp?(Proof::SCHEME)
+      end
+
       def authorization
         "#{token_type} #{access_token}"
       end

data/lib/masks/client/transport.rb

@@ -0,0 +1,114 @@
+module Masks
+  module Client
+    class Transport
+      VERBS = {
+        "GET" => Net::HTTP::Get, "HEAD" => Net::HTTP::Head, "POST" => Net::HTTP::Post, "PUT" => Net::HTTP::Put,
+        "PATCH" => Net::HTTP::Patch, "DELETE" => Net::HTTP::Delete
+      }.freeze
+
+      attr_reader :origins, :key
+
+      def initialize(*origins, tokens: nil, key: nil, &renew)
+        raise ArgumentError, "a transport needs the origins it may send its tokens to" if origins.empty?
+        raise ArgumentError, "a transport needs tokens or a way to fetch them" if tokens.nil? && renew.nil?
+
+        @origins = origins.flatten.map { |origin| Nonces.origin(HTTP.checked(URI.parse(origin.to_s))) }.uniq.freeze
+        @tokens = tokens
+        @key = key && Key.from(key)
+        @renew = renew
+        @lock = Mutex.new
+        @nonces = Nonces.new
+      end
+
+      def tokens
+        @lock.synchronize do
+          @tokens = @renew.call(@tokens) if @renew && (@tokens.nil? || @tokens.expired?)
+          @tokens
+        end
+      end
+
+      def get(url, headers: {})
+        request("GET", url, headers: headers)
+      end
+
+      def head(url, headers: {})
+        request("HEAD", url, headers: headers)
+      end
+
+      def delete(url, headers: {})
+        request("DELETE", url, headers: headers)
+      end
+
+      def post(url, body: nil, headers: {})
+        request("POST", url, body: body, headers: headers)
+      end
+
+      def put(url, body: nil, headers: {})
+        request("PUT", url, body: body, headers: headers)
+      end
+
+      def patch(url, body: nil, headers: {})
+        request("PATCH", url, body: body, headers: headers)
+      end
+
+      def request(method, url, body: nil, headers: {}, limit: nil)
+        uri = URI.parse(url.to_s)
+        verb = VERBS.fetch(method.to_s.upcase) { raise ArgumentError, "#{method} is not a method a transport sends" }
+
+        unless origins.include?(Nonces.origin(uri))
+          raise Foreign, "this transport holds tokens only for #{origins.join(', ')}"
+        end
+
+        held = tokens
+        nonce = @nonces[uri] if held.bound?
+        response = HTTP.deliver(signed(verb, uri, body, headers, held, nonce), limit: limit)
+
+        return response unless held.bound?
+
+        wanted = @nonces.learn(uri, response)
+
+        return response unless wanted && wanted != nonce && nonce_asked?(response)
+
+        HTTP.deliver(signed(verb, uri, body, headers, held, wanted), limit: limit)
+      end
+
+      def inspect
+        "#<#{self.class.name} #{origins.join(', ')}>"
+      end
+
+      private
+
+        def signed(verb, uri, body, headers, held, nonce)
+          request = verb.new(uri, HTTP.default_headers.merge(headers))
+
+          if held.bound?
+            raise Error, "a DPoP token needs the key it is held to" if key.nil?
+
+            request["Authorization"] = "#{Proof::SCHEME} #{held.access_token}"
+            request["DPoP"] = key.proof(request.method, uri, access_token: held.access_token, nonce: nonce)
+          else
+            request["Authorization"] = "Bearer #{held.access_token}"
+          end
+
+          written(request, body)
+        end
+
+        def written(request, body)
+          return request if body.nil?
+
+          if body.is_a?(String)
+            request.body = body
+          else
+            request.body = JSON.generate(body)
+            request["Content-Type"] ||= "application/json"
+          end
+
+          request
+        end
+
+        def nonce_asked?(response)
+          response.code.to_i == 401 && response["WWW-Authenticate"].to_s.include?("use_dpop_nonce")
+        end
+    end
+  end
+end

data/lib/masks/client.rb

@@ -1,4 +1,5 @@
 require "base64"
+require "ipaddr"
 require "json"
 require "jwt"
 require "net/http"
@@ -9,14 +10,20 @@ require "uri"
 require_relative "version"
 require_relative "client/errors"
 require_relative "client/http"
+require_relative "client/embedded"
 require_relative "client/pkce"
 require_relative "client/stores"
 require_relative "client/tracker"
+require_relative "client/nonces"
+require_relative "client/key"
 require_relative "client/issuer"
 require_relative "client/registry"
 require_relative "client/tokens"
 require_relative "client/claims"
 require_relative "client/introspection"
+require_relative "client/enrollment"
+require_relative "client/device"
+require_relative "client/transport"
 require_relative "client/session"
 require_relative "client/verifier"
 require_relative "client/proof"
@@ -44,6 +51,20 @@ module Masks
   # state of its own beyond the discovery cache in ::registry.
   module Client
     class << self
+      attr_writer :plain_http
+
+      def plain_http?
+        @plain_http == true
+      end
+
+      def embed(app, &serves)
+        @embedded = app && Embedded.new(app, &serves)
+      end
+
+      def embedded_for(uri)
+        @embedded if @embedded&.serves?(uri)
+      end
+
       # The process-wide cache of resolved issuers, so discovery is fetched
       # once rather than per request.
       #