masks 0.5.0 → 0.7.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/errors.rb

@@ -16,6 +16,14 @@ module Masks
       end
     end
 
+    class Unregistered < Rejected
+      CODE = "invalid_client".freeze
+
+      def self.raised_by?(body)
+        body["error"].to_s == CODE
+      end
+    end
+
     class InvalidToken < Error; end
 
     class Challenge < Error

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/http.rb

@@ -31,6 +31,19 @@ module Masks
         request(Net::HTTP::Delete.new(URI.parse(url.to_s), default_headers.merge(headers)))
       end
 
+      def fetch(url, headers = {})
+        uri = URI.parse(url.to_s)
+
+        Net::HTTP.start(
+          uri.hostname, uri.port,
+          use_ssl: uri.scheme == "https",
+          open_timeout: OPEN_TIMEOUT,
+          read_timeout: READ_TIMEOUT
+        ) { |http| http.request(Net::HTTP::Get.new(uri, headers)) }
+      rescue SystemCallError, SocketError, Net::OpenTimeout, Net::ReadTimeout, OpenSSL::SSL::SSLError => e
+        raise Unreachable, "#{uri.host} is unreachable (#{e.class})"
+      end
+
       def json(verb, url, body, headers)
         uri = URI.parse(url.to_s)
         request = verb.new(uri, default_headers.merge(headers))
@@ -67,7 +80,9 @@ module Masks
         end
 
         unless response.is_a?(Net::HTTPSuccess)
-          raise Rejected.new(
+          refusal = Unregistered.raised_by?(body) ? Unregistered : Rejected
+
+          raise refusal.new(
             body["error"] || "http_#{response.code}",
             body["error_description"] || response.message,
             status: response.code.to_i

data/lib/masks/client/introspection.rb

@@ -5,7 +5,7 @@ module Masks
         to_h["active"] == true
       end
 
-      def username
+      def nickname
         self["username"]
       end
 

data/lib/masks/client/issuer.rb

@@ -51,6 +51,26 @@ 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
+
+      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

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])
+
+          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?
@@ -59,18 +58,30 @@ module Masks
         metadata["registration_client_uri"]
       end
 
+      REFUSED = [ 401, 403 ].freeze
+      GONE = (REFUSED + [ 404 ]).freeze
+
       def read
-        HTTP.get(uri, authorization)
+        still_ours(REFUSED) { HTTP.get(uri, authorization) }
       end
 
       def update(**attributes)
-        @metadata = metadata.merge(HTTP.put_json(uri, self.class.stringify(attributes), authorization))
+        @metadata = metadata.merge(
+          still_ours(REFUSED) { HTTP.put_json(uri, self.class.stringify(attributes), authorization) }
+        )
         self
       end
 
       def delete
-        HTTP.delete(uri, authorization)
+        still_ours(GONE) { HTTP.delete(uri, authorization) }
+        true
+      end
+
+      def known?
+        read
         true
+      rescue Unregistered
+        false
       end
 
       def authorization
@@ -86,6 +97,18 @@ module Masks
           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/session.rb

@@ -14,7 +14,7 @@ module Masks
       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)
         pkce = Pkce.generate
         scopes = Array(scope || self.scope)
         nonce = nil unless scopes.include?("openid")
@@ -33,6 +33,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
 
         {
           url: "#{issuer.endpoint('authorization_endpoint')}?#{URI.encode_www_form(pairs)}",
@@ -69,7 +70,7 @@ module Masks
         Tokens.granted(HTTP.post_form(issuer.endpoint("token_endpoint"), form, authorization))
       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)
         form = [
           [ "grant_type", Tokens::EXCHANGE ],
           [ "client_id", client_id ],
@@ -77,6 +78,9 @@ module Masks
           [ "subject_token_type", Tokens::ACCESS_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 ] }
@@ -92,6 +96,10 @@ module Masks
         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

data/lib/masks/client/tokens.rb

@@ -4,7 +4,8 @@ module Masks
       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
+      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 +27,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.rb

@@ -19,33 +19,79 @@ require_relative "client/claims"
 require_relative "client/introspection"
 require_relative "client/session"
 require_relative "client/verifier"
+require_relative "client/logout"
 require_relative "client/resource"
 require_relative "client/rack"
 require_relative "client/registration"
 require_relative "client/handshake"
+require_relative "client/delegations"
 
 module Masks
+  # = Masks::Client
+  #
+  # The protocol half of the gem: plain Ruby, no \Rails, no database. Every
+  # entry point here is a class method that builds one of the objects below.
+  #
+  # Which one you want depends on what the application is doing:
+  #
+  # [issuer]    an app signing people in — discovery, PKCE, the code exchange
+  # [verifier]  an API checking a bearer it was handed
+  # [resource]  an API publishing what it is and which scopes it takes
+  # [handshake] an app registering itself, once, without a copied secret
+  #
+  # Everything reachable from here talks HTTP to a masks issuer and holds no
+  # state of its own beyond the discovery cache in ::registry.
   module Client
     class << self
+      # The process-wide cache of resolved issuers, so discovery is fetched
+      # once rather than per request.
+      #
+      # @return [Masks::Client::Registry]
       def registry
         @registry ||= Registry.new
       end
 
+      # Resolves +url+ through its discovery document and returns the issuer
+      # it describes. Cached in ::registry, so calling this per request is
+      # cheap after the first.
+      #
+      #   issuer = Masks::Client.issuer("https://auth.example")
+      #   issuer.authorization_url(client_id: id, redirect_uri: uri)
+      #
+      # @return [Masks::Client::Issuer]
       def issuer(url, **options)
         Issuer.resolve(url, **options)
       end
 
+      # Checks tokens minted by the issuer at +url+ against +audience+ — the
+      # API's own URL, which the token names in +aud+. A token issued for
+      # anything else is refused rather than merely noted.
+      #
+      # @return [Masks::Client::Verifier]
       def verifier(url, audience:, **options)
         Verifier.new(issuer(url), audience: audience, **options)
       end
 
+      # Describes this API to callers: the scopes it accepts and the issuer
+      # that may mint tokens for it, served as RFC 9728 metadata.
+      #
+      # @return [Masks::Client::Resource]
       def resource(url, issuer:, **options)
         Resource.new(issuer: issuer, url: url, **options)
       end
 
+      # Registers this application against a masks issuer. A person approves
+      # it in their browser and the credentials come back server to server, so
+      # no secret is pasted between the two.
+      #
+      # @return [Masks::Client::Handshake]
       def handshake(url, **options)
         Handshake.new(url, **options)
       end
+
+      def delegations(issuer, **options)
+        Delegations.new(issuer: issuer, **options)
+      end
     end
   end
 end