masks 0.4.0 → 0.6.0

data/lib/masks/client/issuer.rb

@@ -0,0 +1,92 @@
+module Masks
+  module Client
+    class Issuer
+      DISCOVERY_PATH = "/.well-known/openid-configuration".freeze
+      TTL = 300
+
+      def self.normalize(url)
+        url.to_s.chomp("/")
+      end
+
+      def self.resolve(issuer, ttl: TTL)
+        return issuer if issuer.is_a?(self)
+
+        Masks::Client.registry[issuer, ttl: ttl]
+      end
+
+      attr_reader :url
+
+      def initialize(url, ttl: TTL)
+        @url = self.class.normalize(url)
+        @ttl = ttl
+        @cache = {}
+        @lock = Mutex.new
+      end
+
+      def discovery
+        fetch(:discovery) do
+          document = HTTP.get("#{url}#{DISCOVERY_PATH}")
+          named = self.class.normalize(document["issuer"])
+
+          unless named == url
+            raise Rejected.new(
+              "invalid_issuer",
+              "#{url} publishes a document naming #{document['issuer'].inspect}"
+            )
+          end
+
+          document
+        end
+      end
+
+      def jwks
+        fetch(:jwks) { HTTP.get(endpoint("jwks_uri")) }
+      end
+
+      def tenant
+        discovery["tenant"]
+      end
+
+      def endpoint(name)
+        discovery.fetch(name) { raise Rejected.new("invalid_issuer", "#{url} publishes no #{name}") }
+      end
+
+      def avatar_styles
+        discovery["avatar_styles_supported"] || Claims::Avatars::STYLES
+      end
+
+      def avatar_url(subject, style: nil, size: nil)
+        wanted = (style || Claims::Avatars::FALLBACK).to_s
+
+        unless avatar_styles.include?(wanted)
+          raise Rejected.new("invalid_style", "#{url} does not serve #{wanted} avatars")
+        end
+
+        query = size ? "?size=#{size.to_i}" : ""
+
+        "#{endpoint('avatar_endpoint')}/#{subject}/#{wanted}#{query}"
+      end
+
+      def refresh!
+        @lock.synchronize { @cache = {} }
+        self
+      end
+
+      private
+
+        def fetch(key)
+          cached = @lock.synchronize { @cache[key] }
+          return cached[:value] if fresh?(cached)
+
+          value = yield
+
+          @lock.synchronize { @cache[key] = { value: value, at: Time.now.to_i } }
+          value
+        end
+
+        def fresh?(entry)
+          entry && entry[:at] + @ttl > Time.now.to_i
+        end
+    end
+  end
+end

data/lib/masks/client/pkce.rb

@@ -0,0 +1,27 @@
+module Masks
+  module Client
+    class Pkce
+      METHOD = "S256".freeze
+
+      attr_reader :verifier
+
+      def self.generate
+        new(SecureRandom.urlsafe_base64(64))
+      end
+
+      def initialize(verifier)
+        @verifier = verifier
+      end
+
+      def challenge
+        Base64.urlsafe_encode64(
+          OpenSSL::Digest::SHA256.digest(verifier), padding: false
+        )
+      end
+
+      def method
+        METHOD
+      end
+    end
+  end
+end

data/lib/masks/client/rack.rb

@@ -0,0 +1,62 @@
+module Masks
+  module Client
+    class Rack
+      CLAIMS = "masks.claims".freeze
+      ERROR = "masks.error".freeze
+
+      def initialize(app, resource:, scope: nil, only: nil, optional: false)
+        @app = app
+        @resource = resource
+        @scope = scope
+        @only = only
+        @optional = optional
+      end
+
+      def call(env)
+        return @app.call(env) unless guards?(env)
+
+        env[CLAIMS] = resource(env).authenticate(env["HTTP_AUTHORIZATION"], scope: @scope)
+
+        @app.call(env)
+      rescue Challenge => e
+        return passthrough(env, e) if @optional && e.is_a?(Unauthenticated)
+
+        refuse(resource(env), e)
+      end
+
+      private
+
+        def guards?(env)
+          return true if @only.nil?
+
+          @only.call(env)
+        end
+
+        def passthrough(env, error)
+          env[ERROR] = error
+
+          @app.call(env)
+        end
+
+        def resource(env)
+          @resource.respond_to?(:call) ? @resource.call(env) : @resource
+        end
+
+        def refuse(resource, error)
+          body = JSON.generate(
+            { "error" => error.code, "error_description" => error.description }.compact
+          )
+
+          [
+            error.status,
+            {
+              "content-type" => "application/json",
+              "cache-control" => "no-store",
+              "www-authenticate" => resource.challenge(error)
+            },
+            [ body ]
+          ]
+        end
+    end
+  end
+end

data/lib/masks/client/registration.rb

@@ -0,0 +1,115 @@
+module Masks
+  module Client
+    class Registration
+      attr_reader :issuer, :metadata, :access_token
+
+      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
+        )
+
+        new(issuer, body)
+      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]),
+          "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]
+        }.reject { |_, value| value.nil? || (value.respond_to?(:empty?) && value.empty?) }
+      end
+
+      def self.fallback(value, default)
+        list = Array(value)
+        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?
+
+        new(Issuer.resolve(issuer), held)
+      end
+
+      def initialize(issuer, body)
+        @issuer = issuer
+        @metadata = body
+        @access_token = body["registration_access_token"]
+      end
+
+      def client_id
+        metadata["client_id"]
+      end
+
+      def client_secret
+        metadata["client_secret"]
+      end
+
+      def uri
+        metadata["registration_client_uri"]
+      end
+
+      REFUSED = [ 401, 403 ].freeze
+      GONE = (REFUSED + [ 404 ]).freeze
+
+      def read
+        still_ours(REFUSED) { HTTP.get(uri, authorization) }
+      end
+
+      def update(**attributes)
+        @metadata = metadata.merge(
+          still_ours(REFUSED) { HTTP.put_json(uri, self.class.stringify(attributes), authorization) }
+        )
+        self
+      end
+
+      def delete
+        still_ours(GONE) { HTTP.delete(uri, authorization) }
+        true
+      end
+
+      def known?
+        read
+        true
+      rescue Unregistered
+        false
+      end
+
+      def authorization
+        { "Authorization" => "Bearer #{access_token}" }
+      end
+
+      def session(redirect_uri:, scope: Session::DEFAULT_SCOPE)
+        Session.new(
+          issuer: issuer,
+          client_id: client_id,
+          client_secret: client_secret,
+          redirect_uri: redirect_uri,
+          scope: scope
+        )
+      end
+
+      private
+
+        def still_ours(statuses)
+          yield
+        rescue Unregistered
+          raise
+        rescue Rejected => e
+          raise unless statuses.include?(e.status)
+
+          raise Unregistered.new(Unregistered::CODE, e.description, status: e.status)
+        end
+    end
+  end
+end

data/lib/masks/client/registry.rb

@@ -0,0 +1,25 @@
+module Masks
+  module Client
+    class Registry
+      def initialize
+        @issuers = {}
+        @lock = Mutex.new
+      end
+
+      def [](url, ttl: Issuer::TTL)
+        key = Issuer.normalize(url)
+
+        @lock.synchronize { @issuers[key] ||= Issuer.new(key, ttl: ttl) }
+      end
+
+      def clear!
+        @lock.synchronize { @issuers.clear }
+        self
+      end
+
+      def urls
+        @lock.synchronize { @issuers.keys }
+      end
+    end
+  end
+end

data/lib/masks/client/resource.rb

@@ -0,0 +1,92 @@
+module Masks
+  module Client
+    class Resource
+      BEARER = /\ABearer[ \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)
+        @issuer = Issuer.resolve(issuer)
+        @url = url.to_s
+        @descriptions = describe(scopes)
+        @scopes = (@descriptions.any? ? @descriptions.keys : Array(scopes).map(&:to_s)).freeze
+        @metadata_url = metadata_url
+        @required = Array(required)
+        @verifier = verifier || Verifier.new(@issuer, audience: @url, algorithms: algorithms)
+      end
+
+      def authenticate(authorization, scope: nil)
+        claims = Claims.new(@verifier.verify(token!(authorization), required: @required))
+
+        Array(scope).each { |name| claims.permit!(name) }
+
+        claims
+      rescue InvalidToken => e
+        raise Unauthorized.new(e.message)
+      end
+
+      def token(authorization)
+        authorization.to_s[BEARER, 1]
+      end
+
+      def metadata_url
+        @metadata_url ||= "#{origin}#{METADATA_PATH}"
+      end
+
+      def metadata
+        {
+          "resource" => url,
+          "authorization_servers" => [ issuer.url ],
+          "scopes_supported" => scopes,
+          "scope_descriptions" => @descriptions,
+          "bearer_methods_supported" => [ "header" ]
+        }.reject { |_, value| value.respond_to?(:empty?) && value.empty? }
+      end
+
+      def challenge(error = nil)
+        error = Unauthorized.new(error.to_s) unless error.is_a?(Challenge)
+
+        parameters = [
+          [ "error", error.code ],
+          [ "error_description", error.description ],
+          [ "scope", error.scope || (scopes.join(" ") if scopes.any?) ],
+          [ "resource_metadata", metadata_url ]
+        ]
+
+        "Bearer " + parameters.filter_map { |name, value|
+          %(#{name}="#{quote(value)}") if value && !value.to_s.empty?
+        }.join(", ")
+      end
+
+      private
+
+        def describe(scopes)
+          return {} unless scopes.is_a?(Hash)
+
+          scopes.each_with_object({}) do |(scope, description), held|
+            held[scope.to_s] = description.to_s
+          end.freeze
+        end
+
+        def token!(authorization)
+          token(authorization) || raise(Unauthenticated.new)
+        end
+
+        def origin
+          uri = URI.parse(url)
+          port = ":#{uri.port}" unless uri.port.nil? || uri.default_port == uri.port
+
+          "#{uri.scheme}://#{uri.host}#{port}"
+        rescue URI::InvalidURIError
+          url
+        end
+
+        def quote(value)
+          value.to_s.gsub(/[\\"]/, " ").gsub(/[[:cntrl:]]/, " ").strip
+        end
+    end
+  end
+end

data/lib/masks/client/session.rb

@@ -0,0 +1,146 @@
+module Masks
+  module Client
+    class Session
+      DEFAULT_SCOPE = %w[openid profile email].freeze
+
+      attr_reader :issuer, :client_id, :client_secret, :redirect_uri, :scope
+
+      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
+        @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))
+        pkce = Pkce.generate
+        scopes = Array(scope || self.scope)
+        nonce = nil unless scopes.include?("openid")
+
+        pairs = [
+          [ "response_type", "code" ],
+          [ "client_id", client_id ],
+          [ "redirect_uri", redirect_uri ],
+          [ "scope", scopes.join(" ") ],
+          [ "state", state ],
+          [ "code_challenge", pkce.challenge ],
+          [ "code_challenge_method", pkce.method ]
+        ]
+
+        pairs << [ "nonce", nonce ] if nonce
+
+        Array(resource).each { |value| pairs << [ "resource", value ] }
+        pairs << [ "prompt", prompt ] if prompt
+
+        {
+          url: "#{issuer.endpoint('authorization_endpoint')}?#{URI.encode_www_form(pairs)}",
+          state: state,
+          nonce: nonce,
+          verifier: pkce.verifier
+        }
+      end
+
+      def complete(code:, verifier:, resource: nil)
+        form = [
+          [ "grant_type", "authorization_code" ],
+          [ "code", code ],
+          [ "client_id", client_id ],
+          [ "redirect_uri", redirect_uri ],
+          [ "code_verifier", verifier ]
+        ]
+
+        Array(resource).each { |value| form << [ "resource", value ] }
+
+        Tokens.granted(HTTP.post_form(issuer.endpoint("token_endpoint"), form, authorization))
+      end
+
+      def refresh(refresh_token, resource: nil, scope: nil)
+        form = [
+          [ "grant_type", "refresh_token" ],
+          [ "refresh_token", refresh_token ],
+          [ "client_id", client_id ]
+        ]
+
+        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))
+      end
+
+      def exchange(subject_token, scope: nil, resource: nil, lifetime: nil)
+        form = [
+          [ "grant_type", Tokens::EXCHANGE ],
+          [ "client_id", client_id ],
+          [ "subject_token", subject_token ],
+          [ "subject_token_type", Tokens::ACCESS_TOKEN ]
+        ]
+
+        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))
+      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)
+        true
+      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
+        pairs << [ "post_logout_redirect_uri", post_logout_redirect_uri ] if post_logout_redirect_uri
+        pairs << [ "state", state ] if state
+
+        "#{issuer.endpoint('end_session_endpoint')}?#{URI.encode_www_form(pairs)}"
+      end
+
+      def introspect(token, hint: nil)
+        form = [ [ "token", token ], [ "client_id", client_id ] ]
+        form << [ "token_type_hint", hint ] if hint
+
+        Introspection.new(
+          HTTP.post_form(issuer.endpoint("introspection_endpoint"), form, authorization)
+        )
+      end
+
+      def userinfo(access_token)
+        HTTP.get(issuer.endpoint("userinfo_endpoint"), "Authorization" => "Bearer #{access_token}")
+      end
+
+      def identity(tokens)
+        return nil if tokens.id_token.nil?
+
+        claims = Verifier.new(issuer, audience: client_id).verify(tokens.id_token)
+
+        profile(tokens).merge(claims)
+      end
+
+      def profile(tokens)
+        return {} if tokens.access_token.nil?
+
+        userinfo(tokens.access_token)
+      rescue Masks::Client::Error
+        {}
+      end
+
+      private
+
+        def authorization
+          return {} if client_secret.nil?
+
+          encoded = Base64.strict_encode64(
+            "#{URI.encode_www_form_component(client_id)}:#{URI.encode_www_form_component(client_secret)}"
+          )
+
+          { "Authorization" => "Basic #{encoded}" }
+        end
+    end
+  end
+end

data/lib/masks/client/stores.rb

@@ -0,0 +1,40 @@
+module Masks
+  module Client
+    module Stores
+      class Memory
+        attr_reader :held
+
+        def initialize(held = {})
+          @held = held
+        end
+
+        def read
+          held
+        end
+
+        def write(value)
+          @held = value
+        end
+      end
+
+      class Session
+        def initialize(session, key)
+          @session = session
+          @key = key
+        end
+
+        def read
+          @session[@key]
+        end
+
+        def write(value)
+          if value.empty?
+            @session.delete(@key)
+          else
+            @session[@key] = value
+          end
+        end
+      end
+    end
+  end
+end

data/lib/masks/client/tokens.rb

@@ -0,0 +1,70 @@
+module Masks
+  module Client
+    class Tokens
+      EXCHANGE = "urn:ietf:params:oauth:grant-type:token-exchange".freeze
+      ACCESS_TOKEN = "urn:ietf:params:oauth:token-type:access_token".freeze
+
+      attr_reader :access_token, :id_token, :refresh_token, :token_type, :scope, :expires_in, :obtained_at
+
+      def self.granted(body)
+        token = new(body)
+
+        if token.access_token.to_s.empty?
+          raise Rejected.new(
+            body["error"] || "invalid_token_response",
+            body["error_description"] || "the token endpoint answered without an access_token"
+          )
+        end
+
+        token
+      end
+
+      def initialize(body)
+        @access_token = body["access_token"]
+        @id_token = body["id_token"]
+        @refresh_token = body["refresh_token"]
+        @token_type = body["token_type"] || "Bearer"
+        @scope = body["scope"].to_s
+        @expires_in = body["expires_in"].to_i
+        @obtained_at = Time.now.to_i
+      end
+
+      def expires_at
+        obtained_at + expires_in
+      end
+
+      def expired?(leeway: 30)
+        Time.now.to_i + leeway >= expires_at
+      end
+
+      def scopes
+        scope.split(/\s+/).reject(&:empty?)
+      end
+
+      def authorization
+        "#{token_type} #{access_token}"
+      end
+
+      def to_h
+        {
+          "access_token" => access_token,
+          "id_token" => id_token,
+          "refresh_token" => refresh_token,
+          "token_type" => token_type,
+          "scope" => scope,
+          "expires_in" => expires_in,
+          "obtained_at" => obtained_at
+        }.compact
+      end
+
+      def self.from_h(data)
+        return nil if data.nil? || data.empty?
+
+        tokens = allocate
+        tokens.send(:initialize, data)
+        tokens.instance_variable_set(:@obtained_at, data["obtained_at"] || Time.now.to_i)
+        tokens
+      end
+    end
+  end
+end