masks 0.12.2 → 0.13.0

data/lib/masks/client/issuer.rb

@@ -2,7 +2,7 @@ module Masks
   module Client
     # One issuer's discovery document and keys, fetched once and kept for an
     # hour. While masks cannot be reached, the last good copies are served, a
-    # token signed with a key never seen raises Unreachable, and refetches back
+    # token signed with a key never seen raises Unavailable, and refetches back
     # off from 5 seconds to once a minute.
     class Issuer
       DISCOVERY_PATH = "/.well-known/openid-configuration".freeze
@@ -37,10 +37,7 @@ module Masks
           named = self.class.normalize(document["issuer"])
 
           unless named == url
-            raise Rejected.new(
-              "invalid_issuer",
-              "#{url} publishes a document naming #{document['issuer'].inspect}"
-            )
+            raise Refused.new(*Masks::Client.failure("names_another", url, document["issuer"]))
           end
 
           document
@@ -60,7 +57,7 @@ module Masks
       end
 
       def endpoint(name)
-        discovery.fetch(name) { raise Rejected.new("invalid_issuer", "#{url} publishes no #{name}") }
+        discovery.fetch(name) { raise Refused.new(*Masks::Client.failure("publishes_nothing", url, name)) }
       end
 
       def backchannel_logout?
@@ -75,7 +72,7 @@ module Masks
         wanted = (style || Claims::Avatars::FALLBACK).to_s
 
         unless avatar_styles.include?(wanted)
-          raise Rejected.new("invalid_style", "#{url} does not serve #{wanted} avatars")
+          raise Refused.new(*Masks::Client.failure("no_avatars", url, wanted))
         end
 
         query = size ? "?size=#{size.to_i}" : ""

data/lib/masks/client/logout.rb

@@ -3,13 +3,14 @@ module Masks
     class Logout
       EVENT = "http://schemas.openid.net/event/backchannel-logout".freeze
       ALGORITHMS = Verifier::ALGORITHMS
+      REQUIRED = %w[iss aud iat exp jti].freeze
       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 exp jti events], typ: Verifier::LOGOUT_TOKEN)
+            .verify(token, required: REQUIRED, typ: Verifier::LOGOUT_TOKEN)
 
           new(held).validate!
         end
@@ -42,23 +43,16 @@ module Masks
       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
+        raise InvalidToken.of("logout_with_nonce") if claims.key?("nonce")
+        raise InvalidToken.of("logout_names_nobody") if subject.to_s.empty? && sid.to_s.empty?
+        raise InvalidToken.of("issued_in_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)
+        raise InvalidToken.of("not_a_logout") unless held.is_a?(Hash) && held[EVENT].is_a?(Hash)
 
         self
       end
-
-      private
-
-        def refuse!(said)
-          raise InvalidToken, said
-        end
     end
   end
 end

data/lib/masks/client/proof.rb

@@ -1,7 +1,9 @@
 module Masks
   module Client
     class Proof
-      class Invalid < Error; end
+      def self.invalid(description)
+        InvalidToken.new(description, code: "invalid_dpop_proof")
+      end
 
       SCHEME = "DPoP".freeze
       TYPE = "dpop+jwt".freeze
@@ -46,10 +48,10 @@ module Masks
       end
 
       def self.thumbprint(jwk)
-        named = THUMBED[jwk["kty"]] || raise(Invalid, "the proof key is of a kind this resource does not read")
+        named = THUMBED[jwk["kty"]] || raise(Proof.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? }
+        raise Proof.invalid("the proof key is missing part of itself") if held.any? { |_, value| value.to_s.empty? }
 
         digest(JSON.generate(held))
       end
@@ -61,7 +63,7 @@ module Masks
       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
+        raise Proof.invalid(Masks::Client.saying("one_proof")) unless held.size == 1
 
         @proof = held.first
         @method = method.to_s.upcase
@@ -74,11 +76,11 @@ module Masks
         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)
+        raise Proof.invalid(Masks::Client.saying("proof_other_key")) 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))
+        raise Proof.invalid(Masks::Client.saying("proof_other_token")) unless same?(claims["ath"].to_s, self.class.digest(access_token))
 
         once!(claims, thumbprint)
 
@@ -90,64 +92,63 @@ module Masks
         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)
+          raise Proof.invalid(Masks::Client.saying("proof_type", TYPE)) unless header["typ"].to_s.casecmp?(TYPE)
+          raise Proof.invalid(Masks::Client.saying("proof_algorithm", header["alg"] || "that")) 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) }
+          raise Proof.invalid(Masks::Client.saying("proof_no_key")) unless jwk.is_a?(Hash)
+          raise Proof.invalid(Masks::Client.saying("proof_key_private")) 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"
+          raise Proof.invalid(Masks::Client.saying("proof_not_a_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"
+          raise Proof.invalid(Masks::Client.saying("proof_unsigned"))
         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)
+          raise Proof.invalid(Masks::Client.saying("proof_other_method")) unless claims["htm"].to_s.upcase == @method
+          raise Proof.invalid(Masks::Client.saying("proof_other_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?
+          raise Proof.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"
+          raise Proof.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
+          raise Proof.invalid("a proof must say when it was made") unless made.is_a?(Numeric)
+          raise Proof.invalid(Masks::Client.saying("proof_not_now")) if made < Time.now.to_i - WINDOW - LEEWAY || 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?
+          raise Proof.invalid(Masks::Client.saying("proof_no_jti")) if jti.empty?
           return if @replay.nil? || first?("#{thumbprint}:#{jti}")
 
-          raise Invalid, "that proof has already been used"
+          raise Proof.invalid(Masks::Client.saying("proof_replayed"))
         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})"
+          raise Unavailable.of("replay_store_unreachable")
         end
 
         def same?(held, expected)

data/lib/masks/client/rack.rb

@@ -21,11 +21,11 @@ module Masks
         )
 
         @app.call(env)
-      rescue Challenge => e
-        return passthrough(env, e) if @optional && e.is_a?(Unauthenticated)
+      rescue InvalidToken, Forbidden => e
+        return passthrough(env, e) if @optional && e.is_a?(InvalidToken) && e.missing?
 
         refuse(resource(env), e)
-      rescue ReplayUnavailable
+      rescue Unavailable
         unavailable
       end
 

data/lib/masks/client/registration.rb

@@ -121,7 +121,7 @@ module Masks
           yield
         rescue Unregistered
           raise
-        rescue Rejected => e
+        rescue Refused => e
           raise unless statuses.include?(e.status)
 
           raise Unregistered.new(Unregistered::CODE, e.description, status: e.status)

data/lib/masks/client/resource.rb

@@ -3,7 +3,7 @@ module Masks
     class Resource
       PRESENTED = /\A(Bearer|DPoP)[ \t]+([^\s,]+)[ \t]*\z/i.freeze
       METADATA_PATH = "/.well-known/oauth-protected-resource".freeze
-      REQUIRED = %w[iss sub exp].freeze
+      REQUIRED = %w[iss sub exp jti].freeze
 
       attr_reader :issuer, :url, :scopes
 
@@ -29,8 +29,6 @@ module Masks
         claims.member!(*Array(role), organization: organization) if role || organization
 
         claims
-      rescue InvalidToken => e
-        raise Unauthorized.new(e.message)
       end
 
       def token(authorization)
@@ -53,16 +51,19 @@ module Masks
       end
 
       def challenge(error = nil)
-        error = Unauthorized.new(error.to_s) unless error.is_a?(Challenge)
+        error = InvalidToken.new(error.to_s) unless error.is_a?(Error)
+        missing = error.respond_to?(:missing?) && error.missing?
+        dpop = error.respond_to?(:dpop?) && error.dpop?
+        scope = error.respond_to?(:scope) ? error.scope : nil
 
         parameters = [
-          [ "error", error.code ],
-          [ "error_description", (error.description if error.code) ],
-          [ "scope", error.scope || (scopes.join(" ") if scopes.any?) ],
+          [ "error", (error.code unless missing) ],
+          [ "error_description", (error.description unless missing) ],
+          [ "scope", scope || (scopes.join(" ") if scopes.any?) ],
           [ "resource_metadata", metadata_url ]
         ]
 
-        scheme = error.dpop? ? "#{Proof::SCHEME} algs=\"#{Proof::ALGORITHMS.join(' ')}\", " : "Bearer "
+        scheme = dpop ? "#{Proof::SCHEME} algs=\"#{Proof::ALGORITHMS.join(' ')}\", " : "Bearer "
 
         scheme + parameters.filter_map { |name, value|
           %(#{name}="#{quote(value)}") if value && !value.to_s.empty?
@@ -80,7 +81,7 @@ module Masks
         end
 
         def presented!(authorization)
-          match = authorization.to_s.match(PRESENTED) || raise(Unauthenticated.new)
+          match = authorization.to_s.match(PRESENTED) || raise(InvalidToken.of("no_token"))
 
           [ match[1].casecmp?(Proof::SCHEME) ? :dpop : :bearer, match[2] ]
         end
@@ -88,13 +89,11 @@ module Masks
         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
+          raise InvalidToken.of("unbound_as_dpop") if jkt.nil? && scheme == :dpop
+          raise InvalidToken.new(Masks::Client.saying("bound_as_bearer"), 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

@@ -152,13 +152,13 @@ module Masks
         interval = device.interval.positive? ? device.interval : pause
 
         loop do
-          raise Rejected.new("expired_token", "the code expired before anyone approved it") if device.expired?
+          raise Refused.new(*Masks::Client.failure("code_expired")) if device.expired?
 
           sleep(interval)
 
           begin
             return token(form)
-          rescue Rejected => e
+          rescue Refused => e
             case e.code
             when "authorization_pending" then next
             when "slow_down" then interval += pause
@@ -217,13 +217,19 @@ module Masks
       end
 
       # The person the +tokens+ belong to: the ID token's claims merged over
-      # userinfo. With +max_age+, the seconds the app asked for when it started
-      # the sign-in, an ID token whose +auth_time+ is missing or older than
-      # that, plus 30 seconds of leeway, raises InvalidToken.
-      def identity(tokens, max_age: nil)
+      # userinfo. With +nonce+, the one the sign-in started with, an ID token
+      # carrying another raises InvalidToken. With +max_age+, the seconds the
+      # app asked for when it started the sign-in, an ID token whose
+      # +auth_time+ is missing or older than that, plus 30 seconds of leeway,
+      # raises InvalidToken. An +at_hash+ that is not the access token's does
+      # too.
+      def identity(tokens, nonce: nil, max_age: nil)
         return nil if tokens.id_token.nil?
 
-        claims = Verifier.recent!(Verifier.new(issuer, audience: client_id).verify(tokens.id_token), max_age)
+        claims = IdToken.verify(
+          tokens.id_token, issuer: issuer, client_id: client_id,
+          nonce: nonce, access_token: tokens.access_token, max_age: max_age
+        )
 
         profile(tokens).merge(claims)
       end
@@ -240,7 +246,7 @@ module Masks
 
         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")
+            raise Refused.new(*Masks::Client.failure("no_refresh_token"))
           end
 
           renewed = refresh(held.refresh_token, scope: scope, resource: resource)
@@ -254,7 +260,7 @@ module Masks
           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")
+            raise Refused.new(*Masks::Client.failure("not_held_to_key"))
           end
 
           tokens
@@ -273,7 +279,7 @@ module Masks
 
           begin
             HTTP.parse(response)
-          rescue Rejected => e
+          rescue Refused => e
             raise unless e.code == NO_NONCE && wanted && wanted != nonce
 
             response = HTTP.deliver(proven_request(url, form, wanted))

data/lib/masks/client/tokens.rb

@@ -12,7 +12,7 @@ module Masks
         token = new(body)
 
         if token.access_token.to_s.empty?
-          raise Rejected.new(
+          raise Refused.new(
             body["error"] || "invalid_token_response",
             body["error_description"] || "the token endpoint answered without an access_token"
           )

data/lib/masks/client/transport.rb

@@ -82,7 +82,7 @@ module Masks
           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?
+            raise Refused.new("invalid_request", "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)

data/lib/masks/client/verifier.rb

@@ -5,6 +5,7 @@ module Masks
       ACCESS_TOKEN = "at+jwt".freeze
       LOGOUT_TOKEN = "logout+jwt".freeze
       ID_TOKEN = [ "jwt", nil ].freeze
+      LEEWAY = 30
       AUTH_TIME_LEEWAY = 30
 
       def self.recent!(claims, max_age)
@@ -13,11 +14,25 @@ module Masks
         signed_in_at = claims["auth_time"]
         allowed = signed_in_at.is_a?(Numeric) && signed_in_at + max_age.to_i + AUTH_TIME_LEEWAY >= Time.now.to_i
 
-        raise InvalidToken, "the person signed in longer ago than max_age allows" unless allowed
+        raise InvalidToken.of("too_old") unless allowed
 
         claims
       end
 
+      def self.header(token)
+        segments = token.to_s.split(".", -1)
+
+        raise InvalidToken.of("not_a_jwt") unless segments.size == 3
+
+        held = JSON.parse(Base64.urlsafe_decode64(segments.first))
+
+        raise InvalidToken.of("not_a_jwt") unless held.is_a?(Hash)
+
+        held
+      rescue ArgumentError, JSON::ParserError
+        raise InvalidToken.of("not_a_jwt")
+      end
+
       attr_reader :issuer, :audience
 
       def initialize(issuer, audience:, algorithms: ALGORITHMS)
@@ -27,29 +42,40 @@ module Masks
       end
 
       def verify(token, required: %w[iss sub exp], typ: ID_TOKEN)
-        claims, header = JWT.decode(
-          token, nil, true,
-          algorithms: @algorithms,
-          jwks: keys,
+        header = self.class.header(token)
+        algorithm = header["alg"].to_s
+
+        raise InvalidToken.of("not_an_algorithm", algorithm) unless @algorithms.include?(algorithm)
+
+        typed!(header["typ"], Array(typ))
+
+        claims, = JWT.decode(
+          token, key_for(header["kid"]), true,
+          algorithms: [ algorithm ],
           iss: issuer.url, verify_iss: true,
           aud: audience, verify_aud: true,
-          verify_expiration: true,
-          required_claims: required
+          verify_expiration: true, exp_leeway: LEEWAY,
+          verify_not_before: true, nbf_leeway: LEEWAY,
+          verify_iat: false
         )
 
-        typed!(header["typ"], Array(typ))
+        Array(required).each { |name| raise InvalidToken.of("missing_claims", name) unless claims.key?(name) }
+
+        issued = claims["iat"]
+
+        raise InvalidToken.of("issued_in_future") if issued.is_a?(Numeric) && issued > Time.now.to_i + LEEWAY
 
         claims
       rescue JWT::ExpiredSignature
-        raise InvalidToken, "that token has expired"
+        raise InvalidToken.of("expired")
+      rescue JWT::ImmatureSignature
+        raise InvalidToken.of("not_valid_yet")
       rescue JWT::InvalidIssuerError
-        raise InvalidToken, "that token was issued by another server"
+        raise InvalidToken.of("other_issuer")
       rescue JWT::InvalidAudError
-        raise InvalidToken, "that token was issued for another app"
-      rescue JWT::MissingRequiredClaim
-        raise InvalidToken, "that token is missing a claim it needs"
+        raise InvalidToken.of("other_audience")
       rescue JWT::DecodeError
-        raise InvalidToken, "that token was not signed by #{issuer.url}"
+        raise InvalidToken.of("not_signed_by", issuer.url)
       end
 
       private
@@ -59,11 +85,21 @@ module Masks
 
           return if accepted.include?(named)
 
-          raise InvalidToken, "that token is typed #{held.inspect}, not #{accepted.compact.join(' or ')}"
+          raise InvalidToken.of("wrong_type", held.to_s.empty? ? "nothing" : held, accepted.compact.join(" or "))
         end
 
-        def keys
-          ->(options) { options[:invalidate] ? issuer.keys! : issuer.jwks }
+        def key_for(kid)
+          found = published(issuer.jwks, kid) || published(issuer.keys!, kid)
+
+          raise InvalidToken.of("no_key", issuer.url, kid.to_s) if found.nil?
+
+          JWT::JWK.import(found).verify_key
+        end
+
+        def published(jwks, kid)
+          keys = jwks.is_a?(Hash) ? Array(jwks["keys"]) : []
+
+          keys.find { |key| key.is_a?(Hash) && key["kid"] == kid && key.fetch("use", "sig") == "sig" }
         end
     end
   end

data/lib/masks/client.rb

@@ -1,4 +1,5 @@
 require "base64"
+require "digest"
 require "ipaddr"
 require "json"
 require "jwt"
@@ -8,6 +9,7 @@ require "securerandom"
 require "uri"
 
 require_relative "version"
+require_relative "client/failures"
 require_relative "client/errors"
 require_relative "client/http"
 require_relative "client/embedded"
@@ -26,6 +28,7 @@ require_relative "client/device"
 require_relative "client/transport"
 require_relative "client/session"
 require_relative "client/verifier"
+require_relative "client/id_token"
 require_relative "client/proof"
 require_relative "client/logout"
 require_relative "client/resource"

data/lib/masks/rails/authentication.rb

@@ -11,7 +11,7 @@ module Masks
         end
 
         if respond_to?(:rescue_from) && method_defined?(:render)
-          rescue_from Masks::Rails::Cache::Unavailable, with: :masks_cache_unavailable
+          rescue_from Masks::Client::Unavailable, with: :masks_cache_unavailable
         end
       end
 
@@ -84,10 +84,10 @@ module Masks
         Masks::Client::Claims::ORGANIZATIONS
       ].freeze
 
-      def masks_identity_from(tokens)
+      def masks_identity_from(tokens, nonce: nil, max_age: nil)
         return nil if tokens.id_token.nil?
 
-        masks_session.identity(tokens)
+        masks_session.identity(tokens, nonce: nonce, max_age: max_age)
       end
 
       def masks_forget
@@ -163,7 +163,7 @@ module Masks
 
         renewal = begin
           masks_cache.renew(masks_config.issuer_for(request).to_s, spent) { masks_renewal(spent) }
-        rescue Masks::Rails::Cache::Unavailable
+        rescue Masks::Client::Unavailable
           Masks::Rails::Renewal.unreachable
         end
 
@@ -240,7 +240,7 @@ module Masks
           Masks::Rails::Renewal.renewed(refreshed, masks_refreshed_identity(refreshed))
         rescue Masks::Client::Unregistered
           Masks::Rails::Renewal.unregistered
-        rescue Masks::Client::Rejected => e
+        rescue Masks::Client::Refused => e
           e.status.to_i >= 500 || e.status.to_i == 429 ? Masks::Rails::Renewal.unreachable : Masks::Rails::Renewal.refused
         rescue Masks::Client::Error
           Masks::Rails::Renewal.unreachable
@@ -274,7 +274,7 @@ module Masks
 
           if masks_asked_already?(session.delete(STEPPED_UP), missing)
             raise Masks::Client::Forbidden.new(
-              "insufficient_scope", "this account does not hold the #{missing.join(' and ')} privilege",
+              *Masks::Client.failure("no_privilege", missing.join(" and ")),
               scope: missing.flat_map { |name| masks_config.privilege(name).scopes }.join(" ")
             )
           end
@@ -329,7 +329,7 @@ module Masks
           response.headers["Retry-After"] = "5"
 
           if masks_wants_json?
-            render json: { "error" => "temporarily_unavailable", "error_description" => error.message },
+            render json: { "error" => "temporarily_unavailable", "error_description" => error.description },
                    status: :service_unavailable
           else
             render plain: "Signing in is unavailable right now. Try again in a moment.", status: :service_unavailable

data/lib/masks/rails/cache.rb

@@ -1,8 +1,6 @@
 module Masks
   module Rails
     class Cache
-      class Unavailable < Masks::Client::Error; end
-
       CLAIM = 30
       RESULT = 60
       WAIT = 0.05
@@ -41,7 +39,7 @@ module Masks
 
         kept = begin
           write(self.class.key("departed", issuer, kind, value), self.class.now, expires_in: DEPARTURE)
-        rescue Unavailable
+        rescue Masks::Client::Unavailable
           false
         end
 
@@ -49,7 +47,7 @@ module Masks
 
         forgotten { delete(self.class.key("logout", issuer, logout.jti)) }
 
-        raise Unavailable, "the cache did not keep that logout"
+        raise Masks::Client::Unavailable, "the cache did not keep that logout"
       end
 
       def departed?(issuer, identity, since:)
@@ -87,7 +85,7 @@ module Masks
           return true if write(key, 1, unless_exist: true, expires_in: expires_in)
           return false unless read(key).nil?
 
-          raise Unavailable, "the cache neither kept that key nor holds it, so it is not answering"
+          raise Masks::Client::Unavailable, "the cache neither kept that key nor holds it, so it is not answering"
         end
 
         def read(key)
@@ -104,15 +102,15 @@ module Masks
 
         def reached
           yield
-        rescue Unavailable
+        rescue Masks::Client::Unavailable
           raise
         rescue StandardError => e
-          raise Unavailable, "the cache could not be reached (#{e.class})"
+          raise Masks::Client::Unavailable, Masks::Client.saying("store_unreachable")
         end
 
         def forgotten
           yield
-        rescue Unavailable
+        rescue Masks::Client::Unavailable
           nil
         end
 

data/lib/masks/rails/configuration.rb

@@ -1,7 +1,11 @@
 module Masks
   module Rails
     class Configuration
-      class Unconfigured < Masks::Client::Error; end
+      class Unconfigured < Masks::Client::Error
+        def initialize(description)
+          super("not_configured", description)
+        end
+      end
 
       Privilege = Struct.new(:name, :scopes, :roles, :organization, keyword_init: true)
       PRIVILEGE_KEYS = %w[scope role organization].freeze