masks 0.3.2 → 0.5.0

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,91 @@
+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
+
+      def read
+        HTTP.get(uri, authorization)
+      end
+
+      def update(**attributes)
+        @metadata = metadata.merge(HTTP.put_json(uri, self.class.stringify(attributes), authorization))
+        self
+      end
+
+      def delete
+        HTTP.delete(uri, authorization)
+        true
+      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
+    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

data/lib/masks/client/tracker.rb

@@ -0,0 +1,122 @@
+module Masks
+  module Client
+    class Tracker
+      TTL = 3600
+      LIMIT = 5
+
+      class Entry
+        attr_reader :id, :data, :opened_at, :expires_at
+
+        def self.from_h(id, held)
+          return nil unless held.is_a?(Hash)
+
+          new(
+            id: id,
+            data: held["data"] || {},
+            opened_at: held["opened_at"].to_f,
+            expires_at: held["expires_at"].to_f
+          )
+        end
+
+        def initialize(id:, data:, opened_at:, expires_at:)
+          @id = id
+          @data = data
+          @opened_at = opened_at
+          @expires_at = expires_at
+        end
+
+        def live?(now = Time.now.to_f)
+          expires_at > now
+        end
+
+        def [](key)
+          data[key.to_s]
+        end
+
+        def to_h
+          { "data" => data, "opened_at" => opened_at, "expires_at" => expires_at }
+        end
+      end
+
+      attr_reader :store, :ttl, :limit
+
+      def initialize(store, ttl: TTL, limit: LIMIT)
+        @store = store
+        @ttl = ttl
+        @limit = limit
+      end
+
+      def open(**data)
+        id = SecureRandom.urlsafe_base64(32)
+        now = Time.now.to_f
+
+        entry = Entry.new(
+          id: id,
+          data: data.transform_keys(&:to_s).compact,
+          opened_at: now,
+          expires_at: now + ttl
+        )
+
+        write(sweep.merge(id => entry.to_h))
+        entry
+      end
+
+      def amend(id, **data)
+        held = sweep
+        entry = Entry.from_h(id, held[id])
+        return nil if entry.nil?
+
+        merged = Entry.new(
+          id: id,
+          data: entry.data.merge(data.transform_keys(&:to_s).compact),
+          opened_at: entry.opened_at,
+          expires_at: entry.expires_at
+        )
+
+        write(held.merge(id => merged.to_h))
+        merged
+      end
+
+      def claim(id)
+        return nil if id.nil? || id.empty?
+
+        held = sweep
+        entry = Entry.from_h(id, held[id])
+        return nil if entry.nil? || !entry.live?
+
+        write(held.except(id))
+        entry
+      end
+
+      def clear!
+        write({})
+      end
+
+      def size
+        sweep.size
+      end
+
+      private
+
+        def sweep
+          now = Time.now.to_f
+
+          held = read.select do |id, value|
+            entry = Entry.from_h(id, value)
+            entry&.live?(now)
+          end
+
+          held.to_a.last(limit).to_h
+        end
+
+        def read
+          value = store.read
+          value.is_a?(Hash) ? value : {}
+        end
+
+        def write(held)
+          store.write(held)
+        end
+    end
+  end
+end

data/lib/masks/client/verifier.rb

@@ -0,0 +1,42 @@
+module Masks
+  module Client
+    class Verifier
+      ALGORITHMS = %w[RS256 ES256].freeze
+
+      attr_reader :issuer, :audience
+
+      def initialize(issuer, audience:, algorithms: ALGORITHMS)
+        @issuer = Issuer.resolve(issuer)
+        @audience = Array(audience)
+        @algorithms = algorithms
+      end
+
+      def verify(token, required: %w[iss sub exp])
+        JWT.decode(
+          token, nil, true,
+          algorithms: @algorithms,
+          jwks: keys,
+          iss: issuer.url, verify_iss: true,
+          aud: audience, verify_aud: true,
+          verify_expiration: true,
+          required_claims: required
+        ).first
+      rescue JWT::DecodeError => e
+        raise InvalidToken, e.message
+      end
+
+      def tenant(token)
+        verify(token)["tenant"]
+      end
+
+      private
+
+        def keys
+          ->(options) do
+            issuer.refresh! if options[:invalidate]
+            issuer.jwks
+          end
+        end
+    end
+  end
+end